@syncular/client 0.0.6-126 → 0.0.6-136

package/src/engine/types.ts

@@ -262,6 +262,23 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   onConflict?: (conflict: ConflictInfo) => void;
   /** Data change callback */
   onDataChange?: (scopes: string[]) => void;
+  /**
+   * Debounce window for coalescing `data:change` emissions.
+   * - `0` (default): emit immediately
+   * - `>0`: merge scopes and emit once per window
+   */
+  dataChangeDebounceMs?: number;
+  /**
+   * Override debounce window while `isSyncing === true`.
+   * If omitted, `dataChangeDebounceMs` is used.
+   */
+  dataChangeDebounceMsWhenSyncing?: number;
+  /**
+   * Override debounce window while `connectionState === "reconnecting"`.
+   * If omitted, `dataChangeDebounceMsWhenSyncing` (if syncing) or
+   * `dataChangeDebounceMs` is used.
+   */
+  dataChangeDebounceMsWhenReconnecting?: number;
   /** Optional client plugins (e.g. encryption) */
   plugins?: SyncClientPlugin[];
   /** Custom SHA-256 hash function (for platforms without crypto.subtle, e.g. React Native) */

package/src/migrate.ts

@@ -2,195 +2,9 @@
  * @syncular/client - Sync migrations (SQLite reference)
  */
 
-import { type Kysely, sql } from 'kysely';
+import type { Kysely } from 'kysely';
 import type { SyncClientDb } from './schema';
 
-type SyncInternalTable =
-  | 'sync_subscription_state'
-  | 'sync_outbox_commits'
-  | 'sync_conflicts';
-
-function toErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function isMissingTableError(message: string): boolean {
-  const normalized = message.toLowerCase();
-  return (
-    normalized.includes('no such table') ||
-    (normalized.includes('relation') && normalized.includes('does not exist'))
-  );
-}
-
-function isMissingColumnError(message: string): boolean {
-  const normalized = message.toLowerCase();
-  return (
-    normalized.includes('no such column') ||
-    (normalized.includes('column') && normalized.includes('does not exist'))
-  );
-}
-
-function isDuplicateColumnError(message: string): boolean {
-  const normalized = message.toLowerCase();
-  return (
-    normalized.includes('duplicate column name') ||
-    (normalized.includes('column') && normalized.includes('already exists'))
-  );
-}
-
-async function getColumnNames<DB extends SyncClientDb>(
-  db: Kysely<DB>,
-  tableName: SyncInternalTable
-): Promise<Set<string> | null> {
-  try {
-    const sqlite = await sql<{ name: string }>`
-      select name from pragma_table_info(${sql.val(tableName)})
-    `.execute(db);
-    return new Set(sqlite.rows.map((row) => String(row.name)));
-  } catch {
-    // Not SQLite or pragma unavailable.
-  }
-
-  try {
-    const postgres = await sql<{ name: string }>`
-      select column_name as name
-      from information_schema.columns
-      where table_name = ${sql.val(tableName)}
-    `.execute(db);
-    return new Set(postgres.rows.map((row) => String(row.name)));
-  } catch {
-    // Introspection unavailable; caller falls back to probing.
-  }
-
-  return null;
-}
-
-async function hasColumn<DB extends SyncClientDb>(
-  db: Kysely<DB>,
-  tableName: SyncInternalTable,
-  columnName: string
-): Promise<boolean> {
-  const columns = await getColumnNames(db, tableName);
-  if (columns) {
-    return columns.has(columnName);
-  }
-
-  try {
-    await sql`select ${sql.ref(columnName)} from ${sql.table(tableName)} limit 1`.execute(
-      db
-    );
-    return true;
-  } catch (error) {
-    const message = toErrorMessage(error);
-    if (isMissingTableError(message) || isMissingColumnError(message)) {
-      return false;
-    }
-    throw error;
-  }
-}
-
-async function addColumnIfMissing<DB extends SyncClientDb>(
-  db: Kysely<DB>,
-  tableName: SyncInternalTable,
-  columnName: string,
-  addColumn: () => Promise<void>
-): Promise<void> {
-  if (await hasColumn(db, tableName, columnName)) {
-    return;
-  }
-  try {
-    await addColumn();
-  } catch (error) {
-    const message = toErrorMessage(error);
-    if (isDuplicateColumnError(message)) {
-      return;
-    }
-    throw error;
-  }
-}
-
-async function ensureClientSyncSchemaCompat<DB extends SyncClientDb>(
-  db: Kysely<DB>
-): Promise<void> {
-  const hasTableColumn = await hasColumn(
-    db,
-    'sync_subscription_state',
-    'table'
-  );
-  if (
-    !hasTableColumn &&
-    (await hasColumn(db, 'sync_subscription_state', 'shape'))
-  ) {
-    try {
-      await sql`alter table ${sql.table('sync_subscription_state')} rename column ${sql.ref('shape')} to ${sql.ref('table')}`.execute(
-        db
-      );
-    } catch {
-      await addColumnIfMissing(
-        db,
-        'sync_subscription_state',
-        'table',
-        async () => {
-          await db.schema
-            .alterTable('sync_subscription_state')
-            .addColumn('table', 'text', (col) => col.notNull().defaultTo(''))
-            .execute();
-        }
-      );
-      await sql`update ${sql.table('sync_subscription_state')}
-        set ${sql.ref('table')} = ${sql.ref('shape')}
-        where ${sql.ref('table')} = ${sql.val('')}`.execute(db);
-    }
-  }
-
-  await addColumnIfMissing(
-    db,
-    'sync_subscription_state',
-    'bootstrap_state_json',
-    async () => {
-      await db.schema
-        .alterTable('sync_subscription_state')
-        .addColumn('bootstrap_state_json', 'text')
-        .execute();
-    }
-  );
-
-  await addColumnIfMissing(
-    db,
-    'sync_outbox_commits',
-    'schema_version',
-    async () => {
-      await db.schema
-        .alterTable('sync_outbox_commits')
-        .addColumn('schema_version', 'integer', (col) =>
-          col.notNull().defaultTo(1)
-        )
-        .execute();
-    }
-  );
-
-  await addColumnIfMissing(db, 'sync_conflicts', 'resolved_at', async () => {
-    await db.schema
-      .alterTable('sync_conflicts')
-      .addColumn('resolved_at', 'bigint')
-      .execute();
-  });
-
-  await addColumnIfMissing(db, 'sync_conflicts', 'resolution', async () => {
-    await db.schema
-      .alterTable('sync_conflicts')
-      .addColumn('resolution', 'text')
-      .execute();
-  });
-
-  await db.schema
-    .createIndex('idx_sync_outbox_commits_status_updated_at')
-    .ifNotExists()
-    .on('sync_outbox_commits')
-    .columns(['status', 'updated_at', 'created_at'])
-    .execute();
-}
-
 /**
  * Ensures the client sync schema exists in the database.
  * Safe to call multiple times (idempotent).
@@ -249,9 +63,6 @@ export async function ensureClientSyncSchema<DB extends SyncClientDb>(
     .addColumn('resolution', 'text')
     .execute();
 
-  // Apply framework-managed compatibility upgrades for legacy sync tables.
-  await ensureClientSyncSchemaCompat(db);
-
   await db.schema
     .createIndex('idx_sync_subscription_state_state_sub')
     .ifNotExists()

package/src/mutations.ts

@@ -168,7 +168,7 @@ function coerceBaseVersion(value: unknown): number | null {
   if (value === null || value === undefined) return null;
   const n = typeof value === 'number' ? value : Number(value);
   if (!Number.isFinite(n)) return null;
-  if (n <= 0) return null;
+  if (n < 0) return null;
   return n;
 }
 
@@ -498,6 +498,9 @@ export function createOutboxCommit<DB extends SyncClientDb>(
             },
 
             async insertMany(rows) {
+              if (rows.length === 0) {
+                throw new Error('insertMany requires at least one row');
+              }
               const ids: string[] = [];
               const toInsert: Record<string, unknown>[] = [];
 
@@ -672,6 +675,7 @@ export function createOutboxCommit<DB extends SyncClientDb>(
             get(_target, prop) {
               if (prop === 'then') return undefined;
               if (typeof prop !== 'string') return undefined;
+              validateTableName(prop);
               return makeTxTable(prop);
             },
           }
@@ -777,6 +781,9 @@ export function createPushCommit<DB = AnyDb>(
         },
 
         async insertMany(rows) {
+          if (rows.length === 0) {
+            throw new Error('insertMany requires at least one row');
+          }
           const ids: string[] = [];
           const toUpsert: Record<string, unknown>[] = [];
 
@@ -885,6 +892,7 @@ export function createPushCommit<DB = AnyDb>(
         get(_target, prop) {
           if (prop === 'then') return undefined;
           if (typeof prop !== 'string') return undefined;
+          validateTableName(prop);
           return makeTxTable(prop);
         },
       }

package/src/query/fingerprint.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'bun:test';
+import { computeRowFingerprint } from './fingerprint';
+
+function createTimestampSource(values: Record<string, number>): {
+  getMutationTimestamp: (table: string, rowId: string) => number;
+} {
+  return {
+    getMutationTimestamp(table: string, rowId: string): number {
+      return values[`${table}:${rowId}`] ?? 0;
+    },
+  };
+}
+
+describe('computeRowFingerprint', () => {
+  it('is deterministic for the same input rows', () => {
+    const source = createTimestampSource({
+      'tasks:a': 1,
+      'tasks:b': 2,
+    });
+    const rows = [{ id: 'a' }, { id: 'b' }];
+
+    const first = computeRowFingerprint(rows, 'tasks', source, 'id');
+    const second = computeRowFingerprint(rows, 'tasks', source, 'id');
+
+    expect(first).toBe(second);
+  });
+
+  it('changes when row order changes', () => {
+    const source = createTimestampSource({
+      'tasks:a': 1,
+      'tasks:b': 2,
+    });
+
+    const first = computeRowFingerprint(
+      [{ id: 'a' }, { id: 'b' }],
+      'tasks',
+      source,
+      'id'
+    );
+    const second = computeRowFingerprint(
+      [{ id: 'b' }, { id: 'a' }],
+      'tasks',
+      source,
+      'id'
+    );
+
+    expect(first).not.toBe(second);
+  });
+
+  it('changes when mutation timestamps change', () => {
+    const rows = [{ id: 'a' }];
+    const first = computeRowFingerprint(
+      rows,
+      'tasks',
+      createTimestampSource({ 'tasks:a': 1 }),
+      'id'
+    );
+    const second = computeRowFingerprint(
+      rows,
+      'tasks',
+      createTimestampSource({ 'tasks:a': 2 }),
+      'id'
+    );
+
+    expect(first).not.toBe(second);
+  });
+
+  it('returns compact hash format', () => {
+    const source = createTimestampSource({});
+    const fingerprint = computeRowFingerprint([], 'tasks', source, 'id');
+    expect(fingerprint).toMatch(/^tasks:0:[0-9a-f]{8}$/);
+  });
+});

package/src/query/fingerprint.ts

@@ -9,6 +9,32 @@ export interface MutationTimestampSource {
   getMutationTimestamp(table: string, rowId: string): number;
 }
 
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+
+function hashMix(hash: number, value: number): number {
+  return Math.imul(hash ^ value, FNV_PRIME) >>> 0;
+}
+
+function hashString(hash: number, value: string): number {
+  let next = hash;
+  for (let i = 0; i < value.length; i++) {
+    next = hashMix(next, value.charCodeAt(i));
+  }
+  return next;
+}
+
+function hashTimestamp(hash: number, value: number): number {
+  if (!Number.isFinite(value)) {
+    return hashMix(hash, 0);
+  }
+  // Keep three decimal places to preserve sub-millisecond precision.
+  const scaled = Math.round(value * 1000);
+  const lowBits = scaled >>> 0;
+  const highBits = Math.floor(scaled / 0x1_0000_0000) >>> 0;
+  return hashMix(hashMix(hash, lowBits), highBits);
+}
+
 /**
  * Compute a fingerprint for query results based on length + ids + mutation timestamps.
  * Much faster than deep equality for large datasets.
@@ -69,7 +95,7 @@ export function canFingerprint<T>(rows: T[], keyField = 'id'): boolean {
 
 /**
  * Compute row-level fingerprint from query results.
- * Format: `table:count:id1@ts1,id2@ts2,...`
+ * Format: `table:count:hash`
  */
 export function computeRowFingerprint(
   rows: unknown[],
@@ -77,17 +103,18 @@ export function computeRowFingerprint(
   engine: MutationTimestampSource,
   keyField: string
 ): string {
-  if (rows.length === 0) return `${table}:0:`;
-
-  const parts: string[] = [];
+  let hash = hashMix(FNV_OFFSET_BASIS, rows.length);
   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}`);
+    hash = hashString(hash, id);
+    hash = hashMix(hash, 0); // separator
+    hash = hashTimestamp(hash, ts);
+    hash = hashMix(hash, 1); // separator
   }
 
-  return `${table}:${rows.length}:${parts.join(',')}`;
+  return `${table}:${rows.length}:${hash.toString(16).padStart(8, '0')}`;
 }
 
 /**

package/src/sync-loop.ts

@@ -5,6 +5,7 @@
  */
 
 import type {
+  SyncCombinedResponse,
   SyncPullResponse,
   SyncPullSubscriptionResponse,
   SyncPushRequest,
@@ -244,25 +245,34 @@ async function syncOnceCombined<DB extends SyncClientDb>(
     }
   }
 
-  const combined = await transport.sync({
-    clientId,
-    ...(pushRequest && !wsPushResponse
-      ? {
-          push: {
-            clientCommitId: pushRequest.clientCommitId,
-            operations: pushRequest.operations,
-            schemaVersion: pushRequest.schemaVersion,
-          },
-        }
-      : {}),
-    pull: {
-      limitCommits: pullState.request.limitCommits,
-      limitSnapshotRows: pullState.request.limitSnapshotRows,
-      maxSnapshotPages: pullState.request.maxSnapshotPages,
-      dedupeRows: pullState.request.dedupeRows,
-      subscriptions: pullState.request.subscriptions,
-    },
-  });
+  let combined: SyncCombinedResponse;
+  try {
+    combined = await transport.sync({
+      clientId,
+      ...(pushRequest && !wsPushResponse
+        ? {
+            push: {
+              clientCommitId: pushRequest.clientCommitId,
+              operations: pushRequest.operations,
+              schemaVersion: pushRequest.schemaVersion,
+            },
+          }
+        : {}),
+      pull: {
+        limitCommits: pullState.request.limitCommits,
+        limitSnapshotRows: pullState.request.limitSnapshotRows,
+        maxSnapshotPages: pullState.request.maxSnapshotPages,
+        dedupeRows: pullState.request.dedupeRows,
+        subscriptions: pullState.request.subscriptions,
+      },
+    });
+  } catch (err) {
+    if (outbox) {
+      const message = err instanceof Error ? err.message : 'Unknown error';
+      await markOutboxCommitPending(db, { id: outbox.id, error: message });
+    }
+    throw err;
+  }
 
   // Process push response
   let pushedCommits = 0;