@btst/stack 5.0.0 → 5.1.0

package/src/plugins/cms/client/index.ts

@@ -1,6 +1,15 @@
 export { cmsClientPlugin } from "./plugin";
 export type { CMSClientConfig, CMSClientHooks, LoaderContext } from "./plugin";
 export type { ContentTypeConfig } from "../types";
+export type {
+	CMSReadOptions,
+	CMSContentFields,
+	CMSSelectedData,
+	CMSReadView,
+	SerializedContentItemContent,
+	CMSContentItemResult,
+	PaginatedContentItems,
+} from "../types";
 export type {
 	CMSPluginOverrides,
 	CMSProviderConfig,

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

@@ -1,4 +1,5 @@
 import type { CMSApiRouter } from "./api";
+import { normalizeContentFields } from "./schemas";
 import {
 	createApiClient,
 	createResourceQueryKeys,
@@ -9,11 +10,19 @@ import type {
 	SerializedContentItemWithType,
 	PaginatedContentItems,
 	InverseRelation,
+	CMSReadOptions,
+	CMSContentFields,
+	CMSReadView,
+	CMSContentItemResult,
 } from "./types";
-import { contentListDiscriminator } from "./api/query-key-defs";
+import {
+	contentListDiscriminator,
+	contentReadDiscriminator,
+	contentReadKey,
+} from "./api/query-key-defs";
 
 /** Params for the paginated content list (one page per `limit`). */
-export interface ContentListParams {
+export interface ContentListParams extends CMSReadOptions {
 	typeSlug: string;
 	limit?: number;
 	/**
@@ -26,13 +35,13 @@ export interface ContentListParams {
 	search?: string;
 }
 
-interface ContentOptionsParams {
+interface ContentOptionsParams extends CMSReadOptions {
 	typeSlug: string;
 	search?: string;
 	limit?: number;
 }
 
-interface ContentByRelationParams {
+interface ContentByRelationParams extends CMSReadOptions {
 	typeSlug: string;
 	field: string;
 	targetId: string;
@@ -44,11 +53,13 @@ interface InverseRelationsParams {
 	itemId: string;
 }
 
-interface InverseRelationItemsParams {
+interface InverseRelationItemsParams extends CMSReadOptions {
 	slug: string;
 	sourceType: string;
 	itemId: string;
 	fieldName: string;
+	limit?: number;
+	offset?: number;
 }
 
 /** Normalizes an empty/whitespace search term to `undefined`. */
@@ -56,6 +67,29 @@ function normalizeSearch(search: string | undefined): string | undefined {
 	return search !== undefined && search.trim() === "" ? undefined : search;
 }
 
+function contentReadQuery(options?: CMSReadOptions) {
+	return {
+		view: options?.view,
+		fields:
+			options?.fields === undefined
+				? undefined
+				: JSON.stringify(normalizeContentFields(options.fields)),
+	};
+}
+
+function relationPageKey(
+	params: CMSReadOptions & { limit?: number; offset?: number },
+) {
+	const limit = params.limit ?? 20;
+	const offset = params.offset ?? 0;
+	return limit === 20 &&
+		offset === 0 &&
+		!params.view &&
+		params.fields === undefined
+		? []
+		: [{ limit, offset, ...contentReadDiscriminator(params) }];
+}
+
 /**
  * `getNextPageParam` for `{ items, total }` page envelopes: stop when the
  * last page is short or everything is loaded, otherwise continue at the
@@ -122,14 +156,18 @@ export const cmsResources = {
 					sourceType: p.sourceType,
 				}),
 				query: (p: InverseRelationItemsParams) => ({
+					...contentReadQuery(p),
 					itemId: p.itemId,
 					fieldName: p.fieldName,
+					limit: p.limit ?? 20,
+					offset: p.offset ?? 0,
 				}),
 				key: (p: InverseRelationItemsParams) => [
 					p.slug,
 					p.sourceType,
 					p.itemId,
 					p.fieldName,
+					...relationPageKey(p),
 				],
 				select: (
 					data: any,
@@ -145,6 +183,7 @@ export const cmsResources = {
 				path: "/content/:typeSlug",
 				params: (p: ContentListParams) => ({ typeSlug: p.typeSlug }),
 				query: (p: ContentListParams) => ({
+					...contentReadQuery(p),
 					limit: p.limit ?? 20,
 					search: normalizeSearch(p.search),
 				}),
@@ -162,21 +201,44 @@ export const cmsResources = {
 
 			detail: {
 				path: "/content/:typeSlug/:id",
-				params: (typeSlug: string, id: string) => ({ typeSlug, id }),
-				key: (typeSlug: string, id: string) => [typeSlug, id],
+				params: (typeSlug: string, id: string, _options?: CMSReadOptions) => ({
+					typeSlug,
+					id,
+				}),
+				query: (_typeSlug: string, _id: string, options?: CMSReadOptions) =>
+					contentReadQuery(options),
+				key: (typeSlug: string, id: string, options?: CMSReadOptions) => [
+					typeSlug,
+					id,
+					...contentReadKey(options),
+				],
 				select: (
 					data: any,
 					_typeSlug: string,
 					_id: string,
+					_options?: CMSReadOptions,
 				): SerializedContentItemWithType | null => data ?? null,
 				skip: (typeSlug: string, id: string) => !typeSlug || !id,
 			},
 
 			bySlug: {
 				path: "/content/:typeSlug",
-				params: (typeSlug: string, _slug: string) => ({ typeSlug }),
-				query: (_typeSlug: string, slug: string) => ({ slug, limit: 1 }),
-				key: (typeSlug: string, slug: string) => ["bySlug", typeSlug, slug],
+				params: (
+					typeSlug: string,
+					_slug: string,
+					_options?: CMSReadOptions,
+				) => ({ typeSlug }),
+				query: (_typeSlug: string, slug: string, options?: CMSReadOptions) => ({
+					slug,
+					limit: 1,
+					...contentReadQuery(options),
+				}),
+				key: (typeSlug: string, slug: string, options?: CMSReadOptions) => [
+					"bySlug",
+					typeSlug,
+					slug,
+					...contentReadKey(options),
+				],
 				select: (data: any): SerializedContentItemWithType | null =>
 					data?.items?.[0] ?? null,
 				skip: (typeSlug: string, slug: string) => !typeSlug || !slug,
@@ -195,11 +257,17 @@ export const cmsResources = {
 				path: "/content/:typeSlug/by-relation",
 				params: (p: ContentByRelationParams) => ({ typeSlug: p.typeSlug }),
 				query: (p: ContentByRelationParams) => ({
+					...contentReadQuery(p),
 					field: p.field,
 					targetId: p.targetId,
 					limit: p.limit ?? 20,
 				}),
-				key: (p: ContentByRelationParams) => [p.typeSlug, p.field, p.targetId],
+				key: (p: ContentByRelationParams) => [
+					p.typeSlug,
+					p.field,
+					p.targetId,
+					...relationPageKey(p),
+				],
 				select: (
 					data: any,
 					_p: ContentByRelationParams,
@@ -218,6 +286,7 @@ export const cmsResources = {
 				path: "/content/:typeSlug",
 				params: (p: ContentOptionsParams) => ({ typeSlug: p.typeSlug }),
 				query: (p: ContentOptionsParams) => ({
+					...contentReadQuery(p),
 					search: normalizeSearch(p.search),
 					limit: p.limit ?? 50,
 				}),
@@ -226,6 +295,7 @@ export const cmsResources = {
 					p.typeSlug,
 					normalizeSearch(p.search),
 					p.limit ?? 50,
+					...contentReadKey(p),
 				],
 				select: (
 					data: any,
@@ -247,7 +317,12 @@ export const cmsResources = {
 					body: { slug: vars.slug, data: vars.data },
 				}),
 				select: (data: any) => data as SerializedContentItemWithType | null,
-				invalidates: ["cmsContent.list", "cmsTypes.list"],
+				invalidates: [
+					"cmsContent",
+					"cmsTypes.list",
+					"cmsTypes.inverseRelationItems",
+					"cmsTypes.inverseRelations",
+				],
 			},
 			update: {
 				path: "@put/content/:typeSlug/:id",
@@ -261,7 +336,11 @@ export const cmsResources = {
 					body: vars.data,
 				}),
 				select: (data: any) => data as SerializedContentItemWithType | null,
-				invalidates: ["cmsContent.list"],
+				invalidates: [
+					"cmsContent",
+					"cmsTypes.inverseRelationItems",
+					"cmsTypes.inverseRelations",
+				],
 				setData: {
 					query: "detail",
 					args: (updated: SerializedContentItemWithType | null) =>
@@ -277,12 +356,88 @@ export const cmsResources = {
 					params: { typeSlug: vars.typeSlug, id: vars.id },
 				}),
 				select: (data: any) => data as { success: boolean },
-				invalidates: ["cmsContent", "cmsTypes.list"],
+				invalidates: [
+					"cmsContent",
+					"cmsTypes.list",
+					"cmsTypes.inverseRelationItems",
+					"cmsTypes.inverseRelations",
+				],
 			},
 		},
 	},
 } satisfies ResourcesDeclaration;
 
+type CMSResourceQueryKeys = ReturnType<
+	typeof createResourceQueryKeys<typeof cmsResources>
+>;
+type ContentQueryResult<TData> = {
+	queryKey: readonly unknown[];
+	queryFn: (context?: { pageParam?: unknown }) => Promise<TData>;
+};
+type CMSItemQueryEntry = {
+	<
+		TView extends CMSReadView = undefined,
+		const TFields extends CMSContentFields = undefined,
+	>(
+		typeSlug: string,
+		identity: string,
+		options?: CMSReadOptions<TView, TFields>,
+	): ContentQueryResult<CMSContentItemResult<
+		Record<string, unknown>,
+		TView,
+		TFields
+	> | null>;
+	_def: readonly [string, string];
+};
+type CMSRelationQueryEntry<TParams> = {
+	<
+		TView extends CMSReadView = undefined,
+		const TFields extends CMSContentFields = undefined,
+	>(
+		params: Omit<TParams, "view" | "fields"> & CMSReadOptions<TView, TFields>,
+	): ContentQueryResult<
+		PaginatedContentItems<Record<string, unknown>, TView, TFields>
+	>;
+	_def: readonly [string, string];
+};
+type CMSQueryKeys = Omit<CMSResourceQueryKeys, "cmsContent" | "cmsTypes"> & {
+	cmsTypes: Omit<CMSResourceQueryKeys["cmsTypes"], "inverseRelationItems"> & {
+		inverseRelationItems: CMSRelationQueryEntry<InverseRelationItemsParams>;
+	};
+	cmsContent: Omit<
+		CMSResourceQueryKeys["cmsContent"],
+		"list" | "detail" | "bySlug" | "byRelation" | "options"
+	> & {
+		list: {
+			<
+				TView extends CMSReadView = undefined,
+				const TFields extends CMSContentFields = undefined,
+			>(
+				params: Omit<ContentListParams, "view" | "fields"> &
+					CMSReadOptions<TView, TFields>,
+			): ContentQueryResult<
+				PaginatedContentItems<Record<string, unknown>, TView, TFields>
+			>;
+			_def: readonly [string, string];
+		};
+		options: {
+			<
+				TView extends CMSReadView = undefined,
+				const TFields extends CMSContentFields = undefined,
+			>(
+				params: Omit<ContentOptionsParams, "view" | "fields"> &
+					CMSReadOptions<TView, TFields>,
+			): ContentQueryResult<
+				CMSContentItemResult<Record<string, unknown>, TView, TFields>[]
+			>;
+			_def: readonly [string, string];
+		};
+		detail: CMSItemQueryEntry;
+		bySlug: CMSItemQueryEntry;
+		byRelation: CMSRelationQueryEntry<ContentByRelationParams>;
+	};
+};
+
 /**
  * Create CMS query keys for React Query
  * Used by consumers and SSR loaders to fetch content types and content items
@@ -290,6 +445,6 @@ export const cmsResources = {
 export function createCMSQueryKeys(
 	client: ReturnType<typeof createApiClient<CMSApiRouter>>,
 	headers?: HeadersInit,
-) {
-	return createResourceQueryKeys(client, cmsResources, headers);
+): CMSQueryKeys {
+	return createResourceQueryKeys(client, cmsResources, headers) as CMSQueryKeys;
 }

package/src/plugins/cms/schemas.ts

@@ -1,8 +1,37 @@
 import { z } from "zod";
+/** Normalize a field set without changing the caller's array. */
+export function normalizeContentFields(
+	fields: readonly string[] | undefined,
+): string[] | undefined {
+	return fields === undefined ? undefined : [...new Set(fields)].sort();
+}
 
 /** Default upper bound for a single page when no maxPageSize is configured. */
 export const DEFAULT_MAX_PAGE_SIZE = 1000;
 
+/** Shared operation and HTTP output options; authorization remains unchanged. */
+export const contentReadOptionsSchema = z.object({
+	view: z.literal("content").optional(),
+	fields: z
+		.array(z.string())
+		.min(1)
+		.transform((fields) => normalizeContentFields(fields)!)
+		.optional(),
+});
+
+/** HTTP transports one JSON-encoded array; operation inputs retain string arrays. */
+export const contentReadQuerySchema = contentReadOptionsSchema.extend({
+	fields: z.preprocess((value) => {
+		if (value === undefined) return undefined;
+		if (typeof value !== "string") return z.NEVER;
+		try {
+			return JSON.parse(value);
+		} catch {
+			return value;
+		}
+	}, contentReadOptionsSchema.shape.fields),
+});
+
 /**
  * Factory that creates the list-content query schema with a configurable
  * upper bound on the `limit` parameter.
@@ -14,6 +43,7 @@ export function createListContentQuerySchema(
 	maxPageSize = DEFAULT_MAX_PAGE_SIZE,
 ) {
 	return z.object({
+		...contentReadOptionsSchema.shape,
 		slug: z.string().optional(),
 		search: z.string().max(200).optional(),
 		limit: z.coerce.number().min(1).max(maxPageSize).optional().default(20),

package/src/plugins/cms/types.ts

@@ -189,12 +189,59 @@ export interface SerializedContentItemWithType<TData = Record<string, unknown>>
 	_relations?: Record<string, SerializedContentItemWithType[]>;
 }
 
+/** Output shape for CMS reads; omission retains the full editor envelope. */
+export type CMSReadView = "content" | undefined;
+
+/** Literal top-level property names selected from parsed content. */
+export type CMSContentFields = readonly string[] | undefined;
+
+/** Select known literal properties, or an honest partial shape for dynamic arrays. */
+export type CMSSelectedData<
+	TData,
+	TFields extends CMSContentFields = undefined,
+> = TFields extends readonly string[]
+	? string extends TFields[number]
+		? Partial<TData>
+		: Pick<TData, Extract<TFields[number], keyof TData>>
+	: TData;
+
+/** Optional output controls for CMS reads. These do not change access checks. */
+export interface CMSReadOptions<
+	TView extends CMSReadView = CMSReadView,
+	TFields extends CMSContentFields = CMSContentFields,
+> {
+	/** Return identity, parsed content and timestamps without editor metadata. */
+	view?: TView;
+	/** Literal declared top-level content properties. Requires content view. */
+	fields?: TFields;
+}
+
+/** Serialized content envelope without raw JSON or editor metadata. */
+export type SerializedContentItemContent<TData = Record<string, unknown>> =
+	Pick<
+		SerializedContentItemWithType<TData>,
+		"id" | "slug" | "parsedData" | "createdAt" | "updatedAt"
+	>;
+
+/** Result envelope selected by a statically known read view. */
+export type CMSContentItemResult<
+	TData = Record<string, unknown>,
+	TView extends CMSReadView = undefined,
+	TFields extends CMSContentFields = undefined,
+> = TView extends "content"
+	? SerializedContentItemContent<CMSSelectedData<TData, TFields>>
+	: SerializedContentItemWithType<TData>;
+
 /**
  * Paginated list response for content items
  * @template TData - The type of the parsed data (defaults to Record<string, unknown>)
  */
-export interface PaginatedContentItems<TData = Record<string, unknown>> {
-	items: SerializedContentItemWithType<TData>[];
+export interface PaginatedContentItems<
+	TData = Record<string, unknown>,
+	TView extends CMSReadView = undefined,
+	TFields extends CMSContentFields = undefined,
+> {
+	items: CMSContentItemResult<TData, TView, TFields>[];
 	total: number;
 	limit: number;
 	offset: number;

package/src/plugins/media/__tests__/identity-partition.test.tsx

@@ -499,20 +499,26 @@ describe("Media protected query identity partition", () => {
 					status: 200,
 					headers: { "content-type": "application/json" },
 				}),
-			);
+			)
+			.mockResolvedValueOnce(responseFor("user-a-refreshed"));
 		const auth = createIdentityTestAuth(vi.fn(() => null));
 		let attemptedIdentity: string | undefined;
+		let committedIdentity: string | undefined;
+		let filename: string | undefined;
 		let deleteAsset:
 			| ReturnType<typeof useDeleteAsset>["mutateAsync"]
 			| undefined;
-		let suspend = false;
 		const never = new Promise<never>(() => {});
 
 		function Probe() {
-			attemptedIdentity = useIdentity().identity?.id;
-			useAssets({ limit: 40 });
+			const identity = useIdentity().identity?.id;
+			attemptedIdentity = identity;
+			useLayoutEffect(() => {
+				committedIdentity = identity;
+			}, [identity]);
+			filename = useAssets({ limit: 40 }).data?.pages[0]?.items[0]?.filename;
 			deleteAsset = useDeleteAsset().mutateAsync;
-			if (suspend) throw never;
+			if (identity === "user-b") throw never;
 			return null;
 		}
 
@@ -532,24 +538,28 @@ describe("Media protected query identity partition", () => {
 		);
 
 		await act(async () => root.render(tree({ id: "user-a" })));
-		await waitFor(() => fetchMock.mock.calls.length === 1);
+		await waitFor(() => filename === "user-a.jpg");
 		const committedDelete = deleteAsset;
-		suspend = true;
 		await act(() => {
 			startTransition(() => root.render(tree({ id: "user-b" })));
 		});
 		await waitFor(() => attemptedIdentity === "user-b");
+		expect(committedIdentity).toBe("user-a");
 		await act(async () => committedDelete?.("asset-user-a"));
 
-		expect(
-			queryClient.getQueryData(
-				MEDIA_QUERY_KEYS.assetsList(
-					{ limit: 40 },
-					{ id: "user-a" },
-					MEDIA_ENDPOINT,
-				),
+		const committedData = queryClient.getQueryData<{
+			pages: Array<{ items: Array<{ filename: string }> }>;
+		}>(
+			MEDIA_QUERY_KEYS.assetsList(
+				{ limit: 40 },
+				{ id: "user-a" },
+				MEDIA_ENDPOINT,
 			),
-		).toBeUndefined();
+		);
+		expect(committedIdentity).toBe("user-a");
+		expect(committedData?.pages[0]?.items[0]?.filename).toBe(
+			"user-a-refreshed.jpg",
+		);
 		expect(
 			queryClient.getQueryData(
 				MEDIA_QUERY_KEYS.assetsList(
@@ -559,7 +569,7 @@ describe("Media protected query identity partition", () => {
 				),
 			),
 		).toBeUndefined();
-		expect(fetchMock).toHaveBeenCalledTimes(2);
+		expect(fetchMock).toHaveBeenCalledTimes(3);
 	});
 
 	it("does not refetch an unmounted identity during a replacement commit", async () => {