@btst/stack 2.12.1 → 3.0.0-rc.1

package/src/plugins/blog/client/plugin.tsx

@@ -2,9 +2,8 @@ import {
 	defineClientPlugin,
 	createApiClient,
 	isConnectionError,
-	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
-import { createRoute } from "@btst/yar";
+import { defineRoute, defineRoutes } from "@btst/yar";
 import type { ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
 import { createSanitizedSSRLoaderError } from "../../utils";
@@ -91,6 +90,7 @@ export interface BlogClientConfig {
 	 * Optional page component overrides.
 	 * Replace any plugin page with a custom React component.
 	 * The built-in component is used as the fallback when not provided.
+	 * Every override receives the route context (`params`, `query`) as props.
 	 */
 	pageComponents?: {
 		/** Replaces the published posts list page */
@@ -100,11 +100,11 @@ export interface BlogClientConfig {
 		/** Replaces the new post page */
 		newPost?: ComponentType;
 		/** Replaces the single post page */
-		post?: ComponentType<{ slug: string }>;
+		post?: ComponentType<{ params: { slug: string } }>;
 		/** Replaces the edit post page */
-		editPost?: ComponentType<{ slug: string }>;
+		editPost?: ComponentType<{ params: { slug: string } }>;
 		/** Replaces the tag posts page */
-		tag?: ComponentType<{ tagSlug: string }>;
+		tag?: ComponentType<{ params: { tagSlug: string } }>;
 	};
 }
 
@@ -200,10 +200,7 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 			try {
 				// Before hook
 				if (hooks?.beforeLoadPosts) {
-					await runClientHookWithShim(
-						() => hooks.beforeLoadPosts!({ published }, context),
-						"Load prevented by beforeLoadPosts hook",
-					);
+					await hooks.beforeLoadPosts({ published }, context);
 				}
 
 				await queryClient.prefetchInfiniteQuery({
@@ -223,10 +220,7 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 				if (hooks?.afterLoadPosts) {
 					const posts =
 						queryClient.getQueryData<Post[]>(listQuery.queryKey) || null;
-					await runClientHookWithShim(
-						() => hooks.afterLoadPosts!(posts, { published }, context),
-						"Load prevented by afterLoadPosts hook",
-					);
+					await hooks.afterLoadPosts(posts, { published }, context);
 				}
 
 				// Check if there was an error after afterLoadPosts hook
@@ -290,10 +284,7 @@ function createPostLoader(
 			try {
 				// Before hook
 				if (hooks?.beforeLoadPost) {
-					await runClientHookWithShim(
-						() => hooks.beforeLoadPost!(slug, context),
-						"Load prevented by beforeLoadPost hook",
-					);
+					await hooks.beforeLoadPost(slug, context);
 				}
 
 				const client = createApiClient<BlogApiRouter>({
@@ -312,10 +303,7 @@ function createPostLoader(
 				if (hooks?.afterLoadPost) {
 					const post =
 						queryClient.getQueryData<Post>(postQuery.queryKey) || null;
-					await runClientHookWithShim(
-						() => hooks.afterLoadPost!(post, slug, context),
-						"Load prevented by afterLoadPost hook",
-					);
+					await hooks.afterLoadPost(post, slug, context);
 				}
 
 				// Check if there was an error after afterLoadPost hook
@@ -364,18 +352,12 @@ function createNewPostLoader(config: BlogClientConfig) {
 			try {
 				// Before hook
 				if (hooks?.beforeLoadNewPost) {
-					await runClientHookWithShim(
-						() => hooks.beforeLoadNewPost!(context),
-						"Load prevented by beforeLoadNewPost hook",
-					);
+					await hooks.beforeLoadNewPost(context);
 				}
 
 				// After hook
 				if (hooks?.afterLoadNewPost) {
-					await runClientHookWithShim(
-						() => hooks.afterLoadNewPost!(context),
-						"Load prevented by afterLoadNewPost hook",
-					);
+					await hooks.afterLoadNewPost(context);
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
@@ -728,64 +710,47 @@ export const blogClientPlugin = (config: BlogClientConfig) =>
 	defineClientPlugin({
 		name: "blog",
 
-		routes: () => ({
-			posts: createRoute("/blog", () => {
-				const CustomPosts = config.pageComponents?.posts;
-				return {
-					PageComponent:
-						CustomPosts ?? (() => <HomePageComponent published={true} />),
-					loader: createPostsLoader(true, config),
-					meta: createPostsListMeta(true, config),
-				};
-			}),
-			drafts: createRoute("/blog/drafts", () => {
-				const CustomDrafts = config.pageComponents?.drafts;
-				return {
-					PageComponent:
-						CustomDrafts ?? (() => <HomePageComponent published={false} />),
-					loader: createPostsLoader(false, config),
-					meta: createPostsListMeta(false, config),
-				};
-			}),
-			newPost: createRoute("/blog/new", () => {
-				const CustomNewPost = config.pageComponents?.newPost;
-				return {
-					PageComponent: CustomNewPost ?? NewPostPageComponent,
-					loader: createNewPostLoader(config),
-					meta: createNewPostMeta(config),
-				};
-			}),
-			editPost: createRoute("/blog/:slug/edit", ({ params: { slug } }) => {
-				const CustomEditPost = config.pageComponents?.editPost;
-				return {
-					PageComponent: CustomEditPost
-						? () => <CustomEditPost slug={slug} />
-						: () => <EditPostPageComponent slug={slug} />,
-					loader: createPostLoader(slug, config, `/blog/${slug}/edit`),
-					meta: createEditPostMeta(slug, config),
-				};
-			}),
-			tag: createRoute("/blog/tag/:tagSlug", ({ params: { tagSlug } }) => {
-				const CustomTag = config.pageComponents?.tag;
-				return {
-					PageComponent: CustomTag
-						? () => <CustomTag tagSlug={tagSlug} />
-						: () => <TagPageComponent tagSlug={tagSlug} />,
-					loader: createTagLoader(tagSlug, config),
-					meta: createTagMeta(tagSlug, config),
-				};
-			}),
-			post: createRoute("/blog/:slug", ({ params: { slug } }) => {
-				const CustomPost = config.pageComponents?.post;
-				return {
-					PageComponent: CustomPost
-						? () => <CustomPost slug={slug} />
-						: () => <PostPageComponent slug={slug} />,
-					loader: createPostLoader(slug, config),
-					meta: createPostMeta(slug, config),
-				};
-			}),
-		}),
+		routes: () =>
+			defineRoutes(
+				{
+					posts: defineRoute("/blog", {
+						page: () => <HomePageComponent published={true} />,
+						loader: createPostsLoader(true, config),
+						meta: createPostsListMeta(true, config),
+					}),
+					drafts: defineRoute("/blog/drafts", {
+						page: () => <HomePageComponent published={false} />,
+						loader: createPostsLoader(false, config),
+						meta: createPostsListMeta(false, config),
+					}),
+					newPost: defineRoute("/blog/new", {
+						page: NewPostPageComponent,
+						loader: createNewPostLoader(config),
+						meta: createNewPostMeta(config),
+					}),
+					editPost: defineRoute("/blog/:slug/edit", {
+						page: ({ params }) => <EditPostPageComponent slug={params.slug} />,
+						loader: ({ params }) =>
+							createPostLoader(
+								params.slug,
+								config,
+								`/blog/${params.slug}/edit`,
+							)(),
+						meta: ({ params }) => createEditPostMeta(params.slug, config)(),
+					}),
+					tag: defineRoute("/blog/tag/:tagSlug", {
+						page: ({ params }) => <TagPageComponent tagSlug={params.tagSlug} />,
+						loader: ({ params }) => createTagLoader(params.tagSlug, config)(),
+						meta: ({ params }) => createTagMeta(params.tagSlug, config)(),
+					}),
+					post: defineRoute("/blog/:slug", {
+						page: ({ params }) => <PostPageComponent slug={params.slug} />,
+						loader: ({ params }) => createPostLoader(params.slug, config)(),
+						meta: ({ params }) => createPostMeta(params.slug, config)(),
+					}),
+				},
+				{ pages: config.pageComponents },
+			),
 
 		sitemap: async () => {
 			const origin = `${config.siteBaseURL}${config.siteBasePath}`;

package/src/plugins/blog/query-keys.ts

@@ -1,9 +1,11 @@
-import {
-	mergeQueryKeys,
-	createQueryKeys,
-} from "@lukemorales/query-key-factory";
 import type { BlogApiRouter } from "./api";
-import { createApiClient } from "@btst/stack/plugins/client";
+import {
+	createApiClient,
+	createResourceQueryKeys,
+	type ResourcesDeclaration,
+} from "@btst/stack/plugins/client";
+import type { z } from "zod";
+import type { createPostSchema, updatePostSchema } from "./schemas";
 import type { SerializedPost, SerializedTag } from "./types";
 import { postsListDiscriminator } from "./api/query-key-defs";
 
@@ -14,265 +16,172 @@ interface PostsListParams {
 	tagSlug?: string;
 }
 
-// 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
-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
-	);
-}
-
-// Helper to convert error to a proper Error object with meaningful message
-function toError(error: unknown): Error {
-	if (error instanceof Error) {
-		return error;
-	}
-
-	// Handle object errors (likely from better-call APIError)
-	if (typeof error === "object" && error !== null) {
-		// Try to extract message from common error object structures
-		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);
-		// Preserve other properties
-		Object.assign(err, error);
-		return err;
-	}
-
-	// Fallback for primitive values
-	return new Error(String(error));
-}
-
-export function createBlogQueryKeys(
-	client: ReturnType<typeof createApiClient<BlogApiRouter>>,
-	headers?: HeadersInit,
-) {
-	const posts = createPostsQueries(client, headers);
-	const drafts = createDraftsQueries(client, headers);
-	const tags = createTagsQueries(client, headers);
-
-	return mergeQueryKeys(posts, drafts, tags);
-}
-
-function createPostsQueries(
-	client: ReturnType<typeof createApiClient<BlogApiRouter>>,
-	headers?: HeadersInit,
-) {
-	return createQueryKeys("posts", {
-		list: (params?: PostsListParams) => ({
-			queryKey: [
-				postsListDiscriminator({
-					published: params?.published ?? true,
+type PostCreateInput = z.infer<typeof createPostSchema>;
+type PostUpdateInput = z.infer<typeof updatePostSchema>;
+
+/**
+ * Blog resource declaration — the single source of truth for query keys,
+ * HTTP mappings and mutations. Feeds both `createBlogQueryKeys` (SSR
+ * loaders) and `createResource` (client hooks, see `client/hooks`).
+ *
+ * Key shapes intentionally match `BLOG_QUERY_KEYS` in
+ * `api/query-key-defs.ts` so SSG `prefetchForRoute` hydration keeps working.
+ */
+export const blogResources = {
+	posts: {
+		queries: {
+			list: {
+				path: "/posts",
+				query: (params?: PostsListParams) => ({
+					query: params?.query,
 					limit: params?.limit ?? 10,
+					published:
+						params?.published !== undefined
+							? params.published
+								? "true"
+								: "false"
+							: undefined,
 					tagSlug: params?.tagSlug,
-					query: params?.query,
 				}),
-			],
-			queryFn: async ({ pageParam }: { pageParam?: number }) => {
-				try {
-					const response = await client("/posts", {
-						method: "GET",
-						query: {
-							query: params?.query,
-							offset: pageParam ?? 0,
-							limit: params?.limit ?? 10,
-							published:
-								params?.published !== undefined
-									? params.published
-										? "true"
-										: "false"
-									: undefined,
-							tagSlug: params?.tagSlug,
-						},
-						headers,
-					});
-					// Check for errors (better-call returns Error$1<unknown> | Data<PostListResult>)
-					if (isErrorResponse(response)) {
-						const errorResponse = response as { error: unknown };
-						throw toError(errorResponse.error);
-					}
-					// Extract .items from the paginated response for infinite scroll compatibility
-					const dataResponse = response as { data?: { items?: unknown[] } };
-					return (dataResponse.data?.items ??
-						[]) as unknown as SerializedPost[];
-				} catch (error) {
-					// Re-throw errors so React Query can catch them
-					throw error;
-				}
+				key: (params?: PostsListParams) => [
+					postsListDiscriminator({
+						published: params?.published ?? true,
+						limit: params?.limit ?? 10,
+						tagSlug: params?.tagSlug,
+						query: params?.query,
+					}),
+				],
+				select: (data: any, _params?: PostsListParams): SerializedPost[] =>
+					data?.items ?? [],
+				infinite: true,
+				pageSize: (params?: PostsListParams) => params?.limit ?? 10,
 			},
-		}),
 
-		// Simplified detail query
-		detail: (slug: string) => ({
-			queryKey: [slug],
-			queryFn: async () => {
-				if (!slug) return null;
-
-				try {
-					const response = await client("/posts", {
-						method: "GET",
-						query: { slug, limit: 1 },
-						headers,
-					});
-					// Check for errors (better-call returns Error$1<unknown> | Data<PostListResult>)
-					if (isErrorResponse(response)) {
-						const errorResponse = response as { error: unknown };
-						throw toError(errorResponse.error);
-					}
-					// Type narrowed to Data<PostListResult> after error check — access .items[0]
-					const dataResponse = response as { data?: { items?: unknown[] } };
-					return (dataResponse.data?.items?.[0] ??
-						null) as unknown as SerializedPost | null;
-				} catch (error) {
-					// Re-throw errors so React Query can catch them
-					throw error;
-				}
+			detail: {
+				path: "/posts",
+				query: (slug: string) => ({ slug, limit: 1 }),
+				key: (slug: string) => [slug],
+				select: (data: any, _slug: string): SerializedPost | null =>
+					data?.items?.[0] ?? null,
+				skip: (slug: string) => !slug,
 			},
-		}),
 
-		// Next/previous posts query
-		nextPrevious: (date: Date | string) => ({
-			queryKey: ["nextPrevious", date],
-			queryFn: async () => {
-				const dateValue = typeof date === "string" ? new Date(date) : date;
-				const response = await client("/posts/next-previous", {
-					method: "GET",
-					query: {
-						date: dateValue.toISOString(),
-					},
-					headers,
-				});
-				// Check for errors (better-call returns Error$1<unknown> | Data<...>)
-				if (isErrorResponse(response)) {
-					const errorResponse = response as { error: unknown };
-					throw toError(errorResponse.error);
-				}
-				// Type narrowed to Data<...> after error check
-				const dataResponse = response as { data?: unknown };
-				return dataResponse.data as {
+			nextPrevious: {
+				path: "/posts/next-previous",
+				query: (date: Date | string) => ({
+					date: (typeof date === "string"
+						? new Date(date)
+						: date
+					).toISOString(),
+				}),
+				key: (date: Date | string) => ["nextPrevious", date],
+				select: (
+					data: any,
+					_date: Date | string,
+				): {
 					previous: SerializedPost | null;
 					next: SerializedPost | null;
-				};
+				} => data,
 			},
-		}),
-
-		// Recent posts query (separate from main list to avoid cache conflicts)
-		recent: (params?: { limit?: number; excludeSlug?: string }) => ({
-			queryKey: ["recent", params],
-			queryFn: async () => {
-				try {
-					const response = await client("/posts", {
-						method: "GET",
-						query: {
-							limit: params?.limit ?? 5,
-							published: "true",
-						},
-						headers,
-					});
-					// Check for errors (better-call returns Error$1<unknown> | Data<PostListResult>)
-					if (isErrorResponse(response)) {
-						const errorResponse = response as { error: unknown };
-						throw toError(errorResponse.error);
-					}
-					// Extract .items from the paginated response
-					const recentResponse = response as { data?: { items?: unknown[] } };
-					let posts = (recentResponse.data?.items ??
-						[]) as unknown as SerializedPost[];
-
-					// Exclude current post if specified
-					if (params?.excludeSlug) {
-						posts = posts.filter((post) => post.slug !== params.excludeSlug);
-					}
 
-					return posts;
-				} catch (error) {
-					// Re-throw errors so React Query can catch them
-					throw error;
-				}
+			// Recent posts query (separate from the main list to avoid cache conflicts)
+			recent: {
+				path: "/posts",
+				query: (params?: { limit?: number; excludeSlug?: string }) => ({
+					limit: params?.limit ?? 5,
+					published: "true",
+				}),
+				key: (params?: { limit?: number; excludeSlug?: string }) => [
+					"recent",
+					params,
+				],
+				select: (
+					data: any,
+					params?: { limit?: number; excludeSlug?: string },
+				): SerializedPost[] => {
+					const posts: SerializedPost[] = data?.items ?? [];
+					return params?.excludeSlug
+						? posts.filter((post) => post.slug !== params.excludeSlug)
+						: posts;
+				},
 			},
-		}),
-	});
-}
-
-function createDraftsQueries(
-	client: ReturnType<typeof createApiClient<BlogApiRouter>>,
-	headers?: HeadersInit,
-) {
-	return createQueryKeys("drafts", {
-		list: (params?: PostsListParams) => ({
-			queryKey: [
-				{
-					...(params?.limit && { limit: params.limit }),
+		},
+
+		mutations: {
+			create: {
+				path: "@post/posts",
+				method: "POST" as const,
+				input: (vars: PostCreateInput) => ({ body: vars }),
+				select: (data: any) => data as SerializedPost | null,
+				invalidates: ["posts.list", "drafts.list"],
+				setData: {
+					query: "detail",
+					args: (created: SerializedPost | null) =>
+						created?.slug ? [created.slug] : null,
 				},
-			],
-			queryFn: async ({ pageParam }: { pageParam?: number }) => {
-				try {
-					const response = await client("/posts", {
-						method: "GET",
-						query: {
-							query: params?.query,
-							offset: pageParam ?? 0,
-							limit: params?.limit ?? 10,
-							published: "false",
-						},
-						headers,
-					});
-					// Check for errors (better-call returns Error$1<unknown> | Data<PostListResult>)
-					if (isErrorResponse(response)) {
-						const errorResponse = response as { error: unknown };
-						throw toError(errorResponse.error);
-					}
-					// Extract .items from the paginated response for infinite scroll compatibility
-					const draftsResponse = response as { data?: { items?: unknown[] } };
-					return (draftsResponse.data?.items ??
-						[]) as unknown as SerializedPost[];
-				} catch (error) {
-					// Re-throw errors so React Query can catch them
-					throw error;
-				}
 			},
-		}),
-	});
-}
+			update: {
+				path: "@put/posts/:id",
+				method: "PUT" as const,
+				input: (vars: { id: string; data: PostUpdateInput }) => ({
+					params: { id: vars.id },
+					body: vars.data,
+				}),
+				select: (data: any) => data as SerializedPost | null,
+				invalidates: ["posts.list", "drafts.list"],
+				setData: {
+					query: "detail",
+					args: (updated: SerializedPost | null) =>
+						updated?.slug ? [updated.slug] : null,
+				},
+			},
+			delete: {
+				path: "@delete/posts/:id",
+				method: "DELETE" as const,
+				input: (vars: { id: string }) => ({ params: { id: vars.id } }),
+				select: (data: any) => data as { success: boolean },
+				invalidates: ["posts", "drafts.list"],
+			},
+		},
+	},
+
+	drafts: {
+		queries: {
+			list: {
+				path: "/posts",
+				query: (params?: PostsListParams) => ({
+					query: params?.query,
+					limit: params?.limit ?? 10,
+					published: "false",
+				}),
+				key: (params?: PostsListParams) => [
+					{
+						...(params?.limit && { limit: params.limit }),
+					},
+				],
+				select: (data: any, _params?: PostsListParams): SerializedPost[] =>
+					data?.items ?? [],
+				infinite: true,
+				pageSize: (params?: PostsListParams) => params?.limit ?? 10,
+			},
+		},
+	},
+
+	tags: {
+		queries: {
+			list: {
+				path: "/tags",
+				key: () => ["tags"],
+				// The API returns serialized tags (dates as strings)
+				select: (data: any): SerializedTag[] => data ?? [],
+			},
+		},
+	},
+} satisfies ResourcesDeclaration;
 
-function createTagsQueries(
+export function createBlogQueryKeys(
 	client: ReturnType<typeof createApiClient<BlogApiRouter>>,
 	headers?: HeadersInit,
 ) {
-	return createQueryKeys("tags", {
-		list: () => ({
-			queryKey: ["tags"],
-			queryFn: async () => {
-				try {
-					const response = await client("/tags", {
-						method: "GET",
-						headers,
-					});
-					// Check for errors (better-call returns Error$1<unknown> | Data<Tag[]>)
-					if (isErrorResponse(response)) {
-						const errorResponse = response as { error: unknown };
-						throw toError(errorResponse.error);
-					}
-					// Type narrowed to Data<Tag[]> after error check
-					// The API returns serialized tags (dates as strings)
-					return ((response as { data?: unknown }).data ??
-						[]) as unknown as SerializedTag[];
-				} catch (error) {
-					// Re-throw errors so React Query can catch them
-					throw error;
-				}
-			},
-		}),
-	});
+	return createResourceQueryKeys(client, blogResources, headers);
 }

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

@@ -0,0 +1,32 @@
+/**
+ * Client-only resource hooks (`"use client"` modules).
+ *
+ * Kept separate from `@btst/stack/plugins/client` so plugin factory entries
+ * (`client/plugin.tsx`) stay server-import-safe during SSG.
+ */
+
+export {
+	createResource,
+	type CreateResourceConfig,
+	type Resource,
+	type ResourceDetailData,
+	type ResourceHandle,
+	type ResourceInfiniteQueryHooks,
+	type ResourceMutationHooks,
+	type ResourcePlainQueryHooks,
+	type ResourceQueryHooks,
+	type ResourceQueryOptions,
+} from "../resource/hooks";
+export type { ResourceOverrides } from "../resource/internal";
+export {
+	createUseForm,
+	type ResourceFormConfig,
+	type ResourceFormResult,
+} from "../resource/use-form";
+export {
+	createUseSelect,
+	type ResourceSelectConfig,
+	type ResourceSelectOption,
+	type ResourceSelectResult,
+} from "../resource/use-select";
+export { useDebounce } from "../resource/use-debounce";