@syncular/client 0.0.1-100

package/src/conflicts.ts

@@ -0,0 +1,171 @@
+/**
+ * @syncular/client - Sync conflict storage helpers
+ */
+
+import type { SyncOperationResult, SyncPushResponse } from '@syncular/core';
+import { randomId } from '@syncular/core';
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import type { SyncClientDb } from './schema';
+
+function messageFromResult(
+  r: Extract<SyncOperationResult, { status: 'conflict' | 'error' }>
+): {
+  message: string;
+  code: string | null;
+  serverVersion: number | null;
+  serverRowJson: string | null;
+} {
+  if (r.status === 'conflict') {
+    return {
+      message: r.message,
+      code: 'CONFLICT',
+      serverVersion: r.server_version,
+      serverRowJson: JSON.stringify(r.server_row),
+    };
+  }
+
+  return {
+    message: r.error,
+    code: r.code ?? null,
+    serverVersion: null,
+    serverRowJson: null,
+  };
+}
+
+export async function upsertConflictsForRejectedCommit<DB extends SyncClientDb>(
+  db: Kysely<DB>,
+  args: {
+    outboxCommitId: string;
+    clientCommitId: string;
+    response: SyncPushResponse;
+    nowMs?: number;
+  }
+): Promise<number> {
+  const now = args.nowMs ?? Date.now();
+
+  // Remove any previous conflict rows for this outbox commit.
+  await sql`
+    delete from ${sql.table('sync_conflicts')}
+    where ${sql.ref('outbox_commit_id')} = ${sql.val(args.outboxCommitId)}
+  `.execute(db);
+
+  const conflictResults = args.response.results.filter(
+    (r) => r.status === 'conflict' || r.status === 'error'
+  );
+
+  if (conflictResults.length === 0) return 0;
+
+  const rows = conflictResults.map((r) => {
+    const info = messageFromResult(r);
+    return {
+      id: randomId(),
+      outbox_commit_id: args.outboxCommitId,
+      client_commit_id: args.clientCommitId,
+      op_index: r.opIndex,
+      result_status: r.status,
+      message: info.message,
+      code: info.code,
+      server_version: info.serverVersion,
+      server_row_json: info.serverRowJson,
+      created_at: now,
+      resolved_at: null,
+      resolution: null,
+    };
+  });
+
+  const insertColumns = [
+    'id',
+    'outbox_commit_id',
+    'client_commit_id',
+    'op_index',
+    'result_status',
+    'message',
+    'code',
+    'server_version',
+    'server_row_json',
+    'created_at',
+    'resolved_at',
+    'resolution',
+  ] as const;
+
+  await sql`
+    insert into ${sql.table('sync_conflicts')} (
+      ${sql.join(insertColumns.map((c) => sql.ref(c)))}
+    ) values ${sql.join(
+      rows.map(
+        (row) =>
+          sql`(${sql.join(
+            [
+              sql.val(row.id),
+              sql.val(row.outbox_commit_id),
+              sql.val(row.client_commit_id),
+              sql.val(row.op_index),
+              sql.val(row.result_status),
+              sql.val(row.message),
+              sql.val(row.code),
+              sql.val(row.server_version),
+              sql.val(row.server_row_json),
+              sql.val(row.created_at),
+              sql.val(row.resolved_at),
+              sql.val(row.resolution),
+            ],
+            sql`, `
+          )})`
+      ),
+      sql`, `
+    )}
+  `.execute(db);
+
+  return conflictResults.length;
+}
+
+export type PendingConflictRow = {
+  id: string;
+  outbox_commit_id: string;
+  client_commit_id: string;
+  op_index: number;
+  result_status: string;
+  message: string;
+  code: string | null;
+  server_version: number | null;
+  server_row_json: string | null;
+  created_at: number;
+};
+
+export async function listPendingConflicts<DB extends SyncClientDb>(
+  db: Kysely<DB>
+): Promise<PendingConflictRow[]> {
+  const res = await sql<PendingConflictRow>`
+    select
+      ${sql.ref('id')},
+      ${sql.ref('outbox_commit_id')},
+      ${sql.ref('client_commit_id')},
+      ${sql.ref('op_index')},
+      ${sql.ref('result_status')},
+      ${sql.ref('message')},
+      ${sql.ref('code')},
+      ${sql.ref('server_version')},
+      ${sql.ref('server_row_json')},
+      ${sql.ref('created_at')}
+    from ${sql.table('sync_conflicts')}
+    where ${sql.ref('resolved_at')} is null
+    order by ${sql.ref('created_at')} desc
+  `.execute(db);
+
+  return res.rows;
+}
+
+export async function resolveConflict<DB extends SyncClientDb>(
+  db: Kysely<DB>,
+  args: { id: string; resolution: string; nowMs?: number }
+): Promise<void> {
+  const now = args.nowMs ?? Date.now();
+  await sql`
+    update ${sql.table('sync_conflicts')}
+    set
+      ${sql.ref('resolved_at')} = ${sql.val(now)},
+      ${sql.ref('resolution')} = ${sql.val(args.resolution)}
+    where ${sql.ref('id')} = ${sql.val(args.id)}
+  `.execute(db);
+}

package/src/create-client.ts

@@ -0,0 +1,297 @@
+/**
+ * Simplified client factory
+ *
+ * Breaking changes from legacy Client:
+ * - handlers: array instead of ClientTableRegistry
+ * - url: string instead of transport (transport auto-created)
+ * - subscriptions: derived from handler.subscribe (no separate param)
+ * - clientId: auto-generated (no longer required)
+ */
+
+import type {
+  ScopeDefinition,
+  ScopeValues,
+  SyncTransport,
+} from '@syncular/core';
+import { extractScopeVars } from '@syncular/core';
+import { createHttpTransport } from '@syncular/transport-http';
+import type { Kysely } from 'kysely';
+import { Client } from './client';
+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';
+
+function deriveDefaultSubscriptionScopes<DB>(args: {
+  handler: Pick<ClientTableHandler<DB>, 'table' | 'scopePatterns'>;
+  actorId: string;
+}): ScopeValues {
+  const patterns = args.handler.scopePatterns ?? [];
+  const vars = new Set<string>();
+  for (const pattern of patterns) {
+    for (const v of extractScopeVars(pattern)) {
+      vars.add(v);
+    }
+  }
+
+  const allVars = Array.from(vars);
+  if (allVars.length !== 1) {
+    throw new Error(
+      `Handler "${args.handler.table}" has subscribe=true but no explicit subscription scopes. ` +
+        'Set subscribe: { scopes: { ... } } on the handler. ' +
+        `(Cannot infer defaults from scopePatterns: ${
+          patterns.length > 0 ? patterns.join(', ') : '(none)'
+        })`
+    );
+  }
+
+  const varName = allVars[0]!;
+  return { [varName]: args.actorId };
+}
+
+/**
+ * Auto-generate a simple handler for a table.
+ * Uses 'id' as primary key and provided scopes.
+ */
+function createAutoHandler<
+  DB extends SyncClientDb,
+  TableName extends keyof DB & string,
+>(table: string, scopes: string[]): ClientTableHandler<DB, TableName> {
+  return createClientHandler<DB, TableName>({
+    table: table as TableName,
+    scopes: scopes as ScopeDefinition[],
+  });
+}
+
+interface CreateClientOptions<DB extends SyncClientDb> {
+  /** Kysely database instance */
+  db: Kysely<DB>;
+
+  /**
+   * Server URL (e.g., '/api/sync' or 'https://api.example.com').
+   * Defaults to '/api/sync' if not provided.
+   * Ignored if transport is provided.
+   */
+  url?: string;
+
+  /**
+   * 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.
+   */
+  handlers?: Array<ClientTableHandler<DB>>;
+
+  /**
+   * Table names to auto-generate handlers for.
+   * Uses default scopes and primary key 'id'.
+   * Either handlers or tables must be provided.
+   *
+   * @example
+   * ```typescript
+   * tables: ['tasks', 'notes', 'projects']
+   * ```
+   */
+  tables?: string[];
+
+  /**
+   * Default scopes for auto-generated table handlers.
+   * Required when using tables option.
+   * Ignored when handlers are provided.
+   */
+  scopes?: string[];
+
+  /** Current actor/user identifier */
+  actorId: string;
+
+  /** Optional: Custom client ID (auto-generated UUID if not provided) */
+  clientId?: string;
+
+  /** Optional: Custom transport (overrides url) */
+  transport?: SyncTransport;
+
+  /** Optional: Function to get auth headers */
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+
+  /** Optional: Sync configuration */
+  sync?: {
+    /** Enable realtime/WebSocket mode (default: true) */
+    realtime?: boolean;
+    /** Polling interval in ms (default: 10000) */
+    pollIntervalMs?: number;
+  };
+
+  /** Optional: Local blob storage adapter */
+  blobStorage?: import('./client').ClientBlobStorage;
+
+  /** Optional: Sync plugins */
+  plugins?: import('./plugins').SyncClientPlugin[];
+
+  /** Optional: State ID for multi-tenant scenarios */
+  stateId?: string;
+
+  /** Optional: Auto-start sync (default: true) */
+  autoStart?: boolean;
+}
+
+interface CreateClientResult<DB extends SyncClientDb> {
+  /** The client instance */
+  client: Client<DB>;
+  /** Stop sync */
+  stop: () => void;
+  /** Destroy client and cleanup */
+  destroy: () => void;
+}
+
+/**
+ * Create a simplified sync client.
+ *
+ * Auto-generates clientId, creates transport from URL (default: '/api/sync'),
+ * builds subscriptions from handlers.
+ *
+ * @example
+ * ```typescript
+ * // Auto-generate handlers for simple tables (default URL: '/api/sync')
+ * const { client } = await createClient({
+ *   db,
+ *   actorId: 'user-123',
+ *   tables: ['tasks', 'notes'],
+ *   scopes: ['user:{user_id}'],
+ * });
+ *
+ * // With custom handlers for advanced cases
+ * const { client } = await createClient({
+ *   db,
+ *   actorId: 'user-123',
+ *   handlers: [
+ *     tasksHandler,      // subscribe: true by default
+ *     notesHandler,      // subscribe: true by default
+ *     draftsHandler,     // subscribe: false (local-only)
+ *   ],
+ * });
+ *
+ * // Listen for events
+ * client.on('sync:error', (err) => console.error(err));
+ * client.on('data:change', (scopes) => console.log('Data changed:', scopes));
+ * ```
+ */
+export async function createClient<DB extends SyncClientDb>(
+  options: CreateClientOptions<DB>
+): Promise<CreateClientResult<DB>> {
+  const {
+    db,
+    url = '/api/sync',
+    handlers: providedHandlers,
+    tables,
+    scopes,
+    actorId,
+    clientId = randomUUID(),
+    transport: customTransport,
+    getHeaders,
+    sync = {},
+    blobStorage,
+    plugins,
+    stateId,
+    autoStart = true,
+  } = options;
+
+  // Validate options
+  if (!providedHandlers && !tables) {
+    throw new Error('Either handlers or tables must be provided');
+  }
+  if (tables && !scopes) {
+    throw new Error('scopes is required when using tables option');
+  }
+
+  // Auto-generate handlers from tables if needed
+  const handlers =
+    providedHandlers ??
+    tables!.map((table) =>
+      createAutoHandler<DB, keyof DB & string>(table, scopes!)
+    );
+
+  // Build registry from handlers array
+  const tableHandlers = new ClientTableRegistry<DB>();
+  for (const handler of handlers) {
+    tableHandlers.register(handler);
+  }
+
+  // Create transport from URL if not provided
+  let transport = customTransport;
+  if (!transport && url) {
+    transport = createHttpTransport({
+      baseUrl: url,
+      getHeaders,
+    });
+  }
+
+  if (!transport) {
+    throw new Error('Either url or transport must be provided');
+  }
+
+  // Build subscriptions from handlers
+  const subscriptions = handlers
+    .map((handler) => {
+      const sub = handler.subscribe;
+      // Skip handlers that are explicitly disabled
+      if (sub === false) return null;
+
+      if (sub === true || sub === undefined) {
+        // Default: subscribe to the handler's single scope var using actorId.
+        // This avoids sending `{}` which would be treated as revoked by the server.
+        const scopes = deriveDefaultSubscriptionScopes({
+          handler,
+          actorId,
+        });
+        return {
+          id: handler.table,
+          shape: handler.table,
+          scopes,
+          params: {},
+        };
+      }
+      // Custom subscription config
+      const scopes: ScopeValues = sub.scopes ?? {};
+      if (Object.keys(scopes).length === 0) {
+        throw new Error(
+          `Handler "${handler.table}" subscription scopes cannot be empty. ` +
+            'Set subscribe: false or provide subscribe.scopes.'
+        );
+      }
+      return {
+        id: handler.table,
+        shape: handler.table,
+        scopes,
+        params: sub.params ?? {},
+      };
+    })
+    .filter((sub): sub is NonNullable<typeof sub> => sub !== null);
+
+  // Create client
+  const client = new Client({
+    db,
+    transport,
+    tableHandlers,
+    clientId,
+    actorId,
+    subscriptions,
+    blobStorage,
+    plugins,
+    stateId,
+    realtimeEnabled: sync.realtime ?? true,
+    pollIntervalMs: sync.pollIntervalMs,
+  });
+
+  // Auto-start
+  if (autoStart) {
+    await client.start();
+  }
+
+  return {
+    client,
+    stop: () => client.stop(),
+    destroy: () => client.destroy(),
+  };
+}

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);
+  });
+});