@syncular/client 0.0.5-42 → 0.0.6-101

package/src/engine/SyncEngine.test.ts

@@ -1,9 +1,14 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import type { SyncChange, SyncTransport } from '@syncular/core';
+import {
+  createDatabase,
+  type SyncChange,
+  type SyncTransport,
+  SyncTransportError,
+} 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 { createBunSqliteDialect } from '../../../dialect-bun-sqlite/src';
+import type { ClientHandlerCollection } from '../handlers/collection';
 import { ensureClientSyncSchema } from '../migrate';
 import type { SyncClientDb } from '../schema';
 import { SyncEngine } from './SyncEngine';
@@ -31,7 +36,10 @@ describe('SyncEngine WS inline apply', () => {
   let db: Kysely<TestDb>;
 
   beforeEach(async () => {
-    db = createBunSqliteDb<TestDb>({ path: ':memory:' });
+    db = createDatabase<TestDb>({
+      dialect: createBunSqliteDialect({ path: ':memory:' }),
+      family: 'sqlite',
+    });
     await ensureClientSyncSchema(db);
 
     await db.schema
@@ -74,29 +82,31 @@ describe('SyncEngine WS inline apply', () => {
   });
 
   it('rolls back row updates and cursor when any inline WS change fails', async () => {
-    const handlers = 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 handlers: ClientHandlerCollection<TestDb> = [
+      {
+        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,
@@ -156,12 +166,14 @@ describe('SyncEngine WS inline apply', () => {
   });
 
   it('returns a bounded inspector snapshot with serializable events', async () => {
-    const handlers = new ClientTableRegistry<TestDb>().register({
-      table: 'tasks',
-      async applySnapshot() {},
-      async clearAll() {},
-      async applyChange() {},
-    });
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {},
+        async clearAll() {},
+        async applyChange() {},
+      },
+    ];
 
     const engine = new SyncEngine<TestDb>({
       db,
@@ -193,4 +205,201 @@ describe('SyncEngine WS inline apply', () => {
     expect(typeof first.payload).toBe('object');
     expect(snapshot.diagnostics).toBeDefined();
   });
+
+  it('ensures sync schema on start without custom migrate callback', async () => {
+    const coldDb = createDatabase<TestDb>({
+      dialect: createBunSqliteDialect({ path: ':memory:' }),
+      family: 'sqlite',
+    });
+    try {
+      await coldDb.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();
+
+      const handlers: ClientHandlerCollection<TestDb> = [
+        {
+          table: 'tasks',
+          async applySnapshot() {},
+          async clearAll() {},
+          async applyChange() {},
+        },
+      ];
+
+      const engine = new SyncEngine<TestDb>({
+        db: coldDb,
+        transport: noopTransport,
+        handlers,
+        actorId: 'u1',
+        clientId: 'client-migrate',
+        subscriptions: [],
+      });
+
+      await engine.start();
+
+      const exists = await sql<{ count: number }>`
+        select count(*) as count
+        from sqlite_master
+        where type = 'table' and name = 'sync_subscription_state'
+      `.execute(coldDb);
+
+      expect(Number(exists.rows[0]?.count ?? 0)).toBe(1);
+    } finally {
+      await coldDb.destroy();
+    }
+  });
+
+  it('classifies missing snapshot chunk pull failures as non-retryable', async () => {
+    const missingChunkTransport: SyncTransport = {
+      async sync() {
+        throw new SyncTransportError('snapshot chunk not found', 404);
+      },
+      async fetchSnapshotChunk() {
+        return new Uint8Array();
+      },
+    };
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {},
+        async clearAll() {},
+        async applyChange() {},
+      },
+    ];
+
+    const engine = new SyncEngine<TestDb>({
+      db,
+      transport: missingChunkTransport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-missing-chunk',
+      subscriptions: [
+        {
+          id: 'sub-1',
+          table: 'tasks',
+          scopes: {},
+        },
+      ],
+      stateId: 'default',
+      pollIntervalMs: 60_000,
+      maxRetries: 3,
+    });
+
+    await engine.start();
+    engine.stop();
+
+    const state = engine.getState();
+    expect(state.error?.code).toBe('SNAPSHOT_CHUNK_NOT_FOUND');
+    expect(state.error?.retryable).toBe(false);
+    expect(state.retryCount).toBe(1);
+    expect(state.isRetrying).toBe(false);
+  });
+
+  it('repairs rebootstrap-missing-chunks by clearing synced state and data', async () => {
+    const outboxId = 'outbox-1';
+    const now = Date.now();
+
+    await db
+      .insertInto('tasks')
+      .values({
+        id: 't2',
+        title: 'to-clear',
+        server_version: 2,
+      })
+      .execute();
+
+    await db
+      .insertInto('sync_outbox_commits')
+      .values({
+        id: outboxId,
+        client_commit_id: 'client-commit-1',
+        status: 'pending',
+        operations_json: '[]',
+        last_response_json: null,
+        error: null,
+        created_at: now,
+        updated_at: now,
+        acked_commit_seq: null,
+      })
+      .execute();
+
+    await db
+      .insertInto('sync_conflicts')
+      .values({
+        id: 'conflict-1',
+        outbox_commit_id: outboxId,
+        client_commit_id: 'client-commit-1',
+        op_index: 0,
+        result_status: 'conflict',
+        message: 'forced conflict',
+        code: 'TEST_CONFLICT',
+        server_version: 1,
+        server_row_json: '{}',
+        created_at: now,
+        resolved_at: null,
+        resolution: null,
+      })
+      .execute();
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {},
+        async clearAll(ctx) {
+          await sql`delete from ${sql.table('tasks')}`.execute(ctx.trx);
+        },
+        async applyChange() {},
+      },
+    ];
+
+    const engine = new SyncEngine<TestDb>({
+      db,
+      transport: noopTransport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-repair',
+      subscriptions: [],
+      stateId: 'default',
+    });
+
+    const result = await engine.repair({
+      mode: 'rebootstrap-missing-chunks',
+      clearOutbox: true,
+      clearConflicts: true,
+    });
+
+    expect(result.deletedSubscriptionStates).toBe(1);
+    expect(result.deletedOutboxCommits).toBe(1);
+    expect(result.deletedConflicts).toBe(1);
+    expect(result.clearedTables).toEqual(['tasks']);
+
+    const tasksCount = await db
+      .selectFrom('tasks')
+      .select(({ fn }) => fn.countAll().as('total'))
+      .executeTakeFirst();
+    expect(Number(tasksCount?.total ?? 0)).toBe(0);
+
+    const subscriptionsCount = await db
+      .selectFrom('sync_subscription_state')
+      .select(({ fn }) => fn.countAll().as('total'))
+      .executeTakeFirst();
+    expect(Number(subscriptionsCount?.total ?? 0)).toBe(0);
+
+    const outboxCount = await db
+      .selectFrom('sync_outbox_commits')
+      .select(({ fn }) => fn.countAll().as('total'))
+      .executeTakeFirst();
+    expect(Number(outboxCount?.total ?? 0)).toBe(0);
+
+    const conflictsCount = await db
+      .selectFrom('sync_conflicts')
+      .select(({ fn }) => fn.countAll().as('total'))
+      .executeTakeFirst();
+    expect(Number(conflictsCount?.total ?? 0)).toBe(0);
+  });
 });

package/src/engine/SyncEngine.ts

@@ -18,6 +18,8 @@ import {
   startSyncSpan,
 } from '@syncular/core';
 import { type Kysely, sql, type Transaction } from 'kysely';
+import { getClientHandler } from '../handlers/collection';
+import { ensureClientSyncSchema } from '../migrate';
 import { syncPushOnce } from '../push-engine';
 import type {
   ConflictResultStatus,
@@ -1005,7 +1007,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     }
 
     if (options.scope === 'all') {
-      for (const handler of this.config.handlers.getAll()) {
+      for (const handler of this.config.handlers) {
         await handler.clearAll({ trx, scopes: {} });
         clearedTables.push(handler.table);
       }
@@ -1014,7 +1016,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
 
     const seen = new Set<string>();
     for (const target of targets) {
-      const handler = this.config.handlers.get(target.table);
+      const handler = getClientHandler(this.config.handlers, target.table);
       if (!handler) continue;
 
       const key = `${target.table}:${JSON.stringify(target.scopes)}`;
@@ -1220,40 +1222,44 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
 
     this.updateState({ enabled: true });
 
-    // Run migration if provided
-    if (this.config.migrate && !this.migrated) {
-      // Best-effort: push any pending outbox commits before migration
-      // (migration may reset the DB, so we try to save unsynced changes)
-      try {
-        const hasOutbox = await sql`
-          select 1 from ${sql.table('sync_outbox_commits')} limit 1
-        `
-          .execute(this.config.db)
-          .then((r) => r.rows.length > 0)
-          .catch(() => false);
-
-        if (hasOutbox) {
-          // Push all pending commits (best effort)
-          let pushed = true;
-          while (pushed) {
-            const result = await syncPushOnce(
-              this.config.db,
-              this.config.transport,
-              {
-                clientId: this.config.clientId!,
-                actorId: this.config.actorId ?? undefined,
-                plugins: this.config.plugins,
-              }
-            );
-            pushed = result.pushed;
+    // Run migrations before first sync.
+    if (!this.migrated) {
+      // Best-effort: push pending commits before user migration, because
+      // app migrations may reset tables and discard unsynced local writes.
+      if (this.config.migrate) {
+        try {
+          const hasOutbox = await sql`
+            select 1 from ${sql.table('sync_outbox_commits')} limit 1
+          `
+            .execute(this.config.db)
+            .then((r) => r.rows.length > 0)
+            .catch(() => false);
+
+          if (hasOutbox) {
+            let pushed = true;
+            while (pushed) {
+              const result = await syncPushOnce(
+                this.config.db,
+                this.config.transport,
+                {
+                  clientId: this.config.clientId!,
+                  actorId: this.config.actorId ?? undefined,
+                  plugins: this.config.plugins,
+                }
+              );
+              pushed = result.pushed;
+            }
           }
+        } catch {
+          // Best-effort: continue even if pre-migration push fails.
         }
-      } catch {
-        // Best-effort: if push fails (network down, table missing), continue
       }
 
       try {
-        await this.config.migrate(this.config.db);
+        if (this.config.migrate) {
+          await this.config.migrate(this.config.db);
+        }
+        await ensureClientSyncSchema(this.config.db);
         this.migrated = true;
       } catch (err) {
         const migrationError =
@@ -1597,7 +1603,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     try {
       await this.config.db.transaction().execute(async (trx) => {
         for (const change of changes) {
-          const handler = this.config.handlers.get(change.table);
+          const handler = getClientHandler(this.config.handlers, change.table);
           if (!handler) {
             throw new Error(
               `Missing client table handler for WS change table "${change.table}"`
@@ -1852,6 +1858,13 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     }
 
     const delay = calculateRetryDelay(this.state.retryCount);
+    if (this.state.pendingCount > 0) {
+      countSyncMetric('sync.outbox.retry_count', 1, {
+        attributes: {
+          retryCount: this.state.retryCount,
+        },
+      });
+    }
     this.updateState({ isRetrying: true });
 
     this.retryTimeoutId = setTimeout(() => {
@@ -1975,6 +1988,13 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
           case 'connected': {
             const wasConnectedBefore = this.hasRealtimeConnectedOnce;
             this.hasRealtimeConnectedOnce = true;
+            if (wasConnectedBefore) {
+              countSyncMetric('sync.transport.reconnects', 1, {
+                attributes: {
+                  source: 'client',
+                },
+              });
+            }
             this.setConnectionState('connected');
             this.updateTransportHealth({
               mode: 'realtime',
@@ -2287,7 +2307,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
 
     await db.transaction().execute(async (trx) => {
       for (const input of inputs) {
-        const handler = handlers.get(input.table);
+        const handler = getClientHandler(handlers, input.table);
         if (!handler) continue;
 
         affectedTables.add(input.table);

package/src/engine/types.ts

@@ -12,7 +12,7 @@ import type {
   SyncTransport,
 } from '@syncular/core';
 import type { Kysely } from 'kysely';
-import type { ClientTableRegistry } from '../handlers/registry';
+import type { ClientHandlerCollection } from '../handlers/collection';
 import type { SyncClientPlugin } from '../plugins/types';
 import type { SyncClientDb } from '../schema';
 import type { SubscriptionState } from '../subscription-state';
@@ -225,7 +225,7 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   /** Sync transport */
   transport: SyncTransport;
   /** Client table handler registry */
-  handlers: ClientTableRegistry<DB>;
+  handlers: ClientHandlerCollection<DB>;
   /** Actor id for sync scoping (null/undefined disables sync) */
   actorId: string | null | undefined;
   /** Stable device/app installation id */
@@ -244,7 +244,7 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   pollIntervalMs?: number;
   /** Max retries before giving up */
   maxRetries?: number;
-  /** Migration function to run before first sync */
+  /** Optional app migration to run before sync schema migration. */
   migrate?: (db: Kysely<DB>) => Promise<void>;
   /** Called when migration fails. Receives the error. */
   onMigrationError?: (error: Error) => void;

package/src/handlers/collection.ts

@@ -0,0 +1,36 @@
+import type { ClientTableHandler } from './types';
+
+export type ClientHandlerCollection<DB> = ClientTableHandler<DB>[];
+
+export function createClientHandlerCollection<DB>(
+  handlers: ClientTableHandler<DB>[]
+): ClientHandlerCollection<DB> {
+  const tables = new Set<string>();
+  for (const handler of handlers) {
+    if (tables.has(handler.table)) {
+      throw new Error(
+        `Client table handler already registered: ${handler.table}`
+      );
+    }
+    tables.add(handler.table);
+  }
+  return handlers;
+}
+
+export function getClientHandler<DB>(
+  handlers: ClientHandlerCollection<DB>,
+  table: string
+): ClientTableHandler<DB> | undefined {
+  return handlers.find((handler) => handler.table === table);
+}
+
+export function getClientHandlerOrThrow<DB>(
+  handlers: ClientHandlerCollection<DB>,
+  table: string
+): ClientTableHandler<DB> {
+  const handler = getClientHandler(handlers, table);
+  if (!handler) {
+    throw new Error(`Missing client table handler for table: ${table}`);
+  }
+  return handler;
+}

package/src/handlers/create-handler.ts

@@ -82,7 +82,7 @@ export interface CreateClientHandlerOptions<
    * Optional column codec resolver.
    * Receives `{ table, column, sqlType?, dialect? }` and returns a codec.
    */
-  columnCodecs?: ColumnCodecSource;
+  codecs?: ColumnCodecSource;
 
   /**
    * Dialect used for codec dialect overrides.
@@ -178,14 +178,14 @@ export function createClientHandler<
   const codecDialect = options.codecDialect ?? 'sqlite';
   const codecCache = new Map<string, ReturnType<typeof toTableColumnCodecs>>();
   const resolveTableCodecs = (row: Record<string, unknown>) => {
-    const columnCodecs = options.columnCodecs;
-    if (!columnCodecs) return {};
+    const codecs = options.codecs;
+    if (!codecs) return {};
     const columns = Object.keys(row);
     if (columns.length === 0) return {};
     const cacheKey = columns.slice().sort().join('\u0000');
     const cached = codecCache.get(cacheKey);
     if (cached) return cached;
-    const resolved = toTableColumnCodecs(table, columnCodecs, columns, {
+    const resolved = toTableColumnCodecs(table, codecs, columns, {
       dialect: codecDialect,
     });
     codecCache.set(cacheKey, resolved);

package/src/index.ts

@@ -9,8 +9,8 @@ export * from './client';
 export * from './conflicts';
 export * from './create-client';
 export * from './engine';
+export * from './handlers/collection';
 export * from './handlers/create-handler';
-export * from './handlers/registry';
 export * from './handlers/types';
 export * from './migrate';
 export * from './mutations';
@@ -22,5 +22,6 @@ export * from './push-engine';
 export * from './query';
 export * from './schema';
 export * from './subscription-state';
+export * from './sync';
 export * from './sync-loop';
 export * from './utils/id';

package/src/migrate.ts

@@ -182,6 +182,13 @@ async function ensureClientSyncSchemaCompat<DB extends SyncClientDb>(
       .addColumn('resolution', 'text')
       .execute();
   });
+
+  await db.schema
+    .createIndex('idx_sync_outbox_commits_status_updated_at')
+    .ifNotExists()
+    .on('sync_outbox_commits')
+    .columns(['status', 'updated_at', 'created_at'])
+    .execute();
 }
 
 /**
@@ -275,6 +282,13 @@ export async function ensureClientSyncSchema<DB extends SyncClientDb>(
     .columns(['status', 'created_at'])
     .execute();
 
+  await db.schema
+    .createIndex('idx_sync_outbox_commits_status_updated_at')
+    .ifNotExists()
+    .on('sync_outbox_commits')
+    .columns(['status', 'updated_at', 'created_at'])
+    .execute();
+
   await db.schema
     .createIndex('idx_sync_conflicts_outbox_commit')
     .ifNotExists()

package/src/mutations.ts

@@ -400,7 +400,7 @@ export interface OutboxCommitConfig<DB extends SyncClientDb> {
   idColumn?: string;
   versionColumn?: string | null;
   omitColumns?: string[];
-  columnCodecs?: ColumnCodecSource;
+  codecs?: ColumnCodecSource;
   codecDialect?: ColumnCodecDialect;
 }
 
@@ -432,8 +432,8 @@ export function createOutboxCommit<DB extends SyncClientDb>(
           table: string,
           row: Record<string, unknown>
         ) => {
-          const columnCodecs = config.columnCodecs;
-          if (!columnCodecs) return {};
+          const codecs = config.codecs;
+          if (!codecs) return {};
           const columns = Object.keys(row);
           if (columns.length === 0) return {};
 
@@ -450,7 +450,7 @@ export function createOutboxCommit<DB extends SyncClientDb>(
           const cached = tableCache.get(cacheKey);
           if (cached) return cached;
 
-          const resolved = toTableColumnCodecs(table, columnCodecs, columns, {
+          const resolved = toTableColumnCodecs(table, codecs, columns, {
             dialect: codecDialect,
           });
           tableCache.set(cacheKey, resolved);