anchordb 0.2.0

package/dist/cjs/sync/adapters/rest.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RestSyncAdapter = void 0;
+const protocol_ts_1 = require("../protocol.js");
+/**
+ * REST transport for the sync protocol.
+ *
+ * `POST {endpoint}/sync/push` and `POST {endpoint}/sync/pull`, plain JSON in and out.
+ *
+ * The important distinction this class draws is between **retryable** and **fatal** failures:
+ * a network error or a 5xx becomes `SyncTransportError` (the engine backs off and keeps the work),
+ * while a 401/403 becomes `SyncAuthError` (the engine pauses and asks the app to refresh the
+ * token). Collapsing those two would either discard queued writes on a transient blip, or retry an
+ * expired token forever.
+ */
+class RestSyncAdapter {
+    constructor(options) {
+        this.name = "rest";
+        this.opts = options;
+    }
+    async push(request) {
+        return this.post("/sync/push", request);
+    }
+    async pull(request) {
+        return this.post("/sync/pull", request);
+    }
+    async post(path, body) {
+        const fetchImpl = this.opts.fetchImpl ?? globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new protocol_ts_1.SyncTransportError("No fetch implementation available. Pass `fetchImpl` to RestSyncAdapter on runtimes without global fetch.");
+        }
+        const url = `${this.opts.endpoint.replace(/\/$/, "")}${path}`;
+        const headers = {
+            "content-type": "application/json",
+            accept: "application/json",
+            ...this.opts.headers,
+        };
+        const token = this.opts.getToken ? await this.opts.getToken() : this.opts.token;
+        if (token)
+            headers.authorization = `Bearer ${token}`;
+        const controller = new AbortController();
+        const timeout = this.opts.timeoutMs ?? 30_000;
+        const timer = setTimeout(() => controller.abort(), timeout);
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            // Network down, DNS failure, timeout — all retryable. The queue is never discarded for these.
+            throw new protocol_ts_1.SyncTransportError(controller.signal.aborted ? `Request to ${url} timed out after ${timeout}ms` : err.message);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new protocol_ts_1.SyncAuthError(response.status, `Authentication failed for ${url} (${response.status})`);
+        }
+        if (!response.ok) {
+            throw new protocol_ts_1.SyncTransportError(`${url} responded ${response.status} ${response.statusText}`, response.status);
+        }
+        try {
+            return (await response.json());
+        }
+        catch (err) {
+            throw new protocol_ts_1.SyncTransportError(`${url} returned a malformed JSON body: ${err.message}`);
+        }
+    }
+}
+exports.RestSyncAdapter = RestSyncAdapter;
+//# sourceMappingURL=rest.js.map

package/dist/cjs/sync/adapters/rest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.js","sourceRoot":"","sources":["../../../../src/sync/adapters/rest.ts"],"names":[],"mappings":"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"}

package/dist/cjs/sync/attach.d.ts

@@ -0,0 +1,30 @@
+import type { AnchorDB } from "../core/anchor-db.js";
+import { MutationQueue } from "./queue.js";
+import { SyncEngine, type SyncRunResult } from "./engine.js";
+import { RestSyncAdapter } from "./adapters/rest.js";
+import type { SyncAdapter } from "./protocol.js";
+export interface AttachSyncOptions {
+    /** Supply a custom transport (WebSocket, GraphQL, a test double). Defaults to REST. */
+    transport?: SyncAdapter;
+    /** Adopt pre-existing local documents on first sync. Default true. */
+    adoptExisting?: boolean;
+}
+export interface AttachedSync {
+    engine: SyncEngine;
+    queue: MutationQueue;
+    /** `immediate` bypasses retry backoff — use it when connectivity is known to be restored. */
+    run(options?: {
+        immediate?: boolean;
+    }): Promise<SyncRunResult>;
+}
+/**
+ * Wire the sync engine into a database.
+ *
+ * Kept as a separate entry point rather than something `AnchorDB` constructs itself, so a local-only
+ * app never imports the engine, the queue, the conflict strategies or the transport at all — they
+ * tree-shake out entirely. Sync genuinely costs nothing when unused.
+ */
+export declare function attachSync(db: AnchorDB, options?: AttachSyncOptions): Promise<AttachedSync>;
+export { MutationQueue, SyncEngine, RestSyncAdapter };
+export type { SyncRunResult };
+//# sourceMappingURL=attach.d.ts.map

package/dist/cjs/sync/attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../../src/sync/attach.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGrD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,eAAe,CAAC;AAE3D,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,sEAAsE;IACtE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,aAAa,CAAC;IACrB,6FAA6F;IAC7F,GAAG,CAAC,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAChE;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC,CA4DrG;AA4CD,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,CAAC"}

package/dist/cjs/sync/attach.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RestSyncAdapter = exports.SyncEngine = exports.MutationQueue = void 0;
+exports.attachSync = attachSync;
+const errors_ts_1 = require("../core/errors.js");
+const queue_ts_1 = require("./queue.js");
+Object.defineProperty(exports, "MutationQueue", { enumerable: true, get: function () { return queue_ts_1.MutationQueue; } });
+const engine_ts_1 = require("./engine.js");
+Object.defineProperty(exports, "SyncEngine", { enumerable: true, get: function () { return engine_ts_1.SyncEngine; } });
+const rest_ts_1 = require("./adapters/rest.js");
+Object.defineProperty(exports, "RestSyncAdapter", { enumerable: true, get: function () { return rest_ts_1.RestSyncAdapter; } });
+/**
+ * Wire the sync engine into a database.
+ *
+ * Kept as a separate entry point rather than something `AnchorDB` constructs itself, so a local-only
+ * app never imports the engine, the queue, the conflict strategies or the transport at all — they
+ * tree-shake out entirely. Sync genuinely costs nothing when unused.
+ */
+async function attachSync(db, options = {}) {
+    const config = db.config.sync;
+    if (!config) {
+        throw new errors_ts_1.AnchorConfigError("attachSync() requires a `sync` block in the AnchorDB config. " +
+            "Without one the database is intentionally local-only.");
+    }
+    await db.open();
+    const transport = options.transport ??
+        new rest_ts_1.RestSyncAdapter({
+            endpoint: config.endpoint,
+            ...(config.token ? { token: config.token } : {}),
+            ...(config.auth?.token ? { token: config.auth.token } : {}),
+            ...(config.auth?.getToken ? { getToken: config.auth.getToken } : {}),
+        });
+    const queue = new queue_ts_1.MutationQueue(db.adapter, db.clientId);
+    const engine = new engine_ts_1.SyncEngine({
+        adapter: db.adapter,
+        transport,
+        queue,
+        clock: db.clock,
+        time: db.time,
+        events: db.events,
+        clientId: db.clientId,
+        ...(config.conflictResolution ? { conflictResolution: config.conflictResolution } : {}),
+        ...(config.batchSize !== undefined ? { batchSize: config.batchSize } : {}),
+        ...(config.maxConflictAttempts !== undefined ? { maxConflictAttempts: config.maxConflictAttempts } : {}),
+    });
+    db._attachSync({
+        recordMutations: async (collection, ops) => {
+            const mutations = ops.map((op) => toMutation(collection, op, db));
+            await queue.enqueue(mutations);
+            const counts = await queue.counts();
+            db.events.emit("queue:changed", { pending: counts.pending, failed: counts.failed });
+        },
+        run: async () => {
+            // db.sync.now() is an explicit user action ("sync now", pull-to-refresh), so it should not
+            // sit behind a backoff timer created while the network was down.
+            const result = await engine.run({ immediate: true });
+            return { pushed: result.pushed, pulled: result.pulled, conflicts: result.conflicts };
+        },
+        pending: async () => (await queue.counts()).pending,
+        setStatus: (setter) => {
+            engineStatusBridge(engine, setter);
+        },
+    });
+    if (options.adoptExisting !== false) {
+        const collections = (await db.adapter.listCollections()).filter((c) => !c.startsWith("__anchor"));
+        await engine.adoptExistingDocuments(collections);
+    }
+    return { engine, queue, run: (options = {}) => engine.run(options) };
+}
+/**
+ * Bridge the engine's status into the database's facade.
+ *
+ * Wrapping rather than adding a listener because the engine sets status synchronously inside its
+ * run loop, and we want `db.sync.status()` to be accurate the instant it changes.
+ */
+function engineStatusBridge(engine, setter) {
+    const target = engine;
+    const original = target.setStatus?.bind(engine);
+    target.setStatus = (status) => {
+        original?.(status);
+        setter(status);
+    };
+}
+/**
+ * Translate a storage write into a wire mutation.
+ *
+ * `update` carries the full document rather than the original operators. That is a deliberate
+ * trade-off: operators would be more compact and would merge more gracefully server-side, but they
+ * cannot be replayed correctly against a server document that has since moved on. Sending the
+ * resulting document keeps the conflict decision on the client, where the configured strategy and
+ * the shadow copy both live. Documented in SYNC_PROTOCOL.md.
+ */
+function toMutation(collection, op, db) {
+    const operation = op.type === "insert" ? "insert" : op.type === "replace" ? "replace" : op.type === "update" ? "update" : "delete";
+    return {
+        collection,
+        documentId: op._id,
+        operation,
+        payload: operation === "delete" ? null : (op.row?.doc ?? null),
+        baseVersion: op.row?.meta.version ?? 0,
+        hlc: op.row?.meta.hlc ?? db.clock.tickStamp(),
+    };
+}
+//# sourceMappingURL=attach.js.map

package/dist/cjs/sync/attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.js","sourceRoot":"","sources":["../../../src/sync/attach.ts"],"names":[],"mappings":"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"}

package/dist/cjs/sync/engine.d.ts

@@ -0,0 +1,96 @@
+import type { HybridLogicalClock } from "../core/hlc.js";
+import type { TypedEmitter } from "../events/emitter.js";
+import type { AnchorEvents } from "../core/runtime.js";
+import type { TimeService } from "../timestamps/index.js";
+import type { DatabaseAdapter } from "../storage/types.js";
+import type { ConflictResolutionConfig } from "../conflict/types.js";
+import { MutationQueue } from "./queue.js";
+import { type SyncAdapter } from "./protocol.js";
+/** Last server-confirmed document per id — the common ancestor a 3-way merge needs. */
+export declare const SHADOW_COLLECTION = "__anchor_shadow";
+export type SyncStatusValue = "idle" | "syncing" | "offline" | "error" | "paused";
+export interface SyncEngineOptions {
+    adapter: DatabaseAdapter;
+    transport: SyncAdapter;
+    queue: MutationQueue;
+    clock: HybridLogicalClock;
+    time: TimeService;
+    events: TypedEmitter<AnchorEvents>;
+    clientId: string;
+    conflictResolution?: ConflictResolutionConfig;
+    batchSize?: number;
+    maxConflictAttempts?: number;
+    onStatus?: (status: SyncStatusValue) => void;
+}
+export interface SyncRunResult {
+    pushed: number;
+    pulled: number;
+    conflicts: number;
+    rejected: number;
+}
+/**
+ * The sync engine.
+ *
+ * Responsibilities, in the order they run:
+ *
+ *   recover -> push (with conflict resolution) -> pull -> apply remote -> persist cursor
+ *
+ * Deliberately serialised: a second `run()` while one is in flight returns the same promise rather
+ * than starting a concurrent pass, because two passes would both take from the queue and could push
+ * the same mutation twice.
+ */
+export declare class SyncEngine {
+    private readonly opts;
+    private readonly strategies;
+    private readonly strategyName;
+    private inFlight;
+    private status;
+    private clockOffsetMs;
+    private recovered;
+    constructor(options: SyncEngineOptions);
+    getStatus(): SyncStatusValue;
+    private setStatus;
+    /**
+     * @param options.immediate Bypass retry backoff. Set for user-initiated or
+     * connectivity-restored syncs, where waiting out a timer computed during the outage is pointless.
+     */
+    run(options?: {
+        immediate?: boolean;
+    }): Promise<SyncRunResult>;
+    private runOnce;
+    private pushAll;
+    private applyPushResult;
+    private resolveConflict;
+    private pullAll;
+    /**
+     * Apply a server change locally.
+     *
+     * A document with unpushed local edits is left alone: overwriting it would silently discard the
+     * user's offline work. The pending mutation will conflict on its next push and go through the
+     * configured strategy, which is where that decision belongs.
+     */
+    private applyRemoteChange;
+    /**
+     * Estimate the client's clock offset from the server and feed it to the HLC.
+     *
+     * This is what stops a device with a badly wrong clock from ordering its writes incorrectly
+     * against everyone else's. The server stamp is treated as authoritative (`trusted: true`) —
+     * see the reasoning in HybridLogicalClock.update().
+     */
+    private absorbServerClock;
+    private markSynced;
+    private writeResolved;
+    private writeShadow;
+    private readShadow;
+    private clearShadow;
+    private emitQueueChanged;
+    /**
+     * Adopt documents written before sync was enabled (§ "turning sync on later").
+     *
+     * Marks every existing document dirty at version 0 so the first sync pushes it. Without this,
+     * enabling sync on an existing app would leave all prior data stranded locally — the single most
+     * likely upgrade path, and the one a naive design silently breaks.
+     */
+    adoptExistingDocuments(collections: string[]): Promise<number>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/cjs/sync/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/sync/engine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAsB,MAAM,qBAAqB,CAAC;AAG/E,OAAO,KAAK,EAAmB,wBAAwB,EAAc,MAAM,sBAAsB,CAAC;AAClG,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAQL,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAInD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAElF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,WAAW,CAAC;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6F;IAClH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,EAAE,iBAAiB;IAStC,SAAS,IAAI,eAAe;IAI5B,OAAO,CAAC,SAAS;IAKjB;;;OAGG;IACG,GAAG,CAAC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,aAAa,CAAC;YAQ1D,OAAO;YAgDP,OAAO;YA0CP,eAAe;YAuCf,eAAe;YAiGf,OAAO;IA8BrB;;;;;;OAMG;YACW,iBAAiB;IAsD/B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;YAWX,UAAU;YAoBV,aAAa;YA2Bb,WAAW;YA0BX,UAAU;YAKV,WAAW;YAMX,gBAAgB;IAK9B;;;;;;OAMG;IACG,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAiCrE"}