@dudousxd/nestjs-codegen 0.13.2 → 0.14.1

package/dist/extension/index.cjs

@@ -29,8 +29,8 @@ module.exports = __toCommonJS(extension_exports);
 function requestShape(route) {
   const cs = route.contract?.contractSource;
   const isGet = route.method.toUpperCase() === "GET";
-  const isQuery = isGet || !!cs?.filterFields?.length;
-  const hasBody = !!cs?.bodyRef || cs?.body != null && cs.body !== "never";
+  const isQuery = isGet || !!cs?.filterFields?.length || !!cs?.asQuery;
+  const hasBody = !!cs?.bodyRef || cs?.body != null && cs.body !== "never" || !!cs?.multipart;
   const hasQuery = isGet || !!cs?.queryRef || cs?.query != null && cs.query !== "never";
   return { isGet, isQuery, hasBody, hasQuery };
 }

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, or a filter-search route (has `filterFields`) even when POST.\n   *  Client layers 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  const isQuery = isGet || !!cs?.filterFields?.length;\n  const hasBody = !!cs?.bodyRef || (cs?.body != null && cs.body !== 'never');\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;;;ACiLO,SAAS,aAAa,OAAsC;AACjE,QAAM,KAAK,MAAM,UAAU;AAC3B,QAAM,QAAQ,MAAM,OAAO,YAAY,MAAM;AAC7C,QAAM,UAAU,SAAS,CAAC,CAAC,IAAI,cAAc;AAC7C,QAAM,UAAU,CAAC,CAAC,IAAI,WAAY,IAAI,QAAQ,QAAQ,GAAG,SAAS;AAClE,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\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":[]}

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-D8RIMVpU.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-DT8SgPxp.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-D8RIMVpU.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-DT8SgPxp.js';
 import 'ts-morph';

package/dist/extension/index.js

@@ -2,8 +2,8 @@
 function requestShape(route) {
   const cs = route.contract?.contractSource;
   const isGet = route.method.toUpperCase() === "GET";
-  const isQuery = isGet || !!cs?.filterFields?.length;
-  const hasBody = !!cs?.bodyRef || cs?.body != null && cs.body !== "never";
+  const isQuery = isGet || !!cs?.filterFields?.length || !!cs?.asQuery;
+  const hasBody = !!cs?.bodyRef || cs?.body != null && cs.body !== "never" || !!cs?.multipart;
   const hasQuery = isGet || !!cs?.queryRef || cs?.query != null && cs.query !== "never";
   return { isGet, isQuery, hasBody, hasQuery };
 }

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, or a filter-search route (has `filterFields`) even when POST.\n   *  Client layers 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  const isQuery = isGet || !!cs?.filterFields?.length;\n  const hasBody = !!cs?.bodyRef || (cs?.body != null && cs.body !== 'never');\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":";AAiLO,SAAS,aAAa,OAAsC;AACjE,QAAM,KAAK,MAAM,UAAU;AAC3B,QAAM,QAAQ,MAAM,OAAO,YAAY,MAAM;AAC7C,QAAM,UAAU,SAAS,CAAC,CAAC,IAAI,cAAc;AAC7C,QAAM,UAAU,CAAC,CAAC,IAAI,WAAY,IAAI,QAAQ,QAAQ,GAAG,SAAS;AAClE,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\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":[]}

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

@@ -330,6 +330,19 @@ interface UserConfig {
         /** Base URL prepended to handler paths. Default: `''` (relative paths). */
         baseUrl?: string;
     };
+    /**
+     * Guard against the CLI (`nestjs-codegen.config.ts`) and the Nest module
+     * (`NestjsCodegenModule.forRoot()`) writing the SAME `outDir` from two
+     * different, drifted configs (classic case: `serialization` `'json'` on one
+     * entry point vs `'superjson'` on the other) — which otherwise ping-pongs
+     * `api.ts` between two shapes as each entry point overwrites the other's
+     * output. When both entry points' resolved configs differ, `generate()`
+     * throws before writing anything, naming both entry points and instructing
+     * you to make them read the same config object. Set `false` to opt out.
+     *
+     * @default true
+     */
+    driftGuard?: boolean;
 }
 interface ScopeConfig {
     glob: string;
@@ -390,6 +403,7 @@ interface ResolvedConfig {
     forms: ResolvedFormsConfig;
     openapi: ResolvedOpenApiConfig;
     mocks: ResolvedMocksConfig;
+    driftGuard: boolean;
 }
 
 interface TypeRef {
@@ -504,6 +518,24 @@ interface ContractSource {
      * or the inline `body` text — preserving the import when there is one.
      */
     multipartBody?: string | null;
+    /**
+     * True when the route's (Promise-unwrapped) handler return type is a binary
+     * download — NestJS `StreamableFile` or Node `Buffer`. The emitted `response`
+     * becomes `RawResponse<Blob>` (never `Jsonify<...>`) and the generated leaf
+     * issues its request via `fetcher.fetchBlob(...)` instead of the verb method,
+     * so callers get `{ data, status, headers }` — the headers carry
+     * `content-disposition` (download filename) etc. Mutually exclusive with
+     * {@link stream}: `Observable`/`ReadableStream` handlers stay on the SSE path.
+     */
+    binaryResponse?: boolean;
+    /**
+     * True when the handler carries the `@AsQuery()` marker decorator
+     * (`@dudousxd/nestjs-codegen/markers`) — an explicit per-route opt-in marking
+     * a non-GET route (e.g. a POST with a query-shaped payload) as a READ, so
+     * {@link import('../extension/types.js').requestShape} emits `queryOptions`
+     * for it the same way a GET or a filter-search route does.
+     */
+    asQuery?: boolean;
 }
 interface ContractDescriptor {
     contractSource: ContractSource;
@@ -607,8 +639,9 @@ interface RequestModel {
     routeName: string;
     method: 'get' | 'post' | 'put' | 'patch' | 'delete';
     isGet: boolean;
-    /** True for reads: a GET, or a filter-search route (has `filterFields`) even when POST.
-     *  Client layers use this (not `isGet`) to decide query vs mutation helpers. */
+    /** True for reads: a GET, a filter-search route (has `filterFields`), or an
+     *  `@AsQuery()`-marked route — even when the method is POST. Client layers
+     *  use this (not `isGet`) to decide query vs mutation helpers. */
     isQuery: boolean;
     hasParams: boolean;
     hasBody: boolean;

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

@@ -330,6 +330,19 @@ interface UserConfig {
         /** Base URL prepended to handler paths. Default: `''` (relative paths). */
         baseUrl?: string;
     };
+    /**
+     * Guard against the CLI (`nestjs-codegen.config.ts`) and the Nest module
+     * (`NestjsCodegenModule.forRoot()`) writing the SAME `outDir` from two
+     * different, drifted configs (classic case: `serialization` `'json'` on one
+     * entry point vs `'superjson'` on the other) — which otherwise ping-pongs
+     * `api.ts` between two shapes as each entry point overwrites the other's
+     * output. When both entry points' resolved configs differ, `generate()`
+     * throws before writing anything, naming both entry points and instructing
+     * you to make them read the same config object. Set `false` to opt out.
+     *
+     * @default true
+     */
+    driftGuard?: boolean;
 }
 interface ScopeConfig {
     glob: string;
@@ -390,6 +403,7 @@ interface ResolvedConfig {
     forms: ResolvedFormsConfig;
     openapi: ResolvedOpenApiConfig;
     mocks: ResolvedMocksConfig;
+    driftGuard: boolean;
 }
 
 interface TypeRef {
@@ -504,6 +518,24 @@ interface ContractSource {
      * or the inline `body` text — preserving the import when there is one.
      */
     multipartBody?: string | null;
+    /**
+     * True when the route's (Promise-unwrapped) handler return type is a binary
+     * download — NestJS `StreamableFile` or Node `Buffer`. The emitted `response`
+     * becomes `RawResponse<Blob>` (never `Jsonify<...>`) and the generated leaf
+     * issues its request via `fetcher.fetchBlob(...)` instead of the verb method,
+     * so callers get `{ data, status, headers }` — the headers carry
+     * `content-disposition` (download filename) etc. Mutually exclusive with
+     * {@link stream}: `Observable`/`ReadableStream` handlers stay on the SSE path.
+     */
+    binaryResponse?: boolean;
+    /**
+     * True when the handler carries the `@AsQuery()` marker decorator
+     * (`@dudousxd/nestjs-codegen/markers`) — an explicit per-route opt-in marking
+     * a non-GET route (e.g. a POST with a query-shaped payload) as a READ, so
+     * {@link import('../extension/types.js').requestShape} emits `queryOptions`
+     * for it the same way a GET or a filter-search route does.
+     */
+    asQuery?: boolean;
 }
 interface ContractDescriptor {
     contractSource: ContractSource;
@@ -607,8 +639,9 @@ interface RequestModel {
     routeName: string;
     method: 'get' | 'post' | 'put' | 'patch' | 'delete';
     isGet: boolean;
-    /** True for reads: a GET, or a filter-search route (has `filterFields`) even when POST.
-     *  Client layers use this (not `isGet`) to decide query vs mutation helpers. */
+    /** True for reads: a GET, a filter-search route (has `filterFields`), or an
+     *  `@AsQuery()`-marked route — even when the method is POST. Client layers
+     *  use this (not `isGet`) to decide query vs mutation helpers. */
     isQuery: boolean;
     hasParams: boolean;
     hasBody: boolean;

package/dist/index.cjs

@@ -32,6 +32,7 @@ var src_exports = {};
 __export(src_exports, {
   CodegenError: () => CodegenError,
   ConfigError: () => ConfigError,
+  DriftGuardError: () => DriftGuardError,
   VERSION: () => VERSION,
   acquireLock: () => acquireLock,
   buildMocksFile: () => buildMocksFile,
@@ -211,7 +212,8 @@ function applyDefaults(userConfig, cwd) {
       fileName: userConfig.mocks?.fileName ?? "mocks.ts",
       seed: userConfig.mocks?.seed ?? 1,
       baseUrl: userConfig.mocks?.baseUrl ?? ""
-    }
+    },
+    driftGuard: userConfig.driftGuard ?? true
   };
 }
 async function loadConfig(cwd) {
@@ -671,8 +673,8 @@ async function collectEmittedFiles(extensions, ctx) {
 function requestShape(route) {
   const cs = route.contract?.contractSource;
   const isGet = route.method.toUpperCase() === "GET";
-  const isQuery = isGet || !!cs?.filterFields?.length;
-  const hasBody = !!cs?.bodyRef || cs?.body != null && cs.body !== "never";
+  const isQuery = isGet || !!cs?.filterFields?.length || !!cs?.asQuery;
+  const hasBody = !!cs?.bodyRef || cs?.body != null && cs.body !== "never" || !!cs?.multipart;
   const hasQuery = isGet || !!cs?.queryRef || cs?.query != null && cs.query !== "never";
   return { isGet, isQuery, hasBody, hasQuery };
 }
@@ -778,6 +780,7 @@ function emitFilterQueryType(c) {
   return `import('@dudousxd/nestjs-filter-client').TypedFilterQuery<${emitFilterQueryTypeArgs(c)}>`;
 }
 function buildResponseType(c, outDir, serialization) {
+  if (c.contractSource.binaryResponse) return "RawResponse<Blob>";
   const raw = rawResponseType(c, outDir);
   return serialization === "json" ? `Jsonify<${raw}>` : raw;
 }
@@ -832,8 +835,9 @@ function emitRouterTypeBlock(tree, indent, outDir, serialization) {
       const safeUrl = JSON.stringify(c.path);
       const filterFields = c.contractSource.filterFields?.length ? c.contractSource.filterFields.map((f) => JSON.stringify(f)).join(" | ") : "never";
       const stream = c.contractSource.stream ? "true" : "false";
+      const binary = c.contractSource.binaryResponse ? "true" : "false";
       lines.push(
-        `${pad}${objKey}: { method: ${safeMethod}; url: ${safeUrl}; params: ${params}; query: ${query}; body: ${body}; response: ${response}; error: ${error}; filterFields: ${filterFields}; stream: ${stream} };`
+        `${pad}${objKey}: { method: ${safeMethod}; url: ${safeUrl}; params: ${params}; query: ${query}; body: ${body}; response: ${response}; error: ${error}; filterFields: ${filterFields}; stream: ${stream}; binary: ${binary} };`
       );
     } else {
       lines.push(`${pad}${objKey}: {`);
@@ -879,6 +883,9 @@ function buildRequestModel(c) {
   if (hasQuery) optsParts.push("query: input?.query as Record<string, unknown> | undefined");
   if (hasBody) optsParts.push("body: input?.body");
   if (hasBody && c.contractSource.multipart) optsParts.push("multipart: true");
+  if (c.contractSource.binaryResponse && m !== "get") {
+    optsParts.unshift(`method: ${JSON.stringify(m.toUpperCase())}`);
+  }
   const optsExpr = optsParts.length ? `{ ${optsParts.join(", ")} }` : "{}";
   return {
     routeName: c.name,
@@ -898,7 +905,8 @@ function buildRequestModel(c) {
     queryKeyExpr: `(input === undefined ? [${flat}] as const : [${flat}, input] as const)`
   };
 }
-function renderFetcherRequest(req) {
+function renderFetcherRequest(req, binaryResponse) {
+  if (binaryResponse) return `fetcher.fetchBlob(${req.urlExpr}, ${req.optsExpr})`;
   return `fetcher.${req.method}<${req.responseType}>(${req.urlExpr}, ${req.optsExpr})`;
 }
 function emitReqHelper() {
@@ -959,7 +967,7 @@ function emitApiObjectBlock(tree, indent, p) {
     const leaf = {
       route: node.route,
       request: req,
-      requestExpr: renderFetcherRequest(req)
+      requestExpr: renderFetcherRequest(req, node.contractSource.binaryResponse === true)
     };
     const owned = /* @__PURE__ */ new Map();
     if (p.layer) {
@@ -1019,6 +1027,8 @@ var ROUTE_NAMESPACE = [
   '  export type FilterFields<K extends string> = ResolveByName<K, "filterFields">;',
   "  /** The streamed element type of an `@Sse()`/streaming route \u2014 the type yielded by its `stream()` AsyncIterable. */",
   '  export type Stream<K extends string> = ResolveByName<K, "response">;',
+  "  /** True for a binary/blob route (`StreamableFile`/`Buffer` handler return type). */",
+  '  export type Binary<K extends string> = ResolveByName<K, "binary">;',
   "  export type Request<K extends string> = {",
   "    body: Body<K>;",
   "    query: Query<K>;",
@@ -1036,6 +1046,7 @@ var PATH_NAMESPACE = [
   '  export type Error<M extends string, U extends string> = ResolveByPath<M, U, "error">;',
   '  export type FilterFields<M extends string, U extends string> = ResolveByPath<M, U, "filterFields">;',
   '  export type Stream<M extends string, U extends string> = ResolveByPath<M, U, "response">;',
+  '  export type Binary<M extends string, U extends string> = ResolveByPath<M, U, "binary">;',
   "}",
   ""
 ];
@@ -1048,6 +1059,7 @@ var EMPTY_ROUTE_NAMESPACE = [
   "  export type Error<K extends string> = never;",
   "  export type FilterFields<K extends string> = never;",
   "  export type Stream<K extends string> = never;",
+  "  export type Binary<K extends string> = never;",
   "  export type Request<K extends string> = { body: never; query: never; params: never };",
   "}",
   ""
@@ -1061,6 +1073,7 @@ var EMPTY_PATH_NAMESPACE = [
   "  export type Error<M extends string, U extends string> = never;",
   "  export type FilterFields<M extends string, U extends string> = never;",
   "  export type Stream<M extends string, U extends string> = never;",
+  "  export type Binary<M extends string, U extends string> = never;",
   "}",
   ""
 ];
@@ -1126,6 +1139,9 @@ function buildApiFile(routes, outDir, opts = {}) {
   if (serialization === "json" && contracted.length > 0) {
     lines.push(`import type { Jsonify } from '${runtimeImport}';`);
   }
+  if (contracted.some((r) => r.contract?.contractSource.binaryResponse)) {
+    lines.push(`import type { RawResponse } from '${runtimeImport}';`);
+  }
   if (importsByFile.size > 0 && outDir) {
     lines.push("");
     const emittedNames = /* @__PURE__ */ new Set();
@@ -1162,6 +1178,12 @@ function buildApiFile(routes, outDir, opts = {}) {
     lines.push("");
     lines.push(...EMPTY_ROUTE_NAMESPACE);
     lines.push(...EMPTY_PATH_NAMESPACE);
+    for (const ext of headerExts) {
+      const statements = ext.apiHeader?.(ctx)?.statements;
+      if (statements?.length) {
+        lines.push(...statements, "");
+      }
+    }
     return lines.join("\n");
   }
   const tree = /* @__PURE__ */ new Map();
@@ -2182,11 +2204,22 @@ var import_node_path12 = require("path");
 var import_fast_glob2 = __toESM(require("fast-glob"), 1);
 var MANIFEST_FILE = ".codegen-manifest.json";
 var LOCK_FILE = ".watcher.lock";
+var DriftGuardError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DriftGuardError";
+  }
+};
+function isEntryPoint(value) {
+  return value === "cli" || value === "module";
+}
 function isManifestShape(value) {
   if (typeof value !== "object" || value === null) return false;
   const candidate = value;
   if (typeof candidate.version !== "string") return false;
   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 (!Array.isArray(candidate.files)) return false;
   return candidate.files.every((entry) => typeof entry === "string");
 }
@@ -2229,11 +2262,20 @@ async function readManifest(outDir) {
     const raw = await (0, import_promises11.readFile)((0, import_node_path12.join)(outDir, MANIFEST_FILE), "utf8");
     const parsed = JSON.parse(raw);
     if (!isManifestShape(parsed)) return null;
-    return { version: parsed.version, hash: parsed.hash, files: parsed.files };
+    return {
+      version: parsed.version,
+      hash: parsed.hash,
+      ...parsed.entryPoint ? { entryPoint: parsed.entryPoint } : {},
+      ...parsed.configHash ? { configHash: parsed.configHash } : {},
+      files: parsed.files
+    };
   } catch {
     return null;
   }
 }
+function computeConfigHash(config) {
+  return (0, import_node_crypto.createHash)("sha256").update(serializeConfig(config)).digest("hex");
+}
 async function writeManifest(outDir, manifest) {
   await (0, import_promises11.writeFile)((0, import_node_path12.join)(outDir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
@@ -2278,7 +2320,10 @@ function debugWarn(message) {
 }
 
 // src/generate.ts
-async function generate(config, inputRoutes = []) {
+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.`;
+}
+async function generate(config, inputRoutes = [], entryPoint = "cli") {
   setCodegenDebug(config.debug);
   const inputsHash = await computeInputsHash(config);
   const manifest = await readManifest(config.codegen.outDir);
@@ -2286,6 +2331,12 @@ async function generate(config, inputRoutes = []) {
     console.log(`[nestjs-codegen] ${config.codegen.outDir} up to date, skipped`);
     return;
   }
+  const configHash = computeConfigHash(config);
+  if (config.driftGuard && manifest?.entryPoint && manifest.entryPoint !== entryPoint && manifest.configHash && manifest.configHash !== configHash) {
+    throw new DriftGuardError(
+      driftGuardMessage(config.codegen.outDir, manifest.entryPoint, entryPoint)
+    );
+  }
   const extensions = config.extensions ?? [];
   let routes = inputRoutes;
   const ctx = createExtensionContext(config, () => routes);
@@ -2351,6 +2402,8 @@ async function generate(config, inputRoutes = []) {
   await writeManifest(config.codegen.outDir, {
     version: VERSION,
     hash: inputsHash,
+    entryPoint,
+    configHash,
     files: outputFiles
   });
 }
@@ -3925,6 +3978,14 @@ function resolveBodyQueryResponseRef(typeNode, sourceFile, project) {
 var STREAM_CONTAINERS = /* @__PURE__ */ new Set(["Observable", "AsyncIterable", "AsyncIterableIterator"]);
 var STREAM_CONTAINERS_GENERATOR = /* @__PURE__ */ new Set(["AsyncGenerator"]);
 var STREAM_ENVELOPES = /* @__PURE__ */ new Set(["MessageEvent", "MessageEventLike"]);
+var BINARY_RESPONSE_TYPES = /* @__PURE__ */ new Set(["StreamableFile", "Buffer"]);
+function detectBinaryResponse(method) {
+  const node = unwrapNamedContainer(method.getReturnTypeNode(), /* @__PURE__ */ new Set(["Promise"]));
+  if (!node || !import_ts_morph7.Node.isTypeReference(node)) return false;
+  const typeName = node.getTypeName();
+  const name = import_ts_morph7.Node.isIdentifier(typeName) ? typeName.getText() : "";
+  return BINARY_RESPONSE_TYPES.has(name);
+}
 function detectStreamElement(method) {
   const hasSse = method.getDecorators().some((d) => d.getName() === "Sse");
   let node = method.getReturnTypeNode();
@@ -3945,6 +4006,9 @@ function streamContainerElement(node) {
   }
   return null;
 }
+function hasAsQueryDecorator(method) {
+  return method.getDecorators().some((d) => d.getName() === "AsQuery");
+}
 function unwrapNamedContainer(node, names) {
   if (!node || !import_ts_morph7.Node.isTypeReference(node)) return node;
   const typeName = node.getTypeName();
@@ -3962,6 +4026,8 @@ function extractDtoContract(method, sourceFile, project) {
   const multipartBody = uploads.fields ? `{ ${uploads.fields} }` : null;
   const streamElement = detectStreamElement(method);
   const isStream = streamElement !== null;
+  const binaryResponse = detectBinaryResponse(method);
+  const asQuery = hasAsQueryDecorator(method);
   if (filterInfo && filterInfo.source === "body") {
     const bodyType = "import('@dudousxd/nestjs-filter-client').FilterQueryResult";
     body = body ?? bodyType;
@@ -3969,7 +4035,7 @@ function extractDtoContract(method, sourceFile, project) {
   const paramsType = extractParamsType(method, sourceFile, project);
   const response = isStream ? resolveTypeNodeToString(streamElement, sourceFile, project, 3) : extractResponseType(method, sourceFile, project);
   const errorInfo = extractErrorType(method, sourceFile, project);
-  if (body === null && query === null && paramsType === null && response === "unknown" && errorInfo === null && filterInfo === null && !isStream && !uploads.multipart) {
+  if (body === null && query === null && paramsType === null && response === "unknown" && errorInfo === null && filterInfo === null && !isStream && !uploads.multipart && !binaryResponse && !asQuery) {
     return null;
   }
   let bodyRef = null;
@@ -4044,7 +4110,9 @@ function extractDtoContract(method, sourceFile, project) {
     querySchema,
     stream: isStream,
     multipart: uploads.multipart,
-    multipartBody
+    multipartBody,
+    binaryResponse,
+    asQuery
   };
 }
 function resolveParamClass(method, decoratorName, sourceFile, project) {
@@ -4531,7 +4599,9 @@ function extractDtoRoute(args) {
       querySchema: dtoContract?.querySchema ?? null,
       stream: dtoContract?.stream ?? false,
       multipart: dtoContract?.multipart ?? false,
-      multipartBody: dtoContract?.multipartBody ?? null
+      multipartBody: dtoContract?.multipartBody ?? null,
+      binaryResponse: dtoContract?.binaryResponse ?? false,
+      asQuery: dtoContract?.asQuery ?? false
     }
   });
 }
@@ -4624,6 +4694,7 @@ var PAGES_DEBOUNCE_MS = 150;
 var NO_OP_WATCHER = { close: async () => {
 } };
 async function watch(config, onChange, options = {}) {
+  const entryPoint = options.entryPoint ?? "cli";
   const lock = await acquireLock(config.codegen.outDir);
   if (lock === null) {
     let holderPid = "unknown";
@@ -4655,13 +4726,17 @@ async function watch(config, onChange, options = {}) {
     try {
       const initialRoutes = (await getDiscovery()).discover();
       lastRoutes = initialRoutes;
-      await generate(config, initialRoutes);
+      await generate(config, initialRoutes, entryPoint);
     } catch (err) {
+      if (err instanceof DriftGuardError) {
+        console.error(err.message);
+        return;
+      }
       console.warn(
         `[nestjs-codegen] Initial route discovery failed, falling back to pages-only: ${err instanceof Error ? err.message : String(err)}`
       );
       try {
-        await generate(config, lastRoutes);
+        await generate(config, lastRoutes, entryPoint);
       } catch {
       }
     }
@@ -4689,7 +4764,7 @@ async function watch(config, onChange, options = {}) {
     pagesDebounceTimer = setTimeout(async () => {
       pagesDebounceTimer = void 0;
       try {
-        await generate(config, lastRoutes);
+        await generate(config, lastRoutes, entryPoint);
       } catch (err) {
         console.error(
           "[nestjs-codegen] Pages generation failed:",
@@ -4721,7 +4796,7 @@ async function watch(config, onChange, options = {}) {
       try {
         const routes = await (await getDiscovery()).rediscover(changed);
         lastRoutes = routes;
-        await generate(config, routes);
+        await generate(config, routes, entryPoint);
       } catch (err) {
         console.error(
           "[nestjs-codegen] Contracts generation failed:",
@@ -4844,11 +4919,12 @@ function createChainModuleRenderer(opts) {
 }
 
 // src/index.ts
-var VERSION = "0.13.2";
+var VERSION = "0.14.1";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CodegenError,
   ConfigError,
+  DriftGuardError,
   VERSION,
   acquireLock,
   buildMocksFile,