@serfab/quereus-plugin-sereus 0.10.0 → 0.12.0

package/src/connect-browser.ts

@@ -42,7 +42,7 @@ export async function connectToStrandBrowser(
 			const dbHandle = await openOptimysticWebDb(`sereus-strand-${strandId}`);
 			return new IndexedDBRawStorage(dbHandle);
 		},
-		async createNode({ networkName, bootstrapNodes, fretProfile, clusterSize, storage }) {
+		async createNode({ networkName, bootstrapNodes, fretProfile, clusterSize, clusterPolicy, storage }) {
 			return createLibp2pNode({
 				transports: [webSockets(), circuitRelayTransport()],
 				listenAddrs: [],
@@ -50,6 +50,7 @@ export async function connectToStrandBrowser(
 				networkName,
 				fretProfile,
 				clusterSize,
+				clusterPolicy,
 				...(storage && { storage }),
 			}) as Promise<Libp2p>;
 		},

package/src/connect.ts

@@ -20,7 +20,7 @@ export async function connectToStrand(
 		async registerCrypto(database) {
 			await registerPlugin(database, cryptoPlugin);
 		},
-		async createNode({ networkName, bootstrapNodes, fretProfile, port, clusterSize, storage }) {
+		async createNode({ networkName, bootstrapNodes, fretProfile, port, clusterSize, clusterPolicy, 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).
@@ -31,6 +31,7 @@ export async function connectToStrand(
 				networkName,
 				fretProfile,
 				clusterSize,
+				clusterPolicy,
 				...(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);
+}