@tangentfeed/adapter-idb 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,10 @@
+# @tangentfeed/adapter-idb
+
+IndexedDB storage adapter for tangentfeed.
+
+```ts
+import { IdbAdapter } from "@tangentfeed/adapter-idb";
+const storage = await IdbAdapter.open("my-space");
+```
+
+Part of [tangentfeed](https://github.com/sreerajta/tangentfeed). MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { StorageAdapter, Op, Frontier, ClockState, DeviceKey, CompactionWrite, BatchWrite } from '@tangentfeed/core';
+
+/**
+ * IndexedDB adapter — PROTOCOL.md §8 capabilities on browser storage.
+ *
+ * Layout (one database per space, name `tangentfeed:{space}`):
+ *   ops   — keyPath "id". Since op.id === op.hlc (34-char sortable string),
+ *           primary-key order IS global HLC order for free.
+ *   cells — key: cellKey(table,row,column) = "table\0row\0column".
+ *           value: { key, op } where op is the current winning op.
+ *           \u0000 sorts below every legal name char, so prefix ranges give
+ *           us per-table and per-row scans without extra indexes.
+ *   meta  — "frontier" and "clock" singletons.
+ *
+ * Atomicity (§8.2): applyBatch issues every put inside ONE readwrite
+ * transaction over all three stores; IndexedDB transactions commit
+ * all-or-nothing. No foreign awaits happen mid-transaction (that would let
+ * the tx auto-commit early); all requests are queued synchronously.
+ *
+ * Known M2 simplifications (revisit in M8/compaction):
+ *   - opsSince scans the whole ops store with a cursor and filters. Fine for
+ *     demo scale; a ["device","hlc"] index makes it O(missing) later.
+ *   - listTables/listRows scan the cells store by cursor.
+ */
+
+declare class IdbAdapter implements StorageAdapter {
+    private readonly db;
+    private constructor();
+    /**
+     * Open (creating on first use) the database for a space.
+     * `factory` defaults to globalThis.indexedDB; inject fake-indexeddb in
+     * tests or a custom factory in exotic environments.
+     */
+    static open(space: string, factory?: IDBFactory): Promise<IdbAdapter>;
+    /** Delete a space's database entirely. */
+    static destroy(space: string, factory?: IDBFactory): Promise<void>;
+    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>;
+    private rangeScan;
+}
+
+export { IdbAdapter };

package/dist/index.js

@@ -0,0 +1,187 @@
+// src/index.ts
+import {
+  aboveFrontier,
+  cellKey
+} from "@tangentfeed/core";
+var SEP = "\0";
+var HIGH = "\uFFFF";
+var IdbAdapter = class _IdbAdapter {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  /**
+   * Open (creating on first use) the database for a space.
+   * `factory` defaults to globalThis.indexedDB; inject fake-indexeddb in
+   * tests or a custom factory in exotic environments.
+   */
+  static async open(space, factory = globalThis.indexedDB) {
+    if (!factory) throw new Error("no IndexedDB available in this environment");
+    const db = await promisifyOpen(factory.open(`tangentfeed:${space}`, 1));
+    return new _IdbAdapter(db);
+  }
+  /** Delete a space's database entirely. */
+  static async destroy(space, factory = globalThis.indexedDB) {
+    await promisifyRequest(factory.deleteDatabase(`tangentfeed:${space}`));
+  }
+  close() {
+    this.db.close();
+  }
+  // ---------- reads ----------
+  async getRow(table, row) {
+    const prefix = table + SEP + row + SEP;
+    const entries = await this.rangeScan("cells", prefix);
+    if (entries.length === 0) return void 0;
+    const out = /* @__PURE__ */ new Map();
+    for (const { key, op } of entries) {
+      out.set(key.slice(prefix.length), op);
+    }
+    return out;
+  }
+  async listRows(table) {
+    const prefix = table + SEP;
+    const rows = /* @__PURE__ */ new Set();
+    for (const { key } of await this.rangeScan("cells", prefix)) {
+      const rest = key.slice(prefix.length);
+      rows.add(rest.slice(0, rest.indexOf(SEP)));
+    }
+    return [...rows];
+  }
+  async listTables() {
+    const tables = /* @__PURE__ */ new Set();
+    for (const { key } of await this.rangeScan("cells", "")) {
+      tables.add(key.slice(0, key.indexOf(SEP)));
+    }
+    return [...tables];
+  }
+  async hasOp(id) {
+    const tx = this.db.transaction("ops", "readonly");
+    const n = await promisifyRequest(tx.objectStore("ops").count(id));
+    return n > 0;
+  }
+  async getWinner(table, row, column) {
+    const tx = this.db.transaction("cells", "readonly");
+    const rec = await promisifyRequest(
+      tx.objectStore("cells").get(cellKey(table, row, column))
+    );
+    return rec?.op;
+  }
+  async opsSince(frontier) {
+    const tx = this.db.transaction("ops", "readonly");
+    const out = [];
+    await cursorEach(tx.objectStore("ops").openCursor(), (op) => {
+      if (aboveFrontier(op, frontier)) out.push(op);
+    });
+    return out;
+  }
+  async getFrontier() {
+    const tx = this.db.transaction("meta", "readonly");
+    return await promisifyRequest(tx.objectStore("meta").get("frontier")) ?? {};
+  }
+  async getClock() {
+    const tx = this.db.transaction("meta", "readonly");
+    return promisifyRequest(tx.objectStore("meta").get("clock"));
+  }
+  // ---------- signing identity (§12) ----------
+  // Stored as raw Uint8Arrays: structured clone handles typed arrays, so there
+  // is nothing to encode and nothing to get wrong on the way back out.
+  async getDeviceKey() {
+    const tx = this.db.transaction("meta", "readonly");
+    return promisifyRequest(tx.objectStore("meta").get("deviceKey"));
+  }
+  async setDeviceKey(key) {
+    const tx = this.db.transaction("meta", "readwrite");
+    tx.objectStore("meta").put({ publicKey: key.publicKey, privateKey: key.privateKey }, "deviceKey");
+    await txDone(tx);
+  }
+  // ---------- compaction support (§9) ----------
+  async opCount() {
+    const tx = this.db.transaction("ops", "readonly");
+    return promisifyRequest(tx.objectStore("ops").count());
+  }
+  async allOps() {
+    const tx = this.db.transaction("ops", "readonly");
+    const out = [];
+    await cursorEach(tx.objectStore("ops").openCursor(), (op) => out.push(op));
+    return out;
+  }
+  async getPeerFrontiers() {
+    const tx = this.db.transaction("meta", "readonly");
+    return await promisifyRequest(
+      tx.objectStore("meta").get("peers")
+    ) ?? {};
+  }
+  async setPeerFrontier(peer, frontier) {
+    const current = await this.getPeerFrontiers();
+    const tx = this.db.transaction("meta", "readwrite");
+    tx.objectStore("meta").put({ ...current, [peer]: frontier }, "peers");
+    await txDone(tx);
+  }
+  async compact(write) {
+    const tx = this.db.transaction(["ops", "cells"], "readwrite");
+    const ops = tx.objectStore("ops");
+    const cells = tx.objectStore("cells");
+    for (const id of write.opIds) ops.delete(id);
+    for (const key of write.cellKeys) cells.delete(key);
+    await txDone(tx);
+  }
+  // ---------- the one write path ----------
+  async applyBatch(batch) {
+    const tx = this.db.transaction(["ops", "cells", "meta"], "readwrite");
+    const ops = tx.objectStore("ops");
+    const cells = tx.objectStore("cells");
+    const meta = tx.objectStore("meta");
+    for (const op of batch.ops) ops.put(op);
+    for (const [key, op] of batch.winners) cells.put({ key, op });
+    meta.put(batch.frontier, "frontier");
+    meta.put(batch.clock, "clock");
+    await txDone(tx);
+  }
+  // ---------- helpers ----------
+  async rangeScan(store, prefix) {
+    const tx = this.db.transaction(store, "readonly");
+    const range = prefix === "" ? void 0 : IDBKeyRange.bound(prefix, prefix + HIGH, false, false);
+    const out = [];
+    await cursorEach(
+      tx.objectStore(store).openCursor(range ?? null),
+      (rec) => out.push(rec)
+    );
+    return out;
+  }
+};
+function promisifyOpen(req) {
+  req.onupgradeneeded = () => {
+    const db = req.result;
+    db.createObjectStore("ops", { keyPath: "id" });
+    db.createObjectStore("cells", { keyPath: "key" });
+    db.createObjectStore("meta");
+  };
+  return promisifyRequest(req);
+}
+function promisifyRequest(req) {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error ?? new Error("IndexedDB request failed"));
+  });
+}
+function txDone(tx) {
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onabort = () => reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+    tx.onerror = () => reject(tx.error ?? new Error("IndexedDB transaction failed"));
+  });
+}
+function cursorEach(req, fn) {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => {
+      const cur = req.result;
+      if (!cur) return resolve();
+      fn(cur.value);
+      cur.continue();
+    };
+    req.onerror = () => reject(req.error ?? new Error("IndexedDB cursor failed"));
+  });
+}
+export {
+  IdbAdapter
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@tangentfeed/adapter-idb",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@tangentfeed/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "fake-indexeddb": "^6.0.0",
+    "fast-check": "^3.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "tsup": "^8.5.0"
+  },
+  "description": "IndexedDB storage adapter for tangentfeed",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sreerajta/tangentfeed.git",
+    "directory": "packages/adapter-idb"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}