@pattern-stack/codegen 0.26.1 → 0.27.0

package/dist/src/cli/index.js

@@ -46,14 +46,18 @@ import {
   writeManifest
 } from "../../chunk-K4BQQ2NN.js";
 import "../../chunk-KVOWSC5S.js";
+import "../../chunk-VCXOPBYY.js";
 import "../../chunk-PRWIX6UW.js";
-import "../../chunk-7XDB4OMR.js";
-import "../../chunk-QXYKV4CE.js";
+import "../../chunk-W4JYZSQK.js";
 import "../../chunk-EO2QPOKH.js";
-import "../../chunk-HLURWFIT.js";
+import "../../chunk-SQDOBLBP.js";
+import "../../chunk-YIVQ7KLS.js";
+import "../../chunk-LG57S2SC.js";
+import "../../chunk-IASPGFFK.js";
+import "../../chunk-S5G3HO7N.js";
+import "../../chunk-MZ6GV4YF.js";
 import "../../chunk-HNWZFNKP.js";
 import "../../chunk-AHV4GDYM.js";
-import "../../chunk-SQDOBLBP.js";
 import "../../chunk-43SBT72G.js";
 import "../../chunk-4MF3HKJA.js";
 import "../../chunk-TIZXQU26.js";
@@ -63,10 +67,6 @@ import {
 } from "../../chunk-5TK7MEN4.js";
 import "../../chunk-4KNXX6TI.js";
 import "../../chunk-3CJFPU6Q.js";
-import "../../chunk-QO35B6BN.js";
-import "../../chunk-MZ6GV4YF.js";
-import "../../chunk-LG57S2SC.js";
-import "../../chunk-S5G3HO7N.js";
 import "../../chunk-U64T4YZE.js";
 import "../../chunk-2E224ZSN.js";
 
@@ -5343,6 +5343,56 @@ function buildClientFile(ctx) {
 ` : "";
   const body = `${imports}${baseUrlConst}
 
+/** Hard upper bound on a single list fetch \u2014 mirrors the backend pageSize clamp. */
+export const MAX_PAGE_SIZE = 200;
+
+/**
+ * Pagination envelope returned by every \`GET /<entities>\` (pagination-by-default).
+ * Mirrors the backend \`Page<T>\` runtime contract
+ * (\`@pattern-stack/codegen/runtime/http/pagination\`); duplicated here so the
+ * generated frontend data layer carries no backend import. \`nextCursor\` is
+ * contract-stable (the backend emits it from day one) \u2014 the offset engine
+ * ignores it on request for now.
+ */
+export interface Page<T> {
+	items: T[];
+	page: number;
+	pageCount: number;
+	total: number;
+	pageSize: number;
+	nextCursor: string | null;
+}
+
+/**
+ * Request query for a list endpoint: page-based pagination + default sort, plus
+ * arbitrary where-filters (passed through to the backend querystring). All keys
+ * optional \u2014 the unfiltered first page is the default.
+ */
+export interface ListQuery {
+	page?: number;
+	cursor?: string;
+	pageSize?: number;
+	sort_by?: string;
+	sort_order?: 'asc' | 'desc';
+	[key: string]: string | number | boolean | null | undefined;
+}
+
+/**
+ * Serialize a {@link ListQuery} into a querystring (leading \`?\`), skipping
+ * undefined/null values. Returns \`''\` for an empty/absent query so an
+ * unfiltered \`list()\` hits the bare route.
+ */
+export function toListQueryString(query?: ListQuery): string {
+	if (!query) return '';
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) {
+		if (value === undefined || value === null) continue;
+		params.set(key, String(value));
+	}
+	const qs = params.toString();
+	return qs ? \`?\${qs}\` : '';
+}
+
 /**
  * Base REST transport for \`api\` sync-mode collections and entity api clients.
  * Throws on non-2xx; returns parsed JSON, or \`undefined\` for 204 No Content.
@@ -5377,11 +5427,41 @@ function buildEntityApiFile(entity, ctx) {
   const { config } = ctx;
   const { camelName, plural, className, name } = entity;
   const verb = updateVerb(config.architecture);
-  const body = `import { request } from './client';
+  const body = `import { MAX_PAGE_SIZE, type ListQuery, type Page, request, toListQueryString } from './client';
 import type { ${className} } from '${config.dbEntitiesImport}/${name}';
 
 export const ${camelName}Api = {
-	list: (): Promise<${className}[]> => request<${className}[]>('GET', '/${plural}'),
+	/**
+	 * Fetch one page of ${plural} (pagination-by-default). Threads page/cursor/
+	 * pageSize/sort + arbitrary where-filters into the querystring; returns the
+	 * \`Page<${className}>\` envelope. Call with no args for the unfiltered first page.
+	 */
+	list: (query?: ListQuery): Promise<Page<${className}>> =>
+		request<Page<${className}>>('GET', \`/${plural}\${toListQueryString(query)}\`),
+
+	/**
+	 * Full-fetch escape hatch (LANDMINE 1): every ${className} across all pages as a
+	 * flat array. Pages through the envelope until exhausted so off-page FK
+	 * resolution (resolvers/lookups) stays correct under pagination-by-default \u2014
+	 * the backing collection only holds the current page, so FK targets that live
+	 * on another page would otherwise resolve to undefined. Used to hydrate the
+	 * store's resolvers/lookups; NOT for rendering a paged table.
+	 */
+	listAll: async (query?: Omit<ListQuery, 'page' | 'pageSize' | 'cursor'>): Promise<${className}[]> => {
+		const all: ${className}[] = [];
+		let page = 1;
+		let pageCount = 1;
+		do {
+			const result = await request<Page<${className}>>(
+				'GET',
+				\`/${plural}\${toListQueryString({ ...query, page, pageSize: MAX_PAGE_SIZE })}\`,
+			);
+			all.push(...result.items);
+			pageCount = result.pageCount;
+			page += 1;
+		} while (page <= pageCount);
+		return all;
+	},
 
 	get: (id: string): Promise<${className}> =>
 		request<${className}>('GET', \`/${plural}/\${id}\`),
@@ -5513,7 +5593,16 @@ export const ${camelName}Collection = createCollection(
 		id: '${plural}',
 		queryKey: ['${plural}'],
 		queryClient,
-		queryFn: () => ${camelName}Api.list(),
+		// pagination-by-default: the list endpoint returns a Page<T> envelope, so
+		// unwrap \`.items\` to seed the collection with rows (the first page). The
+		// paged table drives later fetches via the sync-layer useList; off-page FK
+		// resolution hydrates from the full-fetch escape hatch (store/resolvers.ts).
+		// async/await (not \`.then\`) so queryCollectionOptions' overload inference
+		// keeps \`getKey\`'s \`item\` typed \u2014 the .then() form collapses it to unknown.
+		queryFn: async () => {
+			const page = await ${camelName}Api.list();
+			return page.items;
+		},
 		getKey: (item) => item.id,
 		schema: ${camelName}Schema,
 	}),
@@ -5644,21 +5733,33 @@ function buildStoreIndexFile(ctx) {
   const entities = sortEntities(ctx.entities);
   const hookImports = entities.map((e) => `import { ${e.camelName}Hooks } from '../entities/${e.name}';`).join("\n");
   const collectionImports = entities.map((e) => `import { ${e.camelName}Collection } from '../collections/${e.name}';`).join("\n");
+  const fieldsImports = entities.map((e) => `import { ${e.camelName}Fields } from '../fields/${e.name}';`).join("\n");
   const entityEntries = entities.map((e) => `		${e.plural}: ${e.camelName}Hooks,`).join("\n");
   const collectionEntries = entities.map((e) => `		${e.plural}: ${e.camelName}Collection,`).join("\n");
+  const fieldsEntries = entities.map((e) => `		${e.plural}: ${e.camelName}Fields,`).join("\n");
   const body = `import { createStore } from '@pattern-stack/frontend-patterns';
 
 ${hookImports}
 
 ${collectionImports}
 
+${fieldsImports}
+
+import { createLookups } from './lookups';
+
 /**
  * The application store \u2014 unified access to every entity.
  *
- * Entities and collections are keyed by their plural name:
+ * Entities, collections, and field metadata are keyed by their plural name:
+ *   store.${entities[0]?.plural ?? "things"}.useData()   // useList + fields[plural] meta + hydrated lookups
  *   store.${entities[0]?.plural ?? "things"}.useList()
  *   store.resolve.<entity>(id)
- *   store.lookups.build()
+ *   store.lookups.current
+ *
+ * \`fields\` carries the generated FieldMeta (\`fields/<entity>\` \u2192 \`<camel>Fields\`);
+ * \`lookups\` is the generated lookups engine (\`{ hydrate(): Promise<EntityLookups>;
+ * current }\`) \u2014 hydrated once so off-page FK resolution stays correct under
+ * pagination-by-default. Both bind \`store.<entity>.useData()\`.
  */
 export const store = createStore({
 	entities: {
@@ -5667,6 +5768,10 @@ ${entityEntries}
 	collections: {
 ${collectionEntries}
 	},
+	fields: {
+${fieldsEntries}
+	},
+	lookups: createLookups(),
 });
 
 /** Store type for the \`useStore\` hook. */
@@ -5677,6 +5782,7 @@ export type AppStore = typeof store;
 function buildResolversFile(ctx) {
   const entities = sortEntities(ctx.entities);
   const collectionImports = entities.map((e) => `import { ${e.camelName}Collection } from '../collections/${e.name}';`).join("\n");
+  const apiImports = entities.map((e) => `import { ${e.camelName}Api } from '../api/${e.name}';`).join("\n");
   const typeImports = entities.map((e) => `import type { ${e.className} } from '${ctx.config.dbEntitiesImport}/${e.name}';`).join("\n");
   const resolverIface = entities.map(
     (e) => `	${e.camelName}: (id: string | null | undefined) => ${e.className} | undefined;`
@@ -5684,9 +5790,16 @@ function buildResolversFile(ctx) {
   const resolverImpls = entities.map(
     (e) => `		${e.camelName}: (id) => {
 			if (!id) return undefined;
-			return ${e.camelName}Collection.state.get(id) as ${e.className} | undefined;
+			return (${e.camelName}Collection.state.get(id) ??
+				hydrationCache.${e.camelName}.get(id)) as ${e.className} | undefined;
 		},`
   ).join("\n");
+  const hydrationCacheFields = entities.map((e) => `	${e.camelName}: new Map<string, ${e.className}>(),`).join("\n");
+  const hydrationCalls = entities.map(
+    (e) => `		${e.camelName}Api.listAll().then((rows) => {
+			hydrationCache.${e.camelName} = new Map(rows.map((r) => [r.id as string, r]));
+		}),`
+  ).join("\n");
   const refBlocks = [];
   for (const e of entities) {
     const rels = resolvableRels(e, ctx);
@@ -5721,11 +5834,37 @@ ${hydrateFields}
 ${refBlocks.join("\n\n")}
 ` : "";
   const body = `${collectionImports}
+${apiImports}
 ${typeImports}
 
+/**
+ * Full-fetch hydration cache (LANDMINE 1 escape hatch for pagination-by-default).
+ *
+ * The backing collections hold only the CURRENT PAGE once lists paginate, so an
+ * FK pointing at a row on another page resolves to undefined against collection
+ * state alone. \`hydrateResolverCache()\` fetches the COMPLETE set per entity (via
+ * \`api.listAll()\`, which pages through the envelope) into these id\u2192entity maps;
+ * resolvers fall back to them on a collection-state miss. Call it once on mount.
+ */
+const hydrationCache = {
+${hydrationCacheFields}
+};
+
+/**
+ * Populate the {@link hydrationCache} from the full set of every entity. Await
+ * (or fire-and-forget) once at app start so off-page FK resolution is correct.
+ * Idempotent \u2014 re-running refreshes every cache map.
+ */
+export async function hydrateResolverCache(): Promise<void> {
+	await Promise.all([
+${hydrationCalls}
+	]);
+}
+
 /**
  * FK resolvers \u2014 resolve a foreign-key id to the full entity object via the
- * backing collection's local state (\`O(1)\` \`Map.get\`).
+ * backing collection's local state (\`O(1)\` \`Map.get\`), falling back to the
+ * full-fetch hydration cache for ids not on the current page.
  *
  * Usage:
  *   const ${entities[0]?.camelName ?? "thing"} = resolvers.${entities[0]?.camelName ?? "thing"}(other.${entities[0]?.camelName ?? "thing"}Id);
@@ -5734,7 +5873,7 @@ export interface Resolvers {
 ${resolverIface}
 }
 
-/** Build the resolver table over the generated collections. */
+/** Build the resolver table over the generated collections + hydration cache. */
 export function createResolvers(): Resolvers {
 	return {
 ${resolverImpls}
@@ -5746,6 +5885,7 @@ ${refsSection}`;
 function buildLookupsFile(ctx) {
   const entities = sortEntities(ctx.entities);
   const collectionImports = entities.map((e) => `import { ${e.camelName}Collection } from '../collections/${e.name}';`).join("\n");
+  const apiImports = entities.map((e) => `import { ${e.camelName}Api } from '../api/${e.name}';`).join("\n");
   const typeImports = entities.map((e) => `import type { ${e.className} } from '${ctx.config.dbEntitiesImport}/${e.name}';`).join("\n");
   const lookupIface = entities.map((e) => `	${e.plural}: Map<string, ${e.className}>;`).join("\n");
   const lookupBuild = entities.map(
@@ -5756,7 +5896,12 @@ function buildLookupsFile(ctx) {
 			]),
 		),`
   ).join("\n");
+  const lookupBuildAsyncDecls = entities.map((e) => `		${e.camelName}Api.listAll(),`).join("\n");
+  const lookupBuildAsyncFields = entities.map(
+    (e, i) => `		${e.plural}: new Map(rows[${i}].map((r) => [r.id as string, r as ${e.className}])),`
+  ).join("\n");
   const body = `${collectionImports}
+${apiImports}
 ${typeImports}
 
 /** All entity lookup maps, keyed by plural entity name (id \u2192 entity). */
@@ -5764,14 +5909,33 @@ export interface EntityLookups {
 ${lookupIface}
 }
 
-/** Build fresh lookup maps from current collection state. */
+/** Build fresh lookup maps from current collection state (current page only). */
 export function buildLookups(): EntityLookups {
 	return {
 ${lookupBuild}
 	};
 }
 
-/** Caching lookup factory: \`build()\` (re)computes, \`current\` reads, \`clear()\` resets. */
+/**
+ * Build lookup maps over the COMPLETE set (LANDMINE 1 escape hatch). Pages
+ * through every entity's list via \`api.listAll()\` so off-page rows are present.
+ * Prefer this over {@link buildLookups} whenever a lookup must resolve ids that
+ * may not be on the current page.
+ */
+export async function buildLookupsAsync(): Promise<EntityLookups> {
+	const rows = await Promise.all([
+${lookupBuildAsyncDecls}
+	]);
+	return {
+${lookupBuildAsyncFields}
+	};
+}
+
+/**
+ * Caching lookup factory: \`build()\` (re)computes from collection state,
+ * \`hydrate()\` (re)computes from the full-fetch escape hatch, \`current\` reads,
+ * \`clear()\` resets.
+ */
 export function createLookups() {
 	let cache: EntityLookups | null = null;
 	return {
@@ -5779,6 +5943,10 @@ export function createLookups() {
 			cache = buildLookups();
 			return cache;
 		},
+		hydrate: async (): Promise<EntityLookups> => {
+			cache = await buildLookupsAsync();
+			return cache;
+		},
 		get current(): EntityLookups | null {
 			return cache;
 		},
@@ -5794,8 +5962,8 @@ function buildStoreModuleIndexFile(ctx) {
   const entities = sortEntities(ctx.entities);
   const lines = [
     "export { store, type AppStore } from './index';",
-    "export { createResolvers, type Resolvers } from './resolvers';",
-    "export { buildLookups, createLookups, type EntityLookups } from './lookups';"
+    "export { createResolvers, hydrateResolverCache, type Resolvers } from './resolvers';",
+    "export { buildLookups, buildLookupsAsync, createLookups, type EntityLookups } from './lookups';"
   ];
   const refExports = entities.filter((e) => resolvableRels(e, ctx).length > 0).map(
     (e) => `export { resolve${e.className}Refs, type ${e.className}Refs } from './resolvers';`
@@ -9402,6 +9570,13 @@ var VENDORED_RUNTIME_FILES = [
   // Pipes — ZodValidationPipe is wired on every generated controller
   // @Body() to give runtime Zod validation at the controller boundary.
   { runtime: "pipes/zod-validation.pipe.ts", target: "src/shared/pipes/zod-validation.pipe.ts" },
+  // Pagination-by-default (Page<T> envelope, ListQuerySchema, resolveListQuery,
+  // buildPage, opaque cursor codec) — imported by EVERY generated list
+  // controller/dto/use-case. Vendored to `src/shared/http/page.ts` (alias
+  // `@shared/http/page`), DISTINCT from the consumer's optional `@shared/http/
+  // pagination` search contract so the two never collide. Package mode resolves
+  // the same source via `@pattern-stack/codegen/runtime/http/pagination`.
+  { runtime: "http/pagination.ts", target: "src/shared/http/page.ts" },
   // EAV helpers — referenced by generated services on `eav_value_table` entities
   { runtime: "eav-helpers.ts", target: "src/shared/eav-helpers.ts" },
   // OpenAPI registry (OPENAPI-1/2) — generated modules register Zod DTOs