@syncular/client 0.15.45 → 0.15.47

package/dist/remote.js

@@ -0,0 +1,441 @@
+/**
+ * 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 { encryptRowValues } from './encryption.js';
+import { ClientSyncError } from './errors.js';
+import { compileClientSchema, recordToRowValues, } from './schema.js';
+export function remoteCommand(id) {
+    if (id.length === 0)
+        throw invalid('remote command id must be non-empty');
+    return { id };
+}
+function invalid(message) {
+    return new ClientSyncError('sync.invalid_request', message);
+}
+function operationResponse(bytes) {
+    let response;
+    try {
+        response = decodeRemoteOperationResponse(bytes);
+    }
+    catch {
+        throw new ClientSyncError('client.invalid_host_response', 'remote operation response is malformed');
+    }
+    if (typeof response !== 'object' ||
+        response === null ||
+        Array.isArray(response)) {
+        throw new ClientSyncError('client.invalid_host_response', 'remote operation response is malformed');
+    }
+    if (response.revision !== 1) {
+        throw new ClientSyncError('client.invalid_host_response', 'remote operation response has an unsupported revision');
+    }
+    if (response.kind === 'error' &&
+        (typeof response.code !== 'string' ||
+            typeof response.message !== 'string' ||
+            typeof response.retryable !== 'boolean')) {
+        throw new ClientSyncError('client.invalid_host_response', 'remote operation error response is malformed');
+    }
+    if (response.kind === 'query' &&
+        (typeof response.operationId !== 'string' ||
+            !Array.isArray(response.rows) ||
+            response.rows.some((row) => typeof row !== 'object' || row === null || Array.isArray(row)) ||
+            !Number.isSafeInteger(response.maxCommitSeq) ||
+            response.maxCommitSeq < 0)) {
+        throw new ClientSyncError('client.invalid_host_response', 'remote query response is malformed');
+    }
+    if (response.kind === 'command' &&
+        (typeof response.operationId !== 'string' ||
+            typeof response.requestId !== 'string' ||
+            !['applied', 'cached', 'rejected'].includes(response.status) ||
+            !Array.isArray(response.results) ||
+            (response.commitSeq !== undefined &&
+                (!Number.isSafeInteger(response.commitSeq) || response.commitSeq < 1)))) {
+        throw new ClientSyncError('client.invalid_host_response', 'remote command response is malformed');
+    }
+    if (response.kind !== 'error' &&
+        response.kind !== 'query' &&
+        response.kind !== 'command') {
+        throw new ClientSyncError('client.invalid_host_response', 'remote operation response has an unknown kind');
+    }
+    return response;
+}
+export class SyncRemoteClient {
+    #schema;
+    #clientId;
+    #transport;
+    #operations;
+    #operationRealtime;
+    #operationSocket;
+    #operationSocketPromise;
+    #operationSocketGeneration = 0;
+    #watches = new Map();
+    #encryption;
+    constructor(config) {
+        if (config.clientId.length === 0) {
+            throw invalid('SyncRemoteClient clientId must be non-empty');
+        }
+        this.#schema =
+            config.schema === undefined
+                ? undefined
+                : compileClientSchema(config.schema);
+        this.#clientId = config.clientId;
+        this.#transport = config.transport;
+        this.#operations = config.operations;
+        this.#operationRealtime = config.operationRealtime;
+        this.#encryption = config.encryption;
+    }
+    async prepareCommit(input) {
+        const schema = this.#schema;
+        if (schema === undefined) {
+            throw new ClientSyncError('client.remote_schema_unconfigured', 'SyncRemoteClient needs a schema to prepare ordinary commits');
+        }
+        if (input.requestId.length === 0) {
+            throw invalid('remote commit requestId must be non-empty');
+        }
+        if (input.mutations.length === 0) {
+            throw new ClientSyncError('sync.empty_commit', 'a remote commit must carry at least one mutation (§6.1)');
+        }
+        const operations = [];
+        for (const mutation of input.mutations) {
+            const table = schema.tables.get(mutation.table);
+            if (table === undefined) {
+                throw invalid('remote commit targets an unknown table');
+            }
+            if (mutation.op === 'delete') {
+                if (mutation.rowId.length === 0) {
+                    throw invalid('remote delete rowId must be non-empty');
+                }
+                operations.push({
+                    table: mutation.table,
+                    rowId: mutation.rowId,
+                    op: 'delete',
+                    ...(mutation.baseVersion !== undefined
+                        ? { baseVersion: mutation.baseVersion }
+                        : {}),
+                });
+                continue;
+            }
+            let values = recordToRowValues(table, mutation.values);
+            const rowId = values[table.primaryKeyIndex];
+            if (typeof rowId !== 'string' || rowId.length === 0) {
+                throw invalid('remote upsert requires a non-empty string primary key');
+            }
+            if (this.#encryption !== undefined && table.hasEncryptedColumns) {
+                values = await encryptRowValues(this.#encryption, table, rowId, values);
+            }
+            operations.push({
+                table: mutation.table,
+                rowId,
+                op: 'upsert',
+                ...(mutation.baseVersion !== undefined
+                    ? { baseVersion: mutation.baseVersion }
+                    : {}),
+                payload: encodeRow(table.columns, values),
+            });
+        }
+        return {
+            requestId: input.requestId,
+            bytes: encodeMessage({
+                wireVersion: PROTOCOL_WIRE_VERSION,
+                msgKind: 'request',
+                frames: [
+                    {
+                        type: 'REQ_HEADER',
+                        clientId: this.#clientId,
+                        schemaVersion: schema.version,
+                    },
+                    {
+                        type: 'PUSH_COMMIT',
+                        clientCommitId: input.requestId,
+                        operations,
+                    },
+                ],
+            }),
+        };
+    }
+    async sendCommit(prepared) {
+        if (this.#transport === undefined) {
+            throw new ClientSyncError('client.remote_sync_unconfigured', 'SyncRemoteClient has no sync transport for ordinary commits');
+        }
+        const response = decodeMessage(await this.#transport(prepared.bytes));
+        if (response.msgKind !== 'response') {
+            throw new ClientSyncError('client.invalid_host_response', 'remote commit transport returned a non-response SSP2 message');
+        }
+        const error = response.frames.find((frame) => frame.type === 'ERROR');
+        if (error?.type === 'ERROR') {
+            throw new ClientSyncError(error.code, error.message, error.retryable);
+        }
+        const result = response.frames.find((frame) => frame.type === 'PUSH_RESULT' &&
+            frame.clientCommitId === prepared.requestId);
+        if (result === undefined) {
+            throw new ClientSyncError('client.invalid_host_response', 'remote commit response carried no matching PUSH_RESULT');
+        }
+        const details = response.frames.find((frame) => frame.type === 'PUSH_RESULT_DETAILS' &&
+            frame.clientCommitId === prepared.requestId);
+        const detailsByIndex = new Map(details?.entries.map((entry) => [entry.opIndex, entry.details]) ?? []);
+        return {
+            requestId: prepared.requestId,
+            status: result.status,
+            ...(result.commitSeq !== undefined
+                ? { commitSeq: result.commitSeq }
+                : {}),
+            results: result.results.map((operation) => {
+                if (operation.status !== 'error')
+                    return operation;
+                const operationDetails = detailsByIndex.get(operation.opIndex);
+                return operationDetails === undefined
+                    ? operation
+                    : { ...operation, details: operationDetails };
+            }),
+        };
+    }
+    async commit(input) {
+        return this.sendCommit(await this.prepareCommit(input));
+    }
+    async query(descriptor, params) {
+        if (this.#operations === undefined) {
+            throw new ClientSyncError('client.remote_operations_unconfigured', 'SyncRemoteClient has no remote operation transport');
+        }
+        const response = operationResponse(await this.#operations(encodeRemoteOperationRequest({
+            revision: 1,
+            kind: 'query',
+            clientId: this.#clientId,
+            operationId: descriptor.id,
+            params: params ?? null,
+        })));
+        if (response.kind === 'error') {
+            throw new ClientSyncError(response.code, response.message, response.retryable);
+        }
+        if (response.kind !== 'query' || response.operationId !== descriptor.id) {
+            throw new ClientSyncError('client.invalid_host_response', 'remote query returned a mismatched response');
+        }
+        try {
+            return {
+                rows: response.rows.map((row) => descriptor.mapRow(row)),
+                maxCommitSeq: response.maxCommitSeq,
+            };
+        }
+        catch {
+            throw new ClientSyncError('client.invalid_host_response', 'remote query row is malformed');
+        }
+    }
+    async command(descriptor, requestId, input) {
+        if (this.#operations === undefined) {
+            throw new ClientSyncError('client.remote_operations_unconfigured', 'SyncRemoteClient has no remote operation transport');
+        }
+        if (requestId.length === 0) {
+            throw invalid('remote command requestId must be non-empty');
+        }
+        const response = operationResponse(await this.#operations(encodeRemoteOperationRequest({
+            revision: 1,
+            kind: 'command',
+            clientId: this.#clientId,
+            operationId: descriptor.id,
+            requestId,
+            params: input ?? null,
+        })));
+        if (response.kind === 'error') {
+            throw new ClientSyncError(response.code, response.message, response.retryable);
+        }
+        if (response.kind !== 'command' ||
+            response.operationId !== descriptor.id ||
+            response.requestId !== requestId) {
+            throw new ClientSyncError('client.invalid_host_response', 'remote command returned a mismatched response');
+        }
+        return {
+            requestId,
+            status: response.status,
+            ...(response.commitSeq !== undefined
+                ? { commitSeq: response.commitSeq }
+                : {}),
+            results: response.results,
+        };
+    }
+    async watch(descriptor, params, handlers) {
+        if (this.#operationRealtime === undefined) {
+            throw new ClientSyncError('client.remote_realtime_unconfigured', 'SyncRemoteClient has no remote operation realtime connector');
+        }
+        const watchId = crypto.randomUUID();
+        this.#watches.set(watchId, {
+            operationId: descriptor.id,
+            mapRow: descriptor.mapRow,
+            handlers: handlers,
+        });
+        let socket;
+        try {
+            socket = await this.#operationRealtimeSocket();
+        }
+        catch (error) {
+            this.#watches.delete(watchId);
+            throw error;
+        }
+        if (!this.#watches.has(watchId)) {
+            throw new ClientSyncError('client.remote_realtime_cancelled', 'remote operation watch was cancelled before registration');
+        }
+        try {
+            socket.send(encodeRemoteOperationRealtimeMessage({
+                revision: 1,
+                kind: 'watch',
+                watchId,
+                clientId: this.#clientId,
+                operationId: descriptor.id,
+                params: params ?? null,
+            }));
+        }
+        catch {
+            const error = new ClientSyncError('client.remote_realtime_closed', 'remote operation realtime connection closed while registering a watch', true);
+            this.#disconnectOperationRealtime(this.#operationSocketGeneration, error, true);
+            throw error;
+        }
+        return () => {
+            if (!this.#watches.delete(watchId))
+                return;
+            try {
+                this.#operationSocket?.send(encodeRemoteOperationRealtimeMessage({
+                    revision: 1,
+                    kind: 'unwatch',
+                    watchId,
+                }));
+            }
+            catch {
+                this.#disconnectOperationRealtime(this.#operationSocketGeneration, new ClientSyncError('client.remote_realtime_closed', 'remote operation realtime connection closed while removing a watch', true), true);
+            }
+        };
+    }
+    async #operationRealtimeSocket() {
+        if (this.#operationSocket !== undefined)
+            return this.#operationSocket;
+        if (this.#operationSocketPromise !== undefined) {
+            return this.#operationSocketPromise;
+        }
+        const connector = this.#operationRealtime;
+        if (connector === undefined) {
+            throw new ClientSyncError('client.remote_realtime_unconfigured', 'SyncRemoteClient has no remote operation realtime connector');
+        }
+        const generation = this.#operationSocketGeneration;
+        const pending = Promise.resolve(connector({
+            onMessage: (bytes) => {
+                if (generation !== this.#operationSocketGeneration)
+                    return;
+                let message;
+                try {
+                    message = decodeRemoteOperationRealtimeMessage(bytes);
+                    if (typeof message !== 'object' ||
+                        message === null ||
+                        message.revision !== 1 ||
+                        (message.kind !== 'snapshot' && message.kind !== 'watch_error') ||
+                        typeof message.watchId !== 'string') {
+                        throw new Error('invalid remote operation realtime message');
+                    }
+                }
+                catch {
+                    this.#disconnectOperationRealtime(generation, new ClientSyncError('client.invalid_host_response', 'remote operation realtime message is malformed'), true);
+                    return;
+                }
+                const watch = this.#watches.get(message.watchId);
+                if (watch === undefined)
+                    return;
+                if (message.kind === 'watch_error') {
+                    if (typeof message.code !== 'string' ||
+                        typeof message.message !== 'string' ||
+                        typeof message.retryable !== 'boolean') {
+                        this.#disconnectOperationRealtime(generation, new ClientSyncError('client.invalid_host_response', 'remote operation watch error is malformed'), true);
+                        return;
+                    }
+                    try {
+                        watch.handlers.onError?.(new ClientSyncError(message.code, message.message, message.retryable));
+                    }
+                    catch {
+                        // An observer cannot alter the connection lifecycle.
+                    }
+                    return;
+                }
+                if (message.operationId !== watch.operationId ||
+                    !Array.isArray(message.rows) ||
+                    message.rows.some((row) => typeof row !== 'object' || row === null || Array.isArray(row)) ||
+                    !Number.isSafeInteger(message.maxCommitSeq) ||
+                    message.maxCommitSeq < 0) {
+                    this.#disconnectOperationRealtime(generation, new ClientSyncError('client.invalid_host_response', 'remote operation watch snapshot is malformed'), true);
+                    return;
+                }
+                let rows;
+                try {
+                    rows = message.rows.map(watch.mapRow);
+                }
+                catch {
+                    try {
+                        watch.handlers.onError?.(new ClientSyncError('client.invalid_host_response', 'remote operation watch row is malformed'));
+                    }
+                    catch {
+                        // An observer cannot alter the connection lifecycle.
+                    }
+                    return;
+                }
+                try {
+                    watch.handlers.onSnapshot({
+                        rows,
+                        maxCommitSeq: message.maxCommitSeq,
+                    });
+                }
+                catch {
+                    // An observer cannot alter the connection lifecycle.
+                }
+            },
+            onClose: () => {
+                this.#disconnectOperationRealtime(generation, new ClientSyncError('client.remote_realtime_closed', 'remote operation realtime connection closed', true), false);
+            },
+        }))
+            .then((socket) => {
+            if (generation !== this.#operationSocketGeneration) {
+                try {
+                    socket.close();
+                }
+                catch {
+                    // The cancelled socket cannot affect the replacement generation.
+                }
+                throw new ClientSyncError('client.remote_realtime_cancelled', 'remote operation realtime connection was cancelled');
+            }
+            this.#operationSocket = socket;
+            return socket;
+        })
+            .finally(() => {
+            if (this.#operationSocketPromise === pending) {
+                this.#operationSocketPromise = undefined;
+            }
+        });
+        this.#operationSocketPromise = pending;
+        return pending;
+    }
+    #disconnectOperationRealtime(generation, error, closeSocket) {
+        if (generation !== this.#operationSocketGeneration)
+            return;
+        this.#operationSocketGeneration += 1;
+        const socket = this.#operationSocket;
+        this.#operationSocket = undefined;
+        this.#operationSocketPromise = undefined;
+        const watches = [...this.#watches.values()];
+        this.#watches.clear();
+        if (closeSocket) {
+            try {
+                socket?.close();
+            }
+            catch {
+                // Local state is already disconnected.
+            }
+        }
+        if (error === undefined)
+            return;
+        for (const watch of watches) {
+            try {
+                watch.handlers.onError?.(error);
+            }
+            catch {
+                // An observer cannot alter the connection lifecycle.
+            }
+        }
+    }
+    close() {
+        this.#disconnectOperationRealtime(this.#operationSocketGeneration, undefined, true);
+    }
+}

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/transport.d.ts

@@ -6,6 +6,17 @@
  */
 /** One combined push+pull round trip: SSP2 request bytes → response bytes. */
 export type SyncTransport = (request: Uint8Array) => Promise<Uint8Array>;
+/** One registered authoritative query or command request. */
+export type RemoteOperationTransport = (request: Uint8Array) => Promise<Uint8Array>;
+export interface RemoteOperationRealtimeHandlers {
+    onMessage(bytes: Uint8Array): void;
+    onClose?(): void;
+}
+export interface RemoteOperationRealtimeSocket {
+    send(bytes: Uint8Array): void;
+    close(): void;
+}
+export type RemoteOperationRealtimeConnector = (handlers: RemoteOperationRealtimeHandlers) => RemoteOperationRealtimeSocket | Promise<RemoteOperationRealtimeSocket>;
 export interface SegmentFetchRequest {
     readonly segmentId: string;
     readonly table: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.45",
+  "version": "0.15.47",
   "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.45"
-  },
-  "peerDependencies": {
-    "better-sqlite3": ">=11"
-  },
-  "peerDependenciesMeta": {
-    "better-sqlite3": {
-      "optional": true
-    }
+    "@syncular/core": "0.15.47"
   },
   "devDependencies": {
-    "@syncular/server": "0.15.45",
-    "@types/better-sqlite3": "^7.6.13",
-    "better-sqlite3": "^12.11.1"
+    "@syncular/server": "0.15.47"
   }
 }

package/src/http.ts

@@ -9,6 +9,8 @@ import { SSP2_CONTENT_TYPE } from './content-type';
 import { ClientSyncError } from './errors';
 import type {
   RealtimeConnector,
+  RemoteOperationTransport,
+  RemoteOperationRealtimeConnector,
   SegmentDownloader,
   SyncTransport,
 } from './transport';
@@ -57,6 +59,78 @@ export function httpSyncTransport(
   };
 }
 
+/** POST one registered authoritative operation to `<mount>/operations`. */
+export function httpRemoteOperationTransport(
+  operationsUrl: string,
+  options?: HttpTransportOptions,
+): RemoteOperationTransport {
+  const doFetch = options?.fetch ?? fetch;
+  return async (request) => {
+    const response = await doFetch(operationsUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/vnd.syncular.operations.v1+json',
+        ...options?.headers,
+      },
+      body: request.slice().buffer as ArrayBuffer,
+    });
+    if (!response.ok) await throwHttpError(response);
+    return new Uint8Array(await response.arrayBuffer());
+  };
+}
+
+/** WebSocket connector for registered query snapshots. */
+export function webSocketRemoteOperationConnector(
+  realtimeUrl: string,
+): RemoteOperationRealtimeConnector {
+  return (handlers) =>
+    new Promise((resolve, reject) => {
+      const socket = new WebSocket(realtimeUrl);
+      let opened = false;
+      socket.binaryType = 'arraybuffer';
+      socket.onopen = () => {
+        opened = true;
+        resolve({
+          send: (bytes) => socket.send(bytes.slice().buffer as ArrayBuffer),
+          close: () => socket.close(),
+        });
+      };
+      socket.onmessage = (event) => {
+        if (event.data instanceof ArrayBuffer) {
+          handlers.onMessage(new Uint8Array(event.data));
+        }
+      };
+      socket.onerror = () => {
+        if (!opened) {
+          reject(
+            new ClientSyncError(
+              'sync.transport_failed',
+              'remote operation realtime socket failed to connect',
+              true,
+            ),
+          );
+        }
+        try {
+          socket.close();
+        } catch {
+          handlers.onClose?.();
+        }
+      };
+      socket.onclose = () => {
+        if (!opened) {
+          reject(
+            new ClientSyncError(
+              'sync.transport_failed',
+              'remote operation realtime socket closed while connecting',
+              true,
+            ),
+          );
+        }
+        handlers.onClose?.();
+      };
+    });
+}
+
 /**
  * §5.5 direct endpoint with the `X-Syncular-Scopes` re-authorization
  * header, plus the §5.4 `fetchUrl` capability (advertises accept bit 3).
@@ -224,8 +298,10 @@ export function webSocketRealtimeConnector(
   return (handlers) =>
     new Promise((resolve, reject) => {
       const socket = new WebSocket(realtimeUrl);
+      let opened = false;
       socket.binaryType = 'arraybuffer';
       socket.onopen = () => {
+        opened = true;
         resolve({
           send: (text) => socket.send(text),
           sendBytes: (bytes) => {
@@ -239,15 +315,31 @@ export function webSocketRealtimeConnector(
         else handlers.onBinary(new Uint8Array(event.data as ArrayBuffer));
       };
       socket.onerror = () => {
-        reject(
-          new ClientSyncError(
-            'sync.transport_failed',
-            'realtime socket failed to connect',
-            true,
-          ),
-        );
+        if (!opened) {
+          reject(
+            new ClientSyncError(
+              'sync.transport_failed',
+              'realtime socket failed to connect',
+              true,
+            ),
+          );
+        }
+        try {
+          socket.close();
+        } catch {
+          handlers.onClose?.();
+        }
       };
       socket.onclose = () => {
+        if (!opened) {
+          reject(
+            new ClientSyncError(
+              'sync.transport_failed',
+              'realtime socket closed while connecting',
+              true,
+            ),
+          );
+        }
         handlers.onClose?.();
       };
     });

package/src/index.ts

@@ -3,7 +3,7 @@
  * SPEC.md is normative.
  *
  * Browser-safe root: database backends live behind subpath exports
- * (`./bun` for bun:sqlite tests, `./wasm` for sqlite-wasm + OPFS); the
+ * (`./sqlite` for Node or Bun, `./wasm` for sqlite-wasm + OPFS); the
  * worker-side bootstrap lives behind `./worker`. The main-thread handle
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.
@@ -30,6 +30,7 @@ export * from './outbox';
 export * from './outcomes';
 export * from './query-guard';
 export * from './reactive-store';
+export * from './remote';
 export * from './realtime-supervisor';
 export * from './schema';
 export * from './sql-tag';