syncorejs 0.2.2 → 0.2.4

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

@@ -9,11 +9,26 @@ import { SYNCORE_DEVTOOLS_MAX_SUPPORTED_PROTOCOL_VERSION, SYNCORE_DEVTOOLS_MIN_S
 //#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,
+* OPFS-backed blob storage when available, 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({
@@ -21,23 +36,27 @@ 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");
+	const storageNamespace = options.storageNamespace ?? options.databaseName ?? "syncore";
+	const storage = options.storage ?? (persistence.storageProtocol === "opfs" ? new BrowserFileStorageAdapter(persistence, storageNamespace) : new UnavailableBrowserStorageAdapter(BROWSER_STORAGE_UNAVAILABLE_REASON));
+	const runtimeCapabilities = createBrowserRuntimeCapabilities(persistence, storage, Boolean(options.storage));
 	const externalChangeSupport = createWebExternalChangeSupport({
 		databaseName: options.databaseName ?? "syncore",
 		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,
@@ -46,11 +65,13 @@ async function createWebSyncoreRuntime(options) {
 	].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(runtimeCapabilities)
 		};
 		if (appName) sinkOptions.appName = appName;
 		if (origin) sinkOptions.origin = origin;
@@ -63,7 +84,7 @@ 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,
@@ -75,18 +96,19 @@ async function createWebSyncoreRuntime(options) {
 		...externalChangeSupport.applier ? { externalChangeApplier: externalChangeSupport.applier } : {},
 		platform: options.platform ?? "browser",
 		...options.capabilities ? { capabilities: options.capabilities } : {},
+		runtimeCapabilities,
 		...resolvedDevtools ? { devtools: resolvedDevtools } : {},
 		...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,
 			admin: runtime.getAdmin()
 		}));
-		autoDevtools.attachSubscriptionHost(createDevtoolsSubscriptionHost({
+		resolvedDevtools.attachSubscriptionHost(createDevtoolsSubscriptionHost({
 			driver,
 			schema: options.schema,
 			functions: options.functions,
@@ -95,6 +117,21 @@ async function createWebSyncoreRuntime(options) {
 	}
 	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;
@@ -111,16 +148,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({
@@ -130,38 +179,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;
@@ -188,7 +306,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();
 		};
@@ -279,7 +399,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({
@@ -313,7 +435,51 @@ 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 createBrowserRuntimeCapabilities(persistence, storage, hasExplicitStorage) {
+	if (!hasExplicitStorage && persistence.storageProtocol !== "opfs") return { storage: {
+		available: false,
+		reason: BROWSER_STORAGE_UNAVAILABLE_REASON,
+		protocol: persistence.storageProtocol,
+		supportsRange: false
+	} };
+	return { storage: {
+		available: true,
+		protocol: hasExplicitStorage ? "custom" : persistence.storageProtocol,
+		...storage.supportsRange ? { supportsRange: storage.supportsRange() !== false } : {}
+	} };
+}
+function createBrowserDevtoolsCapabilities(runtimeCapabilities) {
+	const storageCapability = runtimeCapabilities?.storage;
+	const storageAvailable = storageCapability?.available !== false;
+	return {
+		sql: {
+			read: false,
+			write: false,
+			live: false,
+			reason: "SQL Console is not available for browser runtimes."
+		},
+		data: {
+			browse: true,
+			mutate: true,
+			importExport: true
+		},
+		storage: {
+			browse: storageAvailable,
+			download: storageAvailable,
+			readRange: storageCapability?.supportsRange === true,
+			delete: storageAvailable,
+			maxPreviewBytes: 8e4,
+			...!storageAvailable && storageCapability?.reason ? { reason: storageCapability.reason } : {}
+		},
+		scheduler: {
+			read: true,
+			edit: true
+		}
 	};
 }
 function shouldAutoConnectDevtools() {
@@ -431,6 +597,17 @@ async function resolvePersistedStorageScopeId(persistence, databaseLabel) {
 	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();
@@ -555,16 +732,33 @@ const SESSION_NOUNS = [
 	"Thunder",
 	"Drift"
 ];
+const BROWSER_STORAGE_UNAVAILABLE_REASON = "Browser file storage requires OPFS. IndexedDB is used for data only.";
 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 OPFS alongside 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: new BrowserFileStorageAdapter(persistence, "files"),
+* });
+* ```
 */
 var BrowserFileStorageAdapter = class {
+	persistence;
+	namespace;
 	constructor(persistence, namespace) {
 		this.persistence = persistence;
 		this.namespace = namespace;
+		if (persistence.storageProtocol !== "opfs") throw new Error(BROWSER_STORAGE_UNAVAILABLE_REASON);
 	}
 	async put(id, input) {
 		const bytes = normalizeBinary(input.data);
@@ -589,11 +783,18 @@ var BrowserFileStorageAdapter = class {
 	async read(id) {
 		return (await this.persistence.getFile(this.namespace, id))?.bytes ?? null;
 	}
+	supportsRange() {
+		return Boolean(this.persistence.getFileRange);
+	}
+	async readRange(id, offset, length) {
+		if (!this.persistence.getFileRange) return null;
+		return (await this.persistence.getFileRange(this.namespace, id, offset, length))?.bytes ?? null;
+	}
 	async delete(id) {
 		await this.persistence.deleteFile(this.namespace, id);
 	}
 	async list() {
-		return (await this.persistence.listFiles(this.namespace)).map((file) => ({
+		return (this.persistence.listFileMetadata ? await this.persistence.listFileMetadata(this.namespace) : await this.persistence.listFiles(this.namespace)).map((file) => ({
 			id: file.id,
 			path: `${this.persistence.storageProtocol}://${this.namespace}/${file.id}`,
 			size: file.size,
@@ -601,6 +802,27 @@ var BrowserFileStorageAdapter = class {
 		}));
 	}
 };
+var UnavailableBrowserStorageAdapter = class {
+	reason;
+	constructor(reason) {
+		this.reason = reason;
+	}
+	async put() {
+		throw new Error(this.reason);
+	}
+	async get() {
+		throw new Error(this.reason);
+	}
+	async read() {
+		throw new Error(this.reason);
+	}
+	supportsRange() {
+		return false;
+	}
+	async delete() {
+		throw new Error(this.reason);
+	}
+};
 function normalizeBinary(data) {
 	if (typeof data === "string") return new TextEncoder().encode(data);
 	if (data instanceof Uint8Array) return data;