taladb 0.11.3 → 0.11.4

package/dist/index.browser.mjs

@@ -1,3 +1,89 @@
+// src/vector-client.ts
+function integer(value, name, min = 0, max = 4294967295) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${name} must be an integer between ${min} and ${max}`);
+}
+function vectorValues(vector) {
+  const values = Array.from(vector);
+  if (values.length === 0 || values.some((v) => !Number.isFinite(v))) throw new Error("vector must contain finite numbers");
+  return values;
+}
+function queryOptions(options) {
+  if (options.efSearch !== void 0) integer(options.efSearch, "efSearch", 1);
+  if (options.offset !== void 0) integer(options.offset, "offset");
+  if (options.groupSize !== void 0) integer(options.groupSize, "groupSize", 1);
+  if (options.oversampling !== void 0) integer(options.oversampling, "oversampling", 1, 100);
+  if (options.scoreThreshold !== void 0 && !Number.isFinite(options.scoreThreshold)) throw new Error("scoreThreshold must be finite");
+  return options;
+}
+function abortError() {
+  const error = new Error("Vector index rebuild cancelled");
+  error.name = "AbortError";
+  return error;
+}
+function createVectorClient(send) {
+  const client = {
+    searchVectors: async (field, vector, topK, filter, options = {}) => {
+      integer(topK, "topK");
+      return send({ op: "search", field, query: vectorValues(vector), topK, filter, options: queryOptions(options) });
+    },
+    findWithin: (field, vector, scoreThreshold, filter) => client.searchVectors(field, vector, 4294967295, filter, { mode: "exact", scoreThreshold }),
+    vectorIndexStatus: (field) => send({ op: "status", field }),
+    beginVectorBuild: (field, options) => send({ op: "beginBuild", field, options }),
+    stepVectorBuild: async (field, id, batchSize = 32) => {
+      integer(batchSize, "batchSize", 1, 1024);
+      return send({ op: "stepBuild", field, id, batchSize });
+    },
+    cancelVectorBuild: (field, id) => send({ op: "cancelBuild", field, id }),
+    rebuildVectorIndex: async (field, options = {}) => {
+      const { signal, onProgress, batchSize = 32, ...graphOptions } = options;
+      integer(batchSize, "batchSize", 1, 1024);
+      if (signal?.aborted) throw abortError();
+      let progress = await client.beginVectorBuild(field, Object.keys(graphOptions).length ? graphOptions : void 0);
+      try {
+        onProgress?.(progress);
+        while (progress.state === "building") {
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          if (signal?.aborted) throw abortError();
+          progress = await client.stepVectorBuild(field, progress.id, batchSize);
+          onProgress?.(progress);
+        }
+        if (progress.state === "failed") throw new Error(progress.error ?? "Vector rebuild failed");
+        if (progress.state === "cancelled") throw abortError();
+        return progress;
+      } catch (error) {
+        if (progress.state === "building") await client.cancelVectorBuild(field, progress.id);
+        throw error;
+      }
+    },
+    measureVectorRecall: async (field, queries, topK, filter, options = {}) => {
+      integer(topK, "topK", 1);
+      return send({ op: "recall", field, queries: queries.map(vectorValues), topK, filter, options: queryOptions(options) });
+    }
+  };
+  return client;
+}
+function vectorIndexRequest(field, options) {
+  integer(options.dimensions, "dimensions", 1);
+  if (options.metric && !["cosine", "dot", "euclidean"].includes(options.metric)) throw new Error("invalid vector metric");
+  if (options.indexType && !["flat", "hnsw"].includes(options.indexType)) throw new Error("invalid vector indexType");
+  if (options.quantization && options.quantization !== "none" && options.indexType !== "hnsw") throw new Error("quantization requires an HNSW index");
+  if (options.indexType === "hnsw") {
+    const m = options.hnswM ?? 32;
+    const efConstruction = options.hnswEfConstruction ?? 200;
+    integer(m, "hnswM", 2, 128);
+    integer(efConstruction, "hnswEfConstruction", m, 1e5);
+    if (options.metric === "dot") throw new Error("HNSW requires cosine or euclidean");
+    if (options.quantization === "binary" && options.metric && options.metric !== "cosine") throw new Error("binary quantization requires cosine");
+  }
+  return {
+    op: "create",
+    field,
+    dimensions: options.dimensions,
+    metric: options.metric,
+    options: options.indexType === "hnsw" ? { m: options.hnswM ?? 32, efConstruction: options.hnswEfConstruction ?? 200, quantization: options.quantization ?? "none" } : null
+  };
+}
+
 // src/config.browser.ts
 var ENDPOINT_FIELDS = [
   "endpoint",
@@ -710,7 +796,9 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
   }
   function wrapCollection(name, opts) {
     const s = JSON.stringify;
+    const vectorCommand = async (request) => JSON.parse(await proxy.send("vectorCommand", { collection: name, requestJson: JSON.stringify(request) }));
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: (doc) => proxy.send("insert", { collection: name, docJson: s(doc) }),
       insertMany: async (docs) => {
         const json = await proxy.send("insertMany", {
@@ -762,25 +850,21 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
       dropCompoundIndex: (fields) => proxy.send("dropCompoundIndex", { collection: name, fieldsJson: JSON.stringify(fields) }),
       createFtsIndex: (field) => proxy.send("createFtsIndex", { collection: name, field }),
       dropFtsIndex: (field) => proxy.send("dropFtsIndex", { collection: name, field }),
-      createVectorIndex: (field, options) => {
-        if (options.indexType === "hnsw") return Promise.reject(new Error("HNSW vector indexes are not available in the browser (requires native threads). Use Node.js or React Native."));
-        return proxy.send("createVectorIndex", {
-          collection: name,
-          field,
-          dimensions: options.dimensions,
-          metric: options.metric,
-          indexType: null,
-          hnswM: null,
-          hnswEfConstruction: null
-        });
+      createVectorIndex: async (field, options) => {
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
       },
       dropVectorIndex: (field) => proxy.send("dropVectorIndex", { collection: name, field }),
-      upgradeVectorIndex: (_field) => Promise.reject(new Error("HNSW vector indexes are not available in the browser (requires native threads). Use Node.js or React Native.")),
+      upgradeVectorIndex: async (field) => {
+        await createVectorClient(vectorCommand).rebuildVectorIndex(field);
+      },
       listIndexes: async () => {
         const json = await proxy.send("listIndexes", { collection: name });
         return JSON.parse(json);
       },
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const json = await proxy.send("findNearest", {
           collection: name,
           field,
@@ -941,7 +1025,9 @@ async function createNodeDB(dbName, webhook, config, passphrase, migrations) {
   const db = TalaDBNode.open(dbName, configJson, passphrase ?? null);
   function wrapCollection(name, opts) {
     const col = db.collection(name);
+    const vectorCommand = async (request) => col.vectorCommandAsync ? col.vectorCommandAsync(request) : col.vectorCommand(request);
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: async (doc) => col.insertAsync ? col.insertAsync(doc) : col.insert(doc),
       insertMany: async (docs) => col.insertManyAsync ? col.insertManyAsync(docs) : col.insertMany(docs),
       find: async (filter) => col.findAsync ? col.findAsync(filter ?? null) : col.find(filter ?? null),
@@ -958,14 +1044,19 @@ async function createNodeDB(dbName, webhook, config, passphrase, migrations) {
       dropCompoundIndex: async (fields) => col.dropCompoundIndex(fields),
       createFtsIndex: async (field) => col.createFtsIndex(field),
       dropFtsIndex: async (field) => col.dropFtsIndex(field),
-      createVectorIndex: async (field, options) => col.createVectorIndex(field, options.dimensions, options.metric ?? null, options.indexType ?? null, options.hnswM ?? null, options.hnswEfConstruction ?? null),
+      createVectorIndex: async (field, options) => {
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
+      },
       dropVectorIndex: async (field) => col.dropVectorIndex(field),
       upgradeVectorIndex: async (field) => col.upgradeVectorIndex(field),
       listIndexes: async () => {
         const json = col.listIndexes();
         return JSON.parse(json);
       },
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const raw = await col.findNearest(field, vector, topK, filter ?? null);
         return raw;
       },
@@ -1044,7 +1135,9 @@ async function createNativeDB(_dbName, webhook, migrations) {
     return result;
   };
   function wrapCollection(name, opts) {
+    const vectorCommand = async (request) => call("vectorCommand", name, request);
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: async (doc) => await call("insert", name, doc),
       insertMany: async (docs) => await call("insertMany", name, docs),
       find: async (filter) => await call("find", name, filter ?? {}),
@@ -1062,17 +1155,15 @@ async function createNativeDB(_dbName, webhook, migrations) {
       createFtsIndex: async (field) => await call("createFtsIndex", name, field),
       dropFtsIndex: async (field) => await call("dropFtsIndex", name, field),
       createVectorIndex: async (field, options) => {
-        const opts2 = {};
-        if (options.metric) opts2.metric = options.metric;
-        if (options.indexType === "hnsw") {
-          opts2.hnsw = { m: options.hnswM ?? 32, ef_construction: options.hnswEfConstruction ?? 200 };
-        }
-        return await call("createVectorIndex", name, field, options.dimensions, opts2);
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
       },
       dropVectorIndex: async (field) => await call("dropVectorIndex", name, field),
       upgradeVectorIndex: async (field) => await call("upgradeVectorIndex", name, field),
       listIndexes: async () => call("listIndexes", name),
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const raw = await call("findNearest", name, field, vector, topK, filter ?? null);
         return raw;
       },
@@ -1100,6 +1191,9 @@ async function createNativeDB(_dbName, webhook, migrations) {
     flush: native.callAsync || native.flush ? async () => {
       await call("flush");
     } : void 0,
+    rebuildVectorIndexes: native.callAsync || native.rebuildVectorIndexes ? async () => {
+      await call("rebuildVectorIndexes");
+    } : void 0,
     // One process owns the file — there is no other tab to defer to.
     isPrimary: async () => true
   };
@@ -1187,6 +1281,7 @@ function attachWebhook(db, webhook) {
 export {
   TalaDbValidationError,
   applySchema,
+  createVectorClient,
   createWebhookDispatcher,
   decorateCollection,
   deriveDocId,

package/dist/index.d.mts

@@ -1,3 +1,81 @@
+/** Shared vector API for Node, browser workers, and the React Native job executor. */
+type VectorQuantization = 'none' | 'scalar' | 'binary';
+interface VectorGraphOptions {
+    m?: number;
+    efConstruction?: number;
+    quantization?: VectorQuantization;
+}
+interface VectorQueryOptions {
+    mode?: 'auto' | 'exact' | 'ann';
+    efSearch?: number;
+    scoreThreshold?: number;
+    offset?: number;
+    groupBy?: string;
+    groupSize?: number;
+    oversampling?: number;
+}
+interface VectorBuildProgress {
+    id: string;
+    state: 'building' | 'ready' | 'cancelled' | 'failed';
+    processed: number;
+    total: number;
+    revision: number;
+    error: string | null;
+}
+interface VectorRebuildOptions extends VectorGraphOptions {
+    /** Insertions per native/worker call (1–1024); defaults to 32 for mobile responsiveness. */
+    batchSize?: number;
+    signal?: AbortSignal;
+    onProgress?: (progress: VectorBuildProgress) => void;
+}
+interface VectorIndexStatus {
+    field: string;
+    state: 'flat' | 'ready' | 'stale' | 'rebuildRequired';
+    persistent: boolean;
+    indexedVectors: number;
+    totalVectors: number;
+    deletedNodes: number;
+    revision: number;
+    indexRevision: number | null;
+    options: Required<VectorGraphOptions> | null;
+    build: VectorBuildProgress | null;
+}
+interface VectorQueryResult<T> {
+    hits: {
+        document: T;
+        score: number;
+    }[];
+    execution: {
+        path: 'exact' | 'hnsw';
+        reason: string;
+        revision: number;
+        efSearch: number | null;
+        distanceComputations: number;
+    };
+    /** Offset pagination uses live snapshots. Writes between pages can change ordering. */
+    nextOffset: number | null;
+}
+interface VectorRecall {
+    recallAtK: number;
+    queries: number;
+    topK: number;
+    exactMs: number;
+    annMs: number;
+}
+interface VectorClient<T> {
+    searchVectors(field: string, vector: ArrayLike<number>, topK: number, filter?: Record<string, unknown>, options?: VectorQueryOptions): Promise<VectorQueryResult<T>>;
+    /** Exact range search. Returns every matching document above the score threshold. */
+    findWithin(field: string, vector: ArrayLike<number>, scoreThreshold: number, filter?: Record<string, unknown>): Promise<VectorQueryResult<T>>;
+    vectorIndexStatus(field: string): Promise<VectorIndexStatus>;
+    rebuildVectorIndex(field: string, options?: VectorRebuildOptions): Promise<VectorBuildProgress>;
+    beginVectorBuild(field: string, options?: VectorGraphOptions): Promise<VectorBuildProgress>;
+    stepVectorBuild(field: string, id: string, batchSize?: number): Promise<VectorBuildProgress>;
+    cancelVectorBuild(field: string, id: string): Promise<VectorBuildProgress>;
+    measureVectorRecall(field: string, queries: ArrayLike<number>[], topK: number, filter?: Record<string, unknown>, options?: VectorQueryOptions): Promise<VectorRecall>;
+}
+/** Binding adapter used by TalaDB's Node, browser, and React Native packages. */
+declare function createVectorClient<T>(send: (request: Record<string, unknown>) => Promise<any>): VectorClient<T>;
+
 /** The three mutation kinds a webhook reports, and the verb each one uses. */
 type WebhookOp = 'insert' | 'update' | 'delete';
 interface WebhookConfig {
@@ -105,13 +183,15 @@ interface VectorIndexOptions {
      * Index algorithm. Defaults to `"flat"` (exact brute-force).
      * Use `"hnsw"` for approximate nearest-neighbour search — much faster on
      * large collections at the cost of occasional missed results.
-     * Requires the `vector-hnsw` feature to be compiled in.
+     * Supported on browser, Node.js and React Native.
      */
     indexType?: 'flat' | 'hnsw';
-    /** HNSW connectivity parameter M. This implementation supports only 32 (the default). */
+    /** HNSW connectivity parameter M. Supported range is 2–128; defaults to 32. */
     hnswM?: number;
     /** HNSW build-time quality parameter ef_construction (default 200). */
     hnswEfConstruction?: number;
+    /** Graph compression; originals remain available for exact rescoring. */
+    quantization?: VectorQuantization;
 }
 /** Describes the indexes that exist on a collection. */
 interface CollectionIndexInfo {
@@ -482,7 +562,7 @@ type AggregatePipeline<T extends Document = Document> = AggregateStage<T>[];
 type InsertDoc<T extends Document> = Omit<T, '_id'> & {
     _id?: string;
 };
-interface Collection<T extends Document = Document> {
+interface Collection<T extends Document = Document> extends VectorClient<T> {
     insert(doc: InsertDoc<T>): Promise<string>;
     insertMany(docs: InsertDoc<T>[]): Promise<string[]>;
     find(filter?: Filter<T>): Promise<T[]>;
@@ -600,7 +680,7 @@ interface Collection<T extends Document = Document> {
      *
      * After calling this, `findNearest` uses approximate nearest-neighbour
      * search which is significantly faster on large collections.
-     * Requires the `vector-hnsw` feature to be compiled in; no-op otherwise.
+     * Promotes flat/legacy indexes and compacts persistent graphs.
      */
     upgradeVectorIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
     /**
@@ -620,7 +700,7 @@ interface Collection<T extends Document = Document> {
      *   locale: 'en',
      * });
      */
-    findNearest(field: keyof Omit<T, '_id'> & string, vector: number[], topK: number, filter?: Filter<T>): Promise<VectorSearchResult<T>[]>;
+    findNearest(field: keyof Omit<T, '_id'> & string, vector: number[], topK: number, filter?: Filter<T>, options?: VectorQueryOptions): 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
@@ -680,6 +760,12 @@ interface TalaDB {
      * "save now" moments (before checkout, on `visibilitychange`).
      */
     flush?(): Promise<void>;
+    /**
+     * Rebuild all configured HNSW graphs for maintenance. Graphs persist across
+     * restarts; startup rebuilding is unnecessary. Prefer per-collection
+     * rebuildVectorIndex for bounded batches, progress and cancellation.
+     */
+    rebuildVectorIndexes?(): Promise<void>;
     /**
      * Whether this browser tab owns the database storage. All tabs execute reads
      * and writes through that owner and await its result. Ownership can change
@@ -932,4 +1018,4 @@ interface OpenDBOptions {
  */
 declare function openDB(dbName?: string, options?: OpenDBOptions): Promise<TalaDB>;
 
-export { type AggregatePipeline, type AggregateStage, type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type DurabilityConfig, type Filter, type HybridSearchOptions, type HybridSearchResult, type InsertDoc, type Migration, type OpenDBOptions, type Schema, type TalaDB, type TalaDbConfig, TalaDbValidationError, type TextSearchOptions, type TextSearchResult, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, type WebhookConfig, type WebhookDispatcher, type WebhookEvent, type WebhookOp, type WebhookStats, applySchema, createWebhookDispatcher, decorateCollection, deriveDocId, isDocId, openDB, runMigrations, validateWebhookConfig };
+export { type AggregatePipeline, type AggregateStage, type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type DurabilityConfig, type Filter, type HybridSearchOptions, type HybridSearchResult, type InsertDoc, type Migration, type OpenDBOptions, type Schema, type TalaDB, type TalaDbConfig, TalaDbValidationError, type TextSearchOptions, type TextSearchResult, type Update, type Value, type VectorBuildProgress, type VectorClient, type VectorGraphOptions, type VectorIndexOptions, type VectorIndexStatus, type VectorMetric, type VectorQuantization, type VectorQueryOptions, type VectorQueryResult, type VectorRebuildOptions, type VectorRecall, type VectorSearchResult, type WebhookConfig, type WebhookDispatcher, type WebhookEvent, type WebhookOp, type WebhookStats, applySchema, createVectorClient, createWebhookDispatcher, decorateCollection, deriveDocId, isDocId, openDB, runMigrations, validateWebhookConfig };

package/dist/index.d.ts

@@ -1,3 +1,81 @@
+/** Shared vector API for Node, browser workers, and the React Native job executor. */
+type VectorQuantization = 'none' | 'scalar' | 'binary';
+interface VectorGraphOptions {
+    m?: number;
+    efConstruction?: number;
+    quantization?: VectorQuantization;
+}
+interface VectorQueryOptions {
+    mode?: 'auto' | 'exact' | 'ann';
+    efSearch?: number;
+    scoreThreshold?: number;
+    offset?: number;
+    groupBy?: string;
+    groupSize?: number;
+    oversampling?: number;
+}
+interface VectorBuildProgress {
+    id: string;
+    state: 'building' | 'ready' | 'cancelled' | 'failed';
+    processed: number;
+    total: number;
+    revision: number;
+    error: string | null;
+}
+interface VectorRebuildOptions extends VectorGraphOptions {
+    /** Insertions per native/worker call (1–1024); defaults to 32 for mobile responsiveness. */
+    batchSize?: number;
+    signal?: AbortSignal;
+    onProgress?: (progress: VectorBuildProgress) => void;
+}
+interface VectorIndexStatus {
+    field: string;
+    state: 'flat' | 'ready' | 'stale' | 'rebuildRequired';
+    persistent: boolean;
+    indexedVectors: number;
+    totalVectors: number;
+    deletedNodes: number;
+    revision: number;
+    indexRevision: number | null;
+    options: Required<VectorGraphOptions> | null;
+    build: VectorBuildProgress | null;
+}
+interface VectorQueryResult<T> {
+    hits: {
+        document: T;
+        score: number;
+    }[];
+    execution: {
+        path: 'exact' | 'hnsw';
+        reason: string;
+        revision: number;
+        efSearch: number | null;
+        distanceComputations: number;
+    };
+    /** Offset pagination uses live snapshots. Writes between pages can change ordering. */
+    nextOffset: number | null;
+}
+interface VectorRecall {
+    recallAtK: number;
+    queries: number;
+    topK: number;
+    exactMs: number;
+    annMs: number;
+}
+interface VectorClient<T> {
+    searchVectors(field: string, vector: ArrayLike<number>, topK: number, filter?: Record<string, unknown>, options?: VectorQueryOptions): Promise<VectorQueryResult<T>>;
+    /** Exact range search. Returns every matching document above the score threshold. */
+    findWithin(field: string, vector: ArrayLike<number>, scoreThreshold: number, filter?: Record<string, unknown>): Promise<VectorQueryResult<T>>;
+    vectorIndexStatus(field: string): Promise<VectorIndexStatus>;
+    rebuildVectorIndex(field: string, options?: VectorRebuildOptions): Promise<VectorBuildProgress>;
+    beginVectorBuild(field: string, options?: VectorGraphOptions): Promise<VectorBuildProgress>;
+    stepVectorBuild(field: string, id: string, batchSize?: number): Promise<VectorBuildProgress>;
+    cancelVectorBuild(field: string, id: string): Promise<VectorBuildProgress>;
+    measureVectorRecall(field: string, queries: ArrayLike<number>[], topK: number, filter?: Record<string, unknown>, options?: VectorQueryOptions): Promise<VectorRecall>;
+}
+/** Binding adapter used by TalaDB's Node, browser, and React Native packages. */
+declare function createVectorClient<T>(send: (request: Record<string, unknown>) => Promise<any>): VectorClient<T>;
+
 /** The three mutation kinds a webhook reports, and the verb each one uses. */
 type WebhookOp = 'insert' | 'update' | 'delete';
 interface WebhookConfig {
@@ -105,13 +183,15 @@ interface VectorIndexOptions {
      * Index algorithm. Defaults to `"flat"` (exact brute-force).
      * Use `"hnsw"` for approximate nearest-neighbour search — much faster on
      * large collections at the cost of occasional missed results.
-     * Requires the `vector-hnsw` feature to be compiled in.
+     * Supported on browser, Node.js and React Native.
      */
     indexType?: 'flat' | 'hnsw';
-    /** HNSW connectivity parameter M. This implementation supports only 32 (the default). */
+    /** HNSW connectivity parameter M. Supported range is 2–128; defaults to 32. */
     hnswM?: number;
     /** HNSW build-time quality parameter ef_construction (default 200). */
     hnswEfConstruction?: number;
+    /** Graph compression; originals remain available for exact rescoring. */
+    quantization?: VectorQuantization;
 }
 /** Describes the indexes that exist on a collection. */
 interface CollectionIndexInfo {
@@ -482,7 +562,7 @@ type AggregatePipeline<T extends Document = Document> = AggregateStage<T>[];
 type InsertDoc<T extends Document> = Omit<T, '_id'> & {
     _id?: string;
 };
-interface Collection<T extends Document = Document> {
+interface Collection<T extends Document = Document> extends VectorClient<T> {
     insert(doc: InsertDoc<T>): Promise<string>;
     insertMany(docs: InsertDoc<T>[]): Promise<string[]>;
     find(filter?: Filter<T>): Promise<T[]>;
@@ -600,7 +680,7 @@ interface Collection<T extends Document = Document> {
      *
      * After calling this, `findNearest` uses approximate nearest-neighbour
      * search which is significantly faster on large collections.
-     * Requires the `vector-hnsw` feature to be compiled in; no-op otherwise.
+     * Promotes flat/legacy indexes and compacts persistent graphs.
      */
     upgradeVectorIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
     /**
@@ -620,7 +700,7 @@ interface Collection<T extends Document = Document> {
      *   locale: 'en',
      * });
      */
-    findNearest(field: keyof Omit<T, '_id'> & string, vector: number[], topK: number, filter?: Filter<T>): Promise<VectorSearchResult<T>[]>;
+    findNearest(field: keyof Omit<T, '_id'> & string, vector: number[], topK: number, filter?: Filter<T>, options?: VectorQueryOptions): 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
@@ -680,6 +760,12 @@ interface TalaDB {
      * "save now" moments (before checkout, on `visibilitychange`).
      */
     flush?(): Promise<void>;
+    /**
+     * Rebuild all configured HNSW graphs for maintenance. Graphs persist across
+     * restarts; startup rebuilding is unnecessary. Prefer per-collection
+     * rebuildVectorIndex for bounded batches, progress and cancellation.
+     */
+    rebuildVectorIndexes?(): Promise<void>;
     /**
      * Whether this browser tab owns the database storage. All tabs execute reads
      * and writes through that owner and await its result. Ownership can change
@@ -932,4 +1018,4 @@ interface OpenDBOptions {
  */
 declare function openDB(dbName?: string, options?: OpenDBOptions): Promise<TalaDB>;
 
-export { type AggregatePipeline, type AggregateStage, type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type DurabilityConfig, type Filter, type HybridSearchOptions, type HybridSearchResult, type InsertDoc, type Migration, type OpenDBOptions, type Schema, type TalaDB, type TalaDbConfig, TalaDbValidationError, type TextSearchOptions, type TextSearchResult, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, type WebhookConfig, type WebhookDispatcher, type WebhookEvent, type WebhookOp, type WebhookStats, applySchema, createWebhookDispatcher, decorateCollection, deriveDocId, isDocId, openDB, runMigrations, validateWebhookConfig };
+export { type AggregatePipeline, type AggregateStage, type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type DurabilityConfig, type Filter, type HybridSearchOptions, type HybridSearchResult, type InsertDoc, type Migration, type OpenDBOptions, type Schema, type TalaDB, type TalaDbConfig, TalaDbValidationError, type TextSearchOptions, type TextSearchResult, type Update, type Value, type VectorBuildProgress, type VectorClient, type VectorGraphOptions, type VectorIndexOptions, type VectorIndexStatus, type VectorMetric, type VectorQuantization, type VectorQueryOptions, type VectorQueryResult, type VectorRebuildOptions, type VectorRecall, type VectorSearchResult, type WebhookConfig, type WebhookDispatcher, type WebhookEvent, type WebhookOp, type WebhookStats, applySchema, createVectorClient, createWebhookDispatcher, decorateCollection, deriveDocId, isDocId, openDB, runMigrations, validateWebhookConfig };

package/dist/index.js

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   TalaDbValidationError: () => TalaDbValidationError,
   applySchema: () => applySchema,
+  createVectorClient: () => createVectorClient,
   createWebhookDispatcher: () => createWebhookDispatcher,
   decorateCollection: () => decorateCollection,
   deriveDocId: () => deriveDocId,
@@ -42,6 +43,92 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/vector-client.ts
+function integer(value, name, min = 0, max = 4294967295) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${name} must be an integer between ${min} and ${max}`);
+}
+function vectorValues(vector) {
+  const values = Array.from(vector);
+  if (values.length === 0 || values.some((v) => !Number.isFinite(v))) throw new Error("vector must contain finite numbers");
+  return values;
+}
+function queryOptions(options) {
+  if (options.efSearch !== void 0) integer(options.efSearch, "efSearch", 1);
+  if (options.offset !== void 0) integer(options.offset, "offset");
+  if (options.groupSize !== void 0) integer(options.groupSize, "groupSize", 1);
+  if (options.oversampling !== void 0) integer(options.oversampling, "oversampling", 1, 100);
+  if (options.scoreThreshold !== void 0 && !Number.isFinite(options.scoreThreshold)) throw new Error("scoreThreshold must be finite");
+  return options;
+}
+function abortError() {
+  const error = new Error("Vector index rebuild cancelled");
+  error.name = "AbortError";
+  return error;
+}
+function createVectorClient(send) {
+  const client = {
+    searchVectors: async (field, vector, topK, filter, options = {}) => {
+      integer(topK, "topK");
+      return send({ op: "search", field, query: vectorValues(vector), topK, filter, options: queryOptions(options) });
+    },
+    findWithin: (field, vector, scoreThreshold, filter) => client.searchVectors(field, vector, 4294967295, filter, { mode: "exact", scoreThreshold }),
+    vectorIndexStatus: (field) => send({ op: "status", field }),
+    beginVectorBuild: (field, options) => send({ op: "beginBuild", field, options }),
+    stepVectorBuild: async (field, id, batchSize = 32) => {
+      integer(batchSize, "batchSize", 1, 1024);
+      return send({ op: "stepBuild", field, id, batchSize });
+    },
+    cancelVectorBuild: (field, id) => send({ op: "cancelBuild", field, id }),
+    rebuildVectorIndex: async (field, options = {}) => {
+      const { signal, onProgress, batchSize = 32, ...graphOptions } = options;
+      integer(batchSize, "batchSize", 1, 1024);
+      if (signal?.aborted) throw abortError();
+      let progress = await client.beginVectorBuild(field, Object.keys(graphOptions).length ? graphOptions : void 0);
+      try {
+        onProgress?.(progress);
+        while (progress.state === "building") {
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          if (signal?.aborted) throw abortError();
+          progress = await client.stepVectorBuild(field, progress.id, batchSize);
+          onProgress?.(progress);
+        }
+        if (progress.state === "failed") throw new Error(progress.error ?? "Vector rebuild failed");
+        if (progress.state === "cancelled") throw abortError();
+        return progress;
+      } catch (error) {
+        if (progress.state === "building") await client.cancelVectorBuild(field, progress.id);
+        throw error;
+      }
+    },
+    measureVectorRecall: async (field, queries, topK, filter, options = {}) => {
+      integer(topK, "topK", 1);
+      return send({ op: "recall", field, queries: queries.map(vectorValues), topK, filter, options: queryOptions(options) });
+    }
+  };
+  return client;
+}
+function vectorIndexRequest(field, options) {
+  integer(options.dimensions, "dimensions", 1);
+  if (options.metric && !["cosine", "dot", "euclidean"].includes(options.metric)) throw new Error("invalid vector metric");
+  if (options.indexType && !["flat", "hnsw"].includes(options.indexType)) throw new Error("invalid vector indexType");
+  if (options.quantization && options.quantization !== "none" && options.indexType !== "hnsw") throw new Error("quantization requires an HNSW index");
+  if (options.indexType === "hnsw") {
+    const m = options.hnswM ?? 32;
+    const efConstruction = options.hnswEfConstruction ?? 200;
+    integer(m, "hnswM", 2, 128);
+    integer(efConstruction, "hnswEfConstruction", m, 1e5);
+    if (options.metric === "dot") throw new Error("HNSW requires cosine or euclidean");
+    if (options.quantization === "binary" && options.metric && options.metric !== "cosine") throw new Error("binary quantization requires cosine");
+  }
+  return {
+    op: "create",
+    field,
+    dimensions: options.dimensions,
+    metric: options.metric,
+    options: options.indexType === "hnsw" ? { m: options.hnswM ?? 32, efConstruction: options.hnswEfConstruction ?? 200, quantization: options.quantization ?? "none" } : null
+  };
+}
+
 // src/webhook.ts
 var METHOD = {
   insert: "POST",
@@ -784,7 +871,9 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
   }
   function wrapCollection(name, opts) {
     const s = JSON.stringify;
+    const vectorCommand = async (request) => JSON.parse(await proxy.send("vectorCommand", { collection: name, requestJson: JSON.stringify(request) }));
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: (doc) => proxy.send("insert", { collection: name, docJson: s(doc) }),
       insertMany: async (docs) => {
         const json = await proxy.send("insertMany", {
@@ -836,25 +925,21 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
       dropCompoundIndex: (fields) => proxy.send("dropCompoundIndex", { collection: name, fieldsJson: JSON.stringify(fields) }),
       createFtsIndex: (field) => proxy.send("createFtsIndex", { collection: name, field }),
       dropFtsIndex: (field) => proxy.send("dropFtsIndex", { collection: name, field }),
-      createVectorIndex: (field, options) => {
-        if (options.indexType === "hnsw") return Promise.reject(new Error("HNSW vector indexes are not available in the browser (requires native threads). Use Node.js or React Native."));
-        return proxy.send("createVectorIndex", {
-          collection: name,
-          field,
-          dimensions: options.dimensions,
-          metric: options.metric,
-          indexType: null,
-          hnswM: null,
-          hnswEfConstruction: null
-        });
+      createVectorIndex: async (field, options) => {
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
       },
       dropVectorIndex: (field) => proxy.send("dropVectorIndex", { collection: name, field }),
-      upgradeVectorIndex: (_field) => Promise.reject(new Error("HNSW vector indexes are not available in the browser (requires native threads). Use Node.js or React Native.")),
+      upgradeVectorIndex: async (field) => {
+        await createVectorClient(vectorCommand).rebuildVectorIndex(field);
+      },
       listIndexes: async () => {
         const json = await proxy.send("listIndexes", { collection: name });
         return JSON.parse(json);
       },
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const json = await proxy.send("findNearest", {
           collection: name,
           field,
@@ -1015,7 +1100,9 @@ async function createNodeDB(dbName, webhook, config, passphrase, migrations) {
   const db = TalaDBNode.open(dbName, configJson, passphrase ?? null);
   function wrapCollection(name, opts) {
     const col = db.collection(name);
+    const vectorCommand = async (request) => col.vectorCommandAsync ? col.vectorCommandAsync(request) : col.vectorCommand(request);
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: async (doc) => col.insertAsync ? col.insertAsync(doc) : col.insert(doc),
       insertMany: async (docs) => col.insertManyAsync ? col.insertManyAsync(docs) : col.insertMany(docs),
       find: async (filter) => col.findAsync ? col.findAsync(filter ?? null) : col.find(filter ?? null),
@@ -1032,14 +1119,19 @@ async function createNodeDB(dbName, webhook, config, passphrase, migrations) {
       dropCompoundIndex: async (fields) => col.dropCompoundIndex(fields),
       createFtsIndex: async (field) => col.createFtsIndex(field),
       dropFtsIndex: async (field) => col.dropFtsIndex(field),
-      createVectorIndex: async (field, options) => col.createVectorIndex(field, options.dimensions, options.metric ?? null, options.indexType ?? null, options.hnswM ?? null, options.hnswEfConstruction ?? null),
+      createVectorIndex: async (field, options) => {
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
+      },
       dropVectorIndex: async (field) => col.dropVectorIndex(field),
       upgradeVectorIndex: async (field) => col.upgradeVectorIndex(field),
       listIndexes: async () => {
         const json = col.listIndexes();
         return JSON.parse(json);
       },
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const raw = await col.findNearest(field, vector, topK, filter ?? null);
         return raw;
       },
@@ -1118,7 +1210,9 @@ async function createNativeDB(_dbName, webhook, migrations) {
     return result;
   };
   function wrapCollection(name, opts) {
+    const vectorCommand = async (request) => call("vectorCommand", name, request);
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: async (doc) => await call("insert", name, doc),
       insertMany: async (docs) => await call("insertMany", name, docs),
       find: async (filter) => await call("find", name, filter ?? {}),
@@ -1136,17 +1230,15 @@ async function createNativeDB(_dbName, webhook, migrations) {
       createFtsIndex: async (field) => await call("createFtsIndex", name, field),
       dropFtsIndex: async (field) => await call("dropFtsIndex", name, field),
       createVectorIndex: async (field, options) => {
-        const opts2 = {};
-        if (options.metric) opts2.metric = options.metric;
-        if (options.indexType === "hnsw") {
-          opts2.hnsw = { m: options.hnswM ?? 32, ef_construction: options.hnswEfConstruction ?? 200 };
-        }
-        return await call("createVectorIndex", name, field, options.dimensions, opts2);
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
       },
       dropVectorIndex: async (field) => await call("dropVectorIndex", name, field),
       upgradeVectorIndex: async (field) => await call("upgradeVectorIndex", name, field),
       listIndexes: async () => call("listIndexes", name),
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const raw = await call("findNearest", name, field, vector, topK, filter ?? null);
         return raw;
       },
@@ -1174,6 +1266,9 @@ async function createNativeDB(_dbName, webhook, migrations) {
     flush: native.callAsync || native.flush ? async () => {
       await call("flush");
     } : void 0,
+    rebuildVectorIndexes: native.callAsync || native.rebuildVectorIndexes ? async () => {
+      await call("rebuildVectorIndexes");
+    } : void 0,
     // One process owns the file — there is no other tab to defer to.
     isPrimary: async () => true
   };
@@ -1262,6 +1357,7 @@ function attachWebhook(db, webhook) {
 0 && (module.exports = {
   TalaDbValidationError,
   applySchema,
+  createVectorClient,
   createWebhookDispatcher,
   decorateCollection,
   deriveDocId,

package/dist/index.mjs

@@ -1,3 +1,89 @@
+// src/vector-client.ts
+function integer(value, name, min = 0, max = 4294967295) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${name} must be an integer between ${min} and ${max}`);
+}
+function vectorValues(vector) {
+  const values = Array.from(vector);
+  if (values.length === 0 || values.some((v) => !Number.isFinite(v))) throw new Error("vector must contain finite numbers");
+  return values;
+}
+function queryOptions(options) {
+  if (options.efSearch !== void 0) integer(options.efSearch, "efSearch", 1);
+  if (options.offset !== void 0) integer(options.offset, "offset");
+  if (options.groupSize !== void 0) integer(options.groupSize, "groupSize", 1);
+  if (options.oversampling !== void 0) integer(options.oversampling, "oversampling", 1, 100);
+  if (options.scoreThreshold !== void 0 && !Number.isFinite(options.scoreThreshold)) throw new Error("scoreThreshold must be finite");
+  return options;
+}
+function abortError() {
+  const error = new Error("Vector index rebuild cancelled");
+  error.name = "AbortError";
+  return error;
+}
+function createVectorClient(send) {
+  const client = {
+    searchVectors: async (field, vector, topK, filter, options = {}) => {
+      integer(topK, "topK");
+      return send({ op: "search", field, query: vectorValues(vector), topK, filter, options: queryOptions(options) });
+    },
+    findWithin: (field, vector, scoreThreshold, filter) => client.searchVectors(field, vector, 4294967295, filter, { mode: "exact", scoreThreshold }),
+    vectorIndexStatus: (field) => send({ op: "status", field }),
+    beginVectorBuild: (field, options) => send({ op: "beginBuild", field, options }),
+    stepVectorBuild: async (field, id, batchSize = 32) => {
+      integer(batchSize, "batchSize", 1, 1024);
+      return send({ op: "stepBuild", field, id, batchSize });
+    },
+    cancelVectorBuild: (field, id) => send({ op: "cancelBuild", field, id }),
+    rebuildVectorIndex: async (field, options = {}) => {
+      const { signal, onProgress, batchSize = 32, ...graphOptions } = options;
+      integer(batchSize, "batchSize", 1, 1024);
+      if (signal?.aborted) throw abortError();
+      let progress = await client.beginVectorBuild(field, Object.keys(graphOptions).length ? graphOptions : void 0);
+      try {
+        onProgress?.(progress);
+        while (progress.state === "building") {
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          if (signal?.aborted) throw abortError();
+          progress = await client.stepVectorBuild(field, progress.id, batchSize);
+          onProgress?.(progress);
+        }
+        if (progress.state === "failed") throw new Error(progress.error ?? "Vector rebuild failed");
+        if (progress.state === "cancelled") throw abortError();
+        return progress;
+      } catch (error) {
+        if (progress.state === "building") await client.cancelVectorBuild(field, progress.id);
+        throw error;
+      }
+    },
+    measureVectorRecall: async (field, queries, topK, filter, options = {}) => {
+      integer(topK, "topK", 1);
+      return send({ op: "recall", field, queries: queries.map(vectorValues), topK, filter, options: queryOptions(options) });
+    }
+  };
+  return client;
+}
+function vectorIndexRequest(field, options) {
+  integer(options.dimensions, "dimensions", 1);
+  if (options.metric && !["cosine", "dot", "euclidean"].includes(options.metric)) throw new Error("invalid vector metric");
+  if (options.indexType && !["flat", "hnsw"].includes(options.indexType)) throw new Error("invalid vector indexType");
+  if (options.quantization && options.quantization !== "none" && options.indexType !== "hnsw") throw new Error("quantization requires an HNSW index");
+  if (options.indexType === "hnsw") {
+    const m = options.hnswM ?? 32;
+    const efConstruction = options.hnswEfConstruction ?? 200;
+    integer(m, "hnswM", 2, 128);
+    integer(efConstruction, "hnswEfConstruction", m, 1e5);
+    if (options.metric === "dot") throw new Error("HNSW requires cosine or euclidean");
+    if (options.quantization === "binary" && options.metric && options.metric !== "cosine") throw new Error("binary quantization requires cosine");
+  }
+  return {
+    op: "create",
+    field,
+    dimensions: options.dimensions,
+    metric: options.metric,
+    options: options.indexType === "hnsw" ? { m: options.hnswM ?? 32, efConstruction: options.hnswEfConstruction ?? 200, quantization: options.quantization ?? "none" } : null
+  };
+}
+
 // src/webhook.ts
 var METHOD = {
   insert: "POST",
@@ -739,7 +825,9 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
   }
   function wrapCollection(name, opts) {
     const s = JSON.stringify;
+    const vectorCommand = async (request) => JSON.parse(await proxy.send("vectorCommand", { collection: name, requestJson: JSON.stringify(request) }));
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: (doc) => proxy.send("insert", { collection: name, docJson: s(doc) }),
       insertMany: async (docs) => {
         const json = await proxy.send("insertMany", {
@@ -791,25 +879,21 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
       dropCompoundIndex: (fields) => proxy.send("dropCompoundIndex", { collection: name, fieldsJson: JSON.stringify(fields) }),
       createFtsIndex: (field) => proxy.send("createFtsIndex", { collection: name, field }),
       dropFtsIndex: (field) => proxy.send("dropFtsIndex", { collection: name, field }),
-      createVectorIndex: (field, options) => {
-        if (options.indexType === "hnsw") return Promise.reject(new Error("HNSW vector indexes are not available in the browser (requires native threads). Use Node.js or React Native."));
-        return proxy.send("createVectorIndex", {
-          collection: name,
-          field,
-          dimensions: options.dimensions,
-          metric: options.metric,
-          indexType: null,
-          hnswM: null,
-          hnswEfConstruction: null
-        });
+      createVectorIndex: async (field, options) => {
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
       },
       dropVectorIndex: (field) => proxy.send("dropVectorIndex", { collection: name, field }),
-      upgradeVectorIndex: (_field) => Promise.reject(new Error("HNSW vector indexes are not available in the browser (requires native threads). Use Node.js or React Native.")),
+      upgradeVectorIndex: async (field) => {
+        await createVectorClient(vectorCommand).rebuildVectorIndex(field);
+      },
       listIndexes: async () => {
         const json = await proxy.send("listIndexes", { collection: name });
         return JSON.parse(json);
       },
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const json = await proxy.send("findNearest", {
           collection: name,
           field,
@@ -970,7 +1054,9 @@ async function createNodeDB(dbName, webhook, config, passphrase, migrations) {
   const db = TalaDBNode.open(dbName, configJson, passphrase ?? null);
   function wrapCollection(name, opts) {
     const col = db.collection(name);
+    const vectorCommand = async (request) => col.vectorCommandAsync ? col.vectorCommandAsync(request) : col.vectorCommand(request);
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: async (doc) => col.insertAsync ? col.insertAsync(doc) : col.insert(doc),
       insertMany: async (docs) => col.insertManyAsync ? col.insertManyAsync(docs) : col.insertMany(docs),
       find: async (filter) => col.findAsync ? col.findAsync(filter ?? null) : col.find(filter ?? null),
@@ -987,14 +1073,19 @@ async function createNodeDB(dbName, webhook, config, passphrase, migrations) {
       dropCompoundIndex: async (fields) => col.dropCompoundIndex(fields),
       createFtsIndex: async (field) => col.createFtsIndex(field),
       dropFtsIndex: async (field) => col.dropFtsIndex(field),
-      createVectorIndex: async (field, options) => col.createVectorIndex(field, options.dimensions, options.metric ?? null, options.indexType ?? null, options.hnswM ?? null, options.hnswEfConstruction ?? null),
+      createVectorIndex: async (field, options) => {
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
+      },
       dropVectorIndex: async (field) => col.dropVectorIndex(field),
       upgradeVectorIndex: async (field) => col.upgradeVectorIndex(field),
       listIndexes: async () => {
         const json = col.listIndexes();
         return JSON.parse(json);
       },
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const raw = await col.findNearest(field, vector, topK, filter ?? null);
         return raw;
       },
@@ -1073,7 +1164,9 @@ async function createNativeDB(_dbName, webhook, migrations) {
     return result;
   };
   function wrapCollection(name, opts) {
+    const vectorCommand = async (request) => call("vectorCommand", name, request);
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: async (doc) => await call("insert", name, doc),
       insertMany: async (docs) => await call("insertMany", name, docs),
       find: async (filter) => await call("find", name, filter ?? {}),
@@ -1091,17 +1184,15 @@ async function createNativeDB(_dbName, webhook, migrations) {
       createFtsIndex: async (field) => await call("createFtsIndex", name, field),
       dropFtsIndex: async (field) => await call("dropFtsIndex", name, field),
       createVectorIndex: async (field, options) => {
-        const opts2 = {};
-        if (options.metric) opts2.metric = options.metric;
-        if (options.indexType === "hnsw") {
-          opts2.hnsw = { m: options.hnswM ?? 32, ef_construction: options.hnswEfConstruction ?? 200 };
-        }
-        return await call("createVectorIndex", name, field, options.dimensions, opts2);
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
       },
       dropVectorIndex: async (field) => await call("dropVectorIndex", name, field),
       upgradeVectorIndex: async (field) => await call("upgradeVectorIndex", name, field),
       listIndexes: async () => call("listIndexes", name),
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const raw = await call("findNearest", name, field, vector, topK, filter ?? null);
         return raw;
       },
@@ -1129,6 +1220,9 @@ async function createNativeDB(_dbName, webhook, migrations) {
     flush: native.callAsync || native.flush ? async () => {
       await call("flush");
     } : void 0,
+    rebuildVectorIndexes: native.callAsync || native.rebuildVectorIndexes ? async () => {
+      await call("rebuildVectorIndexes");
+    } : void 0,
     // One process owns the file — there is no other tab to defer to.
     isPrimary: async () => true
   };
@@ -1216,6 +1310,7 @@ function attachWebhook(db, webhook) {
 export {
   TalaDbValidationError,
   applySchema,
+  createVectorClient,
   createWebhookDispatcher,
   decorateCollection,
   deriveDocId,

package/dist/index.react-native.mjs

@@ -1,3 +1,89 @@
+// src/vector-client.ts
+function integer(value, name, min = 0, max = 4294967295) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${name} must be an integer between ${min} and ${max}`);
+}
+function vectorValues(vector) {
+  const values = Array.from(vector);
+  if (values.length === 0 || values.some((v) => !Number.isFinite(v))) throw new Error("vector must contain finite numbers");
+  return values;
+}
+function queryOptions(options) {
+  if (options.efSearch !== void 0) integer(options.efSearch, "efSearch", 1);
+  if (options.offset !== void 0) integer(options.offset, "offset");
+  if (options.groupSize !== void 0) integer(options.groupSize, "groupSize", 1);
+  if (options.oversampling !== void 0) integer(options.oversampling, "oversampling", 1, 100);
+  if (options.scoreThreshold !== void 0 && !Number.isFinite(options.scoreThreshold)) throw new Error("scoreThreshold must be finite");
+  return options;
+}
+function abortError() {
+  const error = new Error("Vector index rebuild cancelled");
+  error.name = "AbortError";
+  return error;
+}
+function createVectorClient(send) {
+  const client = {
+    searchVectors: async (field, vector, topK, filter, options = {}) => {
+      integer(topK, "topK");
+      return send({ op: "search", field, query: vectorValues(vector), topK, filter, options: queryOptions(options) });
+    },
+    findWithin: (field, vector, scoreThreshold, filter) => client.searchVectors(field, vector, 4294967295, filter, { mode: "exact", scoreThreshold }),
+    vectorIndexStatus: (field) => send({ op: "status", field }),
+    beginVectorBuild: (field, options) => send({ op: "beginBuild", field, options }),
+    stepVectorBuild: async (field, id, batchSize = 32) => {
+      integer(batchSize, "batchSize", 1, 1024);
+      return send({ op: "stepBuild", field, id, batchSize });
+    },
+    cancelVectorBuild: (field, id) => send({ op: "cancelBuild", field, id }),
+    rebuildVectorIndex: async (field, options = {}) => {
+      const { signal, onProgress, batchSize = 32, ...graphOptions } = options;
+      integer(batchSize, "batchSize", 1, 1024);
+      if (signal?.aborted) throw abortError();
+      let progress = await client.beginVectorBuild(field, Object.keys(graphOptions).length ? graphOptions : void 0);
+      try {
+        onProgress?.(progress);
+        while (progress.state === "building") {
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          if (signal?.aborted) throw abortError();
+          progress = await client.stepVectorBuild(field, progress.id, batchSize);
+          onProgress?.(progress);
+        }
+        if (progress.state === "failed") throw new Error(progress.error ?? "Vector rebuild failed");
+        if (progress.state === "cancelled") throw abortError();
+        return progress;
+      } catch (error) {
+        if (progress.state === "building") await client.cancelVectorBuild(field, progress.id);
+        throw error;
+      }
+    },
+    measureVectorRecall: async (field, queries, topK, filter, options = {}) => {
+      integer(topK, "topK", 1);
+      return send({ op: "recall", field, queries: queries.map(vectorValues), topK, filter, options: queryOptions(options) });
+    }
+  };
+  return client;
+}
+function vectorIndexRequest(field, options) {
+  integer(options.dimensions, "dimensions", 1);
+  if (options.metric && !["cosine", "dot", "euclidean"].includes(options.metric)) throw new Error("invalid vector metric");
+  if (options.indexType && !["flat", "hnsw"].includes(options.indexType)) throw new Error("invalid vector indexType");
+  if (options.quantization && options.quantization !== "none" && options.indexType !== "hnsw") throw new Error("quantization requires an HNSW index");
+  if (options.indexType === "hnsw") {
+    const m = options.hnswM ?? 32;
+    const efConstruction = options.hnswEfConstruction ?? 200;
+    integer(m, "hnswM", 2, 128);
+    integer(efConstruction, "hnswEfConstruction", m, 1e5);
+    if (options.metric === "dot") throw new Error("HNSW requires cosine or euclidean");
+    if (options.quantization === "binary" && options.metric && options.metric !== "cosine") throw new Error("binary quantization requires cosine");
+  }
+  return {
+    op: "create",
+    field,
+    dimensions: options.dimensions,
+    metric: options.metric,
+    options: options.indexType === "hnsw" ? { m: options.hnswM ?? 32, efConstruction: options.hnswEfConstruction ?? 200, quantization: options.quantization ?? "none" } : null
+  };
+}
+
 // src/config.browser.ts
 var ENDPOINT_FIELDS = [
   "endpoint",
@@ -710,7 +796,9 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
   }
   function wrapCollection(name, opts) {
     const s = JSON.stringify;
+    const vectorCommand = async (request) => JSON.parse(await proxy.send("vectorCommand", { collection: name, requestJson: JSON.stringify(request) }));
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: (doc) => proxy.send("insert", { collection: name, docJson: s(doc) }),
       insertMany: async (docs) => {
         const json = await proxy.send("insertMany", {
@@ -762,25 +850,21 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
       dropCompoundIndex: (fields) => proxy.send("dropCompoundIndex", { collection: name, fieldsJson: JSON.stringify(fields) }),
       createFtsIndex: (field) => proxy.send("createFtsIndex", { collection: name, field }),
       dropFtsIndex: (field) => proxy.send("dropFtsIndex", { collection: name, field }),
-      createVectorIndex: (field, options) => {
-        if (options.indexType === "hnsw") return Promise.reject(new Error("HNSW vector indexes are not available in the browser (requires native threads). Use Node.js or React Native."));
-        return proxy.send("createVectorIndex", {
-          collection: name,
-          field,
-          dimensions: options.dimensions,
-          metric: options.metric,
-          indexType: null,
-          hnswM: null,
-          hnswEfConstruction: null
-        });
+      createVectorIndex: async (field, options) => {
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
       },
       dropVectorIndex: (field) => proxy.send("dropVectorIndex", { collection: name, field }),
-      upgradeVectorIndex: (_field) => Promise.reject(new Error("HNSW vector indexes are not available in the browser (requires native threads). Use Node.js or React Native.")),
+      upgradeVectorIndex: async (field) => {
+        await createVectorClient(vectorCommand).rebuildVectorIndex(field);
+      },
       listIndexes: async () => {
         const json = await proxy.send("listIndexes", { collection: name });
         return JSON.parse(json);
       },
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const json = await proxy.send("findNearest", {
           collection: name,
           field,
@@ -941,7 +1025,9 @@ async function createNodeDB(dbName, webhook, config, passphrase, migrations) {
   const db = TalaDBNode.open(dbName, configJson, passphrase ?? null);
   function wrapCollection(name, opts) {
     const col = db.collection(name);
+    const vectorCommand = async (request) => col.vectorCommandAsync ? col.vectorCommandAsync(request) : col.vectorCommand(request);
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: async (doc) => col.insertAsync ? col.insertAsync(doc) : col.insert(doc),
       insertMany: async (docs) => col.insertManyAsync ? col.insertManyAsync(docs) : col.insertMany(docs),
       find: async (filter) => col.findAsync ? col.findAsync(filter ?? null) : col.find(filter ?? null),
@@ -958,14 +1044,19 @@ async function createNodeDB(dbName, webhook, config, passphrase, migrations) {
       dropCompoundIndex: async (fields) => col.dropCompoundIndex(fields),
       createFtsIndex: async (field) => col.createFtsIndex(field),
       dropFtsIndex: async (field) => col.dropFtsIndex(field),
-      createVectorIndex: async (field, options) => col.createVectorIndex(field, options.dimensions, options.metric ?? null, options.indexType ?? null, options.hnswM ?? null, options.hnswEfConstruction ?? null),
+      createVectorIndex: async (field, options) => {
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
+      },
       dropVectorIndex: async (field) => col.dropVectorIndex(field),
       upgradeVectorIndex: async (field) => col.upgradeVectorIndex(field),
       listIndexes: async () => {
         const json = col.listIndexes();
         return JSON.parse(json);
       },
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const raw = await col.findNearest(field, vector, topK, filter ?? null);
         return raw;
       },
@@ -1044,7 +1135,9 @@ async function createNativeDB(_dbName, webhook, migrations) {
     return result;
   };
   function wrapCollection(name, opts) {
+    const vectorCommand = async (request) => call("vectorCommand", name, request);
     const wrapped = {
+      ...createVectorClient(vectorCommand),
       insert: async (doc) => await call("insert", name, doc),
       insertMany: async (docs) => await call("insertMany", name, docs),
       find: async (filter) => await call("find", name, filter ?? {}),
@@ -1062,17 +1155,15 @@ async function createNativeDB(_dbName, webhook, migrations) {
       createFtsIndex: async (field) => await call("createFtsIndex", name, field),
       dropFtsIndex: async (field) => await call("dropFtsIndex", name, field),
       createVectorIndex: async (field, options) => {
-        const opts2 = {};
-        if (options.metric) opts2.metric = options.metric;
-        if (options.indexType === "hnsw") {
-          opts2.hnsw = { m: options.hnswM ?? 32, ef_construction: options.hnswEfConstruction ?? 200 };
-        }
-        return await call("createVectorIndex", name, field, options.dimensions, opts2);
+        const request = vectorIndexRequest(field, options);
+        await vectorCommand({ ...request, deferBuild: true });
+        if (request.options) await createVectorClient(vectorCommand).rebuildVectorIndex(field, request.options);
       },
       dropVectorIndex: async (field) => await call("dropVectorIndex", name, field),
       upgradeVectorIndex: async (field) => await call("upgradeVectorIndex", name, field),
       listIndexes: async () => call("listIndexes", name),
-      findNearest: async (field, vector, topK, filter) => {
+      findNearest: async (field, vector, topK, filter, options) => {
+        if (options) return (await createVectorClient(vectorCommand).searchVectors(field, vector, topK, filter, options)).hits;
         const raw = await call("findNearest", name, field, vector, topK, filter ?? null);
         return raw;
       },
@@ -1100,6 +1191,9 @@ async function createNativeDB(_dbName, webhook, migrations) {
     flush: native.callAsync || native.flush ? async () => {
       await call("flush");
     } : void 0,
+    rebuildVectorIndexes: native.callAsync || native.rebuildVectorIndexes ? async () => {
+      await call("rebuildVectorIndexes");
+    } : void 0,
     // One process owns the file — there is no other tab to defer to.
     isPrimary: async () => true
   };
@@ -1187,6 +1281,7 @@ function attachWebhook(db, webhook) {
 export {
   TalaDbValidationError,
   applySchema,
+  createVectorClient,
   createWebhookDispatcher,
   decorateCollection,
   deriveDocId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taladb",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "The embedded vector database for on-device AI — documents, similarity search, and offline sync for browser, React Native, and Node.js",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -62,8 +62,8 @@
     "vitest": "^3.2.0"
   },
   "peerDependencies": {
-    "@taladb/web": "0.11.3",
-    "@taladb/node": "0.11.3"
+    "@taladb/web": "0.11.4",
+    "@taladb/node": "0.11.4"
   },
   "peerDependenciesMeta": {
     "@taladb/web": {