@syncular/client 0.0.6-95 → 0.1.0

package/src/push-engine.ts

@@ -1,216 +0,0 @@
-/**
- * @syncular/client - Sync push engine (commit-based)
- */
-
-import type {
-  SyncPushRequest,
-  SyncPushResponse,
-  SyncTransport,
-} from '@syncular/core';
-import { countSyncMetric } from '@syncular/core';
-import type { Kysely } from 'kysely';
-import { upsertConflictsForRejectedCommit } from './conflicts';
-import {
-  getNextSendableOutboxCommit,
-  markOutboxCommitAcked,
-  markOutboxCommitFailed,
-  markOutboxCommitPending,
-} from './outbox';
-import type {
-  SyncClientPlugin,
-  SyncClientPluginContext,
-} from './plugins/types';
-import type { SyncClientDb } from './schema';
-
-export interface SyncPushOnceOptions {
-  clientId: string;
-  actorId?: string;
-  plugins?: SyncClientPlugin[];
-}
-
-export interface SyncPushOnceResult {
-  pushed: boolean;
-  response?: SyncPushResponse;
-}
-
-interface TransportWithWsPush extends SyncTransport {
-  pushViaWs(request: SyncPushRequest): Promise<SyncPushResponse | null>;
-}
-
-function hasPushViaWs(
-  transport: SyncTransport
-): transport is TransportWithWsPush {
-  return 'pushViaWs' in transport && typeof transport.pushViaWs === 'function';
-}
-
-function clonePushRequest(request: SyncPushRequest): SyncPushRequest {
-  if (typeof structuredClone === 'function') return structuredClone(request);
-  return JSON.parse(JSON.stringify(request)) as SyncPushRequest;
-}
-
-export async function syncPushOnce<DB extends SyncClientDb>(
-  db: Kysely<DB>,
-  transport: SyncTransport,
-  options: SyncPushOnceOptions
-): Promise<SyncPushOnceResult> {
-  // getNextSendableOutboxCommit now atomically claims the commit
-  // (marks it as 'sending' and returns it in one operation)
-  const next = await getNextSendableOutboxCommit(db);
-  if (!next) return { pushed: false };
-
-  const request: SyncPushRequest = {
-    clientId: options.clientId,
-    clientCommitId: next.client_commit_id,
-    operations: next.operations,
-    schemaVersion: next.schema_version,
-  };
-  const ctx: SyncClientPluginContext = {
-    actorId: options.actorId ?? 'unknown',
-    clientId: options.clientId,
-  };
-  const plugins = options.plugins ?? [];
-
-  let requestToSend = request;
-  if (plugins.length > 0) {
-    try {
-      requestToSend = clonePushRequest(request);
-      for (const plugin of plugins) {
-        if (!plugin.beforePush) continue;
-        requestToSend = await plugin.beforePush(ctx, requestToSend);
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : 'Unknown error';
-      await markOutboxCommitPending(db, { id: next.id, error: message });
-      throw err;
-    }
-  }
-
-  let res: SyncPushResponse;
-  let usedWsPush = false;
-  try {
-    // Try WS push first if the transport supports it
-    let wsResponse: SyncPushResponse | null = null;
-    if (hasPushViaWs(transport)) {
-      wsResponse = await transport.pushViaWs(requestToSend);
-    }
-
-    if (wsResponse) {
-      res = wsResponse;
-      usedWsPush = true;
-    } else {
-      // Fall back to HTTP
-      const combined = await transport.sync({
-        clientId: requestToSend.clientId,
-        push: {
-          clientCommitId: requestToSend.clientCommitId,
-          operations: requestToSend.operations,
-          schemaVersion: requestToSend.schemaVersion,
-        },
-      });
-      if (!combined.push) {
-        throw new Error('Server returned no push response');
-      }
-      res = combined.push;
-    }
-  } catch (err) {
-    const message = err instanceof Error ? err.message : 'Unknown error';
-    // Treat transport exceptions as retryable. The sync loop already applies backoff,
-    // and failed commits are reserved for terminal server rejections (e.g. conflicts).
-    await markOutboxCommitPending(db, { id: next.id, error: message });
-    throw err;
-  }
-
-  let responseToUse = res;
-  if (plugins.length > 0) {
-    try {
-      for (const plugin of plugins) {
-        if (!plugin.afterPush) continue;
-        responseToUse = await plugin.afterPush(ctx, {
-          request: requestToSend,
-          response: responseToUse,
-        });
-      }
-    } catch (err) {
-      // The server already received and processed this commit. Persist the raw response
-      // so we don't end up retrying a commit that was already applied.
-      const responseJson = JSON.stringify(res);
-
-      if (res.status === 'applied' || res.status === 'cached') {
-        await markOutboxCommitAcked(db, {
-          id: next.id,
-          commitSeq: res.commitSeq ?? null,
-          responseJson,
-        });
-      } else {
-        await upsertConflictsForRejectedCommit(db, {
-          outboxCommitId: next.id,
-          clientCommitId: next.client_commit_id,
-          response: res,
-        });
-        await markOutboxCommitFailed(db, {
-          id: next.id,
-          error: 'REJECTED',
-          responseJson,
-        });
-      }
-
-      throw err;
-    }
-  }
-
-  const responseJson = JSON.stringify(responseToUse);
-  const detectedConflicts = responseToUse.results.reduce(
-    (count, result) => count + (result.status === 'conflict' ? 1 : 0),
-    0
-  );
-  if (detectedConflicts > 0 && !usedWsPush) {
-    countSyncMetric('sync.conflicts.detected', detectedConflicts, {
-      attributes: {
-        source: 'client',
-        transport: 'http',
-      },
-    });
-  }
-
-  if (responseToUse.status === 'applied' || responseToUse.status === 'cached') {
-    await markOutboxCommitAcked(db, {
-      id: next.id,
-      commitSeq: responseToUse.commitSeq ?? null,
-      responseJson,
-    });
-    return { pushed: true, response: responseToUse };
-  }
-
-  // Check if all errors are retriable - if so, keep pending for retry
-  const errorResults = responseToUse.results.filter(
-    (r) => r.status === 'error'
-  );
-  const allRetriable =
-    errorResults.length > 0 && errorResults.every((r) => r.retriable === true);
-
-  if (allRetriable) {
-    // All errors are retriable - keep commit pending for retry
-    const errorMessages = errorResults
-      .map((r) => r.error ?? 'Unknown error')
-      .join('; ');
-    await markOutboxCommitPending(db, {
-      id: next.id,
-      error: `Retriable: ${errorMessages}`,
-      responseJson,
-    });
-    return { pushed: true, response: responseToUse };
-  }
-
-  // Terminal rejection - mark as failed and record conflicts
-  await upsertConflictsForRejectedCommit(db, {
-    outboxCommitId: next.id,
-    clientCommitId: next.client_commit_id,
-    response: responseToUse,
-  });
-  await markOutboxCommitFailed(db, {
-    id: next.id,
-    error: 'REJECTED',
-    responseJson,
-  });
-  return { pushed: true, response: responseToUse };
-}

package/src/query/FingerprintCollector.ts

@@ -1,29 +0,0 @@
-/**
- * @syncular/client - Fingerprint Collector
- *
- * Accumulates fingerprint data from multiple queries.
- */
-
-/**
- * Fingerprint collector accumulates fingerprint data from multiple queries
- */
-export class FingerprintCollector {
-  private fingerprints: string[] = [];
-
-  add(fingerprint: string): void {
-    this.fingerprints.push(fingerprint);
-  }
-
-  /**
-   * Get combined fingerprint from all collected fingerprints
-   */
-  getCombined(): string {
-    if (this.fingerprints.length === 0) return '';
-    if (this.fingerprints.length === 1) return this.fingerprints[0] ?? '';
-    return this.fingerprints.join('|');
-  }
-
-  clear(): void {
-    this.fingerprints = [];
-  }
-}

package/src/query/QueryContext.ts

@@ -1,54 +0,0 @@
-/**
- * @syncular/client - Query Context
- *
- * Provides a query context with tracked selectFrom for scope tracking
- * and automatic fingerprint generation.
- */
-
-import type { Kysely } from 'kysely';
-import type { SyncClientDb } from '../schema';
-import type { FingerprintCollector } from './FingerprintCollector';
-import type { MutationTimestampSource } from './fingerprint';
-import { createTrackedSelectFrom } from './tracked-select';
-
-export type TrackedSelectFrom<DB> = ReturnType<
-  typeof createTrackedSelectFrom<DB>
->;
-
-/**
- * Query context provided to query functions.
- *
- * Only `selectFrom` is exposed to ensure proper scope tracking and fingerprinting.
- * If you need raw database access, use the db directly outside the query function.
- */
-export interface QueryContext<DB extends SyncClientDb = SyncClientDb> {
-  /**
-   * Wrapped selectFrom that:
-   * 1. Registers table as watched scope
-   * 2. Intercepts .execute() to auto-detect fingerprinting mode:
-   *    - Result has keyField (default: 'id')? -> row-level fingerprinting
-   *    - No keyField? -> value-based fingerprinting (for aggregates)
-   */
-  selectFrom: TrackedSelectFrom<DB>;
-}
-
-/**
- * Create a query context with tracked selectFrom.
- */
-export function createQueryContext<DB extends SyncClientDb>(
-  db: Kysely<DB>,
-  scopeCollector: Set<string>,
-  fingerprintCollector: FingerprintCollector,
-  engine: MutationTimestampSource,
-  keyField = 'id'
-): QueryContext<DB> {
-  return {
-    selectFrom: createTrackedSelectFrom(
-      db,
-      scopeCollector,
-      fingerprintCollector,
-      engine,
-      keyField
-    ),
-  };
-}

package/src/query/fingerprint.ts

@@ -1,109 +0,0 @@
-/**
- * @syncular/client - Fingerprint-based rerender optimization utilities
- *
- * Provides efficient fingerprint computation for query results to avoid
- * expensive deep equality checks. Uses mutation timestamps from the SyncEngine.
- */
-
-export interface MutationTimestampSource {
-  getMutationTimestamp(table: string, rowId: string): number;
-}
-
-/**
- * Compute a fingerprint for query results based on length + ids + mutation timestamps.
- * Much faster than deep equality for large datasets.
- *
- * Fingerprint format: `length:id1@ts1,id2@ts2,...`
- *
- * @param rows - Query result rows (must have an id-like field)
- * @param engine - SyncEngine to look up mutation timestamps
- * @param table - Table name for timestamp lookup
- * @param keyField - Field name to use as row identifier (default: 'id')
- * @returns Fingerprint string for comparison
- *
- * @example
- * ```ts
- * const fingerprint = computeFingerprint(tasks, engine, 'tasks', 'id');
- * // Returns: "3:abc@1706123456789,def@1706123456790,ghi@0"
- * ```
- */
-export function computeFingerprint<T extends Record<string, unknown>>(
-  rows: T[],
-  engine: MutationTimestampSource,
-  table: string,
-  keyField = 'id'
-): string {
-  if (rows.length === 0) return '0:';
-
-  const parts: string[] = [];
-  for (const row of rows) {
-    const id = String(row[keyField] ?? '');
-    const ts = engine.getMutationTimestamp(table, id);
-    parts.push(`${id}@${ts}`);
-  }
-
-  return `${rows.length}:${parts.join(',')}`;
-}
-
-/**
- * Check if rows have the required key field for fingerprinting.
- * Returns true for empty arrays (no data to fingerprint).
- *
- * @param rows - Query result rows to check
- * @param keyField - Field name to check for (default: 'id')
- * @returns true if rows can be fingerprinted, false otherwise
- *
- * @example
- * ```ts
- * // Can fingerprint - rows have 'id' field
- * canFingerprint([{ id: '1', name: 'foo' }]); // true
- *
- * // Cannot fingerprint - rows lack 'id' field (aggregates, etc.)
- * canFingerprint([{ count: 42 }]); // false
- * ```
- */
-export function canFingerprint<T>(rows: T[], keyField = 'id'): boolean {
-  if (rows.length === 0) return true;
-  return keyField in (rows[0] as Record<string, unknown>);
-}
-
-/**
- * Compute row-level fingerprint from query results.
- * Format: `table:count:id1@ts1,id2@ts2,...`
- */
-export function computeRowFingerprint(
-  rows: unknown[],
-  table: string,
-  engine: MutationTimestampSource,
-  keyField: string
-): string {
-  if (rows.length === 0) return `${table}:0:`;
-
-  const parts: string[] = [];
-  for (const row of rows) {
-    const r = row as Record<string, unknown>;
-    const id = String(r[keyField] ?? '');
-    const ts = engine.getMutationTimestamp(table, id);
-    parts.push(`${id}@${ts}`);
-  }
-
-  return `${table}:${rows.length}:${parts.join(',')}`;
-}
-
-/**
- * Compute value-based fingerprint for aggregate/scalar queries.
- * Format: `table:hash(value)`
- */
-export function computeValueFingerprint(table: string, value: unknown): string {
-  // Simple hash of the JSON representation
-  const json = JSON.stringify(value);
-  return `${table}:${json}`;
-}
-
-/**
- * Check if result rows have the key field for row-level fingerprinting.
- */
-export function hasKeyField(rows: unknown[], keyField: string): boolean {
-  if (rows.length === 0) return false;
-  return keyField in (rows[0] as Record<string, unknown>);
-}

package/src/query/index.ts

@@ -1,10 +0,0 @@
-/**
- * @syncular/client - Query utilities exports
- */
-
-export { FingerprintCollector } from './FingerprintCollector';
-export {
-  canFingerprint,
-  computeFingerprint,
-} from './fingerprint';
-export { createQueryContext, type QueryContext } from './QueryContext';

package/src/query/tracked-select.ts

@@ -1,139 +0,0 @@
-/**
- * @syncular/client - Tracked SelectFrom
- *
- * Provides a wrapped selectFrom that:
- * 1. Tracks tables as watched scopes when called
- * 2. Intercepts .execute() to auto-generate fingerprints
- */
-
-import type { Kysely } from 'kysely';
-import type { FingerprintCollector } from './FingerprintCollector';
-
-/** Portable type alias for Kysely's selectFrom method signature */
-type TrackedSelectFrom<DB> = Kysely<DB>['selectFrom'];
-
-import {
-  computeRowFingerprint,
-  computeValueFingerprint,
-  hasKeyField,
-  type MutationTimestampSource,
-} from './fingerprint';
-
-/**
- * Create a proxy that intercepts execute() to compute fingerprints.
- */
-
-type ExecutableQuery = {
-  execute: () => Promise<unknown>;
-  executeTakeFirst: () => Promise<unknown>;
-  executeTakeFirstOrThrow: () => Promise<unknown>;
-};
-
-function isExecutableQuery(value: unknown): value is ExecutableQuery {
-  if (typeof value !== 'object' || value === null) return false;
-  return (
-    typeof Reflect.get(value, 'execute') === 'function' &&
-    typeof Reflect.get(value, 'executeTakeFirst') === 'function' &&
-    typeof Reflect.get(value, 'executeTakeFirstOrThrow') === 'function'
-  );
-}
-
-function createExecuteProxy<B extends ExecutableQuery>(
-  builder: B,
-  table: string,
-  collector: FingerprintCollector,
-  engine: MutationTimestampSource,
-  keyField: string
-): B {
-  return new Proxy(builder, {
-    get(target, prop: string | symbol) {
-      if (prop === 'execute') {
-        return async () => {
-          const rows = await target.execute();
-          // Auto-detect fingerprint mode based on result shape
-          if (Array.isArray(rows)) {
-            if (hasKeyField(rows, keyField)) {
-              // Row-level fingerprinting - result has keyField
-              const fp = computeRowFingerprint(rows, table, engine, keyField);
-              collector.add(fp);
-            } else {
-              // Value-based fingerprinting - for aggregates/scalars
-              const fp = computeValueFingerprint(table, rows);
-              collector.add(fp);
-            }
-          } else {
-            // Unexpected, but keep rerender behavior deterministic.
-            const fp = computeValueFingerprint(table, rows);
-            collector.add(fp);
-          }
-          return rows;
-        };
-      }
-      if (prop === 'executeTakeFirst') {
-        return async () => {
-          const row = await target.executeTakeFirst();
-          // Value-based fingerprinting for single-row queries
-          const fp = computeValueFingerprint(table, row);
-          collector.add(fp);
-          return row;
-        };
-      }
-      if (prop === 'executeTakeFirstOrThrow') {
-        return async () => {
-          const row = await target.executeTakeFirstOrThrow();
-          // Value-based fingerprinting for single-row queries
-          const fp = computeValueFingerprint(table, row);
-          collector.add(fp);
-          return row;
-        };
-      }
-      // For other methods, return wrapped builder for chaining
-      const value = Reflect.get(target, prop, target);
-      if (typeof value === 'function') {
-        return (...args: unknown[]) => {
-          const result = Reflect.apply(value, target, args);
-          if (isExecutableQuery(result)) {
-            return createExecuteProxy(
-              result,
-              table,
-              collector,
-              engine,
-              keyField
-            );
-          }
-          return result;
-        };
-      }
-      return value;
-    },
-  });
-}
-
-/**
- * Create a tracked selectFrom that registers scopes and generates fingerprints.
- */
-export function createTrackedSelectFrom<DB>(
-  db: Kysely<DB>,
-  scopeCollector: Set<string>,
-  fingerprintCollector: FingerprintCollector,
-  engine: MutationTimestampSource,
-  keyField = 'id'
-): TrackedSelectFrom<DB> {
-  const selectFrom = <TB extends keyof DB & string>(table: TB) => {
-    // 1. Register this table as a watched scope
-    scopeCollector.add(table);
-
-    // 2. Get the real query builder
-    const builder = db.selectFrom(table);
-
-    // 3. Return a proxy that intercepts .execute()
-    return createExecuteProxy(
-      builder,
-      table,
-      fingerprintCollector,
-      engine,
-      keyField
-    );
-  };
-  return selectFrom as TrackedSelectFrom<DB>;
-}

package/src/schema.ts

@@ -1,94 +0,0 @@
-/**
- * @syncular/client - Sync client schema types (SQLite reference)
- *
- * These tables are sync-internal and should not collide with app tables.
- */
-
-import type { Generated, Kysely } from 'kysely';
-import type { SyncBlobClientDb } from './blobs/types';
-
-/**
- * Database executor type that both Kysely and Transaction satisfy.
- * Use this when a function needs to work with either a raw Kysely instance
- * or within a transaction context.
- */
-export type SyncClientExecutor<DB extends SyncClientDb = SyncClientDb> = Pick<
-  Kysely<DB>,
-  'selectFrom' | 'insertInto' | 'updateTable' | 'deleteFrom'
->;
-
-export type OutboxCommitStatus = 'pending' | 'sending' | 'acked' | 'failed';
-
-export type SubscriptionStatus = 'active' | 'revoked';
-
-export interface SyncSubscriptionStateTable {
-  /** Logical profile id (default: 'default') */
-  state_id: string;
-  /** Subscription identifier (client-chosen) */
-  subscription_id: string;
-  /** Table name for this subscription */
-  table: string;
-  /** JSON string of ScopeValues for this subscription */
-  scopes_json: string;
-  /** JSON string of params */
-  params_json: string;
-  /** Per-subscription cursor (last applied commit_seq) */
-  cursor: number;
-  /**
-   * JSON string of SyncBootstrapState (or null).
-   * When set, indicates a paginated bootstrap is in progress for this subscription.
-   */
-  bootstrap_state_json: string | null;
-  /** active | revoked */
-  status: SubscriptionStatus;
-  created_at: number;
-  updated_at: number;
-}
-
-export interface SyncOutboxCommitsTable {
-  /** Local row id (uuid) */
-  id: string;
-  /** Client-provided idempotency key (uuid) */
-  client_commit_id: string;
-  /** pending | sending | acked | failed */
-  status: OutboxCommitStatus;
-  /** JSON string of SyncOperation[] */
-  operations_json: string;
-  /** JSON string of the last SyncPushResponse (optional) */
-  last_response_json: string | null;
-  /** Last error (if any) */
-  error: string | null;
-  /** Created timestamp (ms since epoch) */
-  created_at: number;
-  /** Updated timestamp (ms since epoch) */
-  updated_at: number;
-  /** How many send attempts have been made */
-  attempt_count: Generated<number>;
-  /** Server commit_seq if acked (optional) */
-  acked_commit_seq: number | null;
-  /** Client schema version when commit was created (default: 1 for legacy) */
-  schema_version: Generated<number>;
-}
-
-export interface SyncClientDb extends SyncBlobClientDb {
-  sync_subscription_state: SyncSubscriptionStateTable;
-  sync_outbox_commits: SyncOutboxCommitsTable;
-  sync_conflicts: SyncConflictsTable;
-}
-
-export type ConflictResultStatus = 'conflict' | 'error';
-
-export interface SyncConflictsTable {
-  id: string;
-  outbox_commit_id: string;
-  client_commit_id: string;
-  op_index: number;
-  result_status: ConflictResultStatus;
-  message: string;
-  code: string | null;
-  server_version: number | null;
-  server_row_json: string | null;
-  created_at: number;
-  resolved_at: number | null;
-  resolution: string | null;
-}