@spooky-sync/client-solid2 0.0.1-canary.200

package/dist/index.cjs

@@ -0,0 +1,903 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _spooky_sync_core = require("@spooky-sync/core");
+let surrealdb = require("surrealdb");
+let solid_js = require("solid-js");
+
+//#region src/lib/conflate.ts
+/**
+* Latest-wins async iterable over a subscribe-callback source.
+*
+* Bridges spooky's push-callback subscriptions into the AsyncIterable shape
+* Solid 2 computations consume natively. Each spooky emission is a full result
+* set, so intermediate values are droppable: only the newest unconsumed value
+* is buffered, and a pending pull resolves with it immediately.
+*
+* Teardown contract (probed in rc-semantics.test.ts): Solid 2 does NOT
+* terminate a superseded/disposed computation's async generator — no
+* `return()`, no `finally`. Consumers MUST call `it.return()` themselves from
+* an `onCleanup` registered synchronously in the compute scope. `return()`
+* unsubscribes (awaiting the unsubscribe if the subscribe returned a promise,
+* as `sp00ky.subscribe` does) and resolves any parked pull as done.
+*/
+function conflate(subscribe) {
+	return { [Symbol.asyncIterator]() {
+		let buffered;
+		let resolveNext;
+		let done = false;
+		const unsubMaybe = subscribe((v) => {
+			if (done) return;
+			if (resolveNext) {
+				const r = resolveNext;
+				resolveNext = void 0;
+				r({
+					value: v,
+					done: false
+				});
+			} else buffered = { v };
+		});
+		const finish = () => {
+			if (done) return;
+			done = true;
+			buffered = void 0;
+			Promise.resolve(unsubMaybe).then((unsub) => unsub()).catch(() => {});
+			if (resolveNext) {
+				const r = resolveNext;
+				resolveNext = void 0;
+				r({
+					value: void 0,
+					done: true
+				});
+			}
+		};
+		return {
+			next() {
+				if (done) return Promise.resolve({
+					value: void 0,
+					done: true
+				});
+				if (buffered) {
+					const v = buffered.v;
+					buffered = void 0;
+					return Promise.resolve({
+						value: v,
+						done: false
+					});
+				}
+				return new Promise((r) => resolveNext = r);
+			},
+			return() {
+				finish();
+				return Promise.resolve({
+					value: void 0,
+					done: true
+				});
+			},
+			throw(e) {
+				finish();
+				return Promise.reject(e);
+			}
+		};
+	} };
+}
+
+//#endregion
+//#region src/lib/from-subscription.ts
+/**
+* Reactive view over a spooky subscribe-callback API.
+*
+* The memo's async generator pulls from a conflated (latest-wins) iterator;
+* `initial` is committed as the memo's `loadingValue`, so the accessor is
+* readable synchronously from birth and never suspends. Spooky's subscribe
+* APIs fire immediately with the current value, so the real value lands within
+* a tick of the first read.
+*
+* Teardown is manual by contract (see conflate.ts): onCleanup terminates the
+* iterator, which unsubscribes.
+*/
+function fromSubscription(subscribe, initial) {
+	return (0, solid_js.createMemo)(async function* () {
+		const it = conflate(subscribe)[Symbol.asyncIterator]();
+		(0, solid_js.onCleanup)(() => void it.return?.());
+		while (true) {
+			const r = await it.next();
+			if (r.done) break;
+			yield r.value;
+		}
+	}, { loadingValue: initial });
+}
+
+//#endregion
+//#region src/lib/context.ts
+const Sp00kyContext = (0, solid_js.createContext)();
+function useDb() {
+	try {
+		return (0, solid_js.useContext)(Sp00kyContext);
+	} catch {
+		throw new Error("useDb must be used within a <Sp00kyProvider>. Wrap your app in <Sp00kyProvider config={...}>.");
+	}
+}
+/**
+* Count of locally-committed mutations not yet acknowledged by the server.
+* Drive an "unsaved changes" indicator off this.
+*/
+function usePendingMutations() {
+	const db = useDb();
+	return fromSubscription((cb) => db.subscribeToPendingMutations(cb), db.pendingMutationCount);
+}
+
+//#endregion
+//#region src/lib/create-query.ts
+function createQuery(dbOrQuery, queryOrOptions, maybeOptions) {
+	let db;
+	let finalQuery;
+	let options;
+	if (dbOrQuery instanceof SyncedDb) {
+		db = dbOrQuery;
+		finalQuery = queryOrOptions;
+		options = maybeOptions;
+	} else {
+		db = useDb();
+		finalQuery = dbOrQuery;
+		options = queryOrOptions;
+	}
+	const sp00ky = db.getSp00ky();
+	const [error, setError] = (0, solid_js.createSignal)(void 0, { ownedWrite: true });
+	const [isFetched, setIsFetched] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	const [isFetching, setIsFetching] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	let activeHash;
+	const store = (0, solid_js.createProjection)(async function* () {
+		const enabled = options?.enabled?.() ?? true;
+		const query = typeof finalQuery === "function" ? finalQuery() : finalQuery;
+		if (!enabled || !query) {
+			setIsFetched(false);
+			setError(void 0);
+			return;
+		}
+		setIsFetched(false);
+		setError(void 0);
+		const iterators = [];
+		const cleanups = [];
+		(0, solid_js.onCleanup)(() => {
+			for (const it of iterators) it.return?.();
+			for (const c of cleanups) c();
+		});
+		try {
+			/**
+			* Registration can fail — the canonical case is the SSP answering 503
+			* NOT_READY while it bootstraps. Surface it as `error()` instead of
+			* throwing into the graph: the sync scheduler retries the
+			* registration underneath, so a transient failure still recovers, and
+			* a spinner driven by `isLoading()` resolves via `error()`.
+			*/
+			const { hash } = await query.run();
+			activeHash = hash;
+			cleanups.push(sp00ky.subscribeQueryStatus(hash, (status) => setIsFetching(status === "fetching"), { immediate: true }));
+			const it = conflate((cb) => sp00ky.subscribe(hash, cb, { immediate: true }))[Symbol.asyncIterator]();
+			iterators.push(it);
+			let isFirstCall = true;
+			while (true) {
+				const r = await it.next();
+				if (r.done) break;
+				const e = r.value;
+				const queryData = query.isOne ? e[0] ?? null : e;
+				const hasData = query.isOne ? queryData !== null && queryData !== void 0 : e.length > 0;
+				if (!isFirstCall || hasData) setIsFetched(true);
+				isFirstCall = false;
+				const t0 = performance.now();
+				yield { value: queryData };
+				sp00ky.reportFrontendTiming(hash, performance.now() - t0);
+			}
+		} catch (err) {
+			setError(err instanceof Error ? err : new Error(String(err)));
+		}
+	}, { value: null }, {
+		key: "id",
+		seedLoadingValue: true
+	});
+	const emptyList = [];
+	const data = () => {
+		const v = store.value;
+		if (v === null || v === void 0) {
+			const query = typeof finalQuery === "function" ? finalQuery() : finalQuery;
+			if (query && !query.isOne) return emptyList;
+		}
+		return v;
+	};
+	const readyGate = (0, solid_js.createMemo)(async () => {
+		if (isFetched() || error()) return true;
+		await new Promise(() => {});
+		return true;
+	});
+	const ready = () => {
+		readyGate();
+		return data();
+	};
+	(0, solid_js.onCleanup)(() => {
+		if (options?.deregisterOnCleanup && activeHash) sp00ky.deregisterQuery(activeHash);
+	});
+	const isLoading = () => !isFetched() && error() === void 0;
+	const isSettled = () => isFetched() && !isFetching();
+	return {
+		data,
+		ready,
+		error,
+		isLoading,
+		isFetching,
+		isSettled
+	};
+}
+/** @deprecated Renamed `createQuery` in the Solid 2 binding. */
+const useQuery = createQuery;
+
+//#endregion
+//#region src/lib/create-preload.ts
+/**
+* Reactive, fire-and-forget prewarm. Resolves the query (calling it if it's a
+* function so it tracks reactive deps), dedupes on the query's stable identity
+* hash, and warms it into the local cache via `db.preload`. No subscription and
+* no cleanup: preload registers nothing that needs tearing down.
+*
+* Typical use: inside a list row, preload the detail query the user is likely
+* to open next, so navigation paints from cache instead of the network.
+*/
+function createPreload(dbOrQuery, queryOrOptions, maybeOptions) {
+	let db;
+	let finalQuery;
+	let options;
+	if (dbOrQuery instanceof SyncedDb) {
+		db = dbOrQuery;
+		finalQuery = queryOrOptions;
+		options = maybeOptions;
+	} else {
+		db = useDb();
+		finalQuery = dbOrQuery;
+		options = queryOrOptions;
+	}
+	let prevHash;
+	(0, solid_js.createEffect)(() => {
+		if (!(options?.enabled?.() ?? true)) return void 0;
+		const query = typeof finalQuery === "function" ? finalQuery() : finalQuery;
+		if (!query) return void 0;
+		if (query.hash === prevHash) return void 0;
+		prevHash = query.hash;
+		return query;
+	}, (query) => {
+		if (!query) return;
+		db.getSp00ky().preload(query, {
+			refresh: options?.refresh,
+			staleTime: options?.staleTime
+		});
+	});
+}
+
+//#endregion
+//#region src/lib/use-sync-status.ts
+/**
+* Observe sync health for a "can't reach the server" banner / indicator.
+*
+* Backed by `db.subscribeToSyncHealth`. Individual sync failures (a transient
+* remote 500 on query registration, a dropped socket) are absorbed by the
+* retry and never flip this; `isDegraded()` only goes true once failures
+* persist for the configured number of consecutive rounds (sp00ky core config
+* `syncHealth.degradeAfterConsecutiveFailures`, default 3), and flips back on
+* the next successful round. Must be used within a `<Sp00kyProvider>`.
+*/
+function useSyncStatus() {
+	const db = useDb();
+	const health = fromSubscription((cb) => db.subscribeToSyncHealth(cb), db.syncHealth);
+	return {
+		health,
+		status: () => health().status,
+		isHealthy: () => health().status === "healthy",
+		isDegraded: () => health().status === "degraded",
+		everConnected: () => health().everConnected,
+		isOffline: () => health().status === "degraded" && health().everConnected,
+		connection: () => health().connection,
+		isReconnecting: () => health().connection === "reconnecting"
+	};
+}
+
+//#endregion
+//#region src/lib/use-storage-status.ts
+/**
+* Observe how durable the LOCAL cache is, for a "no local storage" warning.
+*
+* Under `localEngine: 'sqlite'` with `store: 'indexeddb'` the durable store is
+* the OPFS SAHPool VFS, and only ONE client per bucket can hold it open: a
+* second tab of the same app cannot get it and runs in memory instead (the
+* engine retries first, so a closing tab's lock is usually waited out). Must be
+* used within a `<Sp00kyProvider>`.
+*/
+function useStorageStatus() {
+	const db = useDb();
+	const health = fromSubscription((cb) => db.subscribeToStorageHealth(cb), db.storageHealth);
+	return {
+		health,
+		status: () => health().status,
+		isPersistent: () => health().status === "persistent",
+		isMemoryFallback: () => health().fallback
+	};
+}
+
+//#endregion
+//#region src/lib/use-crdt-field.ts
+function useCrdtField(table, recordId, field, fallbackText) {
+	const db = useDb();
+	const [crdtField, setCrdtField] = (0, solid_js.createSignal)(null, { ownedWrite: true });
+	(0, solid_js.createEffect)(() => recordId(), (id) => {
+		if (!id) {
+			setCrdtField(null);
+			return;
+		}
+		const sp00ky = db.getSp00ky();
+		let superseded = false;
+		const text = fallbackText?.();
+		sp00ky.openCrdtField(table, id, field, text).then((cf) => {
+			if (!superseded) setCrdtField(cf);
+			else sp00ky.closeCrdtField(table, id, field);
+		}).catch((err) => {
+			console.error(`[useCrdtField] Failed to open CRDT field ${table}.${field} on ${id}:`, err);
+		});
+		return () => {
+			superseded = true;
+			if (crdtField()) {
+				sp00ky.closeCrdtField(table, id, field);
+				setCrdtField(null);
+			}
+		};
+	});
+	return crdtField;
+}
+
+//#endregion
+//#region src/lib/use-feature-flag.ts
+/**
+* Subscribe to a feature flag for the currently authenticated user.
+*
+* Returns three Solid accessors that update reactively whenever the
+* server-materialized assignment in `_00_user_feature` changes. Backed by
+* the same SSP + sync pipeline that powers `createQuery`, so toggling a flag
+* via `spky flag enable <key>` propagates to the UI without a refresh.
+*
+* `enabled()` is `true` when the resolved variant exists and is not 'off'.
+* For multi-variant flags, prefer `variant()` directly.
+*/
+function useFeatureFlag(key, options) {
+	const handle = useDb().getSp00ky().feature(key, options);
+	(0, solid_js.onCleanup)(() => handle.close());
+	const state = fromSubscription((cb) => handle.subscribe((s) => cb({
+		variant: s.variant ?? options?.fallback,
+		payload: s.payload
+	})), {
+		variant: handle.variant(),
+		payload: handle.payload()
+	});
+	return {
+		variant: () => state().variant,
+		payload: () => state().payload,
+		enabled: () => {
+			const v = state().variant;
+			return v !== void 0 && v !== "off";
+		}
+	};
+}
+
+//#endregion
+//#region src/lib/use-app-release.ts
+async function reloadForSnapshot(snapshot) {
+	if (typeof window === "undefined") return;
+	if (snapshot.cacheBust) try {
+		if (window.caches) {
+			const keys = await window.caches.keys();
+			await Promise.all(keys.map((k) => window.caches.delete(k)));
+		}
+		if (navigator.serviceWorker) {
+			const regs = await navigator.serviceWorker.getRegistrations();
+			for (const r of regs) r.update().catch(() => {});
+		}
+		window.location.href = window.location.pathname + "?cb=" + Date.now();
+		return;
+	} catch {}
+	window.location.reload();
+}
+/**
+* Observe the app's announced release (`_00_app_release:<app>`, written by
+* `spky deploy` / `spky release`) and compare it against the running build.
+*
+* Typical use: mount a small "new version available — Reload" notification
+* gated on `updateAvailable()`, auto-invoking `reload()` when `mandatory()`
+* (guard the auto path against reload loops with a per-version marker, since
+* a client can reload while the deploy is still rolling out and land on the
+* old bundle again).
+*/
+function useAppRelease(options) {
+	const handle = useDb().getSp00ky().appRelease(options.app, { ttl: options.ttl });
+	(0, solid_js.onCleanup)(() => handle.close());
+	const snapshot = fromSubscription((cb) => handle.subscribe(cb), handle.snapshot());
+	const updateAvailable = () => (0, _spooky_sync_core.semverGt)(snapshot().version, options.currentVersion);
+	return {
+		latestVersion: () => snapshot().version,
+		updateAvailable,
+		mandatory: () => updateAvailable() && snapshot().mandatory,
+		cacheBust: () => snapshot().cacheBust,
+		reload: () => reloadForSnapshot(snapshot())
+	};
+}
+
+//#endregion
+//#region src/lib/use-file-upload.ts
+function useFileUpload(dbOrBucketName, maybeBucketName) {
+	let db;
+	let bucketName;
+	if (typeof dbOrBucketName === "string") {
+		db = useDb();
+		bucketName = dbOrBucketName;
+	} else {
+		db = dbOrBucketName;
+		bucketName = maybeBucketName;
+	}
+	const [isUploading, setIsUploading] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	const [error, setError] = (0, solid_js.createSignal)(null, { ownedWrite: true });
+	const objectUrls = [];
+	(0, solid_js.onCleanup)(() => {
+		for (const url of objectUrls) URL.revokeObjectURL(url);
+	});
+	const clearError = () => setError(null);
+	const validate = (file) => {
+		const config = db.getBucketConfig(bucketName);
+		if (!config) return;
+		if (config.maxSize !== null && config.maxSize !== void 0 && file.size > config.maxSize) {
+			const maxMB = (config.maxSize / (1024 * 1024)).toFixed(1);
+			throw new Error(`File exceeds maximum size of ${maxMB} MB.`);
+		}
+		if (config.allowedExtensions && config.allowedExtensions.length > 0) {
+			const fileName = file.name;
+			if (fileName) {
+				const ext = fileName.split(".").pop()?.toLowerCase();
+				if (!ext || !config.allowedExtensions.includes(ext)) throw new Error(`File type not allowed. Accepted: ${config.allowedExtensions.join(", ")}.`);
+			}
+		}
+	};
+	const upload = async (path, file, options) => {
+		setError(null);
+		try {
+			validate(file);
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+			return;
+		}
+		setIsUploading(true);
+		try {
+			const bytes = await (0, _spooky_sync_core.fileToUint8Array)(file);
+			return await db.bucket(bucketName).put(path, bytes, options);
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+		} finally {
+			setIsUploading(false);
+		}
+	};
+	const download = async (path) => {
+		setError(null);
+		try {
+			const content = await db.bucket(bucketName).get(path);
+			if (!content) return null;
+			const objectUrl = URL.createObjectURL(new Blob([content]));
+			objectUrls.push(objectUrl);
+			return objectUrl;
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+			return null;
+		}
+	};
+	const remove = async (path) => {
+		setError(null);
+		try {
+			await db.bucket(bucketName).delete(path);
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+		}
+	};
+	const exists = async (path) => {
+		setError(null);
+		try {
+			return await db.bucket(bucketName).exists(path);
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+			return false;
+		}
+	};
+	return {
+		isUploading,
+		error,
+		clearError,
+		upload,
+		download,
+		remove,
+		exists
+	};
+}
+
+//#endregion
+//#region src/lib/use-download-file.ts
+function useDownloadFile(dbOrBucketName, bucketNameOrPath, pathOrOptions, maybeOptions) {
+	let db;
+	let bucketName;
+	let path;
+	let options;
+	if (typeof dbOrBucketName === "string") {
+		db = useDb();
+		bucketName = dbOrBucketName;
+		path = bucketNameOrPath;
+		options = pathOrOptions ?? {};
+	} else {
+		db = dbOrBucketName;
+		bucketName = bucketNameOrPath;
+		path = pathOrOptions;
+		options = maybeOptions ?? {};
+	}
+	const useCache = options.cache !== false;
+	const [url, setUrl] = (0, solid_js.createSignal)(null, { ownedWrite: true });
+	const [isLoading, setIsLoading] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	const [error, setError] = (0, solid_js.createSignal)(null, { ownedWrite: true });
+	let lease = null;
+	let privateUrl = null;
+	const [refetchSignal, setRefetchSignal] = (0, solid_js.createSignal)(0);
+	/** Consumed by the next effect run, so `refetch()` bypasses every layer once. */
+	let reloadOnce = false;
+	function releaseCurrent() {
+		lease?.release();
+		lease = null;
+		if (privateUrl) {
+			URL.revokeObjectURL(privateUrl);
+			privateUrl = null;
+		}
+	}
+	(0, solid_js.createEffect)(() => {
+		refetchSignal();
+		return path();
+	}, (filePath) => {
+		releaseCurrent();
+		if (!filePath) {
+			setUrl(null);
+			setIsLoading(false);
+			setError(null);
+			return;
+		}
+		const reload = reloadOnce;
+		reloadOnce = false;
+		let cancelled = false;
+		setIsLoading(true);
+		setError(null);
+		const bucket = db.bucket(bucketName);
+		(useCache ? bucket.url(filePath, {
+			persist: options.persist !== false,
+			pin: options.pin,
+			revalidate: options.revalidate,
+			reload
+		}).then((acquired) => {
+			if (!acquired) return null;
+			if (cancelled) {
+				acquired.release();
+				return null;
+			}
+			lease = acquired;
+			return acquired.url;
+		}) : bucket.read(filePath, {
+			persist: false,
+			reload: true
+		}).then((blob) => {
+			if (!blob || cancelled) return null;
+			privateUrl = URL.createObjectURL(blob);
+			return privateUrl;
+		})).then((result) => {
+			if (!cancelled) {
+				setUrl(result);
+				setIsLoading(false);
+			}
+		}, (err) => {
+			if (!cancelled) {
+				setError(err instanceof Error ? err : new Error(String(err)));
+				setIsLoading(false);
+			}
+		});
+		return () => {
+			cancelled = true;
+		};
+	});
+	(0, solid_js.onCleanup)(() => {
+		releaseCurrent();
+	});
+	const refetch = () => {
+		reloadOnce = true;
+		setRefetchSignal((n) => n + 1);
+	};
+	return {
+		url,
+		isLoading,
+		error,
+		refetch
+	};
+}
+
+//#endregion
+//#region src/lib/Sp00kyProvider.ts
+function Sp00kyProvider(props) {
+	const merged = (0, solid_js.merge)({ fallback: void 0 }, props);
+	const [db, setDb] = (0, solid_js.createSignal)(void 0, { ownedWrite: true });
+	let disposed = false;
+	(0, solid_js.onCleanup)(() => {
+		disposed = true;
+	});
+	(0, solid_js.onSettled)(() => {
+		(async () => {
+			try {
+				const instance = new SyncedDb(merged.config);
+				await instance.init();
+				if (disposed) {
+					await instance.close();
+					return;
+				}
+				if (merged.preload) try {
+					await merged.preload(instance);
+				} catch (e) {
+					console.error("Sp00kyProvider: preload failed; revealing UI anyway", e);
+				}
+				setDb(() => instance);
+				merged.onReady?.(instance);
+			} catch (e) {
+				const error = e instanceof Error ? e : new Error(String(e));
+				if (merged.onError) merged.onError(error);
+				else console.error("Sp00kyProvider: Failed to initialize database", error);
+			}
+		})();
+	});
+	return (0, solid_js.createMemo)(() => {
+		const instance = db();
+		if (!instance) return merged.fallback;
+		return (0, solid_js.createComponent)(Sp00kyContext, {
+			value: instance,
+			get children() {
+				return merged.children;
+			}
+		});
+	});
+}
+
+//#endregion
+//#region src/lib/create-submission.ts
+/**
+* Thin submission-state wrapper for mutations — button spinner/disable state
+* around `db.create/update/delete/run` calls.
+*
+* Deliberately NOT built on Solid 2's `action()`/`createOptimisticStore`: the
+* spooky engine is already optimistic local-first (writes commit to the local
+* DB and re-render through live queries before sync; `run()` is an outbox
+* CREATE), so a transaction/revert layer on top buys nothing and `action()`'s
+* await-vs-yield transaction escape is a real footgun. Errors here mean the
+* LOCAL commit failed — sync/push failures surface through `useSyncStatus`
+* and `usePendingMutations` instead.
+*/
+function createSubmission(fn) {
+	const [inFlight, setInFlight] = (0, solid_js.createSignal)(0, { ownedWrite: true });
+	const [error, setError] = (0, solid_js.createSignal)(void 0, { ownedWrite: true });
+	const [result, setResult] = (0, solid_js.createSignal)(void 0, { ownedWrite: true });
+	const submit = async (...args) => {
+		setError(void 0);
+		setInFlight((n) => n + 1);
+		try {
+			const r = await fn(...args);
+			setResult(() => r);
+			return r;
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+			return;
+		} finally {
+			setInFlight((n) => n - 1);
+		}
+	};
+	return {
+		submit,
+		pending: () => inFlight() > 0,
+		error,
+		result,
+		clearError: () => setError(void 0)
+	};
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* SyncedDb - A thin wrapper around sp00ky-ts for Solid.js integration.
+* Delegates all logic to the underlying sp00ky-ts instance.
+*
+* NOTE: keep in sync with packages/client-solid/src/index.ts (SyncedDb).
+* Copied rather than shared so this package's dependency graph never pulls
+* in solid-js 1.x; fold the two together once client-solid moves to Solid 2.
+*/
+var SyncedDb = class {
+	constructor(config) {
+		this.sp00ky = null;
+		this._initialized = false;
+		this.config = config;
+	}
+	getSp00ky() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky;
+	}
+	/**
+	* Initialize the sp00ky-ts instance
+	*/
+	async init() {
+		if (this._initialized) return;
+		this.sp00ky = new _spooky_sync_core.Sp00kyClient(this.config);
+		await this.sp00ky.init();
+		this._initialized = true;
+	}
+	/**
+	* Tear down the client: leaves the tabs broker, closes the local store and
+	* remote socket, and frees the wasm circuit. Without this a remounted provider
+	* (or an HMR reload) strands a whole client, and the abandoned wasm heaps stay
+	* resident because V8 cannot see how much wasm memory a dropped wrapper holds.
+	*/
+	async close() {
+		const instance = this.sp00ky;
+		this.sp00ky = null;
+		this._initialized = false;
+		if (instance) await instance.close();
+	}
+	/**
+	* Create a new record in the database
+	*/
+	async create(id, payload) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.create(id, payload);
+	}
+	/**
+	* Update an existing record in the database
+	*/
+	async update(tableName, recordId, payload, options) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.update(tableName, recordId, payload, options);
+	}
+	/**
+	* Delete an existing record in the database
+	*/
+	async delete(tableName, selector) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		const ctorName = selector?.constructor?.name;
+		const isRecordId = selector instanceof surrealdb.RecordId || ctorName === "RecordId" || ctorName === "bound RecordId";
+		let id;
+		if (typeof selector === "string") id = selector;
+		else if (isRecordId) id = `${tableName}:${selector.id}`;
+		else throw new Error("Only string ID or RecordId selectors are supported currently with core");
+		await this.sp00ky.delete(tableName, id);
+	}
+	/**
+	* Preload/prewarm a built query into the local cache without registering a
+	* live view. Fetches once and stores the rows (+ embedded related children)
+	* locally so a later `createQuery` for the same data paints instantly. Best-effort.
+	*/
+	async preload(finalQuery, options) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.preload(finalQuery, options);
+	}
+	/**
+	* Query data from the database
+	*/
+	query(table) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.query(table, {});
+	}
+	/**
+	* Run a backend operation
+	*/
+	async run(backend, path, payload, options) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.run(backend, path, payload, options);
+	}
+	/**
+	* Sign out, clear session and local storage
+	*/
+	async signOut() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.auth.signOut();
+	}
+	/**
+	* Execute a function with direct access to the remote database connection
+	*/
+	async useRemote(fn) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return await this.sp00ky.useRemote(fn);
+	}
+	/**
+	* Access the remote database service directly
+	*/
+	get remote() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.remoteClient;
+	}
+	/**
+	* Access the local database service directly
+	*/
+	get local() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.localClient;
+	}
+	/**
+	* Access the auth service
+	*/
+	get auth() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.auth;
+	}
+	get pendingMutationCount() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.pendingMutationCount;
+	}
+	/** Diagnostic — see `Sp00kyClient.liveRetryCount`. */
+	get liveRetryCount() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.liveRetryCount;
+	}
+	subscribeToPendingMutations(cb) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.subscribeToPendingMutations(cb);
+	}
+	/** Current sync-health snapshot. See {@link useSyncStatus}. */
+	get syncHealth() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.syncHealth;
+	}
+	/**
+	* Observe sync health. Fires immediately with the current status and again
+	* on every healthy↔degraded transition. Prefer the `useSyncStatus` hook in
+	* components; this is the imperative escape hatch.
+	*/
+	subscribeToSyncHealth(cb) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.subscribeToSyncHealth(cb);
+	}
+	/** Current local-store durability snapshot. See {@link useStorageStatus}. */
+	get storageHealth() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.storageHealth;
+	}
+	/**
+	* Observe local-store durability. Fires immediately with the current snapshot
+	* and again on change. Prefer the `useStorageStatus` hook in components; this
+	* is the imperative escape hatch.
+	*/
+	subscribeToStorageHealth(cb) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.subscribeToStorageHealth(cb);
+	}
+	bucket(name) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.bucket(name);
+	}
+	getBucketConfig(name) {
+		return this.config.schema.buckets?.find((b) => b.name === name);
+	}
+};
+
+//#endregion
+exports.RecordId = surrealdb.RecordId;
+exports.Sp00kyProvider = Sp00kyProvider;
+exports.SyncedDb = SyncedDb;
+exports.Uuid = surrealdb.Uuid;
+exports.conflate = conflate;
+exports.createPreload = createPreload;
+exports.createQuery = createQuery;
+exports.createSubmission = createSubmission;
+exports.fromSubscription = fromSubscription;
+exports.useAppRelease = useAppRelease;
+exports.useCrdtField = useCrdtField;
+exports.useDb = useDb;
+exports.useDownloadFile = useDownloadFile;
+exports.useFeatureFlag = useFeatureFlag;
+exports.useFileUpload = useFileUpload;
+exports.usePendingMutations = usePendingMutations;
+exports.useQuery = useQuery;
+exports.useStorageStatus = useStorageStatus;
+exports.useSyncStatus = useSyncStatus;
+//# sourceMappingURL=index.cjs.map