syncorejs 0.2.1 → 0.2.3

package/dist/_vendor/react/index.js

@@ -2,16 +2,50 @@ import { createContext, useContext, useEffect, useMemo, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/index.tsx
 /**
-* Pass `"skip"` as the args argument to `useQuery` to suppress the subscription
-* entirely and return `undefined` without contacting the runtime.
+* Pass `skip` as the `args` argument to any Syncore React hook to suppress
+* that subscription entirely.
+*
+* Useful when the query arguments depend on state that is not yet available
+* (e.g. a selected item ID) — instead of conditionally calling the hook
+* (which violates the Rules of Hooks), pass `skip` to deactivate it:
+*
+* ```tsx
+* const task = useQuery(api.tasks.get, selectedId ? { id: selectedId } : skip);
+* // task is `undefined` while selectedId is null/undefined
+* ```
+*
+* Skipped queries return `undefined` for `data`, `"skipped"` for `status`,
+* and `false` for `isLoading`.
 */
 const skip = "skip";
+const defaultRuntimeStatus = {
+	kind: "starting",
+	reason: "booting"
+};
 const SyncoreContext = createContext(null);
 /**
-* Provide a Syncore client to React descendants.
+* Provides a Syncore client to all React descendants via context.
+*
+* Wrap your app (or any subtree that uses Syncore hooks) with
+* `SyncoreProvider`. All `useQuery`, `useMutation`, `useAction`, and
+* `useQueries` calls inside the tree will automatically use the client you
+* supply.
+*
+* ```tsx
+* // For a browser worker setup
+* const client = createBrowserWorkerClient();
+*
+* function App() {
+*   return (
+*     <SyncoreProvider client={client}>
+*       <TaskList />
+*     </SyncoreProvider>
+*   );
+* }
+* ```
 *
-* Wrap your app with this component to use Syncore hooks like `useQuery` and
-* `useMutation`.
+* For Next.js apps use `SyncoreNextProvider` which also handles service worker
+* and worker URL configuration.
 */
 function SyncoreProvider({ client, children }) {
 	return /* @__PURE__ */ jsx(SyncoreContext.Provider, {
@@ -20,9 +54,17 @@ function SyncoreProvider({ client, children }) {
 	});
 }
 /**
-* Read the active Syncore client from React context.
+* Returns the active `SyncoreClient` from the nearest {@link SyncoreProvider}
+* in the React tree.
 *
-* Throws if used outside of {@link SyncoreProvider}.
+* Throws if called outside of a `SyncoreProvider`. Prefer the higher-level
+* hooks (`useQuery`, `useMutation`, etc.) for common operations — use
+* `useSyncore` only when you need direct access to the client object.
+*
+* ```ts
+* const client = useSyncore();
+* const tasks = await client.query(api.tasks.list);
+* ```
 */
 function useSyncore() {
 	const client = useContext(SyncoreContext);
@@ -30,15 +72,90 @@ function useSyncore() {
 	return client;
 }
 /**
-* Load a reactive Syncore query within a React component.
+* Subscribe to the runtime’s lifecycle status.
+*
+* Returns a {@link SyncoreRuntimeStatus} that updates whenever the underlying
+* runtime changes state (e.g. starting, ready, error). Use it to gate your UI
+* on the runtime being ready or to display an error boundary:
+*
+* ```tsx
+* function TaskList() {
+*   const status = useSyncoreStatus();
+*   if (status.kind === "starting") return <Spinner />;
+*   if (status.kind === "error")    return <ErrorScreen error={status.error} />;
+*   return <Tasks />;
+* }
+* ```
+*
+* Most components do not need this — `useQuery` already incorporates runtime
+* status into the `SyncoreQueryState.runtimeStatus` field.
+*/
+function useSyncoreStatus() {
+	const client = useSyncore();
+	const watch = useMemo(() => client.watchRuntimeStatus(), [client]);
+	const [status, setStatus] = useState(() => readRuntimeStatusSnapshot(watch));
+	useEffect(() => {
+		const sync = () => {
+			setStatus(readRuntimeStatusSnapshot(watch));
+		};
+		sync();
+		return watch.onUpdate(sync);
+	}, [watch]);
+	useEffect(() => () => {
+		watch.dispose?.();
+	}, [watch]);
+	return status;
+}
+/**
+* Subscribe to a reactive Syncore query and return the current data.
+*
+* The component re-renders automatically whenever the query result changes.
+* If the query throws, `useQuery` re-throws the error so a React error
+* boundary can catch it — use {@link useQueryState} if you need to handle
+* errors inline.
+*
+* ```tsx
+* // Basic usage
+* const tasks = useQuery(api.tasks.list);
+*
+* // With arguments
+* const task = useQuery(api.tasks.get, { id: taskId });
+*
+* // Conditionally skip when arguments are not yet available
+* const task = useQuery(api.tasks.get, taskId ? { id: taskId } : skip);
+* ```
 *
-* The hook subscribes automatically and re-renders whenever the local query
-* result changes. Pass `"skip"` as the second argument to suppress the
-* subscription entirely and return `undefined` without contacting the runtime.
+* @param reference - A typed function reference (from the generated `api` object).
+* @param args      - The query’s arguments, or `skip` to suppress the subscription.
+* @returns The current query result, or `undefined` while loading.
 */
 function useQuery(reference, ...args) {
+	const state = useQueryState(reference, ...args);
+	if (state.error) throw state.error;
+	return state.data;
+}
+/**
+* Subscribe to a reactive Syncore query and return the full
+* {@link SyncoreQueryState} including loading, error, and runtime status.
+*
+* Use this instead of {@link useQuery} when you need to:
+* - Differentiate between `undefined` data and an error.
+* - React to `isLoading` / `isError` without relying on error boundaries.
+* - Inspect `runtimeStatus` for the underlying runtime’s health.
+*
+* ```tsx
+* const { data, isLoading, isError, error } = useQueryState(api.tasks.list);
+*
+* if (isLoading) return <Spinner />;
+* if (isError)   return <ErrorBanner message={error.message} />;
+* return <TaskList tasks={data} />;
+* ```
+*/
+function useQueryState(reference, ...args) {
 	const isSkipped = args[0] === skip;
-	const watch = useManagedQueryWatch(useSyncore(), reference, isSkipped ? void 0 : normalizeOptionalArgs(args), isSkipped);
+	const client = useSyncore();
+	const runtimeStatus = useSyncoreStatus();
+	const watch = useManagedQueryWatch(client, reference, isSkipped ? void 0 : normalizeOptionalArgs(args), isSkipped);
 	const [snapshot, setSnapshot] = useState(() => isSkipped ? noOpSnapshot : readWatchSnapshot(watch));
 	useEffect(() => {
 		if (isSkipped) {
@@ -51,78 +168,277 @@ function useQuery(reference, ...args) {
 		sync();
 		return watch.onUpdate(sync);
 	}, [watch, isSkipped]);
-	if (snapshot.error) throw snapshot.error;
-	return snapshot.result;
+	return toQueryState(snapshot, runtimeStatus, isSkipped);
 }
-const noOpSnapshot = {
-	result: void 0,
-	error: void 0
-};
-const noOpWatch = {
-	onUpdate: () => () => {},
-	localQueryResult: () => void 0,
-	localQueryError: () => void 0
-};
 /**
-* Construct a stable function that executes a Syncore mutation.
+* Returns a stable callback for executing a Syncore mutation.
+*
+* The returned function is type-safe: its parameter types are inferred from
+* the mutation definition and remain stable across re-renders (no need to
+* wrap in `useCallback`).
+*
+* ```tsx
+* const createTask = useMutation(api.tasks.create);
+*
+* return (
+*   <button onClick={() => createTask({ title: "New task" })}>
+*     Add task
+*   </button>
+* );
+* ```
+*
+* @param reference - A typed mutation reference from the generated `api` object.
+* @returns A function that, when called, executes the mutation and returns a
+*   promise that resolves to the mutation’s return value.
 */
 function useMutation(reference) {
 	const client = useSyncore();
 	return (...args) => client.mutation(reference, normalizeOptionalArgs(args));
 }
 /**
-* Construct a stable function that executes a Syncore action.
+* Returns a stable callback for executing a Syncore action.
+*
+* Identical to {@link useMutation} but for actions. Use this when the work you
+* need to do cannot run inside a transaction (external API calls, long-running
+* tasks, etc.).
+*
+* ```tsx
+* const importTasks = useAction(api.tasks.importFromCsv);
+*
+* return (
+*   <button onClick={() => importTasks({ url: csvUrl })}>
+*     Import
+*   </button>
+* );
+* ```
+*
+* @param reference - A typed action reference from the generated `api` object.
+* @returns A function that, when called, executes the action and returns a
+*   promise that resolves to the action’s return value.
 */
 function useAction(reference) {
 	const client = useSyncore();
 	return (...args) => client.action(reference, normalizeOptionalArgs(args));
 }
 /**
-* Load several Syncore queries at once using explicit keys.
+* Subscribe to multiple Syncore queries simultaneously and receive per-entry
+* state objects in a single hook call.
+*
+* More efficient than calling `useQuery` in a loop when the set of queries is
+* known at component render time. The hook maintains only one subscription per
+* unique `(reference, args)` combination even if entries are duplicated.
+*
+* ```tsx
+* const { header, sidebar } = useQueries({
+*   header:  { query: api.layout.header },
+*   sidebar: { query: api.layout.sidebar, args: { userId } },
+* });
+*
+* if (header.isLoading || sidebar.isLoading) return <Spinner />;
+* ```
+*
+* @param entries - A record of named query requests. Each entry can include
+*   `args: skip` to suppress that specific subscription.
+* @returns A record with the same keys, each holding a {@link SyncoreQueryState}.
 */
 function useQueries(entries) {
 	const client = useSyncore();
-	const entriesKey = stableStringify(entries.map((entry) => ({
-		key: entry.key,
-		referenceName: entry.reference.name,
-		args: entry.args ?? {}
+	const runtimeStatus = useSyncoreStatus();
+	const entriesKey = stableStringify(Object.entries(entries).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => ({
+		key,
+		referenceName: entry.query.name,
+		skipped: entry.args === skip,
+		args: entry.args === "skip" ? {} : normalizeOptionalArgs([entry.args ?? {}])
 	})));
 	const normalizedEntries = useMemo(() => JSON.parse(entriesKey), [entriesKey]);
-	const watches = useMemo(() => normalizedEntries.map((entry) => ({
-		key: entry.key,
-		watch: client.watchQuery({
-			kind: "query",
-			name: entry.referenceName
-		}, entry.args)
-	})), [client, normalizedEntries]);
-	const [snapshot, setSnapshot] = useState(() => readQueriesSnapshot(watches));
-	useEffect(() => () => {
-		for (const entry of watches) entry.watch.dispose?.();
-	}, [watches]);
+	const [observer] = useState(() => new ReactQueriesObserver(client));
+	const [, setVersion] = useState(0);
+	if (observer.client !== client) observer.replaceClient(client);
+	useEffect(() => () => observer.destroy(), [observer]);
 	useEffect(() => {
-		const sync = () => {
-			setSnapshot(readQueriesSnapshot(watches));
+		observer.setEntries(normalizedEntries);
+		setVersion((value) => value + 1);
+		return observer.subscribe(() => {
+			setVersion((value) => value + 1);
+		});
+	}, [normalizedEntries, observer]);
+	const snapshot = observer.getSnapshot(normalizedEntries);
+	return useMemo(() => {
+		return Object.fromEntries(normalizedEntries.map((entry) => [entry.key, toQueryState(snapshot[entry.key] ?? noOpSnapshot, runtimeStatus, entry.skipped)]));
+	}, [
+		normalizedEntries,
+		runtimeStatus,
+		snapshot
+	]);
+}
+/**
+* Subscribe to a paginated Syncore query, incrementally loading more pages.
+*
+* The query must accept a `paginationOpts` argument and return a
+* `PaginationResult`. The hook manages cursors automatically — call the
+* returned `loadMore` function to append the next page to the results.
+*
+* ```tsx
+* const { results, status, loadMore, hasMore } = usePaginatedQuery(
+*   api.tasks.list,
+*   { projectId },
+*   { initialNumItems: 20 },
+* );
+*
+* return (
+*   <>
+*     {results.map((t) => <TaskRow key={t._id} task={t} />)}
+*     {hasMore && (
+*       <button
+*         onClick={() => loadMore(20)}
+*         disabled={status === "loadingMore"}
+*       >
+*         Load more
+*       </button>
+*     )}
+*   </>
+* );
+* ```
+*
+* Pass `skip` as `args` to suppress the subscription until arguments are
+* ready.
+*
+* @param reference          - A typed query reference whose handler calls
+*   `ctx.db.query(…).paginate(paginationOpts)`.
+* @param args               - Arguments for the query (excluding
+*   `paginationOpts`, which is managed internally), or `skip`.
+* @param options.initialNumItems - Number of items to load on the first page.
+* @returns A {@link UsePaginatedQueryResult} with the accumulated results and
+*   a `loadMore` callback.
+*/
+function usePaginatedQuery(reference, args, options) {
+	if (typeof options.initialNumItems !== "number" || options.initialNumItems <= 0) throw new Error(`options.initialNumItems must be a positive number. Received ${String(options.initialNumItems)}.`);
+	const runtimeStatus = useSyncoreStatus();
+	const isSkipped = args === skip;
+	const normalizedArgs = isSkipped ? {} : args ?? {};
+	const requestKey = stableStringify({
+		referenceName: reference.name,
+		args: normalizedArgs,
+		initialNumItems: options.initialNumItems,
+		skipped: isSkipped
+	});
+	const createInitialState = useMemo(() => () => ({
+		requestKey,
+		nextPageKey: 1,
+		pages: isSkipped ? [] : [{
+			key: "0",
+			cursor: null,
+			numItems: options.initialNumItems
+		}]
+	}), [
+		isSkipped,
+		options.initialNumItems,
+		requestKey
+	]);
+	const [state, setState] = useState(createInitialState);
+	let currentState = state;
+	if (currentState.requestKey !== requestKey) {
+		currentState = createInitialState();
+		setState(currentState);
+	}
+	const pageStates = useQueries(useMemo(() => {
+		const requests = {};
+		for (const page of currentState.pages) requests[page.key] = {
+			query: reference,
+			args: {
+				...normalizedArgs,
+				paginationOpts: {
+					cursor: page.cursor,
+					numItems: page.numItems
+				}
+			}
 		};
-		sync();
-		const cleanups = watches.map((entry) => entry.watch.onUpdate(sync));
-		return () => {
-			for (const cleanup of cleanups) cleanup();
+		return requests;
+	}, [
+		currentState.pages,
+		normalizedArgs,
+		reference
+	]));
+	const derived = useMemo(() => {
+		const pages = [];
+		let error;
+		for (const page of currentState.pages) {
+			const pageState = pageStates[page.key];
+			if (!pageState || pageState.status === "loading") break;
+			if (pageState.status === "error") {
+				error = pageState.error;
+				break;
+			}
+			if (pageState.data) pages.push(pageState.data);
+		}
+		const results = pages.flatMap((page) => page.page);
+		const lastLoadedPage = pages.at(-1);
+		const lastRequestedKey = currentState.pages.at(-1)?.key;
+		const lastRequestedState = lastRequestedKey ? pageStates[lastRequestedKey] : void 0;
+		const isLoading = !isSkipped && pages.length === 0 && !error;
+		const isLoadingMore = currentState.pages.length > pages.length || !!lastRequestedState && lastRequestedState.status === "loading" && pages.length > 0;
+		const hasMore = !!lastLoadedPage && !lastLoadedPage.isDone;
+		const status = error ? "error" : isSkipped ? "ready" : isLoading ? "loading" : isLoadingMore ? "loadingMore" : hasMore ? "ready" : "exhausted";
+		return {
+			pages,
+			results,
+			error,
+			isLoading,
+			isLoadingMore,
+			hasMore,
+			cursor: lastLoadedPage?.cursor ?? null,
+			status
 		};
-	}, [watches]);
-	return snapshot;
+	}, [
+		currentState.pages,
+		isSkipped,
+		pageStates
+	]);
+	return {
+		...derived,
+		runtimeStatus,
+		loadMore(numItems = options.initialNumItems) {
+			if (isSkipped || derived.error || derived.isLoadingMore || !derived.hasMore || !derived.cursor) return;
+			setState((previous) => ({
+				...previous,
+				nextPageKey: previous.nextPageKey + 1,
+				pages: [...previous.pages, {
+					key: String(previous.nextPageKey),
+					cursor: derived.cursor,
+					numItems
+				}]
+			}));
+		}
+	};
 }
-function useManagedQueryWatch(client, reference, args, isSkipped) {
-	const argsKey = isSkipped ? "skip" : stableStringify(args ?? {});
-	const normalizedArgs = useMemo(() => isSkipped ? void 0 : JSON.parse(argsKey), [argsKey, isSkipped]);
-	const watch = useMemo(() => isSkipped ? noOpWatch : client.watchQuery(reference, normalizedArgs), [
+const noOpSnapshot = {
+	data: void 0,
+	error: void 0
+};
+const noOpWatch = {
+	onUpdate: () => () => void 0,
+	localQueryResult: () => void 0,
+	localQueryError: () => void 0
+};
+function useManagedQueryWatch(client, reference, args, isSkipped = false) {
+	const argsKey = isSkipped ? skip : stableStringify(args ?? {});
+	const [watch, setWatch] = useState(() => noOpWatch);
+	useEffect(() => {
+		if (isSkipped) {
+			setWatch(noOpWatch);
+			return;
+		}
+		const nextWatch = client.watchQuery(reference, JSON.parse(argsKey));
+		setWatch(nextWatch);
+		return () => {
+			nextWatch.dispose?.();
+		};
+	}, [
+		argsKey,
 		client,
-		normalizedArgs,
-		reference,
-		isSkipped
+		isSkipped,
+		reference
 	]);
-	useEffect(() => () => {
-		if (!isSkipped) watch.dispose?.();
-	}, [watch, isSkipped]);
 	return watch;
 }
 function normalizeOptionalArgs(args) {
@@ -130,12 +446,36 @@ function normalizeOptionalArgs(args) {
 }
 function readWatchSnapshot(watch) {
 	return {
-		result: watch.localQueryResult(),
+		data: watch.localQueryResult(),
 		error: watch.localQueryError()
 	};
 }
-function readQueriesSnapshot(watches) {
-	return Object.fromEntries(watches.map((entry) => [entry.key, entry.watch.localQueryResult()]));
+function readQueriesSnapshot(records) {
+	return Object.fromEntries(records.map((entry) => [entry.key, entry.snapshot]));
+}
+function readRuntimeStatusSnapshot(watch) {
+	return watch.localQueryResult() ?? defaultRuntimeStatus;
+}
+function toQueryState(snapshot, runtimeStatus, isSkipped) {
+	if (isSkipped) return {
+		data: void 0,
+		error: void 0,
+		status: "skipped",
+		runtimeStatus,
+		isLoading: false,
+		isError: false,
+		isReady: false
+	};
+	const status = snapshot.error !== void 0 ? "error" : snapshot.data === void 0 ? "loading" : "success";
+	return {
+		data: snapshot.data,
+		error: snapshot.error,
+		status,
+		runtimeStatus,
+		isLoading: status === "loading",
+		isError: status === "error",
+		isReady: status === "success"
+	};
 }
 function stableStringify(value) {
 	return JSON.stringify(sortValue(value));
@@ -145,7 +485,80 @@ function sortValue(value) {
 	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, nested]) => [key, sortValue(nested)]));
 	return value;
 }
+var ReactQueriesObserver = class {
+	client;
+	listeners = /* @__PURE__ */ new Set();
+	records = /* @__PURE__ */ new Map();
+	constructor(client) {
+		this.client = client;
+	}
+	replaceClient(client) {
+		this.destroy();
+		this.client = client;
+	}
+	setEntries(entries) {
+		const activeKeys = new Set(entries.map((entry) => entry.key));
+		for (const entry of entries) {
+			const requestKey = `${entry.referenceName}:${stableStringify(entry.args)}:${String(entry.skipped)}`;
+			const current = this.records.get(entry.key);
+			if (current?.requestKey === requestKey) continue;
+			current?.unsubscribe();
+			current?.watch?.dispose?.();
+			if (entry.skipped) {
+				this.records.set(entry.key, {
+					requestKey,
+					snapshot: noOpSnapshot,
+					unsubscribe: () => void 0
+				});
+				continue;
+			}
+			const watch = this.client.watchQuery({
+				kind: "query",
+				name: entry.referenceName
+			}, entry.args);
+			const record = {
+				requestKey,
+				snapshot: readWatchSnapshot(watch),
+				unsubscribe: () => void 0,
+				watch
+			};
+			record.unsubscribe = watch.onUpdate(() => {
+				record.snapshot = readWatchSnapshot(watch);
+				this.notify();
+			});
+			this.records.set(entry.key, record);
+		}
+		for (const [key, record] of this.records.entries()) {
+			if (activeKeys.has(key)) continue;
+			record.unsubscribe();
+			record.watch?.dispose?.();
+			this.records.delete(key);
+		}
+	}
+	getSnapshot(entries) {
+		return readQueriesSnapshot(entries.map((entry) => ({
+			key: entry.key,
+			snapshot: this.records.get(entry.key)?.snapshot ?? noOpSnapshot
+		})));
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	destroy() {
+		for (const record of this.records.values()) {
+			record.unsubscribe();
+			record.watch?.dispose?.();
+		}
+		this.records.clear();
+	}
+	notify() {
+		for (const listener of this.listeners) listener();
+	}
+};
 //#endregion
-export { SyncoreProvider, skip, useAction, useMutation, useQueries, useQuery, useSyncore };
+export { SyncoreProvider, skip, useAction, useMutation, usePaginatedQuery, useQueries, useQuery, useQueryState, useSyncore, useSyncoreStatus };
 
 //# sourceMappingURL=index.js.map