@btst/stack 2.12.2 → 3.0.0-rc.1

package/src/plugins/utils.ts

@@ -1,24 +1,7 @@
 import { createClient } from "better-call/client";
 
-/**
- * Runs a hook with backward-compatible denial handling.
- * Hooks may deny by returning a falsy value (old) or throwing (new).
- * Both are normalized to an HTTP error via `createError` (`ctx.error`).
- * Returns the hook's result so transform hooks can apply mutations.
- *
- * ## Migration note (v2.4 → v2.5)
- *
- * Old-style hooks signalled denial by returning `false` and allowance by returning `true`.
- * Pre-shim call sites used `if (!result)` which treated `undefined` (fall-through) as deny.
- * New-style hooks throw an Error to deny and return void/undefined to allow.
- *
- * The shim detects old-style boolean returns at runtime and emits a deprecation warning so
- * that any hook with a code path returning a boolean is surfaced immediately. Hooks that fall
- * through to `undefined` on **every** code path (no boolean return anywhere) cannot be
- * distinguished from new-style void hooks — those hooks must be audited manually and updated
- * to throw explicitly when they intend to deny access.
- */
-export async function runHookWithShim<T>(
+/** Runs a hook and normalizes thrown values to an HTTP error. */
+export async function runHook<T>(
 	hookFn: () => Promise<T> | T,
 	createError: (
 		status: keyof typeof statusCodes | Status,
@@ -26,69 +9,14 @@ export async function runHookWithShim<T>(
 	) => any,
 	defaultMessage: string,
 	errorStatus = 403 as keyof typeof statusCodes | Status,
-): Promise<Exclude<Awaited<T>, false>> {
-	let result: Awaited<T>;
+): Promise<Awaited<T>> {
 	try {
-		result = await hookFn();
+		return await hookFn();
 	} catch (e) {
 		throw createError(errorStatus, {
 			message: e instanceof Error ? e.message : defaultMessage,
 		});
 	}
-	// Detect old-style boolean returns (pre-v2.5 pattern).
-	// Emitting a warning here is the only reliable way to surface hooks that still rely on
-	// boolean returns — including hooks where one branch returns `false` and another falls
-	// through to `undefined`, which was previously denied by `if (!result)` at the call site
-	// but would now silently allow if the warning is not acted on.
-	if (typeof result === "boolean") {
-		if (process.env.NODE_ENV !== "production") {
-			console.warn(
-				`[btst] A lifecycle hook returned a boolean (${result}). ` +
-					`Boolean returns are deprecated — throw an Error to deny access instead. ` +
-					`IMPORTANT: any code path in this hook that falls through to undefined ` +
-					`now ALLOWS access (previously denied). ` +
-					`Update the hook to throw new Error("Unauthorized") to deny.`,
-			);
-		}
-		if (!result) {
-			throw createError(errorStatus, { message: defaultMessage });
-		}
-	}
-	return result as Exclude<Awaited<T>, false>;
-}
-
-/**
- * Client-side equivalent of runHookWithShim — throws a plain Error instead of an HTTP error.
- * Hooks may deny by returning false (old) or throwing (new); both normalize to an Error.
- *
- * See `runHookWithShim` for the full migration note on boolean-vs-void semantics.
- */
-export async function runClientHookWithShim<T>(
-	hookFn: () => Promise<T> | T,
-	defaultMessage: string,
-): Promise<Exclude<Awaited<T>, false>> {
-	let result: Awaited<T>;
-	try {
-		result = await hookFn();
-	} catch (e) {
-		throw e instanceof Error ? e : new Error(defaultMessage);
-	}
-	// Detect old-style boolean returns and warn; see runHookWithShim for rationale.
-	if (typeof result === "boolean") {
-		if (process.env.NODE_ENV !== "production") {
-			console.warn(
-				`[btst] A lifecycle hook returned a boolean (${result}). ` +
-					`Boolean returns are deprecated — throw an Error to deny access instead. ` +
-					`IMPORTANT: any code path in this hook that falls through to undefined ` +
-					`now ALLOWS access (previously denied). ` +
-					`Update the hook to throw new Error("Unauthorized") to deny.`,
-			);
-		}
-		if (!result) {
-			throw new Error(defaultMessage);
-		}
-	}
-	return result as Exclude<Awaited<T>, false>;
 }
 
 /**

package/src/react-router/handlers.ts

@@ -0,0 +1,26 @@
+import type { StackRequestHandler } from "../shared/entry-factories";
+
+/**
+ * Wires a BTST API handler to the `loader`/`action` exports a React Router
+ * catch-all API route needs.
+ *
+ * Note: React Router's build cannot strip destructured exports from route
+ * modules, so export the fields individually rather than destructuring.
+ *
+ * @example
+ * ```ts
+ * // app/routes/api/data/$.ts
+ * import { toReactRouterHandlers } from "@btst/stack/react-router";
+ * import { handler } from "~/lib/stack";
+ *
+ * const handlers = toReactRouterHandlers(handler);
+ * export const loader = handlers.loader;
+ * export const action = handlers.action;
+ * ```
+ */
+export function toReactRouterHandlers(handler: StackRequestHandler) {
+	return {
+		loader: ({ request }: { request: Request }) => handler(request),
+		action: ({ request }: { request: Request }) => handler(request),
+	};
+}

package/src/react-router/index.tsx

@@ -0,0 +1,11 @@
+export { toReactRouterHandlers } from "./handlers";
+export {
+	type CreateReactRouterPageOptions,
+	type ReactRouterPageLoaderArgs,
+	createReactRouterPage,
+} from "./page";
+export { reactRouter } from "./router";
+export type {
+	GetStackClient,
+	StackRequestHandler,
+} from "../shared/entry-factories";

package/src/react-router/page.tsx

@@ -0,0 +1,139 @@
+import {
+	HydrationBoundary,
+	dehydrate,
+	useQueryClient,
+} from "@tanstack/react-query";
+import type { DehydrateOptions, QueryClient } from "@tanstack/react-query";
+import type { ComponentType, ReactNode } from "react";
+import { useMemo } from "react";
+import { useLoaderData, useRouteError } from "react-router";
+import { normalizePath } from "../client/path-utils";
+import {
+	type GetStackClient,
+	stackDehydrateOptions,
+} from "../shared/entry-factories";
+
+/**
+ * Loose structural form of React Router's generated `Route.LoaderArgs` /
+ * `Route.MetaArgs` for a catch-all route. The generated `./+types/$` types
+ * are not available inside the library, so the factory types the subset it
+ * uses; the results remain assignable to the generated route exports.
+ */
+export interface ReactRouterPageLoaderArgs {
+	params: { "*"?: string } & Record<string, string | undefined>;
+}
+
+export interface CreateReactRouterPageOptions {
+	/** Returns the stack client for a given QueryClient (`lib/stack-client`). */
+	getStackClient: GetStackClient;
+	/** Returns the QueryClient for the current context (`lib/query-client`). */
+	getQueryClient: () => QueryClient;
+	/** Rendered when no route matches. Defaults to a "Route not found" div. */
+	NotFound?: ComponentType;
+	/**
+	 * Rendered when the route errors. Defaults to a `<pre>` with the
+	 * stringified error — provide your own component for a production-safe
+	 * error UI (use `useRouteError()` from react-router to read the error).
+	 */
+	ErrorBoundary?: ComponentType;
+	/** Wraps the rendered page (inside the `HydrationBoundary`). */
+	wrapPage?: (page: ReactNode) => ReactNode;
+	/**
+	 * Options passed to `dehydrate()`. Defaults to dehydrating failed queries
+	 * in addition to the React Query defaults, so the client does not refetch
+	 * queries that errored during SSR. Override e.g. to sanitize error
+	 * payloads before they are serialized into the HTML.
+	 */
+	dehydrateOptions?: DehydrateOptions;
+}
+
+/**
+ * Creates the React Router catch-all route pieces for BTST plugin routes:
+ * SSR prefetch via `route.loader()`, React Query dehydration (including
+ * failed queries), and loader-before-meta ordering.
+ *
+ * @example
+ * ```tsx
+ * // app/routes/pages/$.tsx
+ * import { createReactRouterPage } from "@btst/stack/react-router";
+ * import { getOrCreateQueryClient } from "~/lib/query-client";
+ * import { getStackClient } from "~/lib/stack-client";
+ *
+ * const page = createReactRouterPage({ getStackClient, getQueryClient: getOrCreateQueryClient });
+ * export const loader = page.loader;
+ * export const meta = page.meta;
+ * export default page.Component;
+ * ```
+ */
+export function createReactRouterPage(options: CreateReactRouterPageOptions) {
+	const {
+		getStackClient,
+		getQueryClient,
+		NotFound,
+		ErrorBoundary: CustomErrorBoundary,
+		wrapPage,
+		dehydrateOptions = stackDehydrateOptions,
+	} = options;
+
+	async function loader({ params }: ReactRouterPageLoaderArgs) {
+		const queryClient = getQueryClient();
+		const path = normalizePath(params["*"]);
+		const route = getStackClient(queryClient).router.getRoute(path);
+
+		if (route?.loader) {
+			await route.loader();
+		}
+
+		return {
+			path,
+			dehydratedState: dehydrate(queryClient, dehydrateOptions),
+			meta: await route?.meta?.(),
+		};
+	}
+
+	type LoaderData = Awaited<ReturnType<typeof loader>>;
+
+	// Recent React Router versions pass `loaderData`; older 7.x used `data`.
+	function meta(args: { loaderData?: LoaderData; data?: LoaderData }) {
+		return (args.loaderData ?? args.data)?.meta;
+	}
+
+	function Component() {
+		const data = useLoaderData<typeof loader>();
+		const queryClient = useQueryClient();
+		// Memoized so PageComponent keeps a stable identity across re-renders:
+		// getRoute() invokes the route handler, which produces new component
+		// references each call. Without the memo, any router state change that
+		// re-renders this component (e.g. a search-param update) would remount
+		// the whole page subtree, losing component state such as open dialogs.
+		const route = useMemo(
+			() => getStackClient(queryClient).router.getRoute(data.path),
+			[queryClient, data.path],
+		);
+		const page = route?.PageComponent ? (
+			<route.PageComponent />
+		) : NotFound ? (
+			<NotFound />
+		) : (
+			<div>Route not found</div>
+		);
+
+		return (
+			<HydrationBoundary state={data.dehydratedState}>
+				{wrapPage ? wrapPage(page) : page}
+			</HydrationBoundary>
+		);
+	}
+
+	function DefaultErrorBoundary() {
+		const error = useRouteError();
+		return <pre>{String(error)}</pre>;
+	}
+
+	return {
+		loader,
+		meta,
+		Component,
+		ErrorBoundary: CustomErrorBoundary ?? DefaultErrorBoundary,
+	};
+}

package/src/react-router/router.tsx

@@ -0,0 +1,63 @@
+"use client";
+import { useMemo } from "react";
+import {
+	Link as ReactRouterLink,
+	useNavigate,
+	useRevalidator,
+	useSearchParams,
+} from "react-router";
+import type { StackRouter, StackRouterConfig } from "../context/router";
+
+function ReactRouterLinkWrapper({
+	href,
+	children,
+	...props
+}: React.ComponentProps<"a"> & Record<string, any>) {
+	return (
+		<ReactRouterLink to={href || ""} {...props}>
+			{children}
+		</ReactRouterLink>
+	);
+}
+
+function useReactRouterStackRouter(): StackRouter {
+	const navigate = useNavigate();
+	const { revalidate } = useRevalidator();
+	const [searchParams, setSearchParams] = useSearchParams();
+
+	return useMemo(
+		() => ({
+			navigate: (path: string) => {
+				void navigate(path);
+			},
+			refresh: () => {
+				void revalidate();
+			},
+			getSearchParams: () => new URLSearchParams(searchParams),
+			setSearchParams: (
+				next: URLSearchParams,
+				opts?: { replace?: boolean },
+			) => {
+				setSearchParams(next, { replace: opts?.replace });
+			},
+		}),
+		[navigate, revalidate, searchParams, setSearchParams],
+	);
+}
+
+/**
+ * Router preset for React Router (v7).
+ *
+ * @example
+ * ```tsx
+ * import { reactRouter } from "@btst/stack/react-router";
+ *
+ * <StackProvider basePath="/pages" router={reactRouter()} api={{ baseURL, basePath: "/api/data" }}>
+ * ```
+ */
+export function reactRouter(): StackRouterConfig {
+	return {
+		Link: ReactRouterLinkWrapper,
+		useRouter: useReactRouterStackRouter,
+	};
+}

package/src/shared/auth-types.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared auth contract types used by both the client provider
+ * (`@btst/stack/context`) and the backend (`@btst/stack/api`).
+ *
+ * This module is intentionally type-only so it can be imported from server
+ * and client code alike.
+ */
+
+/**
+ * The identity of the current user as resolved by an auth provider.
+ * Extra provider-specific fields are allowed.
+ */
+export interface StackIdentity {
+	/** Unique user id */
+	id: string;
+	/** Display name */
+	name?: string;
+	/** Email address */
+	email?: string;
+	/** Avatar image URL */
+	image?: string;
+	/** Additional provider-specific fields */
+	[key: string]: unknown;
+}
+
+/**
+ * A permission check request: "can the current user perform `action` on
+ * `resource`?" (e.g. resource `"blog:post"`, action `"delete"`).
+ */
+export interface CanParams {
+	/** The resource being accessed (e.g. "blog:post", "comments:moderate") */
+	resource: string;
+	/** The action being performed (e.g. "read", "create", "delete") */
+	action: string;
+	/** Optional extra parameters (e.g. the specific record id) */
+	params?: Record<string, unknown>;
+}
+
+/**
+ * Client-side auth provider, passed to `StackProvider` via the `auth` prop.
+ *
+ * All fields besides `getIdentity` are optional:
+ * - Without `can`, every permission check resolves to `true`.
+ * - Without `loginPath`, denied route access is not redirected.
+ *
+ * @example
+ * ```tsx
+ * const authProvider: StackAuthProvider = {
+ *   getIdentity: () => authClient.getSession().then((s) => s?.user ?? null),
+ *   can: ({ resource, action }) => checkPermission(resource, action),
+ *   loginPath: "/login",
+ * };
+ *
+ * <StackProvider auth={authProvider} ...>
+ * ```
+ */
+export interface StackAuthProvider {
+	/**
+	 * Resolve the current user's identity. Return `null` when unauthenticated.
+	 */
+	getIdentity: () => Promise<StackIdentity | null> | StackIdentity | null;
+	/**
+	 * Permission check. When omitted, all `useCan()` / `<CanAccess>` checks
+	 * resolve to `true`.
+	 */
+	can?: (
+		params: CanParams & { identity: StackIdentity | null },
+	) => Promise<boolean> | boolean;
+	/**
+	 * Path unauthenticated users are redirected to when route-level permission
+	 * checks deny access (e.g. "/login").
+	 */
+	loginPath?: string;
+}
+
+/**
+ * Server-side auth provider, passed to `stack()` via the `auth` config option.
+ * `stack()` resolves the identity lazily and at most once per request; plugin
+ * lifecycle hooks can read it via `getRequestIdentity(headers)` from
+ * `@btst/stack/api`.
+ */
+export interface StackServerAuthProvider {
+	/**
+	 * Resolve the identity for an incoming request (e.g. from a session
+	 * cookie). Return `null` when unauthenticated.
+	 */
+	getIdentity: (ctx: {
+		headers: Headers;
+		request: Request;
+	}) => Promise<StackIdentity | null> | StackIdentity | null;
+	/**
+	 * Optional server-side permission check, for consumers and plugins that
+	 * want to share one `can` implementation across lifecycle hooks.
+	 */
+	can?: (
+		params: CanParams & { identity: StackIdentity | null; headers: Headers },
+	) => Promise<boolean> | boolean;
+}

package/src/shared/entry-factories.ts

@@ -0,0 +1,55 @@
+import {
+	type DehydrateOptions,
+	type QueryClient,
+	defaultShouldDehydrateQuery,
+} from "@tanstack/react-query";
+import type { ComponentType } from "react";
+
+/**
+ * Minimal structural view of a route returned by
+ * `createStackClient(...).router.getRoute(path)`. The framework entry
+ * factories only need these three fields.
+ */
+export interface StackRouteLike {
+	PageComponent?: ComponentType<any> | undefined;
+	loader?: ((...args: any[]) => unknown) | undefined;
+	meta?: ((...args: any[]) => any) | undefined;
+}
+
+/**
+ * Minimal structural view of the object returned by `createStackClient`.
+ * Any concrete `ClientLib<TRoutes>` is assignable to this shape.
+ */
+export interface StackClientLike {
+	router: {
+		getRoute: (
+			path: string,
+			queryParams?: Record<string, string | string[]>,
+		) => (StackRouteLike & Record<string, any>) | null | undefined;
+	};
+}
+
+/**
+ * Consumer-provided factory that returns the stack client for a given
+ * QueryClient (per-request on the server, singleton on the client).
+ */
+export type GetStackClient = (queryClient: QueryClient) => StackClientLike;
+
+/**
+ * A framework-agnostic BTST API handler, as returned by
+ * `createBackendHandler(...).handler`.
+ */
+export type StackRequestHandler = (
+	request: Request,
+) => Response | Promise<Response>;
+
+/**
+ * Dehydration config owned by the page factories: dehydrate everything the
+ * default would, plus failed queries, so the client does not refetch (and
+ * flash a loading state) for queries that errored during SSR — regardless of
+ * how the consumer configured their QueryClient.
+ */
+export const stackDehydrateOptions: DehydrateOptions = {
+	shouldDehydrateQuery: (query) =>
+		defaultShouldDehydrateQuery(query) || query.state.status === "error",
+};

package/src/shared/i18n-types.ts

@@ -0,0 +1,31 @@
+/**
+ * Optional i18n provider, passed to `StackProvider` via the `i18n` prop.
+ *
+ * Without a provider, `useTranslate()` returns the default English string with
+ * `{{param}}` interpolation — zero setup cost for English-only apps.
+ *
+ * @example
+ * ```tsx
+ * const i18n: StackI18nProvider = {
+ *   translate: (key, defaultValue, params) =>
+ *     t(key, { defaultValue, ...params }),
+ * };
+ *
+ * <StackProvider i18n={i18n} ...>
+ * ```
+ */
+export interface StackI18nProvider {
+	/**
+	 * Translate a namespaced key. Receives the English default and optional
+	 * interpolation params when no translation exists for the key.
+	 */
+	translate: (
+		key: string,
+		defaultValue: string,
+		params?: Record<string, unknown>,
+	) => string;
+	/** Return the active locale (optional) */
+	getLocale?: () => string;
+	/** Switch locale (optional) */
+	changeLocale?: (locale: string) => void;
+}

package/src/shared/interpolate.ts

@@ -0,0 +1,14 @@
+/**
+ * Replace `{{key}}` placeholders in a template with stringified param values.
+ */
+export function interpolate(
+	template: string,
+	params?: Record<string, unknown>,
+): string {
+	if (!params) return template;
+
+	return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => {
+		const value = params[key];
+		return value == null ? "" : String(value);
+	});
+}

package/src/shared/list-state.ts

@@ -0,0 +1,147 @@
+import { interpolate } from "./interpolate";
+
+export type ListStateFieldType = "string" | "number" | "boolean";
+
+export interface ListStateField<
+	T extends ListStateFieldType = ListStateFieldType,
+> {
+	type: T;
+	default: T extends "string" ? string : T extends "number" ? number : boolean;
+	/**
+	 * How URL history is updated when this field changes.
+	 * - `"push"` (default): discrete changes (tab switch, page change) — back button undoes.
+	 * - `"replace"`: rapid changes (typing in a filter) — no extra history entries.
+	 */
+	history?: "push" | "replace";
+}
+
+export type ListStateSchema = Record<string, ListStateField>;
+
+export type InferListStateValue<F extends ListStateField> =
+	F["type"] extends "string"
+		? string
+		: F["type"] extends "number"
+			? number
+			: boolean;
+
+export type InferListState<S extends ListStateSchema> = {
+	[K in keyof S]: InferListStateValue<S[K]>;
+};
+
+/**
+ * URL query param key for a list-state field.
+ * The `namespace` argument identifies the hook instance for SSR helpers but
+ * does not prefix URL keys — field names are used directly (e.g. `?tab=spam`).
+ */
+export function listStateParamKey(
+	_namespace: string,
+	fieldKey: string,
+): string {
+	return fieldKey;
+}
+
+function parseFieldValue<F extends ListStateField>(
+	field: F,
+	raw: string | null,
+): InferListStateValue<F> {
+	if (raw == null || raw === "") {
+		return field.default as InferListStateValue<F>;
+	}
+
+	switch (field.type) {
+		case "number": {
+			const parsed = Number(raw);
+			return (
+				Number.isFinite(parsed) ? parsed : field.default
+			) as InferListStateValue<F>;
+		}
+		case "boolean":
+			return (raw === "true") as InferListStateValue<F>;
+		default:
+			return raw as InferListStateValue<F>;
+	}
+}
+
+function serializeFieldValue(value: unknown): string {
+	return String(value);
+}
+
+function valuesEqual(a: unknown, b: unknown): boolean {
+	return a === b;
+}
+
+/**
+ * Parse list state from URL search params (SSR-safe — pass the request URL's
+ * search string or a `URLSearchParams` instance).
+ */
+export function parseListStateFromSearchParams<S extends ListStateSchema>(
+	namespace: string,
+	schema: S,
+	searchParams: URLSearchParams | string,
+): InferListState<S> {
+	const params =
+		typeof searchParams === "string"
+			? new URLSearchParams(searchParams)
+			: searchParams;
+
+	const state = {} as InferListState<S>;
+
+	for (const fieldKey of Object.keys(schema) as Array<keyof S & string>) {
+		const field = schema[fieldKey]!;
+		const paramKey = listStateParamKey(namespace, fieldKey);
+		state[fieldKey as keyof S] = parseFieldValue(
+			field,
+			params.get(paramKey),
+		) as InferListState<S>[keyof S];
+	}
+
+	return state;
+}
+
+/**
+ * Serialize list state into URL search params. Default values are omitted for
+ * clean URLs.
+ */
+export function serializeListStateToSearchParams<S extends ListStateSchema>(
+	namespace: string,
+	schema: S,
+	state: InferListState<S>,
+	baseParams?: URLSearchParams,
+): URLSearchParams {
+	const params = new URLSearchParams(baseParams?.toString());
+
+	for (const fieldKey of Object.keys(schema) as Array<keyof S & string>) {
+		const field = schema[fieldKey]!;
+		const paramKey = listStateParamKey(namespace, fieldKey);
+		const value = state[fieldKey as keyof S];
+
+		if (valuesEqual(value, field.default)) {
+			params.delete(paramKey);
+		} else {
+			params.set(paramKey, serializeFieldValue(value));
+		}
+	}
+
+	return params;
+}
+
+/**
+ * Decide whether a list-state update should use `replace` or `push` history.
+ */
+export function resolveListStateHistoryMode<S extends ListStateSchema>(
+	schema: S,
+	updates: Partial<InferListState<S>>,
+	explicit?: boolean,
+): boolean {
+	if (explicit !== undefined) return explicit;
+
+	for (const fieldKey of Object.keys(updates) as Array<keyof S & string>) {
+		if (schema[fieldKey]?.history === "replace") {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+export { interpolate };