@syncular/client 0.1.2 → 0.2.0

package/dist/worker-protocol.d.ts

@@ -1,64 +1,176 @@
-import type { SyncularGeneratedWorkerRequest } from './generated-bridge';
-import type { SyncularBootstrapStatus, SyncularDiagnosticEvent, SyncularErrorCategory, SyncularErrorCode, SyncularErrorRecommendedAction, SyncularLiveQueryEvent, SyncularRealtimeConnectionState, SyncularRowsChangedEvent } from './types';
-export declare const SYNCULAR_WORKER_PROTOCOL_VERSION = 2;
-export interface SyncularWorkerErrorPayload {
-    code: SyncularErrorCode;
-    message: string;
-    category?: SyncularErrorCategory;
-    retryable?: boolean;
-    recommendedAction?: SyncularErrorRecommendedAction;
-    name?: string;
-    stack?: string;
-    details?: unknown;
+/**
+ * The worker RPC protocol (Direction decision 2, 2026-07-03): the whole
+ * client core runs in a Web Worker; the UI thread talks to it through
+ * this thin, multiplexed postMessage protocol. Exactly SIX message types
+ * (`init`, `call`, `ready`, `result`, `error`, `event`) — every logical
+ * API method multiplexes over `call`, every notification over `event`.
+ *
+ * Both sides derive their typing from ONE shared shape: `WorkerApi`.
+ * The worker implements it (`worker-entry.ts`); the handle projects it
+ * to promises (`worker-host.ts`). Everything crossing the boundary is
+ * structured-clone data — no functions, no class instances.
+ *
+ * Scheduling note (SPEC §8.4): the sync-needed signal is host-driven,
+ * and in worker mode the HOST LOOP LIVES IN THE WORKER — wake-ups
+ * coalesce into jittered `syncUntilIdle` rounds there (`autoSync`),
+ * so the UI thread never has to react to keep data flowing. Events are
+ * still forwarded to the handle for visibility.
+ */
+import type { WakeReason } from '@syncular/core';
+import type { BlobRef, CachedBlob } from './blob.js';
+import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { SqlRow, SqlValue } from './database.js';
+import type { InvalidationEvent } from './invalidation.js';
+import type { OutboxCommit } from './outbox.js';
+import type { ClientSchema } from './schema.js';
+import type { SubscriptionRecord } from './state.js';
+import type { WindowBase } from './window.js';
+/** The handle exists but this tab lost the leader election (TODO 3.2). */
+export declare const NOT_LEADER_CODE = "client.not_leader";
+/** The worker (or its RPC channel) failed outside protocol semantics. */
+export declare const WORKER_FAILED_CODE = "client.worker_failed";
+export type WorkerDatabaseInit = {
+    /** THE persistent mode: opfs-sahpool, named database. */
+    readonly mode: 'persistent';
+    readonly name: string;
+    /** Optional pool directory override (default `.syncular/<name>`). */
+    readonly directory?: string;
+} | {
+    /**
+     * Bootstrap-provided database (tests inject bun:sqlite here). The
+     * worker entry MUST have an `openDatabase` override or init fails.
+     */
+    readonly mode: 'custom';
+    readonly options?: unknown;
+};
+export interface WorkerEndpoints {
+    /** POST target for SSP2 sync rounds (§1.1). */
+    readonly syncUrl: string;
+    /** Segment download base URL; omit when segments are not served. */
+    readonly segmentsUrl?: string;
+    /** Blob upload/download base URL (§5.9); omit when blobs are unused. */
+    readonly blobsUrl?: string;
+    /**
+     * WebSocket URL for §8 realtime. The literal placeholder `{clientId}`
+     * is substituted with the (possibly persisted) client id after start.
+     */
+    readonly realtimeUrl?: string;
 }
-export declare function createSyncularWorkerErrorPayload(code: SyncularErrorCode, message?: string, options?: {
-    name?: string;
-    stack?: string;
-    details?: unknown;
-}): SyncularWorkerErrorPayload;
-export type { SyncularWorkerRealtimeOptions, SyncularWorkerRuntimeArtifact, } from './generated-bridge';
-export type SyncularWorkerRequest = SyncularGeneratedWorkerRequest;
-interface SyncularWorkerResponseBase {
-    id: number;
-    protocolVersion: typeof SYNCULAR_WORKER_PROTOCOL_VERSION;
+export interface WorkerInitConfig {
+    readonly schema: ClientSchema;
+    readonly database: WorkerDatabaseInit;
+    readonly endpoints: WorkerEndpoints;
+    readonly clientId?: string;
+    readonly limits?: SyncClientLimits;
+    /**
+     * Worker-side host loop (§8.4): coalesce wake-ups into jittered
+     * `syncUntilIdle` rounds inside the worker. Default true.
+     */
+    readonly autoSync?: boolean;
+    /** Max jitter before a coalesced auto-sync round (default 200 ms). */
+    readonly wakeJitterMs?: number;
 }
-interface SyncularWorkerEventBase {
-    protocolVersion: typeof SYNCULAR_WORKER_PROTOCOL_VERSION;
+/** Successful init reply. */
+export interface WorkerInitResult {
+    readonly clientId: string;
 }
-export type SyncularWorkerResponse = (SyncularWorkerResponseBase & {
-    ok: true;
-    value?: unknown;
-}) | (SyncularWorkerResponseBase & {
-    ok: false;
-    error: SyncularWorkerErrorPayload;
-});
-export type SyncularWorkerEvent = (SyncularWorkerEventBase & {
-    type: 'liveQueryEvents';
-    events: Array<SyncularLiveQueryEvent<Record<string, unknown>>>;
-}) | (SyncularWorkerEventBase & SyncularRowsChangedEvent & {
-    type: 'rowsChanged';
-}) | (SyncularWorkerEventBase & {
-    type: 'bootstrapChanged';
-    bootstrap: SyncularBootstrapStatus;
-}) | (SyncularWorkerEventBase & {
-    type: 'realtimeState';
-    state: SyncularRealtimeConnectionState;
-}) | (SyncularWorkerEventBase & {
-    type: 'presenceEvent';
-    action: 'join' | 'leave' | 'update' | 'snapshot';
-    scopeKey: string;
-    clientId?: string;
-    actorId?: string;
-    metadata?: Record<string, unknown>;
-    entries?: Array<{
-        clientId: string;
-        actorId: string;
-        joinedAt: number;
-        metadata?: Record<string, unknown>;
-    }>;
-}) | (SyncularWorkerEventBase & {
-    type: 'diagnostic';
-    event: SyncularDiagnosticEvent;
-});
-export type SyncularWorkerOutboundMessage = SyncularWorkerResponse | SyncularWorkerEvent;
-//# sourceMappingURL=worker-protocol.d.ts.map
+export interface WorkerApi {
+    subscribe(input: SubscribeInput): void;
+    unsubscribe(id: string): void;
+    /** §4.8 windowed subscriptions: set the live units for a window base. */
+    setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
+    /** §4.8 completeness oracle (I3): the windowed-in units for a base. */
+    windowState(base: WindowBase): WindowState;
+    mutate(mutations: readonly MutationInput[]): string;
+    sync(): Promise<SyncSummary>;
+    syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
+    query(sql: string, params?: readonly SqlValue[]): SqlRow[];
+    conflicts(): readonly ConflictRecord[];
+    rejections(): readonly RejectionRecord[];
+    schemaFloor(): SchemaFloor | undefined;
+    /** §7.3.5: the opaque auth-lease state, or undefined. */
+    leaseState(): LeaseState | undefined;
+    /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
+    upgrading(): boolean;
+    syncNeeded(): boolean;
+    pendingCommits(): OutboxCommit[];
+    subscriptions(): SubscriptionRecord[];
+    subscription(id: string): SubscriptionRecord | undefined;
+    connectRealtime(): Promise<void>;
+    disconnectRealtime(): void;
+    /** §8.6 presence: publish/clear a scope-keyed presence document. */
+    setPresence(scopeKey: string, doc: Record<string, unknown> | null): void;
+    /** §8.6 presence: the peers currently present on a scope key. */
+    presence(scopeKey: string): readonly PresencePeer[];
+    /** §5.9 blobs: stage bytes (returns the canonical ref) / resolve bytes. */
+    uploadBlob(bytes: Uint8Array, options?: {
+        readonly mediaType?: string;
+        readonly name?: string;
+    }): Promise<BlobRef>;
+    fetchBlob(blobIdOrRef: string): Promise<CachedBlob>;
+    /** Sever/restore the transport + realtime (offline simulation, demos). */
+    setOffline(offline: boolean): void;
+    close(): Promise<void>;
+}
+export type WorkerMethod = keyof WorkerApi;
+/** `call` for method M, with args typed straight off `WorkerApi`. */
+export type WorkerCallMessage = {
+    [M in WorkerMethod]: {
+        readonly t: 'call';
+        readonly id: number;
+        readonly method: M;
+        readonly args: Parameters<WorkerApi[M]>;
+    };
+}[WorkerMethod];
+export type MainToWorkerMessage = {
+    readonly t: 'init';
+    readonly id: number;
+    readonly config: WorkerInitConfig;
+} | WorkerCallMessage;
+export interface WorkerErrorShape {
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+}
+export type SyncWorkerEvent = {
+    readonly kind: 'sync-needed';
+    readonly reason: 'hello' | WakeReason;
+} | {
+    readonly kind: 'conflict';
+    readonly conflict: ConflictRecord;
+} | {
+    /** An autoSync round finished (or failed) inside the worker. */
+    readonly kind: 'synced';
+    readonly summary?: SyncSummary;
+    readonly error?: WorkerErrorShape;
+} | {
+    /** §7.4.5: the schema-bump `upgrading` state changed in the worker. */
+    readonly kind: 'upgrading';
+    readonly upgrading: boolean;
+} | {
+    /** §8.6: presence on a scope key changed inside the worker. */
+    readonly kind: 'presence';
+    readonly scopeKey: string;
+} | {
+    /**
+     * TODO 3.1 / I1: one coalesced apply-batch invalidation. `Set`s
+     * structured-clone across the worker boundary, so the event crosses
+     * verbatim — the handle re-emits it to `onInvalidate` listeners.
+     */
+    readonly kind: 'invalidate';
+    readonly event: InvalidationEvent;
+};
+export type WorkerToMainMessage = {
+    readonly t: 'ready';
+} | {
+    readonly t: 'result';
+    readonly id: number;
+    readonly value: unknown;
+} | {
+    readonly t: 'error';
+    readonly id: number;
+    readonly error: WorkerErrorShape;
+} | {
+    readonly t: 'event';
+    readonly event: SyncWorkerEvent;
+};

package/dist/worker-protocol.js

@@ -1,16 +1,7 @@
-import { SYNCULAR_ERROR_DEFINITIONS } from '@syncular/core';
-export const SYNCULAR_WORKER_PROTOCOL_VERSION = 2;
-export function createSyncularWorkerErrorPayload(code, message, options = {}) {
-    const definition = SYNCULAR_ERROR_DEFINITIONS[code];
-    return {
-        code,
-        message: message ?? definition.message,
-        category: definition.category,
-        retryable: definition.retryable,
-        recommendedAction: definition.recommendedAction,
-        ...(options.name ? { name: options.name } : {}),
-        ...(options.stack ? { stack: options.stack } : {}),
-        ...(options.details !== undefined ? { details: options.details } : {}),
-    };
-}
-//# sourceMappingURL=worker-protocol.js.map
+// ---------------------------------------------------------------------------
+// Client-local error codes (never wire codes; §10 stays server-owned)
+// ---------------------------------------------------------------------------
+/** The handle exists but this tab lost the leader election (TODO 3.2). */
+export const NOT_LEADER_CODE = 'client.not_leader';
+/** The worker (or its RPC channel) failed outside protocol semantics. */
+export const WORKER_FAILED_CODE = 'client.worker_failed';

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@syncular/client",
-  "version": "0.1.2",
-  "description": "Syncular Rust-owned SQLite browser client with optional React, host bridge, and CRDT adapter subpaths",
+  "version": "0.2.0",
+  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
   "homepage": "https://syncular.dev",
   "repository": {
     "type": "git",
     "url": "https://github.com/syncular/syncular.git",
-    "directory": "packages/client"
+    "directory": "packages/web-client"
   },
   "bugs": {
     "url": "https://github.com/syncular/syncular/issues"
@@ -16,18 +16,15 @@
   "keywords": [
     "sync",
     "offline-first",
+    "realtime",
     "database",
-    "typescript",
-    "rust",
-    "wasm",
-    "sqlite",
-    "kysely"
+    "typescript"
   ],
-  "private": false,
+  "type": "module",
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
-  "type": "module",
   "exports": {
     ".": {
       "bun": "./src/index.ts",
@@ -37,130 +34,66 @@
         "default": "./dist/index.js"
       }
     },
-    "./worker": {
-      "bun": "./src/worker-entry.ts",
-      "browser": "./src/worker-entry.ts",
-      "import": {
-        "types": "./dist/worker-entry.d.ts",
-        "default": "./dist/worker-entry.js"
-      }
-    },
-    "./sentry": {
-      "bun": "./src/sentry.ts",
-      "browser": "./src/sentry.ts",
+    "./bun": {
+      "bun": "./src/bun-database.ts",
+      "browser": "./src/bun-database.ts",
       "import": {
-        "types": "./dist/sentry.d.ts",
-        "default": "./dist/sentry.js"
+        "types": "./dist/bun-database.d.ts",
+        "default": "./dist/bun-database.js"
       }
     },
-    "./react": {
-      "bun": "./src/react/index.ts",
-      "browser": "./src/react/index.ts",
+    "./node": {
+      "bun": "./src/node-database.ts",
+      "browser": "./src/node-database.ts",
       "import": {
-        "types": "./dist/react/index.d.ts",
-        "default": "./dist/react/index.js"
+        "types": "./dist/node-database.d.ts",
+        "default": "./dist/node-database.js"
       }
     },
-    "./tauri": {
-      "bun": "./src/tauri/index.ts",
+    "./wasm": {
+      "bun": "./src/wasm-database.ts",
+      "browser": "./src/wasm-database.ts",
       "import": {
-        "types": "./dist/tauri/index.d.ts",
-        "default": "./dist/tauri/index.js"
+        "types": "./dist/wasm-database.d.ts",
+        "default": "./dist/wasm-database.js"
       }
     },
-    "./react-native": {
-      "bun": "./src/react-native/index.ts",
-      "import": {
-        "types": "./dist/react-native/index.d.ts",
-        "default": "./dist/react-native/index.js"
-      }
-    },
-    "./crdt-yjs": {
-      "bun": "./src/crdt-yjs/index.ts",
-      "browser": "./src/crdt-yjs/index.ts",
+    "./worker": {
+      "bun": "./src/worker-entry.ts",
+      "browser": "./src/worker-entry.ts",
       "import": {
-        "types": "./dist/crdt-yjs/index.d.ts",
-        "default": "./dist/crdt-yjs/index.js"
+        "types": "./dist/worker-entry.d.ts",
+        "default": "./dist/worker-entry.js"
       }
     }
   },
-  "scripts": {
-    "generate:bridge": "bun scripts/generate-bridge.ts",
-    "generate:wasm-types": "bun scripts/generate-wasm-bindings.ts",
-    "test": "bun test src/*.test.ts src/react/*.test.ts src/tauri/*.test.ts src/react-native/*.test.ts src/crdt-yjs/*.test.ts",
-    "test:wasm:auth": "bun run build:wasm:dev && bun test src/__tests__/auth-hono.wasm.test.ts",
-    "test:wasm:hono": "bun run build:wasm:dev && bun test src/__tests__/*-hono.wasm.test.ts",
-    "test:wasm:variants": "bun run build:wasm:core && bun test src/__tests__/variant-core.wasm.test.ts",
-    "tsgo": "tsgo --noEmit",
-    "build:wasm": "bun scripts/build-syncular-wasm.ts --variant full && bun run generate:wasm-types && bun scripts/size-syncular-wasm.ts --check --report ../../.context/wasm-size/syncular-wasm-size.txt",
-    "build:wasm:perf": "bun scripts/build-syncular-wasm.ts --out-dir dist/wasm-perf --variant full-perf --artifact-name full-perf --release-opt-level 3",
-    "build:wasm:core": "bun scripts/build-syncular-wasm.ts --out-dir dist/wasm-core --features web-owned-sqlite-core --variant core",
-    "build:wasm:variants": "bun run build:wasm && bun run build:wasm:perf && bun run build:wasm:core && bun run catalog:wasm && bun run size:wasm:core && bun run size:wasm:perf",
-    "build:wasm:dev": "bun scripts/build-syncular-wasm.ts --dev && bun run generate:wasm-types",
-    "catalog:wasm": "bun scripts/write-syncular-wasm-catalog.ts --artifact dist/wasm-core --artifact dist/wasm --artifact dist/wasm-perf",
-    "size:wasm": "bun scripts/size-syncular-wasm.ts",
-    "size:wasm:check": "bun scripts/size-syncular-wasm.ts --check --attribution --report ../../.context/wasm-size/syncular-wasm-size.txt",
-    "size:wasm:core": "bun scripts/size-syncular-wasm.ts --wasm dist/wasm-core/syncular_bg.wasm --report ../../.context/wasm-size/syncular-wasm-core-size.txt",
-    "size:wasm:perf": "bun scripts/size-syncular-wasm.ts --wasm dist/wasm-perf/syncular_bg.wasm --report ../../.context/wasm-size/syncular-wasm-perf-size.txt",
-    "build": "bun run build:wasm:variants && tsgo",
-    "release": "syncular-publish"
-  },
-  "dependencies": {
-    "@syncular/core": "0.1.1",
-    "kysely": "^0.28.0",
-    "kysely-generic-sqlite": "^1.2.1"
-  },
-  "devDependencies": {
-    "@happy-dom/global-registrator": "^20.8.9",
-    "@sentry/react": "^10.47.0",
-    "@syncular/config": "0.0.0",
-    "@testing-library/react": "^16.3.2",
-    "@types/react": "^19.2.14",
-    "hono": "^4.12.15",
-    "react": "*",
-    "yjs": "^13.6.30"
-  },
   "files": [
-    "dist/*.d.ts",
-    "dist/*.d.ts.map",
-    "dist/*.js",
-    "dist/*.js.map",
-    "dist/crdt-yjs",
-    "dist/react",
-    "dist/react-native",
-    "dist/syncular-runtime-artifacts.json",
-    "dist/tauri",
-    "dist/wasm",
-    "dist/wasm-bindings",
-    "dist/wasm-core",
-    "dist/wasm-perf",
+    "dist",
     "src",
+    "README.md",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
-    "!src/**/__tests__/**",
-    "!dist/**/*.test.*",
-    "!dist/**/__tests__/**",
-    "!test/**",
-    "!tests/**"
+    "!dist/**/*.test.js",
+    "!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"
+  },
+  "dependencies": {
+    "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
+    "@syncular/core": "0.2.0"
+  },
   "peerDependencies": {
-    "@sentry/react": "^10.47.0",
-    "react": "^18.0.0 || ^19.0.0",
-    "react-native": "*",
-    "yjs": "^13.6.30"
+    "better-sqlite3": ">=11"
   },
   "peerDependenciesMeta": {
-    "@sentry/react": {
-      "optional": true
-    },
-    "react": {
-      "optional": true
-    },
-    "react-native": {
-      "optional": true
-    },
-    "yjs": {
+    "better-sqlite3": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "@syncular/server": "0.2.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "better-sqlite3": "^12.11.1"
   }
 }