@spooky-sync/client-solid 0.0.1-canary.1 → 0.0.1-canary.100

package/dist/index.js

@@ -1,12 +1,13 @@
-import { SpookyClient } from "@spooky-sync/core";
+import { Sp00kyClient, fileToUint8Array } from "@spooky-sync/core";
 import { RecordId, Uuid } from "surrealdb";
 import { createComponent, createContext, createEffect, createMemo, createSignal, mergeProps, onCleanup, onMount, useContext } from "solid-js";
+import { createStore, reconcile } from "solid-js/store";
 
 //#region src/lib/context.ts
-const SpookyContext = createContext();
+const Sp00kyContext = createContext();
 function useDb() {
-	const db = useContext(SpookyContext);
-	if (!db) throw new Error("useDb must be used within a <SpookyProvider>. Wrap your app in <SpookyProvider config={...}>.");
+	const db = useContext(Sp00kyContext);
+	if (!db) throw new Error("useDb must be used within a <Sp00kyProvider>. Wrap your app in <Sp00kyProvider config={...}>.");
 	return db;
 }
 
@@ -21,27 +22,56 @@ function useQuery(dbOrQuery, queryOrOptions, maybeOptions) {
 		finalQuery = queryOrOptions;
 		options = maybeOptions;
 	} else {
-		const contextDb = useContext(SpookyContext);
-		if (!contextDb) throw new Error("useQuery: No db argument provided and no SpookyContext found. Either pass a SyncedDb instance or wrap your app in <SpookyProvider>.");
+		const contextDb = useContext(Sp00kyContext);
+		if (!contextDb) throw new Error("useQuery: No db argument provided and no Sp00kyContext found. Either pass a SyncedDb instance or wrap your app in <Sp00kyProvider>.");
 		db = contextDb;
 		finalQuery = dbOrQuery;
 		options = queryOrOptions;
 	}
-	const [data, setData] = createSignal(void 0);
 	const [error, setError] = createSignal(void 0);
 	const [isFetched, setIsFetched] = createSignal(false);
-	const [unsubscribe, setUnsubscribe] = createSignal(void 0);
+	const [isFetching, setIsFetching] = createSignal(false);
+	const [state, setState] = createStore({ value: void 0 });
+	const [version, setVersion] = createSignal(0);
+	const data = () => {
+		version();
+		return state.value;
+	};
 	let prevQueryString;
-	const spooky = db.getSpooky();
-	const initQuery = async (query) => {
+	let runId = 0;
+	let activeUnsub;
+	let activeHash;
+	const teardownActive = () => {
+		activeUnsub?.();
+		activeUnsub = void 0;
+	};
+	const sp00ky = db.getSp00ky();
+	const initQuery = async (query, myRun) => {
 		const { hash } = await query.run();
+		if (myRun !== runId) return;
+		activeHash = hash;
 		setError(void 0);
-		const unsub = await spooky.subscribe(hash, (e) => {
-			const data = query.isOne ? e[0] : e;
-			setData(() => data);
-			setIsFetched(true);
+		let isFirstCall = true;
+		const unsub = await sp00ky.subscribe(hash, (e) => {
+			const queryData = query.isOne ? e[0] : e;
+			const reconcileStart = performance.now();
+			setState("value", reconcile(queryData, { key: "id" }));
+			setVersion((v) => v + 1);
+			sp00ky.reportFrontendTiming(hash, performance.now() - reconcileStart);
+			const hasData = query.isOne ? queryData !== null && queryData !== void 0 : e.length > 0;
+			if (!isFirstCall || hasData) setIsFetched(true);
+			isFirstCall = false;
 		}, { immediate: true });
-		setUnsubscribe(() => unsub);
+		const unsubStatus = sp00ky.subscribeQueryStatus(hash, (status) => setIsFetching(status === "fetching"), { immediate: true });
+		const teardown = () => {
+			unsub();
+			unsubStatus();
+		};
+		if (myRun !== runId) {
+			teardown();
+			return;
+		}
+		activeUnsub = teardown;
 	};
 	createEffect(() => {
 		if (!(options?.enabled?.() ?? true)) {
@@ -50,14 +80,18 @@ function useQuery(dbOrQuery, queryOrOptions, maybeOptions) {
 		}
 		const query = typeof finalQuery === "function" ? finalQuery() : finalQuery;
 		if (!query) return;
-		const queryString = JSON.stringify(query);
+		const queryString = String(query.hash);
 		if (queryString === prevQueryString) return;
 		prevQueryString = queryString;
+		const myRun = ++runId;
+		teardownActive();
 		setIsFetched(false);
-		initQuery(query);
-		onCleanup(() => {
-			unsubscribe?.();
-		});
+		initQuery(query, myRun);
+	});
+	onCleanup(() => {
+		runId++;
+		teardownActive();
+		if (options?.deregisterOnCleanup && activeHash) sp00ky.deregisterQuery(activeHash);
 	});
 	const isLoading = () => {
 		return !isFetched() && error() === void 0;
@@ -65,13 +99,359 @@ function useQuery(dbOrQuery, queryOrOptions, maybeOptions) {
 	return {
 		data,
 		error,
-		isLoading
+		isLoading,
+		isFetching
+	};
+}
+
+//#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, setHealth] = createSignal(db.syncHealth);
+	onCleanup(db.subscribeToSyncHealth(setHealth));
+	return {
+		health,
+		status: () => health().status,
+		isHealthy: () => health().status === "healthy",
+		isDegraded: () => health().status === "degraded"
+	};
+}
+
+//#endregion
+//#region src/lib/use-crdt-field.ts
+function useCrdtField(table, recordId, field, fallbackText) {
+	const db = useContext(Sp00kyContext);
+	if (!db) throw new Error("useCrdtField must be used within a <Sp00kyProvider>");
+	const [crdtField, setCrdtField] = createSignal(null);
+	let currentId;
+	let initialized = false;
+	createEffect(() => {
+		const id = recordId();
+		if (initialized && id === currentId) return;
+		if (currentId && crdtField()) {
+			db.getSp00ky().closeCrdtField(table, currentId, field);
+			setCrdtField(null);
+		}
+		currentId = id;
+		initialized = true;
+		if (!id) return;
+		const sp00ky = db.getSp00ky();
+		const text = fallbackText?.();
+		sp00ky.openCrdtField(table, id, field, text).then((cf) => {
+			if (currentId === id) setCrdtField(cf);
+		}).catch((err) => {
+			console.error(`[useCrdtField] Failed to open CRDT field ${table}.${field} on ${id}:`, err);
+		});
+	});
+	onCleanup(() => {
+		if (currentId && crdtField()) {
+			db.getSp00ky().closeCrdtField(table, currentId, 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 `useQuery`, 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);
+	const [variant, setVariant] = createSignal(handle.variant());
+	const [payload, setPayload] = createSignal(handle.payload());
+	const unsub = handle.subscribe((s) => {
+		setVariant(s.variant ?? options?.fallback);
+		setPayload(s.payload);
+	});
+	onCleanup(() => {
+		unsub();
+		handle.close();
+	});
+	return {
+		variant,
+		payload,
+		enabled: () => {
+			const v = variant();
+			return v !== void 0 && v !== "off";
+		}
+	};
+}
+
+//#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] = createSignal(false);
+	const [error, setError] = createSignal(null);
+	const objectUrls = [];
+	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) => {
+		setError(null);
+		try {
+			validate(file);
+		} catch (e) {
+			setError(e instanceof Error ? e : new Error(String(e)));
+			return;
+		}
+		setIsUploading(true);
+		try {
+			const bytes = await fileToUint8Array(file);
+			await db.bucket(bucketName).put(path, bytes);
+		} 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/SpookyProvider.ts
-function SpookyProvider(props) {
+//#region src/lib/use-download-file.ts
+const downloadCache = /* @__PURE__ */ new Map();
+const inflightRequests = /* @__PURE__ */ new Map();
+function cacheKey(bucket, path) {
+	return `${bucket}:${path}`;
+}
+function releaseEntry(key) {
+	const entry = downloadCache.get(key);
+	if (!entry) return;
+	entry.refCount--;
+	if (entry.refCount <= 0) {
+		URL.revokeObjectURL(entry.url);
+		downloadCache.delete(key);
+	}
+}
+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] = createSignal(null);
+	const [isLoading, setIsLoading] = createSignal(false);
+	const [error, setError] = createSignal(null);
+	let currentKey = null;
+	let privateUrl = null;
+	const [refetchSignal, setRefetchSignal] = createSignal(0);
+	const refetchTrigger = () => setRefetchSignal((n) => n + 1);
+	async function doDownload(key, filePath) {
+		if (useCache) {
+			const cached = downloadCache.get(key);
+			if (cached) {
+				cached.refCount++;
+				currentKey = key;
+				return cached.url;
+			}
+			const inflight = inflightRequests.get(key);
+			if (inflight) {
+				const result = await inflight;
+				if (result) {
+					const entry = downloadCache.get(key);
+					if (entry) {
+						entry.refCount++;
+						currentKey = key;
+					}
+				}
+				return result;
+			}
+			const promise = (async () => {
+				const content = await db.bucket(bucketName).get(filePath);
+				if (!content) return null;
+				const objectUrl = URL.createObjectURL(new Blob([content]));
+				downloadCache.set(key, {
+					url: objectUrl,
+					refCount: 1
+				});
+				return objectUrl;
+			})();
+			inflightRequests.set(key, promise);
+			try {
+				const result = await promise;
+				currentKey = key;
+				return result;
+			} finally {
+				inflightRequests.delete(key);
+			}
+		} else {
+			const content = await db.bucket(bucketName).get(filePath);
+			if (!content) return null;
+			const objectUrl = URL.createObjectURL(new Blob([content]));
+			privateUrl = objectUrl;
+			return objectUrl;
+		}
+	}
+	function releaseCurrentEntry() {
+		if (useCache && currentKey) {
+			releaseEntry(currentKey);
+			currentKey = null;
+		}
+		if (!useCache && privateUrl) {
+			URL.revokeObjectURL(privateUrl);
+			privateUrl = null;
+		}
+	}
+	createEffect(() => {
+		const filePath = path();
+		refetchSignal();
+		releaseCurrentEntry();
+		if (!filePath) {
+			setUrl(null);
+			setIsLoading(false);
+			setError(null);
+			return;
+		}
+		const key = cacheKey(bucketName, filePath);
+		if (useCache) {
+			const cached = downloadCache.get(key);
+			if (cached) {
+				cached.refCount++;
+				currentKey = key;
+				setUrl(cached.url);
+				setIsLoading(false);
+				setError(null);
+				return;
+			}
+		}
+		let cancelled = false;
+		setIsLoading(true);
+		setError(null);
+		doDownload(key, filePath).then((result) => {
+			if (!cancelled) {
+				setUrl(result);
+				setIsLoading(false);
+			}
+		}, (err) => {
+			if (!cancelled) {
+				setError(err instanceof Error ? err : new Error(String(err)));
+				setIsLoading(false);
+			}
+		});
+		onCleanup(() => {
+			cancelled = true;
+		});
+	});
+	onCleanup(() => {
+		releaseCurrentEntry();
+	});
+	const refetch = () => {
+		if (useCache && currentKey) {
+			const entry = downloadCache.get(currentKey);
+			if (entry) {
+				URL.revokeObjectURL(entry.url);
+				downloadCache.delete(currentKey);
+			}
+			currentKey = null;
+		}
+		refetchTrigger();
+	};
+	return {
+		url,
+		isLoading,
+		error,
+		refetch
+	};
+}
+
+//#endregion
+//#region src/lib/Sp00kyProvider.ts
+function Sp00kyProvider(props) {
 	const merged = mergeProps({ fallback: void 0 }, props);
 	const [db, setDb] = createSignal(void 0);
 	onMount(async () => {
@@ -83,13 +463,13 @@ function SpookyProvider(props) {
 		} catch (e) {
 			const error = e instanceof Error ? e : new Error(String(e));
 			if (merged.onError) merged.onError(error);
-			else console.error("SpookyProvider: Failed to initialize database", error);
+			else console.error("Sp00kyProvider: Failed to initialize database", error);
 		}
 	});
 	return createMemo(() => {
 		const instance = db();
 		if (!instance) return merged.fallback;
-		return createComponent(SpookyContext.Provider, {
+		return createComponent(Sp00kyContext.Provider, {
 			value: instance,
 			get children() {
 				return merged.children;
@@ -101,69 +481,73 @@ function SpookyProvider(props) {
 //#endregion
 //#region src/index.ts
 /**
-* SyncedDb - A thin wrapper around spooky-ts for Solid.js integration
-* Delegates all logic to the underlying spooky-ts instance
+* SyncedDb - A thin wrapper around sp00ky-ts for Solid.js integration
+* Delegates all logic to the underlying sp00ky-ts instance
 */
 var SyncedDb = class {
 	constructor(config) {
-		this.spooky = null;
+		this.sp00ky = null;
 		this._initialized = false;
 		this.config = config;
 	}
-	getSpooky() {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky;
+	getSp00ky() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky;
 	}
 	/**
-	* Initialize the spooky-ts instance
+	* Initialize the sp00ky-ts instance
 	*/
 	async init() {
 		if (this._initialized) return;
-		this.spooky = new SpookyClient(this.config);
-		await this.spooky.init();
+		this.sp00ky = new Sp00kyClient(this.config);
+		await this.sp00ky.init();
 		this._initialized = true;
 	}
 	/**
 	* Create a new record in the database
 	*/
 	async create(id, payload) {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		await this.spooky.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.spooky) throw new Error("SyncedDb not initialized");
-		await this.spooky.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.spooky) throw new Error("SyncedDb not initialized");
-		if (typeof selector !== "string") throw new Error("Only string ID selectors are supported currently with core");
-		await this.spooky.delete(tableName, selector);
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		const isRecordId = selector instanceof RecordId || selector?.constructor?.name === "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);
 	}
 	/**
 	* Query data from the database
 	*/
 	query(table) {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.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.spooky) throw new Error("SyncedDb not initialized");
-		await this.spooky.run(backend, path, payload, options);
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		await this.sp00ky.run(backend, path, payload, options);
 	}
 	/**
 	* Authenticate with the database
 	*/
 	async authenticate(token) {
-		await this.spooky?.authenticate(token);
+		await this.sp00ky?.authenticate(token);
 		return new RecordId("user", "me");
 	}
 	/**
@@ -177,47 +561,73 @@ var SyncedDb = class {
 	* Sign out, clear session and local storage
 	*/
 	async signOut() {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		await this.spooky.auth.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.spooky) throw new Error("SyncedDb not initialized");
-		return await this.spooky.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.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.remoteClient;
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.remoteClient;
 	}
 	/**
 	* Access the local database service directly
 	*/
 	get local() {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.localClient;
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.localClient;
 	}
 	/**
 	* Access the auth service
 	*/
 	get auth() {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.auth;
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.auth;
 	}
 	get pendingMutationCount() {
-		if (!this.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.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.spooky) throw new Error("SyncedDb not initialized");
-		return this.spooky.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);
+	}
+	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
-export { RecordId, SpookyProvider, SyncedDb, Uuid, useDb, useQuery };
+export { RecordId, Sp00kyProvider, SyncedDb, Uuid, useCrdtField, useDb, useDownloadFile, useFeatureFlag, useFileUpload, useQuery, useSyncStatus };
 //# sourceMappingURL=index.js.map