@btst/stack 2.1.0 → 2.3.0

package/src/plugins/blog/api/getters.ts

@@ -0,0 +1,243 @@
+import type { Adapter } from "@btst/db";
+import type { Post, PostWithPostTag, Tag } from "../types";
+
+/**
+ * Parameters for filtering/paginating posts.
+ * Mirrors the shape of the list API query schema.
+ */
+export interface PostListParams {
+	slug?: string;
+	tagSlug?: string;
+	offset?: number;
+	limit?: number;
+	query?: string;
+	published?: boolean;
+}
+
+/**
+ * Paginated result returned by {@link getAllPosts}.
+ */
+export interface PostListResult {
+	items: Array<Post & { tags: Tag[] }>;
+	total: number;
+	limit?: number;
+	offset?: number;
+}
+
+/**
+ * Retrieve all posts matching optional filter criteria.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks (e.g. `onBeforeListPosts`) are NOT
+ * called. The caller is responsible for any access-control checks before
+ * invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param params - Optional filter/pagination parameters (same shape as the list API query)
+ */
+export async function getAllPosts(
+	adapter: Adapter,
+	params?: PostListParams,
+): Promise<PostListResult> {
+	const query = params ?? {};
+
+	const whereConditions: Array<{
+		field: string;
+		value: string | number | boolean | string[] | number[] | Date | null;
+		operator: "eq" | "in";
+	}> = [];
+
+	// Resolve tagSlug → post IDs up front, then push an `in` condition so the
+	// adapter can filter and paginate entirely at the DB level.  The previous
+	// approach loaded every post into memory and filtered with a JS Set, which
+	// scans the whole table on every request.
+	if (query.tagSlug) {
+		const tag = await adapter.findOne<Tag>({
+			model: "tag",
+			where: [{ field: "slug", value: query.tagSlug, operator: "eq" as const }],
+		});
+
+		if (!tag) {
+			return { items: [], total: 0, limit: query.limit, offset: query.offset };
+		}
+
+		const postTags = await adapter.findMany<{ postId: string; tagId: string }>({
+			model: "postTag",
+			where: [{ field: "tagId", value: tag.id, operator: "eq" as const }],
+		});
+
+		const taggedPostIds = postTags.map((pt) => pt.postId);
+		if (taggedPostIds.length === 0) {
+			return { items: [], total: 0, limit: query.limit, offset: query.offset };
+		}
+
+		whereConditions.push({
+			field: "id",
+			value: taggedPostIds,
+			operator: "in" as const,
+		});
+	}
+
+	if (query.published !== undefined) {
+		whereConditions.push({
+			field: "published",
+			value: query.published,
+			operator: "eq" as const,
+		});
+	}
+
+	if (query.slug) {
+		whereConditions.push({
+			field: "slug",
+			value: query.slug,
+			operator: "eq" as const,
+		});
+	}
+
+	// Full-text search across title/content/excerpt must remain in-memory:
+	// the adapter's `contains` operator is case-sensitive and cannot be
+	// grouped with AND conditions using OR connectors in all adapter
+	// implementations.  All other filters above are pushed to DB, so the
+	// in-memory pass only scans the already-narrowed result set.
+	const needsInMemoryFilter = !!query.query;
+
+	const dbWhere = whereConditions.length > 0 ? whereConditions : undefined;
+
+	const dbTotal: number | undefined = !needsInMemoryFilter
+		? await adapter.count({ model: "post", where: dbWhere })
+		: undefined;
+
+	const posts = await adapter.findMany<PostWithPostTag>({
+		model: "post",
+		limit: !needsInMemoryFilter ? query.limit : undefined,
+		offset: !needsInMemoryFilter ? query.offset : undefined,
+		where: dbWhere,
+		sortBy: { field: "createdAt", direction: "desc" },
+		join: { postTag: true },
+	});
+
+	// Collect the unique tag IDs present in this page of posts, then fetch
+	// only those tags (not the entire tags table).
+	const tagIds = new Set<string>();
+	for (const post of posts) {
+		if (post.postTag) {
+			for (const pt of post.postTag) {
+				tagIds.add(pt.tagId);
+			}
+		}
+	}
+
+	const tags =
+		tagIds.size > 0
+			? await adapter.findMany<Tag>({
+					model: "tag",
+					where: [
+						{
+							field: "id",
+							value: Array.from(tagIds),
+							operator: "in" as const,
+						},
+					],
+				})
+			: [];
+	const tagMap = new Map<string, Tag>(tags.map((t) => [t.id, t]));
+
+	let result = posts.map((post) => {
+		const postTags = (post.postTag || [])
+			.map((pt) => {
+				const tag = tagMap.get(pt.tagId);
+				return tag ? { ...tag } : undefined;
+			})
+			.filter((tag): tag is Tag => tag !== undefined);
+		const { postTag: _, ...postWithoutJoin } = post;
+		return { ...postWithoutJoin, tags: postTags };
+	});
+
+	if (query.query) {
+		const searchLower = query.query.toLowerCase();
+		result = result.filter(
+			(post) =>
+				post.title?.toLowerCase().includes(searchLower) ||
+				post.content?.toLowerCase().includes(searchLower) ||
+				post.excerpt?.toLowerCase().includes(searchLower),
+		);
+	}
+
+	if (needsInMemoryFilter) {
+		const total = result.length;
+		const offset = query.offset ?? 0;
+		const limit = query.limit;
+		result = result.slice(
+			offset,
+			limit !== undefined ? offset + limit : undefined,
+		);
+		return { items: result, total, limit: query.limit, offset: query.offset };
+	}
+
+	return {
+		items: result,
+		total: dbTotal ?? result.length,
+		limit: query.limit,
+		offset: query.offset,
+	};
+}
+
+/**
+ * Retrieve a single post by its slug, including associated tags.
+ * Returns null if no post is found.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param slug - The post slug
+ */
+export async function getPostBySlug(
+	adapter: Adapter,
+	slug: string,
+): Promise<(Post & { tags: Tag[] }) | null> {
+	const posts = await adapter.findMany<PostWithPostTag>({
+		model: "post",
+		where: [{ field: "slug", value: slug, operator: "eq" as const }],
+		limit: 1,
+		join: { postTag: true },
+	});
+
+	if (posts.length === 0) return null;
+
+	const post = posts[0]!;
+	const tagIds = (post.postTag || []).map((pt) => pt.tagId);
+
+	const tags =
+		tagIds.length > 0
+			? await adapter.findMany<Tag>({
+					model: "tag",
+					where: [{ field: "id", value: tagIds, operator: "in" as const }],
+				})
+			: [];
+
+	const tagMap = new Map<string, Tag>(tags.map((t) => [t.id, t]));
+	const resolvedTags = (post.postTag || [])
+		.map((pt) => tagMap.get(pt.tagId))
+		.filter((t): t is Tag => t !== undefined);
+
+	const { postTag: _, ...postWithoutJoin } = post;
+	return { ...postWithoutJoin, tags: resolvedTags };
+}
+
+/**
+ * Retrieve all tags, sorted alphabetically by name.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ */
+export async function getAllTags(adapter: Adapter): Promise<Tag[]> {
+	return adapter.findMany<Tag>({
+		model: "tag",
+		sortBy: { field: "name", direction: "asc" },
+	});
+}

package/src/plugins/blog/api/index.ts

@@ -1,2 +1,11 @@
 export * from "./plugin";
+export {
+	getAllPosts,
+	getPostBySlug,
+	getAllTags,
+	type PostListParams,
+	type PostListResult,
+} from "./getters";
+export { serializePost, serializeTag } from "./serializers";
+export { BLOG_QUERY_KEYS } from "./query-key-defs";
 export { createBlogQueryKeys } from "../query-keys";

package/src/plugins/blog/api/plugin.ts

@@ -6,6 +6,91 @@ import { blogSchema as dbSchema } from "../db";
 import type { Post, PostWithPostTag, Tag } from "../types";
 import { slugify } from "../utils";
 import { createPostSchema, updatePostSchema } from "../schemas";
+import { getAllPosts, getPostBySlug, getAllTags } from "./getters";
+import { BLOG_QUERY_KEYS } from "./query-key-defs";
+import { serializePost, serializeTag } from "./serializers";
+import type { QueryClient } from "@tanstack/react-query";
+
+/**
+ * Route keys for the blog plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+export type BlogRouteKey =
+	| "posts"
+	| "drafts"
+	| "post"
+	| "tag"
+	| "newPost"
+	| "editPost";
+
+/**
+ * Overloaded signature for `prefetchForRoute`.
+ * TypeScript enforces the correct params for each routeKey at call sites.
+ */
+interface BlogPrefetchForRoute {
+	(key: "posts" | "drafts" | "newPost", qc: QueryClient): Promise<void>;
+	(
+		key: "post" | "editPost",
+		qc: QueryClient,
+		params: { slug: string },
+	): Promise<void>;
+	(key: "tag", qc: QueryClient, params: { tagSlug: string }): Promise<void>;
+}
+
+function createBlogPrefetchForRoute(adapter: Adapter): BlogPrefetchForRoute {
+	return async function prefetchForRoute(
+		key: BlogRouteKey,
+		qc: QueryClient,
+		params?: Record<string, string>,
+	): Promise<void> {
+		switch (key) {
+			case "posts":
+			case "drafts": {
+				const published = key === "posts";
+				const [result, tags] = await Promise.all([
+					getAllPosts(adapter, { published, limit: 10 }),
+					getAllTags(adapter),
+				]);
+				qc.setQueryData(BLOG_QUERY_KEYS.postsList({ published, limit: 10 }), {
+					pages: [result.items.map(serializePost)],
+					pageParams: [0],
+				});
+				qc.setQueryData(BLOG_QUERY_KEYS.tagsList(), tags.map(serializeTag));
+				break;
+			}
+			case "post":
+			case "editPost": {
+				const slug = params?.slug ?? "";
+				if (slug) {
+					const post = await getPostBySlug(adapter, slug);
+					qc.setQueryData(
+						BLOG_QUERY_KEYS.postDetail(slug),
+						post ? serializePost(post) : null,
+					);
+				}
+				break;
+			}
+			case "tag": {
+				const tagSlug = params?.tagSlug ?? "";
+				const [result, tags] = await Promise.all([
+					getAllPosts(adapter, { published: true, limit: 10, tagSlug }),
+					getAllTags(adapter),
+				]);
+				qc.setQueryData(
+					BLOG_QUERY_KEYS.postsList({ published: true, limit: 10, tagSlug }),
+					{
+						pages: [result.items.map(serializePost)],
+						pageParams: [0],
+					},
+				);
+				qc.setQueryData(BLOG_QUERY_KEYS.tagsList(), tags.map(serializeTag));
+				break;
+			}
+			default:
+				break;
+		}
+	} as BlogPrefetchForRoute;
+}
 
 export const PostListQuerySchema = z.object({
 	slug: z.string().optional(),
@@ -86,12 +171,12 @@ export interface BlogBackendHooks {
 
 	/**
 	 * Called after posts are read successfully
-	 * @param posts - Array of posts that were read
+	 * @param posts - The list of posts returned by the query
 	 * @param filter - Query parameters used for filtering
 	 * @param context - Request context
 	 */
 	onPostsRead?: (
-		posts: Post[],
+		posts: Array<Post & { tags: Tag[] }>,
 		filter: z.infer<typeof PostListQuerySchema>,
 		context: BlogApiContext,
 	) => Promise<void> | void;
@@ -168,6 +253,14 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 
 		dbPlugin: dbSchema,
 
+		api: (adapter) => ({
+			getAllPosts: (params?: Parameters<typeof getAllPosts>[1]) =>
+				getAllPosts(adapter, params),
+			getPostBySlug: (slug: string) => getPostBySlug(adapter, slug),
+			getAllTags: () => getAllTags(adapter),
+			prefetchForRoute: createBlogPrefetchForRoute(adapter),
+		}),
+
 		routes: (adapter: Adapter) => {
 			const findOrCreateTags = async (
 				tagInputs: Array<
@@ -265,144 +358,10 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 							}
 						}
 
-						let tagFilterPostIds: Set<string> | null = null;
-
-						if (query.tagSlug) {
-							const tag = await adapter.findOne<Tag>({
-								model: "tag",
-								where: [
-									{
-										field: "slug",
-										value: query.tagSlug,
-										operator: "eq" as const,
-									},
-								],
-							});
-
-							if (!tag) {
-								return [];
-							}
-
-							const postTags = await adapter.findMany<{
-								postId: string;
-								tagId: string;
-							}>({
-								model: "postTag",
-								where: [
-									{
-										field: "tagId",
-										value: tag.id,
-										operator: "eq" as const,
-									},
-								],
-							});
-							tagFilterPostIds = new Set(postTags.map((pt) => pt.postId));
-							if (tagFilterPostIds.size === 0) {
-								return [];
-							}
-						}
-
-						const whereConditions = [];
-
-						if (query.published !== undefined) {
-							whereConditions.push({
-								field: "published",
-								value: query.published,
-								operator: "eq" as const,
-							});
-						}
-
-						if (query.slug) {
-							whereConditions.push({
-								field: "slug",
-								value: query.slug,
-								operator: "eq" as const,
-							});
-						}
-
-						const posts = await adapter.findMany<PostWithPostTag>({
-							model: "post",
-							limit:
-								query.query || query.tagSlug ? undefined : (query.limit ?? 10),
-							offset:
-								query.query || query.tagSlug ? undefined : (query.offset ?? 0),
-							where: whereConditions,
-							sortBy: {
-								field: "createdAt",
-								direction: "desc",
-							},
-							join: {
-								postTag: true,
-							},
-						});
-
-						// Collect unique tag IDs from joined postTag data
-						const tagIds = new Set<string>();
-						for (const post of posts) {
-							if (post.postTag) {
-								for (const pt of post.postTag) {
-									tagIds.add(pt.tagId);
-								}
-							}
-						}
-
-						// Fetch all tags at once
-						const tags =
-							tagIds.size > 0
-								? await adapter.findMany<Tag>({
-										model: "tag",
-									})
-								: [];
-						const tagMap = new Map<string, Tag>();
-						for (const tag of tags) {
-							if (tagIds.has(tag.id)) {
-								tagMap.set(tag.id, tag);
-							}
-						}
-
-						// Map tags to posts (spread to avoid circular references)
-						let result = posts.map((post) => {
-							const postTags = (post.postTag || [])
-								.map((pt) => {
-									const tag = tagMap.get(pt.tagId);
-									return tag ? { ...tag } : undefined;
-								})
-								.filter((tag): tag is Tag => tag !== undefined);
-							const { postTag: _, ...postWithoutJoin } = post;
-							return {
-								...postWithoutJoin,
-								tags: postTags,
-							};
-						});
-
-						if (tagFilterPostIds) {
-							result = result.filter((post) => tagFilterPostIds!.has(post.id));
-						}
-
-						if (query.query) {
-							const searchLower = query.query.toLowerCase();
-							result = result.filter((post) => {
-								const titleMatch = post.title
-									?.toLowerCase()
-									.includes(searchLower);
-								const contentMatch = post.content
-									?.toLowerCase()
-									.includes(searchLower);
-								const excerptMatch = post.excerpt
-									?.toLowerCase()
-									.includes(searchLower);
-								return titleMatch || contentMatch || excerptMatch;
-							});
-						}
-
-						if (query.tagSlug || query.query) {
-							const offset = query.offset ?? 0;
-							const limit = query.limit ?? 10;
-							result = result.slice(offset, offset + limit);
-						}
+						const result = await getAllPosts(adapter, query);
 
 						if (hooks?.onPostsRead) {
-							await hooks.onPostsRead(result, query, context);
+							await hooks.onPostsRead(result.items, query, context);
 						}
 
 						return result;
@@ -806,9 +765,7 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 					method: "GET",
 				},
 				async () => {
-					return await adapter.findMany<Tag>({
-						model: "tag",
-					});
+					return await getAllTags(adapter);
 				},
 			);
 

package/src/plugins/blog/api/query-key-defs.ts

@@ -0,0 +1,46 @@
+/**
+ * Internal query key constants for the blog plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+
+export interface PostsListDiscriminator {
+	query: string | undefined;
+	limit: number;
+	published: boolean;
+	tagSlug: string | undefined;
+}
+
+/**
+ * Builds the discriminator object used as the cache key for the posts list.
+ * Mirrors the inline object in createPostsQueries so both paths stay in sync.
+ */
+export function postsListDiscriminator(params: {
+	published: boolean;
+	limit?: number;
+	tagSlug?: string;
+	query?: string;
+}): PostsListDiscriminator {
+	return {
+		query:
+			params.query !== undefined && params.query.trim() === ""
+				? undefined
+				: params.query,
+		limit: params.limit ?? 10,
+		published: params.published,
+		tagSlug: params.tagSlug,
+	};
+}
+
+/** Full query key builders — use these with queryClient.setQueryData() */
+export const BLOG_QUERY_KEYS = {
+	postsList: (params: {
+		published: boolean;
+		limit?: number;
+		tagSlug?: string;
+	}) => ["posts", "list", postsListDiscriminator(params)] as const,
+
+	postDetail: (slug: string) => ["posts", "detail", slug] as const,
+
+	tagsList: () => ["tags", "list", "tags"] as const,
+};

package/src/plugins/blog/api/serializers.ts

@@ -0,0 +1,27 @@
+import type { Post, Tag, SerializedPost, SerializedTag } from "../types";
+
+/**
+ * Serialize a Tag for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeTag(tag: Tag): SerializedTag {
+	return {
+		...tag,
+		createdAt: tag.createdAt.toISOString(),
+		updatedAt: tag.updatedAt.toISOString(),
+	};
+}
+
+/**
+ * Serialize a Post (with tags) for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializePost(post: Post & { tags: Tag[] }): SerializedPost {
+	return {
+		...post,
+		createdAt: post.createdAt.toISOString(),
+		updatedAt: post.updatedAt.toISOString(),
+		publishedAt: post.publishedAt?.toISOString(),
+		tags: post.tags.map(serializeTag),
+	};
+}

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

@@ -1,6 +1,7 @@
 import {
 	defineClientPlugin,
 	createApiClient,
+	isConnectionError,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -226,6 +227,12 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				// Let Error Boundaries handle errors when components render
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/blog] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.blog.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -299,6 +306,12 @@ function createPostLoader(
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				// Let Error Boundaries handle errors when components render
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/blog] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.blog.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -398,6 +411,12 @@ function createTagLoader(tagSlug: string, config: BlogClientConfig) {
 					await hooks.onLoadError(error, context);
 				}
 			} catch (error) {
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/blog] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.blog.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -750,7 +769,8 @@ export const blogClientPlugin = (config: BlogClientConfig) =>
 						published: "true",
 					},
 				});
-				const page = (res.data ?? []) as unknown as SerializedPost[];
+				// The /posts endpoint returns PostListResult { items, total, limit, offset }
+				const page = ((res.data as any)?.items ?? []) as SerializedPost[];
 				posts.push(...page);
 				if (page.length < limit) break;
 				offset += limit;