taladb 0.11.2 → 0.11.4

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,
@@ -867,7 +951,7 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
   function nudgedPoller(collection, fetchJson, callback, onError) {
     let active = true;
     let lastJson = "";
-    let lastGeneration = -1;
+    let lastGeneration = null;
     let generationSupported = true;
     let timer = null;
     let running = false;
@@ -932,6 +1016,7 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
       await proxy.send("flush");
     },
     isPrimary: () => proxy.send("isPrimary"),
+    storageInfo: () => proxy.send("capabilities"),
     close: async () => {
       channel?.close();
       try {
@@ -944,14 +1029,16 @@ async function createBrowserDB(dbName, webhook, config, passphrase, migrations)
     listCollectionNames: async () => JSON.parse(await proxy.send("listCollections"))
   };
   if (migrations?.length) {
-    await runMigrations(
-      handle,
-      async () => proxy.send("userVersion"),
-      async (v) => {
-        await proxy.send("setUserVersion", { version: v });
-      },
-      migrations
-    );
+    await navigator.locks.request(`taladb:migrations:${dbName}`, async () => {
+      await runMigrations(
+        handle,
+        async () => proxy.send("userVersion"),
+        async (v) => {
+          await proxy.send("setUserVersion", { version: v });
+        },
+        migrations
+      );
+    });
   }
   return handle;
 }
@@ -967,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),
@@ -984,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;
       },
@@ -1039,78 +1133,109 @@ async function createNativeDB(_dbName, webhook, migrations) {
     );
   }
   const native = maybeNative;
+  let nativeQueue = Promise.resolve();
+  let queued = 0;
+  let closed = false;
+  const call = (op, ...args) => {
+    if (queued >= 128) return Promise.reject(new Error("TalaDB native request queue is full"));
+    queued++;
+    const result = nativeQueue.then(async () => {
+      if (closed) throw new Error("TalaDB database is closed");
+      if (op === "close") {
+        closed = true;
+        native.close();
+        return;
+      }
+      if (op === "findNearest" && native.findNearestAsync) {
+        return native.findNearestAsync(...args);
+      }
+      if (native.callAsync) return native.callAsync(op, args);
+      if (op === "find" && native.findAsync) {
+        return native.findAsync(...args);
+      }
+      const method = native[op];
+      if (!method) throw new Error(`${op} requires a newer @taladb/react-native binary; rebuild the native module`);
+      return method(...args);
+    });
+    nativeQueue = result.catch(() => {
+    }).finally(() => {
+      queued--;
+    });
+    return result;
+  };
   function wrapCollection(name, opts) {
+    const vectorCommand = async (request) => call("vectorCommand", name, request);
     const wrapped = {
-      insert: async (doc) => native.insert(name, doc),
-      insertMany: async (docs) => native.insertMany(name, docs),
-      find: async (filter) => native.find(name, filter ?? {}),
-      findOne: async (filter) => native.findOne(name, filter ?? {}),
-      updateOne: async (filter, update) => native.updateOne(name, filter, update),
-      updateMany: async (filter, update) => native.updateMany(name, filter, update),
-      deleteOne: async (filter) => native.deleteOne(name, filter),
-      deleteMany: async (filter) => native.deleteMany(name, filter),
-      count: async (filter) => native.count(name, filter ?? {}),
-      aggregate: async (pipeline) => native.aggregate(name, pipeline),
-      createIndex: async (field) => native.createIndex(name, field),
-      dropIndex: async (field) => native.dropIndex(name, field),
-      createCompoundIndex: async (fields) => native.createCompoundIndex(name, fields),
-      dropCompoundIndex: async (fields) => native.dropCompoundIndex(name, fields),
-      createFtsIndex: async (field) => native.createFtsIndex(name, field),
-      dropFtsIndex: async (field) => native.dropFtsIndex(name, field),
+      ...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 ?? {}),
+      findOne: async (filter) => await call("findOne", name, filter ?? {}),
+      updateOne: async (filter, update) => await call("updateOne", name, filter, update),
+      updateMany: async (filter, update) => await call("updateMany", name, filter, update),
+      deleteOne: async (filter) => await call("deleteOne", name, filter),
+      deleteMany: async (filter) => await call("deleteMany", name, filter),
+      count: async (filter) => await call("count", name, filter ?? {}),
+      aggregate: async (pipeline) => await call("aggregate", name, pipeline),
+      createIndex: async (field) => await call("createIndex", name, field),
+      dropIndex: async (field) => await call("dropIndex", name, field),
+      createCompoundIndex: async (fields) => await call("createCompoundIndex", name, fields),
+      dropCompoundIndex: async (fields) => await call("dropCompoundIndex", name, fields),
+      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.hnswM || options.hnswEfConstruction) {
-          opts2.hnsw = { m: options.hnswM, efConstruction: options.hnswEfConstruction };
-        }
-        return native.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) => native.dropVectorIndex(name, field),
-      upgradeVectorIndex: async (field) => native.upgradeVectorIndex(name, field),
-      // The JSI HostObject does not expose index introspection yet; return a
-      // correctly-shaped empty result rather than `{}` cast to the interface.
-      listIndexes: async () => ({ btree: [], fts: [], vector: [] }),
-      findNearest: async (field, vector, topK, filter) => {
-        const raw = native.findNearest(name, field, vector, topK, filter ?? null);
+      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, 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;
       },
       searchText: async (field, query, topK, filter, options) => {
-        if (!native.searchText) {
+        if (!native.callAsync && !native.searchText) {
           throw new Error("searchText requires @taladb/react-native \u2265 0.10 \u2014 rebuild the native module");
         }
-        return native.searchText(name, field, query, topK, filter ?? null, options ?? null);
+        return await call("searchText", name, field, query, topK, filter ?? null, options ?? null);
       },
       hybridSearch: async (text, vector, topK, filter, options) => {
-        if (!native.hybridSearch) {
+        if (!native.callAsync && !native.hybridSearch) {
           throw new Error("hybridSearch requires @taladb/react-native \u2265 0.10 \u2014 rebuild the native module");
         }
-        return native.hybridSearch(name, text.textField, text.text, vector.vectorField, vector.vector, topK, filter ?? null, options ?? null);
+        return await call("hybridSearch", name, text.textField, text.text, vector.vectorField, vector.vector, topK, filter ?? null, options ?? null);
       },
-      subscribe: (filter, callback, onError) => makePoller(async () => native.find(name, filter ?? {}), callback, onError),
-      subscribeAggregate: (pipeline, callback, onError) => makePoller(async () => native.aggregate(name, pipeline), callback, onError)
+      subscribe: (filter, callback, onError) => makePoller(async () => await call("find", name, filter ?? {}), callback, onError),
+      subscribeAggregate: (pipeline, callback, onError) => makePoller(async () => await call("aggregate", name, pipeline), callback, onError)
     };
     return decorateCollection(wrapped, name, opts, webhook);
   }
   const handle = {
     collection: (name, opts) => wrapCollection(name, opts),
-    compact: async () => native.compact(),
-    close: async () => native.close(),
-    flush: native.flush ? async () => {
-      native.flush();
+    compact: async () => await call("compact"),
+    close: async () => await call("close"),
+    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
   };
   if (migrations?.length) {
-    if (typeof native.userVersion !== "function" || typeof native.setUserVersion !== "function") {
+    if (!native.callAsync && (typeof native.userVersion !== "function" || typeof native.setUserVersion !== "function")) {
       throw new Error(
         "openDB({ migrations }) is not available on this @taladb/react-native binary yet (the JSI HostObject does not expose userVersion/setUserVersion). Update the native module."
       );
     }
     await runMigrations(
       handle,
-      async () => native.userVersion(),
-      async (v) => native.setUserVersion(v),
+      async () => call("userVersion"),
+      async (v) => call("setUserVersion", v),
       migrations
     );
   }
@@ -1185,6 +1310,7 @@ function attachWebhook(db, webhook) {
 export {
   TalaDbValidationError,
   applySchema,
+  createVectorClient,
   createWebhookDispatcher,
   decorateCollection,
   deriveDocId,