taladb 0.8.2 → 0.8.4

package/dist/index.browser.mjs

@@ -21,6 +21,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({ _id: target });
+  return doc?.sinceMs ?? 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 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 sinceMs = await readCursor(cursorCol, target);
+  const startedAt = Date.now();
+  const local = doPush ? await handle.exportChanges(collections, sinceMs) : "[]";
+  let pulled = 0;
+  if (doPull) {
+    const remote = await adapter.pull(sinceMs);
+    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, startedAt);
+  return { pushed, pulled, cursor: startedAt };
+}
+
+// src/http-adapter.ts
+var HttpSyncAdapter = class {
+  constructor(options) {
+    this.endpoint = options.endpoint.replace(/\/$/, "");
+    this.headers = options.headers ?? {};
+    const f = options.fetch ?? globalThis.fetch;
+    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 TalaDbValidationError = class extends Error {
   constructor(cause, context) {
@@ -197,6 +294,13 @@ 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 }),
       createFtsIndex: (field) => proxy.send("createFtsIndex", { collection: name, field }),
@@ -277,7 +381,8 @@ async function createBrowserDB(dbName, config) {
         worker.terminate();
         proxy.abort(new Error("taladb worker closed"));
       }
-    }
+    },
+    ...unsupportedSync("browser (OPFS worker)")
   };
 }
 async function createNodeDB(dbName, config) {
@@ -296,6 +401,7 @@ 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),
       createFtsIndex: async (field) => col.createFtsIndex(field),
@@ -315,12 +421,17 @@ async function createNodeDB(dbName, config) {
     };
     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__;
@@ -341,6 +452,7 @@ 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),
       createFtsIndex: async (field) => native.createFtsIndex(name, field),
@@ -369,7 +481,8 @@ async function createNativeDB(_dbName) {
   return {
     collection: (name, opts) => wrapCollection(name, opts),
     compact: async () => native.compact(),
-    close: async () => native.close()
+    close: async () => native.close(),
+    ...unsupportedSync("react-native")
   };
 }
 async function openDB(dbName = "taladb.db", options) {
@@ -391,6 +504,7 @@ async function openDB(dbName = "taladb.db", options) {
   }
 }
 export {
+  HttpSyncAdapter,
   TalaDbValidationError,
   openDB
 };

package/dist/index.d.mts

@@ -113,6 +113,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,6 +143,18 @@ 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>;
     /**
@@ -198,8 +230,82 @@ interface Collection<T extends Document = Document> {
      */
     subscribe(filter: Filter<T>, callback: (docs: T[]) => 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 for cursor persistence, so multiple remotes each
+     * keep their own watermark. 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;
+    /** New sync cursor (ms epoch) persisted for the next pass. */
+    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.
@@ -252,6 +358,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.
@@ -294,4 +439,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.d.ts

@@ -113,6 +113,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,6 +143,18 @@ 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>;
     /**
@@ -198,8 +230,82 @@ interface Collection<T extends Document = Document> {
      */
     subscribe(filter: Filter<T>, callback: (docs: T[]) => 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 for cursor persistence, so multiple remotes each
+     * keep their own watermark. 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;
+    /** New sync cursor (ms epoch) persisted for the next pass. */
+    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.
@@ -252,6 +358,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.
@@ -294,4 +439,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({ _id: target });
+  return doc?.sinceMs ?? 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 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 sinceMs = await readCursor(cursorCol, target);
+  const startedAt = Date.now();
+  const local = doPush ? await handle.exportChanges(collections, sinceMs) : "[]";
+  let pulled = 0;
+  if (doPull) {
+    const remote = await adapter.pull(sinceMs);
+    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, startedAt);
+  return { pushed, pulled, cursor: startedAt };
+}
+
+// src/http-adapter.ts
+var HttpSyncAdapter = class {
+  constructor(options) {
+    this.endpoint = options.endpoint.replace(/\/$/, "");
+    this.headers = options.headers ?? {};
+    const f = options.fetch ?? globalThis.fetch;
+    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 {
@@ -292,6 +390,13 @@ 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 }),
       createFtsIndex: (field) => proxy.send("createFtsIndex", { collection: name, field }),
@@ -372,7 +477,8 @@ async function createBrowserDB(dbName, config) {
         worker.terminate();
         proxy.abort(new Error("taladb worker closed"));
       }
-    }
+    },
+    ...unsupportedSync("browser (OPFS worker)")
   };
 }
 async function createNodeDB(dbName, config) {
@@ -391,6 +497,7 @@ 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),
       createFtsIndex: async (field) => col.createFtsIndex(field),
@@ -410,12 +517,17 @@ async function createNodeDB(dbName, config) {
     };
     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,6 +548,7 @@ 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),
       createFtsIndex: async (field) => native.createFtsIndex(name, field),
@@ -464,7 +577,8 @@ async function createNativeDB(_dbName) {
   return {
     collection: (name, opts) => wrapCollection(name, opts),
     compact: async () => native.compact(),
-    close: async () => native.close()
+    close: async () => native.close(),
+    ...unsupportedSync("react-native")
   };
 }
 async function openDB(dbName = "taladb.db", options) {
@@ -487,6 +601,7 @@ async function openDB(dbName = "taladb.db", options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  HttpSyncAdapter,
   TalaDbValidationError,
   openDB
 });

package/dist/index.mjs

@@ -78,6 +78,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({ _id: target });
+  return doc?.sinceMs ?? 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 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 sinceMs = await readCursor(cursorCol, target);
+  const startedAt = Date.now();
+  const local = doPush ? await handle.exportChanges(collections, sinceMs) : "[]";
+  let pulled = 0;
+  if (doPull) {
+    const remote = await adapter.pull(sinceMs);
+    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, startedAt);
+  return { pushed, pulled, cursor: startedAt };
+}
+
+// src/http-adapter.ts
+var HttpSyncAdapter = class {
+  constructor(options) {
+    this.endpoint = options.endpoint.replace(/\/$/, "");
+    this.headers = options.headers ?? {};
+    const f = options.fetch ?? globalThis.fetch;
+    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 TalaDbValidationError = class extends Error {
   constructor(cause, context) {
@@ -254,6 +351,13 @@ 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 }),
       createFtsIndex: (field) => proxy.send("createFtsIndex", { collection: name, field }),
@@ -334,7 +438,8 @@ async function createBrowserDB(dbName, config) {
         worker.terminate();
         proxy.abort(new Error("taladb worker closed"));
       }
-    }
+    },
+    ...unsupportedSync("browser (OPFS worker)")
   };
 }
 async function createNodeDB(dbName, config) {
@@ -353,6 +458,7 @@ 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),
       createFtsIndex: async (field) => col.createFtsIndex(field),
@@ -372,12 +478,17 @@ async function createNodeDB(dbName, config) {
     };
     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__;
@@ -398,6 +509,7 @@ 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),
       createFtsIndex: async (field) => native.createFtsIndex(name, field),
@@ -426,7 +538,8 @@ async function createNativeDB(_dbName) {
   return {
     collection: (name, opts) => wrapCollection(name, opts),
     compact: async () => native.compact(),
-    close: async () => native.close()
+    close: async () => native.close(),
+    ...unsupportedSync("react-native")
   };
 }
 async function openDB(dbName = "taladb.db", options) {
@@ -448,6 +561,7 @@ async function openDB(dbName = "taladb.db", options) {
   }
 }
 export {
+  HttpSyncAdapter,
   TalaDbValidationError,
   openDB
 };

package/dist/index.react-native.mjs

@@ -21,6 +21,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({ _id: target });
+  return doc?.sinceMs ?? 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 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 sinceMs = await readCursor(cursorCol, target);
+  const startedAt = Date.now();
+  const local = doPush ? await handle.exportChanges(collections, sinceMs) : "[]";
+  let pulled = 0;
+  if (doPull) {
+    const remote = await adapter.pull(sinceMs);
+    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, startedAt);
+  return { pushed, pulled, cursor: startedAt };
+}
+
+// src/http-adapter.ts
+var HttpSyncAdapter = class {
+  constructor(options) {
+    this.endpoint = options.endpoint.replace(/\/$/, "");
+    this.headers = options.headers ?? {};
+    const f = options.fetch ?? globalThis.fetch;
+    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 TalaDbValidationError = class extends Error {
   constructor(cause, context) {
@@ -197,6 +294,13 @@ 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 }),
       createFtsIndex: (field) => proxy.send("createFtsIndex", { collection: name, field }),
@@ -277,7 +381,8 @@ async function createBrowserDB(dbName, config) {
         worker.terminate();
         proxy.abort(new Error("taladb worker closed"));
       }
-    }
+    },
+    ...unsupportedSync("browser (OPFS worker)")
   };
 }
 async function createNodeDB(dbName, config) {
@@ -296,6 +401,7 @@ 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),
       createFtsIndex: async (field) => col.createFtsIndex(field),
@@ -315,12 +421,17 @@ async function createNodeDB(dbName, config) {
     };
     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__;
@@ -341,6 +452,7 @@ 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),
       createFtsIndex: async (field) => native.createFtsIndex(name, field),
@@ -369,7 +481,8 @@ async function createNativeDB(_dbName) {
   return {
     collection: (name, opts) => wrapCollection(name, opts),
     compact: async () => native.compact(),
-    close: async () => native.close()
+    close: async () => native.close(),
+    ...unsupportedSync("react-native")
   };
 }
 async function openDB(dbName = "taladb.db", options) {
@@ -391,6 +504,7 @@ async function openDB(dbName = "taladb.db", options) {
   }
 }
 export {
+  HttpSyncAdapter,
   TalaDbValidationError,
   openDB
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taladb",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Local-first document and vector database for React, React Native, and Node.js",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -42,7 +42,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/thinkgrid-labs/taladb.git",
-    "directory": "packages/taladb"
+    "directory": "packages/clients/taladb"
   },
   "homepage": "https://thinkgrid-labs.github.io/taladb/",
   "bugs": {