@syncular/client 0.0.6-95 → 0.1.0

package/src/conflicts.ts

@@ -1,171 +0,0 @@
-/**
- * @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.test.ts

@@ -1,83 +0,0 @@
-import { afterEach, describe, expect, it } from 'bun:test';
-import { createDatabase } from '@syncular/core';
-import type { Kysely } from 'kysely';
-import { createBunSqliteDialect } 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 = createDatabase<TestDb>({
-    dialect: createBunSqliteDialect({ path: ':memory:' }),
-    family: 'sqlite',
-  });
-  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

@@ -1,330 +0,0 @@
-/**
- * Simplified client factory
- *
- * Breaking changes from legacy Client:
- * - 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)
- */
-
-import type {
-  ColumnCodecDialect,
-  ColumnCodecSource,
-  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 { createClientHandlerCollection } from './handlers/collection';
-import { createClientHandler } from './handlers/create-handler';
-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[],
-  options: {
-    codecs?: ColumnCodecSource;
-    codecDialect?: ColumnCodecDialect;
-  }
-): ClientTableHandler<DB, TableName> {
-  return createClientHandler<DB, TableName>({
-    table: table as TableName,
-    scopes: scopes as ScopeDefinition[],
-    codecs: options.codecs,
-    codecDialect: options.codecDialect,
-  });
-}
-
-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>;
-
-  /**
-   * 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.
-   */
-  url?: string;
-
-  /**
-   * Table handlers for applying snapshots and changes.
-   * 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: Column codec resolver */
-  codecs?: ColumnCodecSource;
-
-  /** Optional: Codec dialect override (default: 'sqlite') */
-  codecDialect?: ColumnCodecDialect;
-
-  /** 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,
-    codecs,
-    codecDialect,
-    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!, {
-        codecs,
-        codecDialect,
-      })
-    );
-
-  const tableHandlers = createClientHandlerCollection(handlers);
-
-  // Create transport from URL if not provided
-  let transport = customTransport;
-  if (!transport && url) {
-    transport = createHttpTransport({
-      baseUrl: normalizeTransportBaseUrl(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,
-          table: handler.table,
-          scopes,
-          params: {},
-        };
-      }
-      // Custom subscription config
-      const scopes: ScopeValues = {};
-      for (const [scopeKey, scopeValue] of Object.entries(sub.scopes ?? {})) {
-        if (scopeValue === undefined) continue;
-        scopes[scopeKey] = scopeValue;
-      }
-      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,
-        table: 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,
-    codecs,
-    codecDialect,
-    realtimeEnabled: sync.realtime ?? true,
-    pollIntervalMs: sync.pollIntervalMs,
-  });
-
-  // Auto-start
-  if (autoStart) {
-    await client.start();
-  }
-
-  return {
-    client,
-    stop: () => client.stop(),
-    destroy: () => client.destroy(),
-  };
-}