@btst/stack 5.0.0 → 5.1.0

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

@@ -6,6 +6,7 @@ import {
 	OperationHttpError,
 	type OperationContext,
 	type OperationData,
+	type OperationCallSignature,
 } from "@btst/stack/plugins/api";
 import { z } from "zod";
 import { formSchemaToZod } from "@workspace/ui/lib/schema-converter";
@@ -13,9 +14,13 @@ import { cmsPermissions } from "../permissions";
 import {
 	createListContentQuerySchema,
 	DEFAULT_MAX_PAGE_SIZE,
+	contentReadOptionsSchema,
 } from "../schemas";
 import type {
 	CMSBackendHooks,
+	CMSReadOptions,
+	CMSContentFields,
+	CMSSelectedData,
 	CMSCreateOperationContext,
 	CMSDeleteOperationContext,
 	CMSOperationData,
@@ -32,6 +37,10 @@ import type {
 import { slugify } from "../utils";
 import {
 	getAllContentItems,
+	validateContentReadOptions,
+	CMSContentSelectionError,
+	applyContentReadOptions,
+	getContentItemsByRelationForType,
 	getContentItemBySlug,
 	serializeContentItemWithType,
 	serializeContentType,
@@ -66,16 +75,50 @@ function operationContentItem(item: SerializedContentItemWithType) {
 }
 
 function operationContentList(
-	result: Awaited<ReturnType<typeof getAllContentItems>>,
+	result: Awaited<ReturnType<typeof getAllContentItems<undefined>>>,
+	options?: CMSReadOptions,
 ) {
 	return {
-		items: result.items.map(operationContentItem),
+		items: result.items.map((item) =>
+			applyContentReadOptions(operationContentItem(item), options),
+		),
 		total: result.total,
 		...(result.limit !== undefined ? { limit: result.limit } : {}),
 		...(result.offset !== undefined ? { offset: result.offset } : {}),
 	};
 }
 
+type ContentReadOperationContent<TOptions> = Omit<
+	Pick<
+		ReturnType<typeof operationContentItem>,
+		"id" | "slug" | "parsedData" | "createdAt" | "updatedAt"
+	>,
+	"parsedData"
+> & {
+	parsedData: TOptions extends {
+		fields?: infer TFields extends CMSContentFields;
+	}
+		? CMSSelectedData<Record<string, unknown>, TFields>
+		: ReturnType<typeof operationContentItem>["parsedData"];
+};
+
+type ContentReadOperationItem<TOptions> = TOptions extends { view: "content" }
+	? ContentReadOperationContent<TOptions>
+	: TOptions extends { view?: undefined }
+		? ReturnType<typeof operationContentItem>
+		: "view" extends keyof TOptions
+			?
+					| ReturnType<typeof operationContentItem>
+					| ContentReadOperationContent<TOptions>
+			: ReturnType<typeof operationContentItem>;
+
+type ContentReadOperationPage<TOptions> = DeepReadonly<{
+	items: ContentReadOperationItem<TOptions>[];
+	total: number;
+	limit: number;
+	offset: number;
+}>;
+
 const JSONValueSchema: z.ZodType<OperationData> = z.lazy(() =>
 	z.union([
 		z.string(),
@@ -114,7 +157,9 @@ export const CMSUpdateContentItemBodySchema = z.object({
 
 const ListContentTypesInputSchema = EmptyInputSchema;
 const GetContentTypeInputSchema = CMSContentTypeParamsSchema;
-const GetContentItemInputSchema = CMSContentItemParamsSchema;
+const GetContentItemInputSchema = CMSContentItemParamsSchema.extend(
+	contentReadOptionsSchema.shape,
+);
 const CreateContentItemInputSchema = z.object({
 	typeSlug: z.string().min(1),
 	body: CMSCreateContentItemBodySchema,
@@ -161,6 +206,25 @@ export class CMSOperationError extends OperationHttpError {
 	}
 }
 
+function validateOperationContentReadOptions(
+	contentType: Pick<ContentType, "jsonSchema"> | undefined,
+	options: CMSReadOptions,
+) {
+	try {
+		validateContentReadOptions(contentType, options);
+	} catch (error) {
+		if (error instanceof CMSContentSelectionError) {
+			throw new CMSOperationError(
+				400,
+				error.message,
+				"INVALID_CONTENT_FIELDS",
+				[{ path: ["fields"], message: error.message }],
+			);
+		}
+		throw error;
+	}
+}
+
 function normalizeOperationError(error: unknown, fallback: string): Error {
 	if (error instanceof Error) return error;
 	return new Error(typeof error === "string" ? error : fallback, {
@@ -930,49 +994,6 @@ async function deriveInverseSourceAuthorization(
 	};
 }
 
-async function listRecordsForRelation(
-	adapter: Adapter,
-	contentType: ContentType,
-	fieldName: string,
-	targetId: string,
-	limit: number,
-	offset: number,
-) {
-	const relations = await adapter.findMany<ContentRelation>({
-		model: "contentRelation",
-		where: [
-			{ field: "targetId", value: targetId, operator: "eq" as const },
-			{ field: "fieldName", value: fieldName, operator: "eq" as const },
-		],
-	});
-	const ids = [...new Set(relations.map((relation) => relation.sourceId))];
-	const items: ContentItemWithType[] = [];
-	for (const id of ids) {
-		const item = await adapter.findOne<ContentItemWithType>({
-			model: "contentItem",
-			where: [
-				{ field: "id", value: id, operator: "eq" as const },
-				{
-					field: "contentTypeId",
-					value: contentType.id,
-					operator: "eq" as const,
-				},
-			],
-			join: { contentType: true },
-		});
-		if (item) items.push(item);
-	}
-	items.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
-	return {
-		items: items
-			.slice(offset, offset + limit)
-			.map(serializeContentItemWithType),
-		total: items.length,
-		limit,
-		offset,
-	};
-}
-
 type EnsureSynced = () => Promise<void>;
 type GetContentTypesWithCounts = () => Promise<
 	Array<ReturnType<typeof serializeContentType> & { itemCount: number }>
@@ -1214,7 +1235,8 @@ export function createCMSOperations(
 		typeSlug: z.string().min(1),
 		query: z
 			.object({ field: z.string().min(1), targetId: z.string().min(1) })
-			.merge(paginationSchema),
+			.merge(paginationSchema)
+			.merge(contentReadOptionsSchema),
 	});
 	const GetInverseRelationsInputSchema = z.object({
 		slug: z.string().min(1),
@@ -1228,7 +1250,8 @@ export function createCMSOperations(
 				itemId: z.string().min(1),
 				fieldName: z.string().min(1),
 			})
-			.merge(paginationSchema),
+			.merge(paginationSchema)
+			.merge(contentReadOptionsSchema),
 	});
 
 	const notifyError = async (
@@ -1338,11 +1361,17 @@ export function createCMSOperations(
 			cmsPermissions.contentType.read({ contentType: facts.contentType }),
 		],
 		execute: async ({ input, facts }) => {
-			const result = await getAllContentItems(
-				adapter,
-				facts.contentType,
-				input.query,
-			);
+			if (input.query.fields !== undefined) {
+				validateOperationContentReadOptions(
+					await getContentTypeOrThrow(adapter, ensureSynced, facts.contentType),
+					input.query,
+				);
+			}
+			const result = await getAllContentItems(adapter, facts.contentType, {
+				...input.query,
+				view: undefined,
+				fields: undefined,
+			});
 			if (facts.scope === "record") {
 				if (!facts.recordId) {
 					if (result.items.length > 0) throw staleRecordError();
@@ -1355,7 +1384,7 @@ export function createCMSOperations(
 					) {
 						throw staleRecordError();
 					}
-					return operationContentList(result);
+					return operationContentList(result, input.query);
 				}
 				if (result.items.length > 1) throw staleRecordError();
 				if (result.items.length === 0) {
@@ -1370,7 +1399,7 @@ export function createCMSOperations(
 					assertRecordFacts(result.items[0]!, facts);
 				}
 			}
-			return operationContentList(result);
+			return operationContentList(result, input.query);
 		},
 		onError: ({ error, ...context }) =>
 			notifyError(
@@ -1390,7 +1419,7 @@ export function createCMSOperations(
 		additionalPermissions: ({ facts }) => [
 			cmsPermissions.contentType.read({ contentType: facts.contentType }),
 		],
-		execute: async ({ facts }) => {
+		execute: async ({ input, facts }) => {
 			const item = await getRecordOrThrow(
 				adapter,
 				ensureSynced,
@@ -1398,7 +1427,11 @@ export function createCMSOperations(
 				facts.recordId ?? "",
 			);
 			assertRecordFacts(item, facts);
-			return operationContentItem(serializeContentItemWithType(item));
+			validateOperationContentReadOptions(item.contentType, input);
+			return applyContentReadOptions(
+				operationContentItem(serializeContentItemWithType(item)),
+				input,
+			);
 		},
 		onError: ({ error, ...context }) =>
 			notifyError(
@@ -1866,7 +1899,7 @@ export function createCMSOperations(
 	});
 
 	const getContentItemPopulated = defineOperation({
-		input: GetContentItemInputSchema,
+		input: CMSContentItemParamsSchema,
 		permission: cmsPermissions.record.read,
 		facts: async ({ input }) =>
 			recordFacts(
@@ -1973,17 +2006,17 @@ export function createCMSOperations(
 				input.query.field,
 				input.query.targetId,
 			);
-			const result = await listRecordsForRelation(
+			validateOperationContentReadOptions(sourceContentType, input.query);
+			const result = await getContentItemsByRelationForType(
 				adapter,
 				sourceContentType,
-				input.query.field,
-				input.query.targetId,
-				input.query.limit,
-				input.query.offset,
+				input.query,
 			);
 			return {
 				...result,
-				items: result.items.map(operationContentItem),
+				items: result.items.map((item) =>
+					applyContentReadOptions(operationContentItem(item), input.query),
+				),
 			};
 		},
 		onError: ({ error, ...context }) =>
@@ -2178,17 +2211,27 @@ export function createCMSOperations(
 					input.slug,
 					input.query.itemId,
 				);
-				const result = await listRecordsForRelation(
+				const sourceContentType = await getContentTypeOrThrow(
 					adapter,
-					await getContentTypeOrThrow(adapter, ensureSynced, facts.contentType),
-					source.fieldName,
-					input.query.itemId,
-					input.query.limit,
-					input.query.offset,
+					ensureSynced,
+					facts.contentType,
+				);
+				validateOperationContentReadOptions(sourceContentType, input.query);
+				const result = await getContentItemsByRelationForType(
+					adapter,
+					sourceContentType,
+					{
+						field: source.fieldName,
+						targetId: input.query.itemId,
+						limit: input.query.limit,
+						offset: input.query.offset,
+					},
 				);
 				return {
 					...result,
-					items: result.items.map(operationContentItem),
+					items: result.items.map((item) =>
+						applyContentReadOptions(operationContentItem(item), input.query),
+					),
 				};
 			} finally {
 				inverseTargetAuthorizationSnapshots.delete(input as object);
@@ -2205,14 +2248,59 @@ export function createCMSOperations(
 	return {
 		listContentTypes,
 		getContentTypeBySlug,
-		listContentItems,
-		getContentItem,
+		listContentItems: listContentItems as typeof listContentItems &
+			OperationCallSignature<
+				<
+					const TInput extends DeepReadonly<
+						z.input<typeof ListContentItemsInputSchema>
+					>,
+				>(
+					input: TInput,
+				) => Promise<
+					DeepReadonly<{
+						items: ContentReadOperationItem<TInput["query"]>[];
+						total: number;
+						limit: number;
+						offset: number;
+					}>
+				>
+			>,
+		getContentItem: getContentItem as typeof getContentItem &
+			OperationCallSignature<
+				<
+					const TInput extends DeepReadonly<
+						z.input<typeof GetContentItemInputSchema>
+					>,
+				>(
+					input: TInput,
+				) => Promise<DeepReadonly<ContentReadOperationItem<TInput>>>
+			>,
 		createContentItem,
 		updateContentItem,
 		deleteContentItem,
 		getContentItemPopulated,
-		listContentByRelation,
+		listContentByRelation:
+			listContentByRelation as typeof listContentByRelation &
+				OperationCallSignature<
+					<
+						const TInput extends DeepReadonly<
+							z.input<typeof ListContentByRelationInputSchema>
+						>,
+					>(
+						input: TInput,
+					) => Promise<ContentReadOperationPage<TInput["query"]>>
+				>,
 		getInverseRelations,
-		listInverseRelationItems,
+		listInverseRelationItems:
+			listInverseRelationItems as typeof listInverseRelationItems &
+				OperationCallSignature<
+					<
+						const TInput extends DeepReadonly<
+							z.input<typeof ListInverseRelationItemsInputSchema>
+						>,
+					>(
+						input: TInput,
+					) => Promise<ContentReadOperationPage<TInput["query"]>>
+				>,
 	} as const;
 }

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

@@ -7,8 +7,15 @@ import { cmsSchema as dbSchema } from "../db";
 import {
 	createListContentQuerySchema,
 	DEFAULT_MAX_PAGE_SIZE,
+	contentReadOptionsSchema,
+	contentReadQuerySchema,
 } from "../schemas";
-import type { CMSBackendConfig, CMSBackendHooks, ContentType } from "../types";
+import type {
+	CMSBackendConfig,
+	CMSBackendHooks,
+	ContentType,
+	CMSReadOptions,
+} from "../types";
 export { CMS_LIFECYCLE_HOOK_MIGRATIONS } from "./lifecycle-migrations";
 import {
 	getAllContentItems,
@@ -54,12 +61,16 @@ interface CMSPrefetchForRoute {
 	(
 		key: "contentList",
 		qc: QueryClient,
-		params: { typeSlug: string },
+		params: {
+			typeSlug: string;
+			limit?: number;
+			search?: string;
+		} & CMSReadOptions,
 	): Promise<void>;
 	(
 		key: "editContent",
 		qc: QueryClient,
-		params: { typeSlug: string; id: string },
+		params: { typeSlug: string; id: string } & CMSReadOptions,
 	): Promise<void>;
 }
 
@@ -187,7 +198,12 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 		async function prefetchForRoute(
 			key: CMSRouteKey,
 			queryClient: QueryClient,
-			params?: Record<string, string>,
+			params?: {
+				typeSlug?: string;
+				id?: string;
+				limit?: number;
+				search?: string;
+			} & CMSReadOptions,
 		): Promise<void> {
 			await ensureSynced(adapter);
 			switch (key) {
@@ -200,13 +216,21 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 					break;
 				case "contentList": {
 					const typeSlug = params?.typeSlug ?? "";
+					const options = createListContentQuerySchema(
+						config.maxPageSize,
+					).parse({
+						limit: params?.limit,
+						search: params?.search,
+						view: params?.view,
+						fields: params?.fields,
+					});
 					const [contentTypes, contentItems] = await Promise.all([
 						getContentTypesWithCounts(adapter),
-						getAllContentItems(adapter, typeSlug, { limit: 20, offset: 0 }),
+						getAllContentItems(adapter, typeSlug, options),
 					]);
 					queryClient.setQueryData(CMS_QUERY_KEYS.typesList(), contentTypes);
 					queryClient.setQueryData(
-						CMS_QUERY_KEYS.contentList({ typeSlug, limit: 20, offset: 0 }),
+						CMS_QUERY_KEYS.contentList({ typeSlug, ...options }),
 						{
 							pages: [
 								{
@@ -224,14 +248,20 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 				case "editContent": {
 					const typeSlug = params?.typeSlug ?? "";
 					const id = params?.id ?? "";
+					const options = contentReadOptionsSchema.parse({
+						view: params?.view,
+						fields: params?.fields,
+					});
 					const [contentTypes, item] = await Promise.all([
 						getContentTypesWithCounts(adapter),
-						id ? getContentItemById(adapter, id) : Promise.resolve(null),
+						id
+							? getContentItemById(adapter, id, options)
+							: Promise.resolve(null),
 					]);
 					queryClient.setQueryData(CMS_QUERY_KEYS.typesList(), contentTypes);
 					if (id) {
 						queryClient.setQueryData(
-							CMS_QUERY_KEYS.contentDetail(typeSlug, id),
+							CMS_QUERY_KEYS.contentDetail(typeSlug, id, options),
 							item,
 						);
 					}
@@ -259,7 +289,9 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 		}),
 
 		routes: (_adapter: Adapter, _context, operations) => {
-			const listQuerySchema = createListContentQuerySchema(config.maxPageSize);
+			const listQuerySchema = createListContentQuerySchema(
+				config.maxPageSize,
+			).extend(contentReadQuerySchema.shape);
 			const paginationSchema = z.object({
 				limit: z.coerce
 					.number()
@@ -301,9 +333,13 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 				{
 					method: "GET",
 					params: CMSContentItemParamsSchema,
+					query: contentReadQuerySchema,
 					requireRequest: true,
 				},
-				operations.getContentItem.route((ctx) => ctx.params),
+				operations.getContentItem.route((ctx) => ({
+					...ctx.params,
+					...ctx.query,
+				})),
 			);
 			const createContentItem = createEndpoint(
 				"/content/:typeSlug",
@@ -356,7 +392,8 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 					params: z.object({ typeSlug: z.string().min(1) }),
 					query: z
 						.object({ field: z.string(), targetId: z.string() })
-						.merge(paginationSchema),
+						.merge(paginationSchema)
+						.merge(contentReadQuerySchema),
 					requireRequest: true,
 				},
 				operations.listContentByRelation.route((ctx) => ({
@@ -387,7 +424,8 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 					}),
 					query: z
 						.object({ itemId: z.string(), fieldName: z.string() })
-						.merge(paginationSchema),
+						.merge(paginationSchema)
+						.merge(contentReadQuerySchema),
 					requireRequest: true,
 				},
 				operations.listInverseRelationItems.route((ctx) => ({

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

@@ -3,12 +3,34 @@
  * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
  * to prevent key drift between SSR loaders and SSG prefetching.
  */
+import type { CMSReadOptions } from "../types";
+
+import { normalizeContentFields } from "../schemas";
+
+/** Shared output discriminator for HTTP resources and database prefetch. */
+export function contentReadDiscriminator(options?: CMSReadOptions) {
+	return {
+		...(options?.view ? { view: options.view } : {}),
+		...(options?.fields !== undefined
+			? { fields: normalizeContentFields(options.fields) }
+			: {}),
+	};
+}
+
+/** Preserve default detail identities while separating every output shape. */
+export function contentReadKey(options?: CMSReadOptions) {
+	return options?.view || options?.fields !== undefined
+		? [contentReadDiscriminator(options)]
+		: [];
+}
 
 export interface ContentListDiscriminator {
 	typeSlug: string;
 	limit: number;
 	offset: number;
 	search: string | undefined;
+	view?: "content";
+	fields?: readonly string[];
 }
 
 /**
@@ -22,8 +44,11 @@ export function contentListDiscriminator(params: {
 	limit?: number;
 	offset?: number;
 	search?: string;
+	view?: "content";
+	fields?: readonly string[];
 }): ContentListDiscriminator {
 	return {
+		...contentReadDiscriminator(params),
 		typeSlug: params.typeSlug,
 		limit: params.limit ?? 20,
 		offset: params.offset ?? 0,
@@ -51,12 +76,14 @@ export const CMS_QUERY_KEYS = {
 		limit?: number;
 		offset?: number;
 		search?: string;
+		view?: "content";
+		fields?: readonly string[];
 	}) => ["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,
+	contentDetail: (typeSlug: string, id: string, options?: CMSReadOptions) =>
+		["cmsContent", "detail", typeSlug, id, ...contentReadKey(options)] as const,
 };