@btst/stack 2.12.2 → 3.0.0-rc.1

package/src/plugins/client/index.ts

@@ -22,13 +22,47 @@ export {
 	createApiClient,
 	createSanitizedSSRLoaderError,
 	isConnectionError,
-	runClientHookWithShim,
 	SSR_LOADER_ERROR_MESSAGE,
 } from "../utils";
 
+// Shared error contract + React Query config for data plugins
+export {
+	isErrorResponse,
+	SHARED_QUERY_CONFIG,
+	toError,
+} from "./resource/errors";
+export type { StackError } from "./resource/errors";
+
+// Resource declaration types + server-safe query-key factory
+export {
+	buildQueryKey,
+	createResourceQueryKeys,
+	resolvePageSize,
+	runResourceMutation,
+	runResourceQuery,
+} from "./resource/queries";
+export type {
+	ResourceClient,
+	ResourceDef,
+	ResourceMutationDef,
+	ResourceMutationResult,
+	ResourceMutationVars,
+	ResourceQueryArgs,
+	ResourceQueryData,
+	ResourceQueryDef,
+	ResourceQueryEntry,
+	ResourceQueryKeys,
+	ResourcesDeclaration,
+} from "./resource/queries";
+
 // Re-export Yar types needed for plugins
-export type { Route } from "@btst/yar";
-export { createRoute, createRouter } from "@btst/yar";
+export type { Route, RouteContext, RouteDef } from "@btst/yar";
+export {
+	createRoute,
+	createRouter,
+	defineRoute,
+	defineRoutes,
+} from "@btst/yar";
 
 export { createClient } from "better-call/client";
 

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

@@ -0,0 +1,160 @@
+/**
+ * Shared error contract and React Query config for all data plugins.
+ *
+ * Every plugin used to copy-paste `isErrorResponse` / `toError` /
+ * `SHARED_QUERY_CONFIG` into its own `query-keys.ts` / hooks files. These now
+ * live in core and are exported once from `@btst/stack/plugins/client`.
+ */
+
+/**
+ * Standardized error shape thrown by resource queries and mutations.
+ *
+ * `errors` maps field names to validation message(s), preserving Zod
+ * field-level issues from better-call endpoint validation errors so form
+ * hooks can map them onto per-field error state.
+ */
+export interface StackError extends Error {
+	statusCode?: number;
+	errors?: Record<string, string | string[]>;
+}
+
+/**
+ * Shared React Query configuration for all plugin queries.
+ * Prevents automatic refetching to avoid hydration mismatches in SSR.
+ */
+export const SHARED_QUERY_CONFIG = {
+	retry: false,
+	refetchOnWindowFocus: false,
+	refetchOnMount: false,
+	refetchOnReconnect: false,
+	staleTime: 1000 * 60 * 5, // 5 minutes
+	gcTime: 1000 * 60 * 10, // 10 minutes
+} as const;
+
+/**
+ * Type guard for better-call error responses.
+ * better-call client returns `Error$1<unknown> | Data<T>` — we check if
+ * `error` exists and is not null/undefined to determine it's an error response.
+ */
+export function isErrorResponse(
+	response: unknown,
+): response is { error: unknown; data?: never } {
+	return (
+		typeof response === "object" &&
+		response !== null &&
+		"error" in response &&
+		response.error !== null &&
+		response.error !== undefined
+	);
+}
+
+/** Serialized validation issue shape included in better-call 400 responses. */
+interface SerializedIssue {
+	path?: Array<string | number | { key: string | number }>;
+	message?: string;
+}
+
+function issuePathToFieldName(issue: SerializedIssue): string {
+	const path = Array.isArray(issue.path) ? issue.path : [];
+	return path
+		.map((segment) =>
+			typeof segment === "object" && segment !== null
+				? String(segment.key)
+				: String(segment),
+		)
+		.join(".");
+}
+
+/**
+ * Converts a validation `issues` array into a field-name → message(s) map.
+ * Issues without a path are skipped — they only contribute to the top-level
+ * error message.
+ */
+function issuesToFieldErrors(
+	issues: unknown,
+): Record<string, string | string[]> | undefined {
+	if (!Array.isArray(issues) || issues.length === 0) return undefined;
+
+	const fieldErrors: Record<string, string[]> = {};
+	for (const issue of issues as SerializedIssue[]) {
+		if (typeof issue !== "object" || issue === null) continue;
+		const field = issuePathToFieldName(issue);
+		if (!field || typeof issue.message !== "string") continue;
+		(fieldErrors[field] ??= []).push(issue.message);
+	}
+
+	const entries = Object.entries(fieldErrors);
+	if (entries.length === 0) return undefined;
+
+	return Object.fromEntries(
+		entries.map(([field, messages]) => [
+			field,
+			messages.length === 1 ? messages[0]! : messages,
+		]),
+	);
+}
+
+function isFieldErrorRecord(
+	value: unknown,
+): value is Record<string, string | string[]> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return false;
+	}
+	return Object.values(value).every(
+		(v) =>
+			typeof v === "string" ||
+			(Array.isArray(v) && v.every((m) => typeof m === "string")),
+	);
+}
+
+/**
+ * Converts an unknown error (typically a better-call / better-fetch error
+ * response body) into a proper `StackError` with a meaningful message.
+ *
+ * Normalizes to `{ message, statusCode?, errors? }` where `errors` maps
+ * field names to validation messages (preserved from Zod issues in
+ * better-call endpoint validation error responses).
+ */
+export function toError(error: unknown): StackError {
+	if (error instanceof Error) {
+		return error as StackError;
+	}
+
+	// Handle object errors (likely from better-call APIError response bodies)
+	if (typeof error === "object" && error !== null) {
+		const errorObj = error as Record<string, unknown>;
+		const message =
+			(typeof errorObj.message === "string" ? errorObj.message : null) ||
+			(typeof errorObj.error === "string" ? errorObj.error : null) ||
+			JSON.stringify(error);
+
+		const err = new Error(message) as StackError;
+		// Preserve other properties (status, code, etc.)
+		Object.assign(err, error);
+
+		const statusCode =
+			typeof errorObj.statusCode === "number"
+				? errorObj.statusCode
+				: typeof errorObj.status === "number"
+					? errorObj.status
+					: undefined;
+		if (statusCode !== undefined) {
+			err.statusCode = statusCode;
+		}
+
+		const fieldErrors = isFieldErrorRecord(errorObj.errors)
+			? errorObj.errors
+			: issuesToFieldErrors(errorObj.issues);
+		if (fieldErrors) {
+			err.errors = fieldErrors;
+		} else {
+			// Object.assign may have copied a non-conforming `errors` property
+			err.errors = undefined;
+		}
+
+		return err;
+	}
+
+	// Fallback for primitive values
+	return new Error(String(error));
+}

package/src/plugins/client/resource/hooks.tsx

@@ -0,0 +1,285 @@
+"use client";
+
+/**
+ * `createResource` — generates the repetitive React Query plumbing for a
+ * plugin's resources from a single declaration: plain queries, suspense
+ * queries, infinite queries, mutations with invalidation, plus `useForm`
+ * and `useSelect` per resource.
+ *
+ * The same declaration feeds `createResourceQueryKeys` (see `./queries`),
+ * so SSR loaders and SSG `prefetchForRoute` keys stay in sync with hooks.
+ *
+ * @example
+ * ```ts
+ * const blog = createResource({ plugin: "blog", resources: blogResources });
+ *
+ * export const usePost = (slug?: string) =>
+ *   blog.posts.detail.use([slug ?? ""], { enabled: !!slug });
+ * export const useCreatePost = () => blog.posts.create.use();
+ * ```
+ */
+
+import {
+	useInfiniteQuery,
+	useQuery,
+	useSuspenseInfiniteQuery,
+	useSuspenseQuery,
+	type InfiniteData,
+	type UseInfiniteQueryResult,
+	type UseMutationResult,
+	type UseQueryResult,
+	type UseSuspenseInfiniteQueryResult,
+	type UseSuspenseQueryResult,
+} from "@tanstack/react-query";
+import { SHARED_QUERY_CONFIG } from "./errors";
+import {
+	buildQueryKey,
+	resolvePageSize,
+	runResourceQuery,
+	type ResourceDef,
+	type ResourceMutationDef,
+	type ResourceMutationResult,
+	type ResourceMutationVars,
+	type ResourceQueryArgs,
+	type ResourceQueryData,
+	type ResourceQueryDef,
+	type ResourcesDeclaration,
+} from "./queries";
+import { useResourceContext, useResourceMutationForDef } from "./internal";
+import {
+	createUseForm,
+	type ResourceFormConfig,
+	type ResourceFormResult,
+} from "./use-form";
+import {
+	createUseSelect,
+	type ResourceSelectConfig,
+	type ResourceSelectResult,
+} from "./use-select";
+
+/** Per-call options for generated query hooks. */
+export interface ResourceQueryOptions {
+	enabled?: boolean;
+}
+
+/** Hooks generated for a non-infinite query declaration. */
+export interface ResourcePlainQueryHooks<
+	TArgs extends readonly unknown[],
+	TData,
+> {
+	use(
+		args?: TArgs,
+		options?: ResourceQueryOptions,
+	): UseQueryResult<TData, Error>;
+	/** Suspense variant — re-throws refetch errors for Error Boundaries */
+	useSuspense(args?: TArgs): UseSuspenseQueryResult<TData, Error>;
+}
+
+/** Hooks generated for an infinite query declaration. */
+export interface ResourceInfiniteQueryHooks<
+	TArgs extends readonly unknown[],
+	TData,
+> {
+	useInfinite(
+		args?: TArgs,
+		options?: ResourceQueryOptions,
+	): UseInfiniteQueryResult<InfiniteData<TData, number>, Error>;
+	/** Suspense variant — re-throws refetch errors for Error Boundaries */
+	useSuspenseInfinite(
+		args?: TArgs,
+	): UseSuspenseInfiniteQueryResult<InfiniteData<TData, number>, Error>;
+}
+
+/** Dispatches to the plain or infinite hook set based on the declaration. */
+export type ResourceQueryHooks<TDef> = TDef extends { infinite: true }
+	? ResourceInfiniteQueryHooks<ResourceQueryArgs<TDef>, ResourceQueryData<TDef>>
+	: ResourcePlainQueryHooks<ResourceQueryArgs<TDef>, ResourceQueryData<TDef>>;
+
+/** Hook generated for a mutation declaration. */
+export interface ResourceMutationHooks<TDef> {
+	use(): UseMutationResult<
+		ResourceMutationResult<TDef>,
+		Error,
+		ResourceMutationVars<TDef>
+	>;
+}
+
+/** The detail-query record type of a resource (used by `useForm` defaults). */
+export type ResourceDetailData<TResource extends ResourceDef> =
+	TResource["queries"] extends { detail: infer TDetail }
+		? ResourceQueryData<TDetail>
+		: unknown;
+
+/** The generated handle for a single resource. */
+export type ResourceHandle<TResource extends ResourceDef> = {
+	[Q in keyof TResource["queries"]]: ResourceQueryHooks<
+		TResource["queries"][Q]
+	>;
+} & {
+	[M in keyof NonNullable<TResource["mutations"]>]: ResourceMutationHooks<
+		NonNullable<TResource["mutations"]>[M]
+	>;
+} & {
+	useForm<TValues, TResult = unknown, TRecord = ResourceDetailData<TResource>>(
+		config: ResourceFormConfig<TValues, TRecord, TResult>,
+	): ResourceFormResult<TValues, TRecord, TResult>;
+	useSelect<TItem>(
+		config: ResourceSelectConfig<TItem>,
+	): ResourceSelectResult<TItem>;
+};
+
+/** The generated resource handles, keyed by resource name. */
+export type Resource<TResources extends ResourcesDeclaration> = {
+	[R in keyof TResources]: ResourceHandle<TResources[R]>;
+};
+
+export interface CreateResourceConfig<TResources extends ResourcesDeclaration> {
+	/** Plugin name used to resolve plugin-specific request headers. */
+	plugin: string;
+	resources: TResources;
+}
+
+function createQueryHooks(
+	plugin: string,
+	resourceName: string,
+	queryName: string,
+	def: ResourceQueryDef<any, any>,
+) {
+	const useQueryConfig = (args: readonly unknown[]) => {
+		const context = useResourceContext(plugin);
+		return {
+			queryKey: buildQueryKey(resourceName, queryName, def, args),
+			queryFn: (queryContext?: { pageParam?: unknown }) =>
+				runResourceQuery(
+					context.client,
+					def,
+					args,
+					queryContext?.pageParam,
+					context.headers,
+				),
+			...SHARED_QUERY_CONFIG,
+		};
+	};
+
+	const infiniteExtras = (args: readonly unknown[]) => {
+		const pageSize = resolvePageSize(def, args);
+		return {
+			initialPageParam: 0,
+			getNextPageParam: (lastPage: unknown, allPages: unknown[]) => {
+				if (def.nextPageParam) {
+					return def.nextPageParam(lastPage, allPages, ...args);
+				}
+				const items = (lastPage as unknown[]) ?? [];
+				if (items.length < pageSize) return undefined;
+				return allPages.length * pageSize;
+			},
+		};
+	};
+
+	return {
+		use(args: readonly unknown[] = [], options?: ResourceQueryOptions) {
+			return useQuery({
+				...useQueryConfig(args),
+				...(options?.enabled !== undefined ? { enabled: options.enabled } : {}),
+			});
+		},
+		useSuspense(args: readonly unknown[] = []) {
+			const result = useSuspenseQuery(useQueryConfig(args));
+			// useSuspenseQuery only throws on initial fetch — manually re-throw
+			// refetch errors so Error Boundaries catch them
+			if (result.error && !result.isFetching) {
+				throw result.error;
+			}
+			return result;
+		},
+		useInfinite(args: readonly unknown[] = [], options?: ResourceQueryOptions) {
+			return useInfiniteQuery({
+				...useQueryConfig(args),
+				...infiniteExtras(args),
+				...(options?.enabled !== undefined ? { enabled: options.enabled } : {}),
+			});
+		},
+		useSuspenseInfinite(args: readonly unknown[] = []) {
+			const result = useSuspenseInfiniteQuery({
+				...useQueryConfig(args),
+				...infiniteExtras(args),
+			});
+			if (result.error && !result.isFetching) {
+				throw result.error;
+			}
+			return result;
+		},
+	};
+}
+
+function createMutationHook(
+	plugin: string,
+	resourceName: string,
+	mutationName: string,
+	resource: ResourceDef,
+	def: ResourceMutationDef<any, any>,
+) {
+	return {
+		use() {
+			const context = useResourceContext(plugin);
+			return useResourceMutationForDef(
+				context,
+				resourceName,
+				mutationName,
+				resource,
+				def,
+			);
+		},
+	};
+}
+
+/**
+ * Generates the full hook surface for a plugin's resources.
+ *
+ * Hooks resolve API and router wiring from `StackProvider`, plus any
+ * plugin-specific request headers, at render time so the declaration can
+ * live at module scope.
+ */
+export function createResource<const TResources extends ResourcesDeclaration>(
+	config: CreateResourceConfig<TResources>,
+): Resource<TResources> {
+	const { plugin, resources } = config;
+	const handles: Record<string, any> = {};
+
+	for (const [resourceName, resource] of Object.entries(resources)) {
+		const handle: Record<string, any> = {};
+
+		for (const [queryName, def] of Object.entries(resource.queries)) {
+			handle[queryName] = createQueryHooks(
+				plugin,
+				resourceName,
+				queryName,
+				def,
+			);
+		}
+
+		for (const [mutationName, def] of Object.entries(
+			resource.mutations ?? {},
+		)) {
+			if (handle[mutationName]) {
+				throw new Error(
+					`Resource "${resourceName}" declares both a query and a mutation named "${mutationName}"`,
+				);
+			}
+			handle[mutationName] = createMutationHook(
+				plugin,
+				resourceName,
+				mutationName,
+				resource,
+				def,
+			);
+		}
+
+		handle.useForm = createUseForm(plugin, resourceName, resource);
+		handle.useSelect = createUseSelect(plugin, resourceName, resource);
+
+		handles[resourceName] = handle;
+	}
+
+	return handles as Resource<TResources>;
+}

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

@@ -0,0 +1,136 @@
+"use client";
+
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import type { UseMutationResult } from "@tanstack/react-query";
+import { usePluginOverrides, useStack } from "../../../context";
+import { createApiClient } from "../../utils";
+import {
+	buildQueryKey,
+	runResourceMutation,
+	type ResourceClient,
+	type ResourceDef,
+	type ResourceMutationDef,
+} from "./queries";
+
+/**
+ * Plugin-specific request options consumed by the resource layer.
+ */
+export interface ResourceOverrides {
+	headers?: HeadersInit;
+}
+
+export interface ResourceContext {
+	client: ResourceClient;
+	headers?: HeadersInit;
+	navigate?: (path: string) => void | Promise<void>;
+	refresh?: () => void | Promise<void>;
+}
+
+/** Resolves the plugin overrides and builds the better-call client. */
+export function useResourceContext(plugin: string): ResourceContext {
+	const { api, router } = useStack();
+	const { headers } = usePluginOverrides<ResourceOverrides>(plugin);
+	const client = createApiClient({
+		baseURL: api?.baseURL,
+		basePath: api?.basePath,
+	});
+	return {
+		client,
+		headers,
+		navigate: router?.navigate,
+		refresh: router?.refresh,
+	};
+}
+
+/**
+ * Splits an `invalidates` target (`"posts"` or `"posts.list"`) into a
+ * query-key prefix.
+ */
+function invalidateTargetToKey(target: string): readonly unknown[] {
+	const dotIndex = target.indexOf(".");
+	if (dotIndex === -1) return [target];
+	return [target.slice(0, dotIndex), target.slice(dotIndex + 1)];
+}
+
+/**
+ * Shared mutation hook used by both the generated mutation hooks and
+ * `useForm`. When `def` is undefined (e.g. `useForm` on a resource without a
+ * declared `create` mutation), the mutation rejects with a descriptive error.
+ */
+export function useResourceMutationForDef(
+	context: ResourceContext,
+	resourceName: string,
+	mutationName: string,
+	resource: ResourceDef,
+	def: ResourceMutationDef<any, any> | undefined,
+): UseMutationResult<unknown, Error, unknown> {
+	const queryClient = useQueryClient();
+	const { client, headers, refresh } = context;
+
+	return useMutation<unknown, Error, unknown>({
+		mutationKey: [resourceName, mutationName],
+		mutationFn: (vars: unknown) => {
+			if (!def) {
+				throw new Error(
+					`Resource "${resourceName}" has no "${mutationName}" mutation declared`,
+				);
+			}
+			return runResourceMutation(client, def, vars, headers);
+		},
+		onSuccess: async (result, variables) => {
+			if (!def) return;
+
+			// Seed a query cache entry (e.g. detail) from the mutation result
+			if (def.setData) {
+				const keyArgs = def.setData.args(result);
+				const targetName = def.setData.query ?? "detail";
+				const targetDef = resource.queries[targetName];
+				if (keyArgs && targetDef) {
+					const key = buildQueryKey(
+						resourceName,
+						targetName,
+						targetDef,
+						keyArgs,
+					);
+					queryClient.setQueryData(key, (previous) =>
+						def.setData?.updater
+							? def.setData.updater(previous, result)
+							: result,
+					);
+				}
+			}
+
+			// Remove a cache entry tied to the successful mutation variables
+			if (def.removeData) {
+				const keyArgs = def.removeData.args(result, variables);
+				const targetName = def.removeData.query ?? "detail";
+				const targetDef = resource.queries[targetName];
+				if (keyArgs && targetDef) {
+					queryClient.removeQueries({
+						queryKey: buildQueryKey(
+							resourceName,
+							targetName,
+							targetDef,
+							keyArgs,
+						),
+						exact: true,
+					});
+				}
+			}
+
+			// Invalidate declared key prefixes — awaited, in declaration order
+			for (const target of def.invalidates ?? []) {
+				await queryClient.invalidateQueries({
+					queryKey: invalidateTargetToKey(target),
+					refetchType: def.refetchType,
+				});
+			}
+
+			// Refresh server-side cache (e.g. Next.js router cache) unless the
+			// mutation opts out (public mutations whose success UI is client state)
+			if (refresh && def.refresh !== false) {
+				await refresh();
+			}
+		},
+	});
+}