@btst/stack 2.1.0 → 2.3.0

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

@@ -14,8 +14,6 @@ import type {
 	ContentRelation,
 	CMSBackendConfig,
 	CMSHookContext,
-	SerializedContentType,
-	SerializedContentItem,
 	SerializedContentItemWithType,
 	RelationConfig,
 	RelationValue,
@@ -23,96 +21,40 @@ import type {
 } from "../types";
 import { listContentQuerySchema } from "../schemas";
 import { slugify } from "../utils";
+import {
+	getAllContentTypes,
+	getAllContentItems,
+	getContentItemBySlug,
+	getContentItemById,
+	serializeContentType,
+	serializeContentItem,
+	serializeContentItemWithType,
+} from "./getters";
+import type { QueryClient } from "@tanstack/react-query";
+import { CMS_QUERY_KEYS } from "./query-key-defs";
 
 /**
- * Migrate a legacy JSON Schema (version 1) to unified format (version 2)
- * by merging fieldConfig values into the JSON Schema properties
- */
-function migrateToUnifiedSchema(
-	jsonSchemaStr: string,
-	fieldConfigStr: string | null | undefined,
-): string {
-	if (!fieldConfigStr) {
-		return jsonSchemaStr;
-	}
-
-	try {
-		const jsonSchema = JSON.parse(jsonSchemaStr);
-		const fieldConfig = JSON.parse(fieldConfigStr);
-
-		if (!jsonSchema.properties || typeof fieldConfig !== "object") {
-			return jsonSchemaStr;
-		}
-
-		// Merge fieldType from fieldConfig into each property
-		for (const [key, config] of Object.entries(fieldConfig)) {
-			if (
-				jsonSchema.properties[key] &&
-				typeof config === "object" &&
-				config !== null &&
-				"fieldType" in config
-			) {
-				jsonSchema.properties[key].fieldType = (
-					config as { fieldType: string }
-				).fieldType;
-			}
-		}
-
-		return JSON.stringify(jsonSchema);
-	} catch {
-		// If parsing fails, return original
-		return jsonSchemaStr;
-	}
-}
-
-/**
- * Serialize a ContentType for API response (convert dates to strings)
- * Also applies lazy migration for legacy schemas (version 1 → 2)
- */
-function serializeContentType(ct: ContentType): SerializedContentType {
-	// Check if this is a legacy schema that needs migration
-	const needsMigration = !ct.autoFormVersion || ct.autoFormVersion < 2;
-
-	// Apply lazy migration: merge fieldConfig into jsonSchema on read
-	const migratedJsonSchema = needsMigration
-		? migrateToUnifiedSchema(ct.jsonSchema, ct.fieldConfig)
-		: ct.jsonSchema;
-
-	return {
-		id: ct.id,
-		name: ct.name,
-		slug: ct.slug,
-		description: ct.description,
-		jsonSchema: migratedJsonSchema,
-		createdAt: ct.createdAt.toISOString(),
-		updatedAt: ct.updatedAt.toISOString(),
-	};
-}
-
-/**
- * Serialize a ContentItem for API response (convert dates to strings)
- */
-function serializeContentItem(item: ContentItem): SerializedContentItem {
-	return {
-		...item,
-		createdAt: item.createdAt.toISOString(),
-		updatedAt: item.updatedAt.toISOString(),
-	};
-}
-
-/**
- * Serialize a ContentItem with parsed data and joined ContentType
+ * Route keys for the CMS plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
  */
-function serializeContentItemWithType(
-	item: ContentItemWithType,
-): SerializedContentItemWithType {
-	return {
-		...serializeContentItem(item),
-		parsedData: JSON.parse(item.data),
-		contentType: item.contentType
-			? serializeContentType(item.contentType)
-			: undefined,
-	};
+export type CMSRouteKey =
+	| "dashboard"
+	| "contentList"
+	| "newContent"
+	| "editContent";
+
+interface CMSPrefetchForRoute {
+	(key: "dashboard" | "newContent", qc: QueryClient): Promise<void>;
+	(
+		key: "contentList",
+		qc: QueryClient,
+		params: { typeSlug: string },
+	): Promise<void>;
+	(
+		key: "editContent",
+		qc: QueryClient,
+		params: { typeSlug: string; id: string },
+	): Promise<void>;
 }
 
 /**
@@ -511,34 +453,130 @@ async function populateRelations(
  *
  * @param config - Configuration with content types and optional hooks
  */
-export const cmsBackendPlugin = (config: CMSBackendConfig) =>
-	defineBackendPlugin({
+export const cmsBackendPlugin = (config: CMSBackendConfig) => {
+	// Shared sync state — used by both the api factory and routes handlers so
+	// that calling a getter before any HTTP request has been made still
+	// triggers the one-time content-type sync.
+	let syncPromise: Promise<void> | null = null;
+
+	const ensureSynced = (adapter: Adapter) => {
+		if (!syncPromise) {
+			syncPromise = syncContentTypes(adapter, config).catch((err) => {
+				// Allow retry on next call if sync fails
+				syncPromise = null;
+				throw err;
+			});
+		}
+		return syncPromise;
+	};
+
+	const getContentTypesWithCounts = async (adapter: Adapter) => {
+		const contentTypes = await getAllContentTypes(adapter);
+		return Promise.all(
+			contentTypes.map(async (ct) => {
+				const count: number = await adapter.count({
+					model: "contentItem",
+					where: [
+						{ field: "contentTypeId", value: ct.id, operator: "eq" as const },
+					],
+				});
+				return { ...ct, itemCount: count };
+			}),
+		);
+	};
+
+	const createCMSPrefetchForRoute = (adapter: Adapter): CMSPrefetchForRoute => {
+		return async function prefetchForRoute(
+			key: CMSRouteKey,
+			qc: QueryClient,
+			params?: Record<string, string>,
+		): Promise<void> {
+			// Sync content types once at the top — idempotent for concurrent SSG calls
+			await ensureSynced(adapter);
+
+			switch (key) {
+				case "dashboard":
+				case "newContent": {
+					const typesWithCounts = await getContentTypesWithCounts(adapter);
+					qc.setQueryData(CMS_QUERY_KEYS.typesList(), typesWithCounts);
+					break;
+				}
+				case "contentList": {
+					const typeSlug = params?.typeSlug ?? "";
+					const [contentTypes, contentItems] = await Promise.all([
+						getContentTypesWithCounts(adapter),
+						getAllContentItems(adapter, typeSlug, { limit: 20, offset: 0 }),
+					]);
+					qc.setQueryData(CMS_QUERY_KEYS.typesList(), contentTypes);
+					qc.setQueryData(
+						CMS_QUERY_KEYS.contentList({ typeSlug, limit: 20, offset: 0 }),
+						{
+							pages: [
+								{
+									items: contentItems.items,
+									total: contentItems.total,
+									limit: contentItems.limit ?? 20,
+									offset: contentItems.offset ?? 0,
+								},
+							],
+							pageParams: [0],
+						},
+					);
+					break;
+				}
+				case "editContent": {
+					const typeSlug = params?.typeSlug ?? "";
+					const id = params?.id ?? "";
+					const [contentTypes, item] = await Promise.all([
+						getContentTypesWithCounts(adapter),
+						id ? getContentItemById(adapter, id) : Promise.resolve(null),
+					]);
+					qc.setQueryData(CMS_QUERY_KEYS.typesList(), contentTypes);
+					if (id) {
+						qc.setQueryData(CMS_QUERY_KEYS.contentDetail(typeSlug, id), item);
+					}
+					break;
+				}
+				default:
+					break;
+			}
+		} as CMSPrefetchForRoute;
+	};
+
+	return defineBackendPlugin({
 		name: "cms",
 
 		dbPlugin: dbSchema,
 
-		routes: (adapter: Adapter) => {
-			// Sync content types on first request using promise-based lock
-			// This prevents race conditions when multiple concurrent requests arrive
-			// on cold start within the same instance
-			let syncPromise: Promise<void> | null = null;
-
-			const ensureSynced = async () => {
-				if (!syncPromise) {
-					syncPromise = syncContentTypes(adapter, config).catch((err) => {
-						// If sync fails, allow retry on next request
-						syncPromise = null;
-						throw err;
-					});
-				}
-				await syncPromise;
-			};
+		api: (adapter) => ({
+			getAllContentTypes: async () => {
+				await ensureSynced(adapter);
+				return getAllContentTypes(adapter);
+			},
+			getAllContentItems: async (
+				contentTypeSlug: string,
+				params?: Parameters<typeof getAllContentItems>[2],
+			) => {
+				await ensureSynced(adapter);
+				return getAllContentItems(adapter, contentTypeSlug, params);
+			},
+			getContentItemBySlug: async (contentTypeSlug: string, slug: string) => {
+				await ensureSynced(adapter);
+				return getContentItemBySlug(adapter, contentTypeSlug, slug);
+			},
+			getContentItemById: async (id: string) => {
+				await ensureSynced(adapter);
+				return getContentItemById(adapter, id);
+			},
+			prefetchForRoute: createCMSPrefetchForRoute(adapter),
+		}),
 
+		routes: (adapter: Adapter) => {
 			// Helper to get content type by slug
 			const getContentType = async (
 				slug: string,
 			): Promise<ContentType | null> => {
-				await ensureSynced();
+				await ensureSynced(adapter);
 				return adapter.findOne<ContentType>({
 					model: "contentType",
 					where: [{ field: "slug", value: slug, operator: "eq" as const }],
@@ -560,7 +598,7 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) =>
 				"/content-types",
 				{ method: "GET" },
 				async (ctx) => {
-					await ensureSynced();
+					await ensureSynced(adapter);
 
 					const contentTypes = await adapter.findMany<ContentType>({
 						model: "contentType",
@@ -627,45 +665,7 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) =>
 						throw ctx.error(404, { message: "Content type not found" });
 					}
 
-					const whereConditions = [
-						{
-							field: "contentTypeId",
-							value: contentType.id,
-							operator: "eq" as const,
-						},
-					];
-
-					if (slug) {
-						whereConditions.push({
-							field: "slug",
-							value: slug,
-							operator: "eq" as const,
-						});
-					}
-
-					// Get total count
-					const allItems = await adapter.findMany<ContentItem>({
-						model: "contentItem",
-						where: whereConditions,
-					});
-					const total = allItems.length;
-
-					// Get paginated items
-					const items = await adapter.findMany<ContentItemWithType>({
-						model: "contentItem",
-						where: whereConditions,
-						limit,
-						offset,
-						sortBy: { field: "createdAt", direction: "desc" },
-						join: { contentType: true },
-					});
-
-					return {
-						items: items.map(serializeContentItemWithType),
-						total,
-						limit,
-						offset,
-					};
+					return getAllContentItems(adapter, typeSlug, { slug, limit, offset });
 				},
 			);
 
@@ -1139,7 +1139,7 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) =>
 					const { slug } = ctx.params;
 					const { itemId } = ctx.query;
 
-					await ensureSynced();
+					await ensureSynced(adapter);
 
 					// Get the target content type
 					const targetContentType = await getContentType(slug);
@@ -1239,7 +1239,7 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) =>
 					const { slug, sourceType } = ctx.params;
 					const { itemId, fieldName, limit, offset } = ctx.query;
 
-					await ensureSynced();
+					await ensureSynced(adapter);
 
 					// Verify target content type exists
 					const targetContentType = await getContentType(slug);
@@ -1317,6 +1317,7 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) =>
 			};
 		},
 	});
+};
 
 export type CMSApiRouter = ReturnType<
 	ReturnType<typeof cmsBackendPlugin>["routes"]

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

@@ -0,0 +1,53 @@
+/**
+ * Internal query key constants for the CMS plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+
+export interface ContentListDiscriminator {
+	typeSlug: string;
+	limit: number;
+	offset: number;
+}
+
+/**
+ * Builds the discriminator object used as the cache key for the content list.
+ * Mirrors the params object used in createContentQueries.list so both paths stay in sync.
+ */
+export function contentListDiscriminator(params: {
+	typeSlug: string;
+	limit?: number;
+	offset?: number;
+}): ContentListDiscriminator {
+	return {
+		typeSlug: params.typeSlug,
+		limit: params.limit ?? 20,
+		offset: params.offset ?? 0,
+	};
+}
+
+/** Full query key builders — use these with queryClient.setQueryData() */
+export const CMS_QUERY_KEYS = {
+	/**
+	 * Key for the cmsTypes.list() query.
+	 * Full key: ["cmsTypes", "list", "list"]
+	 */
+	typesList: () => ["cmsTypes", "list", "list"] as const,
+
+	/**
+	 * Key for the cmsContent.list({ typeSlug, limit, offset }) query.
+	 * Full key: ["cmsContent", "list", { typeSlug, limit, offset }]
+	 */
+	contentList: (params: {
+		typeSlug: string;
+		limit?: number;
+		offset?: number;
+	}) => ["cmsContent", "list", contentListDiscriminator(params)] as const,
+
+	/**
+	 * Key for the cmsContent.detail(typeSlug, id) query.
+	 * Full key: ["cmsContent", "detail", typeSlug, id]
+	 */
+	contentDetail: (typeSlug: string, id: string) =>
+		["cmsContent", "detail", typeSlug, id] as const,
+};

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

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

package/src/plugins/cms/client/components/pages/content-editor-page.internal.tsx

@@ -241,7 +241,7 @@ export function ContentEditorPage({ typeSlug, id }: ContentEditorPageProps) {
 					contentType={contentType}
 					initialData={
 						isEditing
-							? item?.parsedData
+							? (item?.parsedData ?? undefined)
 							: Object.keys(prefillParams).length > 0
 								? convertPrefillToFormData(
 										prefillParams,

package/src/plugins/cms/client/hooks/cms-hooks.tsx

@@ -608,9 +608,11 @@ export function useCreateContent<TData = Record<string, unknown>>(
 		onSuccess: async () => {
 			await queryClient.invalidateQueries({
 				queryKey: queries.cmsContent.list._def,
+				refetchType: "all",
 			});
 			await queryClient.invalidateQueries({
 				queryKey: queries.cmsTypes.list._def,
+				refetchType: "all",
 			});
 			if (refresh) {
 				await refresh();
@@ -675,6 +677,7 @@ export function useUpdateContent<TData = Record<string, unknown>>(
 			}
 			await queryClient.invalidateQueries({
 				queryKey: queries.cmsContent.list._def,
+				refetchType: "all",
 			});
 			if (refresh) {
 				await refresh();

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

@@ -2,6 +2,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";
@@ -181,6 +182,12 @@ function createDashboardLoader(config: CMSClientConfig) {
 			} 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/cms] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -275,6 +282,12 @@ function createContentListLoader(typeSlug: string, config: CMSClientConfig) {
 			} 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/cms] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -357,6 +370,12 @@ function createContentEditorLoader(
 			} 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/cms] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}

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

@@ -9,6 +9,7 @@ import type {
 	SerializedContentItemWithType,
 	PaginatedContentItems,
 } from "./types";
+import { contentListDiscriminator } from "./api/query-key-defs";
 
 interface ContentListParams {
 	limit?: number;
@@ -115,7 +116,7 @@ function createContentQueries(
 ) {
 	return createQueryKeys("cmsContent", {
 		list: (params: { typeSlug: string } & ContentListParams) => ({
-			queryKey: [params],
+			queryKey: [contentListDiscriminator(params)],
 			queryFn: async () => {
 				try {
 					const response: unknown = await client("/content/:typeSlug", {

package/src/plugins/cms/types.ts

@@ -178,7 +178,7 @@ export interface SerializedContentItem
  */
 export interface SerializedContentItemWithType<TData = Record<string, unknown>>
 	extends SerializedContentItem {
-	/** Parsed data object (JSON.parse of data field) */
+	/** Parsed data object (JSON.parse of data field). */
 	parsedData: TData;
 	/** Joined content type */
 	contentType?: SerializedContentType;

package/src/plugins/form-builder/__tests__/getters.test.ts

@@ -0,0 +1,159 @@
+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 { formBuilderSchema } from "../db";
+import { getAllForms, getFormBySlug, getFormSubmissions } from "../api/getters";
+
+const createTestAdapter = (): Adapter => {
+	const db = defineDb({}).use(formBuilderSchema);
+	return createMemoryAdapter(db)({});
+};
+
+const SIMPLE_SCHEMA = JSON.stringify({
+	type: "object",
+	properties: { name: { type: "string" } },
+});
+
+async function createForm(
+	adapter: Adapter,
+	slug: string,
+	status = "active",
+): Promise<any> {
+	return adapter.create({
+		model: "form",
+		data: {
+			name: `Form ${slug}`,
+			slug,
+			schema: SIMPLE_SCHEMA,
+			status,
+			createdAt: new Date(),
+			updatedAt: new Date(),
+		},
+	});
+}
+
+describe("form-builder getters", () => {
+	let adapter: Adapter;
+
+	beforeEach(() => {
+		adapter = createTestAdapter();
+	});
+
+	describe("getAllForms", () => {
+		it("returns empty result when no forms exist", async () => {
+			const result = await getAllForms(adapter);
+			expect(result.items).toEqual([]);
+			expect(result.total).toBe(0);
+		});
+
+		it("returns all forms serialized", async () => {
+			await createForm(adapter, "contact");
+			await createForm(adapter, "feedback");
+
+			const result = await getAllForms(adapter);
+			expect(result.items).toHaveLength(2);
+			expect(result.total).toBe(2);
+			expect(typeof result.items[0]!.createdAt).toBe("string");
+		});
+
+		it("filters forms by status", async () => {
+			await createForm(adapter, "active-form", "active");
+			await createForm(adapter, "inactive-form", "inactive");
+
+			const active = await getAllForms(adapter, { status: "active" });
+			expect(active.items).toHaveLength(1);
+			expect(active.items[0]!.slug).toBe("active-form");
+
+			const inactive = await getAllForms(adapter, { status: "inactive" });
+			expect(inactive.items).toHaveLength(1);
+			expect(inactive.items[0]!.slug).toBe("inactive-form");
+		});
+
+		it("respects limit and offset", async () => {
+			for (let i = 1; i <= 4; i++) {
+				await createForm(adapter, `form-${i}`);
+			}
+
+			const page1 = await getAllForms(adapter, { limit: 2, offset: 0 });
+			expect(page1.items).toHaveLength(2);
+			expect(page1.total).toBe(4);
+
+			const page2 = await getAllForms(adapter, { limit: 2, offset: 2 });
+			expect(page2.items).toHaveLength(2);
+		});
+	});
+
+	describe("getFormBySlug", () => {
+		it("returns null when form does not exist", async () => {
+			const form = await getFormBySlug(adapter, "nonexistent");
+			expect(form).toBeNull();
+		});
+
+		it("returns the form when it exists", async () => {
+			await createForm(adapter, "contact");
+
+			const form = await getFormBySlug(adapter, "contact");
+			expect(form).not.toBeNull();
+			expect(form!.slug).toBe("contact");
+			expect(typeof form!.createdAt).toBe("string");
+		});
+	});
+
+	describe("getFormSubmissions", () => {
+		it("returns empty result when form does not exist", async () => {
+			const result = await getFormSubmissions(adapter, "nonexistent-id");
+			expect(result.items).toEqual([]);
+			expect(result.total).toBe(0);
+		});
+
+		it("returns submissions for a form", async () => {
+			const form = (await createForm(adapter, "contact")) as any;
+
+			await adapter.create({
+				model: "formSubmission",
+				data: {
+					formId: form.id,
+					data: JSON.stringify({ name: "Alice" }),
+					submittedAt: new Date(),
+				},
+			});
+			await adapter.create({
+				model: "formSubmission",
+				data: {
+					formId: form.id,
+					data: JSON.stringify({ name: "Bob" }),
+					submittedAt: new Date(),
+				},
+			});
+
+			const result = await getFormSubmissions(adapter, form.id);
+			expect(result.items).toHaveLength(2);
+			expect(result.total).toBe(2);
+			expect(typeof result.items[0]!.submittedAt).toBe("string");
+			expect(result.items[0]!.parsedData).toBeDefined();
+		});
+
+		it("respects pagination", async () => {
+			const form = (await createForm(adapter, "survey")) as any;
+
+			for (let i = 1; i <= 5; i++) {
+				await adapter.create({
+					model: "formSubmission",
+					data: {
+						formId: form.id,
+						data: JSON.stringify({ name: `User ${i}` }),
+						submittedAt: new Date(Date.now() + i * 1000),
+					},
+				});
+			}
+
+			const page1 = await getFormSubmissions(adapter, form.id, {
+				limit: 2,
+				offset: 0,
+			});
+			expect(page1.items).toHaveLength(2);
+			expect(page1.total).toBe(5);
+		});
+	});
+});