@catalyst-cloud/replicate 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { applyDelta, truncateReplica, getCursor, setCursor } from "./replicate.js";
+export type { ReplicaWriteDb, ReplicaChange, ToBindable } from "./replicate.js";

package/{src/index.ts → dist/index.js}

@@ -4,6 +4,4 @@
 // lands a change-feed record into a local SQLite replica over the portable `ReplicaWriteDb` handle, so
 // the IDENTICAL apply logic runs unchanged in the host-sync bun:sqlite replica and the browser OPFS
 // wasm replica — collapsing the two hand-maintained `apply.ts` twins into one source of truth.
-
-export { applyDelta, truncateReplica, getCursor, setCursor } from "./replicate";
-export type { ReplicaWriteDb, ReplicaChange, ToBindable } from "./replicate";
+export { applyDelta, truncateReplica, getCursor, setCursor } from "./replicate.js";

package/dist/replicate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The portable replica WRITE seam — the write counterpart to read-model's `SqlExecutor`. bun:sqlite
+ * (host-sync) and sqlite-wasm (browser OPFS) each satisfy it via a thin adapter. Generic over the
+ * bindable type `B` because the two engines coerce binary/bigint differently (bun binds Uint8Array /
+ * bigint; wasm binds ArrayBuffer / number) — the runtime supplies its own `toBindable` so every bound
+ * value is already a `B`.
+ */
+export interface ReplicaWriteDb<B> {
+    /** Execute a parameterized mutation; return the number of rows changed (sqlite3_changes()). */
+    run(sql: string, ...bindings: B[]): number;
+    /** Run a single-row query; return the first row as an object, or undefined. */
+    get(sql: string, ...bindings: B[]): Record<string, B> | undefined;
+}
+/** Coerce ONE wire JSON value to the runtime's bindable scalar `B` (booleans → 0/1, etc.). Runtime-
+ *  specific (binary/bigint differ per engine), so it is injected rather than baked in. */
+export type ToBindable<B> = (value: unknown) => B;
+/** One change-feed record (a /snapshot line or a /changes row). accountId/seq are the caller's concern.
+ *  `entity` is widened to string here (the runtime callers pass their stricter EntityName). */
+export interface ReplicaChange {
+    entity: string;
+    op: "upsert" | "delete";
+    /** Full normalized row for "upsert"; for "delete" may be `{}` or carry just the PK columns. */
+    row: Record<string, unknown>;
+    /** The change_log.entity_id — the PK (composite PKs joined with ':'). Required to apply a delete. */
+    entityId?: string;
+}
+/**
+ * Apply ONE change-feed record to the replica. Returns true iff a row was actually written (a stale
+ * upsert rejected by the updated_at guard, or a delete of an already-absent row, returns false). Never
+ * throws on a well-formed record; throws only on an unknown entity (malformed wire data).
+ */
+export declare function applyDelta<B>(db: ReplicaWriteDb<B>, change: ReplicaChange, toBindable: ToBindable<B>): boolean;
+/**
+ * Wipe every replica entity table (but NOT the host-only `sync_meta` cursor table). Called before
+ * replaying a fresh /snapshot so a resync can't leave orphaned rows the new snapshot no longer contains.
+ */
+export declare function truncateReplica<B>(db: ReplicaWriteDb<B>): void;
+/** Read the persisted change-feed cursor (or null if a snapshot has never completed). */
+export declare function getCursor<B>(db: ReplicaWriteDb<B>): number | null;
+/** Persist the change-feed cursor (the last applied change_log.seq). */
+export declare function setCursor<B>(db: ReplicaWriteDb<B>, cursor: number, toBindable: ToBindable<B>): void;

package/dist/replicate.js

@@ -0,0 +1,112 @@
+// @catalyst-cloud/replicate — the runtime-agnostic replica WRITE path (ADR-0002). The write
+// counterpart to @catalyst-cloud/read-model: one `applyDelta` (+ cursor + truncate) that lands a
+// change-feed record into a local SQLite replica, schema-driven from the one Drizzle SSOT
+// (@catalyst-cloud/schema MIRROR_TABLE_META). The host-sync bun:sqlite replica and the browser OPFS
+// wasm replica BOTH route through this — collapsing the two hand-maintained `apply.ts` twins into one,
+// so they can never drift. Dependency-free / runtime-agnostic by design (NO bun:sqlite / node imports);
+// the runtime engine adapts to the portable `ReplicaWriteDb` handle, exactly as the read-model's
+// `SqlExecutor` is adapted per runtime.
+//
+// WIRE CONTRACT (shared — see apps/mirror/src/do/changefeed.ts):
+//   • op:"upsert"  → row is the FULL normalized DO row; INSERT … ON CONFLICT(pk) DO UPDATE, last-write-
+//                    wins by updated_at where present (DO NOTHING for a pure-join row like issue_labels).
+//   • op:"delete"  → soft-delete (set removed_at) on tables with a removed_at column, else hard-delete;
+//                    the PK is recovered from the row's PK columns or by splitting entityId on ':'.
+import { MIRROR_TABLE_META } from "@catalyst-cloud/schema";
+function quoteIdent(ident) {
+    return `"${ident.replace(/"/g, '""')}"`;
+}
+function metaFor(entity) {
+    return MIRROR_TABLE_META[entity];
+}
+/**
+ * Apply ONE change-feed record to the replica. Returns true iff a row was actually written (a stale
+ * upsert rejected by the updated_at guard, or a delete of an already-absent row, returns false). Never
+ * throws on a well-formed record; throws only on an unknown entity (malformed wire data).
+ */
+export function applyDelta(db, change, toBindable) {
+    const meta = metaFor(change.entity);
+    if (!meta)
+        throw new Error(`applyDelta: unknown entity ${String(change.entity)}`);
+    if (change.op === "delete")
+        return applyDelete(db, change, meta, toBindable);
+    return applyUpsert(db, change, meta, toBindable);
+}
+function applyUpsert(db, change, meta, toBindable) {
+    const table = change.entity;
+    const cols = Object.keys(change.row);
+    if (cols.length === 0)
+        return false; // malformed wire upsert — skip rather than emit invalid SQL.
+    const pkSet = new Set(meta.pk);
+    const nonPkCols = cols.filter((c) => !pkSet.has(c));
+    const hasUpdatedAt = cols.includes("updated_at");
+    const colList = cols.map(quoteIdent).join(", ");
+    const placeholders = cols.map(() => "?").join(", ");
+    const conflictTarget = meta.pk.map(quoteIdent).join(", ");
+    let conflictClause;
+    if (nonPkCols.length === 0) {
+        // Pure join/edge row (issue_labels): PK is the whole row — no-op on conflict.
+        conflictClause = `ON CONFLICT(${conflictTarget}) DO NOTHING`;
+    }
+    else {
+        const setClause = nonPkCols
+            .map((c) => `${quoteIdent(c)} = excluded.${quoteIdent(c)}`)
+            .join(", ");
+        // Last-write-wins by updated_at — mirrors the DO's guard so out-of-order deltas can't regress.
+        const guard = hasUpdatedAt
+            ? ` WHERE excluded.updated_at > ${quoteIdent(table)}.updated_at`
+            : "";
+        conflictClause = `ON CONFLICT(${conflictTarget}) DO UPDATE SET ${setClause}${guard}`;
+    }
+    const sql = `INSERT INTO ${quoteIdent(table)} (${colList}) VALUES (${placeholders}) ${conflictClause}`;
+    return db.run(sql, ...cols.map((c) => toBindable(change.row[c]))) > 0;
+}
+function applyDelete(db, change, meta, toBindable) {
+    const table = change.entity;
+    const pkVals = pkValuesFor(change, meta, toBindable);
+    if (!pkVals)
+        return false; // can't locate the row → nothing to do.
+    const where = meta.pk.map((c) => `${quoteIdent(c)} = ?`).join(" AND ");
+    if (meta.softDelete) {
+        // Soft-delete: set removed_at, but only if currently live (idempotent re-delete is a no-op).
+        return (db.run(`UPDATE ${quoteIdent(table)} SET removed_at = ? WHERE ${where} AND removed_at IS NULL`, toBindable(Date.now()), ...pkVals) > 0);
+    }
+    // Hard-delete (join/edge/GitHub tables have no removed_at).
+    return db.run(`DELETE FROM ${quoteIdent(table)} WHERE ${where}`, ...pkVals) > 0;
+}
+/** Resolve the PK column values for a delete from the row's PK fields first, then entityId, else null.
+ *  Every value is routed through `toBindable` so the result is uniformly `B[]`. */
+function pkValuesFor(change, meta, toBindable) {
+    const fromRow = meta.pk.map((c) => change.row[c]);
+    if (fromRow.every((v) => v !== undefined && v !== null)) {
+        return fromRow.map(toBindable);
+    }
+    if (change.entityId != null) {
+        const parts = change.entityId.split(":");
+        if (parts.length === meta.pk.length)
+            return parts.map((p) => toBindable(p));
+    }
+    return null;
+}
+/**
+ * Wipe every replica entity table (but NOT the host-only `sync_meta` cursor table). Called before
+ * replaying a fresh /snapshot so a resync can't leave orphaned rows the new snapshot no longer contains.
+ */
+export function truncateReplica(db) {
+    for (const entity of Object.keys(MIRROR_TABLE_META)) {
+        db.run(`DELETE FROM ${quoteIdent(entity)}`);
+    }
+}
+/** Read the persisted change-feed cursor (or null if a snapshot has never completed). */
+export function getCursor(db) {
+    const row = db.get("SELECT value FROM sync_meta WHERE key = 'cursor'");
+    if (!row)
+        return null;
+    const n = Number(row["value"]);
+    return Number.isFinite(n) ? n : null;
+}
+/** Persist the change-feed cursor (the last applied change_log.seq). */
+export function setCursor(db, cursor, toBindable) {
+    db.run("INSERT INTO sync_meta (key, value) VALUES (?, ?) " +
+        "ON CONFLICT(key) DO UPDATE SET value = excluded.value", toBindable("cursor"), toBindable(String(cursor)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/replicate",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Runtime-agnostic replica write path — applyDelta / truncateReplica / cursor over a portable ReplicaWriteDb (ADR-0002). Shared by the host-sync bun:sqlite replica and the browser OPFS replica so the two apply paths can't drift.",
   "license": "MIT",
@@ -10,18 +10,23 @@
     "directory": "packages/replicate"
   },
   "files": [
-    "src"
+    "dist"
   ],
   "publishConfig": {
     "access": "public"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
     "@catalyst-cloud/schema": "^0.1.0"

package/src/replicate.ts

@@ -1,184 +0,0 @@
-// @catalyst-cloud/replicate — the runtime-agnostic replica WRITE path (ADR-0002). The write
-// counterpart to @catalyst-cloud/read-model: one `applyDelta` (+ cursor + truncate) that lands a
-// change-feed record into a local SQLite replica, schema-driven from the one Drizzle SSOT
-// (@catalyst-cloud/schema MIRROR_TABLE_META). The host-sync bun:sqlite replica and the browser OPFS
-// wasm replica BOTH route through this — collapsing the two hand-maintained `apply.ts` twins into one,
-// so they can never drift. Dependency-free / runtime-agnostic by design (NO bun:sqlite / node imports);
-// the runtime engine adapts to the portable `ReplicaWriteDb` handle, exactly as the read-model's
-// `SqlExecutor` is adapted per runtime.
-//
-// WIRE CONTRACT (shared — see apps/mirror/src/do/changefeed.ts):
-//   • op:"upsert"  → row is the FULL normalized DO row; INSERT … ON CONFLICT(pk) DO UPDATE, last-write-
-//                    wins by updated_at where present (DO NOTHING for a pure-join row like issue_labels).
-//   • op:"delete"  → soft-delete (set removed_at) on tables with a removed_at column, else hard-delete;
-//                    the PK is recovered from the row's PK columns or by splitting entityId on ':'.
-
-import { MIRROR_TABLE_META, type TableMeta } from "@catalyst-cloud/schema";
-
-/**
- * The portable replica WRITE seam — the write counterpart to read-model's `SqlExecutor`. bun:sqlite
- * (host-sync) and sqlite-wasm (browser OPFS) each satisfy it via a thin adapter. Generic over the
- * bindable type `B` because the two engines coerce binary/bigint differently (bun binds Uint8Array /
- * bigint; wasm binds ArrayBuffer / number) — the runtime supplies its own `toBindable` so every bound
- * value is already a `B`.
- */
-export interface ReplicaWriteDb<B> {
-  /** Execute a parameterized mutation; return the number of rows changed (sqlite3_changes()). */
-  run(sql: string, ...bindings: B[]): number;
-  /** Run a single-row query; return the first row as an object, or undefined. */
-  get(sql: string, ...bindings: B[]): Record<string, B> | undefined;
-}
-
-/** Coerce ONE wire JSON value to the runtime's bindable scalar `B` (booleans → 0/1, etc.). Runtime-
- *  specific (binary/bigint differ per engine), so it is injected rather than baked in. */
-export type ToBindable<B> = (value: unknown) => B;
-
-/** One change-feed record (a /snapshot line or a /changes row). accountId/seq are the caller's concern.
- *  `entity` is widened to string here (the runtime callers pass their stricter EntityName). */
-export interface ReplicaChange {
-  entity: string;
-  op: "upsert" | "delete";
-  /** Full normalized row for "upsert"; for "delete" may be `{}` or carry just the PK columns. */
-  row: Record<string, unknown>;
-  /** The change_log.entity_id — the PK (composite PKs joined with ':'). Required to apply a delete. */
-  entityId?: string;
-}
-
-function quoteIdent(ident: string): string {
-  return `"${ident.replace(/"/g, '""')}"`;
-}
-
-function metaFor(entity: string): TableMeta | undefined {
-  return (MIRROR_TABLE_META as Record<string, TableMeta>)[entity];
-}
-
-/**
- * Apply ONE change-feed record to the replica. Returns true iff a row was actually written (a stale
- * upsert rejected by the updated_at guard, or a delete of an already-absent row, returns false). Never
- * throws on a well-formed record; throws only on an unknown entity (malformed wire data).
- */
-export function applyDelta<B>(
-  db: ReplicaWriteDb<B>,
-  change: ReplicaChange,
-  toBindable: ToBindable<B>,
-): boolean {
-  const meta = metaFor(change.entity);
-  if (!meta) throw new Error(`applyDelta: unknown entity ${String(change.entity)}`);
-  if (change.op === "delete") return applyDelete(db, change, meta, toBindable);
-  return applyUpsert(db, change, meta, toBindable);
-}
-
-function applyUpsert<B>(
-  db: ReplicaWriteDb<B>,
-  change: ReplicaChange,
-  meta: TableMeta,
-  toBindable: ToBindable<B>,
-): boolean {
-  const table = change.entity;
-  const cols = Object.keys(change.row);
-  if (cols.length === 0) return false; // malformed wire upsert — skip rather than emit invalid SQL.
-
-  const pkSet = new Set<string>(meta.pk);
-  const nonPkCols = cols.filter((c) => !pkSet.has(c));
-  const hasUpdatedAt = cols.includes("updated_at");
-
-  const colList = cols.map(quoteIdent).join(", ");
-  const placeholders = cols.map(() => "?").join(", ");
-  const conflictTarget = meta.pk.map(quoteIdent).join(", ");
-
-  let conflictClause: string;
-  if (nonPkCols.length === 0) {
-    // Pure join/edge row (issue_labels): PK is the whole row — no-op on conflict.
-    conflictClause = `ON CONFLICT(${conflictTarget}) DO NOTHING`;
-  } else {
-    const setClause = nonPkCols
-      .map((c) => `${quoteIdent(c)} = excluded.${quoteIdent(c)}`)
-      .join(", ");
-    // Last-write-wins by updated_at — mirrors the DO's guard so out-of-order deltas can't regress.
-    const guard = hasUpdatedAt
-      ? ` WHERE excluded.updated_at > ${quoteIdent(table)}.updated_at`
-      : "";
-    conflictClause = `ON CONFLICT(${conflictTarget}) DO UPDATE SET ${setClause}${guard}`;
-  }
-
-  const sql = `INSERT INTO ${quoteIdent(table)} (${colList}) VALUES (${placeholders}) ${conflictClause}`;
-  return db.run(sql, ...cols.map((c) => toBindable(change.row[c]))) > 0;
-}
-
-function applyDelete<B>(
-  db: ReplicaWriteDb<B>,
-  change: ReplicaChange,
-  meta: TableMeta,
-  toBindable: ToBindable<B>,
-): boolean {
-  const table = change.entity;
-
-  const pkVals = pkValuesFor(change, meta, toBindable);
-  if (!pkVals) return false; // can't locate the row → nothing to do.
-
-  const where = meta.pk.map((c) => `${quoteIdent(c)} = ?`).join(" AND ");
-
-  if (meta.softDelete) {
-    // Soft-delete: set removed_at, but only if currently live (idempotent re-delete is a no-op).
-    return (
-      db.run(
-        `UPDATE ${quoteIdent(table)} SET removed_at = ? WHERE ${where} AND removed_at IS NULL`,
-        toBindable(Date.now()),
-        ...pkVals,
-      ) > 0
-    );
-  }
-
-  // Hard-delete (join/edge/GitHub tables have no removed_at).
-  return db.run(`DELETE FROM ${quoteIdent(table)} WHERE ${where}`, ...pkVals) > 0;
-}
-
-/** Resolve the PK column values for a delete from the row's PK fields first, then entityId, else null.
- *  Every value is routed through `toBindable` so the result is uniformly `B[]`. */
-function pkValuesFor<B>(
-  change: ReplicaChange,
-  meta: TableMeta,
-  toBindable: ToBindable<B>,
-): B[] | null {
-  const fromRow = meta.pk.map((c) => change.row[c]);
-  if (fromRow.every((v) => v !== undefined && v !== null)) {
-    return fromRow.map(toBindable);
-  }
-  if (change.entityId != null) {
-    const parts = change.entityId.split(":");
-    if (parts.length === meta.pk.length) return parts.map((p) => toBindable(p));
-  }
-  return null;
-}
-
-/**
- * Wipe every replica entity table (but NOT the host-only `sync_meta` cursor table). Called before
- * replaying a fresh /snapshot so a resync can't leave orphaned rows the new snapshot no longer contains.
- */
-export function truncateReplica<B>(db: ReplicaWriteDb<B>): void {
-  for (const entity of Object.keys(MIRROR_TABLE_META)) {
-    db.run(`DELETE FROM ${quoteIdent(entity)}`);
-  }
-}
-
-/** Read the persisted change-feed cursor (or null if a snapshot has never completed). */
-export function getCursor<B>(db: ReplicaWriteDb<B>): number | null {
-  const row = db.get("SELECT value FROM sync_meta WHERE key = 'cursor'");
-  if (!row) return null;
-  const n = Number(row["value"]);
-  return Number.isFinite(n) ? n : null;
-}
-
-/** Persist the change-feed cursor (the last applied change_log.seq). */
-export function setCursor<B>(
-  db: ReplicaWriteDb<B>,
-  cursor: number,
-  toBindable: ToBindable<B>,
-): void {
-  db.run(
-    "INSERT INTO sync_meta (key, value) VALUES (?, ?) " +
-      "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
-    toBindable("cursor"),
-    toBindable(String(cursor)),
-  );
-}