@tangentfeed/adapter-sqlite 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sreeraj T A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @tangentfeed/adapter-sqlite
+
+SQLite storage adapter for [tangentfeed](https://github.com/sreerajta/tangentfeed). Runs
+on Node, Electron, Bun, and React Native — your synced data becomes a real
+SQLite database you can open with any client.
+
+```ts
+import Database from "better-sqlite3";
+import { SqliteAdapter, betterSqliteDriver } from "@tangentfeed/adapter-sqlite";
+import { SyncEngine } from "@tangentfeed/core";
+
+const storage = SqliteAdapter.open(betterSqliteDriver(new Database("tasks.db")));
+const engine = await SyncEngine.open({ deviceId, storage });
+```
+
+## Drivers
+
+The adapter targets a four-method interface, so the SQLite binding is your
+choice:
+
+```ts
+betterSqliteDriver(new Database("tasks.db"))          // better-sqlite3
+nodeSqliteDriver(new DatabaseSync("tasks.db"))        // node:sqlite (Node 22+)
+```
+
+Bun's `bun:sqlite` and `expo-sqlite` fit the same shape; wrap them with a small
+object exposing `exec`, `prepare`, and optionally `close`.
+
+## Schema
+
+| Table | Contents |
+|---|---|
+| `ops` | The operation log. `id` is the HLC string, so PRIMARY KEY order is causal order. Indexed on `(device, hlc)` for frontier diffs |
+| `cells` | Materialized state: winning op per `(table_name, row_id, column_name)` |
+| `meta` | Frontier, persisted clock, recorded peer frontiers |
+
+Both data tables are `WITHOUT ROWID`, since their primary keys are the natural
+access paths.
+
+```bash
+sqlite3 tasks.db "SELECT table_name, column_name, value FROM ops ORDER BY id;"
+```
+
+Writes run inside `BEGIN IMMEDIATE` transactions, satisfying the all-or-nothing
+requirement in PROTOCOL.md §8.2.
+
+Part of [tangentfeed](https://github.com/sreerajta/tangentfeed). MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import { StorageAdapter, Op, Frontier, ClockState, DeviceKey, CompactionWrite, BatchWrite } from '@tangentfeed/core';
+export { aboveFrontier } from '@tangentfeed/core';
+
+/**
+ * SQLite storage adapter — PROTOCOL.md §8 on real tables.
+ *
+ * Schema (three tables, mirroring the IndexedDB layout):
+ *
+ *   ops   (id PK, table_name, row_id, column_name, value, hlc, device)
+ *         The operation log. `id` is the 34-char HLC string, so PRIMARY KEY
+ *         order IS causal order — the same trick the IndexedDB adapter uses,
+ *         and the reason opsSince() can stream in order with no sort.
+ *         Index on (device, hlc) makes frontier-diff queries index-only,
+ *         which is the hot path during sync.
+ *
+ *   cells (table_name, row_id, column_name PK, op_json)
+ *         Materialized state: the currently winning op per cell. Composite
+ *         primary key gives us per-table and per-row scans for free, without
+ *         the string-concatenation keys IndexedDB forced on us.
+ *
+ *   meta  (key PK, value)
+ *         Frontier, persisted clock state, recorded peer frontiers.
+ *
+ * Atomicity (§8.2): applyBatch and compact run inside a single IMMEDIATE
+ * transaction, so a crash mid-apply can never leave the log and materialized
+ * state disagreeing.
+ *
+ * Driver-agnostic: works with better-sqlite3, node:sqlite, bun:sqlite, or
+ * expo-sqlite by supplying a ~4-method adapter (see SqliteDriver). Ready-made
+ * wrappers for the first two are exported below.
+ */
+
+interface SqliteStatement {
+    all(...params: unknown[]): unknown[];
+    get(...params: unknown[]): unknown;
+    run(...params: unknown[]): void;
+}
+interface SqliteDriver {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement;
+    close?(): void;
+}
+/** Wrap a better-sqlite3 Database. */
+declare function betterSqliteDriver(db: {
+    exec(sql: string): unknown;
+    prepare(sql: string): {
+        all(...p: unknown[]): unknown[];
+        get(...p: unknown[]): unknown;
+        run(...p: unknown[]): unknown;
+    };
+    close(): unknown;
+}): SqliteDriver;
+/** Wrap a node:sqlite DatabaseSync (Node 22+). */
+declare function nodeSqliteDriver(db: {
+    exec(sql: string): unknown;
+    prepare(sql: string): {
+        all(...p: unknown[]): unknown[];
+        get(...p: unknown[]): unknown;
+        run(...p: unknown[]): unknown;
+    };
+    close(): unknown;
+}): SqliteDriver;
+declare class SqliteAdapter implements StorageAdapter {
+    private readonly db;
+    private readonly stmts;
+    private constructor();
+    static open(driver: SqliteDriver): SqliteAdapter;
+    close(): void;
+    getRow(table: string, row: string): Promise<ReadonlyMap<string, Op> | undefined>;
+    listRows(table: string): Promise<string[]>;
+    listTables(): Promise<string[]>;
+    hasOp(id: string): Promise<boolean>;
+    getWinner(table: string, row: string, column: string): Promise<Op | undefined>;
+    opsSince(frontier: Frontier): Promise<Op[]>;
+    getFrontier(): Promise<Frontier>;
+    getClock(): Promise<ClockState | undefined>;
+    getDeviceKey(): Promise<DeviceKey | undefined>;
+    setDeviceKey(key: DeviceKey): Promise<void>;
+    opCount(): Promise<number>;
+    allOps(): Promise<Op[]>;
+    getPeerFrontiers(): Promise<Record<string, Frontier>>;
+    setPeerFrontier(peer: string, frontier: Frontier): Promise<void>;
+    compact(write: CompactionWrite): Promise<void>;
+    applyBatch(batch: BatchWrite): Promise<void>;
+    /** All-or-nothing (§8.2). IMMEDIATE takes the write lock up front. */
+    private transaction;
+    private readMeta;
+    private writeMeta;
+}
+
+export { SqliteAdapter, type SqliteDriver, type SqliteStatement, betterSqliteDriver, nodeSqliteDriver };

package/dist/index.js

@@ -0,0 +1,249 @@
+// src/index.ts
+import {
+  aboveFrontier
+} from "@tangentfeed/core";
+function betterSqliteDriver(db) {
+  return {
+    exec: (sql) => void db.exec(sql),
+    prepare: (sql) => {
+      const stmt = db.prepare(sql);
+      return {
+        all: (...p) => stmt.all(...p),
+        get: (...p) => stmt.get(...p),
+        run: (...p) => void stmt.run(...p)
+      };
+    },
+    close: () => void db.close()
+  };
+}
+function nodeSqliteDriver(db) {
+  return betterSqliteDriver(db);
+}
+var SCHEMA = `
+PRAGMA journal_mode = WAL;
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS ops (
+  id          TEXT PRIMARY KEY,
+  table_name  TEXT NOT NULL,
+  row_id      TEXT NOT NULL,
+  column_name TEXT NOT NULL,
+  value       TEXT NOT NULL,   -- JSON-encoded, so NULL stays distinguishable
+  hlc         TEXT NOT NULL,
+  device      TEXT NOT NULL,
+  sig         TEXT NOT NULL    -- base64 Ed25519, section 12
+) WITHOUT ROWID;
+
+-- the sync hot path: "everything from device D above hlc H"
+CREATE INDEX IF NOT EXISTS ops_device_hlc ON ops (device, hlc);
+
+CREATE TABLE IF NOT EXISTS cells (
+  table_name  TEXT NOT NULL,
+  row_id      TEXT NOT NULL,
+  column_name TEXT NOT NULL,
+  op_json     TEXT NOT NULL,
+  PRIMARY KEY (table_name, row_id, column_name)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+) WITHOUT ROWID;
+`;
+var SqliteAdapter = class _SqliteAdapter {
+  db;
+  stmts;
+  constructor(db) {
+    this.db = db;
+    db.exec(SCHEMA);
+    this.stmts = {
+      insertOp: db.prepare(
+        `INSERT OR IGNORE INTO ops (id, table_name, row_id, column_name, value, hlc, device, sig)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+      ),
+      deleteOp: db.prepare(`DELETE FROM ops WHERE id = ?`),
+      upsertCell: db.prepare(
+        `INSERT INTO cells (table_name, row_id, column_name, op_json) VALUES (?, ?, ?, ?)
+         ON CONFLICT(table_name, row_id, column_name) DO UPDATE SET op_json = excluded.op_json`
+      ),
+      deleteCell: db.prepare(
+        `DELETE FROM cells WHERE table_name = ? AND row_id = ? AND column_name = ?`
+      ),
+      getCell: db.prepare(
+        `SELECT op_json FROM cells WHERE table_name = ? AND row_id = ? AND column_name = ?`
+      ),
+      rowCells: db.prepare(
+        `SELECT column_name, op_json FROM cells WHERE table_name = ? AND row_id = ?`
+      ),
+      tableRows: db.prepare(`SELECT DISTINCT row_id FROM cells WHERE table_name = ?`),
+      tables: db.prepare(`SELECT DISTINCT table_name FROM cells`),
+      countOp: db.prepare(`SELECT 1 AS found FROM ops WHERE id = ?`),
+      countOps: db.prepare(`SELECT COUNT(*) AS n FROM ops`),
+      allOps: db.prepare(`SELECT * FROM ops ORDER BY id`),
+      opsAboveFor: db.prepare(
+        `SELECT * FROM ops WHERE device = ? AND hlc > ? ORDER BY hlc`
+      ),
+      allOpsUnfiltered: db.prepare(`SELECT * FROM ops ORDER BY id`),
+      getMeta: db.prepare(`SELECT value FROM meta WHERE key = ?`),
+      setMeta: db.prepare(
+        `INSERT INTO meta (key, value) VALUES (?, ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+      )
+    };
+  }
+  static open(driver) {
+    return new _SqliteAdapter(driver);
+  }
+  close() {
+    this.db.close?.();
+  }
+  // ---------- reads ----------
+  async getRow(table, row) {
+    const rows = this.stmts.rowCells.all(table, row);
+    if (rows.length === 0) return void 0;
+    const out = /* @__PURE__ */ new Map();
+    for (const r of rows) out.set(r.column_name, JSON.parse(r.op_json));
+    return out;
+  }
+  async listRows(table) {
+    return this.stmts.tableRows.all(table).map((r) => r.row_id);
+  }
+  async listTables() {
+    return this.stmts.tables.all().map((r) => r.table_name);
+  }
+  async hasOp(id) {
+    return this.stmts.countOp.get(id) !== void 0;
+  }
+  async getWinner(table, row, column) {
+    const rec = this.stmts.getCell.get(table, row, column);
+    return rec ? JSON.parse(rec.op_json) : void 0;
+  }
+  async opsSince(frontier) {
+    const devices = Object.keys(frontier);
+    if (devices.length === 0) {
+      return this.stmts.allOpsUnfiltered.all().map(toOp);
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const device of devices) {
+      for (const r of this.stmts.opsAboveFor.all(device, frontier[device])) {
+        seen.add(r.id);
+        out.push(toOp(r));
+      }
+    }
+    for (const r of this.stmts.allOpsUnfiltered.all()) {
+      if (frontier[r.device] === void 0 && !seen.has(r.id)) out.push(toOp(r));
+    }
+    out.sort((a, b) => a.hlc < b.hlc ? -1 : a.hlc > b.hlc ? 1 : 0);
+    return out;
+  }
+  async getFrontier() {
+    return this.readMeta("frontier") ?? {};
+  }
+  async getClock() {
+    return this.readMeta("clock");
+  }
+  // ---------- signing identity (§12) ----------
+  // Meta values are JSON, which has no byte-array type, so the keypair is
+  // stored hex-encoded rather than as an array of numbers — half the size and
+  // unambiguous to read back.
+  async getDeviceKey() {
+    const stored = this.readMeta("deviceKey");
+    if (!stored) return void 0;
+    return { publicKey: unhex(stored.publicKey), privateKey: unhex(stored.privateKey) };
+  }
+  async setDeviceKey(key) {
+    this.writeMeta("deviceKey", {
+      publicKey: hex(key.publicKey),
+      privateKey: hex(key.privateKey)
+    });
+  }
+  // ---------- compaction support ----------
+  async opCount() {
+    return this.stmts.countOps.get().n;
+  }
+  async allOps() {
+    return this.stmts.allOps.all().map(toOp);
+  }
+  async getPeerFrontiers() {
+    return this.readMeta("peers") ?? {};
+  }
+  async setPeerFrontier(peer, frontier) {
+    const current = await this.getPeerFrontiers();
+    this.writeMeta("peers", { ...current, [peer]: frontier });
+  }
+  async compact(write) {
+    this.transaction(() => {
+      for (const id of write.opIds) this.stmts.deleteOp.run(id);
+      for (const key of write.cellKeys) {
+        const [table, row, column] = key.split("\0");
+        this.stmts.deleteCell.run(table, row, column);
+      }
+    });
+  }
+  // ---------- the one write path ----------
+  async applyBatch(batch) {
+    this.transaction(() => {
+      for (const op of batch.ops) {
+        this.stmts.insertOp.run(
+          op.id,
+          op.table,
+          op.row,
+          op.column,
+          JSON.stringify(op.value),
+          op.hlc,
+          op.device,
+          op.sig
+        );
+      }
+      for (const [key, op] of batch.winners) {
+        const [table, row, column] = key.split("\0");
+        this.stmts.upsertCell.run(table, row, column, JSON.stringify(op));
+      }
+      this.stmts.setMeta.run("frontier", JSON.stringify(batch.frontier));
+      this.stmts.setMeta.run("clock", JSON.stringify(batch.clock));
+    });
+  }
+  // ---------- helpers ----------
+  /** All-or-nothing (§8.2). IMMEDIATE takes the write lock up front. */
+  transaction(fn) {
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      fn();
+      this.db.exec("COMMIT");
+    } catch (err) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    }
+  }
+  readMeta(key) {
+    const rec = this.stmts.getMeta.get(key);
+    return rec ? JSON.parse(rec.value) : void 0;
+  }
+  writeMeta(key, value) {
+    this.stmts.setMeta.run(key, JSON.stringify(value));
+  }
+};
+function toOp(r) {
+  return {
+    id: r.id,
+    table: r.table_name,
+    row: r.row_id,
+    column: r.column_name,
+    value: JSON.parse(r.value),
+    hlc: r.hlc,
+    device: r.device,
+    sig: r.sig
+  };
+}
+var hex = (b) => [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+var unhex = (s) => new Uint8Array((s.match(/../g) ?? []).map((h) => parseInt(h, 16)));
+export {
+  SqliteAdapter,
+  aboveFrontier,
+  betterSqliteDriver,
+  nodeSqliteDriver
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@tangentfeed/adapter-sqlite",
+  "version": "0.2.0",
+  "description": "SQLite storage adapter for tangentfeed (better-sqlite3, node:sqlite, bun:sqlite)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "prepack": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tangentfeed/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^20.0.0",
+    "better-sqlite3": "^11.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}