@syncular/client 0.0.6-95 → 0.1.0

package/src/command-history.ts

@@ -0,0 +1,623 @@
+import { randomId } from '@syncular/core';
+import {
+  createMutationsApi,
+  type MutationReceipt,
+  type MutationsApi,
+  type MutationsCommitFn,
+  type MutationsTx,
+  type TableMutationsTx,
+} from './mutations';
+import type {
+  SyncularSqlClient,
+  SyncularTableConfigMap,
+  SyncularUnsafeSqlClient,
+} from './types';
+
+type AnyDb = Record<string, Record<string, unknown>>;
+type MutationScope = 'mutations' | 'leasedMutations';
+type RowSnapshot = Record<string, unknown> | null;
+
+interface HistoryRow extends Record<string, unknown> {
+  id: string;
+  mutation_scope: MutationScope;
+  state: 'done' | 'undone';
+  entries_json: string;
+  client_commit_id: string;
+  undo_client_commit_id: string | null;
+  redo_client_commit_id: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+interface CommandEntry {
+  table: string;
+  rowId: string;
+  before: RowSnapshot;
+  after: RowSnapshot;
+}
+
+interface PendingCommandEntry {
+  table: string;
+  rowId: string;
+  before: RowSnapshot;
+}
+
+export type SyncularCommandHistoryErrorCode =
+  | 'sync.command_history_empty'
+  | 'sync.command_history_conflict'
+  | 'sync.command_history_storage_unavailable'
+  | 'sync.command_history_table_unsupported'
+  | 'sync.command_history_unsafe_field';
+
+export class SyncularCommandHistoryError extends Error {
+  readonly code: SyncularCommandHistoryErrorCode;
+  readonly commandId?: string;
+
+  constructor(
+    code: SyncularCommandHistoryErrorCode,
+    message: string,
+    options: { commandId?: string } = {}
+  ) {
+    super(message);
+    this.name = 'SyncularCommandHistoryError';
+    this.code = code;
+    this.commandId = options.commandId;
+  }
+}
+
+export interface SyncularCommandHistoryReceipt extends MutationReceipt {
+  commandId: string;
+}
+
+export interface SyncularCommandHistory {
+  canUndo(): Promise<boolean>;
+  canRedo(): Promise<boolean>;
+  undoLast(): Promise<SyncularCommandHistoryReceipt>;
+  redoLast(): Promise<SyncularCommandHistoryReceipt>;
+}
+
+export interface SyncularCommandHistoryController<DB> {
+  history: SyncularCommandHistory;
+  wrapMutations(
+    mutations: MutationsApi<DB, undefined>,
+    scope: MutationScope
+  ): MutationsApi<DB, undefined>;
+}
+
+export interface CreateSyncularCommandHistoryOptions<DB> {
+  client: SyncularSqlClient & Partial<SyncularUnsafeSqlClient>;
+  tableConfig: SyncularTableConfigMap;
+  mutations: MutationsApi<DB, undefined>;
+  leasedMutations: MutationsApi<DB, undefined>;
+  nowMs?: () => number;
+  idFactory?: () => string;
+}
+
+export function createSyncularCommandHistory<DB>(
+  options: CreateSyncularCommandHistoryOptions<DB>
+): SyncularCommandHistoryController<DB> {
+  const store = new CommandHistoryStore(options);
+  const history = new CommandHistory(options, store);
+
+  return {
+    history,
+    wrapMutations(mutations, scope) {
+      return createMutationsApi(createTrackedCommit(mutations, scope, history));
+    },
+  };
+}
+
+function createTrackedCommit<DB>(
+  mutations: MutationsApi<DB, undefined>,
+  scope: MutationScope,
+  history: CommandHistory<DB>
+): MutationsCommitFn<DB, void, undefined> {
+  return async (fn) => {
+    await history.ensureReady();
+    const recorder = new PendingCommandRecorder(history);
+    const { result, commit } = await mutations.$commit(async (tx) =>
+      fn(createTrackedTx(tx, recorder) as MutationsTx<DB>)
+    );
+    await recorder.recordCommitted(scope, commit);
+    return { result, receipt: commit, meta: undefined };
+  };
+}
+
+function createTrackedTx<DB>(
+  tx: MutationsTx<DB>,
+  recorder: PendingCommandRecorder<DB>
+): MutationsTx<DB> {
+  const tableCache = new Map<string, TableMutationsTx<AnyDb, string>>();
+  return new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (prop === 'then') return undefined;
+        if (typeof prop !== 'string') return undefined;
+        const cached = tableCache.get(prop);
+        if (cached) return cached;
+        const tableTx = tx[prop] as TableMutationsTx<AnyDb, string> | undefined;
+        if (!tableTx) return undefined;
+        const tracked = createTrackedTableTx(prop, tableTx, recorder);
+        tableCache.set(prop, tracked);
+        return tracked;
+      },
+    }
+  ) as MutationsTx<DB>;
+}
+
+function createTrackedTableTx<DB>(
+  table: string,
+  tableTx: TableMutationsTx<AnyDb, string>,
+  recorder: PendingCommandRecorder<DB>
+): TableMutationsTx<AnyDb, string> {
+  return {
+    async insert(values) {
+      const id = await tableTx.insert(values);
+      await recorder.track(table, id);
+      return id;
+    },
+    async insertMany(rows) {
+      const ids = await tableTx.insertMany(rows);
+      for (const id of ids) await recorder.track(table, id);
+      return ids;
+    },
+    async update(id, patch, options) {
+      await recorder.track(table, id);
+      await tableTx.update(id, patch, options);
+    },
+    async delete(id, options) {
+      await recorder.track(table, id);
+      await tableTx.delete(id, options);
+    },
+    async upsert(id, patch, options) {
+      await recorder.track(table, id);
+      await tableTx.upsert(id, patch, options);
+    },
+  };
+}
+
+class PendingCommandRecorder<DB> {
+  readonly #entries = new Map<string, PendingCommandEntry>();
+
+  constructor(private readonly history: CommandHistory<DB>) {}
+
+  async track(table: string, rowId: string): Promise<void> {
+    const key = `${table}\0${rowId}`;
+    if (this.#entries.has(key)) return;
+    this.#entries.set(key, {
+      table,
+      rowId,
+      before: await this.history.readRow(table, rowId),
+    });
+  }
+
+  async recordCommitted(
+    scope: MutationScope,
+    receipt: MutationReceipt
+  ): Promise<void> {
+    if (this.#entries.size === 0) return;
+    const entries: CommandEntry[] = [];
+    for (const entry of this.#entries.values()) {
+      const after = await this.history.readRow(entry.table, entry.rowId);
+      if (sameSnapshot(entry.before, after)) continue;
+      entries.push({ ...entry, after });
+    }
+    if (entries.length === 0) return;
+    await this.history.record(scope, entries, receipt);
+  }
+}
+
+class CommandHistory<DB> implements SyncularCommandHistory {
+  constructor(
+    private readonly options: CreateSyncularCommandHistoryOptions<DB>,
+    private readonly store: CommandHistoryStore<DB>
+  ) {}
+
+  ensureReady(): Promise<void> {
+    return this.store.ensureReady();
+  }
+
+  readRow(table: string, rowId: string): Promise<RowSnapshot> {
+    const config = this.options.tableConfig[table];
+    if (!config) {
+      throw new SyncularCommandHistoryError(
+        'sync.command_history_table_unsupported',
+        `Cannot record undo history for unsupported table ${table}`
+      );
+    }
+    return readCurrentRow(
+      this.options.client,
+      table,
+      config.primaryKeyColumn ?? 'id',
+      rowId
+    );
+  }
+
+  record(
+    scope: MutationScope,
+    entries: CommandEntry[],
+    receipt: MutationReceipt
+  ): Promise<void> {
+    return this.store.insert(scope, entries, receipt);
+  }
+
+  async canUndo(): Promise<boolean> {
+    await this.ensureReady();
+    return (await this.store.latest('done')) !== null;
+  }
+
+  async canRedo(): Promise<boolean> {
+    await this.ensureReady();
+    return (await this.store.latest('undone')) !== null;
+  }
+
+  async undoLast(): Promise<SyncularCommandHistoryReceipt> {
+    await this.ensureReady();
+    const command = await this.store.latest('done');
+    if (!command) {
+      throw new SyncularCommandHistoryError(
+        'sync.command_history_empty',
+        'There is no Syncular command to undo'
+      );
+    }
+    const entries = decodeEntries(command);
+    this.assertSafeReplay(command.id, entries);
+    await this.assertCurrentRows(command.id, entries, 'after');
+    const commit = await this.applySnapshots(
+      command.mutation_scope,
+      [...entries].reverse().map((entry) => ({
+        table: entry.table,
+        rowId: entry.rowId,
+        snapshot: entry.before,
+      }))
+    );
+    await this.store.mark(command.id, 'undone', commit);
+    return { ...commit, commandId: command.id };
+  }
+
+  async redoLast(): Promise<SyncularCommandHistoryReceipt> {
+    await this.ensureReady();
+    const command = await this.store.latest('undone');
+    if (!command) {
+      throw new SyncularCommandHistoryError(
+        'sync.command_history_empty',
+        'There is no Syncular command to redo'
+      );
+    }
+    const entries = decodeEntries(command);
+    this.assertSafeReplay(command.id, entries);
+    await this.assertCurrentRows(command.id, entries, 'before');
+    const commit = await this.applySnapshots(
+      command.mutation_scope,
+      entries.map((entry) => ({
+        table: entry.table,
+        rowId: entry.rowId,
+        snapshot: entry.after,
+      }))
+    );
+    await this.store.mark(command.id, 'done', commit);
+    return { ...commit, commandId: command.id };
+  }
+
+  private async assertCurrentRows(
+    commandId: string,
+    entries: readonly CommandEntry[],
+    expected: 'before' | 'after'
+  ): Promise<void> {
+    for (const entry of entries) {
+      const config = this.options.tableConfig[entry.table];
+      if (!config) {
+        throw new SyncularCommandHistoryError(
+          'sync.command_history_table_unsupported',
+          `Cannot replay undo history for unsupported table ${entry.table}`,
+          { commandId }
+        );
+      }
+      const current = await this.readRow(entry.table, entry.rowId);
+      if (!sameReplaySnapshot(config, current, entry[expected])) {
+        throw new SyncularCommandHistoryError(
+          'sync.command_history_conflict',
+          `Cannot ${expected === 'after' ? 'undo' : 'redo'} Syncular command ${commandId}; ${entry.table}.${entry.rowId} changed since the command was recorded`,
+          { commandId }
+        );
+      }
+    }
+  }
+
+  private assertSafeReplay(
+    commandId: string,
+    entries: readonly CommandEntry[]
+  ): void {
+    for (const entry of entries) {
+      const config = this.options.tableConfig[entry.table];
+      if (!config) {
+        throw new SyncularCommandHistoryError(
+          'sync.command_history_table_unsupported',
+          `Cannot replay undo history for unsupported table ${entry.table}`,
+          { commandId }
+        );
+      }
+      const unsafeFields = unsafeChangedFields(config, entry);
+      if (unsafeFields.length > 0) {
+        throw new SyncularCommandHistoryError(
+          'sync.command_history_unsafe_field',
+          `Cannot replay Syncular command ${commandId}; ${entry.table}.${entry.rowId} changed unsafe fields: ${unsafeFields.join(', ')}`,
+          { commandId }
+        );
+      }
+    }
+  }
+
+  private async applySnapshots(
+    scope: MutationScope,
+    snapshots: Array<{ table: string; rowId: string; snapshot: RowSnapshot }>
+  ): Promise<MutationReceipt> {
+    const mutations =
+      scope === 'leasedMutations'
+        ? this.options.leasedMutations
+        : this.options.mutations;
+    const { commit } = await mutations.$commit(async (tx) => {
+      for (const snapshot of snapshots) {
+        const table = tx[snapshot.table] as
+          | TableMutationsTx<AnyDb, string>
+          | undefined;
+        if (!table) {
+          throw new SyncularCommandHistoryError(
+            'sync.command_history_table_unsupported',
+            `Cannot apply undo history for unsupported table ${snapshot.table}`
+          );
+        }
+        if (snapshot.snapshot === null) {
+          await table.delete(snapshot.rowId);
+        } else {
+          await table.upsert(
+            snapshot.rowId,
+            this.mutationPayloadForSnapshot(snapshot.table, snapshot.snapshot)
+          );
+        }
+      }
+    });
+    return commit;
+  }
+
+  private mutationPayloadForSnapshot(
+    table: string,
+    snapshot: Record<string, unknown>
+  ): Record<string, unknown> {
+    const config = this.options.tableConfig[table];
+    if (!config) {
+      throw new SyncularCommandHistoryError(
+        'sync.command_history_table_unsupported',
+        `Cannot apply undo history for unsupported table ${table}`
+      );
+    }
+    const payload = { ...snapshot };
+    delete payload[config.primaryKeyColumn ?? 'id'];
+    if (config.serverVersionColumn) delete payload[config.serverVersionColumn];
+    for (const field of config.crdtYjsFields ?? []) {
+      delete payload[field.stateColumn];
+    }
+    return payload;
+  }
+}
+
+class CommandHistoryStore<DB> {
+  #ready: Promise<void> | undefined;
+
+  constructor(
+    private readonly options: CreateSyncularCommandHistoryOptions<DB>
+  ) {}
+
+  ensureReady(): Promise<void> {
+    this.#ready ??= this.#ensureReady();
+    return this.#ready;
+  }
+
+  async insert(
+    scope: MutationScope,
+    entries: readonly CommandEntry[],
+    receipt: MutationReceipt
+  ): Promise<void> {
+    await this.ensureReady();
+    const now = this.now();
+    const id = this.options.idFactory?.() ?? `cmd_${randomId()}`;
+    const client = this.unsafeClient();
+    await client.executeUnsafeSql(
+      "delete from sync_command_history where state = 'undone'"
+    );
+    await client.executeUnsafeSql(
+      `insert into sync_command_history (
+        id,
+        mutation_scope,
+        state,
+        entries_json,
+        client_commit_id,
+        created_at,
+        updated_at
+      ) values (?, ?, 'done', ?, ?, ?, ?)`,
+      [id, scope, JSON.stringify(entries), receipt.clientCommitId, now, now]
+    );
+  }
+
+  async latest(state: 'done' | 'undone'): Promise<HistoryRow | null> {
+    await this.ensureReady();
+    const result = await this.options.client.executeSql<HistoryRow>(
+      `select id, mutation_scope, state, entries_json, client_commit_id,
+              undo_client_commit_id, redo_client_commit_id, created_at, updated_at
+       from sync_command_history
+       where state = ?
+       order by updated_at desc, created_at desc, id desc
+       limit 1`,
+      [state]
+    );
+    return result.rows[0] ?? null;
+  }
+
+  async mark(
+    id: string,
+    state: 'done' | 'undone',
+    receipt: MutationReceipt
+  ): Promise<void> {
+    await this.ensureReady();
+    const replayColumn =
+      state === 'undone' ? 'undo_client_commit_id' : 'redo_client_commit_id';
+    await this.unsafeClient().executeUnsafeSql(
+      `update sync_command_history
+       set state = ?, updated_at = ?, ${replayColumn} = ?
+       where id = ?`,
+      [state, this.now(), receipt.clientCommitId, id]
+    );
+  }
+
+  async #ensureReady(): Promise<void> {
+    const client = this.unsafeClient();
+    await client.executeUnsafeSql(
+      `create table if not exists sync_command_history (
+        id text primary key,
+        mutation_scope text not null,
+        state text not null check (state in ('done', 'undone')),
+        entries_json text not null,
+        client_commit_id text not null,
+        undo_client_commit_id text null,
+        redo_client_commit_id text null,
+        created_at integer not null,
+        updated_at integer not null
+      )`
+    );
+    await client.executeUnsafeSql(
+      `create index if not exists idx_sync_command_history_state_updated
+       on sync_command_history (state, updated_at, created_at)`
+    );
+  }
+
+  private unsafeClient(): SyncularUnsafeSqlClient {
+    const client = this.options.client;
+    if (typeof client.executeUnsafeSql === 'function') {
+      return client as SyncularUnsafeSqlClient;
+    }
+    throw new SyncularCommandHistoryError(
+      'sync.command_history_storage_unavailable',
+      'Syncular command history requires internal SQLite write access'
+    );
+  }
+
+  private now(): number {
+    return Math.trunc(this.options.nowMs?.() ?? Date.now());
+  }
+}
+
+async function readCurrentRow(
+  client: SyncularSqlClient,
+  table: string,
+  idColumn: string,
+  rowId: string
+): Promise<RowSnapshot> {
+  const result = await client.executeSql(
+    `select * from ${quoteIdentifier(table)} where ${quoteIdentifier(idColumn)} = ? limit 1`,
+    [rowId]
+  );
+  const row = result.rows[0];
+  return row ? normalizeSnapshot(row) : null;
+}
+
+function decodeEntries(row: HistoryRow): CommandEntry[] {
+  const entries = JSON.parse(row.entries_json) as CommandEntry[];
+  if (!Array.isArray(entries)) {
+    throw new SyncularCommandHistoryError(
+      'sync.command_history_conflict',
+      `Syncular command history row ${row.id} is malformed`,
+      { commandId: row.id }
+    );
+  }
+  return entries;
+}
+
+function normalizeSnapshot(
+  row: Record<string, unknown>
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(row).sort(([a], [b]) => a.localeCompare(b))
+  );
+}
+
+function sameSnapshot(left: RowSnapshot, right: RowSnapshot): boolean {
+  return stableJson(left) === stableJson(right);
+}
+
+function sameReplaySnapshot(
+  config: SyncularTableConfigMap[string],
+  left: RowSnapshot,
+  right: RowSnapshot
+): boolean {
+  return (
+    stableJson(replayComparableSnapshot(config, left)) ===
+    stableJson(replayComparableSnapshot(config, right))
+  );
+}
+
+function replayComparableSnapshot(
+  config: SyncularTableConfigMap[string],
+  snapshot: RowSnapshot
+): RowSnapshot {
+  if (snapshot === null) return null;
+  const comparable = { ...snapshot };
+  if (config.serverVersionColumn) delete comparable[config.serverVersionColumn];
+  for (const field of config.crdtYjsFields ?? []) {
+    delete comparable[field.stateColumn];
+  }
+  return comparable;
+}
+
+function unsafeChangedFields(
+  config: SyncularTableConfigMap[string],
+  entry: CommandEntry
+): string[] {
+  const rowLifecycleReplay = entry.before === null || entry.after === null;
+  const unsafeFields = new Set<string>();
+  for (const column of config.blobColumns ?? []) unsafeFields.add(column);
+  for (const field of config.encryptedFields ?? [])
+    unsafeFields.add(field.field);
+  if (!rowLifecycleReplay) {
+    for (const field of config.crdtYjsFields ?? []) {
+      unsafeFields.add(field.field);
+      unsafeFields.add(field.stateColumn);
+    }
+  }
+
+  const changed: string[] = [];
+  for (const field of unsafeFields) {
+    const before = entry.before?.[field];
+    const after = entry.after?.[field];
+    if (
+      stableJson(nullishToNull(before)) === stableJson(nullishToNull(after))
+    ) {
+      continue;
+    }
+    if (rowLifecycleReplay && before == null && after == null) continue;
+    changed.push(field);
+  }
+  return changed;
+}
+
+function nullishToNull(value: unknown): unknown {
+  return value == null ? null : value;
+}
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(sortValue(value));
+}
+
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, nested]) => [key, sortValue(nested)])
+  );
+}
+
+function quoteIdentifier(identifier: string): string {
+  return `"${identifier.replaceAll('"', '""')}"`;
+}