@syncular/client 0.15.46 → 0.15.48

package/dist/node-database.js

@@ -1,23 +1,9 @@
 /**
- * `ClientDatabase` on better-sqlite3 — the Electron-main / plain-Node
- * backend. Semantics mirror `./bun-database`
- * exactly (synchronous exec/query/transaction with the shared savepoint
- * helper, and the same §5.3 sqlite-image ATTACH path), so the core behaves
- * identically whether it runs on bun:sqlite (tests), sqlite-wasm (browser)
- * or better-sqlite3 (Node/Electron-main).
- *
- * better-sqlite3 is an OPTIONAL peer dependency, not a hard one: the package
- * installs cleanly without it and this module errors helpfully only when a
- * host actually calls `openNodeDatabase()` without having installed the peer.
- * Not exported from the package root, so browser/bun entries never resolve
- * the native module. Subpath export: `@syncular/client/node`.
- *
- * bun CANNOT dlopen better-sqlite3 (ERR_DLOPEN_FAILED, oven-sh/bun#4290), so
- * this adapter is verified under real Node — see the README "Electron-main /
- * plain-Node" section for the one-command recipe and `test/node-database`.
+ * `ClientDatabase` on Node's built-in `node:sqlite`. Semantics mirror the Bun
+ * adapter: synchronous queries, nested transactions, and SQLite image attach.
  */
+import { DatabaseSync } from 'node:sqlite';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { assertImageAlias, runTransaction, } from './database.js';
@@ -28,19 +14,12 @@ function coerceParams(params) {
         return value;
     });
 }
-/**
- * better-sqlite3 returns BLOB columns as Node `Buffer`s. A Buffer IS a
- * Uint8Array subclass, but it can be a view onto a shared pool buffer, so we
- * normalize to a standalone Uint8Array — matching what bun:sqlite hands back
- * and keeping the buffer-ownership assumptions elsewhere (worker transfer,
- * structured clone) honest.
- */
 function normalizeRow(row) {
     const out = {};
     for (const key in row) {
         const value = row[key];
-        if (Buffer.isBuffer(value)) {
-            out[key] = new Uint8Array(value); // copies out of the pool
+        if (value instanceof Uint8Array) {
+            out[key] = new Uint8Array(value);
         }
         else {
             out[key] = value;
@@ -48,47 +27,11 @@ function normalizeRow(row) {
     }
     return out;
 }
-/**
- * Load the optional peer AND open the database in one guarded step, so BOTH
- * failure modes are turned into a clear, actionable error rather than a raw
- * one:
- *
- *  - `require('better-sqlite3')` throwing MODULE_NOT_FOUND — the peer is not
- *    installed (the common browser-only-host case), and
- *  - `new Database()` throwing ERR_DLOPEN_FAILED — the module resolves but the
- *    native addon cannot load, which is exactly what bun does for
- *    better-sqlite3 (oven-sh/bun#4290); the addon only dlopens at construction.
- */
-function openBetterSqlite(path) {
-    const require = createRequire(import.meta.url);
-    try {
-        const mod = require('better-sqlite3');
-        const Database = mod.default ??
-            mod;
-        return new Database(path);
-    }
-    catch (error) {
-        const code = error?.code;
-        if (code === 'ERR_DLOPEN_FAILED') {
-            throw new Error("openNodeDatabase() requires the 'better-sqlite3' native module, but " +
-                'it failed to load. This most commonly means you are running under ' +
-                'bun, which cannot dlopen better-sqlite3 (oven-sh/bun#4290) — use ' +
-                "the bun:sqlite backend ('@syncular/client/bun') under bun, " +
-                "and reserve '@syncular/client/node' for Node/Electron-main. " +
-                `Underlying error: ${String(error)}`);
-        }
-        throw new Error('openNodeDatabase() requires the optional peer dependency ' +
-            "'better-sqlite3', which is not installed. Add it to your app " +
-            '(`npm install better-sqlite3` / `bun add better-sqlite3`) — it is ' +
-            'kept optional so @syncular/client installs without a native ' +
-            `build for browser-only hosts. Underlying error: ${String(error)}`);
-    }
-}
 export class NodeClientDatabase {
     db;
     #tx = { depth: 0 };
     constructor(path = ':memory:') {
-        this.db = openBetterSqlite(path);
+        this.db = new DatabaseSync(path);
     }
     exec(sql, params = []) {
         this.db.prepare(sql).run(...coerceParams(params));
@@ -100,12 +43,7 @@ export class NodeClientDatabase {
     transaction(fn) {
         return runTransaction(this.#tx, (sql) => this.db.exec(sql), fn);
     }
-    /**
-     * §5.3 image import: better-sqlite3 (like bun:sqlite) attaches files, not
-     * buffers, so the image lands in a private temp file for the duration of
-     * the ATTACH. Must be called outside any open transaction (SQLite cannot
-     * ATTACH inside one).
-     */
+    /** §5.3 image import through a private file attached for one callback. */
     withSqliteImage(bytes, alias, fn) {
         assertImageAlias(alias);
         const dir = mkdtempSync(join(tmpdir(), 'syncular-image-'));

package/dist/query-guard.d.ts

@@ -10,8 +10,8 @@
  *      bypasses the outbox (SPEC §7.1) and silently diverges from the
  *      server — writes MUST go through `client.mutate([...])`.
  *   2. ONE STATEMENT. `sqlite-wasm`'s `exec` runs every statement in a
- *      multi-statement string (`SELECT 1; DROP TABLE t`), while bun:sqlite /
- *      better-sqlite3 prepare only the first. We unify on the strict
+ *      multi-statement string (`SELECT 1; DROP TABLE t`), while the native
+ *      SQLite adapters prepare only the first. We unify on the strict
  *      behaviour: exactly one statement per `query()`.
  *
  * The guard only fronts the PUBLIC `client.query()` — engine-internal reads

package/dist/query-guard.js

@@ -10,8 +10,8 @@
  *      bypasses the outbox (SPEC §7.1) and silently diverges from the
  *      server — writes MUST go through `client.mutate([...])`.
  *   2. ONE STATEMENT. `sqlite-wasm`'s `exec` runs every statement in a
- *      multi-statement string (`SELECT 1; DROP TABLE t`), while bun:sqlite /
- *      better-sqlite3 prepare only the first. We unify on the strict
+ *      multi-statement string (`SELECT 1; DROP TABLE t`), while the native
+ *      SQLite adapters prepare only the first. We unify on the strict
  *      behaviour: exactly one statement per `query()`.
  *
  * The guard only fronts the PUBLIC `client.query()` — engine-internal reads

package/dist/remote.d.ts

@@ -18,6 +18,8 @@ export interface SyncRemoteClientConfig {
     readonly operations?: RemoteOperationTransport;
     readonly operationRealtime?: RemoteOperationRealtimeConnector;
     readonly encryption?: EncryptionConfig;
+    /** Acquired partition log epoch for restore-safe ordinary commits (§2.1). */
+    readonly logEpoch?: string;
 }
 export interface RemoteCommitInput {
     /** Stable caller-owned idempotency identity for this logical commit. */

package/dist/remote.js

@@ -2,7 +2,7 @@
  * Database-less SSP2 producer (§6.10). It prepares and sends ordinary commits
  * through the existing push path without creating a local replica or outbox.
  */
-import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeRow, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
+import { decodeMessage, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeMessage, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeRow, } from '@syncular/core';
 import { encryptRowValues } from './encryption.js';
 import { ClientSyncError } from './errors.js';
 import { compileClientSchema, recordToRowValues, } from './schema.js';
@@ -71,10 +71,14 @@ export class SyncRemoteClient {
     #operationSocketGeneration = 0;
     #watches = new Map();
     #encryption;
+    #logEpoch;
     constructor(config) {
         if (config.clientId.length === 0) {
             throw invalid('SyncRemoteClient clientId must be non-empty');
         }
+        if (config.logEpoch !== undefined && config.logEpoch.length === 0) {
+            throw invalid('SyncRemoteClient logEpoch must be non-empty');
+        }
         this.#schema =
             config.schema === undefined
                 ? undefined
@@ -84,6 +88,7 @@ export class SyncRemoteClient {
         this.#operations = config.operations;
         this.#operationRealtime = config.operationRealtime;
         this.#encryption = config.encryption;
+        this.#logEpoch = config.logEpoch;
     }
     async prepareCommit(input) {
         const schema = this.#schema;
@@ -137,13 +142,16 @@ export class SyncRemoteClient {
         return {
             requestId: input.requestId,
             bytes: encodeMessage({
-                wireVersion: PROTOCOL_WIRE_VERSION,
+                wireVersion: this.#logEpoch === undefined ? 1 : 2,
                 msgKind: 'request',
                 frames: [
                     {
                         type: 'REQ_HEADER',
                         clientId: this.#clientId,
                         schemaVersion: schema.version,
+                        ...(this.#logEpoch !== undefined
+                            ? { logEpoch: this.#logEpoch }
+                            : {}),
                     },
                     {
                         type: 'PUSH_COMMIT',

package/dist/sqlite-bun.d.ts

@@ -0,0 +1,2 @@
+import type { ClientDatabase } from './database.js';
+export declare function openSqliteDatabase(path?: string): ClientDatabase;

package/dist/sqlite-bun.js

@@ -0,0 +1,4 @@
+import { openBunDatabase } from './bun-database.js';
+export function openSqliteDatabase(path = ':memory:') {
+    return openBunDatabase(path);
+}

package/dist/sqlite-node.d.ts

@@ -0,0 +1,2 @@
+import type { ClientDatabase } from './database.js';
+export declare function openSqliteDatabase(path?: string): ClientDatabase;

package/dist/sqlite-node.js

@@ -0,0 +1,4 @@
+import { openNodeDatabase } from './node-database.js';
+export function openSqliteDatabase(path = ':memory:') {
+    return openNodeDatabase(path);
+}

package/dist/sync-scheduler.d.ts

@@ -0,0 +1,23 @@
+import type { WakeReason } from '@syncular/core';
+import type { SecurityLifecycle } from './client.js';
+import type { SyncIntent } from './invalidation.js';
+export interface SyncSchedulerClient {
+    readonly syncNeeded: boolean;
+    readonly securityLifecycle: SecurityLifecycle;
+    syncUntilIdle(maxRounds?: number): Promise<unknown>;
+    onSyncNeeded(listener: (reason: 'startup' | 'hello' | WakeReason) => void): () => void;
+    onSyncIntent(listener: (intent: SyncIntent) => void): () => void;
+}
+export interface SyncSchedulerOptions {
+    readonly maxRounds?: number;
+    readonly onError?: (error: unknown) => void;
+    readonly now?: () => number;
+    readonly queueMicrotask?: (callback: () => void) => void;
+    readonly schedule?: (callback: () => void, delayMs: number) => () => void;
+}
+export interface SyncScheduler {
+    readonly stopped: boolean;
+    stop(): void;
+}
+/** Install the event-driven single-flight host loop for a direct client. */
+export declare function installSyncScheduler(client: SyncSchedulerClient, options?: SyncSchedulerOptions): SyncScheduler;

package/dist/sync-scheduler.js

@@ -0,0 +1,122 @@
+/** Install the event-driven single-flight host loop for a direct client. */
+export function installSyncScheduler(client, options = {}) {
+    const now = options.now ?? Date.now;
+    const enqueue = options.queueMicrotask ?? globalThis.queueMicrotask;
+    const schedule = options.schedule ??
+        ((callback, delayMs) => {
+            const timer = globalThis.setTimeout(callback, delayMs);
+            return () => globalThis.clearTimeout(timer);
+        });
+    let stopped = false;
+    let running = false;
+    let immediatePending = false;
+    let immediateQueued = false;
+    let backgroundReady = false;
+    let backgroundDue = Number.POSITIVE_INFINITY;
+    let cancelBackground;
+    const report = (error) => {
+        if (options.onError !== undefined) {
+            options.onError(error);
+            return;
+        }
+        const root = globalThis;
+        if (root.reportError !== undefined)
+            root.reportError(error);
+        else
+            console.error(error);
+    };
+    const clearBackground = () => {
+        cancelBackground?.();
+        cancelBackground = undefined;
+        backgroundReady = false;
+        backgroundDue = Number.POSITIVE_INFINITY;
+    };
+    const queueImmediate = () => {
+        immediatePending = true;
+        if (stopped || running || immediateQueued)
+            return;
+        immediateQueued = true;
+        enqueue(() => {
+            immediateQueued = false;
+            if (stopped || !immediatePending)
+                return;
+            immediatePending = false;
+            run();
+        });
+    };
+    const run = () => {
+        if (stopped || running)
+            return;
+        if (client.securityLifecycle === 'preflight') {
+            immediatePending = false;
+            return;
+        }
+        running = true;
+        backgroundReady = false;
+        void client
+            .syncUntilIdle(options.maxRounds)
+            .catch((error) => {
+            if (!stopped)
+                report(error);
+        })
+            .finally(() => {
+            running = false;
+            if (stopped)
+                return;
+            if (immediatePending || backgroundReady) {
+                queueImmediate();
+                return;
+            }
+            if (cancelBackground !== undefined && backgroundDue <= now()) {
+                clearBackground();
+                queueImmediate();
+            }
+        });
+    };
+    const consume = (intent) => {
+        if (stopped)
+            return;
+        if (intent.kind === 'none') {
+            clearBackground();
+            immediatePending = false;
+            return;
+        }
+        if (intent.kind === 'interactive') {
+            clearBackground();
+            queueImmediate();
+            return;
+        }
+        if (immediatePending || immediateQueued)
+            return;
+        clearBackground();
+        backgroundDue = now() + Math.max(0, intent.delayMs);
+        cancelBackground = schedule(() => {
+            cancelBackground = undefined;
+            backgroundDue = Number.POSITIVE_INFINITY;
+            backgroundReady = true;
+            if (!running)
+                queueImmediate();
+        }, Math.max(0, intent.delayMs));
+    };
+    const unsubscribeNeeded = client.onSyncNeeded(() => {
+        consume({ kind: 'interactive' });
+    });
+    const unsubscribeIntent = client.onSyncIntent(consume);
+    if (client.syncNeeded && client.securityLifecycle === 'active') {
+        consume({ kind: 'interactive' });
+    }
+    return {
+        get stopped() {
+            return stopped;
+        },
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            clearBackground();
+            immediatePending = false;
+            unsubscribeNeeded();
+            unsubscribeIntent();
+        },
+    };
+}

package/dist/window.d.ts

@@ -14,6 +14,11 @@
  */
 import { type ScopeMap } from '@syncular/core';
 import type { ClientDatabase } from './database.js';
+export type TimeBucketUnit = 'month';
+/** Derive the immutable UTC scope value stored when a row is created. */
+export declare function creationTimeBucket(createdAtMs: number, unit: TimeBucketUnit): string;
+/** Return a rolling UTC month window ordered from oldest to newest. */
+export declare function last(count: number, unit: TimeBucketUnit, nowMs?: number): string[];
 /**
  * A window base: one table, one variable whose values are the window
  * units, and any FIXED scopes every unit shares (other variables pinned

package/dist/window.js

@@ -13,6 +13,45 @@
  * transaction and the invalidation choke point.
  */
 import { canonicalScopeJson } from '@syncular/core';
+import { ClientSyncError } from './errors.js';
+const MAX_TIME_BUCKET_MS = 253_402_300_799_999;
+function monthBucket(year, month) {
+    return `${year.toString().padStart(4, '0')}-${month.toString().padStart(2, '0')}`;
+}
+/** Derive the immutable UTC scope value stored when a row is created. */
+export function creationTimeBucket(createdAtMs, unit) {
+    if (unit !== 'month' ||
+        !Number.isSafeInteger(createdAtMs) ||
+        createdAtMs < 0 ||
+        createdAtMs > MAX_TIME_BUCKET_MS) {
+        throw new ClientSyncError('sync.invalid_request', 'creationTimeBucket requires a supported unit and a UTC timestamp from 1970 through 9999');
+    }
+    const date = new Date(createdAtMs);
+    return monthBucket(date.getUTCFullYear(), date.getUTCMonth() + 1);
+}
+/** Return a rolling UTC month window ordered from oldest to newest. */
+export function last(count, unit, nowMs = Date.now()) {
+    if (unit !== 'month' ||
+        !Number.isSafeInteger(count) ||
+        count < 1 ||
+        count > 1_200 ||
+        !Number.isSafeInteger(nowMs) ||
+        nowMs < 0 ||
+        nowMs > MAX_TIME_BUCKET_MS) {
+        throw new ClientSyncError('sync.invalid_request', 'last requires a supported unit, a count from 1 through 1200, and a UTC timestamp from 1970 through 9999');
+    }
+    const date = new Date(nowMs);
+    const current = date.getUTCFullYear() * 12 + date.getUTCMonth();
+    if (current - (count - 1) < 1970 * 12) {
+        throw new ClientSyncError('sync.invalid_request', 'last requires every returned UTC month to fall from 1970 through 9999');
+    }
+    const units = [];
+    for (let offset = count - 1; offset >= 0; offset -= 1) {
+        const value = current - offset;
+        units.push(monthBucket(Math.floor(value / 12), (value % 12) + 1));
+    }
+    return units;
+}
 /**
  * A stable, server-opaque key for a window base — table + variable +
  * canonical fixed scopes. Two `setWindow` calls with the same base

package/dist/worker-entry.js

@@ -147,9 +147,6 @@ export function startSyncWorker(overrides = {}) {
         autoSyncScheduled = true;
         queueMicrotask(runAutoSync);
     }
-    function consumeEffects(effects) {
-        consumeSyncIntent(effects.sync);
-    }
     function requireClient() {
         if (client === undefined) {
             throw new ClientSyncError(WORKER_FAILED_CODE, 'the worker received a call before init completed');
@@ -304,20 +301,16 @@ export function startSyncWorker(overrides = {}) {
         subscribe: (input) => requireClient().subscribe(input),
         unsubscribe: (id) => requireClient().unsubscribe(id),
         setWindow: async (base, units) => {
-            const result = await requireClient().setWindowCommand(base, units);
-            consumeEffects(result.effects);
+            await requireClient().setWindowCommand(base, units);
         },
         windowState: (base) => requireClient().windowState(base),
         mutate: (mutations) => {
-            const result = requireClient().mutateCommand(mutations);
-            consumeEffects(result.effects);
-            return result.value;
+            return requireClient().mutateCommand(mutations).value;
         },
         patch: (table, rowId, partial, options) => {
             // Same §8.4 rule as `mutate`: a local write must push without the app
             // orchestrating sync, so consume the core's immediate intent.
             const result = requireClient().patchCommand(table, rowId, partial, options);
-            consumeEffects(result.effects);
             return result.value;
         },
         purgeLocalData: (input) => requireClient().purgeLocalData(input),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.46",
+  "version": "0.15.48",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -58,6 +58,14 @@
         "default": "./dist/node-database.js"
       }
     },
+    "./sqlite": {
+      "bun": "./src/sqlite-bun.ts",
+      "node": {
+        "types": "./dist/sqlite-node.d.ts",
+        "default": "./dist/sqlite-node.js"
+      },
+      "types": "./dist/sqlite-node.d.ts"
+    },
     "./wasm": {
       "bun": "./src/wasm-database.ts",
       "browser": "./dist/wasm-database.js",
@@ -85,23 +93,13 @@
     "!dist/**/*.test.d.ts"
   ],
   "scripts": {
-    "verify:node": "bun build ./test/node-database/verify-node.mjs --target=node --external better-sqlite3 --outfile=./.verify-node.built.mjs && node ./.verify-node.built.mjs"
+    "verify:node": "bun build ./test/node-database/verify-node.mjs --target=node --outfile=./.verify-node.built.mjs && node ./.verify-node.built.mjs"
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.46"
-  },
-  "peerDependencies": {
-    "better-sqlite3": ">=11"
-  },
-  "peerDependenciesMeta": {
-    "better-sqlite3": {
-      "optional": true
-    }
+    "@syncular/core": "0.15.48"
   },
   "devDependencies": {
-    "@syncular/server": "0.15.46",
-    "@types/better-sqlite3": "^7.6.13",
-    "better-sqlite3": "^12.11.1"
+    "@syncular/server": "0.15.48"
   }
 }

package/src/bun-database.ts

@@ -15,6 +15,12 @@ import {
   type SqlValue,
 } from './database';
 
+declare module 'bun:sqlite' {
+  interface Database {
+    clearQueryCache(): void;
+  }
+}
+
 type BunParam = string | number | bigint | Uint8Array | null;
 
 function coerceParams(params: readonly SqlValue[]): BunParam[] {
@@ -34,6 +40,11 @@ export class BunClientDatabase implements ClientDatabase {
 
   exec(sql: string, params: readonly SqlValue[] = []): void {
     this.db.query(sql).run(...coerceParams(params));
+    // `Database.query()` caches prepared statements. Clear that cache after
+    // schema DDL so a reset does not reprepare every later row upsert.
+    if (/^\s*(?:CREATE|DROP|ALTER)\b/i.test(sql)) {
+      this.db.clearQueryCache();
+    }
   }
 
   query(sql: string, params: readonly SqlValue[] = []): SqlRow[] {