@syncular/client 0.1.3 → 0.2.0

package/src/node-database.ts

@@ -0,0 +1,180 @@
+/**
+ * `ClientDatabase` on better-sqlite3 — the Electron-main / plain-Node
+ * backend (TODO 2: Node ClientDatabase). Semantics mirror `./bun-database`
+ * exactly (synchronous exec/query/transaction with the shared savepoint
+ * helper, and the same §5.3 sqlite-image ATTACH path), so the core behaves
+ * identically whether it runs on bun:sqlite (tests), sqlite-wasm (browser)
+ * or better-sqlite3 (Node/Electron-main).
+ *
+ * better-sqlite3 is an OPTIONAL peer dependency, not a hard one: the package
+ * installs cleanly without it and this module errors helpfully only when a
+ * host actually calls `openNodeDatabase()` without having installed the peer.
+ * Not exported from the package root, so browser/bun entries never resolve
+ * the native module. Subpath export: `@syncular/client/node`.
+ *
+ * bun CANNOT dlopen better-sqlite3 (ERR_DLOPEN_FAILED, oven-sh/bun#4290), so
+ * this adapter is verified under real Node — see the README "Electron-main /
+ * plain-Node" section for the one-command recipe and `test/node-database`.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  assertImageAlias,
+  type ClientDatabase,
+  runTransaction,
+  type SqlRow,
+  type SqlValue,
+} from './database';
+
+/**
+ * Structural view of the tiny better-sqlite3 surface this binding uses. We
+ * type it locally (rather than importing `better-sqlite3`'s types) so the
+ * package typechecks without the optional peer installed.
+ */
+interface BetterSqliteStatement {
+  run(...params: NodeParam[]): unknown;
+  all(...params: NodeParam[]): unknown[];
+}
+interface BetterSqliteDatabase {
+  readonly inTransaction: boolean;
+  prepare(sql: string): BetterSqliteStatement;
+  exec(sql: string): unknown;
+  close(): void;
+}
+type BetterSqliteConstructor = new (
+  path: string,
+  options?: { readonly?: boolean; fileMustExist?: boolean },
+) => BetterSqliteDatabase;
+
+/**
+ * better-sqlite3 accepts string / number / bigint / null / Buffer|Uint8Array
+ * bind values, but NOT booleans (it throws "TypeError: can only bind …"). We
+ * coerce booleans to 0/1 exactly like the bun adapter so callers see one
+ * uniform bind contract across every backend.
+ */
+type NodeParam = string | number | bigint | Uint8Array | null;
+
+function coerceParams(params: readonly SqlValue[]): NodeParam[] {
+  return params.map((value): NodeParam => {
+    if (typeof value === 'boolean') return value ? 1 : 0;
+    return value;
+  });
+}
+
+/**
+ * better-sqlite3 returns BLOB columns as Node `Buffer`s. A Buffer IS a
+ * Uint8Array subclass, but it can be a view onto a shared pool buffer, so we
+ * normalize to a standalone Uint8Array — matching what bun:sqlite hands back
+ * and keeping the buffer-ownership assumptions elsewhere (worker transfer,
+ * structured clone) honest.
+ */
+function normalizeRow(row: Record<string, unknown>): SqlRow {
+  const out: SqlRow = {};
+  for (const key in row) {
+    const value = row[key];
+    if (Buffer.isBuffer(value)) {
+      out[key] = new Uint8Array(value); // copies out of the pool
+    } else {
+      out[key] = value as SqlValue;
+    }
+  }
+  return out;
+}
+
+/**
+ * Load the optional peer AND open the database in one guarded step, so BOTH
+ * failure modes are turned into a clear, actionable error rather than a raw
+ * one:
+ *
+ *  - `require('better-sqlite3')` throwing MODULE_NOT_FOUND — the peer is not
+ *    installed (the common browser-only-host case), and
+ *  - `new Database()` throwing ERR_DLOPEN_FAILED — the module resolves but the
+ *    native addon cannot load, which is exactly what bun does for
+ *    better-sqlite3 (oven-sh/bun#4290); the addon only dlopens at construction.
+ */
+function openBetterSqlite(path: string): BetterSqliteDatabase {
+  const require = createRequire(import.meta.url);
+  try {
+    const mod = require('better-sqlite3') as
+      | BetterSqliteConstructor
+      | { default: BetterSqliteConstructor };
+    const Database =
+      (mod as { default?: BetterSqliteConstructor }).default ??
+      (mod as BetterSqliteConstructor);
+    return new Database(path);
+  } catch (error) {
+    const code = (error as { code?: string })?.code;
+    if (code === 'ERR_DLOPEN_FAILED') {
+      throw new Error(
+        "openNodeDatabase() requires the 'better-sqlite3' native module, but " +
+          'it failed to load. This most commonly means you are running under ' +
+          'bun, which cannot dlopen better-sqlite3 (oven-sh/bun#4290) — use ' +
+          "the bun:sqlite backend ('@syncular/client/bun') under bun, " +
+          "and reserve '@syncular/client/node' for Node/Electron-main. " +
+          `Underlying error: ${String(error)}`,
+      );
+    }
+    throw new Error(
+      'openNodeDatabase() requires the optional peer dependency ' +
+        "'better-sqlite3', which is not installed. Add it to your app " +
+        '(`npm install better-sqlite3` / `bun add better-sqlite3`) — it is ' +
+        'kept optional so @syncular/client installs without a native ' +
+        `build for browser-only hosts. Underlying error: ${String(error)}`,
+    );
+  }
+}
+
+export class NodeClientDatabase implements ClientDatabase {
+  readonly db: BetterSqliteDatabase;
+  #tx = { depth: 0 };
+
+  constructor(path = ':memory:') {
+    this.db = openBetterSqlite(path);
+  }
+
+  exec(sql: string, params: readonly SqlValue[] = []): void {
+    this.db.prepare(sql).run(...coerceParams(params));
+  }
+
+  query(sql: string, params: readonly SqlValue[] = []): SqlRow[] {
+    const rows = this.db.prepare(sql).all(...coerceParams(params));
+    return (rows as Record<string, unknown>[]).map(normalizeRow);
+  }
+
+  transaction<T>(fn: () => T): T {
+    return runTransaction(this.#tx, (sql) => this.db.exec(sql), fn);
+  }
+
+  /**
+   * §5.3 image import: better-sqlite3 (like bun:sqlite) attaches files, not
+   * buffers, so the image lands in a private temp file for the duration of
+   * the ATTACH. Must be called outside any open transaction (SQLite cannot
+   * ATTACH inside one).
+   */
+  withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T): T {
+    assertImageAlias(alias);
+    const dir = mkdtempSync(join(tmpdir(), 'syncular-image-'));
+    const path = join(dir, 'segment.db');
+    try {
+      writeFileSync(path, bytes);
+      this.db.prepare(`ATTACH DATABASE ? AS ${alias}`).run(path);
+      try {
+        return fn();
+      } finally {
+        this.db.prepare(`DETACH DATABASE ${alias}`).run();
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+export function openNodeDatabase(path = ':memory:'): ClientDatabase {
+  return new NodeClientDatabase(path);
+}

package/src/outbox.ts

@@ -0,0 +1,206 @@
+/**
+ * The durable outbox (SPEC.md §7.1) with encode-at-send (the §0 binary-push
+ * outbox rule): local mutations are persisted in a schema-agnostic JSON
+ * form and encoded with the *current* generated row codec only when a push
+ * request is built — a commit recorded under schema N replays after an
+ * upgrade to N+1 by re-encoding.
+ */
+import {
+  encodeRow,
+  type PushCommitFrame,
+  type PushOperation,
+  type ScopeMap,
+} from '@syncular/core';
+import type { ClientDatabase } from './database';
+import type { EncryptionConfig } from './encryption';
+import { ClientSyncError } from './errors';
+import {
+  type CompiledClientSchema,
+  type CompiledClientTable,
+  type JsonRowValue,
+  jsonToRowValue,
+} from './schema';
+
+export interface OutboxOperation {
+  readonly table: string;
+  readonly rowId: string;
+  readonly op: 'upsert' | 'delete';
+  /** Optimistic-concurrency token (§6.2); absent = last-write-wins. */
+  readonly baseVersion?: number;
+  /** Full-row values keyed by column name; present iff `op` is `upsert`. */
+  readonly values?: Readonly<Record<string, JsonRowValue>>;
+}
+
+export interface OutboxCommit {
+  readonly seq: number;
+  readonly clientCommitId: string;
+  readonly createdAtMs: number;
+  readonly operations: readonly OutboxOperation[];
+}
+
+export function appendOutboxCommit(
+  db: ClientDatabase,
+  clientCommitId: string,
+  operations: readonly OutboxOperation[],
+  nowMs: number,
+): void {
+  if (operations.length === 0) {
+    throw new ClientSyncError(
+      'sync.empty_commit',
+      'a local commit must carry at least one operation (§6.1)',
+    );
+  }
+  db.exec(
+    `INSERT INTO _syncular_outbox(client_commit_id, created_at_ms, operations)
+     VALUES (?, ?, ?)`,
+    [clientCommitId, nowMs, JSON.stringify(operations)],
+  );
+}
+
+/** Pending commits in FIFO creation order (§7.1). */
+export function listOutbox(db: ClientDatabase): OutboxCommit[] {
+  return db
+    .query(
+      `SELECT seq, client_commit_id, created_at_ms, operations
+       FROM _syncular_outbox ORDER BY seq ASC`,
+    )
+    .map((row) => ({
+      seq: row.seq as number,
+      clientCommitId: row.client_commit_id as string,
+      createdAtMs: row.created_at_ms as number,
+      operations: JSON.parse(row.operations as string) as OutboxOperation[],
+    }));
+}
+
+export function deleteOutboxCommit(
+  db: ClientDatabase,
+  clientCommitId: string,
+): void {
+  db.exec('DELETE FROM _syncular_outbox WHERE client_commit_id = ?', [
+    clientCommitId,
+  ]);
+}
+
+/**
+ * §7.4.4: after a schema bump, a persisted upsert may name a column the new
+ * schema no longer has. The value has nowhere to go and there is no
+ * migration — surface it as `sync.outbox_incompatible` (client-local, §10.3)
+ * so the caller can drop the commit through the rejection channel.
+ */
+export class OutboxEncodeError extends ClientSyncError {
+  constructor(message: string) {
+    super('sync.outbox_incompatible', message, false);
+  }
+}
+
+function orderedValues(
+  table: CompiledClientTable,
+  values: Readonly<Record<string, JsonRowValue>>,
+) {
+  // Any persisted key that is not a column of the CURRENT schema means the
+  // bump removed (or renamed) it — the commit cannot be expressed now.
+  for (const key of Object.keys(values)) {
+    if (!table.columnIndex.has(key)) {
+      throw new OutboxEncodeError(
+        `outbox commit references column ${JSON.stringify(key)} on ${JSON.stringify(table.name)}, which the current schema no longer has (§7.4.4)`,
+      );
+    }
+  }
+  return table.columns.map((column) => {
+    const value = values[column.name];
+    if (value === undefined) return null;
+    return jsonToRowValue(value);
+  });
+}
+
+/**
+ * Encode one outbox commit as a `PUSH_COMMIT` frame with the current
+ * schema's row codec (§6.1). When `encryption` is configured, encrypted
+ * columns (§5.11) are encrypted here — the encode-at-send seam — before the
+ * row codec serializes them as ciphertext-envelope `bytes`. Async because
+ * WebCrypto is async.
+ */
+export async function encodeOutboxCommit(
+  schema: CompiledClientSchema,
+  commit: OutboxCommit,
+  encryption?: EncryptionConfig,
+): Promise<PushCommitFrame> {
+  const operations: PushOperation[] = [];
+  for (const op of commit.operations) {
+    if (op.op === 'delete') {
+      operations.push({
+        table: op.table,
+        rowId: op.rowId,
+        op: 'delete',
+        ...(op.baseVersion !== undefined
+          ? { baseVersion: op.baseVersion }
+          : {}),
+      });
+      continue;
+    }
+    const table = schema.tables.get(op.table);
+    if (table === undefined) {
+      // §7.4.4: the bump removed this table — the commit cannot be encoded.
+      throw new OutboxEncodeError(
+        `outbox commit ${commit.clientCommitId} targets table ${JSON.stringify(op.table)}, which the current schema no longer has (§7.4.4)`,
+      );
+    }
+    if (op.values === undefined) {
+      throw new ClientSyncError(
+        'sync.invalid_request',
+        `outbox upsert on ${op.table}/${op.rowId} has no values`,
+      );
+    }
+    let values = orderedValues(table, op.values);
+    if (encryption !== undefined && table.hasEncryptedColumns) {
+      // Lazy: opt-in E2EE never enters an encryption-free app's bundle.
+      const { encryptRowValues } = await import('./encryption');
+      values = await encryptRowValues(encryption, table, op.rowId, values);
+    }
+    operations.push({
+      table: op.table,
+      rowId: op.rowId,
+      op: 'upsert',
+      ...(op.baseVersion !== undefined ? { baseVersion: op.baseVersion } : {}),
+      payload: encodeRow(table.columns, values),
+    });
+  }
+  return {
+    type: 'PUSH_COMMIT',
+    clientCommitId: commit.clientCommitId,
+    operations,
+  };
+}
+
+/**
+ * §3.3: drop pending commits that write into a revoked scope instead of
+ * replaying them into guaranteed rejections. A whole commit is dropped when
+ * any of its upserts provably lands in the revoked effective scopes —
+ * commits are atomic and their content is pinned by the idempotency key,
+ * so ops are never removed individually. Returns dropped commit ids.
+ */
+export function dropOutboxCommitsInScope(
+  db: ClientDatabase,
+  table: CompiledClientTable,
+  effective: ScopeMap,
+): string[] {
+  const entries = Object.entries(effective);
+  if (entries.length === 0) return [];
+  const dropped: string[] = [];
+  for (const commit of listOutbox(db)) {
+    const inScope = commit.operations.some((op) => {
+      if (op.table !== table.name || op.values === undefined) return false;
+      return entries.every(([variable, values]) => {
+        const column = table.scopeColumnByVariable.get(variable);
+        if (column === undefined) return false;
+        const value = op.values?.[column];
+        return typeof value === 'string' && values.includes(value);
+      });
+    });
+    if (inScope) {
+      deleteOutboxCommit(db, commit.clientCommitId);
+      dropped.push(commit.clientCommitId);
+    }
+  }
+  return dropped;
+}