@btst/stack 2.12.2 → 3.0.0-rc.1

package/src/plugins/client/resource/queries.ts

@@ -0,0 +1,330 @@
+/**
+ * Server-safe resource declaration types and query-key/queryFn builder.
+ *
+ * A plugin declares its resources once (paths, query mappings, unwrapping,
+ * key discriminators) and gets:
+ *
+ * - `createResourceQueryKeys(client, resources, headers?)` — a query-key
+ *   factory usable from SSR loaders and `query-keys.ts` (no React), with the
+ *   same `_def` / `queryKey` shapes as `@lukemorales/query-key-factory`, so
+ *   existing SSG `prefetchForRoute` / `query-key-defs.ts` keys keep matching.
+ * - `createResource(...)` (see `./hooks`) — generated React Query hooks.
+ */
+
+import { isErrorResponse, toError } from "./errors";
+
+/**
+ * Minimal better-call client shape the resource layer needs.
+ * Any `createApiClient<TRouter>()` result is assignable.
+ */
+export type ResourceClient = (path: any, options?: any) => Promise<unknown>;
+
+/**
+ * Declaration for a single query on a resource.
+ *
+ * Query-key shape: `[resourceName, queryName, ...key(...args)]` where `key`
+ * defaults to the args themselves. Share discriminator functions with
+ * `api/query-key-defs.ts` to keep SSG prefetch keys in sync.
+ */
+export interface ResourceQueryDef<
+	TArgs extends readonly unknown[] = readonly any[],
+	TData = unknown,
+> {
+	/** better-call endpoint path, e.g. `"/posts"` or `"/content/:typeSlug"` */
+	path: string;
+	/** Maps hook args to the endpoint path params (for `:param` segments) */
+	params?: (...args: TArgs) => Record<string, string>;
+	/** Maps hook args to the HTTP query object */
+	query?: (...args: TArgs) => Record<string, unknown> | undefined;
+	/**
+	 * Maps hook args to the queryKey discriminator cells appended after
+	 * `[resourceName, queryName]`. Defaults to the args themselves.
+	 */
+	key?: (...args: TArgs) => readonly unknown[];
+	/** Unwraps/selects data from the raw response data */
+	select?: (data: any, ...args: TArgs) => TData;
+	/**
+	 * Offset-paginated infinite query. The queryFn receives `pageParam` and
+	 * injects it into the HTTP query as `offsetParam`. `select` must return
+	 * an array (one page of items).
+	 */
+	infinite?: boolean;
+	/** HTTP query param carrying the page offset (default `"offset"`) */
+	offsetParam?: string;
+	/**
+	 * Page size used to derive `getNextPageParam` for infinite queries
+	 * (default 10). A function form derives it from the hook args.
+	 */
+	pageSize?: number | ((...args: TArgs) => number);
+	/**
+	 * Custom `getNextPageParam` for infinite queries whose pages are not
+	 * plain item arrays (e.g. `{ items, total }` envelopes). Overrides the
+	 * default page-size heuristic. Return `undefined` when there is no
+	 * next page.
+	 */
+	nextPageParam?: (
+		lastPage: TData,
+		allPages: TData[],
+		...args: TArgs
+	) => unknown | undefined;
+	/** When true, skip fetching and resolve `null` (e.g. missing id) */
+	skip?: (...args: TArgs) => boolean;
+}
+
+/**
+ * Declaration for a single mutation on a resource.
+ */
+export interface ResourceMutationDef<TVars = any, TResult = unknown> {
+	/** better-call endpoint path, e.g. `"@post/posts"` or `"@put/posts/:id"` */
+	path: string;
+	method: "POST" | "PUT" | "PATCH" | "DELETE";
+	/**
+	 * Maps mutation variables to better-call call options.
+	 * Defaults to `{ body: vars }`.
+	 */
+	input?: (vars: TVars) => {
+		body?: unknown;
+		params?: Record<string, string>;
+		query?: Record<string, unknown>;
+	};
+	/** Unwraps the mutation result from the raw response data */
+	select?: (data: any) => TResult;
+	/**
+	 * Query-key prefixes invalidated (awaited, in order) after success.
+	 * `"posts"` invalidates the whole resource, `"posts.list"` one query.
+	 */
+	invalidates?: readonly string[];
+	/**
+	 * Which matching queries to refetch during invalidation. Defaults to
+	 * React Query's `"active"`; use `"all"` when an inactive view must be
+	 * refreshed before it remounts.
+	 */
+	refetchType?: "active" | "inactive" | "all" | "none";
+	/**
+	 * Seed a query cache entry from the mutation result (e.g. the detail
+	 * entry for a created/updated record). `args` returns the key args for
+	 * the target query, or `null` to skip seeding.
+	 */
+	setData?: {
+		/** Target query name on the same resource (default `"detail"`) */
+		query?: string;
+		args: (result: TResult) => readonly unknown[] | null;
+		/**
+		 * Optionally merge the mutation result with the existing cache value.
+		 * Defaults to replacing the cached value with `result`.
+		 */
+		updater?: (previous: unknown, result: TResult) => unknown;
+	};
+	/**
+	 * Remove a query cache entry after success (e.g. the deleted record's
+	 * detail query). `args` may derive the target key from both the result and
+	 * the submitted variables, or return `null` to skip removal.
+	 */
+	removeData?: {
+		/** Target query name on the same resource (default `"detail"`) */
+		query?: string;
+		args: (result: TResult, variables: TVars) => readonly unknown[] | null;
+	};
+	/**
+	 * Whether to call the router `refresh` override after success (default
+	 * `true`). Set `false` for mutations that must not reload server-rendered
+	 * state — e.g. public submissions whose success UI lives in client state.
+	 */
+	refresh?: boolean;
+}
+
+/** Declaration for one resource: its queries and (optionally) mutations. */
+export interface ResourceDef {
+	queries: Record<string, ResourceQueryDef<any, any>>;
+	mutations?: Record<string, ResourceMutationDef<any, any>>;
+}
+
+/** A plugin's full resource declaration, keyed by resource name. */
+export type ResourcesDeclaration = Record<string, ResourceDef>;
+
+/** Extracts the hook args tuple from a query declaration. */
+export type ResourceQueryArgs<TDef> = TDef extends {
+	query: (...args: infer A) => any;
+}
+	? A
+	: TDef extends { params: (...args: infer A) => any }
+		? A
+		: TDef extends { key: (...args: infer A) => any }
+			? A
+			: TDef extends { select: (data: any, ...args: infer A) => any }
+				? A
+				: [];
+
+/** Extracts the (per-page, for infinite queries) data type from a query declaration. */
+export type ResourceQueryData<TDef> = TDef extends {
+	select: (data: any, ...args: any[]) => infer D;
+}
+	? D
+	: unknown;
+
+/** Extracts the variables type from a mutation declaration. */
+export type ResourceMutationVars<TDef> = TDef extends {
+	input: (vars: infer V) => any;
+}
+	? V
+	: unknown;
+
+/** Extracts the result type from a mutation declaration. */
+export type ResourceMutationResult<TDef> = TDef extends {
+	select: (data: any) => infer R;
+}
+	? R
+	: unknown;
+
+/**
+ * A query-key factory entry: call with args to get `{ queryKey, queryFn }`,
+ * read `_def` for the `[resourceName, queryName]` prefix.
+ */
+export interface ResourceQueryEntry<
+	TArgs extends readonly unknown[] = readonly any[],
+	TData = unknown,
+> {
+	(
+		...args: TArgs
+	): {
+		queryKey: readonly unknown[];
+		queryFn: (context?: { pageParam?: unknown }) => Promise<TData>;
+	};
+	_def: readonly [string, string];
+}
+
+/** The query-key factory produced from a resources declaration. */
+export type ResourceQueryKeys<TResources extends ResourcesDeclaration> = {
+	[R in keyof TResources]: {
+		[Q in keyof TResources[R]["queries"]]: ResourceQueryEntry<
+			ResourceQueryArgs<TResources[R]["queries"][Q]>,
+			ResourceQueryData<TResources[R]["queries"][Q]>
+		>;
+	} & { _def: readonly [R] };
+};
+
+/** Resolves the effective page size for an infinite query declaration. */
+export function resolvePageSize(
+	def: ResourceQueryDef<any, any>,
+	args: readonly unknown[],
+): number {
+	if (typeof def.pageSize === "function") return def.pageSize(...args);
+	return def.pageSize ?? 10;
+}
+
+/** Builds the full query key for a query declaration and args. */
+export function buildQueryKey(
+	resourceName: string,
+	queryName: string,
+	def: ResourceQueryDef<any, any>,
+	args: readonly unknown[],
+): readonly unknown[] {
+	const cells = def.key ? def.key(...args) : args;
+	return [resourceName, queryName, ...cells];
+}
+
+/**
+ * Executes the fetch → error-check → unwrap dance for a query declaration.
+ */
+export async function runResourceQuery(
+	client: ResourceClient,
+	def: ResourceQueryDef<any, any>,
+	args: readonly unknown[],
+	pageParam?: unknown,
+	headers?: HeadersInit,
+): Promise<unknown> {
+	if (def.skip?.(...args)) return null;
+
+	const baseQuery = def.query?.(...args);
+	const query = def.infinite
+		? { ...baseQuery, [def.offsetParam ?? "offset"]: pageParam ?? 0 }
+		: baseQuery;
+	const params = def.params?.(...args);
+
+	const response = await client(def.path, {
+		method: "GET",
+		...(params !== undefined ? { params } : {}),
+		...(query !== undefined ? { query } : {}),
+		...(headers !== undefined ? { headers } : {}),
+	});
+
+	if (isErrorResponse(response)) {
+		throw toError(response.error);
+	}
+
+	const data = (response as { data?: unknown }).data;
+	return def.select ? def.select(data, ...args) : data;
+}
+
+/**
+ * Executes a mutation declaration: fetch → error-check → unwrap.
+ *
+ * `headers` supports plugins whose public hooks take an explicit client
+ * config (e.g. embeddable components) instead of resolving it from
+ * `usePluginOverrides` — same as the `headers` parameter on
+ * `createResourceQueryKeys`.
+ */
+export async function runResourceMutation(
+	client: ResourceClient,
+	def: ResourceMutationDef<any, any>,
+	vars: unknown,
+	headers?: HeadersInit,
+): Promise<unknown> {
+	const { body, params, query } = def.input
+		? def.input(vars)
+		: { body: vars, params: undefined, query: undefined };
+
+	const response = await client(def.path, {
+		method: def.method,
+		...(body !== undefined ? { body } : {}),
+		...(params !== undefined ? { params } : {}),
+		...(query !== undefined ? { query } : {}),
+		...(headers !== undefined ? { headers } : {}),
+	});
+
+	if (isErrorResponse(response)) {
+		throw toError(response.error);
+	}
+
+	const data = (response as { data?: unknown }).data;
+	return def.select ? def.select(data) : data;
+}
+
+/**
+ * Builds a query-key factory from a resources declaration.
+ *
+ * Compatible with the shapes `@lukemorales/query-key-factory` produces:
+ * `store.posts.list(params)` → `{ queryKey: ["posts", "list", ...], queryFn }`,
+ * `store.posts.list._def` → `["posts", "list"]`, `store.posts._def` → `["posts"]`.
+ *
+ * Server-safe (no React) — usable from SSR loaders and `query-keys.ts`.
+ */
+export function createResourceQueryKeys<
+	const TResources extends ResourcesDeclaration,
+>(
+	client: ResourceClient,
+	resources: TResources,
+	headers?: HeadersInit,
+): ResourceQueryKeys<TResources> {
+	const store: Record<string, any> = {};
+
+	for (const [resourceName, resource] of Object.entries(resources)) {
+		const resourceStore: Record<string, any> = {
+			_def: [resourceName] as const,
+		};
+
+		for (const [queryName, def] of Object.entries(resource.queries)) {
+			const entry = (...args: readonly unknown[]) => ({
+				queryKey: buildQueryKey(resourceName, queryName, def, args),
+				queryFn: (context?: { pageParam?: unknown }) =>
+					runResourceQuery(client, def, args, context?.pageParam, headers),
+			});
+			entry._def = [resourceName, queryName] as const;
+			resourceStore[queryName] = entry;
+		}
+
+		store[resourceName] = resourceStore;
+	}
+
+	return store as ResourceQueryKeys<TResources>;
+}

package/src/plugins/client/resource/use-debounce.ts

@@ -0,0 +1,18 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/** Returns `value` debounced by `delay` milliseconds (default 500). */
+export function useDebounce<T>(value: T, delay?: number): T {
+	const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+	useEffect(() => {
+		const timer = setTimeout(() => setDebouncedValue(value), delay || 500);
+
+		return () => {
+			clearTimeout(timer);
+		};
+	}, [value, delay]);
+
+	return debouncedValue;
+}

package/src/plugins/client/resource/use-form.ts

@@ -0,0 +1,236 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { useMemo, useRef, useState } from "react";
+import { useNotify } from "../../../context";
+import { SHARED_QUERY_CONFIG, toError, type StackError } from "./errors";
+import { buildQueryKey, runResourceQuery, type ResourceDef } from "./queries";
+import { useResourceContext, useResourceMutationForDef } from "./internal";
+
+/** Configuration for the per-resource `useForm` hook. */
+export interface ResourceFormConfig<
+	TValues,
+	TRecord = unknown,
+	TResult = unknown,
+> {
+	action: "create" | "edit";
+	/** Detail-query arg identifying the record to edit (e.g. a slug or id) */
+	id?: unknown;
+	/** Query used to fetch the record for edit (default `"detail"`) */
+	detailQuery?: string;
+	/** Mutation used on create submit (default `"create"`) */
+	createMutation?: string;
+	/** Mutation used on edit submit (default `"update"`) */
+	updateMutation?: string;
+	/**
+	 * Externally supplied record — skips the internal detail fetch. Useful
+	 * when the record comes from a suspense hook higher in the tree.
+	 */
+	record?: TRecord | null;
+	/** Default form values, or a function deriving them from the record */
+	defaults?: TValues | ((record: TRecord | null) => TValues);
+	/** Maps form values to create-mutation variables (default: identity) */
+	toCreateVars?: (values: TValues) => unknown;
+	/** Maps form values to update-mutation variables (default: identity) */
+	toUpdateVars?: (values: TValues, record: TRecord | null) => unknown;
+	/** Success notification, sent through the `notify` provider */
+	successMessage?:
+		| string
+		| ((result: TResult, action: "create" | "edit") => string);
+	/**
+	 * Error notification for non-field errors. Field-level validation errors
+	 * land on `fieldErrors` instead of producing a notification.
+	 */
+	errorMessage?: string | ((error: StackError) => string);
+	/**
+	 * Path to navigate to after success (via the router adapter's
+	 * `navigate`). A function form derives it from the result; return a
+	 * falsy value to skip navigation.
+	 */
+	redirect?:
+		| string
+		| ((
+				result: TResult,
+				action: "create" | "edit",
+		  ) => string | false | null | undefined);
+	/** Called after a successful submit (before redirect) */
+	onSuccess?: (result: TResult) => void | Promise<void>;
+}
+
+/** Result of the per-resource `useForm` hook. */
+export interface ResourceFormResult<
+	TValues,
+	TRecord = unknown,
+	TResult = unknown,
+> {
+	action: "create" | "edit";
+	/** The record being edited (null while loading or when creating) */
+	record: TRecord | null;
+	isLoadingRecord: boolean;
+	recordError: Error | null;
+	/** Resolved default values (stable while `record` is unchanged) */
+	defaultValues: TValues | undefined;
+	/** Runs the right mutation; resolves the result, or undefined on error */
+	submit: (values: TValues) => Promise<TResult | undefined>;
+	isSubmitting: boolean;
+	/** Last submit error (normalized), or null */
+	error: StackError | null;
+	/** Field name → validation message(s) from the last submit error */
+	fieldErrors: Record<string, string | string[]>;
+	clearErrors: () => void;
+}
+
+/**
+ * Builds the per-resource `useForm` hook: bundles the create/edit lifecycle —
+ * fetch record for edit, defaults, submit the right mutation, invalidate,
+ * notify, redirect, and per-field error state from `StackError.errors`.
+ */
+export function createUseForm(
+	plugin: string,
+	resourceName: string,
+	resource: ResourceDef,
+) {
+	return function useForm<TValues, TRecord = unknown, TResult = unknown>(
+		config: ResourceFormConfig<TValues, TRecord, TResult>,
+	): ResourceFormResult<TValues, TRecord, TResult> {
+		const context = useResourceContext(plugin);
+		const notify = useNotify();
+		const { action } = config;
+
+		// --- record fetch (edit) ---------------------------------------------
+		const detailName = config.detailQuery ?? "detail";
+		const detailDef = resource.queries[detailName];
+		const hasExternalRecord = config.record !== undefined;
+		const detailArgs = config.id !== undefined ? [config.id] : [];
+		const detailEnabled =
+			action === "edit" &&
+			!hasExternalRecord &&
+			config.id !== undefined &&
+			!!detailDef;
+
+		const recordQuery = useQuery<unknown, Error>({
+			queryKey: detailDef
+				? buildQueryKey(resourceName, detailName, detailDef, detailArgs)
+				: [resourceName, detailName],
+			queryFn: () => {
+				if (!detailDef) {
+					// Unreachable: the query is disabled when detailDef is missing
+					throw new Error(
+						`Resource "${resourceName}" has no "${detailName}" query declared`,
+					);
+				}
+				return runResourceQuery(
+					context.client,
+					detailDef,
+					detailArgs,
+					undefined,
+					context.headers,
+				);
+			},
+			...SHARED_QUERY_CONFIG,
+			enabled: detailEnabled,
+		});
+
+		const record = hasExternalRecord
+			? (config.record ?? null)
+			: ((recordQuery.data as TRecord | undefined) ?? null);
+
+		// --- defaults ----------------------------------------------------------
+		const defaultsRef = useRef(config.defaults);
+		defaultsRef.current = config.defaults;
+		const defaultValues = useMemo(() => {
+			const defaults = defaultsRef.current;
+			if (typeof defaults === "function") {
+				return (defaults as (record: TRecord | null) => TValues)(record);
+			}
+			return defaults;
+			// The defaults function itself is intentionally not a dependency —
+			// it is typically an inline closure; only record changes matter.
+		}, [record]);
+
+		// --- mutations ---------------------------------------------------------
+		const createName = config.createMutation ?? "create";
+		const updateName = config.updateMutation ?? "update";
+		const createMutation = useResourceMutationForDef(
+			context,
+			resourceName,
+			createName,
+			resource,
+			resource.mutations?.[createName],
+		);
+		const updateMutation = useResourceMutationForDef(
+			context,
+			resourceName,
+			updateName,
+			resource,
+			resource.mutations?.[updateName],
+		);
+
+		// --- submit ------------------------------------------------------------
+		const [error, setError] = useState<StackError | null>(null);
+
+		const submit = async (values: TValues): Promise<TResult | undefined> => {
+			setError(null);
+			try {
+				const isEdit = action === "edit";
+				const vars = isEdit
+					? config.toUpdateVars
+						? config.toUpdateVars(values, record)
+						: values
+					: config.toCreateVars
+						? config.toCreateVars(values)
+						: values;
+				const mutation = isEdit ? updateMutation : createMutation;
+				const result = (await mutation.mutateAsync(vars)) as TResult;
+
+				if (config.successMessage) {
+					notify.success(
+						typeof config.successMessage === "function"
+							? config.successMessage(result, action)
+							: config.successMessage,
+					);
+				}
+				if (config.onSuccess) {
+					await config.onSuccess(result);
+				}
+				if (config.redirect) {
+					const path =
+						typeof config.redirect === "function"
+							? config.redirect(result, action)
+							: config.redirect;
+					if (path) {
+						await context.navigate?.(path);
+					}
+				}
+				return result;
+			} catch (e) {
+				const stackError = toError(e);
+				setError(stackError);
+				// Field-level validation errors land on fieldErrors, not a toast
+				if (!stackError.errors && config.errorMessage) {
+					notify.error(
+						typeof config.errorMessage === "function"
+							? config.errorMessage(stackError)
+							: config.errorMessage,
+					);
+				}
+				return undefined;
+			}
+		};
+
+		const fieldErrors = useMemo(() => error?.errors ?? {}, [error]);
+
+		return {
+			action,
+			record,
+			isLoadingRecord: detailEnabled ? recordQuery.isLoading : false,
+			recordError: detailEnabled ? recordQuery.error : null,
+			defaultValues,
+			submit,
+			isSubmitting: createMutation.isPending || updateMutation.isPending,
+			error,
+			fieldErrors,
+			clearErrors: () => setError(null),
+		};
+	};
+}