@octanejs/tanstack-db 0.0.1

package/src/useLiveSuspenseQuery.ts

@@ -0,0 +1,251 @@
+import { use, useRef } from 'octane';
+import { splitTrailingSlot, subSlot } from './slot';
+import { useLiveQuery } from './useLiveQuery';
+import type {
+	Collection,
+	Context,
+	GetResult,
+	InferResultType,
+	InitialQueryBuilder,
+	LiveQueryCollectionConfig,
+	NonSingleResult,
+	QueryBuilder,
+	SingleResult,
+} from '@tanstack/db';
+
+// Shared, already-fulfilled thenable handed to `use()` on the non-suspending
+// paths (see the divergence note in the hook body). It carries the React 19
+// `cache()` "settled thenable" shape (`status: 'fulfilled'`), which Octane's
+// `use()` returns synchronously without instrumentation. A bare
+// `Promise.resolve()` would NOT work: `use()` tags an untagged thenable
+// `'pending'` synchronously (the fulfillment callback runs a microtask later),
+// so its first use would suspend and flash the fallback even though data is
+// ready. Its resolved value is never read — only the settled status matters — so
+// one module-level instance is safe to share across every hook and render.
+const SETTLED: Promise<void> & { status: 'fulfilled'; value: undefined } = Object.assign(
+	Promise.resolve(),
+	{ status: `fulfilled` as const, value: undefined },
+);
+
+/**
+ * Create a live query with React Suspense support
+ * @param queryFn - Query function that defines what data to fetch
+ * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @returns Object with reactive data and state - data is guaranteed to be defined
+ * @throws Promise when data is loading (caught by Suspense boundary)
+ * @throws Error when collection fails (caught by Error boundary)
+ * @example
+ * // Basic usage with Suspense
+ * function TodoList() {
+ *   const { data } = useLiveSuspenseQuery((q) =>
+ *     q.from({ todos: todosCollection })
+ *      .where(({ todos }) => eq(todos.completed, false))
+ *      .select(({ todos }) => ({ id: todos.id, text: todos.text }))
+ *   )
+ *
+ *   return (
+ *     <ul>
+ *       {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<div>Loading...</div>}>
+ *       <TodoList />
+ *     </Suspense>
+ *   )
+ * }
+ *
+ * @example
+ * // Single result query
+ * const { data } = useLiveSuspenseQuery(
+ *   (q) => q.from({ todos: todosCollection })
+ *          .where(({ todos }) => eq(todos.id, 1))
+ *          .findOne()
+ * )
+ * // data is guaranteed to be the single item (or undefined if not found)
+ *
+ * @example
+ * // With dependencies that trigger re-suspension
+ * const { data } = useLiveSuspenseQuery(
+ *   (q) => q.from({ todos: todosCollection })
+ *          .where(({ todos }) => gt(todos.priority, minPriority)),
+ *   [minPriority] // Re-suspends when minPriority changes
+ * )
+ *
+ * @example
+ * // With Error boundary
+ * function App() {
+ *   return (
+ *     <ErrorBoundary fallback={<div>Error loading data</div>}>
+ *       <Suspense fallback={<div>Loading...</div>}>
+ *         <TodoList />
+ *       </Suspense>
+ *     </ErrorBoundary>
+ *   )
+ * }
+ *
+ * @remarks
+ * **Important:** This hook does NOT support disabled queries (returning undefined/null).
+ * Following TanStack Query's useSuspenseQuery design, the query callback must always
+ * return a valid query, collection, or config object.
+ *
+ * ❌ **This will cause a type error:**
+ * ```ts
+ * useLiveSuspenseQuery(
+ *   (q) => userId ? q.from({ users }) : undefined  // ❌ Error!
+ * )
+ * ```
+ *
+ * ✅ **Use conditional rendering instead:**
+ * ```ts
+ * function Profile({ userId }: { userId: string }) {
+ *   const { data } = useLiveSuspenseQuery(
+ *     (q) => q.from({ users }).where(({ users }) => eq(users.id, userId))
+ *   )
+ *   return <div>{data.name}</div>
+ * }
+ *
+ * // In parent component:
+ * {userId ? <Profile userId={userId} /> : <div>No user</div>}
+ * ```
+ *
+ * ✅ **Or use useLiveQuery for conditional queries:**
+ * ```ts
+ * const { data, isEnabled } = useLiveQuery(
+ *   (q) => userId ? q.from({ users }) : undefined,  // ✅ Supported!
+ *   [userId]
+ * )
+ * ```
+ */
+// Overload 1: Accept query function that always returns QueryBuilder
+export function useLiveSuspenseQuery<TContext extends Context>(
+	queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
+	deps?: Array<unknown>,
+): {
+	state: Map<string | number, GetResult<TContext>>;
+	data: InferResultType<TContext>;
+	collection: Collection<GetResult<TContext>, string | number, {}>;
+};
+
+// Overload 2: Accept config object
+export function useLiveSuspenseQuery<TContext extends Context>(
+	config: LiveQueryCollectionConfig<TContext>,
+	deps?: Array<unknown>,
+): {
+	state: Map<string | number, GetResult<TContext>>;
+	data: InferResultType<TContext>;
+	collection: Collection<GetResult<TContext>, string | number, {}>;
+};
+
+// Overload 3: Accept pre-created live query collection
+export function useLiveSuspenseQuery<
+	TResult extends object,
+	TKey extends string | number,
+	TUtils extends Record<string, any>,
+>(
+	liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,
+): {
+	state: Map<TKey, TResult>;
+	data: Array<TResult>;
+	collection: Collection<TResult, TKey, TUtils>;
+};
+
+// Overload 4: Accept pre-created live query collection with singleResult: true
+export function useLiveSuspenseQuery<
+	TResult extends object,
+	TKey extends string | number,
+	TUtils extends Record<string, any>,
+>(
+	liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult,
+): {
+	state: Map<TKey, TResult>;
+	data: TResult | undefined;
+	collection: Collection<TResult, TKey, TUtils> & SingleResult;
+};
+
+// Implementation - uses useLiveQuery internally and adds Suspense logic
+export function useLiveSuspenseQuery(configOrQueryOrCollection: any, ...rest: Array<unknown>) {
+	const [args, slot] = splitTrailingSlot(rest);
+	const deps = (args[0] as Array<unknown> | undefined) ?? [];
+
+	const promiseRef = useRef<Promise<void> | null>(null, subSlot(slot, `promise-ref`));
+	const collectionRef = useRef<Collection<any, any, any> | null>(null, subSlot(slot, `coll-ref`));
+	const hasBeenReadyRef = useRef(false, subSlot(slot, `ready-ref`));
+
+	// Use useLiveQuery to handle collection management and reactivity.
+	// Namespace the nested slot so useLiveQuery's internal refs (e.g. `coll-ref`)
+	// don't alias this wrapper's own refs of the same tag.
+	const result = (useLiveQuery as any)(configOrQueryOrCollection, deps, subSlot(slot, `lq`));
+
+	// Reset promise and ready state when collection changes (deps changed)
+	if (collectionRef.current !== result.collection) {
+		promiseRef.current = null;
+		collectionRef.current = result.collection;
+		hasBeenReadyRef.current = false;
+	}
+
+	// SUSPENSE LOGIC: Throw promise or error based on collection status
+
+	if (!result.isEnabled) {
+		// Suspense queries cannot be disabled - this matches TanStack Query's useSuspenseQuery behavior
+		throw new Error(
+			`useLiveSuspenseQuery does not support disabled queries (callback returned undefined/null). ` +
+				`The Suspense pattern requires data to always be defined (T, not T | undefined). ` +
+				`Solutions: ` +
+				`1) Use conditional rendering - don't render the component until the condition is met. ` +
+				`2) Use useLiveQuery instead, which supports disabled queries with the 'isEnabled' flag.`,
+		);
+	}
+
+	// It’s not recommended to suspend a render based on a store value returned by useSyncExternalStore.
+	// result.status is the snapshot from syncExternalStore. We read the fresh status from the collection reference instead.
+	const collectionStatus = result.collection.status;
+
+	// Track when we reach ready state
+	if (collectionStatus === `ready`) {
+		hasBeenReadyRef.current = true;
+		promiseRef.current = null;
+	}
+
+	// Only throw errors during initial load (before first ready)
+	// After success, errors surface as stale data (matches TanStack Query behavior).
+	// This throw aborts the whole component body (no later hook runs), so it does
+	// not perturb the call-order invariant the `use()` below depends on.
+	if (collectionStatus === `error` && !hasBeenReadyRef.current) {
+		promiseRef.current = null;
+		// TODO: Once collections hold a reference to their last error object (#671),
+		// we should rethrow that actual error instead of creating a generic message
+		throw new Error(`Collection "${result.collection.id}" failed to load`);
+	}
+
+	// OCTANE DIVERGENCE: suspend via `use(thenable)`, not `throw promise`, and call
+	// `use()` UNCONDITIONALLY — exactly once on every path that keeps rendering.
+	//
+	// Upstream react-db `throw`s the preload promise, and a React `throw` suspends
+	// the whole component with no positional state. Octane Suspense instead only
+	// recognizes the sentinel `use()` produces (a raw thrown promise reaches the
+	// error path and never renders the fallback), and Octane tracks `use(thenable)`
+	// by dynamic call-order index (the runtime's `__thenableIdx`), like React's
+	// positional `thenableState` — NOT by compiler slot. So skipping `use()` on the
+	// ready / stale-after-error paths would shift the thenable index of any sibling
+	// `use()` or second `useLiveSuspenseQuery` in the same component, which could
+	// then read a neighbor's fulfilled thenable and expose still-pending data as
+	// ready. Handing `use()` an already-resolved thenable when we are not loading
+	// keeps the call count stable and returns synchronously without suspending.
+	// Reusing the `promiseRef` identity lets `use()` dedupe the thenable across the
+	// suspension's replay renders.
+	const isLoading = collectionStatus === `loading` || collectionStatus === `idle`;
+	const preloadPromise = isLoading ? (promiseRef.current ??= result.collection.preload()) : SETTLED;
+	use(preloadPromise);
+
+	// Return data without status/loading flags (handled by Suspense/ErrorBoundary)
+	// If error after success, return last known good state (stale data)
+	return {
+		state: result.state,
+		data: result.data,
+		collection: result.collection,
+	};
+}

package/src/usePacedMutations.ts

@@ -0,0 +1,151 @@
+import { useCallback, useMemo, useRef } from 'octane';
+import { createPacedMutations } from '@tanstack/db';
+import { splitTrailingSlot, subSlot } from './slot';
+import type { PacedMutationsConfig, Transaction } from '@tanstack/db';
+
+/**
+ * React hook for managing paced mutations with timing strategies.
+ *
+ * Provides optimistic mutations with pluggable strategies like debouncing,
+ * queuing, or throttling. The optimistic updates are applied immediately via
+ * `onMutate`, and the actual persistence is controlled by the strategy.
+ *
+ * @param config - Configuration including onMutate, mutationFn and strategy
+ * @returns A mutate function that accepts variables and returns Transaction objects
+ *
+ * @example
+ * ```tsx
+ * // Debounced auto-save
+ * function AutoSaveForm({ formId }: { formId: string }) {
+ *   const mutate = usePacedMutations<string>({
+ *     onMutate: (value) => {
+ *       // Apply optimistic update immediately
+ *       formCollection.update(formId, draft => {
+ *         draft.content = value
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.save(transaction.mutations)
+ *     },
+ *     strategy: debounceStrategy({ wait: 500 })
+ *   })
+ *
+ *   const handleChange = async (value: string) => {
+ *     const tx = mutate(value)
+ *
+ *     // Optional: await persistence or handle errors
+ *     try {
+ *       await tx.isPersisted.promise
+ *       console.log('Saved!')
+ *     } catch (error) {
+ *       console.error('Save failed:', error)
+ *     }
+ *   }
+ *
+ *   return <textarea onChange={e => handleChange(e.target.value)} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Throttled slider updates
+ * function VolumeSlider() {
+ *   const mutate = usePacedMutations<number>({
+ *     onMutate: (volume) => {
+ *       settingsCollection.update('volume', draft => {
+ *         draft.value = volume
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.updateVolume(transaction.mutations)
+ *     },
+ *     strategy: throttleStrategy({ wait: 200 })
+ *   })
+ *
+ *   return <input type="range" onChange={e => mutate(+e.target.value)} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Debounce with leading/trailing for color picker (persist first + final only)
+ * function ColorPicker() {
+ *   const mutate = usePacedMutations<string>({
+ *     onMutate: (color) => {
+ *       themeCollection.update('primary', draft => {
+ *         draft.color = color
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.updateTheme(transaction.mutations)
+ *     },
+ *     strategy: debounceStrategy({ wait: 0, leading: true, trailing: true })
+ *   })
+ *
+ *   return (
+ *     <input
+ *       type="color"
+ *       onChange={e => mutate(e.target.value)}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function usePacedMutations<TVariables = unknown, T extends object = Record<string, unknown>>(
+	config: PacedMutationsConfig<TVariables, T>,
+	...rest: Array<unknown>
+): (variables: TVariables) => Transaction<T> {
+	const [, slot] = splitTrailingSlot(rest);
+
+	// Keep refs to the latest callbacks so we can call them without recreating the instance
+	const onMutateRef = useRef(config.onMutate, subSlot(slot, `on-mutate-ref`));
+	onMutateRef.current = config.onMutate;
+
+	const mutationFnRef = useRef(config.mutationFn, subSlot(slot, `mutation-fn-ref`));
+	mutationFnRef.current = config.mutationFn;
+
+	// Create stable wrappers that always call the latest version
+	const stableOnMutate = useCallback<typeof config.onMutate>(
+		(variables) => {
+			return onMutateRef.current(variables);
+		},
+		[],
+		subSlot(slot, `on-mutate-cb`),
+	);
+
+	const stableMutationFn = useCallback<typeof config.mutationFn>(
+		(params) => {
+			return mutationFnRef.current(params);
+		},
+		[],
+		subSlot(slot, `mutation-fn-cb`),
+	);
+
+	// Create paced mutations instance with proper dependency tracking
+	// Serialize strategy for stable comparison since strategy objects are recreated on each render
+	const mutate = useMemo(
+		() => {
+			return createPacedMutations<TVariables, T>({
+				...config,
+				onMutate: stableOnMutate,
+				mutationFn: stableMutationFn,
+			});
+		},
+		[
+			stableOnMutate,
+			stableMutationFn,
+			config.metadata,
+			// Serialize strategy to avoid recreating when object reference changes but values are same
+			JSON.stringify({
+				type: config.strategy._type,
+				options: config.strategy.options,
+			}),
+		],
+		subSlot(slot, `mutate-memo`),
+	);
+
+	// Return stable mutate callback
+	const stableMutate = useCallback(mutate, [mutate], subSlot(slot, `mutate-cb`));
+
+	return stableMutate;
+}