@serfab/quereus-plugin-sereus 0.10.0 → 0.11.0

package/src/connect-browser.ts

@@ -1,57 +1,57 @@
-import type { Database, VTablePluginInfo, FunctionPluginInfo, CollationPluginInfo } from '@quereus/quereus';
-import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
-import { createLibp2pNode } from '@optimystic/db-p2p/rn';
-import { webSockets } from '@libp2p/websockets';
-import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
-import { IndexedDBRawStorage, openOptimysticWebDb } from '@optimystic/db-p2p-storage-web';
-import type { Libp2p } from '@libp2p/interface';
-import type { StrandConnectionOptions, SereusPluginResult } from './types.js';
-import { composeStrand, applyRegistrations } from './compose-strand.js';
-
-/** The subset of the crypto plugin result we register inline in the browser. */
-interface CryptoPluginResult {
-	vtables: VTablePluginInfo[];
-	functions: FunctionPluginInfo[];
-	collations: CollationPluginInfo[];
-}
-
-/**
- * Connect a Quereus Database to a Sereus strand from a browser/worker.
- *
- * Thin adapter over the shared {@link composeStrand} composition, supplying the
- * browser platform seams:
- *  - crypto registered inline (no runtime `@quereus/quereus` import, so the
- *    bundle does not duplicate the host's instance),
- *  - storage defaulting to `IndexedDBRawStorage` keyed by `sereus-strand-<id>`,
- *  - a node created via the TCP-free `@optimystic/db-p2p/rn` entry with explicit
- *    `webSockets()` + `circuitRelayTransport()` transports.
- */
-export async function connectToStrandBrowser(
-	db: Database,
-	options: StrandConnectionOptions,
-): Promise<SereusPluginResult> {
-	return composeStrand(db, options, {
-		registerCrypto(database) {
-			applyRegistrations(database, cryptoPlugin(database, {}) as unknown as CryptoPluginResult);
-		},
-		async resolveStorage({ strandId, resolvedTransactor, requestedStorage }) {
-			if (requestedStorage) return requestedStorage;
-			// Browsers always default to IndexedDB so a reload survives; the
-			// unit-test fake transactor needs no storage.
-			if (resolvedTransactor === 'test') return undefined;
-			const dbHandle = await openOptimysticWebDb(`sereus-strand-${strandId}`);
-			return new IndexedDBRawStorage(dbHandle);
-		},
-		async createNode({ networkName, bootstrapNodes, fretProfile, clusterSize, storage }) {
-			return createLibp2pNode({
-				transports: [webSockets(), circuitRelayTransport()],
-				listenAddrs: [],
-				bootstrapNodes,
-				networkName,
-				fretProfile,
-				clusterSize,
-				...(storage && { storage }),
-			}) as Promise<Libp2p>;
-		},
-	});
-}
+import type { Database, VTablePluginInfo, FunctionPluginInfo, CollationPluginInfo } from '@quereus/quereus';
+import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
+import { createLibp2pNode } from '@optimystic/db-p2p/rn';
+import { webSockets } from '@libp2p/websockets';
+import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
+import { IndexedDBRawStorage, openOptimysticWebDb } from '@optimystic/db-p2p-storage-web';
+import type { Libp2p } from '@libp2p/interface';
+import type { StrandConnectionOptions, SereusPluginResult } from './types.js';
+import { composeStrand, applyRegistrations } from './compose-strand.js';
+
+/** The subset of the crypto plugin result we register inline in the browser. */
+interface CryptoPluginResult {
+	vtables: VTablePluginInfo[];
+	functions: FunctionPluginInfo[];
+	collations: CollationPluginInfo[];
+}
+
+/**
+ * Connect a Quereus Database to a Sereus strand from a browser/worker.
+ *
+ * Thin adapter over the shared {@link composeStrand} composition, supplying the
+ * browser platform seams:
+ *  - crypto registered inline (no runtime `@quereus/quereus` import, so the
+ *    bundle does not duplicate the host's instance),
+ *  - storage defaulting to `IndexedDBRawStorage` keyed by `sereus-strand-<id>`,
+ *  - a node created via the TCP-free `@optimystic/db-p2p/rn` entry with explicit
+ *    `webSockets()` + `circuitRelayTransport()` transports.
+ */
+export async function connectToStrandBrowser(
+	db: Database,
+	options: StrandConnectionOptions,
+): Promise<SereusPluginResult> {
+	return composeStrand(db, options, {
+		registerCrypto(database) {
+			applyRegistrations(database, cryptoPlugin(database, {}) as unknown as CryptoPluginResult);
+		},
+		async resolveStorage({ strandId, resolvedTransactor, requestedStorage }) {
+			if (requestedStorage) return requestedStorage;
+			// Browsers always default to IndexedDB so a reload survives; the
+			// unit-test fake transactor needs no storage.
+			if (resolvedTransactor === 'test') return undefined;
+			const dbHandle = await openOptimysticWebDb(`sereus-strand-${strandId}`);
+			return new IndexedDBRawStorage(dbHandle);
+		},
+		async createNode({ networkName, bootstrapNodes, fretProfile, clusterSize, storage }) {
+			return createLibp2pNode({
+				transports: [webSockets(), circuitRelayTransport()],
+				listenAddrs: [],
+				bootstrapNodes,
+				networkName,
+				fretProfile,
+				clusterSize,
+				...(storage && { storage }),
+			}) as Promise<Libp2p>;
+		},
+	});
+}

package/src/connect.ts

@@ -1,38 +1,38 @@
-import type { Database } from '@quereus/quereus';
-import { registerPlugin } from '@quereus/quereus';
-import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
-import type { Libp2p } from '@libp2p/interface';
-import type { StrandConnectionOptions, SereusPluginResult } from './types.js';
-import { composeStrand } from './compose-strand.js';
-
-/**
- * Connect a Quereus Database to a Sereus strand (Node).
- *
- * Thin adapter over the shared {@link composeStrand} composition, supplying the
- * Node platform seams: crypto via `@quereus/quereus`'s `registerPlugin`, and a
- * TCP libp2p node created (only when not injected) via `@optimystic/db-p2p`.
- */
-export async function connectToStrand(
-	db: Database,
-	options: StrandConnectionOptions,
-): Promise<SereusPluginResult> {
-	return composeStrand(db, options, {
-		async registerCrypto(database) {
-			await registerPlugin(database, cryptoPlugin);
-		},
-		async createNode({ networkName, bootstrapNodes, fretProfile, port, clusterSize, storage }) {
-			// Dynamically import to keep the module cross-platform friendly: this
-			// pulls the Node-only `@optimystic/db-p2p` (TCP) entry, and is only
-			// reached when actually creating a node (never for injected nodes).
-			const { createLibp2pNode } = await import('@optimystic/db-p2p');
-			return createLibp2pNode({
-				port,
-				bootstrapNodes,
-				networkName,
-				fretProfile,
-				clusterSize,
-				...(storage && { storage }),
-			}) as Promise<Libp2p>;
-		},
-	});
-}
+import type { Database } from '@quereus/quereus';
+import { registerPlugin } from '@quereus/quereus';
+import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
+import type { Libp2p } from '@libp2p/interface';
+import type { StrandConnectionOptions, SereusPluginResult } from './types.js';
+import { composeStrand } from './compose-strand.js';
+
+/**
+ * Connect a Quereus Database to a Sereus strand (Node).
+ *
+ * Thin adapter over the shared {@link composeStrand} composition, supplying the
+ * Node platform seams: crypto via `@quereus/quereus`'s `registerPlugin`, and a
+ * TCP libp2p node created (only when not injected) via `@optimystic/db-p2p`.
+ */
+export async function connectToStrand(
+	db: Database,
+	options: StrandConnectionOptions,
+): Promise<SereusPluginResult> {
+	return composeStrand(db, options, {
+		async registerCrypto(database) {
+			await registerPlugin(database, cryptoPlugin);
+		},
+		async createNode({ networkName, bootstrapNodes, fretProfile, port, clusterSize, storage }) {
+			// Dynamically import to keep the module cross-platform friendly: this
+			// pulls the Node-only `@optimystic/db-p2p` (TCP) entry, and is only
+			// reached when actually creating a node (never for injected nodes).
+			const { createLibp2pNode } = await import('@optimystic/db-p2p');
+			return createLibp2pNode({
+				port,
+				bootstrapNodes,
+				networkName,
+				fretProfile,
+				clusterSize,
+				...(storage && { storage }),
+			}) as Promise<Libp2p>;
+		},
+	});
+}

package/src/index.ts

@@ -7,4 +7,5 @@ export {
 	STRAND_CLUSTER_POLICY,
 	resolveStrandClusterSize
 } from './cluster-size.js';
-export type { StrandConnectionOptions, SereusPluginResult } from './types.js';
+export { wrapStorageWithCache, disposeStorageCache } from './cached-storage.js';
+export type { StrandConnectionOptions, SereusPluginResult, StrandTransactor } from './types.js';

package/src/parse-config.ts

@@ -1,55 +1,70 @@
-import type { SqlValue } from '@quereus/quereus';
-import type { StrandConnectionOptions } from './types.js';
-
-/**
- * Parse the plugin-loader SqlValue config into typed StrandConnectionOptions.
- * Shared by the Node (`plugin.ts`) and browser (`plugin-browser.ts`) entries.
- */
-export function parseConfig(config: Record<string, SqlValue>): StrandConnectionOptions {
-	const strandId = config.strand_id;
-	if (typeof strandId !== 'string' || !strandId) {
-		throw new Error('quereus-plugin-sereus: strand_id is required');
-	}
-
-	const bootstrapNodesRaw = config.bootstrap_nodes;
-	const bootstrapNodes = typeof bootstrapNodesRaw === 'string' && bootstrapNodesRaw
-		? bootstrapNodesRaw.split(',').map(s => s.trim()).filter(Boolean)
-		: [];
-
-	const schema = typeof config.schema === 'string' ? config.schema : undefined;
-	const sAppId = typeof config.sapp_id === 'string' ? config.sapp_id : 'unknown';
-	const sAppVersion = typeof config.sapp_version === 'string' ? config.sapp_version : '1.0.0';
-	const port = typeof config.port === 'number' ? config.port : 0;
-	const enableCache = config.enable_cache !== false && config.enable_cache !== 0;
-	const fretProfile = config.fret_profile === 'core' ? 'core' as const : 'edge' as const;
-
-	// Lifecycle mode: selects bootstrap (local transactor) vs networked. Only the
-	// two known values are honored; anything else falls through to the default.
-	const mode = config.mode === 'bootstrap' || config.mode === 'networked'
-		? config.mode
-		: undefined;
-
-	// Internal transactor override (e.g. `'test'`). Applies only when `mode` is
-	// unset — see `StrandConnectionOptions.transactor`.
-	const transactor = typeof config.transactor === 'string' && config.transactor
-		? config.transactor
-		: undefined;
-
-	// NOTE: persistent storage cannot ride a `Record<string, SqlValue>` — an
-	// `IRawStorage` is not an `SqlValue`. The Node loader (`plugin.ts`) reads the
-	// platform-only `storage_path` key directly and resolves it to a concrete
-	// `FileRawStorage`; it is intentionally NOT parsed into the typed options here.
-
-	return {
-		strandId,
-		bootstrapNodes,
-		schema,
-		sAppId,
-		sAppVersion,
-		port,
-		enableCache,
-		fretProfile,
-		...(mode && { mode }),
-		...(transactor && { transactor }),
-	};
-}
+import type { SqlValue } from '@quereus/quereus';
+import type { StrandConnectionOptions, StrandTransactor } from './types.js';
+
+const STRAND_TRANSACTORS: readonly StrandTransactor[] = ['local', 'network', 'test'];
+
+/**
+ * Read the optional `transactor` key. Unlike `fret_profile` (whose unknown
+ * values fall back to the default), an unrecognised transactor throws: silently
+ * running on the network when the caller asked for local storage is the kind of
+ * mistake that only surfaces as a mysterious hang on a machine with no peers.
+ */
+function parseTransactor(raw: SqlValue): StrandTransactor | undefined {
+	if (raw === undefined || raw === null || raw === '') return undefined;
+	if (typeof raw !== 'string' || !STRAND_TRANSACTORS.includes(raw as StrandTransactor)) {
+		throw new Error(
+			`quereus-plugin-sereus: transactor must be one of ${STRAND_TRANSACTORS.join(', ')} (got ${JSON.stringify(raw)})`,
+		);
+	}
+	return raw as StrandTransactor;
+}
+
+/**
+ * Parse the plugin-loader SqlValue config into typed StrandConnectionOptions.
+ * Shared by the Node (`plugin.ts`) and browser (`plugin-browser.ts`) entries.
+ */
+export function parseConfig(config: Record<string, SqlValue>): StrandConnectionOptions {
+	const strandId = config.strand_id;
+	if (typeof strandId !== 'string' || !strandId) {
+		throw new Error('quereus-plugin-sereus: strand_id is required');
+	}
+
+	const bootstrapNodesRaw = config.bootstrap_nodes;
+	const bootstrapNodes = typeof bootstrapNodesRaw === 'string' && bootstrapNodesRaw
+		? bootstrapNodesRaw.split(',').map(s => s.trim()).filter(Boolean)
+		: [];
+
+	const schema = typeof config.schema === 'string' ? config.schema : undefined;
+	const sAppId = typeof config.sapp_id === 'string' ? config.sapp_id : 'unknown';
+	const sAppVersion = typeof config.sapp_version === 'string' ? config.sapp_version : '1.0.0';
+	const port = typeof config.port === 'number' ? config.port : 0;
+	const enableCache = config.enable_cache !== false && config.enable_cache !== 0;
+	const fretProfile = config.fret_profile === 'core' ? 'core' as const : 'edge' as const;
+
+	// Storage engine — see `StrandConnectionOptions.transactor`. Left out entirely
+	// when unset so `composeStrand` applies its own default.
+	const transactor = parseTransactor(config.transactor);
+
+	// NOTE: `parseConfig` reads the keys it knows and ignores every other key in
+	// the map — there is no allowlist, so a misspelled or retired setting (e.g.
+	// the `mode` this package used to carry) is silently dropped rather than
+	// rejected. Deliberate: the plugin loader hands through whatever the host's
+	// settings file holds.
+
+	// NOTE: persistent storage cannot ride a `Record<string, SqlValue>` — an
+	// `IRawStorage` is not an `SqlValue`. The Node loader (`plugin.ts`) reads the
+	// platform-only `storage_path` key directly and resolves it to a concrete
+	// `FileRawStorage`; it is intentionally NOT parsed into the typed options here.
+
+	return {
+		strandId,
+		bootstrapNodes,
+		schema,
+		sAppId,
+		sAppVersion,
+		port,
+		enableCache,
+		fretProfile,
+		...(transactor && { transactor }),
+	};
+}

package/src/plugin-browser.ts

@@ -1,29 +1,29 @@
-/**
- * Quereus plugin entry point for Sereus strand connections (browser/worker).
- *
- * This is the ESM-bundled counterpart to `./plugin`. Load via Quoomb-web's
- * plugin URL field or `plugins[].source` in `quoomb.config.json`. Defaults
- * storage to IndexedDB and uses WebSockets + circuit-relay transports.
- */
-
-import type { Database, SqlValue } from '@quereus/quereus';
-import { connectToStrandBrowser } from './connect-browser.js';
-import { parseConfig } from './parse-config.js';
-import type { SereusPluginResult } from './types.js';
-
-export { parseConfig };
-
-/**
- * Default export: Quereus plugin registration function (browser).
- *
- * Note: the `storage_path` setting is Node-only (it resolves to a filesystem
- * `FileRawStorage` in `./plugin`). The browser entry ignores it and defaults
- * storage to IndexedDB via `connectToStrandBrowser`.
- */
-export default async function register(
-	db: Database,
-	config: Record<string, SqlValue> = {},
-): Promise<SereusPluginResult> {
-	const options = parseConfig(config);
-	return connectToStrandBrowser(db, options);
-}
+/**
+ * Quereus plugin entry point for Sereus strand connections (browser/worker).
+ *
+ * This is the ESM-bundled counterpart to `./plugin`. Load via Quoomb-web's
+ * plugin URL field or `plugins[].source` in `quoomb.config.json`. Defaults
+ * storage to IndexedDB and uses WebSockets + circuit-relay transports.
+ */
+
+import type { Database, SqlValue } from '@quereus/quereus';
+import { connectToStrandBrowser } from './connect-browser.js';
+import { parseConfig } from './parse-config.js';
+import type { SereusPluginResult } from './types.js';
+
+export { parseConfig };
+
+/**
+ * Default export: Quereus plugin registration function (browser).
+ *
+ * Note: the `storage_path` setting is Node-only (it resolves to a filesystem
+ * `FileRawStorage` in `./plugin`). The browser entry ignores it and defaults
+ * storage to IndexedDB via `connectToStrandBrowser`.
+ */
+export default async function register(
+	db: Database,
+	config: Record<string, SqlValue> = {},
+): Promise<SereusPluginResult> {
+	const options = parseConfig(config);
+	return connectToStrandBrowser(db, options);
+}

package/src/plugin.ts

@@ -1,39 +1,39 @@
-/**
- * Quereus plugin entry point for Sereus strand connections (Node).
- *
- * Loaded via Quoomb's `.plugin install` or config file, or via `registerPlugin()`.
- * Parses SqlValue config and delegates to `connectToStrand`.
- *
- * Browser/Worker consumers should load `./plugin-browser` instead, which uses
- * the TCP-free libp2p entry and IndexedDB-backed default storage.
- */
-
-import type { Database, SqlValue } from '@quereus/quereus';
-import { connectToStrand } from './connect.js';
-import { parseConfig } from './parse-config.js';
-import type { SereusPluginResult } from './types.js';
-
-export { parseConfig };
-
-/**
- * Default export: Quereus plugin registration function.
- */
-export default async function register(
-	db: Database,
-	config: Record<string, SqlValue> = {},
-): Promise<SereusPluginResult> {
-	const options = parseConfig(config);
-
-	// `storage_path` is a Node-only loader convenience: a `Record<string, SqlValue>`
-	// cannot carry an `IRawStorage`, so the path is resolved to a concrete
-	// `FileRawStorage` here (not in the platform-agnostic `parseConfig`). The
-	// dynamic import keeps `@optimystic/db-p2p-storage-fs` (and its `node:fs`
-	// dependency) out of the browser/RN module graph.
-	const storagePath = config.storage_path;
-	if (typeof storagePath === 'string' && storagePath) {
-		const { FileRawStorage } = await import('@optimystic/db-p2p-storage-fs');
-		options.storage = new FileRawStorage(storagePath);
-	}
-
-	return connectToStrand(db, options);
-}
+/**
+ * Quereus plugin entry point for Sereus strand connections (Node).
+ *
+ * Loaded via Quoomb's `.plugin install` or config file, or via `registerPlugin()`.
+ * Parses SqlValue config and delegates to `connectToStrand`.
+ *
+ * Browser/Worker consumers should load `./plugin-browser` instead, which uses
+ * the TCP-free libp2p entry and IndexedDB-backed default storage.
+ */
+
+import type { Database, SqlValue } from '@quereus/quereus';
+import { connectToStrand } from './connect.js';
+import { parseConfig } from './parse-config.js';
+import type { SereusPluginResult } from './types.js';
+
+export { parseConfig };
+
+/**
+ * Default export: Quereus plugin registration function.
+ */
+export default async function register(
+	db: Database,
+	config: Record<string, SqlValue> = {},
+): Promise<SereusPluginResult> {
+	const options = parseConfig(config);
+
+	// `storage_path` is a Node-only loader convenience: a `Record<string, SqlValue>`
+	// cannot carry an `IRawStorage`, so the path is resolved to a concrete
+	// `FileRawStorage` here (not in the platform-agnostic `parseConfig`). The
+	// dynamic import keeps `@optimystic/db-p2p-storage-fs` (and its `node:fs`
+	// dependency) out of the browser/RN module graph.
+	const storagePath = config.storage_path;
+	if (typeof storagePath === 'string' && storagePath) {
+		const { FileRawStorage } = await import('@optimystic/db-p2p-storage-fs');
+		options.storage = new FileRawStorage(storagePath);
+	}
+
+	return connectToStrand(db, options);
+}