@syncular/client 0.30.12 → 0.30.14

package/dist/worker-entry.js

@@ -94,6 +94,7 @@ export function startSyncWorker(overrides = {}) {
         autoSyncScheduled = false;
         if (closed ||
             client === undefined ||
+            offline ||
             client.securityLifecycle() === 'preflight') {
             return;
         }
@@ -116,6 +117,7 @@ export function startSyncWorker(overrides = {}) {
         if (!autoSync ||
             closed ||
             client === undefined ||
+            offline ||
             client.securityLifecycle() === 'preflight' ||
             intent.kind === 'none') {
             return;
@@ -156,31 +158,6 @@ export function startSyncWorker(overrides = {}) {
         }
         return client;
     }
-    function assertOnline() {
-        if (offline) {
-            throw new ClientSyncError('sync.transport_failed', 'the worker transport is offline (setOffline(true))', true);
-        }
-    }
-    function gateOffline(inner) {
-        return (request) => {
-            assertOnline();
-            return inner(request);
-        };
-    }
-    /** Offline gate that preserves the §5.4 `fetchUrl` capability marker. */
-    function gateSegmentsOffline(inner) {
-        const fetchUrl = inner.fetchUrl;
-        return Object.assign(gateOffline(inner), {
-            ...(fetchUrl !== undefined
-                ? {
-                    fetchUrl: (url, onProgress) => {
-                        assertOnline();
-                        return fetchUrl(url, onProgress);
-                    },
-                }
-                : {}),
-        });
-    }
     async function init(config) {
         if (client !== undefined) {
             throw new ClientSyncError(WORKER_FAILED_CODE, 'the worker is already initialized');
@@ -215,9 +192,9 @@ export function startSyncWorker(overrides = {}) {
                 }
             }
         }
-        const transport = gateOffline(overrides.createTransport !== undefined
+        const transport = overrides.createTransport !== undefined
             ? overrides.createTransport(config)
-            : httpSyncTransport(config.endpoints.syncUrl, http));
+            : httpSyncTransport(config.endpoints.syncUrl, http);
         const segments = overrides.createSegments !== undefined
             ? overrides.createSegments(config)
             : config.endpoints.segmentsUrl !== undefined
@@ -231,18 +208,15 @@ export function startSyncWorker(overrides = {}) {
         // `{clientId}` URL placeholder — start the client first, then attach
         // the connector through a mutable slot read at connect time.
         let realtimeConnector;
+        offline = config.transportEnabled === false;
         const started = new SyncClient({
+            transportEnabled: !offline,
             database,
             schema: config.schema,
             transport,
-            ...(segments !== undefined
-                ? { segments: gateSegmentsOffline(segments) }
-                : {}),
+            ...(segments !== undefined ? { segments } : {}),
             ...(blobs !== undefined ? { blobs } : {}),
             realtime: (handlers) => {
-                if (offline) {
-                    throw new ClientSyncError('sync.transport_failed', 'the worker realtime channel is offline (setOffline(true))', true);
-                }
                 if (realtimeConnector === undefined) {
                     throw new ClientSyncError('sync.invalid_request', 'no realtime connector configured');
                 }
@@ -399,8 +373,13 @@ export function startSyncWorker(overrides = {}) {
         },
         setOffline: (value) => {
             offline = value;
-            if (offline)
-                client?.disconnectRealtime();
+            requireClient().setTransportEnabled(!value);
+            if (offline) {
+                if (backgroundTimer !== undefined)
+                    clearTimeout(backgroundTimer);
+                backgroundTimer = undefined;
+                backgroundDue = Number.POSITIVE_INFINITY;
+            }
             else if (client !== undefined) {
                 const snapshot = client.diagnosticsSnapshot();
                 post({

package/dist/worker-host.d.ts

@@ -85,6 +85,7 @@ export interface SyncClientHandleConfig {
     readonly encryption?: EncryptionKeyringConfig;
     /** Open the worker-owned replica behind the fail-closed security gate. */
     readonly securityPreflight?: boolean;
+    readonly transportEnabled?: boolean;
     readonly clientId?: string;
     readonly limits?: SyncClientLimits;
     readonly retainFailedCommits?: boolean;

package/dist/worker-host.js

@@ -566,6 +566,9 @@ function buildInitConfig(config, headers = config.headers) {
         ...(config.encryption !== undefined
             ? { encryption: config.encryption }
             : {}),
+        ...(config.transportEnabled !== undefined
+            ? { transportEnabled: config.transportEnabled }
+            : {}),
         ...(config.securityPreflight !== undefined
             ? { securityPreflight: config.securityPreflight }
             : {}),

package/dist/worker-protocol.d.ts

@@ -78,6 +78,7 @@ export interface WorkerInitConfig {
     readonly encryption?: EncryptionKeyringConfig;
     /** Open the worker-owned replica behind the fail-closed security gate. */
     readonly securityPreflight?: boolean;
+    readonly transportEnabled?: boolean;
     readonly clientId?: string;
     readonly limits?: SyncClientLimits;
     readonly retainFailedCommits?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.30.12",
+  "version": "0.30.14",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,10 +89,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.30.12"
+    "@syncular/core": "0.30.14"
   },
   "devDependencies": {
-    "@syncular/server": "0.30.12",
+    "@syncular/server": "0.30.14",
     "playwright": "1.63.0",
     "@electric-sql/pglite": "^0.5.4"
   }

package/src/apply.ts

@@ -1,4 +1,6 @@
-import { RETAINED_ROWS } from './failed-overlay';
+import { hasUniqueIndex } from './schema';
+import { OUTBOX_TABLE, OUTBOX_IMAGES, countOutbox } from './outbox';
+import { RETAINED_ROWS, type OverlayScope } from './failed-overlay';
 import { retainedBaseWrite, restoreFailedBases } from './failed-overlay';
 /**
  * Local application of server data: `COMMIT` frames (§4.5), rows segments
@@ -28,7 +30,7 @@ import {
 } from './schema';
 
 /** Lets the client wrap the physical write in its revision transaction. */
-export type ApplyTransaction = <T>(fn: () => T) => T;
+export type ApplyTransaction = (fn: () => OverlayScope) => unknown;
 
 function upsertSql(table: CompiledClientTable): string {
   const names = [
@@ -96,8 +98,7 @@ export async function applyCommitFrame(
   schema: CompiledClientSchema,
   frame: CommitFrame,
   encryption?: EncryptionConfig,
-  transaction: (fn: () => readonly string[] | undefined) => unknown = (fn) =>
-    db.transaction(fn),
+  transaction: (fn: () => OverlayScope) => unknown = (fn) => db.transaction(fn),
 ): Promise<void> {
   type Resolved =
     | { op: 'delete'; table: CompiledClientTable; rowId: string }
@@ -142,18 +143,18 @@ export async function applyCommitFrame(
     });
   }
   transaction(() => {
-    const rowKeys = frame.tables.some((name) =>
-      schema.tables.get(name)?.indexes.some((index) => index.unique),
-    )
-      ? undefined
-      : frame.changes.map((change) =>
-          JSON.stringify([frame.tables[change.tableIndex], change.rowId]),
-        );
-    restoreFailedBases(db, schema, false, rowKeys);
+    const scope = resolved.map((change, index) =>
+      JSON.stringify(
+        hasUniqueIndex(change.table)
+          ? [change.table.name]
+          : [change.table.name, frame.changes[index]!.rowId],
+      ),
+    );
+    restoreFailedBases(db, schema, scope);
     for (const [index, change] of resolved.entries()) {
       const rowId = frame.changes[index]!.rowId;
       db.exec(
-        "UPDATE _syncular_outbox_before_images SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE (client_commit_id,op_index) IN(SELECT client_commit_id,json_each.key FROM _syncular_outbox,json_each(operations) WHERE json_extract(value,'$.table')=? AND json_extract(value,'$.rowId')=?)",
+        `UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE (client_commit_id,op_index) IN(SELECT client_commit_id,json_each.key FROM ${OUTBOX_TABLE},json_each(operations) WHERE json_extract(value,'$.table')=? AND json_extract(value,'$.rowId')=?)`,
         [frame.commitSeq, change.table.name, rowId],
       );
       db.exec(
@@ -166,7 +167,7 @@ export async function applyCommitFrame(
         upsertLocalRow(db, change.table, change.values, change.rowVersion);
       }
     }
-    return rowKeys;
+    return scope;
   });
 }
 
@@ -238,6 +239,41 @@ export function localScopePredicate(
   return { sql, params };
 }
 
+function scopedRows(
+  db: ClientDatabase,
+  table: CompiledClientTable,
+  scope: ReturnType<typeof localScopePredicate>,
+) {
+  return scope
+    ? db.query(
+        `SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${scope.sql}`,
+        scope.params,
+      )
+    : [];
+}
+
+function bootstrapScope(
+  db: ClientDatabase,
+  table: CompiledClientTable,
+  effective: ScopeMap,
+): string[] {
+  const rows = scopedRows(db, table, localScopePredicate(table, effective));
+  rows.push(
+    ...db
+      .query(`SELECT id,base,intent FROM ${RETAINED_ROWS} WHERE tbl=?`, [
+        table.name,
+      ])
+      .filter((row) =>
+        [row.base, row.intent].some(
+          (json) =>
+            json !== null &&
+            matchesLocalScopes(table, effective, JSON.parse(json as string)),
+        ),
+      ),
+  );
+  return rows.map((row) => JSON.stringify([table.name, String(row.id)]));
+}
+
 export function deleteScopedRows(
   db: ClientDatabase,
   table: CompiledClientTable,
@@ -246,10 +282,7 @@ export function deleteScopedRows(
   const scope = localScopePredicate(table, effective);
   if (!scope) return;
   const { sql, params } = scope;
-  for (const row of db.query(
-    `SELECT ${quoteIdent(table.primaryKey)} AS id FROM ${quoteIdent(table.name)} WHERE ${sql}`,
-    params,
-  )) {
+  for (const row of scopedRows(db, table, scope)) {
     retainedBaseWrite(db, table, String(row.id));
   }
   db.exec(`DELETE FROM ${quoteIdent(table.name)} WHERE ${sql}`, params);
@@ -451,8 +484,31 @@ export async function applySqliteSegment(
         predicates.push(`${primaryKey} <= ?`);
         params.push(boundary);
       }
+      const replay =
+        countOutbox(db) ||
+        db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? LIMIT 1`, [
+          table.name,
+        ]).length;
+      const rows = replay
+        ? db.query(
+            `SELECT * FROM ${source} WHERE ${predicates.join(' AND ') || 'true'}`,
+            params,
+          )
+        : [];
       (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
-        restoreFailedBases(db, schema);
+        const scope = !replay
+          ? []
+          : hasUniqueIndex(table)
+            ? [JSON.stringify([table.name])]
+            : [
+                ...(after === undefined && options.clearFirst
+                  ? bootstrapScope(db, table, options.effective)
+                  : []),
+                ...rows.map((row) =>
+                  JSON.stringify([table.name, String(row[table.primaryKey])]),
+                ),
+              ];
+        const protectedRows = restoreFailedBases(db, schema, scope);
         if (after === undefined && options.clearFirst)
           deleteScopedRows(db, table, options.effective);
         db.exec(
@@ -460,23 +516,22 @@ export async function applySqliteSegment(
           params,
         );
         applied += Number(db.query('SELECT changes()AS n')[0]?.n ?? 0);
-        for (const row of db.query(
-          `SELECT * FROM ${source} WHERE ${predicates.join(' AND ') || 'true'}`,
-          params,
-        )) {
-          retainedBaseWrite(
-            db,
-            table,
-            String(row[table.primaryKey]),
-            Object.fromEntries(
-              table.columns.map((column) => [
-                column.name,
-                rowValueToJson(row[column.name] as RowValue),
-              ]),
-            ),
-            Number(row._syncular_version),
-          );
-        }
+        if (protectedRows)
+          for (const row of rows) {
+            retainedBaseWrite(
+              db,
+              table,
+              String(row[table.primaryKey]),
+              Object.fromEntries(
+                table.columns.map((column) => [
+                  column.name,
+                  rowValueToJson(row[column.name] as RowValue),
+                ]),
+              ),
+              Number(row._syncular_version),
+            );
+          }
+        return scope;
       });
       options.onProgress?.(applied);
       await yieldToHost();
@@ -537,7 +592,20 @@ export async function applyRowsSegment(
     first = false;
     if (!clearThisBlock && rows.length === 0) continue;
     (options.transaction ?? ((fn) => db.transaction(fn)))(() => {
-      const protectedRows = restoreFailedBases(db, schema);
+      const scope: OverlayScope = hasUniqueIndex(table)
+        ? [JSON.stringify([table.name])]
+        : [
+            ...(clearThisBlock
+              ? bootstrapScope(db, table, options.effective)
+              : []),
+            ...rows.map((row) =>
+              JSON.stringify([
+                table.name,
+                String(row.values[table.primaryKeyIndex]),
+              ]),
+            ),
+          ];
+      const protectedRows = restoreFailedBases(db, schema, scope);
       if (clearThisBlock) {
         deleteScopedRows(db, table, options.effective);
       }
@@ -546,6 +614,7 @@ export async function applyRowsSegment(
         applied += 1;
         if (applied % 1024 === 0) options.onProgress?.(applied);
       }
+      return scope;
     });
     options.onProgress?.(applied);
     await yieldToHost();

package/src/blob.ts

@@ -1,3 +1,4 @@
+export const BLOB_COMMIT_REFS = '_syncular_blob_commit_refs';
 /**
  * Client-side blob cache + transport (SPEC.md §5.9.7).
  *
@@ -187,7 +188,7 @@ export function enforceBlobCacheCap(
   if (total <= maxBytes) return [];
   // Oldest eligible body first, with blob ID as a stable tie.
   const candidates = db.query(
-    `SELECT blob_id,byte_length FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM _syncular_blob_commit_refs)AND blob_id NOT IN(${visibleBlobIdsSql(schema)})ORDER BY created_at_ms ASC,blob_id ASC`,
+    `SELECT blob_id,byte_length FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM ${BLOB_COMMIT_REFS})AND blob_id NOT IN(${visibleBlobIdsSql(schema)})ORDER BY created_at_ms ASC,blob_id ASC`,
   );
   const evicted: string[] = [];
   db.transaction(() => {
@@ -207,7 +208,7 @@ export function listPendingUploads(
 ): { blobId: string; mediaType?: string }[] {
   return db
     .query(
-      'SELECT blob_id,media_type FROM(SELECT blob_id,media_type,created_at_ms FROM _syncular_blob_uploads UNION ALL SELECT DISTINCT r.blob_id,b.media_type,9223372036854775807 AS created_at_ms FROM _syncular_blob_commit_refs r LEFT JOIN _syncular_blobs b ON b.blob_id=r.blob_id WHERE NOT EXISTS(SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id=r.blob_id))ORDER BY created_at_ms,blob_id',
+      `SELECT blob_id,media_type FROM(SELECT blob_id,media_type,created_at_ms FROM _syncular_blob_uploads UNION ALL SELECT DISTINCT r.blob_id,b.media_type,9223372036854775807 AS created_at_ms FROM ${BLOB_COMMIT_REFS} r LEFT JOIN _syncular_blobs b ON b.blob_id=r.blob_id WHERE NOT EXISTS(SELECT 1 FROM _syncular_blob_uploads u WHERE u.blob_id=r.blob_id))ORDER BY created_at_ms,blob_id`,
     )
     .map((row) => {
       if (
@@ -285,7 +286,7 @@ export function deleteUnreferencedCachedBlobs(
   schema: CompiledClientSchema,
 ): void {
   db.exec(
-    `DELETE FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM _syncular_blob_commit_refs)AND blob_id NOT IN(${visibleBlobIdsSql(schema)})`,
+    `DELETE FROM _syncular_blobs WHERE blob_id NOT IN(SELECT blob_id FROM _syncular_blob_uploads)AND blob_id NOT IN(SELECT blob_id FROM ${BLOB_COMMIT_REFS})AND blob_id NOT IN(${visibleBlobIdsSql(schema)})`,
   );
 }