@btst/stack 5.0.0 → 5.2.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/crm/__tests__/cache-invalidation.test.tsx

@@ -0,0 +1,145 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { QueryClient } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createClientStack } from "../../../client";
+import { StackProvider } from "../../../context";
+import { defineClientPlugin } from "../../../plugins/client";
+import { createResource } from "../../../plugins/client/hooks";
+import { createCrmQueryKeys, crmResources } from "../query-keys";
+
+(
+	globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+const crm = createResource({ plugin: "crm", resources: crmResources });
+const keys = createCrmQueryKeys(vi.fn());
+const cachedQueries = {
+	contacts: keys.crmContacts.list({}).queryKey,
+	contact: keys.crmContacts.detail("contact").queryKey,
+	companies: keys.crmCompanies.list({}).queryKey,
+	company: keys.crmCompanies.detail("company").queryKey,
+	deals: keys.crmDeals.list({}).queryKey,
+	deal: keys.crmDeals.detail("deal").queryKey,
+	activities: keys.crmActivities.list({ dealId: "deal" }).queryKey,
+	pipelines: keys.crmPipelines.list({}).queryKey,
+	pipeline: keys.crmPipelines.detail("pipeline").queryKey,
+};
+type CachedQuery = keyof typeof cachedQueries;
+
+describe("CRM dependent cache invalidation", () => {
+	let root: Root;
+	let container: HTMLDivElement;
+	let queryClient: QueryClient;
+	beforeEach(() => {
+		queryClient = new QueryClient();
+		container = document.createElement("div");
+		document.body.appendChild(container);
+		root = createRoot(container);
+		vi.spyOn(globalThis, "fetch").mockImplementation(
+			async () =>
+				new Response(JSON.stringify({ success: true }), {
+					headers: { "content-type": "application/json" },
+				}),
+		);
+		for (const key of Object.values(cachedQueries))
+			queryClient.setQueryData(key, { id: "linked-record" });
+	});
+	afterEach(async () => {
+		await act(async () => root.unmount());
+		container.remove();
+		queryClient.clear();
+		vi.restoreAllMocks();
+	});
+	async function mutate(
+		useMutation: () => { mutateAsync: (input: string) => Promise<unknown> },
+	) {
+		const stack = createClientStack({
+			api: { baseURL: "https://example.test", basePath: "/api/data" },
+			site: { baseURL: "https://example.test", basePath: "/pages" },
+			queryClient,
+			plugins: {
+				crm: defineClientPlugin({
+					id: "crm",
+					resolve: () => ({ routes: () => ({}) }),
+				}),
+			},
+		});
+		let mutation!: ReturnType<typeof useMutation>;
+		function Probe() {
+			mutation = useMutation();
+			return null;
+		}
+		await act(async () =>
+			root.render(
+				<StackProvider stack={stack} router={{}}>
+					<Probe />
+				</StackProvider>,
+			),
+		);
+		await act(async () => {
+			await mutation.mutateAsync("deleted-record");
+		});
+	}
+	it.each<{
+		resource: "crmCompanies" | "crmContacts" | "crmDeals";
+		stale: CachedQuery[];
+	}>([
+		{
+			resource: "crmCompanies",
+			stale: [
+				"companies",
+				"company",
+				"contacts",
+				"contact",
+				"deals",
+				"deal",
+				"pipelines",
+				"pipeline",
+			],
+		},
+		{
+			resource: "crmContacts",
+			stale: [
+				"contacts",
+				"contact",
+				"deals",
+				"deal",
+				"activities",
+				"pipelines",
+				"pipeline",
+			],
+		},
+		{
+			resource: "crmDeals",
+			stale: ["deals", "deal", "activities", "pipelines", "pipeline"],
+		},
+	])(
+		"refreshes dependent cached records after deleting $resource",
+		async ({ resource, stale }) => {
+			await mutate(() => crm[resource].delete.use());
+			for (const [name, key] of Object.entries(cachedQueries))
+				expect(queryClient.getQueryState(key)?.isInvalidated, name).toBe(
+					stale.includes(name as CachedQuery),
+				);
+		},
+	);
+	it("refreshes contact search membership when a linked company is renamed", async () => {
+		await mutate(() => {
+			const mutation = crm.crmCompanies.update.use();
+			return {
+				mutateAsync: (id: string) =>
+					mutation.mutateAsync({ id, data: { name: "Renamed company" } }),
+			};
+		});
+		expect(
+			queryClient.getQueryState(cachedQueries.contacts)?.isInvalidated,
+		).toBe(true);
+		expect(
+			queryClient.getQueryState(cachedQueries.contact)?.isInvalidated,
+		).toBe(false);
+		expect(
+			queryClient.getQueryState(cachedQueries.activities)?.isInvalidated,
+		).toBe(false);
+	});
+});