@syncular/client 0.0.1-60

package/src/engine/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @syncular/client - Engine exports
+ */
+
+export { SyncEngine } from './SyncEngine';
+export * from './types';

package/src/engine/types.ts

@@ -0,0 +1,268 @@
+/**
+ * @syncular/client - Sync engine types
+ *
+ * Framework-agnostic types for the sync engine.
+ */
+
+import type {
+  SyncPullResponse,
+  SyncPushRequest,
+  SyncPushResponse,
+  SyncSubscriptionRequest,
+  SyncTransport,
+} from '@syncular/core';
+import type { Kysely } from 'kysely';
+import type { ClientTableRegistry } from '../handlers/registry';
+import type { SyncClientPlugin } from '../plugins/types';
+import type { SyncClientDb } from '../schema';
+
+/**
+ * Connection state for the sync engine
+ */
+export type SyncConnectionState =
+  | 'disconnected'
+  | 'connecting'
+  | 'connected'
+  | 'reconnecting';
+
+/**
+ * Transport mode (detected or configured)
+ */
+export type SyncTransportMode = 'polling' | 'realtime';
+
+/**
+ * Sync engine state
+ */
+export interface SyncEngineState {
+  /** Whether sync is enabled */
+  enabled: boolean;
+  /** Whether currently syncing */
+  isSyncing: boolean;
+  /** Current connection state */
+  connectionState: SyncConnectionState;
+  /** Transport mode */
+  transportMode: SyncTransportMode;
+  /** Last successful sync timestamp */
+  lastSyncAt: number | null;
+  /** Last error (cleared on successful sync) */
+  error: SyncError | null;
+  /** Number of pending outbox commits */
+  pendingCount: number;
+  /** Number of sync retries (reset on success) */
+  retryCount: number;
+  /** Whether currently retrying */
+  isRetrying: boolean;
+}
+
+/**
+ * Sync error with context
+ */
+export interface SyncError {
+  /** Error code */
+  code: 'NETWORK_ERROR' | 'SYNC_ERROR' | 'CONFLICT' | 'UNKNOWN';
+  /** Error message */
+  message: string;
+  /** Original error if available */
+  cause?: Error;
+  /** Timestamp when error occurred */
+  timestamp: number;
+}
+
+/**
+ * Sync event types
+ */
+export type SyncEventType =
+  | 'state:change'
+  | 'sync:start'
+  | 'sync:complete'
+  | 'sync:error'
+  | 'connection:change'
+  | 'outbox:change'
+  | 'data:change'
+  | 'presence:change';
+
+/**
+ * Presence entry for a client connected to a scope
+ */
+export interface PresenceEntry<TMetadata = Record<string, unknown>> {
+  clientId: string;
+  actorId: string;
+  joinedAt: number;
+  metadata?: TMetadata;
+}
+
+/**
+ * Sync event payloads
+ */
+export interface SyncEventPayloads {
+  'state:change': Record<string, never>;
+  'sync:start': { timestamp: number };
+  'sync:complete': {
+    timestamp: number;
+    pushedCommits: number;
+    pullRounds: number;
+    pullResponse: SyncPullResponse;
+  };
+  'sync:error': SyncError;
+  'connection:change': {
+    previous: SyncConnectionState;
+    current: SyncConnectionState;
+  };
+  'outbox:change': {
+    pendingCount: number;
+    sendingCount: number;
+    failedCount: number;
+    ackedCount: number;
+  };
+  'data:change': {
+    scopes: string[];
+    timestamp: number;
+  };
+  'presence:change': {
+    scopeKey: string;
+    presence: PresenceEntry[];
+  };
+}
+
+/**
+ * Sync event listener
+ */
+export type SyncEventListener<T extends SyncEventType> = (
+  payload: SyncEventPayloads[T]
+) => void;
+
+/**
+ * Sync engine configuration
+ */
+export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
+  /** Database instance */
+  db: Kysely<DB>;
+  /** Sync transport */
+  transport: SyncTransport;
+  /** Client shape registry */
+  shapes: ClientTableRegistry<DB>;
+  /** Actor id for sync scoping (null/undefined disables sync) */
+  actorId: string | null | undefined;
+  /** Stable device/app installation id */
+  clientId: string | null | undefined;
+  /** Subscriptions for partial sync */
+  subscriptions: Array<Omit<SyncSubscriptionRequest, 'cursor'>>;
+  /** Pull limit (commit count per request) */
+  limitCommits?: number;
+  /** Bootstrap snapshot rows per page */
+  limitSnapshotRows?: number;
+  /** Bootstrap snapshot pages per pull */
+  maxSnapshotPages?: number;
+  /** Optional state row id (multi-profile support) */
+  stateId?: string;
+  /** Poll interval in milliseconds (polling mode) */
+  pollIntervalMs?: number;
+  /** Max retries before giving up */
+  maxRetries?: number;
+  /** Migration function to run before first sync */
+  migrate?: (db: Kysely<DB>) => Promise<void>;
+  /** Called when migration fails. Receives the error. */
+  onMigrationError?: (error: Error) => void;
+  /**
+   * Enable realtime mode (WebSocket wake-ups).
+   * Default behavior is auto-enable when transport supports realtime.
+   * Set to false to force polling.
+   */
+  realtimeEnabled?: boolean;
+  /** Fallback poll interval when realtime reconnecting */
+  realtimeFallbackPollMs?: number;
+  /** Error callback */
+  onError?: (error: SyncError) => void;
+  /** Conflict callback */
+  onConflict?: (conflict: ConflictInfo) => void;
+  /** Data change callback */
+  onDataChange?: (scopes: string[]) => void;
+  /** Optional client plugins (e.g. encryption) */
+  plugins?: SyncClientPlugin[];
+}
+
+/**
+ * Conflict information for callback
+ */
+export interface ConflictInfo {
+  id: string;
+  outboxCommitId: string;
+  clientCommitId: string;
+  opIndex: number;
+  resultStatus: 'conflict' | 'error';
+  message: string;
+  code: string | null;
+  serverVersion: number | null;
+  serverRowJson: string | null;
+  createdAt: number;
+  /** Table name from the conflicting operation */
+  table: string;
+  /** Row ID from the conflicting operation */
+  rowId: string;
+  /** Local payload that was rejected (extracted from outbox) */
+  localPayload: Record<string, unknown> | null;
+}
+
+/**
+ * Realtime transport interface (duck-typed from transport)
+ */
+export interface RealtimeTransportLike extends SyncTransport {
+  connect(
+    args: { clientId: string },
+    onEvent: (event: {
+      event: string;
+      data: {
+        cursor?: number;
+        changes?: unknown[];
+        error?: string;
+        timestamp: number;
+      };
+    }) => void,
+    onStateChange?: (state: 'disconnected' | 'connecting' | 'connected') => void
+  ): () => void;
+  getConnectionState(): 'disconnected' | 'connecting' | 'connected';
+  reconnect(): void;
+  sendPresenceJoin?(scopeKey: string, metadata?: Record<string, unknown>): void;
+  sendPresenceLeave?(scopeKey: string): void;
+  sendPresenceUpdate?(
+    scopeKey: string,
+    metadata: Record<string, unknown>
+  ): void;
+  onPresenceEvent?(
+    callback: (event: {
+      action: 'join' | 'leave' | 'update' | 'snapshot';
+      scopeKey: string;
+      clientId?: string;
+      actorId?: string;
+      metadata?: Record<string, unknown>;
+      entries?: PresenceEntry[];
+    }) => void
+  ): () => void;
+  /**
+   * Push a commit via WebSocket (bypasses HTTP).
+   * Returns `null` if WS is not connected or times out (caller should fall back to HTTP).
+   */
+  pushViaWs?(request: SyncPushRequest): Promise<SyncPushResponse | null>;
+}
+
+/**
+ * Sync result from a single sync cycle
+ */
+export interface SyncResult {
+  success: boolean;
+  pushedCommits: number;
+  pullRounds: number;
+  pullResponse: SyncPullResponse;
+  error?: SyncError;
+}
+
+/**
+ * Outbox statistics
+ */
+export interface OutboxStats {
+  pending: number;
+  sending: number;
+  failed: number;
+  acked: number;
+  total: number;
+}

package/src/handlers/create-handler.ts

@@ -0,0 +1,287 @@
+/**
+ * @syncular/client - Declarative client handler helper
+ */
+
+import type { ScopeDefinition, SyncChange, SyncSnapshot } from '@syncular/core';
+import { normalizeScopes } from '@syncular/core';
+import { sql } from 'kysely';
+import type { SyncClientDb } from '../schema';
+import type {
+  ClientClearContext,
+  ClientHandlerContext,
+  ClientSnapshotHookContext,
+  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,
+ *   so we convert them to 0/1 before binding.
+ * - Objects/arrays (e.g. from SerializePlugin auto-deserialization) are
+ *   re-serialized to JSON strings so they survive the round-trip through
+ *   SQLite/PGlite TEXT columns.
+ */
+function coerceForSql(value: unknown): unknown {
+  if (value === undefined) return null;
+  if (typeof value === 'boolean') return value ? 1 : 0;
+  if (value !== null && typeof value === 'object' && !(value instanceof Date)) {
+    return JSON.stringify(value);
+  }
+  return value;
+}
+
+/**
+ * Options for creating a declarative client handler.
+ */
+export interface CreateClientHandlerOptions<
+  DB extends SyncClientDb,
+  TableName extends keyof DB & string,
+> {
+  /** Table name in the database */
+  table: TableName;
+
+  /**
+   * Scope definitions for this table.
+   * Can be simple strings (column auto-derived) or objects with explicit mapping.
+   *
+   * @example
+   * ```typescript
+   * // Simple: column auto-derived from placeholder
+   * scopes: ['user:{user_id}', 'org:{org_id}']
+   *
+   * // Explicit: when column differs from pattern variable
+   * scopes: [
+   *   { pattern: 'user:{user_id}', column: 'owner_id' }
+   * ]
+   * ```
+   */
+  scopes: ScopeDefinition[];
+
+  /**
+   * Subscription configuration for this table.
+   * - `true` (default): Subscribe to this table with default scopes/params
+   * - `false`: Don't subscribe (handler only for local mutations)
+   * - Object: Subscribe with custom scopes and params
+   */
+  subscribe?:
+    | boolean
+    | {
+        scopes?: Record<string, string | string[]>;
+        params?: Record<string, unknown>;
+      };
+
+  /** Primary key column name (default: 'id') */
+  primaryKey?: keyof DB[TableName] & string;
+
+  /**
+   * Optional version column name (e.g. 'server_version') to store `change.row_version`.
+   * If omitted, row_version is ignored by the default handler.
+   */
+  versionColumn?: keyof DB[TableName] & string;
+
+  /**
+   * Override: Apply a snapshot.
+   * Default: upsert all rows (no delete on isFirstPage).
+   */
+  applySnapshot?: (
+    ctx: ClientHandlerContext<DB>,
+    snapshot: SyncSnapshot
+  ) => Promise<void>;
+
+  /**
+   * Override: Apply a single change.
+   * Default: upsert on upsert, delete on delete.
+   */
+  applyChange?: (
+    ctx: ClientHandlerContext<DB>,
+    change: SyncChange
+  ) => Promise<void>;
+
+  /**
+   * Override: Clear all data for this table.
+   * Default: delete all rows from the table.
+   */
+  clearAll?: (ctx: ClientClearContext<DB>) => Promise<void>;
+
+  /**
+   * Hook: Called when a snapshot begins (isFirstPage = true).
+   * Default: no-op.
+   */
+  onSnapshotStart?: (ctx: ClientSnapshotHookContext<DB>) => Promise<void>;
+
+  /**
+   * Hook: Called when a snapshot ends (isLastPage = true).
+   * Default: no-op.
+   */
+  onSnapshotEnd?: (ctx: ClientSnapshotHookContext<DB>) => Promise<void>;
+}
+
+/**
+ * Create a declarative client table handler with sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * import { createClientHandler } from '@syncular/client';
+ * import type { ClientDb } from './db.generated';
+ *
+ * export const tasksHandler = createClientHandler<ClientDb, 'tasks'>({
+ *   table: 'tasks',
+ *   scopes: ['user:{user_id}'],  // column auto-derived from placeholder
+ * });
+ *
+ * // With custom column mapping:
+ * export const tasksHandler = createClientHandler<ClientDb, 'tasks'>({
+ *   table: 'tasks',
+ *   scopes: [{ pattern: 'user:{user_id}', column: 'owner_id' }],
+ * });
+ *
+ * // With soft delete pattern:
+ * export const tasksHandler = createClientHandler<ClientDb, 'tasks'>({
+ *   table: 'tasks',
+ *   scopes: ['user:{user_id}'],
+ *   onSnapshotStart: async (ctx) => {
+ *     await ctx.trx.updateTable('tasks')
+ *       .set({ _sync_stale: 1 })
+ *       .where('user_id', '=', ctx.scopeKey.split(':')[1])
+ *       .execute();
+ *   },
+ *   onSnapshotEnd: async (ctx) => {
+ *     await ctx.trx.deleteFrom('tasks')
+ *       .where('_sync_stale', '=', 1)
+ *       .execute();
+ *   },
+ * });
+ * ```
+ */
+export function createClientHandler<
+  DB extends SyncClientDb,
+  TableName extends keyof DB & string,
+>(
+  options: CreateClientHandlerOptions<DB, TableName>
+): ClientTableHandler<DB, TableName> {
+  const { table, scopes: scopeDefs } = options;
+  const primaryKey =
+    options.primaryKey ?? ('id' as keyof DB[TableName] & string);
+  const versionColumn = options.versionColumn;
+
+  // Normalize scopes to pattern map (stored for metadata)
+  const scopeColumnMap = normalizeScopes(scopeDefs);
+  const scopePatterns = Object.keys(scopeColumnMap);
+
+  // Default applySnapshot: upsert all rows
+  const defaultApplySnapshot = async (
+    ctx: ClientHandlerContext<DB>,
+    snapshot: SyncSnapshot
+  ): Promise<void> => {
+    const rows: Array<Record<string, unknown>> = [];
+    for (const row of snapshot.rows ?? []) {
+      if (!isRecord(row)) continue;
+      rows.push(row);
+    }
+
+    if (rows.length === 0) return;
+
+    // Get column names from first row
+    const columns = Object.keys(rows[0]!);
+    if (columns.length === 0) return;
+    const updateColumns = columns.filter((c) => c !== primaryKey);
+
+    const onConflict =
+      updateColumns.length === 0
+        ? sql`do nothing`
+        : sql`do update set ${sql.join(
+            updateColumns.map(
+              (col) => sql`${sql.ref(col)} = ${sql.ref(`excluded.${col}`)}`
+            ),
+            sql`, `
+          )}`;
+
+    await sql`
+      insert into ${sql.table(table)} (${sql.join(columns.map((c) => sql.ref(c)))})
+      values ${sql.join(
+        rows.map(
+          (row) =>
+            sql`(${sql.join(
+              columns.map((col) => sql.val(coerceForSql(row[col]))),
+              sql`, `
+            )})`
+        ),
+        sql`, `
+      )}
+      on conflict (${sql.ref(primaryKey)}) ${onConflict}
+    `.execute(ctx.trx);
+  };
+
+  // Default applyChange: upsert on upsert, delete on delete
+  const defaultApplyChange = async (
+    ctx: ClientHandlerContext<DB>,
+    change: SyncChange
+  ): Promise<void> => {
+    if (change.op === 'delete') {
+      await sql`
+        delete from ${sql.table(table)}
+        where ${sql.ref(primaryKey)} = ${sql.val(change.row_id)}
+      `.execute(ctx.trx);
+      return;
+    }
+
+    const row = isRecord(change.row_json) ? change.row_json : {};
+    const insertRow: Record<string, unknown> = {
+      ...row,
+      [primaryKey]: change.row_id,
+    };
+
+    if (
+      versionColumn &&
+      change.row_version !== null &&
+      change.row_version !== undefined
+    ) {
+      insertRow[versionColumn] = change.row_version;
+    }
+
+    const columns = Object.keys(insertRow);
+    const updateColumns = columns.filter((c) => c !== primaryKey);
+    const onConflict =
+      updateColumns.length === 0
+        ? sql`do nothing`
+        : sql`do update set ${sql.join(
+            updateColumns.map(
+              (col) => sql`${sql.ref(col)} = ${sql.ref(`excluded.${col}`)}`
+            ),
+            sql`, `
+          )}`;
+
+    await sql`
+      insert into ${sql.table(table)} (${sql.join(columns.map((c) => sql.ref(c)))})
+      values (${sql.join(
+        columns.map((col) => sql.val(coerceForSql(insertRow[col]))),
+        sql`, `
+      )})
+      on conflict (${sql.ref(primaryKey)}) ${onConflict}
+    `.execute(ctx.trx);
+  };
+
+  // Default clearAll: delete all rows from the table
+  const defaultClearAll = async (
+    ctx: ClientClearContext<DB>
+  ): Promise<void> => {
+    await sql`delete from ${sql.table(table)}`.execute(ctx.trx);
+  };
+
+  return {
+    table,
+    scopePatterns,
+    subscribe: options.subscribe,
+
+    applySnapshot: options.applySnapshot ?? defaultApplySnapshot,
+    applyChange: options.applyChange ?? defaultApplyChange,
+    clearAll: options.clearAll ?? defaultClearAll,
+
+    onSnapshotStart: options.onSnapshotStart,
+    onSnapshotEnd: options.onSnapshotEnd,
+  };
+}

package/src/handlers/registry.ts

@@ -0,0 +1,36 @@
+/**
+ * @syncular/client - Sync client table registry
+ */
+
+import type { ClientTableHandler } from './types';
+
+/**
+ * Registry for client-side table handlers.
+ */
+export class ClientTableRegistry<DB> {
+  private handlers = new Map<string, ClientTableHandler<DB>>();
+
+  register(handler: ClientTableHandler<DB>): this {
+    if (this.handlers.has(handler.table)) {
+      throw new Error(
+        `Client table handler already registered: ${handler.table}`
+      );
+    }
+    this.handlers.set(handler.table, handler);
+    return this;
+  }
+
+  get(table: string): ClientTableHandler<DB> | undefined {
+    return this.handlers.get(table);
+  }
+
+  getOrThrow(table: string): ClientTableHandler<DB> {
+    const h = this.handlers.get(table);
+    if (!h) throw new Error(`Missing client table handler for table: ${table}`);
+    return h;
+  }
+
+  getAll(): ClientTableHandler<DB>[] {
+    return Array.from(this.handlers.values());
+  }
+}

package/src/handlers/types.ts

@@ -0,0 +1,102 @@
+/**
+ * @syncular/client - Sync client table handler interface
+ */
+
+import type { ScopeValues, SyncChange, SyncSnapshot } from '@syncular/core';
+import type { Transaction } from 'kysely';
+
+/**
+ * Context passed to client table handler methods.
+ */
+export interface ClientHandlerContext<DB> {
+  /** Database transaction */
+  trx: Transaction<DB>;
+}
+
+/**
+ * Extended context for snapshot lifecycle hooks.
+ */
+export interface ClientSnapshotHookContext<DB>
+  extends ClientHandlerContext<DB> {
+  /** The table being snapshotted */
+  table: string;
+  /** The scope values for this subscription */
+  scopes: ScopeValues;
+}
+
+/**
+ * Context for clearAll/clearScope operations.
+ */
+export interface ClientClearContext<DB> extends ClientHandlerContext<DB> {
+  /** The scope values to clear (data matching these scopes should be removed) */
+  scopes: ScopeValues;
+}
+
+/**
+ * Subscription configuration for a handler.
+ */
+export interface HandlerSubscriptionConfig {
+  /** Scope values for this subscription */
+  scopes?: Record<string, string | string[]>;
+  /** Params for this subscription */
+  params?: Record<string, unknown>;
+}
+
+/**
+ * Client-side table handler for applying sync snapshots and changes.
+ */
+export interface ClientTableHandler<
+  DB,
+  TableName extends keyof DB & string = keyof DB & string,
+> {
+  /** Table name (used as identifier in sync operations) */
+  table: TableName;
+
+  /**
+   * Scope patterns used by this table.
+   * Used for deriving safe default subscriptions in `createClient`.
+   */
+  scopePatterns?: string[];
+
+  /**
+   * Subscription configuration.
+   * - `true`: Subscribe to this table (default)
+   * - `false`: Don't subscribe (local-only handler)
+   * - Object: Subscribe with custom scopes/params
+   */
+  subscribe?: boolean | HandlerSubscriptionConfig;
+
+  /**
+   * Apply a snapshot page for this table.
+   * The handler is responsible for upserting the rows.
+   */
+  applySnapshot(
+    ctx: ClientHandlerContext<DB>,
+    snapshot: SyncSnapshot
+  ): Promise<void>;
+
+  /**
+   * Clear local data for this table matching the given scopes.
+   * Used when subscription is removed or revoked.
+   * If scopes is empty, clear all data for this table.
+   */
+  clearAll(ctx: ClientClearContext<DB>): Promise<void>;
+
+  /**
+   * Apply a single change (upsert/delete).
+   * Must be idempotent (retries may re-apply).
+   */
+  applyChange(ctx: ClientHandlerContext<DB>, change: SyncChange): Promise<void>;
+
+  /**
+   * Optional: Called when a snapshot begins (isFirstPage = true).
+   * Use this for marking existing rows as stale before applying snapshot.
+   */
+  onSnapshotStart?(ctx: ClientSnapshotHookContext<DB>): Promise<void>;
+
+  /**
+   * Optional: Called when a snapshot ends (isLastPage = true).
+   * Use this for cleaning up stale rows after snapshot is complete.
+   */
+  onSnapshotEnd?(ctx: ClientSnapshotHookContext<DB>): Promise<void>;
+}