taladb 0.8.4 → 0.9.0

package/dist/index.browser.mjs

@@ -39,15 +39,13 @@ function unsupportedSync(runtime) {
   };
 }
 async function readCursor(cursorCol, target) {
-  const doc = await cursorCol.findOne({ _id: target });
-  return doc?.sinceMs ?? 0;
+  const doc = await cursorCol.findOne({ target });
+  return { pushMs: doc?.pushMs ?? 0, pullMs: doc?.pullMs ?? 0 };
 }
-async function writeCursor(cursorCol, target, sinceMs) {
-  const existing = await cursorCol.findOne({ _id: target });
-  if (existing) {
-    await cursorCol.updateOne({ _id: target }, { $set: { sinceMs } });
-  } else {
-    await cursorCol.insert({ _id: target, sinceMs });
+async function writeCursor(cursorCol, target, cursor) {
+  const updated = await cursorCol.updateOne({ target }, { $set: { ...cursor } });
+  if (!updated) {
+    await cursorCol.insert({ target, ...cursor });
   }
 }
 async function runSync(handle, adapter, options) {
@@ -63,12 +61,11 @@ async function runSync(handle, adapter, options) {
   }
   const collections = await resolveCollections(handle, options);
   const cursorCol = handle.collection(CURSOR_COLLECTION);
-  const sinceMs = await readCursor(cursorCol, target);
-  const startedAt = Date.now();
-  const local = doPush ? await handle.exportChanges(collections, sinceMs) : "[]";
+  const cursor = await readCursor(cursorCol, target);
+  const local = doPush ? await handle.exportChanges(collections, 0) : "[]";
   let pulled = 0;
   if (doPull) {
-    const remote = await adapter.pull(sinceMs);
+    const remote = await adapter.pull(0);
     if (remote && remote !== "[]") {
       pulled = await handle.importChanges(remote);
     }
@@ -78,8 +75,11 @@ async function runSync(handle, adapter, options) {
     pushed = JSON.parse(local).length;
     await adapter.push(local);
   }
-  await writeCursor(cursorCol, target, startedAt);
-  return { pushed, pulled, cursor: startedAt };
+  await writeCursor(cursorCol, target, {
+    pushMs: cursor.pushMs,
+    pullMs: cursor.pullMs
+  });
+  return { pushed, pulled, cursor: 0 };
 }
 
 // src/http-adapter.ts
@@ -87,7 +87,7 @@ var HttpSyncAdapter = class {
   constructor(options) {
     this.endpoint = options.endpoint.replace(/\/$/, "");
     this.headers = options.headers ?? {};
-    const f = options.fetch ?? globalThis.fetch;
+    const f = options.fetch ?? globalThis.fetch?.bind(globalThis);
     if (!f) {
       throw new Error(
         "HttpSyncAdapter: no fetch available. Pass options.fetch on runtimes without a global fetch."
@@ -213,28 +213,44 @@ var WorkerProxy = class {
     this.pending.clear();
   }
 };
-function makePoller(findFn, callback) {
+function makePoller(findFn, callback, onError) {
   let active = true;
   let lastJson = "";
+  let running = false;
+  let rerun = false;
   const poll = async () => {
     if (!active) return;
+    if (running) {
+      rerun = true;
+      return;
+    }
+    running = true;
     try {
       const docs = await findFn();
+      if (!active) return;
       const json = JSON.stringify(docs);
       if (json !== lastJson) {
         lastJson = json;
         callback(docs);
       }
-    } catch {
+    } catch (error) {
+      if (active) onError?.(error);
+    } finally {
+      running = false;
+      if (active) {
+        if (rerun) {
+          rerun = false;
+          void poll();
+        } else setTimeout(poll, 300);
+      }
     }
-    if (active) setTimeout(poll, 300);
   };
   poll();
   return () => {
     active = false;
   };
 }
-async function createBrowserDB(dbName, config) {
+async function createBrowserDB(dbName, config, passphrase) {
   const workerUrl = new URL("@taladb/web/worker/taladb.worker.js", import.meta.url);
   const worker = new Worker(workerUrl, { type: "module", name: "taladb" });
   const proxy = new WorkerProxy(worker);
@@ -242,7 +258,13 @@ async function createBrowserDB(dbName, config) {
     proxy.abort(new Error(`taladb worker error: ${e.message ?? "unknown"}`));
   };
   const configJson = config !== void 0 ? JSON.stringify(config) : void 0;
-  await proxy.send("init", { dbName, configJson });
+  try {
+    await proxy.send("init", { dbName, configJson, passphrase });
+  } catch (e) {
+    proxy.abort(e instanceof Error ? e : new Error(String(e)));
+    worker.terminate();
+    throw e;
+  }
   const nudgeCallbacks = /* @__PURE__ */ new Set();
   let channel = null;
   if (typeof BroadcastChannel !== "undefined") {
@@ -303,6 +325,8 @@ async function createBrowserDB(dbName, config) {
       },
       createIndex: (field) => proxy.send("createIndex", { collection: name, field }),
       dropIndex: (field) => proxy.send("dropIndex", { collection: name, field }),
+      createCompoundIndex: (fields) => proxy.send("createCompoundIndex", { collection: name, fieldsJson: JSON.stringify(fields) }),
+      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) => {
@@ -333,12 +357,19 @@ async function createBrowserDB(dbName, config) {
         });
         return JSON.parse(json);
       },
-      subscribe: (filter, callback) => {
+      subscribe: (filter, callback, onError) => {
         let active = true;
         let lastJson = "";
         let timer = null;
+        let running = false;
+        let rerun = false;
         const poll = async () => {
           if (!active) return;
+          if (running) {
+            rerun = true;
+            return;
+          }
+          running = true;
           if (timer !== null) {
             clearTimeout(timer);
             timer = null;
@@ -348,13 +379,22 @@ async function createBrowserDB(dbName, config) {
               collection: name,
               filterJson: filter ? s(filter) : "null"
             });
+            if (!active) return;
             if (json !== lastJson) {
               lastJson = json;
               callback(JSON.parse(json));
             }
-          } catch {
+          } catch (error) {
+            if (active) onError?.(error);
+          } finally {
+            running = false;
+          }
+          if (active) {
+            if (rerun) {
+              rerun = false;
+              void poll();
+            } else timer = setTimeout(poll, 300);
           }
-          if (active) timer = setTimeout(poll, 300);
         };
         nudgeCallbacks.add(poll);
         poll();
@@ -370,9 +410,11 @@ async function createBrowserDB(dbName, config) {
     };
     return opts ? applySchema(wrapped, opts) : wrapped;
   }
-  return {
+  const handle = {
     collection: (name, opts) => wrapCollection(name, opts),
     compact: () => proxy.send("compact"),
+    syncStatus: async () => JSON.parse(await proxy.send("syncStatus")),
+    flushSync: (timeoutMs = 5e3) => proxy.send("flushSync", { timeoutMs }),
     close: async () => {
       channel?.close();
       try {
@@ -382,13 +424,21 @@ async function createBrowserDB(dbName, config) {
         proxy.abort(new Error("taladb worker closed"));
       }
     },
-    ...unsupportedSync("browser (OPFS worker)")
+    // All engine work (export scan, LWW merge) runs inside the worker, off the
+    // main thread — a sync pass never blocks rendering, whatever its size.
+    exportChanges: (collections, sinceMs) => proxy.send("exportChangeset", { collectionsJson: JSON.stringify(collections), sinceMs }),
+    importChanges: (changeset) => proxy.send("importChangeset", { changesetJson: changeset }),
+    listCollectionNames: async () => JSON.parse(await proxy.send("listCollections")),
+    sync: (adapter, options) => runSync(handle, adapter, options)
   };
+  return handle;
 }
-async function createNodeDB(dbName, config) {
-  const { TalaDBNode } = await import("@taladb/node");
+async function createNodeDB(dbName, config, passphrase) {
+  const native = await import("./node-A4LKRSW5.mjs");
+  const TalaDBNode = native.TalaDbNode ?? native.TalaDBNode;
+  if (!TalaDBNode) throw new Error("@taladb/node loaded but exports no TalaDbNode class \u2014 rebuild the native module");
   const configJson = config !== void 0 ? JSON.stringify(config) : null;
-  const db = TalaDBNode.open(dbName, configJson);
+  const db = TalaDBNode.open(dbName, configJson, passphrase ?? null);
   function wrapCollection(name, opts) {
     const col = db.collection(name);
     const wrapped = {
@@ -404,6 +454,8 @@ async function createNodeDB(dbName, config) {
       aggregate: async (pipeline) => col.aggregate(pipeline),
       createIndex: async (field) => col.createIndex(field),
       dropIndex: async (field) => col.dropIndex(field),
+      createCompoundIndex: async (fields) => col.createCompoundIndex(fields),
+      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),
@@ -417,7 +469,7 @@ async function createNodeDB(dbName, config) {
         const raw = await col.findNearest(field, vector, topK, filter ?? null);
         return raw;
       },
-      subscribe: (filter, callback) => makePoller(async () => col.find(filter ?? null), callback)
+      subscribe: (filter, callback, onError) => makePoller(async () => col.find(filter ?? null), callback, onError)
     };
     return opts ? applySchema(wrapped, opts) : wrapped;
   }
@@ -455,6 +507,8 @@ async function createNativeDB(_dbName) {
       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),
       createVectorIndex: async (field, options) => {
@@ -474,18 +528,35 @@ async function createNativeDB(_dbName) {
         const raw = native.findNearest(name, field, vector, topK, filter ?? null);
         return raw;
       },
-      subscribe: (filter, callback) => makePoller(async () => native.find(name, filter ?? {}), callback)
+      subscribe: (filter, callback, onError) => makePoller(async () => native.find(name, filter ?? {}), callback, onError)
     };
     return opts ? applySchema(wrapped, opts) : wrapped;
   }
+  const syncSurface = typeof native.exportChanges === "function" && typeof native.importChanges === "function" && typeof native.listCollectionNames === "function" ? (() => {
+    const handle = {
+      collection: (name, opts) => wrapCollection(name, opts),
+      exportChanges: async (collections, sinceMs) => native.exportChanges(collections, sinceMs),
+      importChanges: async (changeset) => native.importChanges(changeset),
+      listCollectionNames: async () => native.listCollectionNames(),
+      sync: (adapter, options) => runSync(handle, adapter, options)
+    };
+    return {
+      exportChanges: handle.exportChanges,
+      importChanges: handle.importChanges,
+      sync: handle.sync
+    };
+  })() : unsupportedSync("react-native");
   return {
     collection: (name, opts) => wrapCollection(name, opts),
     compact: async () => native.compact(),
     close: async () => native.close(),
-    ...unsupportedSync("react-native")
+    ...syncSurface
   };
 }
 async function openDB(dbName = "taladb.db", options) {
+  if (options?.passphrase !== void 0 && options.passphrase.length === 0) {
+    throw new Error("TalaDB encryption passphrase must not be empty");
+  }
   let resolvedConfig;
   if (options?.config !== void 0) {
     validateConfig(options.config);
@@ -496,11 +567,14 @@ async function openDB(dbName = "taladb.db", options) {
   const platform = detectPlatform();
   switch (platform) {
     case "browser":
-      return createBrowserDB(dbName, resolvedConfig);
+      return createBrowserDB(dbName, resolvedConfig, options?.passphrase);
     case "react-native":
+      if (options?.passphrase !== void 0) {
+        throw new Error("On React Native, pass the passphrase in the config JSON to TalaDBModule.initialize(); refusing to assume the already-open native database is encrypted");
+      }
       return createNativeDB(dbName);
     case "node":
-      return createNodeDB(dbName, resolvedConfig);
+      return createNodeDB(dbName, resolvedConfig, options?.passphrase);
   }
 }
 export {

package/dist/index.d.mts

@@ -57,6 +57,7 @@ type FieldOps<T> = T extends null | undefined ? {
     $exists?: boolean;
     /** Full-text search: matches documents where this string field contains the given token. */
     $contains?: string;
+    $regex?: string;
 };
 type Filter<T extends Document = Document> = {
     [K in keyof T]?: T[K] | FieldOps<T[K]>;
@@ -157,6 +158,21 @@ interface Collection<T extends Document = Document> {
     aggregate<R extends Document = Document>(pipeline: AggregatePipeline<T>): Promise<R[]>;
     createIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
     dropIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
+    /**
+     * Create a compound (multi-field) index over an ordered list of fields.
+     *
+     * The query planner uses it to accelerate an `$and` where **every** field of
+     * the index is constrained by equality — e.g. an index on
+     * `['userId', 'status']` serves `find({ userId, status })` with a single
+     * index scan instead of a full-collection scan. Fields are ascending; a
+     * partial-prefix or trailing-range match is not used yet (planned).
+     *
+     * @example
+     * await orders.createCompoundIndex(['userId', 'status'])
+     */
+    createCompoundIndex(fields: (keyof Omit<T, '_id'> & string)[]): Promise<void>;
+    /** Drop a compound index by its ordered field list. */
+    dropCompoundIndex(fields: (keyof Omit<T, '_id'> & string)[]): Promise<void>;
     /**
      * Create a full-text search index on a string field.
      *
@@ -228,7 +244,7 @@ interface Collection<T extends Document = Document> {
      * // later…
      * unsub();
      */
-    subscribe(filter: Filter<T>, callback: (docs: T[]) => void): () => void;
+    subscribe(filter: Filter<T>, callback: (docs: T[]) => void, onError?: (error: unknown) => void): () => void;
 }
 /**
  * A JSON-encoded changeset — the opaque payload exchanged between peers. Produced
@@ -269,8 +285,9 @@ interface SyncOptions {
     /** Direction of the pass. Default `'both'` (bidirectional). */
     direction?: SyncDirection;
     /**
-     * Names this sync target for cursor persistence, so multiple remotes each
-     * keep their own watermark. Default `'default'`.
+     * Names this sync target. Reserved cursor state remains isolated per target
+     * for forward compatibility with monotonic server cursors. Default
+     * `'default'`.
      */
     target?: string;
 }
@@ -279,7 +296,7 @@ interface SyncResult {
     pushed: number;
     /** Number of documents changed locally by the pulled remote changeset. */
     pulled: number;
-    /** New sync cursor (ms epoch) persisted for the next pass. */
+    /** Active sync cursor. Currently `0` because timestamp adapters replay safely. */
     cursor: number;
 }
 interface TalaDB {
@@ -317,6 +334,14 @@ interface TalaDB {
      * await db.compact();
      */
     compact(): Promise<void>;
+    /** Browser HTTP-push queue health, when supported by the active binding. */
+    syncStatus?(): Promise<{
+        pending: number;
+        dropped: number;
+        failed: number;
+    }>;
+    /** Wait for accepted browser HTTP-push events, returning false on timeout. */
+    flushSync?(timeoutMs?: number): Promise<boolean>;
     close(): Promise<void>;
 }
 
@@ -408,6 +433,8 @@ declare class TalaDbValidationError extends Error {
 
 /** Options for `openDB`. */
 interface OpenDBOptions {
+    /** Encrypt native database values at rest. Never hard-code this value. */
+    passphrase?: string;
     /**
      * Explicit path to a `taladb.config.yml` / `taladb.config.json` file.
      * If omitted, TalaDB auto-discovers the file from `process.cwd()` on Node.js.

package/dist/index.d.ts

@@ -57,6 +57,7 @@ type FieldOps<T> = T extends null | undefined ? {
     $exists?: boolean;
     /** Full-text search: matches documents where this string field contains the given token. */
     $contains?: string;
+    $regex?: string;
 };
 type Filter<T extends Document = Document> = {
     [K in keyof T]?: T[K] | FieldOps<T[K]>;
@@ -157,6 +158,21 @@ interface Collection<T extends Document = Document> {
     aggregate<R extends Document = Document>(pipeline: AggregatePipeline<T>): Promise<R[]>;
     createIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
     dropIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
+    /**
+     * Create a compound (multi-field) index over an ordered list of fields.
+     *
+     * The query planner uses it to accelerate an `$and` where **every** field of
+     * the index is constrained by equality — e.g. an index on
+     * `['userId', 'status']` serves `find({ userId, status })` with a single
+     * index scan instead of a full-collection scan. Fields are ascending; a
+     * partial-prefix or trailing-range match is not used yet (planned).
+     *
+     * @example
+     * await orders.createCompoundIndex(['userId', 'status'])
+     */
+    createCompoundIndex(fields: (keyof Omit<T, '_id'> & string)[]): Promise<void>;
+    /** Drop a compound index by its ordered field list. */
+    dropCompoundIndex(fields: (keyof Omit<T, '_id'> & string)[]): Promise<void>;
     /**
      * Create a full-text search index on a string field.
      *
@@ -228,7 +244,7 @@ interface Collection<T extends Document = Document> {
      * // later…
      * unsub();
      */
-    subscribe(filter: Filter<T>, callback: (docs: T[]) => void): () => void;
+    subscribe(filter: Filter<T>, callback: (docs: T[]) => void, onError?: (error: unknown) => void): () => void;
 }
 /**
  * A JSON-encoded changeset — the opaque payload exchanged between peers. Produced
@@ -269,8 +285,9 @@ interface SyncOptions {
     /** Direction of the pass. Default `'both'` (bidirectional). */
     direction?: SyncDirection;
     /**
-     * Names this sync target for cursor persistence, so multiple remotes each
-     * keep their own watermark. Default `'default'`.
+     * Names this sync target. Reserved cursor state remains isolated per target
+     * for forward compatibility with monotonic server cursors. Default
+     * `'default'`.
      */
     target?: string;
 }
@@ -279,7 +296,7 @@ interface SyncResult {
     pushed: number;
     /** Number of documents changed locally by the pulled remote changeset. */
     pulled: number;
-    /** New sync cursor (ms epoch) persisted for the next pass. */
+    /** Active sync cursor. Currently `0` because timestamp adapters replay safely. */
     cursor: number;
 }
 interface TalaDB {
@@ -317,6 +334,14 @@ interface TalaDB {
      * await db.compact();
      */
     compact(): Promise<void>;
+    /** Browser HTTP-push queue health, when supported by the active binding. */
+    syncStatus?(): Promise<{
+        pending: number;
+        dropped: number;
+        failed: number;
+    }>;
+    /** Wait for accepted browser HTTP-push events, returning false on timeout. */
+    flushSync?(timeoutMs?: number): Promise<boolean>;
     close(): Promise<void>;
 }
 
@@ -408,6 +433,8 @@ declare class TalaDbValidationError extends Error {
 
 /** Options for `openDB`. */
 interface OpenDBOptions {
+    /** Encrypt native database values at rest. Never hard-code this value. */
+    passphrase?: string;
     /**
      * Explicit path to a `taladb.config.yml` / `taladb.config.json` file.
      * If omitted, TalaDB auto-discovers the file from `process.cwd()` on Node.js.