@dudousxd/nestjs-codegen 0.14.1 → 0.15.0

package/dist/extension/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/extension/index.ts","../../src/extension/types.ts"],"sourcesContent":["export { defineExtension, requestShape } from './types.js';\nexport type {\n  ApiClientLayer,\n  ApiHeaderContribution,\n  ApiModuleDeps,\n  CodegenExtension,\n  EmittedFile,\n  ExtensionContext,\n  LeafModel,\n  RequestModel,\n  RequestShape,\n} from './types.js';\n","import type { Project } from 'ts-morph';\nimport type { ResolvedConfig } from '../config/types.js';\nimport type { RouteDescriptor } from '../discovery/types.js';\n\n/**\n * The published, versioned extension contract for `@dudousxd/nestjs-codegen`.\n *\n * Extensions are **build-time** objects (usually returned by a factory so they can take\n * options) registered explicitly via `forRoot({ extensions: [...] })`. The host runs them\n * around the core discovery → IR → emit pipeline.\n *\n * Hooks split into **multi** (every extension runs; results accumulate or chain) and\n * **single-slot** (at most one extension may claim it — two claimers is a hard error).\n *\n * @remarks Semver 0.x — the shape may change until 1.0. Out-of-repo extensions should pin\n * a compatible `@dudousxd/nestjs-codegen` peer range.\n */\nexport interface CodegenExtension {\n  /** Unique id. Used in conflict/collision errors and for deterministic ordering. */\n  name: string;\n\n  // ── multi hooks (every extension runs) ────────────────────────────────────\n\n  /**\n   * Mutate/augment the route IR before emit. Runs in registration order, chained\n   * (each extension sees the previous one's output). Return the new array, or mutate\n   * in place and return void. Example: the filter extension attaches `filterFields` to\n   * matching routes here.\n   */\n  transformRoutes?(\n    routes: RouteDescriptor[],\n    ctx: ExtensionContext,\n  ): RouteDescriptor[] | undefined | Promise<RouteDescriptor[] | undefined>;\n\n  /**\n   * Contribute extra output files (additive). Paths are relative to `outDir`; a path\n   * claimed by two extensions is a hard error. Example: the Inertia extension does its\n   * own page discovery via `ctx.project()` and emits `pages.d.ts` + `components.json`.\n   */\n  emitFiles?(ctx: ExtensionContext): EmittedFile[] | Promise<EmittedFile[]>;\n\n  /**\n   * Contribute top-level code to `api.ts` (imports + statements). Runs in registration\n   * order; imports are deduped by the host. Example: the Inertia extension adds\n   * `import { router } from '@inertiajs/react'` and the `navigate()` helper.\n   */\n  apiHeader?(ctx: ExtensionContext): ApiHeaderContribution | undefined;\n\n  /**\n   * Add named members to a **handle** leaf. Only runs when a client layer is active\n   * (i.e. the leaf is a handle, not a bare callable). Member-name collisions across\n   * extensions are a hard error. Example: the filter extension adds `filterQuery` to\n   * leaves whose route carries `filterFields`.\n   */\n  apiMembers?(leaf: LeafModel, ctx: ExtensionContext): Record<string, string> | undefined;\n\n  // ── single-slot hooks (at most one extension) ─────────────────────────────\n\n  /**\n   * Claims **what** a leaf returns and **how** it issues its request. At most one extension\n   * may claim it. When unset, a leaf is a bare awaitable callable backed by the neutral\n   * fetcher. Example: the TanStack extension wraps each leaf into a handle exposing\n   * `{ fetch, queryKey, queryOptions | mutationOptions }`, composing with the fetcher\n   * request the host passes in.\n   */\n  apiClientLayer?: ApiClientLayer;\n}\n\n/** Shared, read-only context handed to every extension hook. */\nexport interface ExtensionContext {\n  cwd: string;\n  outDir: string;\n  routes: readonly RouteDescriptor[];\n  config: ResolvedConfig;\n  /** Lazily-created shared ts-morph Project for AST work (pages, custom decorators). */\n  project(): Project;\n}\n\n/** A file contributed by an extension's `emitFiles` hook. */\nexport interface EmittedFile {\n  /** Path relative to `outDir`. A collision across extensions throws. */\n  path: string;\n  contents: string;\n}\n\n/** Top-level `api.ts` contributions from an extension's `apiHeader` hook. */\nexport interface ApiHeaderContribution {\n  /** Raw import lines (e.g. `import { router } from '@inertiajs/react';`), deduped by the host. */\n  imports?: string[];\n  /** Top-level statements appended after the api factory (e.g. the `navigate()` helper). */\n  statements?: string[];\n}\n\n/**\n * The neutral, per-endpoint request model the host builds for each leaf before any\n * transport/layer runs. Extensions read this to render their output.\n */\nexport interface RequestModel {\n  /** Dot-path route name, e.g. `users.show`. */\n  routeName: string;\n  method: 'get' | 'post' | 'put' | 'patch' | 'delete';\n  isGet: boolean;\n  /** True for reads: a GET, a filter-search route (has `filterFields`), or an\n   *  `@AsQuery()`-marked route — even when the method is POST. Client layers\n   *  use this (not `isGet`) to decide query vs mutation helpers. */\n  isQuery: boolean;\n  hasParams: boolean;\n  hasBody: boolean;\n  /** Type of the leaf's `input` arg, e.g. `{ params: ...; query?: ... }` or `Record<string, never>`. */\n  inputType: string;\n  /** URL expression, e.g. `route('users.show', input?.params) || '/api/users/:id'`. */\n  urlExpr: string;\n  /** Request-options expression, e.g. `{ query: ... }` or `{ body: input?.body }`. */\n  optsExpr: string;\n  /** Response type access, e.g. `ApiRouter['users']['show']['response']`. */\n  responseType: string;\n  /** Stable query-key expression, e.g. `[\"users.show\", input] as const`. */\n  queryKeyExpr: string;\n}\n\n/**\n * Per-leaf model passed through the api.ts pipeline: layer → member contributors → render.\n * `requestExpr` is the host's neutral fetcher request; `members`, when present, flips the\n * leaf from a bare callable to a handle.\n */\nexport interface LeafModel {\n  route: RouteDescriptor;\n  request: RequestModel;\n  /** The expression that issues the request (the host's neutral fetcher call). */\n  requestExpr: string;\n  /** When present, the leaf renders as a handle exposing these members (ordered). */\n  members?: Record<string, string>;\n}\n\n/**\n * Top-level `api.ts` imports a client layer depends on. A function of the context so it can\n * be route-aware (e.g. only import `mutationOptions` when a mutation exists). Imports are\n * deduped by the host across all extensions.\n */\nexport interface ApiModuleDeps {\n  /** Raw import lines (e.g. `import { queryOptions as _q } from '@tanstack/react-query';`). */\n  imports?(ctx: ExtensionContext): string[];\n}\n\n/** Single-slot: decides what a leaf returns (the handle members). */\nexport interface ApiClientLayer extends ApiModuleDeps {\n  name: string;\n  /**\n   * Given the request expression (from the transport) and the leaf, return the handle's\n   * members as an ordered `name → value` map (value is the expression after `name: `).\n   * Returning members flips the leaf from a bare callable to a handle.\n   */\n  buildMembers(requestExpr: string, leaf: LeafModel, ctx: ExtensionContext): Record<string, string>;\n}\n\n/**\n * The four request-shape flags derived from a route's method + contract. Computed in ONE\n * place ({@link requestShape}) and read by both the host emitter and client-layer\n * extensions, so the \"filter-search POST counts as a read\" rule is encoded exactly once.\n */\nexport interface RequestShape {\n  /** The route is a `GET`. */\n  isGet: boolean;\n  /** True for reads: a GET, or a filter-search route (carries `filterFields`) even when POST.\n   *  Client layers use this (not `isGet`) to decide query vs mutation helpers. */\n  isQuery: boolean;\n  /** The route carries a body contract (a mutation payload). */\n  hasBody: boolean;\n  /** The route can take a query string — always for GET; a mutation may too (query + body). */\n  hasQuery: boolean;\n}\n\n/**\n * Compute the {@link RequestShape} flags for a route from its method and contract. This is\n * the SINGLE source of truth for these flags — `buildRequestModel`, the TanStack layer's\n * `imports()`, and any other reader must call this rather than re-deriving. The\n * \"filter-search POST counts as a read\" rule lives here and nowhere else.\n */\nexport function requestShape(route: RouteDescriptor): RequestShape {\n  const cs = route.contract?.contractSource;\n  const isGet = route.method.toUpperCase() === 'GET';\n  // A route counts as a read when it's a GET, a filter-search POST (carries\n  // `filterFields`), or explicitly opted in via `@AsQuery()` (`cs.asQuery`) —\n  // e.g. a POST whose semantics are a read (a query-shaped payload).\n  const isQuery = isGet || !!cs?.filterFields?.length || !!cs?.asQuery;\n  // `multipart` implies a body even when the route has no `@Body()` at all (a bare\n  // `@UploadedFile()` route): the type block intersects `multipartBody` into the body\n  // type, so the runtime leaf must accept and forward it too — otherwise the ApiRouter\n  // type promises `body: { file: File | Blob }` while the generated call silently\n  // drops the file.\n  const hasBody = !!cs?.bodyRef || (cs?.body != null && cs.body !== 'never') || !!cs?.multipart;\n  const hasQuery = isGet || !!cs?.queryRef || (cs?.query != null && cs.query !== 'never');\n  return { isGet, isQuery, hasBody, hasQuery };\n}\n\n/** Identity helper for authoring extensions with full type inference. */\nexport function defineExtension(ext: CodegenExtension): CodegenExtension {\n  return ext;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACkLO,SAAS,aAAa,OAAsC;AACjE,QAAM,KAAK,MAAM,UAAU;AAC3B,QAAM,QAAQ,MAAM,OAAO,YAAY,MAAM;AAI7C,QAAM,UAAU,SAAS,CAAC,CAAC,IAAI,cAAc,UAAU,CAAC,CAAC,IAAI;AAM7D,QAAM,UAAU,CAAC,CAAC,IAAI,WAAY,IAAI,QAAQ,QAAQ,GAAG,SAAS,WAAY,CAAC,CAAC,IAAI;AACpF,QAAM,WAAW,SAAS,CAAC,CAAC,IAAI,YAAa,IAAI,SAAS,QAAQ,GAAG,UAAU;AAC/E,SAAO,EAAE,OAAO,SAAS,SAAS,SAAS;AAC7C;AAGO,SAAS,gBAAgB,KAAyC;AACvE,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/extension/index.ts","../../src/extension/types.ts"],"sourcesContent":["export { defineExtension, requestShape } from './types.js';\nexport type {\n  ApiClientLayer,\n  ApiHeaderContribution,\n  ApiModuleDeps,\n  CodegenExtension,\n  EmittedFile,\n  ExtensionContext,\n  LeafModel,\n  RequestModel,\n  RequestShape,\n} from './types.js';\n","import type { Project } from 'ts-morph';\nimport type { ResolvedConfig } from '../config/types.js';\nimport type { RouteDescriptor } from '../discovery/types.js';\n\n/**\n * The published, versioned extension contract for `@dudousxd/nestjs-codegen`.\n *\n * Extensions are **build-time** objects (usually returned by a factory so they can take\n * options) registered explicitly via `forRoot({ extensions: [...] })`. The host runs them\n * around the core discovery → IR → emit pipeline.\n *\n * Hooks split into **multi** (every extension runs; results accumulate or chain) and\n * **single-slot** (at most one extension may claim it — two claimers is a hard error).\n *\n * @remarks Semver 0.x — the shape may change until 1.0. Out-of-repo extensions should pin\n * a compatible `@dudousxd/nestjs-codegen` peer range.\n */\nexport interface CodegenExtension {\n  /** Unique id. Used in conflict/collision errors and for deterministic ordering. */\n  name: string;\n\n  // ── multi hooks (every extension runs) ────────────────────────────────────\n\n  /**\n   * Mutate/augment the route IR before emit. Runs in registration order, chained\n   * (each extension sees the previous one's output). Return the new array, or mutate\n   * in place and return void. Example: the filter extension attaches `filterFields` to\n   * matching routes here.\n   */\n  transformRoutes?(\n    routes: RouteDescriptor[],\n    ctx: ExtensionContext,\n  ): RouteDescriptor[] | undefined | Promise<RouteDescriptor[] | undefined>;\n\n  /**\n   * Contribute extra output files (additive). Paths are relative to `outDir`; a path\n   * claimed by two extensions is a hard error. Example: the Inertia extension does its\n   * own page discovery via `ctx.project()` and emits `pages.d.ts` + `components.json`.\n   */\n  emitFiles?(ctx: ExtensionContext): EmittedFile[] | Promise<EmittedFile[]>;\n\n  /**\n   * Contribute top-level code to `api.ts` (imports + statements). Runs in registration\n   * order; imports are deduped by the host. Example: the Inertia extension adds\n   * `import { router } from '@inertiajs/react'` and the `navigate()` helper.\n   */\n  apiHeader?(ctx: ExtensionContext): ApiHeaderContribution | undefined;\n\n  /**\n   * Add named members to a **handle** leaf. Only runs when a client layer is active\n   * (i.e. the leaf is a handle, not a bare callable). Member-name collisions across\n   * extensions are a hard error. Example: the filter extension adds `filterQuery` to\n   * leaves whose route carries `filterFields`.\n   */\n  apiMembers?(leaf: LeafModel, ctx: ExtensionContext): Record<string, string> | undefined;\n\n  // ── single-slot hooks (at most one extension) ─────────────────────────────\n\n  /**\n   * Claims **what** a leaf returns and **how** it issues its request. At most one extension\n   * may claim it. When unset, a leaf is a bare awaitable callable backed by the neutral\n   * fetcher. Example: the TanStack extension wraps each leaf into a handle exposing\n   * `{ fetch, queryKey, queryOptions | mutationOptions }`, composing with the fetcher\n   * request the host passes in.\n   */\n  apiClientLayer?: ApiClientLayer;\n}\n\n/** Shared, read-only context handed to every extension hook. */\nexport interface ExtensionContext {\n  cwd: string;\n  outDir: string;\n  routes: readonly RouteDescriptor[];\n  config: ResolvedConfig;\n  /** Lazily-created shared ts-morph Project for AST work (pages, custom decorators). */\n  project(): Project;\n}\n\n/** A file contributed by an extension's `emitFiles` hook. */\nexport interface EmittedFile {\n  /** Path relative to `outDir`. A collision across extensions throws. */\n  path: string;\n  contents: string;\n}\n\n/** Top-level `api.ts` contributions from an extension's `apiHeader` hook. */\nexport interface ApiHeaderContribution {\n  /** Raw import lines (e.g. `import { router } from '@inertiajs/react';`), deduped by the host. */\n  imports?: string[];\n  /** Top-level statements appended after the api factory (e.g. the `navigate()` helper). */\n  statements?: string[];\n}\n\n/**\n * The neutral, per-endpoint request model the host builds for each leaf before any\n * transport/layer runs. Extensions read this to render their output.\n */\nexport interface RequestModel {\n  /** Dot-path route name, e.g. `users.show`. */\n  routeName: string;\n  method: 'get' | 'post' | 'put' | 'patch' | 'delete';\n  isGet: boolean;\n  /** True for reads: a GET, a filter-search route (has `filterFields`), or an\n   *  `@AsQuery()`-marked route — even when the method is POST. Client layers\n   *  use this (not `isGet`) to decide query vs mutation helpers. */\n  isQuery: boolean;\n  hasParams: boolean;\n  hasBody: boolean;\n  /** Type of the leaf's `input` arg, e.g. `{ params: ...; query?: ... }` or `Record<string, never>`. */\n  inputType: string;\n  /** URL expression, e.g. `route('users.show', input?.params) || '/api/users/:id'`. */\n  urlExpr: string;\n  /** Request-options expression, e.g. `{ query: ... }` or `{ body: input?.body }`. */\n  optsExpr: string;\n  /** Response type access, e.g. `ApiRouter['users']['show']['response']`. */\n  responseType: string;\n  /** Stable query-key expression, e.g. `[\"users.show\", input] as const`. */\n  queryKeyExpr: string;\n  /**\n   * Runtime filter-fields literal-array expression, e.g. `[\"id\", \"name\"] as const`,\n   * or `undefined` for a route with no filter. Derived from the same discovered\n   * field list as the type-level `filterFields` union, so the emitted value stays\n   * in lockstep with the type.\n   */\n  filterFieldsExpr?: string | undefined;\n}\n\n/**\n * Per-leaf model passed through the api.ts pipeline: layer → member contributors → render.\n * `requestExpr` is the host's neutral fetcher request; `members`, when present, flips the\n * leaf from a bare callable to a handle.\n */\nexport interface LeafModel {\n  route: RouteDescriptor;\n  request: RequestModel;\n  /** The expression that issues the request (the host's neutral fetcher call). */\n  requestExpr: string;\n  /** When present, the leaf renders as a handle exposing these members (ordered). */\n  members?: Record<string, string>;\n}\n\n/**\n * Top-level `api.ts` imports a client layer depends on. A function of the context so it can\n * be route-aware (e.g. only import `mutationOptions` when a mutation exists). Imports are\n * deduped by the host across all extensions.\n */\nexport interface ApiModuleDeps {\n  /** Raw import lines (e.g. `import { queryOptions as _q } from '@tanstack/react-query';`). */\n  imports?(ctx: ExtensionContext): string[];\n}\n\n/** Single-slot: decides what a leaf returns (the handle members). */\nexport interface ApiClientLayer extends ApiModuleDeps {\n  name: string;\n  /**\n   * Given the request expression (from the transport) and the leaf, return the handle's\n   * members as an ordered `name → value` map (value is the expression after `name: `).\n   * Returning members flips the leaf from a bare callable to a handle.\n   */\n  buildMembers(requestExpr: string, leaf: LeafModel, ctx: ExtensionContext): Record<string, string>;\n}\n\n/**\n * The four request-shape flags derived from a route's method + contract. Computed in ONE\n * place ({@link requestShape}) and read by both the host emitter and client-layer\n * extensions, so the \"filter-search POST counts as a read\" rule is encoded exactly once.\n */\nexport interface RequestShape {\n  /** The route is a `GET`. */\n  isGet: boolean;\n  /** True for reads: a GET, or a filter-search route (carries `filterFields`) even when POST.\n   *  Client layers use this (not `isGet`) to decide query vs mutation helpers. */\n  isQuery: boolean;\n  /** The route carries a body contract (a mutation payload). */\n  hasBody: boolean;\n  /** The route can take a query string — always for GET; a mutation may too (query + body). */\n  hasQuery: boolean;\n}\n\n/**\n * Compute the {@link RequestShape} flags for a route from its method and contract. This is\n * the SINGLE source of truth for these flags — `buildRequestModel`, the TanStack layer's\n * `imports()`, and any other reader must call this rather than re-deriving. The\n * \"filter-search POST counts as a read\" rule lives here and nowhere else.\n */\nexport function requestShape(route: RouteDescriptor): RequestShape {\n  const cs = route.contract?.contractSource;\n  const isGet = route.method.toUpperCase() === 'GET';\n  // A route counts as a read when it's a GET, a filter-search POST (carries\n  // `filterFields`), or explicitly opted in via `@AsQuery()` (`cs.asQuery`) —\n  // e.g. a POST whose semantics are a read (a query-shaped payload).\n  const isQuery = isGet || !!cs?.filterFields?.length || !!cs?.asQuery;\n  // `multipart` implies a body even when the route has no `@Body()` at all (a bare\n  // `@UploadedFile()` route): the type block intersects `multipartBody` into the body\n  // type, so the runtime leaf must accept and forward it too — otherwise the ApiRouter\n  // type promises `body: { file: File | Blob }` while the generated call silently\n  // drops the file.\n  const hasBody = !!cs?.bodyRef || (cs?.body != null && cs.body !== 'never') || !!cs?.multipart;\n  const hasQuery = isGet || !!cs?.queryRef || (cs?.query != null && cs.query !== 'never');\n  return { isGet, isQuery, hasBody, hasQuery };\n}\n\n/** Identity helper for authoring extensions with full type inference. */\nexport function defineExtension(ext: CodegenExtension): CodegenExtension {\n  return ext;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACyLO,SAAS,aAAa,OAAsC;AACjE,QAAM,KAAK,MAAM,UAAU;AAC3B,QAAM,QAAQ,MAAM,OAAO,YAAY,MAAM;AAI7C,QAAM,UAAU,SAAS,CAAC,CAAC,IAAI,cAAc,UAAU,CAAC,CAAC,IAAI;AAM7D,QAAM,UAAU,CAAC,CAAC,IAAI,WAAY,IAAI,QAAQ,QAAQ,GAAG,SAAS,WAAY,CAAC,CAAC,IAAI;AACpF,QAAM,WAAW,SAAS,CAAC,CAAC,IAAI,YAAa,IAAI,SAAS,QAAQ,GAAG,UAAU;AAC/E,SAAO,EAAE,OAAO,SAAS,SAAS,SAAS;AAC7C;AAGO,SAAS,gBAAgB,KAAyC;AACvE,SAAO;AACT;","names":[]}

package/dist/extension/index.d.cts

@@ -1,2 +1,2 @@
-export { m as ApiClientLayer, n as ApiHeaderContribution, o as ApiModuleDeps, C as CodegenExtension, p as EmittedFile, E as ExtensionContext, L as LeafModel, q as RequestModel, s as RequestShape, t as defineExtension, u as requestShape } from '../index-DT8SgPxp.cjs';
+export { m as ApiClientLayer, n as ApiHeaderContribution, o as ApiModuleDeps, C as CodegenExtension, p as EmittedFile, E as ExtensionContext, L as LeafModel, q as RequestModel, s as RequestShape, t as defineExtension, u as requestShape } from '../index-CjIDPMsV.cjs';
 import 'ts-morph';

package/dist/extension/index.d.ts

@@ -1,2 +1,2 @@
-export { m as ApiClientLayer, n as ApiHeaderContribution, o as ApiModuleDeps, C as CodegenExtension, p as EmittedFile, E as ExtensionContext, L as LeafModel, q as RequestModel, s as RequestShape, t as defineExtension, u as requestShape } from '../index-DT8SgPxp.js';
+export { m as ApiClientLayer, n as ApiHeaderContribution, o as ApiModuleDeps, C as CodegenExtension, p as EmittedFile, E as ExtensionContext, L as LeafModel, q as RequestModel, s as RequestShape, t as defineExtension, u as requestShape } from '../index-CjIDPMsV.js';
 import 'ts-morph';

package/dist/extension/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/extension/types.ts"],"sourcesContent":["import type { Project } from 'ts-morph';\nimport type { ResolvedConfig } from '../config/types.js';\nimport type { RouteDescriptor } from '../discovery/types.js';\n\n/**\n * The published, versioned extension contract for `@dudousxd/nestjs-codegen`.\n *\n * Extensions are **build-time** objects (usually returned by a factory so they can take\n * options) registered explicitly via `forRoot({ extensions: [...] })`. The host runs them\n * around the core discovery → IR → emit pipeline.\n *\n * Hooks split into **multi** (every extension runs; results accumulate or chain) and\n * **single-slot** (at most one extension may claim it — two claimers is a hard error).\n *\n * @remarks Semver 0.x — the shape may change until 1.0. Out-of-repo extensions should pin\n * a compatible `@dudousxd/nestjs-codegen` peer range.\n */\nexport interface CodegenExtension {\n  /** Unique id. Used in conflict/collision errors and for deterministic ordering. */\n  name: string;\n\n  // ── multi hooks (every extension runs) ────────────────────────────────────\n\n  /**\n   * Mutate/augment the route IR before emit. Runs in registration order, chained\n   * (each extension sees the previous one's output). Return the new array, or mutate\n   * in place and return void. Example: the filter extension attaches `filterFields` to\n   * matching routes here.\n   */\n  transformRoutes?(\n    routes: RouteDescriptor[],\n    ctx: ExtensionContext,\n  ): RouteDescriptor[] | undefined | Promise<RouteDescriptor[] | undefined>;\n\n  /**\n   * Contribute extra output files (additive). Paths are relative to `outDir`; a path\n   * claimed by two extensions is a hard error. Example: the Inertia extension does its\n   * own page discovery via `ctx.project()` and emits `pages.d.ts` + `components.json`.\n   */\n  emitFiles?(ctx: ExtensionContext): EmittedFile[] | Promise<EmittedFile[]>;\n\n  /**\n   * Contribute top-level code to `api.ts` (imports + statements). Runs in registration\n   * order; imports are deduped by the host. Example: the Inertia extension adds\n   * `import { router } from '@inertiajs/react'` and the `navigate()` helper.\n   */\n  apiHeader?(ctx: ExtensionContext): ApiHeaderContribution | undefined;\n\n  /**\n   * Add named members to a **handle** leaf. Only runs when a client layer is active\n   * (i.e. the leaf is a handle, not a bare callable). Member-name collisions across\n   * extensions are a hard error. Example: the filter extension adds `filterQuery` to\n   * leaves whose route carries `filterFields`.\n   */\n  apiMembers?(leaf: LeafModel, ctx: ExtensionContext): Record<string, string> | undefined;\n\n  // ── single-slot hooks (at most one extension) ─────────────────────────────\n\n  /**\n   * Claims **what** a leaf returns and **how** it issues its request. At most one extension\n   * may claim it. When unset, a leaf is a bare awaitable callable backed by the neutral\n   * fetcher. Example: the TanStack extension wraps each leaf into a handle exposing\n   * `{ fetch, queryKey, queryOptions | mutationOptions }`, composing with the fetcher\n   * request the host passes in.\n   */\n  apiClientLayer?: ApiClientLayer;\n}\n\n/** Shared, read-only context handed to every extension hook. */\nexport interface ExtensionContext {\n  cwd: string;\n  outDir: string;\n  routes: readonly RouteDescriptor[];\n  config: ResolvedConfig;\n  /** Lazily-created shared ts-morph Project for AST work (pages, custom decorators). */\n  project(): Project;\n}\n\n/** A file contributed by an extension's `emitFiles` hook. */\nexport interface EmittedFile {\n  /** Path relative to `outDir`. A collision across extensions throws. */\n  path: string;\n  contents: string;\n}\n\n/** Top-level `api.ts` contributions from an extension's `apiHeader` hook. */\nexport interface ApiHeaderContribution {\n  /** Raw import lines (e.g. `import { router } from '@inertiajs/react';`), deduped by the host. */\n  imports?: string[];\n  /** Top-level statements appended after the api factory (e.g. the `navigate()` helper). */\n  statements?: string[];\n}\n\n/**\n * The neutral, per-endpoint request model the host builds for each leaf before any\n * transport/layer runs. Extensions read this to render their output.\n */\nexport interface RequestModel {\n  /** Dot-path route name, e.g. `users.show`. */\n  routeName: string;\n  method: 'get' | 'post' | 'put' | 'patch' | 'delete';\n  isGet: boolean;\n  /** True for reads: a GET, a filter-search route (has `filterFields`), or an\n   *  `@AsQuery()`-marked route — even when the method is POST. Client layers\n   *  use this (not `isGet`) to decide query vs mutation helpers. */\n  isQuery: boolean;\n  hasParams: boolean;\n  hasBody: boolean;\n  /** Type of the leaf's `input` arg, e.g. `{ params: ...; query?: ... }` or `Record<string, never>`. */\n  inputType: string;\n  /** URL expression, e.g. `route('users.show', input?.params) || '/api/users/:id'`. */\n  urlExpr: string;\n  /** Request-options expression, e.g. `{ query: ... }` or `{ body: input?.body }`. */\n  optsExpr: string;\n  /** Response type access, e.g. `ApiRouter['users']['show']['response']`. */\n  responseType: string;\n  /** Stable query-key expression, e.g. `[\"users.show\", input] as const`. */\n  queryKeyExpr: string;\n}\n\n/**\n * Per-leaf model passed through the api.ts pipeline: layer → member contributors → render.\n * `requestExpr` is the host's neutral fetcher request; `members`, when present, flips the\n * leaf from a bare callable to a handle.\n */\nexport interface LeafModel {\n  route: RouteDescriptor;\n  request: RequestModel;\n  /** The expression that issues the request (the host's neutral fetcher call). */\n  requestExpr: string;\n  /** When present, the leaf renders as a handle exposing these members (ordered). */\n  members?: Record<string, string>;\n}\n\n/**\n * Top-level `api.ts` imports a client layer depends on. A function of the context so it can\n * be route-aware (e.g. only import `mutationOptions` when a mutation exists). Imports are\n * deduped by the host across all extensions.\n */\nexport interface ApiModuleDeps {\n  /** Raw import lines (e.g. `import { queryOptions as _q } from '@tanstack/react-query';`). */\n  imports?(ctx: ExtensionContext): string[];\n}\n\n/** Single-slot: decides what a leaf returns (the handle members). */\nexport interface ApiClientLayer extends ApiModuleDeps {\n  name: string;\n  /**\n   * Given the request expression (from the transport) and the leaf, return the handle's\n   * members as an ordered `name → value` map (value is the expression after `name: `).\n   * Returning members flips the leaf from a bare callable to a handle.\n   */\n  buildMembers(requestExpr: string, leaf: LeafModel, ctx: ExtensionContext): Record<string, string>;\n}\n\n/**\n * The four request-shape flags derived from a route's method + contract. Computed in ONE\n * place ({@link requestShape}) and read by both the host emitter and client-layer\n * extensions, so the \"filter-search POST counts as a read\" rule is encoded exactly once.\n */\nexport interface RequestShape {\n  /** The route is a `GET`. */\n  isGet: boolean;\n  /** True for reads: a GET, or a filter-search route (carries `filterFields`) even when POST.\n   *  Client layers use this (not `isGet`) to decide query vs mutation helpers. */\n  isQuery: boolean;\n  /** The route carries a body contract (a mutation payload). */\n  hasBody: boolean;\n  /** The route can take a query string — always for GET; a mutation may too (query + body). */\n  hasQuery: boolean;\n}\n\n/**\n * Compute the {@link RequestShape} flags for a route from its method and contract. This is\n * the SINGLE source of truth for these flags — `buildRequestModel`, the TanStack layer's\n * `imports()`, and any other reader must call this rather than re-deriving. The\n * \"filter-search POST counts as a read\" rule lives here and nowhere else.\n */\nexport function requestShape(route: RouteDescriptor): RequestShape {\n  const cs = route.contract?.contractSource;\n  const isGet = route.method.toUpperCase() === 'GET';\n  // A route counts as a read when it's a GET, a filter-search POST (carries\n  // `filterFields`), or explicitly opted in via `@AsQuery()` (`cs.asQuery`) —\n  // e.g. a POST whose semantics are a read (a query-shaped payload).\n  const isQuery = isGet || !!cs?.filterFields?.length || !!cs?.asQuery;\n  // `multipart` implies a body even when the route has no `@Body()` at all (a bare\n  // `@UploadedFile()` route): the type block intersects `multipartBody` into the body\n  // type, so the runtime leaf must accept and forward it too — otherwise the ApiRouter\n  // type promises `body: { file: File | Blob }` while the generated call silently\n  // drops the file.\n  const hasBody = !!cs?.bodyRef || (cs?.body != null && cs.body !== 'never') || !!cs?.multipart;\n  const hasQuery = isGet || !!cs?.queryRef || (cs?.query != null && cs.query !== 'never');\n  return { isGet, isQuery, hasBody, hasQuery };\n}\n\n/** Identity helper for authoring extensions with full type inference. */\nexport function defineExtension(ext: CodegenExtension): CodegenExtension {\n  return ext;\n}\n"],"mappings":";AAkLO,SAAS,aAAa,OAAsC;AACjE,QAAM,KAAK,MAAM,UAAU;AAC3B,QAAM,QAAQ,MAAM,OAAO,YAAY,MAAM;AAI7C,QAAM,UAAU,SAAS,CAAC,CAAC,IAAI,cAAc,UAAU,CAAC,CAAC,IAAI;AAM7D,QAAM,UAAU,CAAC,CAAC,IAAI,WAAY,IAAI,QAAQ,QAAQ,GAAG,SAAS,WAAY,CAAC,CAAC,IAAI;AACpF,QAAM,WAAW,SAAS,CAAC,CAAC,IAAI,YAAa,IAAI,SAAS,QAAQ,GAAG,UAAU;AAC/E,SAAO,EAAE,OAAO,SAAS,SAAS,SAAS;AAC7C;AAGO,SAAS,gBAAgB,KAAyC;AACvE,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/extension/types.ts"],"sourcesContent":["import type { Project } from 'ts-morph';\nimport type { ResolvedConfig } from '../config/types.js';\nimport type { RouteDescriptor } from '../discovery/types.js';\n\n/**\n * The published, versioned extension contract for `@dudousxd/nestjs-codegen`.\n *\n * Extensions are **build-time** objects (usually returned by a factory so they can take\n * options) registered explicitly via `forRoot({ extensions: [...] })`. The host runs them\n * around the core discovery → IR → emit pipeline.\n *\n * Hooks split into **multi** (every extension runs; results accumulate or chain) and\n * **single-slot** (at most one extension may claim it — two claimers is a hard error).\n *\n * @remarks Semver 0.x — the shape may change until 1.0. Out-of-repo extensions should pin\n * a compatible `@dudousxd/nestjs-codegen` peer range.\n */\nexport interface CodegenExtension {\n  /** Unique id. Used in conflict/collision errors and for deterministic ordering. */\n  name: string;\n\n  // ── multi hooks (every extension runs) ────────────────────────────────────\n\n  /**\n   * Mutate/augment the route IR before emit. Runs in registration order, chained\n   * (each extension sees the previous one's output). Return the new array, or mutate\n   * in place and return void. Example: the filter extension attaches `filterFields` to\n   * matching routes here.\n   */\n  transformRoutes?(\n    routes: RouteDescriptor[],\n    ctx: ExtensionContext,\n  ): RouteDescriptor[] | undefined | Promise<RouteDescriptor[] | undefined>;\n\n  /**\n   * Contribute extra output files (additive). Paths are relative to `outDir`; a path\n   * claimed by two extensions is a hard error. Example: the Inertia extension does its\n   * own page discovery via `ctx.project()` and emits `pages.d.ts` + `components.json`.\n   */\n  emitFiles?(ctx: ExtensionContext): EmittedFile[] | Promise<EmittedFile[]>;\n\n  /**\n   * Contribute top-level code to `api.ts` (imports + statements). Runs in registration\n   * order; imports are deduped by the host. Example: the Inertia extension adds\n   * `import { router } from '@inertiajs/react'` and the `navigate()` helper.\n   */\n  apiHeader?(ctx: ExtensionContext): ApiHeaderContribution | undefined;\n\n  /**\n   * Add named members to a **handle** leaf. Only runs when a client layer is active\n   * (i.e. the leaf is a handle, not a bare callable). Member-name collisions across\n   * extensions are a hard error. Example: the filter extension adds `filterQuery` to\n   * leaves whose route carries `filterFields`.\n   */\n  apiMembers?(leaf: LeafModel, ctx: ExtensionContext): Record<string, string> | undefined;\n\n  // ── single-slot hooks (at most one extension) ─────────────────────────────\n\n  /**\n   * Claims **what** a leaf returns and **how** it issues its request. At most one extension\n   * may claim it. When unset, a leaf is a bare awaitable callable backed by the neutral\n   * fetcher. Example: the TanStack extension wraps each leaf into a handle exposing\n   * `{ fetch, queryKey, queryOptions | mutationOptions }`, composing with the fetcher\n   * request the host passes in.\n   */\n  apiClientLayer?: ApiClientLayer;\n}\n\n/** Shared, read-only context handed to every extension hook. */\nexport interface ExtensionContext {\n  cwd: string;\n  outDir: string;\n  routes: readonly RouteDescriptor[];\n  config: ResolvedConfig;\n  /** Lazily-created shared ts-morph Project for AST work (pages, custom decorators). */\n  project(): Project;\n}\n\n/** A file contributed by an extension's `emitFiles` hook. */\nexport interface EmittedFile {\n  /** Path relative to `outDir`. A collision across extensions throws. */\n  path: string;\n  contents: string;\n}\n\n/** Top-level `api.ts` contributions from an extension's `apiHeader` hook. */\nexport interface ApiHeaderContribution {\n  /** Raw import lines (e.g. `import { router } from '@inertiajs/react';`), deduped by the host. */\n  imports?: string[];\n  /** Top-level statements appended after the api factory (e.g. the `navigate()` helper). */\n  statements?: string[];\n}\n\n/**\n * The neutral, per-endpoint request model the host builds for each leaf before any\n * transport/layer runs. Extensions read this to render their output.\n */\nexport interface RequestModel {\n  /** Dot-path route name, e.g. `users.show`. */\n  routeName: string;\n  method: 'get' | 'post' | 'put' | 'patch' | 'delete';\n  isGet: boolean;\n  /** True for reads: a GET, a filter-search route (has `filterFields`), or an\n   *  `@AsQuery()`-marked route — even when the method is POST. Client layers\n   *  use this (not `isGet`) to decide query vs mutation helpers. */\n  isQuery: boolean;\n  hasParams: boolean;\n  hasBody: boolean;\n  /** Type of the leaf's `input` arg, e.g. `{ params: ...; query?: ... }` or `Record<string, never>`. */\n  inputType: string;\n  /** URL expression, e.g. `route('users.show', input?.params) || '/api/users/:id'`. */\n  urlExpr: string;\n  /** Request-options expression, e.g. `{ query: ... }` or `{ body: input?.body }`. */\n  optsExpr: string;\n  /** Response type access, e.g. `ApiRouter['users']['show']['response']`. */\n  responseType: string;\n  /** Stable query-key expression, e.g. `[\"users.show\", input] as const`. */\n  queryKeyExpr: string;\n  /**\n   * Runtime filter-fields literal-array expression, e.g. `[\"id\", \"name\"] as const`,\n   * or `undefined` for a route with no filter. Derived from the same discovered\n   * field list as the type-level `filterFields` union, so the emitted value stays\n   * in lockstep with the type.\n   */\n  filterFieldsExpr?: string | undefined;\n}\n\n/**\n * Per-leaf model passed through the api.ts pipeline: layer → member contributors → render.\n * `requestExpr` is the host's neutral fetcher request; `members`, when present, flips the\n * leaf from a bare callable to a handle.\n */\nexport interface LeafModel {\n  route: RouteDescriptor;\n  request: RequestModel;\n  /** The expression that issues the request (the host's neutral fetcher call). */\n  requestExpr: string;\n  /** When present, the leaf renders as a handle exposing these members (ordered). */\n  members?: Record<string, string>;\n}\n\n/**\n * Top-level `api.ts` imports a client layer depends on. A function of the context so it can\n * be route-aware (e.g. only import `mutationOptions` when a mutation exists). Imports are\n * deduped by the host across all extensions.\n */\nexport interface ApiModuleDeps {\n  /** Raw import lines (e.g. `import { queryOptions as _q } from '@tanstack/react-query';`). */\n  imports?(ctx: ExtensionContext): string[];\n}\n\n/** Single-slot: decides what a leaf returns (the handle members). */\nexport interface ApiClientLayer extends ApiModuleDeps {\n  name: string;\n  /**\n   * Given the request expression (from the transport) and the leaf, return the handle's\n   * members as an ordered `name → value` map (value is the expression after `name: `).\n   * Returning members flips the leaf from a bare callable to a handle.\n   */\n  buildMembers(requestExpr: string, leaf: LeafModel, ctx: ExtensionContext): Record<string, string>;\n}\n\n/**\n * The four request-shape flags derived from a route's method + contract. Computed in ONE\n * place ({@link requestShape}) and read by both the host emitter and client-layer\n * extensions, so the \"filter-search POST counts as a read\" rule is encoded exactly once.\n */\nexport interface RequestShape {\n  /** The route is a `GET`. */\n  isGet: boolean;\n  /** True for reads: a GET, or a filter-search route (carries `filterFields`) even when POST.\n   *  Client layers use this (not `isGet`) to decide query vs mutation helpers. */\n  isQuery: boolean;\n  /** The route carries a body contract (a mutation payload). */\n  hasBody: boolean;\n  /** The route can take a query string — always for GET; a mutation may too (query + body). */\n  hasQuery: boolean;\n}\n\n/**\n * Compute the {@link RequestShape} flags for a route from its method and contract. This is\n * the SINGLE source of truth for these flags — `buildRequestModel`, the TanStack layer's\n * `imports()`, and any other reader must call this rather than re-deriving. The\n * \"filter-search POST counts as a read\" rule lives here and nowhere else.\n */\nexport function requestShape(route: RouteDescriptor): RequestShape {\n  const cs = route.contract?.contractSource;\n  const isGet = route.method.toUpperCase() === 'GET';\n  // A route counts as a read when it's a GET, a filter-search POST (carries\n  // `filterFields`), or explicitly opted in via `@AsQuery()` (`cs.asQuery`) —\n  // e.g. a POST whose semantics are a read (a query-shaped payload).\n  const isQuery = isGet || !!cs?.filterFields?.length || !!cs?.asQuery;\n  // `multipart` implies a body even when the route has no `@Body()` at all (a bare\n  // `@UploadedFile()` route): the type block intersects `multipartBody` into the body\n  // type, so the runtime leaf must accept and forward it too — otherwise the ApiRouter\n  // type promises `body: { file: File | Blob }` while the generated call silently\n  // drops the file.\n  const hasBody = !!cs?.bodyRef || (cs?.body != null && cs.body !== 'never') || !!cs?.multipart;\n  const hasQuery = isGet || !!cs?.queryRef || (cs?.query != null && cs.query !== 'never');\n  return { isGet, isQuery, hasBody, hasQuery };\n}\n\n/** Identity helper for authoring extensions with full type inference. */\nexport function defineExtension(ext: CodegenExtension): CodegenExtension {\n  return ext;\n}\n"],"mappings":";AAyLO,SAAS,aAAa,OAAsC;AACjE,QAAM,KAAK,MAAM,UAAU;AAC3B,QAAM,QAAQ,MAAM,OAAO,YAAY,MAAM;AAI7C,QAAM,UAAU,SAAS,CAAC,CAAC,IAAI,cAAc,UAAU,CAAC,CAAC,IAAI;AAM7D,QAAM,UAAU,CAAC,CAAC,IAAI,WAAY,IAAI,QAAQ,QAAQ,GAAG,SAAS,WAAY,CAAC,CAAC,IAAI;AACpF,QAAM,WAAW,SAAS,CAAC,CAAC,IAAI,YAAa,IAAI,SAAS,QAAQ,GAAG,UAAU;AAC/E,SAAO,EAAE,OAAO,SAAS,SAAS,SAAS;AAC7C;AAGO,SAAS,gBAAgB,KAAyC;AACvE,SAAO;AACT;","names":[]}

package/dist/{index-DT8SgPxp.d.cts → index-CjIDPMsV.d.cts}

@@ -655,6 +655,13 @@ interface RequestModel {
     responseType: string;
     /** Stable query-key expression, e.g. `["users.show", input] as const`. */
     queryKeyExpr: string;
+    /**
+     * Runtime filter-fields literal-array expression, e.g. `["id", "name"] as const`,
+     * or `undefined` for a route with no filter. Derived from the same discovered
+     * field list as the type-level `filterFields` union, so the emitted value stays
+     * in lockstep with the type.
+     */
+    filterFieldsExpr?: string | undefined;
 }
 /**
  * Per-leaf model passed through the api.ts pipeline: layer → member contributors → render.

package/dist/{index-DT8SgPxp.d.ts → index-CjIDPMsV.d.ts}

@@ -655,6 +655,13 @@ interface RequestModel {
     responseType: string;
     /** Stable query-key expression, e.g. `["users.show", input] as const`. */
     queryKeyExpr: string;
+    /**
+     * Runtime filter-fields literal-array expression, e.g. `["id", "name"] as const`,
+     * or `undefined` for a route with no filter. Derived from the same discovered
+     * field list as the type-level `filterFields` union, so the emitted value stays
+     * in lockstep with the type.
+     */
+    filterFieldsExpr?: string | undefined;
 }
 /**
  * Per-leaf model passed through the api.ts pipeline: layer → member contributors → render.

package/dist/index.cjs

@@ -807,6 +807,9 @@ function buildErrorType(c) {
   }
   return c.contractSource.error ?? "unknown";
 }
+function filterFieldLiterals(fields) {
+  return fields?.length ? fields.map((f) => JSON.stringify(f)) : [];
+}
 function emitRouterTypeBlock(tree, indent, outDir, serialization) {
   const pad = " ".repeat(indent);
   const lines = [];
@@ -833,7 +836,8 @@ function emitRouterTypeBlock(tree, indent, outDir, serialization) {
       const params = buildParamsType(c.params);
       const safeMethod = JSON.stringify(method);
       const safeUrl = JSON.stringify(c.path);
-      const filterFields = c.contractSource.filterFields?.length ? c.contractSource.filterFields.map((f) => JSON.stringify(f)).join(" | ") : "never";
+      const filterLiterals = filterFieldLiterals(c.contractSource.filterFields);
+      const filterFields = filterLiterals.length ? filterLiterals.join(" | ") : "never";
       const stream = c.contractSource.stream ? "true" : "false";
       const binary = c.contractSource.binaryResponse ? "true" : "false";
       lines.push(
@@ -873,6 +877,7 @@ function buildRequestModel(c) {
   const TA = buildRouterTypeAccess(c.name);
   const withParams = hasPathParams(c.params);
   const { isGet, isQuery, hasBody, hasQuery } = requestShape(c.route);
+  const filterLiterals = filterFieldLiterals(c.contractSource.filterFields);
   const fields = [];
   if (withParams) fields.push(`params: ${TA}['params']`);
   if (hasQuery) fields.push(`query?: ${TA}['query']`);
@@ -902,7 +907,12 @@ function buildRequestModel(c) {
     // (`[name]` rather than `[name, undefined]`) so the bare `.queryKey()` is a
     // clean prefix that partial-matches every parametrized variant — making it
     // directly usable for `invalidateQueries`.
-    queryKeyExpr: `(input === undefined ? [${flat}] as const : [${flat}, input] as const)`
+    queryKeyExpr: `(input === undefined ? [${flat}] as const : [${flat}, input] as const)`,
+    // Runtime counterpart to the type-level `filterFields` union: the same
+    // discovered field list, emitted as a literal `[...] as const` so apps can
+    // validate a dynamic/user-supplied field string with `isFilterField(...)`
+    // instead of casting. Omitted for routes with no filter.
+    ...filterLiterals.length ? { filterFieldsExpr: `[${filterLiterals.join(", ")}] as const` } : {}
   };
 }
 function renderFetcherRequest(req, binaryResponse) {
@@ -937,9 +947,24 @@ function emitReqHelper() {
     ""
   ];
 }
+function emitFilterFieldGuard() {
+  return [
+    "/** Runtime guard: narrows `value` to one of the leaf's `filterFields` (a `readonly K[] as const`), so a dynamic field string can be passed to `.where()` without a cast. */",
+    "export function isFilterField<const K extends string>(",
+    "  fields: readonly K[],",
+    "  value: string,",
+    "): value is K {",
+    "  return (fields as readonly string[]).includes(value);",
+    "}",
+    ""
+  ];
+}
 function renderLeaf(pad, objKey, req, requestExpr, members, streamExpr) {
   const lines = [`${pad}${objKey}: (input?: ${req.inputType}) => ({`];
   lines.push(`${pad}  ...__req<${req.responseType}>(() => ${requestExpr}),`);
+  if (req.filterFieldsExpr) {
+    lines.push(`${pad}  filterFields: ${req.filterFieldsExpr},`);
+  }
   if (streamExpr) {
     lines.push(`${pad}  stream: () => ${streamExpr},`);
   }
@@ -1211,6 +1236,9 @@ function buildApiFile(routes, outDir, opts = {}) {
   lines.push("};");
   lines.push("");
   lines.push(...emitReqHelper());
+  if (contracted.some((r) => r.contract?.contractSource.filterFields?.length)) {
+    lines.push(...emitFilterFieldGuard());
+  }
   lines.push("export function createApi(fetcher: Fetcher) {");
   lines.push("  return {");
   lines.push(
@@ -2220,19 +2248,41 @@ function isManifestShape(value) {
   if (typeof candidate.hash !== "string") return false;
   if (candidate.entryPoint !== void 0 && !isEntryPoint(candidate.entryPoint)) return false;
   if (candidate.configHash !== void 0 && typeof candidate.configHash !== "string") return false;
+  if (candidate.configKeyHashes !== void 0 && !isStringRecord(candidate.configKeyHashes)) {
+    return false;
+  }
   if (!Array.isArray(candidate.files)) return false;
   return candidate.files.every((entry) => typeof entry === "string");
 }
+function isStringRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((entry) => typeof entry === "string");
+}
 function serializeConfig(config) {
+  return serializeConfigValue(config, `unserializable:${config.codegen.outDir}`);
+}
+function serializeConfigValue(value, unserializableMarker) {
   try {
-    return JSON.stringify(config, (_key, value) => {
-      if (typeof value === "function") return `[fn:${value.name}]${value.toString()}`;
-      return value;
+    return JSON.stringify(value, (_key, entry) => {
+      if (typeof entry === "function") return `[fn:${entry.name}]`;
+      return entry;
     });
   } catch {
-    return `unserializable:${config.codegen.outDir}:${config.contracts.glob}`;
+    return unserializableMarker;
   }
 }
+function computeConfigKeyHashes(config) {
+  const hashes = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (value === void 0) continue;
+    hashes[key] = (0, import_node_crypto.createHash)("sha256").update(serializeConfigValue(value, `unserializable:${key}`)).digest("hex");
+  }
+  return hashes;
+}
+function diffConfigKeyHashes(previous, current) {
+  const keys = /* @__PURE__ */ new Set([...Object.keys(previous), ...Object.keys(current)]);
+  return [...keys].filter((key) => previous[key] !== current[key]).sort();
+}
 async function discoverInputFiles(config) {
   const globs = [config.contracts.glob, config.forms.watch];
   if (config.pages) globs.push(config.pages.glob);
@@ -2267,6 +2317,7 @@ async function readManifest(outDir) {
       hash: parsed.hash,
       ...parsed.entryPoint ? { entryPoint: parsed.entryPoint } : {},
       ...parsed.configHash ? { configHash: parsed.configHash } : {},
+      ...parsed.configKeyHashes ? { configKeyHashes: parsed.configKeyHashes } : {},
       files: parsed.files
     };
   } catch {
@@ -2320,8 +2371,9 @@ function debugWarn(message) {
 }
 
 // src/generate.ts
-function driftGuardMessage(outDir, previousEntryPoint, currentEntryPoint) {
-  return `[nestjs-codegen] Config drift detected in "${outDir}": the last generate ran from the "${previousEntryPoint}" entry point, this run is from the "${currentEntryPoint}" entry point, and their resolved configs differ (e.g. \`serialization: "json"\` vs \`"superjson"\`). Both entry points must read the SAME config \u2014 export a shared config object (e.g. codegen.config.ts) and import it from BOTH nestjs-codegen.config.ts (CLI) and NestjsCodegenModule.forRoot() (Nest module), or set \`driftGuard: false\` on either config to opt out of this check.`;
+function driftGuardMessage(outDir, previousEntryPoint, currentEntryPoint, differingKeys) {
+  const differ = differingKeys.length > 0 ? `their resolved configs differ at: ${differingKeys.map((key) => `\`${key}\``).join(", ")}` : "their resolved configs differ (re-run after this generate records per-key hashes to see which keys)";
+  return `[nestjs-codegen] Config drift detected in "${outDir}": the last generate ran from the "${previousEntryPoint}" entry point, this run is from the "${currentEntryPoint}" entry point, and ${differ}. Both entry points must read the SAME config \u2014 export a shared config object (e.g. codegen.config.ts) and import it from BOTH nestjs-codegen.config.ts (CLI) and NestjsCodegenModule.forRoot() (Nest module), or set \`driftGuard: false\` on either config to opt out of this check.`;
 }
 async function generate(config, inputRoutes = [], entryPoint = "cli") {
   setCodegenDebug(config.debug);
@@ -2332,9 +2384,17 @@ async function generate(config, inputRoutes = [], entryPoint = "cli") {
     return;
   }
   const configHash = computeConfigHash(config);
+  const configKeyHashes = computeConfigKeyHashes(config);
   if (config.driftGuard && manifest?.entryPoint && manifest.entryPoint !== entryPoint && manifest.configHash && manifest.configHash !== configHash) {
     throw new DriftGuardError(
-      driftGuardMessage(config.codegen.outDir, manifest.entryPoint, entryPoint)
+      driftGuardMessage(
+        config.codegen.outDir,
+        manifest.entryPoint,
+        entryPoint,
+        // A pre-key-hash manifest can't tell us WHICH keys differ — pass none
+        // rather than diffing against {} (which would name every key).
+        manifest.configKeyHashes ? diffConfigKeyHashes(manifest.configKeyHashes, configKeyHashes) : []
+      )
     );
   }
   const extensions = config.extensions ?? [];
@@ -2404,6 +2464,7 @@ async function generate(config, inputRoutes = [], entryPoint = "cli") {
     hash: inputsHash,
     entryPoint,
     configHash,
+    configKeyHashes,
     files: outputFiles
   });
 }
@@ -4919,7 +4980,7 @@ function createChainModuleRenderer(opts) {
 }
 
 // src/index.ts
-var VERSION = "0.14.1";
+var VERSION = "0.15.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CodegenError,