@syncular/client 0.0.1-72 → 0.0.1-83

package/src/engine/SyncEngine.test.ts

@@ -0,0 +1,157 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import type { SyncChange, SyncTransport } from '@syncular/core';
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import { createBunSqliteDb } from '../../../dialect-bun-sqlite/src';
+import { ClientTableRegistry } from '../handlers/registry';
+import { ensureClientSyncSchema } from '../migrate';
+import type { SyncClientDb } from '../schema';
+import { SyncEngine } from './SyncEngine';
+
+interface TasksTable {
+  id: string;
+  title: string;
+  server_version: number;
+}
+
+interface TestDb extends SyncClientDb {
+  tasks: TasksTable;
+}
+
+const noopTransport: SyncTransport = {
+  async sync() {
+    return {};
+  },
+  async fetchSnapshotChunk() {
+    return new Uint8Array();
+  },
+};
+
+describe('SyncEngine WS inline apply', () => {
+  let db: Kysely<TestDb>;
+
+  beforeEach(async () => {
+    db = createBunSqliteDb<TestDb>({ path: ':memory:' });
+    await ensureClientSyncSchema(db);
+
+    await db.schema
+      .createTable('tasks')
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('title', 'text', (col) => col.notNull())
+      .addColumn('server_version', 'integer', (col) =>
+        col.notNull().defaultTo(0)
+      )
+      .execute();
+
+    await db
+      .insertInto('tasks')
+      .values({
+        id: 't1',
+        title: 'old',
+        server_version: 1,
+      })
+      .execute();
+
+    await db
+      .insertInto('sync_subscription_state')
+      .values({
+        state_id: 'default',
+        subscription_id: 'sub-1',
+        shape: 'tasks',
+        scopes_json: '{}',
+        params_json: '{}',
+        cursor: 0,
+        bootstrap_state_json: null,
+        status: 'active',
+        created_at: Date.now(),
+        updated_at: Date.now(),
+      })
+      .execute();
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+  });
+
+  it('rolls back row updates and cursor when any inline WS change fails', async () => {
+    const shapes = new ClientTableRegistry<TestDb>().register({
+      table: 'tasks',
+      async applySnapshot() {},
+      async clearAll() {},
+      async applyChange(ctx, change) {
+        if (change.row_id === 'fail') {
+          throw new Error('forced apply failure');
+        }
+        const rowJson =
+          change.row_json && typeof change.row_json === 'object'
+            ? change.row_json
+            : null;
+        const title =
+          rowJson && 'title' in rowJson ? String(rowJson.title ?? '') : '';
+        await sql`
+          update ${sql.table('tasks')}
+          set
+            ${sql.ref('title')} = ${sql.val(title)},
+            ${sql.ref('server_version')} = ${sql.val(Number(change.row_version ?? 0))}
+          where ${sql.ref('id')} = ${sql.val(change.row_id)}
+        `.execute(ctx.trx);
+      },
+    });
+
+    const engine = new SyncEngine<TestDb>({
+      db,
+      transport: noopTransport,
+      shapes,
+      actorId: 'u1',
+      clientId: 'client-1',
+      subscriptions: [],
+      stateId: 'default',
+    });
+
+    const changes: SyncChange[] = [
+      {
+        table: 'tasks',
+        row_id: 't1',
+        op: 'upsert',
+        row_json: { id: 't1', title: 'new' },
+        row_version: 2,
+        scopes: {},
+      },
+      {
+        table: 'tasks',
+        row_id: 'fail',
+        op: 'upsert',
+        row_json: { id: 'fail', title: 'bad' },
+        row_version: 1,
+        scopes: {},
+      },
+    ];
+
+    const applyWsDeliveredChanges = Reflect.get(
+      engine,
+      'applyWsDeliveredChanges'
+    );
+    if (typeof applyWsDeliveredChanges !== 'function') {
+      throw new Error('Expected applyWsDeliveredChanges to be callable');
+    }
+    const applied = await applyWsDeliveredChanges.call(engine, changes, 10);
+
+    expect(applied).toBe(false);
+
+    const task = await db
+      .selectFrom('tasks')
+      .select(['title', 'server_version'])
+      .where('id', '=', 't1')
+      .executeTakeFirstOrThrow();
+    expect(task.title).toBe('old');
+    expect(task.server_version).toBe(1);
+
+    const state = await db
+      .selectFrom('sync_subscription_state')
+      .select(['cursor'])
+      .where('state_id', '=', 'default')
+      .where('subscription_id', '=', 'sub-1')
+      .executeTakeFirstOrThrow();
+    expect(state.cursor).toBe(0);
+  });
+});

package/src/engine/SyncEngine.ts

@@ -10,6 +10,7 @@ import type {
   SyncPullResponse,
   SyncSubscriptionRequest,
 } from '@syncular/core';
+import { isRecord } from '@syncular/core';
 import { type Kysely, sql } from 'kysely';
 import { syncPushOnce } from '../push-engine';
 import type {
@@ -71,10 +72,6 @@ function createSyncError(
   };
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 /**
  * Sync engine that orchestrates push/pull cycles with proper lifecycle management.
  *
@@ -611,7 +608,12 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       }
 
       // Refresh outbox stats (fire-and-forget — don't block sync:complete)
-      this.refreshOutboxStats().catch(() => {});
+      this.refreshOutboxStats().catch((error) => {
+        console.warn(
+          '[SyncEngine] Failed to refresh outbox stats after sync:',
+          error
+        );
+      });
 
       return syncResult;
     } catch (err) {
@@ -680,13 +682,13 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     try {
       await this.config.db.transaction().execute(async (trx) => {
         for (const change of changes) {
-          try {
-            const handler = this.config.shapes.get(change.table);
-            if (!handler) continue;
-            await handler.applyChange({ trx }, change);
-          } catch {
-            // Best-effort: individual change failures are fine
+          const handler = this.config.shapes.get(change.table);
+          if (!handler) {
+            throw new Error(
+              `Missing client table handler for WS change table "${change.table}"`
+            );
           }
+          await handler.applyChange({ trx }, change);
         }
 
         // Update subscription cursors
@@ -737,13 +739,19 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
   ): Promise<void> {
     // If a sync is already in-flight, let it handle everything
     if (this.syncPromise) {
-      this.sync({ trigger: 'ws' });
+      this.triggerSyncInBackground(
+        { trigger: 'ws' },
+        'ws delivery with in-flight sync'
+      );
       return;
     }
 
     // If there are pending outbox commits, need to push via HTTP
     if (this.state.pendingCount > 0) {
-      this.sync({ trigger: 'ws' });
+      this.triggerSyncInBackground(
+        { trigger: 'ws' },
+        'ws delivery with pending outbox'
+      );
       return;
     }
 
@@ -753,14 +761,20 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       (p) => typeof p.afterPull === 'function'
     );
     if (hasAfterPullPlugins) {
-      this.sync({ trigger: 'ws' });
+      this.triggerSyncInBackground(
+        { trigger: 'ws' },
+        'ws delivery with afterPull plugins'
+      );
       return;
     }
 
     // Apply changes + update cursor
     const applied = await this.applyWsDeliveredChanges(changes, cursor);
     if (!applied) {
-      this.sync({ trigger: 'ws' });
+      this.triggerSyncInBackground(
+        { trigger: 'ws' },
+        'ws inline apply fallback'
+      );
       return;
     }
 
@@ -779,7 +793,12 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       pullResponse: { ok: true, subscriptions: [] },
     });
 
-    this.refreshOutboxStats().catch(() => {});
+    this.refreshOutboxStats().catch((error) => {
+      console.warn(
+        '[SyncEngine] Failed to refresh outbox stats after WS apply:',
+        error
+      );
+    });
   }
 
   private timestampCounter = 0;
@@ -888,7 +907,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     this.retryTimeoutId = setTimeout(() => {
       this.retryTimeoutId = null;
       if (!this.isDestroyed) {
-        this.sync();
+        this.triggerSyncInBackground(undefined, 'retry timer');
       }
     }, delay);
   }
@@ -898,13 +917,25 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     this.config.onError?.(error);
   }
 
+  private triggerSyncInBackground(
+    opts?: { trigger?: 'ws' | 'local' | 'poll' },
+    reason = 'background'
+  ): void {
+    void this.sync(opts).catch((error) => {
+      console.error(
+        `[SyncEngine] Unexpected sync failure during ${reason}:`,
+        error
+      );
+    });
+  }
+
   private setupPolling(): void {
     this.stopPolling();
 
     const interval = this.config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     this.pollerId = setInterval(() => {
       if (!this.state.isSyncing && !this.isDestroyed) {
-        this.sync();
+        this.triggerSyncInBackground(undefined, 'polling interval');
       }
     }, interval);
 
@@ -966,7 +997,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
             this.handleWsDelivery(event.data.changes as SyncChange[], cursor);
           } else {
             // Cursor-only wake-up or no cursor — must HTTP sync
-            this.sync({ trigger: 'ws' });
+            this.triggerSyncInBackground({ trigger: 'ws' }, 'ws cursor wakeup');
           }
         }
       },
@@ -977,7 +1008,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
             this.hasRealtimeConnectedOnce = true;
             this.setConnectionState('connected');
             this.stopFallbackPolling();
-            this.sync();
+            this.triggerSyncInBackground(undefined, 'realtime connected state');
             if (wasConnectedBefore) {
               this.scheduleRealtimeReconnectCatchupSync();
             }
@@ -1022,9 +1053,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       if (this.isDestroyed || !this.isEnabled()) return;
       if (this.state.connectionState !== 'connected') return;
 
-      this.sync().catch(() => {
-        // Best-effort catch-up sync after reconnect.
-      });
+      this.triggerSyncInBackground(undefined, 'realtime reconnect catchup');
     }, REALTIME_RECONNECT_CATCHUP_DELAY_MS);
   }
 
@@ -1034,7 +1063,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     const interval = this.config.realtimeFallbackPollMs ?? 30_000;
     this.fallbackPollerId = setInterval(() => {
       if (!this.state.isSyncing && !this.isDestroyed) {
-        this.sync();
+        this.triggerSyncInBackground(undefined, 'realtime fallback poll');
       }
     }, interval);
   }
@@ -1087,10 +1116,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     // Polling mode: restart the poller and trigger a sync immediately.
     if (this.state.transportMode === 'polling') {
       this.setupPolling();
-      // Trigger sync in background - errors are handled internally by sync()
-      this.sync().catch((err) => {
-        console.error('Unexpected error during reconnect sync:', err);
-      });
+      this.triggerSyncInBackground(undefined, 'reconnect');
     }
   }
 
@@ -1247,7 +1273,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
   ): void {
     this.config.subscriptions = subscriptions;
     // Trigger a sync to apply new subscriptions
-    this.sync();
+    this.triggerSyncInBackground(undefined, 'subscription update');
   }
 
   /**

package/src/handlers/create-handler.ts

@@ -3,7 +3,7 @@
  */
 
 import type { ScopeDefinition, SyncChange, SyncSnapshot } from '@syncular/core';
-import { normalizeScopes } from '@syncular/core';
+import { isRecord, normalizeScopes } from '@syncular/core';
 import { sql } from 'kysely';
 import type { SyncClientDb } from '../schema';
 import type {
@@ -13,10 +13,6 @@ import type {
   ClientTableHandler,
 } from './types';
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 /**
  * Coerce a value for SQL parameter binding.
  * - PostgreSQL (PGlite) does not implicitly cast booleans to integers,

package/src/mutations.ts

@@ -19,6 +19,7 @@ import type {
   SyncPushResponse,
   SyncTransport,
 } from '@syncular/core';
+import { isRecord, randomId } from '@syncular/core';
 import type { Insertable, Kysely, Transaction, Updateable } from 'kysely';
 import { sql } from 'kysely';
 import { enqueueOutboxCommit } from './outbox';
@@ -138,21 +139,6 @@ export type MutationsApi<DB, CommitOptions = unknown> = {
   [T in KnownTableKey<DB>]: TableMutations<DB, T>;
 };
 
-function randomId(): string {
-  if (
-    typeof crypto !== 'undefined' &&
-    typeof crypto.randomUUID === 'function'
-  ) {
-    return crypto.randomUUID();
-  }
-  // Very small fallback; good enough for tests.
-  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function sanitizePayload(
   payload: Record<string, unknown>,
   args: { omit: string[] }

package/src/outbox.ts

@@ -3,6 +3,7 @@
  */
 
 import type { SyncOperation } from '@syncular/core';
+import { isRecord, randomId } from '@syncular/core';
 import type { Kysely } from 'kysely';
 import { sql } from 'kysely';
 import type { OutboxCommitStatus, SyncClientDb } from './schema';
@@ -22,21 +23,6 @@ export interface OutboxCommit {
   schema_version: number;
 }
 
-function randomId(): string {
-  if (
-    typeof crypto !== 'undefined' &&
-    typeof crypto.randomUUID === 'function'
-  ) {
-    return crypto.randomUUID();
-  }
-  // Very small fallback; good enough for tests.
-  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function isSyncOperation(value: unknown): value is SyncOperation {
   if (!isRecord(value)) return false;
   if (typeof value.table !== 'string') return false;