@btst/stack 2.1.0 → 2.3.0

package/src/plugins/kanban/__tests__/getters.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { createMemoryAdapter } from "@btst/adapter-memory";
+import { defineDb } from "@btst/db";
+import type { Adapter } from "@btst/db";
+import { kanbanSchema } from "../db";
+import { getAllBoards, getBoardById } from "../api/getters";
+
+const createTestAdapter = (): Adapter => {
+	const db = defineDb({}).use(kanbanSchema);
+	return createMemoryAdapter(db)({});
+};
+
+async function createBoard(
+	adapter: Adapter,
+	name: string,
+	slug: string,
+	ownerId?: string,
+): Promise<any> {
+	return adapter.create({
+		model: "kanbanBoard",
+		data: {
+			name,
+			slug,
+			...(ownerId ? { ownerId } : {}),
+			createdAt: new Date(),
+			updatedAt: new Date(),
+		},
+	});
+}
+
+async function createColumn(
+	adapter: Adapter,
+	boardId: string,
+	title: string,
+	order: number,
+): Promise<any> {
+	return adapter.create({
+		model: "kanbanColumn",
+		data: {
+			boardId,
+			title,
+			order,
+			createdAt: new Date(),
+			updatedAt: new Date(),
+		},
+	});
+}
+
+async function createTask(
+	adapter: Adapter,
+	columnId: string,
+	title: string,
+	order: number,
+): Promise<any> {
+	return adapter.create({
+		model: "kanbanTask",
+		data: {
+			columnId,
+			title,
+			priority: "MEDIUM",
+			order,
+			isArchived: false,
+			createdAt: new Date(),
+			updatedAt: new Date(),
+		},
+	});
+}
+
+describe("kanban getters", () => {
+	let adapter: Adapter;
+
+	beforeEach(() => {
+		adapter = createTestAdapter();
+	});
+
+	describe("getAllBoards", () => {
+		it("returns empty array when no boards exist", async () => {
+			const { items, total } = await getAllBoards(adapter);
+			expect(items).toEqual([]);
+			expect(total).toBe(0);
+		});
+
+		it("returns all boards with columns and tasks", async () => {
+			const board = (await createBoard(adapter, "My Board", "my-board")) as any;
+			const col = (await createColumn(adapter, board.id, "To Do", 0)) as any;
+			await createTask(adapter, col.id, "Task 1", 0);
+
+			const { items: boards, total } = await getAllBoards(adapter);
+			expect(boards).toHaveLength(1);
+			expect(total).toBe(1);
+			expect(boards[0]!.slug).toBe("my-board");
+			expect(boards[0]!.columns).toHaveLength(1);
+			expect(boards[0]!.columns[0]!.title).toBe("To Do");
+			expect(boards[0]!.columns[0]!.tasks).toHaveLength(1);
+			expect(boards[0]!.columns[0]!.tasks[0]!.title).toBe("Task 1");
+		});
+
+		it("returns boards with empty columns array when no columns exist", async () => {
+			await createBoard(adapter, "Empty Board", "empty-board");
+
+			const { items: boards } = await getAllBoards(adapter);
+			expect(boards).toHaveLength(1);
+			expect(boards[0]!.columns).toEqual([]);
+		});
+
+		it("filters boards by slug", async () => {
+			await createBoard(adapter, "Board A", "board-a");
+			await createBoard(adapter, "Board B", "board-b");
+
+			const { items, total } = await getAllBoards(adapter, { slug: "board-a" });
+			expect(items).toHaveLength(1);
+			expect(total).toBe(1);
+			expect(items[0]!.slug).toBe("board-a");
+		});
+
+		it("filters boards by ownerId", async () => {
+			await createBoard(adapter, "Alice Board", "alice-board", "user-alice");
+			await createBoard(adapter, "Bob Board", "bob-board", "user-bob");
+
+			const { items, total } = await getAllBoards(adapter, {
+				ownerId: "user-alice",
+			});
+			expect(items).toHaveLength(1);
+			expect(total).toBe(1);
+			expect(items[0]!.slug).toBe("alice-board");
+		});
+
+		it("sorts columns by order", async () => {
+			const board = (await createBoard(adapter, "Board", "board")) as any;
+			// Create columns out of order
+			await createColumn(adapter, board.id, "Done", 2);
+			await createColumn(adapter, board.id, "To Do", 0);
+			await createColumn(adapter, board.id, "In Progress", 1);
+
+			const { items: boards } = await getAllBoards(adapter);
+			expect(boards[0]!.columns[0]!.title).toBe("To Do");
+			expect(boards[0]!.columns[1]!.title).toBe("In Progress");
+			expect(boards[0]!.columns[2]!.title).toBe("Done");
+		});
+	});
+
+	describe("getBoardById", () => {
+		it("returns null when board does not exist", async () => {
+			const board = await getBoardById(adapter, "nonexistent");
+			expect(board).toBeNull();
+		});
+
+		it("returns the board with columns and tasks", async () => {
+			const board = (await createBoard(adapter, "My Board", "my-board")) as any;
+			const col1 = (await createColumn(adapter, board.id, "To Do", 0)) as any;
+			const col2 = (await createColumn(adapter, board.id, "Done", 1)) as any;
+			await createTask(adapter, col1.id, "Task A", 0);
+			await createTask(adapter, col1.id, "Task B", 1);
+			await createTask(adapter, col2.id, "Task C", 0);
+
+			const result = await getBoardById(adapter, board.id);
+			expect(result).not.toBeNull();
+			expect(result!.id).toBe(board.id);
+			expect(result!.columns).toHaveLength(2);
+			expect(result!.columns[0]!.tasks).toHaveLength(2);
+			expect(result!.columns[1]!.tasks).toHaveLength(1);
+		});
+
+		it("returns board with empty columns when no columns exist", async () => {
+			const board = (await createBoard(adapter, "Empty Board", "empty")) as any;
+
+			const result = await getBoardById(adapter, board.id);
+			expect(result).not.toBeNull();
+			expect(result!.columns).toEqual([]);
+		});
+	});
+});

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

@@ -0,0 +1,149 @@
+import type { Adapter } from "@btst/db";
+import type {
+	BoardWithKanbanColumn,
+	BoardWithColumns,
+	ColumnWithTasks,
+	Task,
+} from "../types";
+import type { z } from "zod";
+import type { BoardListQuerySchema } from "../schemas";
+
+/**
+ * Paginated result returned by {@link getAllBoards}.
+ */
+export interface BoardListResult {
+	items: BoardWithColumns[];
+	total: number;
+	limit?: number;
+	offset?: number;
+}
+
+/**
+ * Given a raw board record (with a `column` join), fetches tasks for every
+ * column in parallel and returns the sorted columns with their tasks attached.
+ * Strips the raw `column` join field from the returned board object.
+ */
+async function hydrateColumnsWithTasks(
+	adapter: Adapter,
+	board: BoardWithKanbanColumn,
+): Promise<BoardWithColumns> {
+	const columnIds = (board.column || []).map((c) => c.id);
+	const tasksByColumn = new Map<string, Task[]>();
+
+	if (columnIds.length > 0) {
+		const taskResults = await Promise.all(
+			columnIds.map((columnId) =>
+				adapter.findMany<Task>({
+					model: "kanbanTask",
+					where: [
+						{ field: "columnId", value: columnId, operator: "eq" as const },
+					],
+					sortBy: { field: "order", direction: "asc" },
+				}),
+			),
+		);
+		for (let i = 0; i < columnIds.length; i++) {
+			const columnId = columnIds[i];
+			const tasks = taskResults[i];
+			if (columnId && tasks) {
+				tasksByColumn.set(columnId, tasks);
+			}
+		}
+	}
+
+	const columns: ColumnWithTasks[] = (board.column || [])
+		.sort((a, b) => a.order - b.order)
+		.map((col) => ({ ...col, tasks: tasksByColumn.get(col.id) || [] }));
+
+	const { column: _, ...boardWithoutJoin } = board;
+	return { ...boardWithoutJoin, columns };
+}
+
+/**
+ * Retrieve all boards matching optional filter criteria, with columns and tasks.
+ * Pure DB function - no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @param adapter - The database adapter
+ * @param params - Optional filter/pagination parameters (same shape as the list API query)
+ */
+export async function getAllBoards(
+	adapter: Adapter,
+	params?: z.infer<typeof BoardListQuerySchema>,
+): Promise<BoardListResult> {
+	const query = params ?? {};
+
+	const whereConditions: Array<{
+		field: string;
+		value: string;
+		operator: "eq";
+	}> = [];
+
+	if (query.slug) {
+		whereConditions.push({
+			field: "slug",
+			value: query.slug,
+			operator: "eq" as const,
+		});
+	}
+
+	if (query.ownerId) {
+		whereConditions.push({
+			field: "ownerId",
+			value: query.ownerId,
+			operator: "eq" as const,
+		});
+	}
+
+	if (query.organizationId) {
+		whereConditions.push({
+			field: "organizationId",
+			value: query.organizationId,
+			operator: "eq" as const,
+		});
+	}
+
+	const where = whereConditions.length > 0 ? whereConditions : undefined;
+
+	const [boards, total] = await Promise.all([
+		adapter.findMany<BoardWithKanbanColumn>({
+			model: "kanbanBoard",
+			limit: query.limit ?? 50,
+			offset: query.offset ?? 0,
+			where,
+			sortBy: { field: "createdAt", direction: "desc" },
+			join: { kanbanColumn: true },
+		}),
+		adapter.count({ model: "kanbanBoard", where }),
+	]);
+
+	const items = await Promise.all(
+		boards.map((board) => hydrateColumnsWithTasks(adapter, board)),
+	);
+
+	return { items, total, limit: query.limit, offset: query.offset };
+}
+
+/**
+ * Retrieve a single board by its ID, with all columns and tasks.
+ * Returns null if the board is not found.
+ * Pure DB function - no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @param adapter - The database adapter
+ * @param id - The board ID
+ */
+export async function getBoardById(
+	adapter: Adapter,
+	id: string,
+): Promise<BoardWithColumns | null> {
+	const board = await adapter.findOne<BoardWithKanbanColumn>({
+		model: "kanbanBoard",
+		where: [{ field: "id", value: id, operator: "eq" as const }],
+		join: { kanbanColumn: true },
+	});
+
+	if (!board) {
+		return null;
+	}
+
+	return hydrateColumnsWithTasks(adapter, board);
+}

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

@@ -1,6 +1,10 @@
 export {
 	kanbanBackendPlugin,
 	type KanbanApiRouter,
+	type KanbanRouteKey,
 	type KanbanApiContext,
 	type KanbanBackendHooks,
 } from "./plugin";
+export { getAllBoards, getBoardById, type BoardListResult } from "./getters";
+export { serializeBoard, serializeColumn, serializeTask } from "./serializers";
+export { KANBAN_QUERY_KEYS } from "./query-key-defs";

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

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { kanbanSchema as dbSchema } from "../db";
 import type {
 	Board,
-	BoardWithKanbanColumn,
+	BoardWithColumns,
 	Column,
 	ColumnWithTasks,
 	Task,
@@ -23,6 +23,55 @@ import {
 	updateColumnSchema,
 	updateTaskSchema,
 } from "../schemas";
+import { getAllBoards, getBoardById } from "./getters";
+import { KANBAN_QUERY_KEYS } from "./query-key-defs";
+import { serializeBoard } from "./serializers";
+import type { QueryClient } from "@tanstack/react-query";
+
+/**
+ * Route keys for the Kanban plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+export type KanbanRouteKey = "boards" | "newBoard" | "board";
+
+interface KanbanPrefetchForRoute {
+	(key: "boards" | "newBoard", qc: QueryClient): Promise<void>;
+	(key: "board", qc: QueryClient, params: { boardId: string }): Promise<void>;
+}
+
+function createKanbanPrefetchForRoute(
+	adapter: Adapter,
+): KanbanPrefetchForRoute {
+	return async function prefetchForRoute(
+		key: KanbanRouteKey,
+		qc: QueryClient,
+		params?: Record<string, string>,
+	): Promise<void> {
+		switch (key) {
+			case "boards": {
+				const result = await getAllBoards(adapter, { limit: 50, offset: 0 });
+				qc.setQueryData(
+					KANBAN_QUERY_KEYS.boardsList({}),
+					result.items.map(serializeBoard),
+				);
+				break;
+			}
+			case "board": {
+				const boardId = params?.boardId ?? "";
+				if (boardId) {
+					const board = await getBoardById(adapter, boardId);
+					qc.setQueryData(
+						KANBAN_QUERY_KEYS.boardDetail(boardId),
+						board ? serializeBoard(board) : null,
+					);
+				}
+				break;
+			}
+			default:
+				break;
+		}
+	} as KanbanPrefetchForRoute;
+}
 
 /**
  * Context passed to kanban API hooks
@@ -84,10 +133,12 @@ export interface KanbanBackendHooks {
 	) => Promise<boolean> | boolean;
 
 	/**
-	 * Called after boards are listed successfully
+	 * Called after boards are listed successfully.
+	 * Receives the items array (same shape as `board[]`) for consistency
+	 * with analogous hooks in other plugins (e.g. `onPostsRead`).
 	 */
 	onBoardsRead?: (
-		boards: Board[],
+		boards: BoardWithColumns[],
 		filter: z.infer<typeof BoardListQuerySchema>,
 		context: KanbanApiContext,
 	) => Promise<void> | void;
@@ -261,6 +312,13 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 
 		dbPlugin: dbSchema,
 
+		api: (adapter) => ({
+			getAllBoards: (params?: Parameters<typeof getAllBoards>[1]) =>
+				getAllBoards(adapter, params),
+			getBoardById: (id: string) => getBoardById(adapter, id),
+			prefetchForRoute: createKanbanPrefetchForRoute(adapter),
+		}),
+
 		routes: (adapter: Adapter) => {
 			// ============ Board Endpoints ============
 
@@ -284,100 +342,10 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 							}
 						}
 
-						const whereConditions = [];
-
-						if (query.slug) {
-							whereConditions.push({
-								field: "slug",
-								value: query.slug,
-								operator: "eq" as const,
-							});
-						}
-
-						if (query.ownerId) {
-							whereConditions.push({
-								field: "ownerId",
-								value: query.ownerId,
-								operator: "eq" as const,
-							});
-						}
-
-						if (query.organizationId) {
-							whereConditions.push({
-								field: "organizationId",
-								value: query.organizationId,
-								operator: "eq" as const,
-							});
-						}
-
-						const boards = await adapter.findMany<BoardWithKanbanColumn>({
-							model: "kanbanBoard",
-							limit: query.limit ?? 50,
-							offset: query.offset ?? 0,
-							where: whereConditions,
-							sortBy: {
-								field: "createdAt",
-								direction: "desc",
-							},
-							join: {
-								kanbanColumn: true,
-							},
-						});
-
-						// Get all column IDs to fetch tasks
-						// Note: adapter returns joined data under schema key name ("column"), not model name
-						const columnIds: string[] = [];
-						for (const board of boards) {
-							if (board.column) {
-								for (const col of board.column) {
-									columnIds.push(col.id);
-								}
-							}
-						}
-
-						// Fetch tasks for each column in parallel (avoids loading all tasks from DB)
-						const tasksByColumn = new Map<string, Task[]>();
-						if (columnIds.length > 0) {
-							const taskQueries = columnIds.map((columnId) =>
-								adapter.findMany<Task>({
-									model: "kanbanTask",
-									where: [
-										{
-											field: "columnId",
-											value: columnId,
-											operator: "eq" as const,
-										},
-									],
-									sortBy: { field: "order", direction: "asc" },
-								}),
-							);
-							const taskResults = await Promise.all(taskQueries);
-							for (let i = 0; i < columnIds.length; i++) {
-								const columnId = columnIds[i];
-								const tasks = taskResults[i];
-								if (columnId && tasks) {
-									tasksByColumn.set(columnId, tasks);
-								}
-							}
-						}
-
-						// Map boards with columns and tasks
-						const result = boards.map((board) => {
-							const columns = (board.column || [])
-								.sort((a, b) => a.order - b.order)
-								.map((col) => ({
-									...col,
-									tasks: tasksByColumn.get(col.id) || [],
-								}));
-							const { column: _, ...boardWithoutJoin } = board;
-							return {
-								...boardWithoutJoin,
-								columns,
-							};
-						});
+						const result = await getAllBoards(adapter, query);
 
 						if (hooks?.onBoardsRead) {
-							await hooks.onBoardsRead(result, query, context);
+							await hooks.onBoardsRead(result.items, query, context);
 						}
 
 						return result;
@@ -409,61 +377,12 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 							}
 						}
 
-						const board = await adapter.findOne<BoardWithKanbanColumn>({
-							model: "kanbanBoard",
-							where: [
-								{ field: "id", value: params.id, operator: "eq" as const },
-							],
-							join: {
-								kanbanColumn: true,
-							},
-						});
+						const result = await getBoardById(adapter, params.id);
 
-						if (!board) {
+						if (!result) {
 							throw ctx.error(404, { message: "Board not found" });
 						}
 
-						// Fetch tasks for each column in parallel (avoids loading all tasks from DB)
-						// Note: adapter returns joined data under schema key name ("column"), not model name
-						const columnIds = (board.column || []).map((c) => c.id);
-						const tasksByColumn = new Map<string, Task[]>();
-						if (columnIds.length > 0) {
-							const taskQueries = columnIds.map((columnId) =>
-								adapter.findMany<Task>({
-									model: "kanbanTask",
-									where: [
-										{
-											field: "columnId",
-											value: columnId,
-											operator: "eq" as const,
-										},
-									],
-									sortBy: { field: "order", direction: "asc" },
-								}),
-							);
-							const taskResults = await Promise.all(taskQueries);
-							for (let i = 0; i < columnIds.length; i++) {
-								const columnId = columnIds[i];
-								const tasks = taskResults[i];
-								if (columnId && tasks) {
-									tasksByColumn.set(columnId, tasks);
-								}
-							}
-						}
-
-						const columns = (board.column || [])
-							.sort((a, b) => a.order - b.order)
-							.map((col) => ({
-								...col,
-								tasks: tasksByColumn.get(col.id) || [],
-							}));
-
-						const { column: _, ...boardWithoutJoin } = board;
-						const result = {
-							...boardWithoutJoin,
-							columns,
-						};
-
 						if (hooks?.onBoardRead) {
 							await hooks.onBoardRead(result, context);
 						}

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

@@ -0,0 +1,54 @@
+/**
+ * Internal query key constants for the Kanban plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+
+export interface BoardsListDiscriminator {
+	slug: string | undefined;
+	ownerId: string | undefined;
+	organizationId: string | undefined;
+	limit: number;
+	offset: number;
+}
+
+/**
+ * Builds the discriminator object for the boards list query key.
+ * Mirrors the inline object used in createBoardsQueries.list.
+ */
+export function boardsListDiscriminator(params?: {
+	slug?: string;
+	ownerId?: string;
+	organizationId?: string;
+	limit?: number;
+	offset?: number;
+}): BoardsListDiscriminator {
+	return {
+		slug: params?.slug,
+		ownerId: params?.ownerId,
+		organizationId: params?.organizationId,
+		limit: params?.limit ?? 50,
+		offset: params?.offset ?? 0,
+	};
+}
+
+/** Full query key builders — use these with queryClient.setQueryData() */
+export const KANBAN_QUERY_KEYS = {
+	/**
+	 * Key for boards.list(params) query.
+	 * Full key: ["boards", "list", { slug, ownerId, organizationId, limit, offset }]
+	 */
+	boardsList: (params?: {
+		slug?: string;
+		ownerId?: string;
+		organizationId?: string;
+		limit?: number;
+		offset?: number;
+	}) => ["boards", "list", boardsListDiscriminator(params)] as const,
+
+	/**
+	 * Key for boards.detail(boardId) query.
+	 * Full key: ["boards", "detail", boardId]
+	 */
+	boardDetail: (boardId: string) => ["boards", "detail", boardId] as const,
+};

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

@@ -0,0 +1,49 @@
+import type {
+	Task,
+	ColumnWithTasks,
+	BoardWithColumns,
+	SerializedTask,
+	SerializedColumn,
+	SerializedBoardWithColumns,
+} from "../types";
+
+/**
+ * Serialize a Task for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeTask(task: Task): SerializedTask {
+	return {
+		...task,
+		completedAt: task.completedAt?.toISOString(),
+		createdAt: task.createdAt.toISOString(),
+		updatedAt: task.updatedAt.toISOString(),
+	};
+}
+
+/**
+ * Serialize a Column (with its tasks) for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeColumn(col: ColumnWithTasks): SerializedColumn {
+	return {
+		...col,
+		createdAt: col.createdAt.toISOString(),
+		updatedAt: col.updatedAt.toISOString(),
+		tasks: col.tasks.map(serializeTask),
+	};
+}
+
+/**
+ * Serialize a Board (with columns and tasks) for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeBoard(
+	board: BoardWithColumns,
+): SerializedBoardWithColumns {
+	return {
+		...board,
+		createdAt: board.createdAt.toISOString(),
+		updatedAt: board.updatedAt.toISOString(),
+		columns: board.columns.map(serializeColumn),
+	};
+}