taladb 0.1.2 → 0.2.0

package/dist/index.d.mts

@@ -1,3 +1,21 @@
+/** Similarity metric used for vector search. */
+type VectorMetric = 'cosine' | 'dot' | 'euclidean';
+interface VectorIndexOptions {
+    /** Number of dimensions in each stored vector. Enforced on insert and search. */
+    dimensions: number;
+    /** Similarity metric. Defaults to `"cosine"`. */
+    metric?: VectorMetric;
+}
+/** A single result returned by `Collection.findNearest`. */
+interface VectorSearchResult<T extends Document = Document> {
+    /** The matched document. */
+    document: T;
+    /**
+     * Similarity score — higher means more similar.
+     * Range depends on metric: cosine ∈ [-1,1], dot ∈ ℝ, euclidean ∈ (0,1].
+     */
+    score: number;
+}
 type Value = null | boolean | number | string | Uint8Array | Value[] | {
     [key: string]: Value;
 };
@@ -54,6 +72,36 @@ interface Collection<T extends Document = Document> {
     count(filter?: Filter<T>): Promise<number>;
     createIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
     dropIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
+    /**
+     * Create a vector index on a numeric-array field.
+     *
+     * After creation, `findNearest` can search this field and new inserts/updates
+     * automatically maintain the index. Existing documents are backfilled.
+     *
+     * @example
+     * await articles.createVectorIndex('embedding', { dimensions: 384 });
+     */
+    createVectorIndex(field: keyof Omit<T, '_id'> & string, options: VectorIndexOptions): Promise<void>;
+    /** Drop a vector index. */
+    dropVectorIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
+    /**
+     * Find the `topK` most similar documents to `vector` using a vector index.
+     *
+     * Optionally combine with a metadata `filter` to restrict the search space
+     * before ranking — e.g. find the 5 most similar english-language articles.
+     *
+     * Results are ordered by descending similarity score (highest first).
+     *
+     * @example
+     * const results = await articles.findNearest('embedding', queryVec, 5);
+     * // results: Array<{ document: Article, score: number }>
+     *
+     * @example with pre-filter
+     * const results = await articles.findNearest('embedding', queryVec, 5, {
+     *   locale: 'en',
+     * });
+     */
+    findNearest(field: keyof Omit<T, '_id'> & string, vector: number[], topK: number, filter?: Filter<T>): Promise<VectorSearchResult<T>[]>;
     /**
      * Subscribe to live query results. The callback receives a full snapshot of
      * matching documents immediately and again after every write that could
@@ -88,4 +136,4 @@ interface TalaDB {
  */
 declare function openDB(dbName?: string): Promise<TalaDB>;
 
-export { type Collection, type Document, type Filter, type TalaDB, type Update, type Value, openDB };
+export { type Collection, type Document, type Filter, type TalaDB, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, openDB };

package/dist/index.d.ts

@@ -1,3 +1,21 @@
+/** Similarity metric used for vector search. */
+type VectorMetric = 'cosine' | 'dot' | 'euclidean';
+interface VectorIndexOptions {
+    /** Number of dimensions in each stored vector. Enforced on insert and search. */
+    dimensions: number;
+    /** Similarity metric. Defaults to `"cosine"`. */
+    metric?: VectorMetric;
+}
+/** A single result returned by `Collection.findNearest`. */
+interface VectorSearchResult<T extends Document = Document> {
+    /** The matched document. */
+    document: T;
+    /**
+     * Similarity score — higher means more similar.
+     * Range depends on metric: cosine ∈ [-1,1], dot ∈ ℝ, euclidean ∈ (0,1].
+     */
+    score: number;
+}
 type Value = null | boolean | number | string | Uint8Array | Value[] | {
     [key: string]: Value;
 };
@@ -54,6 +72,36 @@ interface Collection<T extends Document = Document> {
     count(filter?: Filter<T>): Promise<number>;
     createIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
     dropIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
+    /**
+     * Create a vector index on a numeric-array field.
+     *
+     * After creation, `findNearest` can search this field and new inserts/updates
+     * automatically maintain the index. Existing documents are backfilled.
+     *
+     * @example
+     * await articles.createVectorIndex('embedding', { dimensions: 384 });
+     */
+    createVectorIndex(field: keyof Omit<T, '_id'> & string, options: VectorIndexOptions): Promise<void>;
+    /** Drop a vector index. */
+    dropVectorIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
+    /**
+     * Find the `topK` most similar documents to `vector` using a vector index.
+     *
+     * Optionally combine with a metadata `filter` to restrict the search space
+     * before ranking — e.g. find the 5 most similar english-language articles.
+     *
+     * Results are ordered by descending similarity score (highest first).
+     *
+     * @example
+     * const results = await articles.findNearest('embedding', queryVec, 5);
+     * // results: Array<{ document: Article, score: number }>
+     *
+     * @example with pre-filter
+     * const results = await articles.findNearest('embedding', queryVec, 5, {
+     *   locale: 'en',
+     * });
+     */
+    findNearest(field: keyof Omit<T, '_id'> & string, vector: number[], topK: number, filter?: Filter<T>): Promise<VectorSearchResult<T>[]>;
     /**
      * Subscribe to live query results. The callback receives a full snapshot of
      * matching documents immediately and again after every write that could
@@ -88,4 +136,4 @@ interface TalaDB {
  */
 declare function openDB(dbName?: string): Promise<TalaDB>;
 
-export { type Collection, type Document, type Filter, type TalaDB, type Update, type Value, openDB };
+export { type Collection, type Document, type Filter, type TalaDB, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, openDB };

package/dist/index.js

@@ -89,6 +89,12 @@ async function createInMemoryBrowserDB(_dbName) {
       count: async (filter) => col.count(filter ?? null),
       createIndex: async (field) => col.createIndex(field),
       dropIndex: async (field) => col.dropIndex(field),
+      createVectorIndex: async (field, options) => col.createVectorIndex(field, options.dimensions, options.metric ?? null),
+      dropVectorIndex: async (field) => col.dropVectorIndex(field),
+      findNearest: async (field, vector, topK, filter) => {
+        const raw = await col.findNearest(field, vector, topK, filter ?? null);
+        return raw;
+      },
       subscribe: (filter, callback) => {
         let active = true;
         let lastJson = "";
@@ -169,6 +175,23 @@ async function createBrowserDB(dbName) {
       }),
       createIndex: (field) => proxy.send("createIndex", { collection: name, field }),
       dropIndex: (field) => proxy.send("dropIndex", { collection: name, field }),
+      createVectorIndex: (field, options) => proxy.send("createVectorIndex", {
+        collection: name,
+        field,
+        dimensions: options.dimensions,
+        metric: options.metric
+      }),
+      dropVectorIndex: (field) => proxy.send("dropVectorIndex", { collection: name, field }),
+      findNearest: async (field, vector, topK, filter) => {
+        const json = await proxy.send("findNearest", {
+          collection: name,
+          field,
+          queryJson: JSON.stringify(vector),
+          topK,
+          filterJson: filter ? JSON.stringify(filter) : "null"
+        });
+        return JSON.parse(json);
+      },
       subscribe: (filter, callback) => {
         let active = true;
         let lastJson = "";
@@ -216,6 +239,12 @@ async function createNodeDB(dbName) {
       count: async (filter) => col.count(filter ?? null),
       createIndex: async (field) => col.createIndex(field),
       dropIndex: async (field) => col.dropIndex(field),
+      createVectorIndex: async (field, options) => col.createVectorIndex(field, options.dimensions, options.metric ?? null),
+      dropVectorIndex: async (field) => col.dropVectorIndex(field),
+      findNearest: async (field, vector, topK, filter) => {
+        const raw = await col.findNearest(field, vector, topK, filter ?? null);
+        return raw;
+      },
       subscribe: (filter, callback) => {
         let active = true;
         let lastJson = "";
@@ -267,6 +296,12 @@ async function createNativeDB(_dbName) {
       count: async (filter) => col.count(filter ?? {}),
       createIndex: async (field) => col.createIndex(field),
       dropIndex: async (field) => col.dropIndex(field),
+      createVectorIndex: async (field, options) => col.createVectorIndex(field, options.dimensions, options.metric ?? null),
+      dropVectorIndex: async (field) => col.dropVectorIndex(field),
+      findNearest: async (field, vector, topK, filter) => {
+        const raw = col.findNearest(field, vector, topK, filter ?? null);
+        return raw;
+      },
       subscribe: (filter, callback) => {
         let active = true;
         let lastJson = "";

package/dist/index.mjs

@@ -54,6 +54,12 @@ async function createInMemoryBrowserDB(_dbName) {
       count: async (filter) => col.count(filter ?? null),
       createIndex: async (field) => col.createIndex(field),
       dropIndex: async (field) => col.dropIndex(field),
+      createVectorIndex: async (field, options) => col.createVectorIndex(field, options.dimensions, options.metric ?? null),
+      dropVectorIndex: async (field) => col.dropVectorIndex(field),
+      findNearest: async (field, vector, topK, filter) => {
+        const raw = await col.findNearest(field, vector, topK, filter ?? null);
+        return raw;
+      },
       subscribe: (filter, callback) => {
         let active = true;
         let lastJson = "";
@@ -134,6 +140,23 @@ async function createBrowserDB(dbName) {
       }),
       createIndex: (field) => proxy.send("createIndex", { collection: name, field }),
       dropIndex: (field) => proxy.send("dropIndex", { collection: name, field }),
+      createVectorIndex: (field, options) => proxy.send("createVectorIndex", {
+        collection: name,
+        field,
+        dimensions: options.dimensions,
+        metric: options.metric
+      }),
+      dropVectorIndex: (field) => proxy.send("dropVectorIndex", { collection: name, field }),
+      findNearest: async (field, vector, topK, filter) => {
+        const json = await proxy.send("findNearest", {
+          collection: name,
+          field,
+          queryJson: JSON.stringify(vector),
+          topK,
+          filterJson: filter ? JSON.stringify(filter) : "null"
+        });
+        return JSON.parse(json);
+      },
       subscribe: (filter, callback) => {
         let active = true;
         let lastJson = "";
@@ -181,6 +204,12 @@ async function createNodeDB(dbName) {
       count: async (filter) => col.count(filter ?? null),
       createIndex: async (field) => col.createIndex(field),
       dropIndex: async (field) => col.dropIndex(field),
+      createVectorIndex: async (field, options) => col.createVectorIndex(field, options.dimensions, options.metric ?? null),
+      dropVectorIndex: async (field) => col.dropVectorIndex(field),
+      findNearest: async (field, vector, topK, filter) => {
+        const raw = await col.findNearest(field, vector, topK, filter ?? null);
+        return raw;
+      },
       subscribe: (filter, callback) => {
         let active = true;
         let lastJson = "";
@@ -232,6 +261,12 @@ async function createNativeDB(_dbName) {
       count: async (filter) => col.count(filter ?? {}),
       createIndex: async (field) => col.createIndex(field),
       dropIndex: async (field) => col.dropIndex(field),
+      createVectorIndex: async (field, options) => col.createVectorIndex(field, options.dimensions, options.metric ?? null),
+      dropVectorIndex: async (field) => col.dropVectorIndex(field),
+      findNearest: async (field, vector, topK, filter) => {
+        const raw = col.findNearest(field, vector, topK, filter ?? null);
+        return raw;
+      },
       subscribe: (filter, callback) => {
         let active = true;
         let lastJson = "";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "taladb",
-  "version": "0.1.2",
-  "description": "Local-first document database for React, React Native, and Node.js",
+  "version": "0.2.0",
+  "description": "Local-first document and vector database for React, React Native, and Node.js",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -21,7 +21,13 @@
     "local-first",
     "offline",
     "wasm",
-    "react-native"
+    "react-native",
+    "vector",
+    "vector-search",
+    "embeddings",
+    "semantic-search",
+    "ai",
+    "hybrid-search"
   ],
   "license": "MIT",
   "repository": {
@@ -42,8 +48,8 @@
     "vitest": "^3.2.0"
   },
   "optionalDependencies": {
-    "@taladb/web": "0.1.2",
-    "@taladb/node": "0.1.2"
+    "@taladb/web": "0.2.0",
+    "@taladb/node": "0.2.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --out-dir dist --external @taladb/web --external @taladb/node --external @taladb/react-native",