@optimystic/db-p2p-storage-web 0.21.0 → 0.24.0

package/README.md

@@ -1,108 +1,108 @@
-# @optimystic/db-p2p-storage-web
-
-IndexedDB-backed storage backend for Optimystic browser peers. Provides:
-
-- **`IndexedDBRawStorage`** — implements `IRawStorage` so a browser node persists
-  block metadata, revisions, pending transactions, committed transactions, and
-  materialized blocks across page reloads.
-- **`IndexedDBKVStore`** — implements `IKVStore` for the persistent transaction
-  state used to recover crashed two-phase commits.
-- **`loadOrCreateBrowserPeerKey`** — generates an Ed25519 libp2p private key on
-  first run and persists it in the same IndexedDB database, giving the browser
-  peer a stable, reload-surviving identity.
-
-This package is browser-only — it imports no Node built-ins. Counterparts:
-
-- `@optimystic/db-p2p-storage-rn` — React Native (MMKV)
-- `@optimystic/db-p2p-storage-fs` — Node filesystem
-
-## Install
-
-```bash
-yarn add @optimystic/db-p2p-storage-web @optimystic/db-p2p @optimystic/db-core
-```
-
-`@optimystic/db-p2p` is consumed via its `react-native` / `./rn` entry point so
-the Node-only filesystem code does not get bundled into the browser:
-
-```ts
-import { createLibp2pNode } from '@optimystic/db-p2p/rn';
-```
-
-## Usage
-
-```ts
-import { createLibp2pNode } from '@optimystic/db-p2p/rn';
-import {
-  openOptimysticWebDb,
-  IndexedDBRawStorage,
-  IndexedDBKVStore,
-  loadOrCreateBrowserPeerKey,
-} from '@optimystic/db-p2p-storage-web';
-
-const db = await openOptimysticWebDb();          // single shared handle
-const rawStorage = new IndexedDBRawStorage(db);  // → IRawStorage
-const kvStore = new IndexedDBKVStore(db);        // → IKVStore (txn recovery)
-const privateKey = await loadOrCreateBrowserPeerKey(db);
-
-const libp2p = await createLibp2pNode({
-  bootstrapNodes: [/* … */],
-  networkName: 'my-network',
-  privateKey,
-});
-```
-
-The same `IDBPDatabase` handle is shared by all three consumers — IndexedDB
-permits concurrent transactions across disjoint object stores, so the storage
-layer parallelises naturally.
-
-## Persistence semantics
-
-The package opens a single IndexedDB database (`optimystic` by default) with
-six object stores. `IndexedDBRawStorage` is a thin shell over the shared
-`KvRawStorage` kernel driven by an `IndexedDBStoreDriver`: the kernel owns all
-JSON/UTF-8 serialization, so the five block-storage stores now hold opaque
-kernel-encoded `Uint8Array` bytes rather than live objects. The keys and the
-logical types the kernel decodes them back into are unchanged:
-
-| Store          | Key                  | Stored value | Decoded (logical) type |
-|----------------|----------------------|--------------|------------------------|
-| `metadata`     | `blockId`            | `Uint8Array` | `BlockMetadata`        |
-| `revisions`    | `[blockId, rev]`     | `Uint8Array` | `ActionId`             |
-| `pending`      | `[blockId, actionId]`| `Uint8Array` | `Transform`            |
-| `transactions` | `[blockId, actionId]`| `Uint8Array` | `Transform`            |
-| `materialized` | `[blockId, actionId]`| `Uint8Array` | `IBlock`               |
-| `kv`           | `key`                | `string` or `Uint8Array` | — (not kernel-backed) |
-
-`listRevisions` and `listPendingTransactions` use real IndexedDB range cursors
-— never `getAllKeys()` + JS filter — so list latency stays bounded as the store
-grows. `promotePendingTransaction` runs as a single `readwrite` transaction
-spanning `pending` and `transactions`, so the move is atomic across crashes.
-
-`getApproximateBytesUsed()` returns `(await navigator.storage.estimate()).usage`,
-which is **per-origin**, not per-database. That is adequate for `StorageMonitor`
-— which uses the figure as an advisory ring-selection input — but is not a
-precise per-database accounting.
-
-## Identity
-
-`loadOrCreateBrowserPeerKey(db, keyName?)` writes the libp2p private key as
-raw protobuf bytes (`Uint8Array`) under `keyName` in the `kv` store
-(default `peer-private-key`). IndexedDB stores typed arrays natively, so no
-base64 round-trip is needed. To rotate the identity, delete that one key:
-
-```ts
-await db.delete('kv', 'peer-private-key');
-```
-
-To wipe the entire backing store (debugging / dev reset):
-
-```ts
-indexedDB.deleteDatabase('optimystic');
-```
-
-## Tests
-
-`yarn test` runs the spec suite under [`fake-indexeddb`](https://www.npmjs.com/package/fake-indexeddb)
-in Node so CI doesn't need a real browser. Production code only uses the
-IndexedDB W3C API, so fake-indexeddb is a faithful behavioural surrogate.
+# @optimystic/db-p2p-storage-web
+
+IndexedDB-backed storage backend for Optimystic browser peers. Provides:
+
+- **`IndexedDBRawStorage`** — implements `IRawStorage` so a browser node persists
+  block metadata, revisions, pending transactions, committed transactions, and
+  materialized blocks across page reloads.
+- **`IndexedDBKVStore`** — implements `IKVStore` for the persistent transaction
+  state used to recover crashed two-phase commits.
+- **`loadOrCreateBrowserPeerKey`** — generates an Ed25519 libp2p private key on
+  first run and persists it in the same IndexedDB database, giving the browser
+  peer a stable, reload-surviving identity.
+
+This package is browser-only — it imports no Node built-ins. Counterparts:
+
+- `@optimystic/db-p2p-storage-rn` — React Native (MMKV)
+- `@optimystic/db-p2p-storage-fs` — Node filesystem
+
+## Install
+
+```bash
+yarn add @optimystic/db-p2p-storage-web @optimystic/db-p2p @optimystic/db-core
+```
+
+`@optimystic/db-p2p` is consumed via its `react-native` / `./rn` entry point so
+the Node-only filesystem code does not get bundled into the browser:
+
+```ts
+import { createLibp2pNode } from '@optimystic/db-p2p/rn';
+```
+
+## Usage
+
+```ts
+import { createLibp2pNode } from '@optimystic/db-p2p/rn';
+import {
+  openOptimysticWebDb,
+  IndexedDBRawStorage,
+  IndexedDBKVStore,
+  loadOrCreateBrowserPeerKey,
+} from '@optimystic/db-p2p-storage-web';
+
+const db = await openOptimysticWebDb();          // single shared handle
+const rawStorage = new IndexedDBRawStorage(db);  // → IRawStorage
+const kvStore = new IndexedDBKVStore(db);        // → IKVStore (txn recovery)
+const privateKey = await loadOrCreateBrowserPeerKey(db);
+
+const libp2p = await createLibp2pNode({
+  bootstrapNodes: [/* … */],
+  networkName: 'my-network',
+  privateKey,
+});
+```
+
+The same `IDBPDatabase` handle is shared by all three consumers — IndexedDB
+permits concurrent transactions across disjoint object stores, so the storage
+layer parallelises naturally.
+
+## Persistence semantics
+
+The package opens a single IndexedDB database (`optimystic` by default) with
+six object stores. `IndexedDBRawStorage` is a thin shell over the shared
+`KvRawStorage` kernel driven by an `IndexedDBStoreDriver`: the kernel owns all
+JSON/UTF-8 serialization, so the five block-storage stores now hold opaque
+kernel-encoded `Uint8Array` bytes rather than live objects. The keys and the
+logical types the kernel decodes them back into are unchanged:
+
+| Store          | Key                  | Stored value | Decoded (logical) type |
+|----------------|----------------------|--------------|------------------------|
+| `metadata`     | `blockId`            | `Uint8Array` | `BlockMetadata`        |
+| `revisions`    | `[blockId, rev]`     | `Uint8Array` | `ActionId`             |
+| `pending`      | `[blockId, actionId]`| `Uint8Array` | `Transform`            |
+| `transactions` | `[blockId, actionId]`| `Uint8Array` | `Transform`            |
+| `materialized` | `[blockId, actionId]`| `Uint8Array` | `IBlock`               |
+| `kv`           | `key`                | `string` or `Uint8Array` | — (not kernel-backed) |
+
+`listRevisions` and `listPendingTransactions` use real IndexedDB range cursors
+— never `getAllKeys()` + JS filter — so list latency stays bounded as the store
+grows. `promotePendingTransaction` runs as a single `readwrite` transaction
+spanning `pending` and `transactions`, so the move is atomic across crashes.
+
+`getApproximateBytesUsed()` returns `(await navigator.storage.estimate()).usage`,
+which is **per-origin**, not per-database. That is adequate for `StorageMonitor`
+— which uses the figure as an advisory ring-selection input — but is not a
+precise per-database accounting.
+
+## Identity
+
+`loadOrCreateBrowserPeerKey(db, keyName?)` writes the libp2p private key as
+raw protobuf bytes (`Uint8Array`) under `keyName` in the `kv` store
+(default `peer-private-key`). IndexedDB stores typed arrays natively, so no
+base64 round-trip is needed. To rotate the identity, delete that one key:
+
+```ts
+await db.delete('kv', 'peer-private-key');
+```
+
+To wipe the entire backing store (debugging / dev reset):
+
+```ts
+indexedDB.deleteDatabase('optimystic');
+```
+
+## Tests
+
+`yarn test` runs the spec suite under [`fake-indexeddb`](https://www.npmjs.com/package/fake-indexeddb)
+in Node so CI doesn't need a real browser. Production code only uses the
+IndexedDB W3C API, so fake-indexeddb is a faithful behavioural surrogate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optimystic/db-p2p-storage-web",
-  "version": "0.21.0",
+  "version": "0.24.0",
   "type": "module",
   "description": "Browser IndexedDB storage backend for @optimystic/db-p2p",
   "main": "dist/src/index.js",
@@ -54,8 +54,8 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@optimystic/db-core": "^0.21.0",
-    "@optimystic/db-p2p": "^0.21.0",
+    "@optimystic/db-core": "^0.24.0",
+    "@optimystic/db-p2p": "^0.24.0",
     "debug": "^4.4.3",
     "idb": "^8.0.3"
   },

package/src/db.ts

@@ -1,92 +1,92 @@
-import { openDB, type DBSchema, type IDBPDatabase } from 'idb';
-import type { ActionId, BlockId } from '@optimystic/db-core';
-
-/**
- * IndexedDB schema for the Optimystic browser storage backend.
- *
- * The five block-storage stores keep their original object stores and compound
- * array keys, but their values are now opaque `Uint8Array` blobs: the shared
- * `KvRawStorage` kernel owns JSON (de)serialization, so `IndexedDBStoreDriver`
- * only ever hands IndexedDB kernel-encoded bytes. IndexedDB stores a
- * `Uint8Array` natively via structured clone and returns a `Uint8Array`, so the
- * bytes round-trip without a codec here.
- *
- * - `metadata`: per-block metadata bytes keyed by `blockId`.
- * - `revisions`: revision lookup keyed by `[blockId, rev]` mapping to actionId bytes.
- *   Range scans use `IDBKeyRange.bound([blockId, startRev], [blockId, endRev])`.
- * - `pending`: pending transform bytes keyed by `[blockId, actionId]`. Listing pending
- *   transactions for a block uses a key cursor over `[blockId, ...]`.
- * - `transactions`: committed transform bytes keyed by `[blockId, actionId]`.
- * - `materialized`: materialized block bytes keyed by `[blockId, actionId]`. Deleting
- *   the row is a driver `delete`, not a stored `undefined`.
- * - `kv`: a generic string keyspace shared by `IndexedDBKVStore` and the
- *   identity helper. Identity keys are stored as raw `Uint8Array` blobs (under
- *   a separate logical store from string-only `IKVStore` data, but the same
- *   IndexedDB object store — IndexedDB stores typed arrays natively).
- */
-export interface OptimysticWebDB extends DBSchema {
-	metadata: {
-		key: BlockId;
-		value: Uint8Array;
-	};
-	revisions: {
-		key: [BlockId, number];
-		value: Uint8Array;
-	};
-	pending: {
-		key: [BlockId, ActionId];
-		value: Uint8Array;
-	};
-	transactions: {
-		key: [BlockId, ActionId];
-		value: Uint8Array;
-	};
-	materialized: {
-		key: [BlockId, ActionId];
-		value: Uint8Array;
-	};
-	kv: {
-		key: string;
-		value: string | Uint8Array;
-	};
-}
-
-export const DEFAULT_DB_NAME = 'optimystic';
-export const DEFAULT_DB_VERSION = 1;
-
-export type OptimysticWebDBHandle = IDBPDatabase<OptimysticWebDB>;
-
-/**
- * Opens (and creates if necessary) the Optimystic IndexedDB database used by
- * `IndexedDBRawStorage`, `IndexedDBKVStore`, and `loadOrCreateBrowserPeerKey`.
- *
- * The same handle can be safely shared across all three — IndexedDB connections
- * support concurrent transactions across disjoint object stores.
- */
-export async function openOptimysticWebDb(
-	name: string = DEFAULT_DB_NAME,
-	version: number = DEFAULT_DB_VERSION,
-): Promise<OptimysticWebDBHandle> {
-	return openDB<OptimysticWebDB>(name, version, {
-		upgrade(db) {
-			if (!db.objectStoreNames.contains('metadata')) {
-				db.createObjectStore('metadata');
-			}
-			if (!db.objectStoreNames.contains('revisions')) {
-				db.createObjectStore('revisions');
-			}
-			if (!db.objectStoreNames.contains('pending')) {
-				db.createObjectStore('pending');
-			}
-			if (!db.objectStoreNames.contains('transactions')) {
-				db.createObjectStore('transactions');
-			}
-			if (!db.objectStoreNames.contains('materialized')) {
-				db.createObjectStore('materialized');
-			}
-			if (!db.objectStoreNames.contains('kv')) {
-				db.createObjectStore('kv');
-			}
-		},
-	});
-}
+import { openDB, type DBSchema, type IDBPDatabase } from 'idb';
+import type { ActionId, BlockId } from '@optimystic/db-core';
+
+/**
+ * IndexedDB schema for the Optimystic browser storage backend.
+ *
+ * The five block-storage stores keep their original object stores and compound
+ * array keys, but their values are now opaque `Uint8Array` blobs: the shared
+ * `KvRawStorage` kernel owns JSON (de)serialization, so `IndexedDBStoreDriver`
+ * only ever hands IndexedDB kernel-encoded bytes. IndexedDB stores a
+ * `Uint8Array` natively via structured clone and returns a `Uint8Array`, so the
+ * bytes round-trip without a codec here.
+ *
+ * - `metadata`: per-block metadata bytes keyed by `blockId`.
+ * - `revisions`: revision lookup keyed by `[blockId, rev]` mapping to actionId bytes.
+ *   Range scans use `IDBKeyRange.bound([blockId, startRev], [blockId, endRev])`.
+ * - `pending`: pending transform bytes keyed by `[blockId, actionId]`. Listing pending
+ *   transactions for a block uses a key cursor over `[blockId, ...]`.
+ * - `transactions`: committed transform bytes keyed by `[blockId, actionId]`.
+ * - `materialized`: materialized block bytes keyed by `[blockId, actionId]`. Deleting
+ *   the row is a driver `delete`, not a stored `undefined`.
+ * - `kv`: a generic string keyspace shared by `IndexedDBKVStore` and the
+ *   identity helper. Identity keys are stored as raw `Uint8Array` blobs (under
+ *   a separate logical store from string-only `IKVStore` data, but the same
+ *   IndexedDB object store — IndexedDB stores typed arrays natively).
+ */
+export interface OptimysticWebDB extends DBSchema {
+	metadata: {
+		key: BlockId;
+		value: Uint8Array;
+	};
+	revisions: {
+		key: [BlockId, number];
+		value: Uint8Array;
+	};
+	pending: {
+		key: [BlockId, ActionId];
+		value: Uint8Array;
+	};
+	transactions: {
+		key: [BlockId, ActionId];
+		value: Uint8Array;
+	};
+	materialized: {
+		key: [BlockId, ActionId];
+		value: Uint8Array;
+	};
+	kv: {
+		key: string;
+		value: string | Uint8Array;
+	};
+}
+
+export const DEFAULT_DB_NAME = 'optimystic';
+export const DEFAULT_DB_VERSION = 1;
+
+export type OptimysticWebDBHandle = IDBPDatabase<OptimysticWebDB>;
+
+/**
+ * Opens (and creates if necessary) the Optimystic IndexedDB database used by
+ * `IndexedDBRawStorage`, `IndexedDBKVStore`, and `loadOrCreateBrowserPeerKey`.
+ *
+ * The same handle can be safely shared across all three — IndexedDB connections
+ * support concurrent transactions across disjoint object stores.
+ */
+export async function openOptimysticWebDb(
+	name: string = DEFAULT_DB_NAME,
+	version: number = DEFAULT_DB_VERSION,
+): Promise<OptimysticWebDBHandle> {
+	return openDB<OptimysticWebDB>(name, version, {
+		upgrade(db) {
+			if (!db.objectStoreNames.contains('metadata')) {
+				db.createObjectStore('metadata');
+			}
+			if (!db.objectStoreNames.contains('revisions')) {
+				db.createObjectStore('revisions');
+			}
+			if (!db.objectStoreNames.contains('pending')) {
+				db.createObjectStore('pending');
+			}
+			if (!db.objectStoreNames.contains('transactions')) {
+				db.createObjectStore('transactions');
+			}
+			if (!db.objectStoreNames.contains('materialized')) {
+				db.createObjectStore('materialized');
+			}
+			if (!db.objectStoreNames.contains('kv')) {
+				db.createObjectStore('kv');
+			}
+		},
+	});
+}

package/src/identity.ts

@@ -1,29 +1,29 @@
-import { generateKeyPair, privateKeyFromProtobuf, privateKeyToProtobuf } from '@libp2p/crypto/keys';
-import type { PrivateKey } from '@libp2p/interface';
-import type { OptimysticWebDBHandle } from './db.js';
-
-export const DEFAULT_PEER_KEY_NAME = 'peer-private-key';
-
-/**
- * Loads the persisted browser peer's libp2p private key, or generates a fresh
- * Ed25519 key on first call and persists it.
- *
- * Stores the key as raw protobuf bytes (a `Uint8Array`) under `keyName` in the
- * `kv` object store. IndexedDB stores typed arrays natively — no base64 round-trip.
- *
- * The returned `PrivateKey` can be passed directly to `createLibp2pNode({ privateKey })`,
- * giving a browser peer a stable, reload-surviving identity.
- */
-export async function loadOrCreateBrowserPeerKey(
-	db: OptimysticWebDBHandle,
-	keyName: string = DEFAULT_PEER_KEY_NAME,
-): Promise<PrivateKey> {
-	const stored = await db.get('kv', keyName);
-	if (stored instanceof Uint8Array) {
-		return privateKeyFromProtobuf(stored);
-	}
-	const key = await generateKeyPair('Ed25519');
-	const bytes = privateKeyToProtobuf(key);
-	await db.put('kv', bytes, keyName);
-	return key;
-}
+import { generateKeyPair, privateKeyFromProtobuf, privateKeyToProtobuf } from '@libp2p/crypto/keys';
+import type { PrivateKey } from '@libp2p/interface';
+import type { OptimysticWebDBHandle } from './db.js';
+
+export const DEFAULT_PEER_KEY_NAME = 'peer-private-key';
+
+/**
+ * Loads the persisted browser peer's libp2p private key, or generates a fresh
+ * Ed25519 key on first call and persists it.
+ *
+ * Stores the key as raw protobuf bytes (a `Uint8Array`) under `keyName` in the
+ * `kv` object store. IndexedDB stores typed arrays natively — no base64 round-trip.
+ *
+ * The returned `PrivateKey` can be passed directly to `createLibp2pNode({ privateKey })`,
+ * giving a browser peer a stable, reload-surviving identity.
+ */
+export async function loadOrCreateBrowserPeerKey(
+	db: OptimysticWebDBHandle,
+	keyName: string = DEFAULT_PEER_KEY_NAME,
+): Promise<PrivateKey> {
+	const stored = await db.get('kv', keyName);
+	if (stored instanceof Uint8Array) {
+		return privateKeyFromProtobuf(stored);
+	}
+	const key = await generateKeyPair('Ed25519');
+	const bytes = privateKeyToProtobuf(key);
+	await db.put('kv', bytes, keyName);
+	return key;
+}

package/src/index.ts

@@ -1,4 +1,4 @@
-export * from './db.js';
-export * from './indexeddb-storage.js';
-export * from './indexeddb-kv-store.js';
-export * from './identity.js';
+export * from './db.js';
+export * from './indexeddb-storage.js';
+export * from './indexeddb-kv-store.js';
+export * from './identity.js';

package/src/indexeddb-kv-store.ts

@@ -1,49 +1,49 @@
-import type { IKVStore } from '@optimystic/db-p2p';
-import type { OptimysticWebDBHandle } from './db.js';
-
-/**
- * IndexedDB-backed `IKVStore` adapter for browser peers.
- *
- * Stored keys are namespaced with `prefix` so the `kv` object store can be
- * shared with the identity helper without collisions. `list(prefix)` uses a
- * range-bounded key cursor — never `getAllKeys()` — so a large `kv` store
- * does not pay an O(n) JS-side filter cost.
- */
-export class IndexedDBKVStore implements IKVStore {
-	constructor(
-		private readonly db: OptimysticWebDBHandle,
-		private readonly prefix: string = 'optimystic:txn:',
-	) {}
-
-	async get(key: string): Promise<string | undefined> {
-		const value = await this.db.get('kv', this.prefix + key);
-		return typeof value === 'string' ? value : undefined;
-	}
-
-	async set(key: string, value: string): Promise<void> {
-		await this.db.put('kv', value, this.prefix + key);
-	}
-
-	async delete(key: string): Promise<void> {
-		await this.db.delete('kv', this.prefix + key);
-	}
-
-	async list(prefix: string): Promise<string[]> {
-		const fullPrefix = this.prefix + prefix;
-		// '￿' is the highest BMP code unit; appending it produces a string
-		// that is >= every string starting with `fullPrefix`. IndexedDB compares
-		// strings by UTF-16 code units, so this bound is exact.
-		const range = IDBKeyRange.bound(fullPrefix, fullPrefix + '￿');
-		const tx = this.db.transaction('kv', 'readonly');
-		const store = tx.objectStore('kv');
-		const keys: string[] = [];
-		let cursor = await store.openKeyCursor(range);
-		while (cursor) {
-			const fullKey = cursor.key as string;
-			keys.push(fullKey.slice(this.prefix.length));
-			cursor = await cursor.continue();
-		}
-		await tx.done;
-		return keys;
-	}
-}
+import type { IKVStore } from '@optimystic/db-p2p';
+import type { OptimysticWebDBHandle } from './db.js';
+
+/**
+ * IndexedDB-backed `IKVStore` adapter for browser peers.
+ *
+ * Stored keys are namespaced with `prefix` so the `kv` object store can be
+ * shared with the identity helper without collisions. `list(prefix)` uses a
+ * range-bounded key cursor — never `getAllKeys()` — so a large `kv` store
+ * does not pay an O(n) JS-side filter cost.
+ */
+export class IndexedDBKVStore implements IKVStore {
+	constructor(
+		private readonly db: OptimysticWebDBHandle,
+		private readonly prefix: string = 'optimystic:txn:',
+	) {}
+
+	async get(key: string): Promise<string | undefined> {
+		const value = await this.db.get('kv', this.prefix + key);
+		return typeof value === 'string' ? value : undefined;
+	}
+
+	async set(key: string, value: string): Promise<void> {
+		await this.db.put('kv', value, this.prefix + key);
+	}
+
+	async delete(key: string): Promise<void> {
+		await this.db.delete('kv', this.prefix + key);
+	}
+
+	async list(prefix: string): Promise<string[]> {
+		const fullPrefix = this.prefix + prefix;
+		// '￿' is the highest BMP code unit; appending it produces a string
+		// that is >= every string starting with `fullPrefix`. IndexedDB compares
+		// strings by UTF-16 code units, so this bound is exact.
+		const range = IDBKeyRange.bound(fullPrefix, fullPrefix + '￿');
+		const tx = this.db.transaction('kv', 'readonly');
+		const store = tx.objectStore('kv');
+		const keys: string[] = [];
+		let cursor = await store.openKeyCursor(range);
+		while (cursor) {
+			const fullKey = cursor.key as string;
+			keys.push(fullKey.slice(this.prefix.length));
+			cursor = await cursor.continue();
+		}
+		await tx.done;
+		return keys;
+	}
+}

package/src/indexeddb-storage.ts

@@ -1,188 +1,188 @@
-import type { ActionId, BlockId } from '@optimystic/db-core';
-import { KvRawStorage, type RawStoreDriver } from '@optimystic/db-p2p';
-import type { OptimysticWebDBHandle } from './db.js';
-import { createLogger } from './logger.js';
-
-const log = createLogger('storage:indexeddb');
-
-/**
- * IndexedDB {@link RawStoreDriver}: the five logical block-storage stores mapped
- * to the five IndexedDB object stores (`metadata`, `revisions`, `pending`,
- * `transactions`, `materialized`) with their original compound array keys. This
- * is a code refactor, not a storage-format change at the key level.
- *
- * `KvRawStorage` now owns all JSON serialization, so this driver only ever
- * reads/writes `Uint8Array` values — IndexedDB stores a typed array natively via
- * structured clone and returns a `Uint8Array`, so no codec lives here. Everything
- * IndexedDB-specific stays: the range/key cursors (drained snapshot-first before
- * yielding), and the single `readwrite` transaction that makes `promote` atomic.
- */
-export class IndexedDBStoreDriver implements RawStoreDriver {
-	constructor(private readonly db: OptimysticWebDBHandle) {}
-
-	// --- metadata ---
-
-	async getMetadata(blockId: BlockId): Promise<Uint8Array | undefined> {
-		return this.db.get('metadata', blockId);
-	}
-
-	async putMetadata(blockId: BlockId, value: Uint8Array): Promise<void> {
-		await this.db.put('metadata', value, blockId);
-	}
-
-	// --- revisions ---
-
-	async getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
-		return this.db.get('revisions', [blockId, rev]);
-	}
-
-	async putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
-		await this.db.put('revisions', value, [blockId, rev]);
-	}
-
-	async *rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]> {
-		const range = IDBKeyRange.bound([blockId, lo], [blockId, hi]);
-		const tx = this.db.transaction('revisions', 'readonly');
-		const store = tx.objectStore('revisions');
-		// Snapshot first so we don't hold the transaction open across yields —
-		// IndexedDB auto-commits idle transactions, which would invalidate the
-		// cursor between the consumer's awaits (the kernel's drain-before-yield
-		// contract). Do NOT switch to lazy yielding mid-transaction.
-		const results: [number, Uint8Array][] = [];
-		let cursor = await store.openCursor(range, reverse ? 'prev' : 'next');
-		while (cursor) {
-			results.push([(cursor.key as [BlockId, number])[1], cursor.value]);
-			cursor = await cursor.continue();
-		}
-		await tx.done;
-		for (const result of results) {
-			yield result;
-		}
-	}
-
-	// --- pending ---
-
-	async getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.db.get('pending', [blockId, actionId]);
-	}
-
-	async putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		await this.db.put('pending', value, [blockId, actionId]);
-	}
-
-	async deletePending(blockId: BlockId, actionId: ActionId): Promise<void> {
-		await this.db.delete('pending', [blockId, actionId]);
-	}
-
-	async *listPendingActionIds(blockId: BlockId): AsyncIterable<ActionId> {
-		// IndexedDB key ordering: array keys compare element-by-element, and a
-		// shorter prefix-equal array is less than a longer one; arrays sort
-		// above all primitive types. So `[blockId]` < `[blockId, anyActionId]`
-		// < `[blockId, []]`, which captures exactly every key for this block.
-		const range = IDBKeyRange.bound([blockId] as IDBValidKey, [blockId, []] as IDBValidKey);
-		const tx = this.db.transaction('pending', 'readonly');
-		const store = tx.objectStore('pending');
-		// Snapshot-first, same rationale as rangeRevisions.
-		const results: ActionId[] = [];
-		let cursor = await store.openKeyCursor(range);
-		while (cursor) {
-			results.push((cursor.key as [BlockId, ActionId])[1]);
-			cursor = await cursor.continue();
-		}
-		await tx.done;
-		for (const actionId of results) {
-			yield actionId;
-		}
-	}
-
-	// --- transactions ---
-
-	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.db.get('transactions', [blockId, actionId]);
-	}
-
-	async putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		await this.db.put('transactions', value, [blockId, actionId]);
-	}
-
-	// --- materialized ---
-
-	async getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
-		return this.db.get('materialized', [blockId, actionId]);
-	}
-
-	async putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
-		await this.db.put('materialized', value, [blockId, actionId]);
-	}
-
-	// The kernel owns the put-or-delete branch of `saveMaterializedBlock`, so the
-	// driver exposes delete as a separate op.
-	async deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void> {
-		await this.db.delete('materialized', [blockId, actionId]);
-	}
-
-	// --- promote (the only cross-key atomic op) ---
-
-	async promote(blockId: BlockId, actionId: ActionId): Promise<void> {
-		const key: [BlockId, ActionId] = [blockId, actionId];
-		// Single readwrite transaction over both stores IS the atomic move: a crash
-		// leaves either the pending or the committed entry, never both/neither.
-		const tx = this.db.transaction(['pending', 'transactions'], 'readwrite');
-		const pendingStore = tx.objectStore('pending');
-		const transactionsStore = tx.objectStore('transactions');
-		const value = await pendingStore.get(key);
-		if (!value) {
-			// Settle the transaction before throwing so the failed promote does not
-			// leak an open transaction — keep this ordering.
-			await tx.done.catch(() => undefined);
-			throw new Error(`Pending action ${actionId} not found for block ${blockId}`);
-		}
-		await transactionsStore.put(value, key);
-		await pendingStore.delete(key);
-		await tx.done;
-	}
-
-	// --- optional passthroughs ---
-
-	async *listBlockIds(): AsyncIterable<BlockId> {
-		// The `metadata` store is keyed by blockId directly, so its keys ARE the
-		// distinct block ids. getAllKeys reads them under an implicit readonly
-		// transaction and returns an already-materialized array — no cursor held
-		// across yields (same rationale as the cursor scans' snapshot-first pattern).
-		const keys = await this.db.getAllKeys('metadata');
-		for (const key of keys) {
-			yield key as BlockId;
-		}
-	}
-
-	async approximateBytesUsed(): Promise<number> {
-		try {
-			const estimate = await navigator.storage?.estimate?.();
-			return estimate?.usage ?? 0;
-		} catch (err) {
-			log('navigator.storage.estimate() failed: %o', err);
-			return 0;
-		}
-	}
-}
-
-/**
- * IndexedDB-backed {@link IRawStorage} for browser peers, now a thin shell over
- * the shared {@link KvRawStorage} kernel driven by an {@link IndexedDBStoreDriver}.
- * The public name/constructor (`new IndexedDBRawStorage(handle)`) is unchanged so
- * existing imports keep resolving; the kernel supplies the `IRawStorage` surface
- * and the driver supplies IndexedDB behavior.
- *
- * `listBlockIds`/`getApproximateBytesUsed` are re-declared here as always-present
- * (the IndexedDB driver always implements them, so the kernel constructor always
- * wires them) — the base declares them optional, but every web consumer relies
- * on them.
- */
-export class IndexedDBRawStorage extends KvRawStorage {
-	declare listBlockIds: () => AsyncIterable<BlockId>;
-	declare getApproximateBytesUsed: () => Promise<number>;
-
-	constructor(db: OptimysticWebDBHandle) {
-		super(new IndexedDBStoreDriver(db));
-	}
-}
+import type { ActionId, BlockId } from '@optimystic/db-core';
+import { KvRawStorage, type RawStoreDriver } from '@optimystic/db-p2p';
+import type { OptimysticWebDBHandle } from './db.js';
+import { createLogger } from './logger.js';
+
+const log = createLogger('storage:indexeddb');
+
+/**
+ * IndexedDB {@link RawStoreDriver}: the five logical block-storage stores mapped
+ * to the five IndexedDB object stores (`metadata`, `revisions`, `pending`,
+ * `transactions`, `materialized`) with their original compound array keys. This
+ * is a code refactor, not a storage-format change at the key level.
+ *
+ * `KvRawStorage` now owns all JSON serialization, so this driver only ever
+ * reads/writes `Uint8Array` values — IndexedDB stores a typed array natively via
+ * structured clone and returns a `Uint8Array`, so no codec lives here. Everything
+ * IndexedDB-specific stays: the range/key cursors (drained snapshot-first before
+ * yielding), and the single `readwrite` transaction that makes `promote` atomic.
+ */
+export class IndexedDBStoreDriver implements RawStoreDriver {
+	constructor(private readonly db: OptimysticWebDBHandle) {}
+
+	// --- metadata ---
+
+	async getMetadata(blockId: BlockId): Promise<Uint8Array | undefined> {
+		return this.db.get('metadata', blockId);
+	}
+
+	async putMetadata(blockId: BlockId, value: Uint8Array): Promise<void> {
+		await this.db.put('metadata', value, blockId);
+	}
+
+	// --- revisions ---
+
+	async getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined> {
+		return this.db.get('revisions', [blockId, rev]);
+	}
+
+	async putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void> {
+		await this.db.put('revisions', value, [blockId, rev]);
+	}
+
+	async *rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]> {
+		const range = IDBKeyRange.bound([blockId, lo], [blockId, hi]);
+		const tx = this.db.transaction('revisions', 'readonly');
+		const store = tx.objectStore('revisions');
+		// Snapshot first so we don't hold the transaction open across yields —
+		// IndexedDB auto-commits idle transactions, which would invalidate the
+		// cursor between the consumer's awaits (the kernel's drain-before-yield
+		// contract). Do NOT switch to lazy yielding mid-transaction.
+		const results: [number, Uint8Array][] = [];
+		let cursor = await store.openCursor(range, reverse ? 'prev' : 'next');
+		while (cursor) {
+			results.push([(cursor.key as [BlockId, number])[1], cursor.value]);
+			cursor = await cursor.continue();
+		}
+		await tx.done;
+		for (const result of results) {
+			yield result;
+		}
+	}
+
+	// --- pending ---
+
+	async getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		return this.db.get('pending', [blockId, actionId]);
+	}
+
+	async putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.db.put('pending', value, [blockId, actionId]);
+	}
+
+	async deletePending(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.db.delete('pending', [blockId, actionId]);
+	}
+
+	async *listPendingActionIds(blockId: BlockId): AsyncIterable<ActionId> {
+		// IndexedDB key ordering: array keys compare element-by-element, and a
+		// shorter prefix-equal array is less than a longer one; arrays sort
+		// above all primitive types. So `[blockId]` < `[blockId, anyActionId]`
+		// < `[blockId, []]`, which captures exactly every key for this block.
+		const range = IDBKeyRange.bound([blockId] as IDBValidKey, [blockId, []] as IDBValidKey);
+		const tx = this.db.transaction('pending', 'readonly');
+		const store = tx.objectStore('pending');
+		// Snapshot-first, same rationale as rangeRevisions.
+		const results: ActionId[] = [];
+		let cursor = await store.openKeyCursor(range);
+		while (cursor) {
+			results.push((cursor.key as [BlockId, ActionId])[1]);
+			cursor = await cursor.continue();
+		}
+		await tx.done;
+		for (const actionId of results) {
+			yield actionId;
+		}
+	}
+
+	// --- transactions ---
+
+	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		return this.db.get('transactions', [blockId, actionId]);
+	}
+
+	async putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.db.put('transactions', value, [blockId, actionId]);
+	}
+
+	// --- materialized ---
+
+	async getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined> {
+		return this.db.get('materialized', [blockId, actionId]);
+	}
+
+	async putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void> {
+		await this.db.put('materialized', value, [blockId, actionId]);
+	}
+
+	// The kernel owns the put-or-delete branch of `saveMaterializedBlock`, so the
+	// driver exposes delete as a separate op.
+	async deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.db.delete('materialized', [blockId, actionId]);
+	}
+
+	// --- promote (the only cross-key atomic op) ---
+
+	async promote(blockId: BlockId, actionId: ActionId): Promise<void> {
+		const key: [BlockId, ActionId] = [blockId, actionId];
+		// Single readwrite transaction over both stores IS the atomic move: a crash
+		// leaves either the pending or the committed entry, never both/neither.
+		const tx = this.db.transaction(['pending', 'transactions'], 'readwrite');
+		const pendingStore = tx.objectStore('pending');
+		const transactionsStore = tx.objectStore('transactions');
+		const value = await pendingStore.get(key);
+		if (!value) {
+			// Settle the transaction before throwing so the failed promote does not
+			// leak an open transaction — keep this ordering.
+			await tx.done.catch(() => undefined);
+			throw new Error(`Pending action ${actionId} not found for block ${blockId}`);
+		}
+		await transactionsStore.put(value, key);
+		await pendingStore.delete(key);
+		await tx.done;
+	}
+
+	// --- optional passthroughs ---
+
+	async *listBlockIds(): AsyncIterable<BlockId> {
+		// The `metadata` store is keyed by blockId directly, so its keys ARE the
+		// distinct block ids. getAllKeys reads them under an implicit readonly
+		// transaction and returns an already-materialized array — no cursor held
+		// across yields (same rationale as the cursor scans' snapshot-first pattern).
+		const keys = await this.db.getAllKeys('metadata');
+		for (const key of keys) {
+			yield key as BlockId;
+		}
+	}
+
+	async approximateBytesUsed(): Promise<number> {
+		try {
+			const estimate = await navigator.storage?.estimate?.();
+			return estimate?.usage ?? 0;
+		} catch (err) {
+			log('navigator.storage.estimate() failed: %o', err);
+			return 0;
+		}
+	}
+}
+
+/**
+ * IndexedDB-backed {@link IRawStorage} for browser peers, now a thin shell over
+ * the shared {@link KvRawStorage} kernel driven by an {@link IndexedDBStoreDriver}.
+ * The public name/constructor (`new IndexedDBRawStorage(handle)`) is unchanged so
+ * existing imports keep resolving; the kernel supplies the `IRawStorage` surface
+ * and the driver supplies IndexedDB behavior.
+ *
+ * `listBlockIds`/`getApproximateBytesUsed` are re-declared here as always-present
+ * (the IndexedDB driver always implements them, so the kernel constructor always
+ * wires them) — the base declares them optional, but every web consumer relies
+ * on them.
+ */
+export class IndexedDBRawStorage extends KvRawStorage {
+	declare listBlockIds: () => AsyncIterable<BlockId>;
+	declare getApproximateBytesUsed: () => Promise<number>;
+
+	constructor(db: OptimysticWebDBHandle) {
+		super(new IndexedDBStoreDriver(db));
+	}
+}

package/src/logger.ts

@@ -1,7 +1,7 @@
-import debug from 'debug';
-
-const BASE_NAMESPACE = 'optimystic:db-p2p-storage-web';
-
-export function createLogger(subNamespace: string): debug.Debugger {
-	return debug(`${BASE_NAMESPACE}:${subNamespace}`);
-}
+import debug from 'debug';
+
+const BASE_NAMESPACE = 'optimystic:db-p2p-storage-web';
+
+export function createLogger(subNamespace: string): debug.Debugger {
+	return debug(`${BASE_NAMESPACE}:${subNamespace}`);
+}