@btst/stack 2.1.0 → 2.3.0

package/src/plugins/form-builder/api/getters.ts

@@ -0,0 +1,226 @@
+import type { Adapter } from "@btst/db";
+import type {
+	Form,
+	FormSubmission,
+	FormSubmissionWithForm,
+	SerializedForm,
+	SerializedFormSubmission,
+	SerializedFormSubmissionWithData,
+} from "../types";
+
+/**
+ * Serialize a Form for SSR/SSG use (convert dates to strings).
+ */
+export function serializeForm(form: Form): SerializedForm {
+	return {
+		id: form.id,
+		name: form.name,
+		slug: form.slug,
+		description: form.description,
+		schema: form.schema,
+		successMessage: form.successMessage,
+		redirectUrl: form.redirectUrl,
+		status: form.status,
+		createdBy: form.createdBy,
+		createdAt: form.createdAt.toISOString(),
+		updatedAt: form.updatedAt.toISOString(),
+	};
+}
+
+/**
+ * Serialize a FormSubmission for SSR/SSG use (convert dates to strings).
+ */
+export function serializeFormSubmission(
+	submission: FormSubmission,
+): SerializedFormSubmission {
+	return {
+		...submission,
+		submittedAt: submission.submittedAt.toISOString(),
+	};
+}
+
+/**
+ * Serialize a FormSubmission with parsed data and joined Form.
+ * If `submission.data` is corrupted JSON, `parsedData` is set to `null` rather
+ * than throwing, so one bad row cannot crash the entire list or SSG build.
+ */
+export function serializeFormSubmissionWithData(
+	submission: FormSubmissionWithForm,
+): SerializedFormSubmissionWithData {
+	let parsedData: Record<string, unknown> | null = null;
+	try {
+		parsedData = JSON.parse(submission.data);
+	} catch {
+		// Corrupted JSON — leave parsedData as null so callers can handle it
+	}
+	return {
+		...serializeFormSubmission(submission),
+		parsedData,
+		form: submission.form ? serializeForm(submission.form) : undefined,
+	};
+}
+
+/**
+ * Retrieve all forms with optional status filter and pagination.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks (e.g. `onBeforeListForms`) 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
+ */
+export async function getAllForms(
+	adapter: Adapter,
+	params?: { status?: string; limit?: number; offset?: number },
+): Promise<{
+	items: SerializedForm[];
+	total: number;
+	limit?: number;
+	offset?: number;
+}> {
+	const whereConditions: Array<{
+		field: string;
+		value: string;
+		operator: "eq";
+	}> = [];
+
+	if (params?.status) {
+		whereConditions.push({
+			field: "status",
+			value: params.status,
+			operator: "eq" as const,
+		});
+	}
+
+	// TODO: remove cast once @btst/db types expose adapter.count()
+	const total: number = await adapter.count({
+		model: "form",
+		where: whereConditions.length > 0 ? whereConditions : undefined,
+	});
+
+	const forms = await adapter.findMany<Form>({
+		model: "form",
+		where: whereConditions.length > 0 ? whereConditions : undefined,
+		limit: params?.limit,
+		offset: params?.offset,
+		sortBy: { field: "createdAt", direction: "desc" },
+	});
+
+	return {
+		items: forms.map(serializeForm),
+		total,
+		limit: params?.limit,
+		offset: params?.offset,
+	};
+}
+
+/**
+ * Retrieve a single form by its ID (UUID).
+ * Returns null if the form is not 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 id - The form UUID
+ */
+export async function getFormById(
+	adapter: Adapter,
+	id: string,
+): Promise<SerializedForm | null> {
+	const form = await adapter.findOne<Form>({
+		model: "form",
+		where: [{ field: "id", value: id, operator: "eq" as const }],
+	});
+	if (!form) return null;
+	return serializeForm(form);
+}
+
+/**
+ * Retrieve a single form by its slug.
+ * Returns null if the form is not 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 form slug
+ */
+export async function getFormBySlug(
+	adapter: Adapter,
+	slug: string,
+): Promise<SerializedForm | null> {
+	const form = await adapter.findOne<Form>({
+		model: "form",
+		where: [{ field: "slug", value: slug, operator: "eq" as const }],
+	});
+
+	if (!form) {
+		return null;
+	}
+
+	return serializeForm(form);
+}
+
+/**
+ * Retrieve submissions for a form by form ID, with optional pagination.
+ * Returns an empty result if the form does not exist.
+ * Pure DB function — no hooks, no HTTP context. Safe for 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 formId - The form ID
+ * @param params - Optional pagination parameters
+ */
+export async function getFormSubmissions(
+	adapter: Adapter,
+	formId: string,
+	params?: { limit?: number; offset?: number },
+): Promise<{
+	items: SerializedFormSubmissionWithData[];
+	total: number;
+	limit?: number;
+	offset?: number;
+}> {
+	const form = await adapter.findOne<Form>({
+		model: "form",
+		where: [{ field: "id", value: formId, operator: "eq" as const }],
+	});
+
+	if (!form) {
+		return {
+			items: [],
+			total: 0,
+			limit: params?.limit,
+			offset: params?.offset,
+		};
+	}
+
+	// TODO: remove cast once @btst/db types expose adapter.count()
+	const total: number = await adapter.count({
+		model: "formSubmission",
+		where: [{ field: "formId", value: formId, operator: "eq" as const }],
+	});
+
+	const submissions = await adapter.findMany<FormSubmissionWithForm>({
+		model: "formSubmission",
+		where: [{ field: "formId", value: formId, operator: "eq" as const }],
+		limit: params?.limit,
+		offset: params?.offset,
+		sortBy: { field: "submittedAt", direction: "desc" },
+		join: { form: true },
+	});
+
+	return {
+		items: submissions.map(serializeFormSubmissionWithData),
+		total,
+		limit: params?.limit,
+		offset: params?.offset,
+	};
+}

package/src/plugins/form-builder/api/index.ts

@@ -1 +1,15 @@
-export { formBuilderBackendPlugin, type FormBuilderApiRouter } from "./plugin";
+export {
+	formBuilderBackendPlugin,
+	type FormBuilderApiRouter,
+	type FormBuilderRouteKey,
+} from "./plugin";
+export {
+	getAllForms,
+	getFormById,
+	getFormBySlug,
+	getFormSubmissions,
+	serializeForm,
+	serializeFormSubmission,
+	serializeFormSubmissionWithData,
+} from "./getters";
+export { FORM_QUERY_KEYS } from "./query-key-defs";

package/src/plugins/form-builder/api/plugin.ts

@@ -11,9 +11,6 @@ import type {
 	FormBuilderBackendConfig,
 	FormBuilderHookContext,
 	SubmissionHookContext,
-	SerializedForm,
-	SerializedFormSubmission,
-	SerializedFormSubmissionWithData,
 	FormInput,
 	FormUpdate,
 } from "../types";
@@ -24,49 +21,102 @@ import {
 	listSubmissionsQuerySchema,
 } from "../schemas";
 import { slugify, extractIpAddress, extractUserAgent } from "../utils";
+import {
+	getAllForms,
+	getFormById as getFormByIdFromDb,
+	getFormBySlug as getFormBySlugFromDb,
+	getFormSubmissions,
+	serializeForm,
+	serializeFormSubmission,
+	serializeFormSubmissionWithData,
+} from "./getters";
+import { FORM_QUERY_KEYS } from "./query-key-defs";
+import type { QueryClient } from "@tanstack/react-query";
 
 /**
- * Serialize a Form for API response (convert dates to strings)
- */
-function serializeForm(form: Form): SerializedForm {
-	return {
-		id: form.id,
-		name: form.name,
-		slug: form.slug,
-		description: form.description,
-		schema: form.schema,
-		successMessage: form.successMessage,
-		redirectUrl: form.redirectUrl,
-		status: form.status,
-		createdBy: form.createdBy,
-		createdAt: form.createdAt.toISOString(),
-		updatedAt: form.updatedAt.toISOString(),
-	};
-}
-
-/**
- * Serialize a FormSubmission for API response (convert dates to strings)
+ * Route keys for the Form Builder plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
  */
-function serializeFormSubmission(
-	submission: FormSubmission,
-): SerializedFormSubmission {
-	return {
-		...submission,
-		submittedAt: submission.submittedAt.toISOString(),
-	};
+export type FormBuilderRouteKey =
+	| "formList"
+	| "newForm"
+	| "editForm"
+	| "submissions";
+
+interface FormBuilderPrefetchForRoute {
+	(key: "formList" | "newForm", qc: QueryClient): Promise<void>;
+	(
+		key: "editForm" | "submissions",
+		qc: QueryClient,
+		params: { id: string },
+	): Promise<void>;
 }
 
-/**
- * Serialize a FormSubmission with parsed data and joined Form
- */
-function serializeFormSubmissionWithData(
-	submission: FormSubmissionWithForm,
-): SerializedFormSubmissionWithData {
-	return {
-		...serializeFormSubmission(submission),
-		parsedData: JSON.parse(submission.data),
-		form: submission.form ? serializeForm(submission.form) : undefined,
-	};
+function createFormBuilderPrefetchForRoute(
+	adapter: Parameters<typeof getAllForms>[0],
+): FormBuilderPrefetchForRoute {
+	return async function prefetchForRoute(
+		key: FormBuilderRouteKey,
+		qc: QueryClient,
+		params?: Record<string, string>,
+	): Promise<void> {
+		switch (key) {
+			case "formList": {
+				const result = await getAllForms(adapter, { limit: 20, offset: 0 });
+				qc.setQueryData(FORM_QUERY_KEYS.formsList({ limit: 20, offset: 0 }), {
+					pages: [
+						{
+							items: result.items,
+							total: result.total,
+							limit: result.limit ?? 20,
+							offset: result.offset ?? 0,
+						},
+					],
+					pageParams: [0],
+				});
+				break;
+			}
+			case "editForm": {
+				const id = params?.id ?? "";
+				if (id) {
+					const form = await getFormByIdFromDb(adapter, id);
+					qc.setQueryData(FORM_QUERY_KEYS.formById(id), form);
+				}
+				break;
+			}
+			case "submissions": {
+				const id = params?.id ?? "";
+				if (id) {
+					const [form, submissionsResult] = await Promise.all([
+						getFormByIdFromDb(adapter, id),
+						getFormSubmissions(adapter, id, { limit: 20, offset: 0 }),
+					]);
+					qc.setQueryData(FORM_QUERY_KEYS.formById(id), form);
+					qc.setQueryData(
+						FORM_QUERY_KEYS.submissionsList({
+							formId: id,
+							limit: 20,
+							offset: 0,
+						}),
+						{
+							pages: [
+								{
+									items: submissionsResult.items,
+									total: submissionsResult.total,
+									limit: submissionsResult.limit ?? 20,
+									offset: submissionsResult.offset ?? 0,
+								},
+							],
+							pageParams: [0],
+						},
+					);
+				}
+				break;
+			}
+			default:
+				break;
+		}
+	} as FormBuilderPrefetchForRoute;
 }
 
 /**
@@ -83,6 +133,18 @@ export const formBuilderBackendPlugin = (
 
 		dbPlugin: dbSchema,
 
+		api: (adapter) => ({
+			getAllForms: (params?: Parameters<typeof getAllForms>[1]) =>
+				getAllForms(adapter, params),
+			getFormById: (id: string) => getFormByIdFromDb(adapter, id),
+			getFormBySlug: (slug: string) => getFormBySlugFromDb(adapter, slug),
+			getFormSubmissions: (
+				formId: string,
+				params?: Parameters<typeof getFormSubmissions>[2],
+			) => getFormSubmissions(adapter, formId, params),
+			prefetchForRoute: createFormBuilderPrefetchForRoute(adapter),
+		}),
+
 		routes: (adapter: Adapter) => {
 			// Helper to create hook context from request
 			const createContext = (headers?: Headers): FormBuilderHookContext => ({
@@ -114,7 +176,6 @@ export const formBuilderBackendPlugin = (
 					const { status, limit, offset } = ctx.query;
 					const context = createContext(ctx.headers);
 
-					// Call before hook for auth check
 					if (config.hooks?.onBeforeListForms) {
 						const canList = await config.hooks.onBeforeListForms(context);
 						if (!canList) {
@@ -122,41 +183,7 @@ export const formBuilderBackendPlugin = (
 						}
 					}
 
-					const whereConditions: Array<{
-						field: string;
-						value: string;
-						operator: "eq";
-					}> = [];
-					if (status) {
-						whereConditions.push({
-							field: "status",
-							value: status,
-							operator: "eq" as const,
-						});
-					}
-
-					// Get total count
-					const allForms = await adapter.findMany<Form>({
-						model: "form",
-						where: whereConditions.length > 0 ? whereConditions : undefined,
-					});
-					const total = allForms.length;
-
-					// Get paginated forms
-					const forms = await adapter.findMany<Form>({
-						model: "form",
-						where: whereConditions.length > 0 ? whereConditions : undefined,
-						limit,
-						offset,
-						sortBy: { field: "createdAt", direction: "desc" },
-					});
-
-					return {
-						items: forms.map(serializeForm),
-						total,
-						limit,
-						offset,
-					};
+					return getAllForms(adapter, { status, limit, offset });
 				},
 			);
 
@@ -178,16 +205,13 @@ export const formBuilderBackendPlugin = (
 						}
 					}
 
-					const form = await adapter.findOne<Form>({
-						model: "form",
-						where: [{ field: "slug", value: slug, operator: "eq" as const }],
-					});
+					const form = await getFormBySlugFromDb(adapter, slug);
 
 					if (!form) {
 						throw ctx.error(404, { message: "Form not found" });
 					}
 
-					return serializeForm(form);
+					return form;
 				},
 			);
 
@@ -647,33 +671,7 @@ export const formBuilderBackendPlugin = (
 						}
 					}
 
-					// Get total count
-					const allSubmissions = await adapter.findMany<FormSubmission>({
-						model: "formSubmission",
-						where: [
-							{ field: "formId", value: formId, operator: "eq" as const },
-						],
-					});
-					const total = allSubmissions.length;
-
-					// Get paginated submissions
-					const submissions = await adapter.findMany<FormSubmissionWithForm>({
-						model: "formSubmission",
-						where: [
-							{ field: "formId", value: formId, operator: "eq" as const },
-						],
-						limit,
-						offset,
-						sortBy: { field: "submittedAt", direction: "desc" },
-						join: { form: true },
-					});
-
-					return {
-						items: submissions.map(serializeFormSubmissionWithData),
-						total,
-						limit,
-						offset,
-					};
+					return getFormSubmissions(adapter, formId, { limit, offset });
 				},
 			);
 

package/src/plugins/form-builder/api/query-key-defs.ts

@@ -0,0 +1,79 @@
+/**
+ * Internal query key constants for the Form Builder plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+
+export interface FormsListDiscriminator {
+	status?: "active" | "inactive" | "archived";
+	limit: number;
+	offset: number;
+}
+
+export interface SubmissionsListDiscriminator {
+	formId: string;
+	limit: number;
+	offset: number;
+}
+
+/**
+ * Builds the discriminator object for the forms list query key.
+ * Mirrors the params object used in createFormsQueries.list.
+ */
+export function formsListDiscriminator(params?: {
+	status?: "active" | "inactive" | "archived";
+	limit?: number;
+	offset?: number;
+}): FormsListDiscriminator {
+	return {
+		status: params?.status,
+		limit: params?.limit ?? 20,
+		offset: params?.offset ?? 0,
+	};
+}
+
+/**
+ * Builds the discriminator object for the submissions list query key.
+ * Mirrors the params object used in createSubmissionsQueries.list.
+ */
+export function submissionsListDiscriminator(params: {
+	formId: string;
+	limit?: number;
+	offset?: number;
+}): SubmissionsListDiscriminator {
+	return {
+		formId: params.formId,
+		limit: params.limit ?? 20,
+		offset: params.offset ?? 0,
+	};
+}
+
+/** Full query key builders — use these with queryClient.setQueryData() */
+export const FORM_QUERY_KEYS = {
+	/**
+	 * Key for forms.list(params) query.
+	 * Full key: ["forms", "list", "list", { status, limit, offset }]
+	 */
+	formsList: (params?: {
+		status?: "active" | "inactive" | "archived";
+		limit?: number;
+		offset?: number;
+	}) => ["forms", "list", "list", formsListDiscriminator(params)] as const,
+
+	/**
+	 * Key for forms.byId(id) query.
+	 * Full key: ["forms", "byId", "byId", id]
+	 */
+	formById: (id: string) => ["forms", "byId", "byId", id] as const,
+
+	/**
+	 * Key for formSubmissions.list(params) query.
+	 * Full key: ["formSubmissions", "list", { formId, limit, offset }]
+	 */
+	submissionsList: (params: {
+		formId: string;
+		limit?: number;
+		offset?: number;
+	}) =>
+		["formSubmissions", "list", submissionsListDiscriminator(params)] as const,
+};

package/src/plugins/form-builder/api/serializers.ts

@@ -0,0 +1,12 @@
+/**
+ * Re-exports serialization helpers from getters.ts for consumers who import
+ * from @btst/stack/plugins/form-builder/api.
+ *
+ * The actual implementations live in getters.ts alongside the DB functions
+ * they serialize so they stay in sync with the returned types.
+ */
+export {
+	serializeForm,
+	serializeFormSubmission,
+	serializeFormSubmissionWithData,
+} from "./getters";

package/src/plugins/form-builder/client/components/pages/submissions-page.internal.tsx

@@ -147,7 +147,7 @@ export function SubmissionsPage({ formId }: SubmissionsPageProps) {
 												{sub.id.slice(0, 8)}...
 											</TableCell>
 											<TableCell className="max-w-xs truncate text-sm text-muted-foreground">
-												{formatSubmissionData(sub.parsedData)}
+												{formatSubmissionData(sub.parsedData ?? {})}
 											</TableCell>
 											<TableCell className="text-muted-foreground">
 												{new Date(sub.submittedAt).toLocaleString()}

package/src/plugins/form-builder/client/plugin.tsx

@@ -3,6 +3,7 @@ import { lazy } from "react";
 import {
 	defineClientPlugin,
 	createApiClient,
+	isConnectionError,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -197,6 +198,12 @@ function createFormListLoader(config: FormBuilderClientConfig) {
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/form-builder] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -265,6 +272,12 @@ function createFormBuilderLoader(
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/form-builder] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -364,6 +377,12 @@ function createSubmissionsLoader(
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/form-builder] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}

package/src/plugins/form-builder/query-keys.ts

@@ -10,6 +10,10 @@ import type {
 	PaginatedFormSubmissions,
 	SerializedFormSubmissionWithData,
 } from "./types";
+import {
+	formsListDiscriminator,
+	submissionsListDiscriminator,
+} from "./api/query-key-defs";
 
 interface FormListParams {
 	status?: "active" | "inactive" | "archived";
@@ -75,7 +79,7 @@ function createFormsQueries(
 ) {
 	return createQueryKeys("forms", {
 		list: (params: FormListParams = {}) => ({
-			queryKey: ["list", params],
+			queryKey: ["list", formsListDiscriminator(params)],
 			queryFn: async () => {
 				try {
 					const response: unknown = await client("/forms", {
@@ -147,7 +151,7 @@ function createSubmissionsQueries(
 ) {
 	return createQueryKeys("formSubmissions", {
 		list: (params: SubmissionListParams) => ({
-			queryKey: [params],
+			queryKey: [submissionsListDiscriminator(params)],
 			queryFn: async () => {
 				try {
 					const response: unknown = await client("/forms/:formId/submissions", {

package/src/plugins/form-builder/types.ts

@@ -82,8 +82,8 @@ export interface SerializedFormSubmission
 export interface SerializedFormSubmissionWithData<
 	TData = Record<string, unknown>,
 > extends SerializedFormSubmission {
-	/** Parsed data object (JSON.parse of data field) */
-	parsedData: TData;
+	/** Parsed data object (JSON.parse of data field). Null when the stored JSON is corrupted. */
+	parsedData: TData | null;
 	/** Joined form */
 	form?: SerializedForm;
 }