@btst/stack 2.1.0 → 2.2.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,9 @@
 export * from "./plugin";
+export {
+	getAllPosts,
+	getPostBySlug,
+	getAllTags,
+	type PostListParams,
+	type PostListResult,
+} from "./getters";
 export { createBlogQueryKeys } from "../query-keys";

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

@@ -6,6 +6,7 @@ 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";
 
 export const PostListQuerySchema = z.object({
 	slug: z.string().optional(),
@@ -86,12 +87,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 +169,13 @@ 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),
+		}),
+
 		routes: (adapter: Adapter) => {
 			const findOrCreateTags = async (
 				tagInputs: Array<
@@ -265,144 +273,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 +680,7 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 					method: "GET",
 				},
 				async () => {
-					return await adapter.findMany<Tag>({
-						model: "tag",
-					});
+					return await getAllTags(adapter);
 				},
 			);
 

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

@@ -750,7 +750,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;

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

@@ -99,13 +99,14 @@ function createPostsQueries(
 						},
 						headers,
 					});
-					// Check for errors (better-call returns Error$1<unknown> | Data<Post[]>)
+					// 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<Post[]> after error check
-					return ((response as { data?: unknown }).data ??
+					// 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
@@ -126,14 +127,14 @@ function createPostsQueries(
 						query: { slug, limit: 1 },
 						headers,
 					});
-					// Check for errors (better-call returns Error$1<unknown> | Data<Post[]>)
+					// 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<Post[]> after error check
-					const dataResponse = response as { data?: unknown[] };
-					return (dataResponse.data?.[0] ??
+					// 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
@@ -181,13 +182,14 @@ function createPostsQueries(
 						},
 						headers,
 					});
-					// Check for errors (better-call returns Error$1<unknown> | Data<Post[]>)
+					// 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<Post[]> after error check
-					let posts = ((response as { data?: unknown }).data ??
+					// 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
@@ -228,13 +230,14 @@ function createDraftsQueries(
 						},
 						headers,
 					});
-					// Check for errors (better-call returns Error$1<unknown> | Data<Post[]>)
+					// 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<Post[]> after error check
-					return ((response as { data?: unknown }).data ??
+					// 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