taladb 0.8.3 → 0.9.0

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]>;
@@ -113,6 +114,26 @@ interface CollectionOptions<T extends Document = Document> {
      */
     validateOnRead?: boolean;
 }
+/** A single MongoDB-style aggregation stage. */
+type AggregateStage<T extends Document = Document> = {
+    $match: Filter<T>;
+} | {
+    /** `_id` is a `"$field"` reference or `null` (single group); other keys are
+     * accumulator outputs, e.g. `total: { $sum: '$amount' }`, `n: { $sum: 1 }`. */
+    $group: {
+        _id: string | null;
+    } & Record<string, unknown>;
+} | {
+    $sort: Record<string, 1 | -1>;
+} | {
+    $skip: number;
+} | {
+    $limit: number;
+} | {
+    $project: Record<string, 0 | 1>;
+};
+/** An ordered aggregation pipeline. */
+type AggregatePipeline<T extends Document = Document> = AggregateStage<T>[];
 interface Collection<T extends Document = Document> {
     insert(doc: Omit<T, '_id'>): Promise<string>;
     insertMany(docs: Omit<T, '_id'>[]): Promise<string[]>;
@@ -123,8 +144,35 @@ interface Collection<T extends Document = Document> {
     deleteOne(filter: Filter<T>): Promise<boolean>;
     deleteMany(filter: Filter<T>): Promise<number>;
     count(filter?: Filter<T>): Promise<number>;
+    /**
+     * Run a MongoDB-style aggregation pipeline (`$match`, `$group`, `$sort`,
+     * `$skip`, `$limit`, `$project`) inside the engine. Returns the resulting
+     * documents. Currently available on Node.js and the in-memory browser build.
+     *
+     * @example
+     * const byStatus = await orders.aggregate([
+     *   { $group: { _id: '$status', total: { $sum: '$amount' }, n: { $sum: 1 } } },
+     *   { $sort: { total: -1 } },
+     * ]);
+     */
+    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.
      *
@@ -196,10 +244,85 @@ 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
+ * by {@link TalaDB.exportChanges}, transported by a {@link SyncAdapter}, and
+ * consumed by {@link TalaDB.importChanges}. Treat it as an opaque string.
+ */
+type SerializedChangeset = string;
+/** Direction of a sync pass. `'both'` (default) is fully bidirectional. */
+type SyncDirection = 'push' | 'pull' | 'both';
+/**
+ * A transport for {@link TalaDB.sync}. Implement `push` to send local changes to
+ * a remote, `pull` to fetch remote changes — or both for bidirectional sync.
+ * The changeset is an opaque JSON string; move it over any wire you like.
+ */
+interface SyncAdapter {
+    /** Send a local changeset to the remote. Required for `'push'` / `'both'`. */
+    push?(changeset: SerializedChangeset): Promise<void>;
+    /**
+     * Fetch remote changes with `changed_at` after `sinceMs` (ms epoch), as a
+     * serialized changeset. Return `'[]'` when there is nothing new. Required for
+     * `'pull'` / `'both'`.
+     */
+    pull?(sinceMs: number): Promise<SerializedChangeset>;
+}
+interface SyncOptions {
+    /**
+     * Collections to sync. Omit to sync **all** user collections (reserved
+     * `_`-prefixed collections are always skipped). Provide an array to sync only
+     * those.
+     */
+    collections?: string[];
+    /**
+     * Collections to skip. Applied after `collections` (or after the
+     * all-collections default), so `{ exclude: ['logs'] }` means "sync everything
+     * except logs".
+     */
+    exclude?: string[];
+    /** Direction of the pass. Default `'both'` (bidirectional). */
+    direction?: SyncDirection;
+    /**
+     * Names this sync target. Reserved cursor state remains isolated per target
+     * for forward compatibility with monotonic server cursors. Default
+     * `'default'`.
+     */
+    target?: string;
+}
+interface SyncResult {
+    /** Number of local changes pushed to the remote. */
+    pushed: number;
+    /** Number of documents changed locally by the pulled remote changeset. */
+    pulled: number;
+    /** Active sync cursor. Currently `0` because timestamp adapters replay safely. */
+    cursor: number;
 }
 interface TalaDB {
     collection<T extends Document = Document>(name: string, options?: CollectionOptions<T>): Collection<T>;
+    /**
+     * Run one bidirectional sync pass against `adapter`: pull remote changes and
+     * merge them (Last-Write-Wins), then push local changes since the last cursor.
+     * The cursor is persisted per `target`, so successive calls sync incrementally.
+     * Set `direction` to `'push'` or `'pull'` to make it one-way.
+     *
+     * @example
+     * await db.sync(httpAdapter, { collections: ['notes'] });          // bidirectional
+     * await db.sync(httpAdapter, { collections: ['logs'], direction: 'push' });
+     */
+    sync(adapter: SyncAdapter, options: SyncOptions): Promise<SyncResult>;
+    /**
+     * Low-level: export changes to `collections` with `changed_at` after `sinceMs`
+     * (exclusive) as a serialized changeset. Most apps use {@link TalaDB.sync}.
+     */
+    exportChanges(collections: string[], sinceMs: number): Promise<SerializedChangeset>;
+    /**
+     * Low-level: merge a serialized changeset into the local database via
+     * Last-Write-Wins. Returns the number of documents changed. Idempotent —
+     * re-importing the same changeset is a no-op.
+     */
+    importChanges(changeset: SerializedChangeset): Promise<number>;
     /**
      * Compact the underlying storage file, reclaiming space freed by deletes
      * and updates.
@@ -211,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>;
 }
 
@@ -252,6 +383,45 @@ interface TalaDbConfig {
     sync?: SyncConfig;
 }
 
+interface HttpSyncAdapterOptions {
+    /** Base URL, e.g. `https://api.example.com/sync`. `/push` and `/pull` are appended. */
+    endpoint: string;
+    /** Extra headers on every request — typically `Authorization`. */
+    headers?: Record<string, string>;
+    /**
+     * `fetch` implementation. Defaults to the global `fetch` (Node 18+, browsers,
+     * React Native). Inject a custom one for tests or non-standard environments.
+     */
+    fetch?: typeof fetch;
+    /** Paths appended to `endpoint`. Override to match an existing API. */
+    paths?: {
+        push?: string;
+        pull?: string;
+    };
+}
+/**
+ * A ready-to-use {@link SyncAdapter} that syncs over plain HTTP. Pair it with
+ * {@link TalaDB.sync}:
+ *
+ * ```ts
+ * const adapter = new HttpSyncAdapter({
+ *   endpoint: 'https://api.example.com/sync',
+ *   headers: { Authorization: `Bearer ${token}` },
+ * });
+ * await db.sync(adapter, { collections: ['notes'] });
+ * ```
+ */
+declare class HttpSyncAdapter implements SyncAdapter {
+    private readonly endpoint;
+    private readonly headers;
+    private readonly fetchFn;
+    private readonly pushPath;
+    private readonly pullPath;
+    constructor(options: HttpSyncAdapterOptions);
+    push(changeset: SerializedChangeset): Promise<void>;
+    pull(sinceMs: number): Promise<SerializedChangeset>;
+}
+
 /**
  * Thrown when a document fails schema validation on `insert` or `insertMany`.
  * The `cause` property holds the original error thrown by the schema library.
@@ -263,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.
@@ -294,4 +466,4 @@ interface OpenDBOptions {
  */
 declare function openDB(dbName?: string, options?: OpenDBOptions): Promise<TalaDB>;
 
-export { type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type Filter, type OpenDBOptions, type Schema, type SyncConfig, type TalaDB, type TalaDbConfig, TalaDbValidationError, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, openDB };
+export { type AggregatePipeline, type AggregateStage, type Collection, type CollectionIndexInfo, type CollectionOptions, type Document, type Filter, HttpSyncAdapter, type OpenDBOptions, type Schema, type SerializedChangeset, type SyncAdapter, type SyncConfig, type SyncDirection, type SyncOptions, type SyncResult, type TalaDB, type TalaDbConfig, TalaDbValidationError, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, openDB };

package/dist/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  HttpSyncAdapter: () => HttpSyncAdapter,
   TalaDbValidationError: () => TalaDbValidationError,
   openDB: () => openDB
 });
@@ -115,6 +116,103 @@ async function loadConfig(configPath) {
   return {};
 }
 
+// src/sync.ts
+var CURSOR_COLLECTION = "__taladb_sync";
+async function resolveCollections(handle, options) {
+  const base = options.collections ?? await handle.listCollectionNames();
+  const excluded = new Set(options.exclude ?? []);
+  return base.filter((c) => !excluded.has(c) && !c.startsWith("_"));
+}
+function unsupportedSync(runtime) {
+  const err = () => new Error(
+    `TalaDB sync is not yet available on the ${runtime} runtime (Node.js is supported today; browser and React Native are in progress). Track it on the roadmap.`
+  );
+  return {
+    sync: () => Promise.reject(err()),
+    exportChanges: () => Promise.reject(err()),
+    importChanges: () => Promise.reject(err())
+  };
+}
+async function readCursor(cursorCol, target) {
+  const doc = await cursorCol.findOne({ target });
+  return { pushMs: doc?.pushMs ?? 0, pullMs: doc?.pullMs ?? 0 };
+}
+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) {
+  const direction = options.direction ?? "both";
+  const target = options.target ?? "default";
+  const doPush = direction === "push" || direction === "both";
+  const doPull = direction === "pull" || direction === "both";
+  if (doPull && !adapter.pull) {
+    throw new Error(`sync direction '${direction}' requires adapter.pull()`);
+  }
+  if (doPush && !adapter.push) {
+    throw new Error(`sync direction '${direction}' requires adapter.push()`);
+  }
+  const collections = await resolveCollections(handle, options);
+  const cursorCol = handle.collection(CURSOR_COLLECTION);
+  const cursor = await readCursor(cursorCol, target);
+  const local = doPush ? await handle.exportChanges(collections, 0) : "[]";
+  let pulled = 0;
+  if (doPull) {
+    const remote = await adapter.pull(0);
+    if (remote && remote !== "[]") {
+      pulled = await handle.importChanges(remote);
+    }
+  }
+  let pushed = 0;
+  if (doPush && local !== "[]") {
+    pushed = JSON.parse(local).length;
+    await adapter.push(local);
+  }
+  await writeCursor(cursorCol, target, {
+    pushMs: cursor.pushMs,
+    pullMs: cursor.pullMs
+  });
+  return { pushed, pulled, cursor: 0 };
+}
+
+// src/http-adapter.ts
+var HttpSyncAdapter = class {
+  constructor(options) {
+    this.endpoint = options.endpoint.replace(/\/$/, "");
+    this.headers = options.headers ?? {};
+    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."
+      );
+    }
+    this.fetchFn = f;
+    this.pushPath = options.paths?.push ?? "/push";
+    this.pullPath = options.paths?.pull ?? "/pull";
+  }
+  async push(changeset) {
+    const res = await this.fetchFn(`${this.endpoint}${this.pushPath}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...this.headers },
+      body: changeset
+    });
+    if (!res.ok) {
+      throw new Error(`HttpSyncAdapter push failed: ${res.status} ${res.statusText}`);
+    }
+  }
+  async pull(sinceMs) {
+    const url = `${this.endpoint}${this.pullPath}?since=${encodeURIComponent(String(sinceMs))}`;
+    const res = await this.fetchFn(url, { method: "GET", headers: this.headers });
+    if (!res.ok) {
+      throw new Error(`HttpSyncAdapter pull failed: ${res.status} ${res.statusText}`);
+    }
+    const body = (await res.text()).trim();
+    return body.length === 0 ? "[]" : body;
+  }
+};
+
 // src/index.ts
 var import_meta = {};
 var TalaDbValidationError = class extends Error {
@@ -211,28 +309,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);
@@ -240,7 +354,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") {
@@ -292,8 +412,17 @@ async function createBrowserDB(dbName, config) {
         collection: name,
         filterJson: filter ? s(filter) : "null"
       }),
+      aggregate: async (pipeline) => {
+        const json = await proxy.send("aggregate", {
+          collection: name,
+          pipelineJson: s(pipeline)
+        });
+        return JSON.parse(json);
+      },
       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) => {
@@ -324,12 +453,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;
@@ -339,13 +475,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();
@@ -361,9 +506,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 {
@@ -372,13 +519,22 @@ async function createBrowserDB(dbName, config) {
         worker.terminate();
         proxy.abort(new Error("taladb worker closed"));
       }
-    }
+    },
+    // 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("@taladb/node");
+  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 = {
@@ -391,8 +547,11 @@ async function createNodeDB(dbName, config) {
       deleteOne: async (filter) => col.deleteOneAsync ? col.deleteOneAsync(filter) : col.deleteOne(filter),
       deleteMany: async (filter) => col.deleteManyAsync ? col.deleteManyAsync(filter) : col.deleteMany(filter),
       count: async (filter) => col.count(filter ?? null),
+      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),
@@ -406,16 +565,21 @@ 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;
   }
-  return {
+  const handle = {
     collection: (name, opts) => wrapCollection(name, opts),
     compact: async () => db.compact(),
     // Releases the native file handle/lock (no-op on older .node binaries).
-    close: async () => db.close?.()
+    close: async () => db.close?.(),
+    exportChanges: async (collections, sinceMs) => db.exportChanges(sinceMs, collections),
+    importChanges: async (changeset) => db.importChanges(changeset),
+    listCollectionNames: async () => db.listCollectionNames(),
+    sync: (adapter, options) => runSync(handle, adapter, options)
   };
+  return handle;
 }
 async function createNativeDB(_dbName) {
   const maybeNative = globalThis.__TalaDB__;
@@ -436,8 +600,11 @@ async function createNativeDB(_dbName) {
       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),
       createVectorIndex: async (field, options) => {
@@ -457,17 +624,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()
+    close: async () => native.close(),
+    ...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);
@@ -478,15 +663,19 @@ 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);
   }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  HttpSyncAdapter,
   TalaDbValidationError,
   openDB
 });