@syncular/client 0.0.1-60

package/src/query/FingerprintCollector.ts

@@ -0,0 +1,29 @@
+/**
+ * @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

@@ -0,0 +1,54 @@
+/**
+ * @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

@@ -0,0 +1,109 @@
+/**
+ * @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

@@ -0,0 +1,10 @@
+/**
+ * @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

@@ -0,0 +1,139 @@
+/**
+ * @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

@@ -0,0 +1,94 @@
+/**
+ * @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;
+  /** Shape name (table) for this subscription */
+  shape: 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;
+}