@syncular/client 0.1.2 → 0.2.0

package/dist/wasm-database.d.ts

@@ -0,0 +1,30 @@
+import { type ClientDatabase } from './database.js';
+/**
+ * EXPLICIT ephemeral mode: an in-memory sqlite-wasm database. For tests,
+ * demos and SSR only — nothing persists. The persistent mode is
+ * `openPersistentWasmDatabase` inside a worker; there is no fallback from
+ * one to the other (Direction decision 2).
+ */
+export declare function openWasmDatabase(): Promise<ClientDatabase>;
+export interface PersistentWasmDatabaseOptions {
+    /**
+     * OPFS directory holding this database's SAH pool (default
+     * `.syncular/<name>`). One pool per concurrent user: the sahpool VFS
+     * forbids two live instances on the same directory, so two cores on one
+     * origin (e.g. the demo's two panes) need distinct names/directories.
+     */
+    readonly directory?: string;
+    /** Initial SAH pool capacity (sqlite-wasm default: 6). */
+    readonly initialCapacity?: number;
+}
+/**
+ * THE persistent browser mode: a named database on OPFS via the
+ * `opfs-sahpool` VFS. Worker-context only — not because SAHPool requires
+ * it (it uses `FileSystemSyncAccessHandle`, no `Atomics.wait`, and could
+ * technically run on the main thread), but because the persistent mode IS
+ * whole-core-in-a-worker (REVISE Direction decision 2, 2026-07-03) and
+ * this factory enforces that decision. No COOP/COEP headers required.
+ *
+ * Support floor: no OPFS → a loud `ClientSyncError`, never a fallback.
+ */
+export declare function openPersistentWasmDatabase(name: string, options?: PersistentWasmDatabaseOptions): Promise<ClientDatabase>;

package/dist/wasm-database.js

@@ -0,0 +1,170 @@
+/**
+ * `ClientDatabase` on @sqlite.org/sqlite-wasm (Direction decision 2,
+ * 2026-07-03). Two modes, no ladder between them:
+ *
+ * - `openPersistentWasmDatabase(name)` — THE persistent browser mode:
+ *   OPFS via the `opfs-sahpool` VFS, restricted to Web Worker contexts
+ *   because the whole client core runs in a worker by design. SAHPool
+ *   needs **no COOP/COEP headers and no SharedArrayBuffer** (it is built
+ *   on `FileSystemSyncAccessHandle`, not the Atomics-based `opfs` VFS
+ *   proxy — the COOP/COEP requirement documented by sqlite-wasm applies
+ *   only to `oo1.OpfsDb`, which this binding no longer uses). Browsers
+ *   without OPFS are unsupported (support floor ~2023+): the factory
+ *   fails loud. Never IndexedDB, never a silent in-memory fallback.
+ * - `openWasmDatabase()` — EXPLICIT ephemeral: an in-memory database for
+ *   tests, demos and SSR. Nothing survives a reload, on purpose.
+ *
+ * A thin binding over the sqlite3 `oo1` API: opening is async (wasm
+ * init), everything after is synchronous like every other
+ * `ClientDatabase`. Browser-only — exercised by the demo, never imported
+ * by bun tests (subpath export `@syncular/client/wasm`).
+ */
+import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
+import { assertImageAlias, runTransaction, } from './database.js';
+import { ClientSyncError } from './errors.js';
+function coerceParams(params) {
+    return params.map((value) => {
+        if (typeof value === 'boolean')
+            return value ? 1 : 0;
+        return value;
+    });
+}
+class WasmClientDatabase {
+    #db;
+    #sqlite3;
+    #tx = { depth: 0 };
+    constructor(db, sqlite3) {
+        this.#db = db;
+        this.#sqlite3 = sqlite3;
+    }
+    exec(sql, params = []) {
+        this.#db.exec({
+            sql,
+            ...(params.length > 0 ? { bind: coerceParams(params) } : {}),
+            rowMode: 'object',
+            resultRows: [],
+        });
+    }
+    query(sql, params = []) {
+        const resultRows = [];
+        this.#db.exec({
+            sql,
+            ...(params.length > 0 ? { bind: coerceParams(params) } : {}),
+            rowMode: 'object',
+            resultRows,
+        });
+        return resultRows;
+    }
+    transaction(fn) {
+        return runTransaction(this.#tx, (sql) => this.exec(sql), fn);
+    }
+    /**
+     * §5.3 image import at near-file-copy speed: attach an empty in-memory
+     * schema, then `sqlite3_deserialize` the image bytes into it (the
+     * documented sqlite-wasm import path — no OPFS round-trip, no SQL-level
+     * row shuttling before the single INSERT…SELECT the caller runs).
+     */
+    withSqliteImage(bytes, alias, fn) {
+        assertImageAlias(alias);
+        const pointer = this.#db.pointer;
+        if (pointer === undefined) {
+            throw new ClientSyncError('sync.invalid_request', 'sqlite-wasm database exposes no native handle for image import');
+        }
+        const { capi, wasm } = this.#sqlite3;
+        this.exec(`ATTACH ':memory:' AS ${alias}`);
+        try {
+            const data = wasm.allocFromTypedArray(bytes);
+            const rc = capi.sqlite3_deserialize(pointer, alias, data, bytes.length, bytes.length, 
+            // FREEONCLOSE: sqlite owns the allocation; READONLY: images are
+            // immutable inputs (§5.1).
+            capi.SQLITE_DESERIALIZE_FREEONCLOSE | capi.SQLITE_DESERIALIZE_READONLY);
+            if (rc !== 0) {
+                throw new ClientSyncError('sync.invalid_request', `sqlite3_deserialize failed with code ${rc} (§5.3)`);
+            }
+            return fn();
+        }
+        finally {
+            this.exec(`DETACH ${alias}`);
+        }
+    }
+    close() {
+        this.#db.close();
+    }
+}
+let sqlite3Init;
+function initSqlite3() {
+    if (sqlite3Init === undefined) {
+        const init = sqlite3InitModule;
+        sqlite3Init = init({
+            print: () => { },
+            printErr: () => { },
+        });
+    }
+    return sqlite3Init;
+}
+/**
+ * EXPLICIT ephemeral mode: an in-memory sqlite-wasm database. For tests,
+ * demos and SSR only — nothing persists. The persistent mode is
+ * `openPersistentWasmDatabase` inside a worker; there is no fallback from
+ * one to the other (Direction decision 2).
+ */
+export async function openWasmDatabase() {
+    const sqlite3 = await initSqlite3();
+    return new WasmClientDatabase(new sqlite3.oo1.DB(':memory:', 'c'), sqlite3);
+}
+function inWorkerContext() {
+    const scope = globalThis;
+    return (typeof scope.WorkerGlobalScope === 'function' &&
+        globalThis instanceof scope.WorkerGlobalScope);
+}
+/** One registered VFS per pool directory, reused across opens. */
+const sahPools = new Map();
+/**
+ * THE persistent browser mode: a named database on OPFS via the
+ * `opfs-sahpool` VFS. Worker-context only — not because SAHPool requires
+ * it (it uses `FileSystemSyncAccessHandle`, no `Atomics.wait`, and could
+ * technically run on the main thread), but because the persistent mode IS
+ * whole-core-in-a-worker (REVISE Direction decision 2, 2026-07-03) and
+ * this factory enforces that decision. No COOP/COEP headers required.
+ *
+ * Support floor: no OPFS → a loud `ClientSyncError`, never a fallback.
+ */
+export async function openPersistentWasmDatabase(name, options) {
+    if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+        throw new ClientSyncError('sync.invalid_request', `invalid persistent database name ${JSON.stringify(name)}`);
+    }
+    if (!inWorkerContext()) {
+        throw new ClientSyncError('sync.invalid_request', 'openPersistentWasmDatabase() must run inside a Web Worker: the ' +
+            'persistent mode is whole-core-in-a-worker by design (Direction ' +
+            'decision 2, 2026-07-03). Use the worker handle from the main ' +
+            'thread, or openWasmDatabase() for explicitly ephemeral state.');
+    }
+    const storage = globalThis.navigator?.storage;
+    if (typeof storage?.getDirectory !== 'function') {
+        throw new ClientSyncError('sync.invalid_request', 'OPFS is unavailable in this browser — the syncular support floor ' +
+            'requires OPFS (~2023+ browsers). There is no IndexedDB or ' +
+            'in-memory fallback for persistent mode.');
+    }
+    const sqlite3 = await initSqlite3();
+    const directory = options?.directory ?? `.syncular/${name}`;
+    let pool = sahPools.get(directory);
+    if (pool === undefined) {
+        pool = sqlite3
+            .installOpfsSAHPoolVfs({
+            // VFS registration names must be unique per directory.
+            name: `syncular-sahpool-${directory.replace(/[^A-Za-z0-9]+/g, '-')}`,
+            directory,
+            ...(options?.initialCapacity !== undefined
+                ? { initialCapacity: options.initialCapacity }
+                : {}),
+        })
+            .catch((error) => {
+            sahPools.delete(directory);
+            throw new ClientSyncError('sync.invalid_request', 'opfs-sahpool VFS failed to initialize (is OPFS available, and ' +
+                `is another live instance using directory ${JSON.stringify(directory)}?): ${String(error)}`);
+        });
+        sahPools.set(directory, pool);
+    }
+    const util = await pool;
+    return new WasmClientDatabase(new util.OpfsSAHPoolDb(`/${name}.db`), sqlite3);
+}

package/dist/window.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Windowed subscriptions (SPEC.md §4.8 / DESIGN-eviction.md W1).
+ *
+ * A window is a partial local replica keyed by scope VALUES: the client
+ * holds rows for a chosen set of units (one scope value each) of a window
+ * BASE (a table + one scope variable + the fixed remainder of the scope
+ * map). Windowing is a set-difference on §4 subscriptions — never a
+ * mutation of one — so it needs zero wire or server changes.
+ *
+ * This module owns the registry bookkeeping and the deterministic
+ * per-unit subscription-id derivation (§4.1 guidance). The eviction that
+ * fuses with a shrink (E1–E4) lives on the client, which holds the DB
+ * transaction and the invalidation choke point.
+ */
+import { type ScopeMap } from '@syncular/core';
+import type { ClientDatabase } from './database.js';
+/**
+ * A window base: one table, one variable whose values are the window
+ * units, and any FIXED scopes every unit shares (other variables pinned
+ * to a constant set). `params` is host-opaque, carried onto every unit's
+ * subscription verbatim.
+ */
+export interface WindowBase {
+    readonly table: string;
+    /** The scope variable whose values are the window units. */
+    readonly variable: string;
+    /** Scopes shared by every unit (other variables), if any. */
+    readonly fixedScopes?: ScopeMap;
+    readonly params?: string;
+}
+/** A live unit in the registry: its value and the subscription it drives. */
+export interface WindowUnit {
+    readonly unit: string;
+    readonly subId: string;
+}
+/**
+ * A stable, server-opaque key for a window base — table + variable +
+ * canonical fixed scopes. Two `setWindow` calls with the same base
+ * address the same registry rows.
+ */
+export declare function windowBaseKey(base: WindowBase): string;
+/** The full requested scope map for one unit (fixed scopes + the unit). */
+export declare function unitScopes(base: WindowBase, unit: string): ScopeMap;
+/**
+ * Deterministic per-unit subscription id (§4.1 guidance):
+ * `w:<table>:<sha256(canonical scope map, §11.2)[0..16]>`. Ids are echoed
+ * not interpreted by the server (§4.1), so the exact hash is pure client
+ * convention; SHA-256 matches the SPEC's worked example.
+ */
+export declare function deriveSubId(base: WindowBase, unit: string): Promise<string>;
+/** Live units for a base, ordered by unit value. */
+export declare function loadWindowUnits(db: ClientDatabase, baseKey: string): WindowUnit[];
+export declare function insertWindowUnit(db: ClientDatabase, baseKey: string, unit: string, subId: string): void;
+export declare function deleteWindowUnit(db: ClientDatabase, baseKey: string, unit: string): void;
+/** Is a single scope value windowed-in for this base? (the oracle, I3) */
+export declare function isUnitLive(db: ClientDatabase, baseKey: string, unit: string): boolean;
+export interface PendingEviction {
+    readonly subId: string;
+    readonly table: string;
+    readonly effective: ScopeMap;
+}
+export declare function savePendingEviction(db: ClientDatabase, subId: string, table: string, effective: ScopeMap): void;
+export declare function deletePendingEviction(db: ClientDatabase, subId: string): void;
+export declare function loadPendingEvictions(db: ClientDatabase): PendingEviction[];

package/dist/worker-entry.d.ts

@@ -1,2 +1,16 @@
-export {};
-//# sourceMappingURL=worker-entry.d.ts.map
+import type { ClientDatabase } from './database.js';
+import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
+import { type WorkerInitConfig } from './worker-protocol.js';
+export interface SyncWorkerOverrides {
+    /** Database factory indirection: tests inject bun:sqlite here. */
+    readonly openDatabase?: (config: WorkerInitConfig) => Promise<ClientDatabase> | ClientDatabase;
+    readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
+    readonly createSegments?: (config: WorkerInitConfig) => SegmentDownloader | undefined;
+    readonly createRealtime?: (config: WorkerInitConfig, clientId: string) => RealtimeConnector | undefined;
+}
+/**
+ * Register the RPC server on the current worker scope. Call this once
+ * from a worker entry script; the main-thread handle drives everything
+ * else through `init`/`call` messages.
+ */
+export declare function startSyncWorker(overrides?: SyncWorkerOverrides): void;