@syncular/client 0.0.6-56 → 0.0.6-67

package/src/create-client.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import type { Kysely } from 'kysely';
+import { createBunSqliteDb } from '../../dialect-bun-sqlite/src';
+import { createClient } from './create-client';
+import type { SyncClientDb } from './schema';
+
+interface TasksTable {
+  id: string;
+  user_id: string;
+  title: string;
+  server_version: number;
+}
+
+interface TestDb extends SyncClientDb {
+  tasks: TasksTable;
+}
+
+async function createTestDb(): Promise<Kysely<TestDb>> {
+  const db = createBunSqliteDb<TestDb>({ path: ':memory:' });
+  await db.schema
+    .createTable('tasks')
+    .addColumn('id', 'text', (col) => col.primaryKey())
+    .addColumn('user_id', 'text', (col) => col.notNull())
+    .addColumn('title', 'text', (col) => col.notNull())
+    .addColumn('server_version', 'integer', (col) => col.notNull().defaultTo(0))
+    .execute();
+  return db;
+}
+
+describe('createClient url normalization', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('accepts sync endpoint URLs without duplicating /sync', async () => {
+    const requests: string[] = [];
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const request = input instanceof Request ? input : new Request(input);
+      requests.push(request.url);
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          pull: { ok: true, subscriptions: [] },
+        }),
+        {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }
+      );
+    }) as typeof fetch;
+
+    const db = await createTestDb();
+    try {
+      const { destroy } = await createClient<TestDb>({
+        db,
+        actorId: 'user-1',
+        clientId: 'client-1',
+        url: 'http://localhost:4311/api/sync',
+        handlers: [
+          {
+            table: 'tasks',
+            subscribe: false,
+            async applySnapshot() {},
+            async clearAll() {},
+            async applyChange() {},
+          },
+        ],
+      });
+
+      destroy();
+      expect(requests).toContain('http://localhost:4311/api/sync');
+      expect(requests).not.toContain('http://localhost:4311/api/sync/sync');
+    } finally {
+      await db.destroy();
+    }
+  });
+});

package/src/create-client.ts

@@ -2,7 +2,7 @@
  * Simplified client factory
  *
  * Breaking changes from legacy Client:
- * - handlers: array instead of ClientTableRegistry
+ * - handlers: plain array (no registry class)
  * - url: string instead of transport (transport auto-created)
  * - subscriptions: derived from handler.subscribe (no separate param)
  * - clientId: auto-generated (no longer required)
@@ -19,8 +19,8 @@ import { extractScopeVars } from '@syncular/core';
 import { createHttpTransport } from '@syncular/transport-http';
 import type { Kysely } from 'kysely';
 import { Client } from './client';
+import { createClientHandlerCollection } from './handlers/collection';
 import { createClientHandler } from './handlers/create-handler';
-import { ClientTableRegistry } from './handlers/registry';
 import type { ClientTableHandler } from './handlers/types';
 import type { SyncClientDb } from './schema';
 import { randomUUID } from './utils/id';
@@ -75,12 +75,22 @@ function createAutoHandler<
   });
 }
 
+function normalizeTransportBaseUrl(url: string): string {
+  const trimmed = url.trim().replace(/\/+$/, '');
+  if (!trimmed.endsWith('/sync')) {
+    return trimmed;
+  }
+
+  const baseUrl = trimmed.slice(0, -'/sync'.length);
+  return baseUrl.length > 0 ? baseUrl : '/';
+}
+
 interface CreateClientOptions<DB extends SyncClientDb> {
   /** Kysely database instance */
   db: Kysely<DB>;
 
   /**
-   * Server URL (e.g., '/api/sync' or 'https://api.example.com').
+   * Sync URL (e.g., '/api/sync') or base API URL (e.g., '/api').
    * Defaults to '/api/sync' if not provided.
    * Ignored if transport is provided.
    */
@@ -88,7 +98,6 @@ interface CreateClientOptions<DB extends SyncClientDb> {
 
   /**
    * Table handlers for applying snapshots and changes.
-   * Array is auto-converted to ClientTableRegistry.
    * Handlers with `subscribe: true` (or an object) are synced.
    * Handlers with `subscribe: false` are local-only.
    * Either handlers or tables must be provided.
@@ -234,17 +243,13 @@ export async function createClient<DB extends SyncClientDb>(
       })
     );
 
-  // Build registry from handlers array
-  const tableHandlers = new ClientTableRegistry<DB>();
-  for (const handler of handlers) {
-    tableHandlers.register(handler);
-  }
+  const tableHandlers = createClientHandlerCollection(handlers);
 
   // Create transport from URL if not provided
   let transport = customTransport;
   if (!transport && url) {
     transport = createHttpTransport({
-      baseUrl: url,
+      baseUrl: normalizeTransportBaseUrl(url),
       getHeaders,
     });
   }

package/src/engine/SyncEngine.test.ts

@@ -3,7 +3,7 @@ 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 type { ClientHandlerCollection } from '../handlers/collection';
 import { ensureClientSyncSchema } from '../migrate';
 import type { SyncClientDb } from '../schema';
 import { SyncEngine } from './SyncEngine';
@@ -74,29 +74,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 +158,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 +197,48 @@ 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 = createBunSqliteDb<TestDb>({ path: ':memory:' });
+    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();
+    }
+  });
 });

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}"`
@@ -2287,7 +2293,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/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/pull-engine.test.ts

@@ -7,8 +7,8 @@ import {
 } from '@syncular/core';
 import { type Kysely, sql } from 'kysely';
 import { createBunSqliteDb } from '../../dialect-bun-sqlite/src';
+import type { ClientHandlerCollection } from './handlers/collection';
 import { createClientHandler } from './handlers/create-handler';
-import { ClientTableRegistry } from './handlers/registry';
 import { ensureClientSyncSchema } from './migrate';
 import { applyPullResponse, buildPullRequest } from './pull-engine';
 import type { SyncClientDb } from './schema';
@@ -75,12 +75,12 @@ describe('applyPullResponse chunk streaming', () => {
       },
     };
 
-    const handlers = new ClientTableRegistry<TestDb>().register(
+    const handlers: ClientHandlerCollection<TestDb> = [
       createClientHandler({
         table: 'items',
         scopes: ['items:{id}'],
-      })
-    );
+      }),
+    ];
 
     const options = {
       clientId: 'client-1',

package/src/pull-engine.ts

@@ -12,7 +12,10 @@ import type {
 } from '@syncular/core';
 import { decodeSnapshotRows } from '@syncular/core';
 import { type Kysely, sql, type Transaction } from 'kysely';
-import type { ClientTableRegistry } from './handlers/registry';
+import {
+  type ClientHandlerCollection,
+  getClientHandlerOrThrow,
+} from './handlers/collection';
 import type { ClientTableHandler } from './handlers/types';
 import type {
   SyncClientPlugin,
@@ -573,7 +576,7 @@ export async function buildPullRequest<DB extends SyncClientDb>(
 export async function applyPullResponse<DB extends SyncClientDb>(
   db: Kysely<DB>,
   transport: SyncTransport,
-  handlers: ClientTableRegistry<DB>,
+  handlers: ClientHandlerCollection<DB>,
   options: SyncPullOnceOptions,
   pullState: {
     request: SyncPullRequest;
@@ -620,7 +623,10 @@ export async function applyPullResponse<DB extends SyncClientDb>(
               ? JSON.parse(row.scopes_json)
               : row.scopes_json
             : {};
-          await handlers.getOrThrow(row.table).clearAll({ trx, scopes });
+          await getClientHandlerOrThrow(handlers, row.table).clearAll({
+            trx,
+            scopes,
+          });
         } catch {
           // ignore missing table handler
         }
@@ -649,7 +655,10 @@ export async function applyPullResponse<DB extends SyncClientDb>(
                 ? JSON.parse(prev.scopes_json)
                 : prev.scopes_json
               : {};
-            await handlers.getOrThrow(prev.table).clearAll({ trx, scopes });
+            await getClientHandlerOrThrow(handlers, prev.table).clearAll({
+              trx,
+              scopes,
+            });
           } catch {
             // ignore missing handler
           }
@@ -666,7 +675,7 @@ export async function applyPullResponse<DB extends SyncClientDb>(
       // Apply snapshots (bootstrap mode)
       if (sub.bootstrap) {
         for (const snapshot of sub.snapshots ?? []) {
-          const handler = handlers.getOrThrow(snapshot.table);
+          const handler = getClientHandlerOrThrow(handlers, snapshot.table);
           const hasChunkRefs =
             Array.isArray(snapshot.chunks) && snapshot.chunks.length > 0;
 
@@ -698,7 +707,7 @@ export async function applyPullResponse<DB extends SyncClientDb>(
         // Apply incremental changes
         for (const commit of sub.commits) {
           for (const change of commit.changes) {
-            const handler = handlers.getOrThrow(change.table);
+            const handler = getClientHandlerOrThrow(handlers, change.table);
             await handler.applyChange({ trx }, change);
           }
         }
@@ -763,7 +772,7 @@ export async function applyPullResponse<DB extends SyncClientDb>(
 export async function syncPullOnce<DB extends SyncClientDb>(
   db: Kysely<DB>,
   transport: SyncTransport,
-  handlers: ClientTableRegistry<DB>,
+  handlers: ClientHandlerCollection<DB>,
   options: SyncPullOnceOptions
 ): Promise<SyncPullResponse> {
   const pullState = await buildPullRequest(db, options);

package/src/sync-loop.ts

@@ -14,7 +14,7 @@ import type {
 } from '@syncular/core';
 import type { Kysely } from 'kysely';
 import { upsertConflictsForRejectedCommit } from './conflicts';
-import type { ClientTableRegistry } from './handlers/registry';
+import type { ClientHandlerCollection } from './handlers/collection';
 import {
   getNextSendableOutboxCommit,
   markOutboxCommitAcked,
@@ -119,7 +119,7 @@ function mergePullResponse(
 async function syncPullUntilSettled<DB extends SyncClientDb>(
   db: Kysely<DB>,
   transport: SyncTransport,
-  handlers: ClientTableRegistry<DB>,
+  handlers: ClientHandlerCollection<DB>,
   options: SyncPullUntilSettledOptions
 ): Promise<SyncPullUntilSettledResult> {
   const maxRounds = Math.max(1, Math.min(1000, options.maxRounds ?? 20));
@@ -182,7 +182,7 @@ export interface SyncOnceResult {
 async function syncOnceCombined<DB extends SyncClientDb>(
   db: Kysely<DB>,
   transport: SyncTransport,
-  handlers: ClientTableRegistry<DB>,
+  handlers: ClientHandlerCollection<DB>,
   options: SyncOnceOptions
 ): Promise<SyncOnceResult> {
   const pullOpts: SyncPullOnceOptions = {
@@ -364,7 +364,7 @@ async function syncOnceCombined<DB extends SyncClientDb>(
 export async function syncOnce<DB extends SyncClientDb>(
   db: Kysely<DB>,
   transport: SyncTransport,
-  handlers: ClientTableRegistry<DB>,
+  handlers: ClientHandlerCollection<DB>,
   options: SyncOnceOptions
 ): Promise<SyncOnceResult> {
   return syncOnceCombined(db, transport, handlers, options);