syncorejs 0.2.1 → 0.2.3

package/dist/_vendor/platform-web/index.js

@@ -4,13 +4,31 @@ import { createWebPersistence, isOpfsAvailable } from "./persistence.js";
 import { BroadcastChannelExternalChangeSignal, SqlJsExternalChangeApplier, createDefaultSyncChannelName } from "./external-change.js";
 import { SqlJsDriver } from "./sqljs.js";
 import { SyncoreWebWorkerClient, attachWebWorkerRuntime, createManagedWebWorkerClient, createSyncoreWebWorkerClient, createWebWorkerClient } from "./worker.js";
-import { SyncoreRuntime, createDevtoolsCommandHandler, createDevtoolsSubscriptionHost } from "../core/index.mjs";
+import { SyncoreRuntime, createDevtoolsCommandHandler, createDevtoolsSubscriptionHost, generateId } from "../core/index.mjs";
+import { SYNCORE_DEVTOOLS_MAX_SUPPORTED_PROTOCOL_VERSION, SYNCORE_DEVTOOLS_MIN_SUPPORTED_PROTOCOL_VERSION, SYNCORE_DEVTOOLS_PROTOCOL_VERSION } from "../devtools-protocol/index.js";
 //#region src/index.ts
+const DEVTOOLS_META_NAMESPACE = "__syncore_devtools_meta__";
+const STORAGE_SCOPE_ID_PREFIX = "storage-scope";
+const DATA_SOURCE_ALIAS_PREFIX = "data-source-alias";
 /**
-* Create a full Syncore runtime directly in the browser.
+* Create a full Syncore runtime directly in the browser (main thread or
+* shared worker).
 *
-* Most React apps should use a worker runtime instead so queries and SQLite work
-* stay off the main thread.
+* This function sets up SQL.js, the OPFS/IndexedDB persistence layer, blob
+* storage, cross-tab change synchronisation via `BroadcastChannel`, and
+* auto-connects to the devtools server in development.
+*
+* @remarks
+* Most React/Svelte apps should run the runtime inside a `Worker` using
+* `createWebWorkerSyncoreRuntime()` instead, so that SQLite queries don’t
+* block the main thread. Use `createWebSyncoreRuntime` only when a worker is
+* not practical (e.g. in Electron renderer processes or certain test setups).
+*
+* ```ts
+* const runtime = await createWebSyncoreRuntime({ schema, functions });
+* await runtime.start();
+* const client = runtime.createClient();
+* ```
 */
 async function createWebSyncoreRuntime(options) {
 	const persistence = options.persistence ?? await createWebPersistence({
@@ -18,10 +36,11 @@ async function createWebSyncoreRuntime(options) {
 		...options.persistenceDatabaseName ? { indexedDbDatabaseName: options.persistenceDatabaseName } : {},
 		opfsRootDirectoryName: options.opfsRootDirectoryName ?? options.databaseName ?? "syncore"
 	});
+	const wasmUrl = options.wasmUrl ?? (options.locateFile || !isBrowserLikeRuntime() ? void 0 : await resolveDefaultWebWasmUrl());
 	const driver = options.driver ?? await SqlJsDriver.create({
 		databaseName: options.databaseName ?? "syncore",
 		persistence,
-		...options.wasmUrl ? { wasmUrl: options.wasmUrl } : {},
+		...wasmUrl ? { wasmUrl } : {},
 		...options.locateFile ? { locateFile: options.locateFile } : {}
 	});
 	const storage = options.storage ?? new BrowserFileStorageAdapter(persistence, options.storageNamespace ?? options.databaseName ?? "syncore");
@@ -30,22 +49,27 @@ async function createWebSyncoreRuntime(options) {
 		persistence,
 		driver
 	});
-	const appName = resolveWebAppName();
+	const appName = options.appName ?? resolveWebAppName();
 	const origin = resolveWebOrigin();
 	const sessionLabel = resolveWebSessionLabel();
 	const databaseLabel = options.databaseName ?? "syncore";
+	const storageScopeId = await resolvePersistedStorageScopeId(persistence, databaseLabel);
+	const dataSourceAlias = await resolvePersistedDataSourceAlias(persistence, databaseLabel);
 	const storageIdentity = [
 		origin ?? "unknown-origin",
 		persistence.storageProtocol,
-		databaseLabel
+		databaseLabel,
+		storageScopeId
 	].join("::");
 	const autoDevtools = options.devtools === void 0 && shouldAutoConnectDevtools() ? (() => {
 		const sinkOptions = {
-			url: resolveDefaultDevtoolsUrl(),
+			url: options.devtoolsUrl ?? resolveDefaultDevtoolsUrl(),
 			targetKind: "client",
 			storageProtocol: persistence.storageProtocol,
 			databaseLabel,
-			storageIdentity
+			dataSourceAlias,
+			storageIdentity,
+			capabilities: createBrowserDevtoolsCapabilities()
 		};
 		if (appName) sinkOptions.appName = appName;
 		if (origin) sinkOptions.origin = origin;
@@ -58,11 +82,12 @@ async function createWebSyncoreRuntime(options) {
 		sessionLabel,
 		appName,
 		origin,
-		devtoolsUrl: options.devtools && typeof options.devtools === "object" ? void 0 : resolveDefaultDevtoolsUrl()
+		devtoolsUrl: options.devtools && typeof options.devtools === "object" ? void 0 : options.devtoolsUrl ?? resolveDefaultDevtoolsUrl()
 	});
 	const runtime = new SyncoreRuntime({
 		schema: options.schema,
 		functions: options.functions,
+		...options.components ? { components: options.components } : {},
 		driver,
 		storage,
 		externalChangeSignal: externalChangeSupport.signal,
@@ -70,26 +95,40 @@ async function createWebSyncoreRuntime(options) {
 		platform: options.platform ?? "browser",
 		...options.capabilities ? { capabilities: options.capabilities } : {},
 		...resolvedDevtools ? { devtools: resolvedDevtools } : {},
-		...options.experimentalPlugins ? { experimentalPlugins: options.experimentalPlugins } : {},
 		...options.scheduler ? { scheduler: options.scheduler } : {}
 	});
-	if (autoDevtools) {
-		autoDevtools.attachRuntime(runtime);
-		autoDevtools.attachCommandHandler(createDevtoolsCommandHandler({
+	if (isAttachableBrowserDevtoolsSink(resolvedDevtools)) {
+		resolvedDevtools.attachRuntime(runtime);
+		resolvedDevtools.attachCommandHandler(createDevtoolsCommandHandler({
 			driver,
 			schema: options.schema,
 			functions: options.functions,
-			runtime
+			admin: runtime.getAdmin()
 		}));
-		autoDevtools.attachSubscriptionHost(createDevtoolsSubscriptionHost({
+		resolvedDevtools.attachSubscriptionHost(createDevtoolsSubscriptionHost({
 			driver,
 			schema: options.schema,
 			functions: options.functions,
-			runtime
+			admin: runtime.getAdmin()
 		}));
 	}
 	return runtime;
 }
+function isAttachableBrowserDevtoolsSink(sink) {
+	return !!sink && typeof sink.attachRuntime === "function" && typeof sink.attachCommandHandler === "function" && typeof sink.attachSubscriptionHost === "function";
+}
+/**
+* Build a {@link WebExternalChangeSupport} bundle for a given database and
+* persistence layer.
+*
+* Creates a `BroadcastChannel`-based signal so that all tabs sharing the same
+* `databaseName` are notified when a mutation commits. When `driver` is a
+* `SqlJsDriver` (i.e. an in-memory database), an `applier` is also created so
+* the local database can be updated from the latest on-disk snapshot.
+*
+* Called automatically by `createWebSyncoreRuntime`. Exposed for advanced use
+* cases such as the Expo web adapter.
+*/
 function createWebExternalChangeSupport(options) {
 	const signal = new BroadcastChannelExternalChangeSignal({ channelName: createDefaultSyncChannelName(options.databaseName) });
 	const sqlDriver = options.driver instanceof SqlJsDriver ? options.driver : void 0;
@@ -106,16 +145,28 @@ function createWebExternalChangeSupport(options) {
 		})
 	};
 }
+/**
+* Build a {@link WebExternalChangeSupport} bundle for an Expo app running on
+* the web platform.
+*
+* Behaves identically to {@link createWebExternalChangeSupport} but accepts
+* the same options shape used by `createExpoSyncoreRuntime`, making it easy
+* to share config when bootstrapping an Expo web runtime.\
+*
+* Called internally by the Expo platform adapter. Use directly only when
+* constructing the runtime outside of `createExpoSyncoreRuntime`.
+*/
 async function createExpoWebExternalChangeSupport(options) {
 	const persistence = await createWebPersistence({
 		...options.persistenceMode ? { mode: options.persistenceMode } : {},
 		...options.persistenceDatabaseName ? { indexedDbDatabaseName: options.persistenceDatabaseName } : {},
 		opfsRootDirectoryName: options.opfsRootDirectoryName ?? options.databaseName
 	});
+	const wasmUrl = options.wasmUrl ?? (options.locateFile || !isBrowserLikeRuntime() ? void 0 : await resolveDefaultWebWasmUrl());
 	const driver = await SqlJsDriver.create({
 		databaseName: options.databaseName,
 		persistence,
-		...options.wasmUrl ? { wasmUrl: options.wasmUrl } : {},
+		...wasmUrl ? { wasmUrl } : {},
 		...options.locateFile ? { locateFile: options.locateFile } : {}
 	});
 	return createWebExternalChangeSupport({
@@ -125,38 +176,107 @@ async function createExpoWebExternalChangeSupport(options) {
 	});
 }
 /**
-* Attach a Syncore runtime to a browser Worker endpoint.
+* Start a Syncore runtime inside a browser `Worker` and wire it to the
+* worker’s own message endpoint.
+*
+* This is the function you call **inside your worker file** (`syncore.worker.ts`).
+* It creates the full runtime (SQL.js + OPFS + BroadcastChannel) in the worker
+* context and begins listening for messages from the main-thread client.
+*
+* ```ts
+* // syncore.worker.ts
+* import { createWebWorkerRuntime } from "syncorejs/browser";
+* import schema from "./syncore/schema";
+* import { functions } from "./syncore/_generated/functions";
+*
+* void createWebWorkerRuntime({
+*   schema,
+*   functions,
+*   endpoint: self as unknown as SyncoreWorkerMessageEndpoint,
+* });
+* ```
+*
+* On the main thread, connect with `createManagedWebWorkerClient()` or
+* `SyncoreNextProvider` (Next.js).
 */
 function createWebWorkerRuntime(options) {
 	return attachWebWorkerRuntime({
 		endpoint: options.endpoint,
-		createRuntime: () => createWebSyncoreRuntime(options)
+		createRuntime: () => createWebSyncoreRuntime({
+			...options,
+			platform: options.platform ?? "browser-worker"
+		})
 	});
 }
 /**
-* Attach a Syncore runtime to a browser Worker endpoint.
+* Alias of {@link createWebWorkerRuntime} for the `syncorejs/browser` surface.
+* @see createWebWorkerRuntime
 */
 function createBrowserWorkerRuntime(options) {
 	return createWebWorkerRuntime(options);
 }
 /**
-* Create a client directly from a browser Syncore runtime.
+* Create a same-process Syncore client from a started browser runtime.
+*
+* Use this when the runtime lives in the same context as the client (e.g.
+* main-thread runtime in an Electron renderer or a test harness). For
+* worker-based setups use `createManagedWebWorkerClient()` instead, which
+* communicates with the worker over `postMessage`.
+*
+* ```ts
+* const runtime = await createWebSyncoreRuntime({ schema, functions });
+* await runtime.start();
+* const client = createWebSyncoreClient(runtime);
+* ```
 */
 function createWebSyncoreClient(runtime) {
 	return runtime.createClient();
 }
 /**
-* Create a full Syncore runtime directly in the browser.
+* Alias of {@link createWebSyncoreRuntime} for the `syncorejs/browser` surface.
+* @see createWebSyncoreRuntime
 */
 function createBrowserSyncoreRuntime(options) {
 	return createWebSyncoreRuntime(options);
 }
 /**
-* Create a client directly from a browser Syncore runtime.
+* Alias of {@link createWebSyncoreClient} for the `syncorejs/browser` surface.
+* @see createWebSyncoreClient
 */
 function createBrowserSyncoreClient(runtime) {
 	return createWebSyncoreClient(runtime);
 }
+async function resolveDefaultWebWasmUrl() {
+	try {
+		return (await import("./web-sqljs-wasm.js")).resolveDefaultWebSqlJsWasmUrl();
+	} catch (error) {
+		if (!isBrowserLikeRuntime()) return;
+		throw new Error("Syncore could not resolve the default sql.js WebAssembly asset. Pass wasmUrl or locateFile to createWebSyncoreRuntime/createBrowserWorkerRuntime for this bundler.", { cause: error });
+	}
+}
+function isBrowserLikeRuntime() {
+	return typeof window !== "undefined" || globalThis.WorkerGlobalScope !== void 0;
+}
+/**
+* Create a WebSocket-based devtools sink that connects to the Syncore devtools
+* server and forwards runtime events in real time.
+*
+* The sink auto-reconnects if the connection drops (e.g. while the devtools
+* dashboard is restarting) and buffers events that arrive before the socket is
+* open.
+*
+* In most cases you do not need to call this directly — `createWebSyncoreRuntime`
+* creates and attaches the sink automatically when `devtools` is omitted and the
+* page is served from a local/private hostname.
+*
+* ```ts
+* const sink = createBrowserWebSocketDevtoolsSink({
+*   url: "ws://127.0.0.1:4311",
+*   appName: "My App",
+* });
+* const runtime = await createWebSyncoreRuntime({ schema, functions, devtools: sink });
+* ```
+*/
 function createBrowserWebSocketDevtoolsSink(options) {
 	let socket;
 	let disposed = false;
@@ -172,6 +292,9 @@ function createBrowserWebSocketDevtoolsSink(options) {
 		socket.onopen = () => {
 			if (latestHello) sendNow({
 				type: "hello",
+				protocolVersion: SYNCORE_DEVTOOLS_PROTOCOL_VERSION,
+				minSupportedProtocolVersion: SYNCORE_DEVTOOLS_MIN_SUPPORTED_PROTOCOL_VERSION,
+				maxSupportedProtocolVersion: SYNCORE_DEVTOOLS_MAX_SUPPORTED_PROTOCOL_VERSION,
 				runtimeId: latestHello.runtimeId,
 				platform: latestHello.platform,
 				...options.appName ? { appName: options.appName } : {},
@@ -180,7 +303,9 @@ function createBrowserWebSocketDevtoolsSink(options) {
 				...options.targetKind ? { targetKind: options.targetKind } : {},
 				...options.storageProtocol ? { storageProtocol: options.storageProtocol } : {},
 				...options.databaseLabel ? { databaseLabel: options.databaseLabel } : {},
-				...options.storageIdentity ? { storageIdentity: options.storageIdentity } : {}
+				...options.dataSourceAlias ? { dataSourceAlias: options.dataSourceAlias } : {},
+				...options.storageIdentity ? { storageIdentity: options.storageIdentity } : {},
+				capabilities: options.capabilities ?? createBrowserDevtoolsCapabilities()
 			});
 			flushPendingMessages();
 		};
@@ -260,6 +385,9 @@ function createBrowserWebSocketDevtoolsSink(options) {
 				};
 				send({
 					type: "hello",
+					protocolVersion: SYNCORE_DEVTOOLS_PROTOCOL_VERSION,
+					minSupportedProtocolVersion: SYNCORE_DEVTOOLS_MIN_SUPPORTED_PROTOCOL_VERSION,
+					maxSupportedProtocolVersion: SYNCORE_DEVTOOLS_MAX_SUPPORTED_PROTOCOL_VERSION,
 					runtimeId: event.runtimeId,
 					platform: event.platform,
 					...options.appName ? { appName: options.appName } : {},
@@ -268,7 +396,9 @@ function createBrowserWebSocketDevtoolsSink(options) {
 					...options.targetKind ? { targetKind: options.targetKind } : {},
 					...options.storageProtocol ? { storageProtocol: options.storageProtocol } : {},
 					...options.databaseLabel ? { databaseLabel: options.databaseLabel } : {},
-					...options.storageIdentity ? { storageIdentity: options.storageIdentity } : {}
+					...options.dataSourceAlias ? { dataSourceAlias: options.dataSourceAlias } : {},
+					...options.storageIdentity ? { storageIdentity: options.storageIdentity } : {},
+					capabilities: options.capabilities ?? createBrowserDevtoolsCapabilities()
 				});
 			}
 			send({
@@ -277,7 +407,7 @@ function createBrowserWebSocketDevtoolsSink(options) {
 			});
 		},
 		attachRuntime(runtime) {
-			getSummary = () => withRuntimeSummaryMeta(runtime.getRuntimeSummary(), options);
+			getSummary = () => withRuntimeSummaryMeta(runtime.getAdmin().getRuntimeSummary(), options);
 		},
 		attachCommandHandler(handler) {
 			onCommand = handler;
@@ -302,7 +432,28 @@ function withRuntimeSummaryMeta(summary, options) {
 		...options.targetKind ? { targetKind: options.targetKind } : {},
 		...options.storageProtocol ? { storageProtocol: options.storageProtocol } : {},
 		...options.databaseLabel ? { databaseLabel: options.databaseLabel } : {},
-		...options.storageIdentity ? { storageIdentity: options.storageIdentity } : {}
+		...options.dataSourceAlias ? { dataSourceAlias: options.dataSourceAlias } : {},
+		...options.storageIdentity ? { storageIdentity: options.storageIdentity } : {},
+		capabilities: options.capabilities ?? createBrowserDevtoolsCapabilities()
+	};
+}
+function createBrowserDevtoolsCapabilities() {
+	return {
+		sql: {
+			read: false,
+			write: false,
+			live: false,
+			reason: "SQL Console is not available for browser runtimes."
+		},
+		data: {
+			browse: true,
+			mutate: true,
+			importExport: true
+		},
+		scheduler: {
+			read: true,
+			edit: true
+		}
 	};
 }
 function shouldAutoConnectDevtools() {
@@ -388,12 +539,49 @@ function resolveWebSessionLabel() {
 				globalThis.localStorage?.setItem(STORAGE_KEY, uniqueName);
 			} catch {}
 		}
-		const browser = navigator.userAgent.includes("Firefox") ? "Firefox" : navigator.userAgent.includes("Chrome") ? "Chrome" : navigator.userAgent.includes("Safari") ? "Safari" : "Browser";
+		const browser = resolveBrowserName(navigator);
 		return `${uniqueName} (${browser})`;
 	} catch {
 		return;
 	}
 }
+function resolveBrowserName(nav) {
+	const brands = nav.userAgentData?.brands?.map((entry) => entry.brand) ?? [];
+	if (brands.some((brand) => /microsoft edge/i.test(brand))) return "Edge";
+	if (brands.some((brand) => /firefox/i.test(brand))) return "Firefox";
+	if (brands.some((brand) => /opera/i.test(brand))) return "Opera";
+	if (brands.some((brand) => /chrome|chromium/i.test(brand))) return "Chrome";
+	if (brands.some((brand) => /safari/i.test(brand))) return "Safari";
+	const userAgent = nav.userAgent;
+	if (/Firefox\//i.test(userAgent)) return "Firefox";
+	if (/Edg\//i.test(userAgent)) return "Edge";
+	if (/OPR\/|Opera/i.test(userAgent)) return "Opera";
+	if (/Chrome\/|CriOS\//i.test(userAgent)) return "Chrome";
+	if (/Safari\//i.test(userAgent)) return "Safari";
+	return "Browser";
+}
+async function resolvePersistedStorageScopeId(persistence, databaseLabel) {
+	const id = `${STORAGE_SCOPE_ID_PREFIX}:${databaseLabel}`;
+	const existing = await persistence.getFile(DEVTOOLS_META_NAMESPACE, id);
+	if (existing) {
+		const value = new TextDecoder().decode(existing.bytes).trim();
+		if (value.length > 0) return value;
+	}
+	const nextValue = generateId();
+	await persistence.putFile(DEVTOOLS_META_NAMESPACE, id, new TextEncoder().encode(nextValue), "text/plain");
+	return nextValue;
+}
+async function resolvePersistedDataSourceAlias(persistence, databaseLabel) {
+	const id = `${DATA_SOURCE_ALIAS_PREFIX}:${databaseLabel}`;
+	const existing = await persistence.getFile(DEVTOOLS_META_NAMESPACE, id);
+	if (existing) {
+		const value = new TextDecoder().decode(existing.bytes).trim();
+		if (value.length > 0) return value;
+	}
+	const nextValue = generateUniqueSessionName();
+	await persistence.putFile(DEVTOOLS_META_NAMESPACE, id, new TextEncoder().encode(nextValue), "text/plain");
+	return nextValue;
+}
 function announceBrowserSession(options) {
 	if (!options.enabled || !options.sessionLabel) return;
 	const announcedSessions = getAnnouncedBrowserSessions();
@@ -522,9 +710,24 @@ function generateUniqueSessionName() {
 	return `${SESSION_ADJECTIVES[Math.floor(Math.random() * SESSION_ADJECTIVES.length)]} ${SESSION_NOUNS[Math.floor(Math.random() * SESSION_NOUNS.length)]}`;
 }
 /**
-* Browser file/blob storage built on top of Syncore web persistence.
+* Browser file/blob storage adapter backed by `SyncoreWebPersistence`.
+*
+* Stores binary blobs (images, documents, etc.) in the same OPFS or
+* IndexedDB store as the SQLite database. Pass an instance to
+* `CreateWebRuntimeOptions.storage` to enable Syncore's Storage API
+* (`ctx.storage.put`, `ctx.storage.get`, etc.) in browser functions.
+*
+* ```ts
+* const runtime = await createWebSyncoreRuntime({
+*   schema,
+*   functions,
+*   storage: (persistence) => new BrowserFileStorageAdapter(persistence, "files"),
+* });
+* ```
 */
 var BrowserFileStorageAdapter = class {
+	persistence;
+	namespace;
 	constructor(persistence, namespace) {
 		this.persistence = persistence;
 		this.namespace = namespace;