@btst/stack 2.12.1 → 3.0.0-rc.1

package/src/api/index.ts

@@ -6,10 +6,77 @@ import type {
 	PluginApis,
 	StackContext,
 } from "../types";
+import type {
+	StackIdentity,
+	StackServerAuthProvider,
+} from "../shared/auth-types";
 import { defineDb } from "@btst/db";
 
 export { toNodeHandler } from "better-call/node";
 
+/**
+ * Lazy, memoized identity resolvers keyed by the request's `Headers`
+ * instance. better-call passes the same `Headers` object from the incoming
+ * `Request` into every endpoint context, so lifecycle hooks can look the
+ * identity up via `getRequestIdentity(ctx.headers)`. Entries are
+ * garbage-collected with the request.
+ */
+const identityResolvers = new WeakMap<
+	Headers,
+	() => Promise<StackIdentity | null>
+>();
+
+function registerIdentityResolver(
+	request: Request,
+	auth: StackServerAuthProvider,
+): void {
+	let cached: Promise<StackIdentity | null> | undefined;
+	identityResolvers.set(request.headers, () => {
+		// Mirror the client-side StackAuthBoundary: a failing getIdentity is
+		// treated as unauthenticated (null) rather than rejecting, so hooks
+		// written without try/catch can't fail the whole request.
+		cached ??= Promise.resolve()
+			.then(() => auth.getIdentity({ headers: request.headers, request }))
+			.then((identity) => identity ?? null)
+			.catch((error) => {
+				console.error("[btst/auth] getIdentity() failed:", error);
+				return null;
+			});
+		return cached;
+	});
+}
+
+/**
+ * Returns the identity of the request that carried these headers, as resolved
+ * by the `auth` provider configured on `stack()`.
+ *
+ * The provider's `getIdentity` runs at most once per request (memoized), no
+ * matter how many hooks call this. Returns `null` when no auth provider is
+ * configured, when called outside a request handled by `stack().handler`, or
+ * when the user is unauthenticated.
+ *
+ * @example
+ * ```ts
+ * import { getRequestIdentity } from "@btst/stack/api";
+ *
+ * const blogBackend = blogBackendPlugin({
+ *   hooks: {
+ *     onBeforeCreatePost: async (data, ctx) => {
+ *       const identity = await getRequestIdentity(ctx.headers);
+ *       if (!identity) throw new Error("Unauthorized");
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export async function getRequestIdentity(
+	// Optional because better-call types endpoint `ctx.headers` as optional.
+	headers: Headers | undefined,
+): Promise<StackIdentity | null> {
+	const resolve = headers ? identityResolvers.get(headers) : undefined;
+	return resolve ? resolve() : null;
+}
+
 /**
  * Creates the backend library with plugin support
  *
@@ -37,7 +104,7 @@ export function stack<
 >(
 	config: BackendLibConfig<TPlugins>,
 ): BackendLib<TRoutes, PluginApis<TPlugins>> {
-	const { plugins, adapter, dbSchema, basePath } = config;
+	const { plugins, adapter, dbSchema, basePath, auth } = config;
 
 	// Collect all routes from all plugins with type-safe prefixed keys
 	const allRoutes = {} as TRoutes;
@@ -57,6 +124,7 @@ export function stack<
 		plugins,
 		basePath,
 		adapter: adapterInstance,
+		auth,
 	};
 
 	for (const [pluginKey, plugin] of Object.entries(plugins)) {
@@ -83,8 +151,18 @@ export function stack<
 		basePath: basePath,
 	});
 
+	// With an auth provider, register a per-request identity resolver before
+	// dispatch so hooks can call getRequestIdentity(ctx.headers). Without one,
+	// the handler is returned untouched.
+	const handler = auth
+		? (request: Request) => {
+				registerIdentityResolver(request, auth);
+				return router.handler(request);
+			}
+		: router.handler;
+
 	return {
-		handler: router.handler,
+		handler,
 		router,
 		dbSchema: betterDbSchema,
 		adapter: adapterInstance,
@@ -99,3 +177,9 @@ export type {
 	PluginApis,
 	StackContext,
 } from "../types";
+
+export type {
+	CanParams,
+	StackIdentity,
+	StackServerAuthProvider,
+} from "../shared/auth-types";

package/src/client/components/compose.tsx

@@ -1,8 +1,11 @@
 "use client";
 
-import React, { Suspense, type ErrorInfo } from "react";
+import React, { Suspense, useEffect, type ErrorInfo } from "react";
 import { type FallbackProps } from "react-error-boundary";
 import type { createRouter } from "@btst/yar";
+import { useAuthContext, useCan } from "../../context/auth";
+import { useStackOrNull } from "../../context/provider";
+import type { CanParams } from "../../shared/auth-types";
 import { ErrorBoundary } from "./error-boundary";
 
 /**
@@ -38,8 +41,13 @@ export function RouteRenderer({
 	onError: (error: Error, info: ErrorInfo) => void;
 	props?: any;
 }) {
-	// Resolve route on the client where components are available
-	const route = router.getRoute(path);
+	// Resolve route on the client where components are available.
+	// 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, React would treat every parent
+	// re-render as a component type change and remount the whole subtree
+	// (losing state and re-triggering Suspense).
+	const route = React.useMemo(() => router.getRoute(path), [router, path]);
 
 	return (
 		<ComposedRoute
@@ -55,6 +63,70 @@ export function RouteRenderer({
 	);
 }
 
+/**
+ * Route-level permission gate used by `ComposedRoute` when a `permission`
+ * is declared.
+ *
+ * - Without an auth provider on `StackProvider`, renders children unchanged.
+ * - While the identity/permission check is pending, renders the route's
+ *   `LoadingComponent` so gated content never flashes.
+ * - On deny: unauthenticated users are redirected to the provider's
+ *   `loginPath` (via the top-level router's `navigate`, falling back to
+ *   `window.location.assign`); authenticated users get an `Unauthorized`
+ *   error thrown into the route's ErrorBoundary.
+ */
+function RouteGuard({
+	permission,
+	LoadingComponent,
+	children,
+}: {
+	permission: CanParams;
+	LoadingComponent?: React.ComponentType;
+	children: React.ReactNode;
+}) {
+	const auth = useAuthContext();
+	const stack = useStackOrNull();
+	const { can, isPending } = useCan(permission);
+
+	const identity = auth?.identity ?? null;
+	const loginPath = auth?.provider.loginPath;
+	const navigate = stack?.router?.navigate;
+
+	const shouldRedirect =
+		!!auth && !isPending && !can && !identity && !!loginPath;
+
+	useEffect(() => {
+		if (!shouldRedirect || !loginPath) return;
+		if (navigate) {
+			void navigate(loginPath);
+		} else if (typeof window !== "undefined") {
+			window.location.assign(loginPath);
+		}
+	}, [shouldRedirect, loginPath, navigate]);
+
+	// No auth provider configured: gating is disabled, behave exactly as before.
+	if (!auth) {
+		return <>{children}</>;
+	}
+
+	if (isPending || shouldRedirect) {
+		return LoadingComponent ? <LoadingComponent /> : null;
+	}
+
+	if (can) {
+		return <>{children}</>;
+	}
+
+	// Keep the thrown message generic — ErrorComponents commonly render
+	// error.message to end-users; the resource/action detail is dev-only.
+	if (process.env.NODE_ENV !== "production") {
+		console.warn(
+			`[btst/auth] RouteGuard denied: cannot ${permission.action} ${permission.resource}`,
+		);
+	}
+	throw new Error("Unauthorized");
+}
+
 /**
  * Renders a route with Suspense and ErrorBoundary wrappers.
  * Handles loading states, error boundaries, and not-found scenarios for a single route.
@@ -65,8 +137,14 @@ export function RouteRenderer({
  * @param LoadingComponent - Component to show during suspense
  * @param onNotFound - Optional callback when route is not found
  * @param NotFoundComponent - Optional component to show for 404s
- * @param props - Additional props to pass to the page component
+ * @param props - Additional props to pass to the page component. For routes
+ *   created with `defineRoute`, these are merged after the route context, so
+ *   a prop named `params` or `query` intentionally takes precedence over the
+ *   router-extracted values. Only pass trusted, framework-controlled values.
  * @param onError - Error handler callback for the error boundary
+ * @param permission - Optional route-level permission requirement (e.g.
+ *   `{ resource: "blog:draft", action: "read" }`). Only enforced when an
+ *   auth provider is configured on `StackProvider`; see `RouteGuard`.
  */
 export function ComposedRoute({
 	path,
@@ -77,6 +155,7 @@ export function ComposedRoute({
 	NotFoundComponent,
 	props,
 	onError,
+	permission,
 }: {
 	path: string;
 	PageComponent: React.ComponentType<any>;
@@ -86,9 +165,16 @@ export function ComposedRoute({
 	NotFoundComponent?: React.ComponentType<{ message: string }>;
 	props?: any;
 	onError: (error: Error, info: ErrorInfo) => void;
+	permission?: CanParams;
 }) {
 	if (PageComponent) {
-		const content = <PageComponent {...props} />;
+		const content = permission ? (
+			<RouteGuard permission={permission} LoadingComponent={LoadingComponent}>
+				<PageComponent {...props} />
+			</RouteGuard>
+		) : (
+			<PageComponent {...props} />
+		);
 		// Always provide the same fallback on server and client — using
 		// `typeof window !== "undefined"` here would produce a different JSX tree
 		// on each side, shifting React's useId() counter and causing hydration

package/src/client/hooks/use-list-state.ts

@@ -0,0 +1,260 @@
+"use client";
+import { useCallback, useState, useSyncExternalStore } from "react";
+import { useStackOrNull } from "../../context/provider";
+import type { InferListState, ListStateSchema } from "../../shared/list-state";
+import {
+	parseListStateFromSearchParams,
+	resolveListStateHistoryMode,
+	serializeListStateToSearchParams,
+} from "../../shared/list-state";
+
+export type {
+	InferListState,
+	ListStateField,
+	ListStateSchema,
+} from "../../shared/list-state";
+export {
+	listStateParamKey,
+	parseListStateFromSearchParams,
+	serializeListStateToSearchParams,
+} from "../../shared/list-state";
+
+export type SetListStateOptions = {
+	/** Force `replace` vs `push` history semantics for this update */
+	replace?: boolean;
+};
+
+export type SetListState<S extends ListStateSchema> = (
+	updates:
+		| Partial<InferListState<S>>
+		| ((prev: InferListState<S>) => Partial<InferListState<S>>),
+	options?: SetListStateOptions,
+) => void;
+
+interface PendingUpdate {
+	namespace: string;
+	schema: ListStateSchema;
+	patch: Record<string, unknown>;
+	explicitReplace: boolean | undefined;
+	getSearchParams: () => URLSearchParams;
+	setSearchParams: (
+		next: URLSearchParams,
+		opts?: { replace?: boolean },
+	) => void;
+}
+
+// All useListState instances subscribe to this module-level store so that a
+// URL flush triggered by ANY instance re-renders every mounted hook — not just
+// the ones that called setState. Needed because router bindings may commit URL
+// changes without re-rendering unrelated subtrees (e.g. the Next.js preset).
+let urlVersion = 0;
+const urlListeners = new Set<() => void>();
+
+function notifyUrlChanged(): void {
+	urlVersion++;
+	for (const listener of urlListeners) listener();
+}
+
+function subscribeToUrl(listener: () => void): () => void {
+	if (urlListeners.size === 0 && typeof window !== "undefined") {
+		window.addEventListener("popstate", notifyUrlChanged);
+	}
+	urlListeners.add(listener);
+	return () => {
+		urlListeners.delete(listener);
+		if (urlListeners.size === 0 && typeof window !== "undefined") {
+			window.removeEventListener("popstate", notifyUrlChanged);
+		}
+	};
+}
+
+function getUrlVersion(): number {
+	return urlVersion;
+}
+
+function getServerUrlVersion(): number {
+	return 0;
+}
+
+// Same-tick updates from ALL useListState instances are coalesced into one
+// `setSearchParams` call. Router bindings commit URL changes asynchronously
+// (Next.js `router.push`, React Router `navigate`), so a second update in the
+// same event would read a stale URL and drop what the first one wrote — and
+// each call would add its own history entry, breaking
+// one-back-press-undoes-one-action semantics. The URL is a per-window
+// singleton, so a module-level queue is the correct batching scope; `setState`
+// only runs in client event handlers, never during SSR.
+let pendingQueue: PendingUpdate[] | null = null;
+
+function searchParamsEqual(a: URLSearchParams, b: URLSearchParams): boolean {
+	const sorted = (params: URLSearchParams) => {
+		const copy = new URLSearchParams(params.toString());
+		copy.sort();
+		return copy.toString();
+	};
+	return sorted(a) === sorted(b);
+}
+
+function enqueueListStateUpdate(update: PendingUpdate): void {
+	if (pendingQueue) {
+		pendingQueue.push(update);
+		return;
+	}
+
+	pendingQueue = [update];
+	queueMicrotask(() => {
+		const queue = pendingQueue;
+		pendingQueue = null;
+		if (!queue || queue.length === 0) return;
+
+		const first = queue[0]!;
+		const currentParams = first.getSearchParams();
+
+		let params = currentParams;
+		let replace = true;
+		let changed = false;
+		for (const entry of queue) {
+			const prevState = parseListStateFromSearchParams(
+				entry.namespace,
+				entry.schema,
+				params,
+			);
+			const nextState = { ...prevState, ...entry.patch };
+			// Compare parsed states, not serialized strings: the URL may hold an
+			// explicit default (`?tab=pending`) or differ only in param order, and
+			// such state-identical updates must not touch history.
+			if (
+				Object.keys(entry.schema).every((key) =>
+					Object.is(prevState[key], nextState[key]),
+				)
+			) {
+				continue;
+			}
+			changed = true;
+			params = serializeListStateToSearchParams(
+				entry.namespace,
+				entry.schema,
+				nextState as InferListState<ListStateSchema>,
+				params,
+			);
+			// A single push among the batched updates makes the whole flush a
+			// push, so the combined action stays one back-press away.
+			if (
+				!resolveListStateHistoryMode(
+					entry.schema,
+					entry.patch as Partial<InferListState<ListStateSchema>>,
+					entry.explicitReplace,
+				)
+			) {
+				replace = false;
+			}
+		}
+
+		// Also skip when later entries reverted earlier ones back to the URL's
+		// current state (net no-op across the batch). Compare order-insensitively:
+		// serialization may reorder params without changing state.
+		if (!changed || searchParamsEqual(params, currentParams)) return;
+		first.setSearchParams(params, { replace });
+		notifyUrlChanged();
+	});
+}
+
+/**
+ * Sync list UI state (filters, tabs, pagination) with URL search params.
+ *
+ * Defaults are omitted from the URL. Field-level `history: "replace"` is used
+ * for rapid changes; discrete changes (tab/page) default to `push` so the back
+ * button undoes them.
+ *
+ * The `namespace` identifies this list state for SSR helpers; URL keys use
+ * the schema field names directly.
+ *
+ * @example
+ * ```tsx
+ * const [state, setState] = useListState("comments-moderation", {
+ *   tab: { type: "string", default: "pending" },
+ *   page: { type: "number", default: 1 },
+ * });
+ * // URL: ?tab=spam&page=3
+ * ```
+ */
+export function useListState<S extends ListStateSchema>(
+	namespace: string,
+	schema: S,
+): [InferListState<S>, SetListState<S>] {
+	const stack = useStackOrNull();
+	const router = stack?.router;
+	const getSearchParams = router?.getSearchParams;
+	const setSearchParams = router?.setSearchParams;
+	const hasWriteBinding = !!getSearchParams && !!setSearchParams;
+
+	// Every instance re-renders whenever any instance flushes a URL update (or
+	// on back/forward), so siblings sharing query keys never serve stale state.
+	// Search params are re-read on every render, so router-driven changes are
+	// also picked up even when `getSearchParams` is referentially stable.
+	useSyncExternalStore(subscribeToUrl, getUrlVersion, getServerUrlVersion);
+	const urlState = parseListStateFromSearchParams(
+		namespace,
+		schema,
+		getSearchParams?.() ?? new URLSearchParams(),
+	);
+
+	// Without a URL write binding (no StackProvider router, or a custom router
+	// missing getSearchParams/setSearchParams) the hook degrades to local
+	// state instead of silently dropping updates. Local patches overlay the
+	// URL state so a read-only `getSearchParams` binding still drives reads
+	// (back/forward, external URL changes) exactly as before.
+	const [localPatch, setLocalPatch] = useState<Partial<InferListState<S>>>({});
+
+	const setState = useCallback<SetListState<S>>(
+		(updates, options) => {
+			if (!setSearchParams || !getSearchParams) {
+				setLocalPatch((prevPatch) => {
+					const urlBase = parseListStateFromSearchParams(
+						namespace,
+						schema,
+						getSearchParams?.() ?? new URLSearchParams(),
+					);
+					const prev = { ...urlBase, ...prevPatch };
+					const patch = typeof updates === "function" ? updates(prev) : updates;
+					if (!patch || Object.keys(patch).length === 0) return prevPatch;
+					return { ...prevPatch, ...patch };
+				});
+				return;
+			}
+
+			// Base state = URL state + patches already queued this tick, so
+			// functional updaters see the values earlier calls just set.
+			let baseState = parseListStateFromSearchParams(
+				namespace,
+				schema,
+				getSearchParams(),
+			);
+			if (pendingQueue) {
+				for (const entry of pendingQueue) {
+					if (entry.namespace === namespace) {
+						baseState = { ...baseState, ...entry.patch };
+					}
+				}
+			}
+			const patch =
+				typeof updates === "function" ? updates(baseState) : updates;
+			if (!patch || Object.keys(patch).length === 0) return;
+
+			enqueueListStateUpdate({
+				namespace,
+				schema,
+				patch: { ...patch },
+				explicitReplace: options?.replace,
+				getSearchParams,
+				setSearchParams,
+			});
+		},
+		[namespace, schema, setSearchParams, getSearchParams],
+	);
+
+	return [
+		hasWriteBinding ? urlState : { ...urlState, ...localPatch },
+		setState,
+	];
+}

package/src/client/index.ts

@@ -114,3 +114,15 @@ export { sitemapEntryToXmlString } from "./sitemap-utils";
 export { metaElementsToObject } from "./meta-utils";
 
 export { normalizePath } from "./path-utils";
+
+export {
+	useListState,
+	parseListStateFromSearchParams,
+	serializeListStateToSearchParams,
+	listStateParamKey,
+	type InferListState,
+	type ListStateField,
+	type ListStateSchema,
+	type SetListState,
+	type SetListStateOptions,
+} from "./hooks/use-list-state";