@dudousxd/nestjs-codegen 0.2.1 → 0.4.0

package/dist/extension/index.cjs

@@ -20,16 +20,26 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/extension/index.ts
 var extension_exports = {};
 __export(extension_exports, {
-  defineExtension: () => defineExtension
+  defineExtension: () => defineExtension,
+  requestShape: () => requestShape
 });
 module.exports = __toCommonJS(extension_exports);
 
 // src/extension/types.ts
+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 hasQuery = isGet || !!cs?.queryRef || cs?.query != null && cs.query !== "never";
+  return { isGet, isQuery, hasBody, hasQuery };
+}
 function defineExtension(ext) {
   return ext;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  defineExtension
+  defineExtension,
+  requestShape
 });
 //# sourceMappingURL=index.cjs.map

package/dist/extension/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/extension/index.ts","../../src/extension/types.ts"],"sourcesContent":["export { defineExtension } from './types.js';\nexport type {\n  ApiClientLayer,\n  ApiHeaderContribution,\n  ApiModuleDeps,\n  ApiTransport,\n  CodegenExtension,\n  EmittedFile,\n  ExtensionContext,\n  LeafModel,\n  RequestModel,\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 **how** a single endpoint issues its request. When unset by every extension,\n   * the host falls back to the neutral fetcher transport. Example: the Inertia extension\n   * routes mutations through the Inertia router while GETs stay fetcher-typed.\n   */\n  apiTransport?: ApiTransport;\n\n  /**\n   * Claims **what** a leaf returns. When unset, a leaf is a bare callable returning a\n   * `Promise`. Example: the TanStack extension wraps each leaf into a handle exposing\n   * `{ fetch, queryKey, queryOptions | mutationOptions }`.\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  /** Body type access, e.g. `ApiRouter['users']['create']['body']` (for mutation layers). */\n  bodyType: 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: transport → layer → member\n * contributors → render. `requestExpr` is set by the transport; `members`, when present,\n * flips the 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 (set by the transport, default = fetcher). */\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 + helpers a transport or layer depends on. Functions of the\n * context so they can be route-aware (e.g. only import `mutationOptions` when a mutation\n * exists). Imports are 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  /** Module-level helper declarations the rendered expressions depend on. */\n  helpers?(ctx: ExtensionContext): string[];\n}\n\n/** Single-slot: decides how an endpoint issues its request. */\nexport interface ApiTransport extends ApiModuleDeps {\n  name: string;\n  /** Render the expression that issues this endpoint's request (e.g. `fetcher.get<Res>(url, opts)`). */\n  renderRequest(leaf: LeafModel, 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/** 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;;;AC2KO,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, 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":[]}

package/dist/extension/index.d.cts

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

package/dist/extension/index.d.ts

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

package/dist/extension/index.js

@@ -1,8 +1,17 @@
 // src/extension/types.ts
+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 hasQuery = isGet || !!cs?.queryRef || cs?.query != null && cs.query !== "never";
+  return { isGet, isQuery, hasBody, hasQuery };
+}
 function defineExtension(ext) {
   return ext;
 }
 export {
-  defineExtension
+  defineExtension,
+  requestShape
 };
 //# sourceMappingURL=index.js.map

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 **how** a single endpoint issues its request. When unset by every extension,\n   * the host falls back to the neutral fetcher transport. Example: the Inertia extension\n   * routes mutations through the Inertia router while GETs stay fetcher-typed.\n   */\n  apiTransport?: ApiTransport;\n\n  /**\n   * Claims **what** a leaf returns. When unset, a leaf is a bare callable returning a\n   * `Promise`. Example: the TanStack extension wraps each leaf into a handle exposing\n   * `{ fetch, queryKey, queryOptions | mutationOptions }`.\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  /** Body type access, e.g. `ApiRouter['users']['create']['body']` (for mutation layers). */\n  bodyType: 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: transport → layer → member\n * contributors → render. `requestExpr` is set by the transport; `members`, when present,\n * flips the 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 (set by the transport, default = fetcher). */\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 + helpers a transport or layer depends on. Functions of the\n * context so they can be route-aware (e.g. only import `mutationOptions` when a mutation\n * exists). Imports are 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  /** Module-level helper declarations the rendered expressions depend on. */\n  helpers?(ctx: ExtensionContext): string[];\n}\n\n/** Single-slot: decides how an endpoint issues its request. */\nexport interface ApiTransport extends ApiModuleDeps {\n  name: string;\n  /** Render the expression that issues this endpoint's request (e.g. `fetcher.get<Res>(url, opts)`). */\n  renderRequest(leaf: LeafModel, 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/** Identity helper for authoring extensions with full type inference. */\nexport function defineExtension(ext: CodegenExtension): CodegenExtension {\n  return ext;\n}\n"],"mappings":";AA2KO,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, 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":[]}

package/dist/{index-BwIRjOQA.d.cts → index-DA4uySjo.d.cts}

@@ -111,6 +111,14 @@ interface SchemaModule {
     root: SchemaNode;
     named: Map<string, SchemaNode>;
     warnings: string[];
+    /**
+     * Names (keys of {@link named}) that are genuinely self/mutually recursive,
+     * i.e. reachable from themselves through a `lazyRef` back-edge. Adapters use
+     * this to break the TypeScript inference cycle (annotated const + hoisted
+     * structural type for zod/valibot; `this`/degrade for arktype). Absent or
+     * empty means no recursion.
+     */
+    recursive?: Set<string>;
 }
 
 /** Signals to an adapter what it must import to render the current output. */
@@ -121,12 +129,32 @@ interface AdapterUsage {
 interface RenderContext {
     /** Hoisted named schemas being emitted alongside the root. */
     named: Map<string, SchemaNode>;
+    /**
+     * Name of the hoisted schema currently being rendered, when rendering a named
+     * schema's own body. Lets an adapter express a self-reference specially (e.g.
+     * arktype's `this` keyword). Absent when rendering the root.
+     */
+    selfName?: string;
 }
 interface RenderedModule {
     /** Root schema source text, e.g. `"z.object({ email: z.string().email() })"`. */
     schemaText: string;
     /** name → schema source text, hoisted above the parent. */
     namedNestedSchemas: Map<string, string>;
+    /**
+     * name → hoisted TS `type` alias *body* for a recursive schema (e.g.
+     * `"{ field?: string; and?: Array<ColumnFilter> }"`), emitted as
+     * `type <TypeName> = <body>;` above the const. The alias name is derived from
+     * the schema name. Absent for adapters/schemas that don't need it (arktype,
+     * non-recursive schemas).
+     */
+    namedTypeAliases?: Map<string, string>;
+    /**
+     * name → const type annotation for a recursive schema (e.g.
+     * `"z.ZodType<ColumnFilter>"`), emitted as `const <name>: <annotation> = ...`
+     * to break the implicit-any self-reference cycle.
+     */
+    namedAnnotations?: Map<string, string>;
     warnings: string[];
 }
 /**
@@ -137,6 +165,12 @@ interface RenderedModule {
 interface ValidationAdapter {
     /** 'zod' | 'valibot' | 'arktype'. */
     name: string;
+    /**
+     * When `true`, the emitter may pass raw zod source from `defineContract`
+     * (`bodyZodText`/`bodyZodRef`) through verbatim and emit a `z` import. Only the
+     * zod adapter sets this; any other adapter skips raw-zod sources with a warning.
+     */
+    acceptsRawZodSource?: boolean;
     /** Import lines required for any rendered text (e.g. `import { z } from 'zod'`). */
     importStatements(usage: AdapterUsage): string[];
     /** Render a single node to this lib's source text. */
@@ -150,14 +184,14 @@ interface ValidationAdapter {
 /** A built-in adapter name or a custom adapter instance. */
 type ValidationOption = 'zod' | 'valibot' | 'arktype' | ValidationAdapter;
 /**
- * Resolve a `validation` config value to a {@link ValidationAdapter}. `'zod'` is
- * bundled in core; the valibot/arktype adapters ship as their own packages — import
- * the adapter instance and pass it directly (it passes through here). A custom
- * adapter object also passes through.
+ * Resolve a `validation` config value to a {@link ValidationAdapter}. No adapter is
+ * bundled in core — the zod/valibot/arktype adapters ship as their own packages.
+ * Import the adapter instance and pass it directly (it passes through here). A
+ * custom adapter object also passes through.
  *
  * @example
- * import { valibotAdapter } from '@dudousxd/nestjs-codegen-valibot';
- * defineConfig({ validation: valibotAdapter });
+ * import { zodAdapter } from '@dudousxd/nestjs-codegen-zod';
+ * defineConfig({ validation: zodAdapter });
  */
 declare function resolveAdapter(option: ValidationOption): ValidationAdapter;
 
@@ -166,15 +200,15 @@ interface UserConfig {
      * Codegen extensions, applied in order. Each may augment the route IR
      * (`transformRoutes`), contribute extra output files (`emitFiles`), and — once a
      * client layer is active — shape `api.ts`. Registered explicitly, e.g.
-     * `extensions: [nestjsInertiaCodegen(), tanstackQuery()]`.
+     * `extensions: [clientCodegen(), tanstackQuery()]`.
      */
     extensions?: CodegenExtension[];
     /**
-     * Validation library for emitted `forms.ts` schemas. `'zod'` (bundled, default)
-     * or an imported adapter instance (`valibotAdapter`/`arktypeAdapter`).
-     * @default 'zod'
+     * Validation library for emitted `forms.ts` schemas. Required — pass an imported
+     * adapter instance, e.g. `zodAdapter` from `@dudousxd/nestjs-codegen-zod`, or
+     * `valibotAdapter`/`arktypeAdapter` from their packages.
      */
-    validation?: ValidationOption;
+    validation: ValidationOption;
     /** Inertia page discovery. Omit when you don't use Inertia. */
     pages?: {
         glob: string;
@@ -202,11 +236,11 @@ interface UserConfig {
      * This lets users configure baseUrl, headers, plugins (e.g. superjson).
      *
      * @example
-     * // nestjs-inertia.config.ts
+     * // nestjs-codegen.config.ts
      * fetcher: { importPath: '~/lib/api' }
      *
-     * // inertia/lib/api.ts
-     * import { createFetcher } from '@dudousxd/nestjs-inertia-client';
+     * // src/lib/api.ts
+     * import { createFetcher } from '@dudousxd/nestjs-client';
      * export const fetcher = createFetcher({ baseUrl: '/api' });
      */
     fetcher?: {
@@ -402,15 +436,11 @@ interface CodegenExtension {
      */
     apiMembers?(leaf: LeafModel, ctx: ExtensionContext): Record<string, string> | undefined;
     /**
-     * Claims **how** a single endpoint issues its request. When unset by every extension,
-     * the host falls back to the neutral fetcher transport. Example: the Inertia extension
-     * routes mutations through the Inertia router while GETs stay fetcher-typed.
-     */
-    apiTransport?: ApiTransport;
-    /**
-     * Claims **what** a leaf returns. When unset, a leaf is a bare callable returning a
-     * `Promise`. Example: the TanStack extension wraps each leaf into a handle exposing
-     * `{ fetch, queryKey, queryOptions | mutationOptions }`.
+     * Claims **what** a leaf returns and **how** it issues its request. At most one extension
+     * may claim it. When unset, a leaf is a bare awaitable callable backed by the neutral
+     * fetcher. Example: the TanStack extension wraps each leaf into a handle exposing
+     * `{ fetch, queryKey, queryOptions | mutationOptions }`, composing with the fetcher
+     * request the host passes in.
      */
     apiClientLayer?: ApiClientLayer;
 }
@@ -458,40 +488,30 @@ interface RequestModel {
     optsExpr: string;
     /** Response type access, e.g. `ApiRouter['users']['show']['response']`. */
     responseType: string;
-    /** Body type access, e.g. `ApiRouter['users']['create']['body']` (for mutation layers). */
-    bodyType: string;
     /** Stable query-key expression, e.g. `["users.show", input] as const`. */
     queryKeyExpr: string;
 }
 /**
- * Per-leaf model passed through the api.ts pipeline: transport → layer → member
- * contributors → render. `requestExpr` is set by the transport; `members`, when present,
- * flips the leaf from a bare callable to a handle.
+ * Per-leaf model passed through the api.ts pipeline: layer → member contributors → render.
+ * `requestExpr` is the host's neutral fetcher request; `members`, when present, flips the
+ * leaf from a bare callable to a handle.
  */
 interface LeafModel {
     route: RouteDescriptor;
     request: RequestModel;
-    /** The expression that issues the request (set by the transport, default = fetcher). */
+    /** The expression that issues the request (the host's neutral fetcher call). */
     requestExpr: string;
     /** When present, the leaf renders as a handle exposing these members (ordered). */
     members?: Record<string, string>;
 }
 /**
- * Top-level `api.ts` imports + helpers a transport or layer depends on. Functions of the
- * context so they can be route-aware (e.g. only import `mutationOptions` when a mutation
- * exists). Imports are deduped by the host across all extensions.
+ * Top-level `api.ts` imports a client layer depends on. A function of the context so it can
+ * be route-aware (e.g. only import `mutationOptions` when a mutation exists). Imports are
+ * deduped by the host across all extensions.
  */
 interface ApiModuleDeps {
     /** Raw import lines (e.g. `import { queryOptions as _q } from '@tanstack/react-query';`). */
     imports?(ctx: ExtensionContext): string[];
-    /** Module-level helper declarations the rendered expressions depend on. */
-    helpers?(ctx: ExtensionContext): string[];
-}
-/** Single-slot: decides how an endpoint issues its request. */
-interface ApiTransport extends ApiModuleDeps {
-    name: string;
-    /** Render the expression that issues this endpoint's request (e.g. `fetcher.get<Res>(url, opts)`). */
-    renderRequest(leaf: LeafModel, ctx: ExtensionContext): string;
 }
 /** Single-slot: decides what a leaf returns (the handle members). */
 interface ApiClientLayer extends ApiModuleDeps {
@@ -503,7 +523,30 @@ interface ApiClientLayer extends ApiModuleDeps {
      */
     buildMembers(requestExpr: string, leaf: LeafModel, ctx: ExtensionContext): Record<string, string>;
 }
+/**
+ * The four request-shape flags derived from a route's method + contract. Computed in ONE
+ * place ({@link requestShape}) and read by both the host emitter and client-layer
+ * extensions, so the "filter-search POST counts as a read" rule is encoded exactly once.
+ */
+interface RequestShape {
+    /** The route is a `GET`. */
+    isGet: boolean;
+    /** True for reads: a GET, or a filter-search route (carries `filterFields`) even when POST.
+     *  Client layers use this (not `isGet`) to decide query vs mutation helpers. */
+    isQuery: boolean;
+    /** The route carries a body contract (a mutation payload). */
+    hasBody: boolean;
+    /** The route can take a query string — always for GET; a mutation may too (query + body). */
+    hasQuery: boolean;
+}
+/**
+ * Compute the {@link RequestShape} flags for a route from its method and contract. This is
+ * the SINGLE source of truth for these flags — `buildRequestModel`, the TanStack layer's
+ * `imports()`, and any other reader must call this rather than re-deriving. The
+ * "filter-search POST counts as a read" rule lives here and nowhere else.
+ */
+declare function requestShape(route: RouteDescriptor): RequestShape;
 /** Identity helper for authoring extensions with full type inference. */
 declare function defineExtension(ext: CodegenExtension): CodegenExtension;
 
-export { type AdapterUsage as A, type CodegenExtension as C, type ExtensionContext as E, type LeafModel as L, type NumberCheck as N, type ResolvedConfig as R, type SchemaModule as S, type TypeRef as T, type UserConfig as U, type ValidationAdapter as V, type RouteDescriptor as a, type ResolvedFormsConfig as b, type ContractDescriptor as c, type ContractSource as d, type ControllerRef as e, type RenderContext as f, type RenderedModule as g, type SchemaNode as h, type ScopeConfig as i, type StringCheck as j, type ValidationOption as k, type ApiClientLayer as l, type ApiHeaderContribution as m, type ApiModuleDeps as n, type ApiTransport as o, type EmittedFile as p, type RequestModel as q, resolveAdapter as r, defineExtension as s };
+export { type AdapterUsage as A, type CodegenExtension as C, type ExtensionContext as E, type LeafModel as L, type NumberCheck as N, type ResolvedConfig as R, type SchemaNode as S, type TypeRef as T, type UserConfig as U, type ValidationAdapter as V, type RouteDescriptor as a, type SchemaModule as b, type ResolvedFormsConfig as c, type ContractDescriptor as d, type ContractSource as e, type ControllerRef as f, type RenderContext as g, type RenderedModule as h, type ScopeConfig as i, type StringCheck as j, type ValidationOption as k, type ApiClientLayer as l, type ApiHeaderContribution as m, type ApiModuleDeps as n, type EmittedFile as o, type RequestModel as p, type RequestShape as q, resolveAdapter as r, defineExtension as s, requestShape as t };

package/dist/{index-BwIRjOQA.d.ts → index-DA4uySjo.d.ts}

@@ -111,6 +111,14 @@ interface SchemaModule {
     root: SchemaNode;
     named: Map<string, SchemaNode>;
     warnings: string[];
+    /**
+     * Names (keys of {@link named}) that are genuinely self/mutually recursive,
+     * i.e. reachable from themselves through a `lazyRef` back-edge. Adapters use
+     * this to break the TypeScript inference cycle (annotated const + hoisted
+     * structural type for zod/valibot; `this`/degrade for arktype). Absent or
+     * empty means no recursion.
+     */
+    recursive?: Set<string>;
 }
 
 /** Signals to an adapter what it must import to render the current output. */
@@ -121,12 +129,32 @@ interface AdapterUsage {
 interface RenderContext {
     /** Hoisted named schemas being emitted alongside the root. */
     named: Map<string, SchemaNode>;
+    /**
+     * Name of the hoisted schema currently being rendered, when rendering a named
+     * schema's own body. Lets an adapter express a self-reference specially (e.g.
+     * arktype's `this` keyword). Absent when rendering the root.
+     */
+    selfName?: string;
 }
 interface RenderedModule {
     /** Root schema source text, e.g. `"z.object({ email: z.string().email() })"`. */
     schemaText: string;
     /** name → schema source text, hoisted above the parent. */
     namedNestedSchemas: Map<string, string>;
+    /**
+     * name → hoisted TS `type` alias *body* for a recursive schema (e.g.
+     * `"{ field?: string; and?: Array<ColumnFilter> }"`), emitted as
+     * `type <TypeName> = <body>;` above the const. The alias name is derived from
+     * the schema name. Absent for adapters/schemas that don't need it (arktype,
+     * non-recursive schemas).
+     */
+    namedTypeAliases?: Map<string, string>;
+    /**
+     * name → const type annotation for a recursive schema (e.g.
+     * `"z.ZodType<ColumnFilter>"`), emitted as `const <name>: <annotation> = ...`
+     * to break the implicit-any self-reference cycle.
+     */
+    namedAnnotations?: Map<string, string>;
     warnings: string[];
 }
 /**
@@ -137,6 +165,12 @@ interface RenderedModule {
 interface ValidationAdapter {
     /** 'zod' | 'valibot' | 'arktype'. */
     name: string;
+    /**
+     * When `true`, the emitter may pass raw zod source from `defineContract`
+     * (`bodyZodText`/`bodyZodRef`) through verbatim and emit a `z` import. Only the
+     * zod adapter sets this; any other adapter skips raw-zod sources with a warning.
+     */
+    acceptsRawZodSource?: boolean;
     /** Import lines required for any rendered text (e.g. `import { z } from 'zod'`). */
     importStatements(usage: AdapterUsage): string[];
     /** Render a single node to this lib's source text. */
@@ -150,14 +184,14 @@ interface ValidationAdapter {
 /** A built-in adapter name or a custom adapter instance. */
 type ValidationOption = 'zod' | 'valibot' | 'arktype' | ValidationAdapter;
 /**
- * Resolve a `validation` config value to a {@link ValidationAdapter}. `'zod'` is
- * bundled in core; the valibot/arktype adapters ship as their own packages — import
- * the adapter instance and pass it directly (it passes through here). A custom
- * adapter object also passes through.
+ * Resolve a `validation` config value to a {@link ValidationAdapter}. No adapter is
+ * bundled in core — the zod/valibot/arktype adapters ship as their own packages.
+ * Import the adapter instance and pass it directly (it passes through here). A
+ * custom adapter object also passes through.
  *
  * @example
- * import { valibotAdapter } from '@dudousxd/nestjs-codegen-valibot';
- * defineConfig({ validation: valibotAdapter });
+ * import { zodAdapter } from '@dudousxd/nestjs-codegen-zod';
+ * defineConfig({ validation: zodAdapter });
  */
 declare function resolveAdapter(option: ValidationOption): ValidationAdapter;
 
@@ -166,15 +200,15 @@ interface UserConfig {
      * Codegen extensions, applied in order. Each may augment the route IR
      * (`transformRoutes`), contribute extra output files (`emitFiles`), and — once a
      * client layer is active — shape `api.ts`. Registered explicitly, e.g.
-     * `extensions: [nestjsInertiaCodegen(), tanstackQuery()]`.
+     * `extensions: [clientCodegen(), tanstackQuery()]`.
      */
     extensions?: CodegenExtension[];
     /**
-     * Validation library for emitted `forms.ts` schemas. `'zod'` (bundled, default)
-     * or an imported adapter instance (`valibotAdapter`/`arktypeAdapter`).
-     * @default 'zod'
+     * Validation library for emitted `forms.ts` schemas. Required — pass an imported
+     * adapter instance, e.g. `zodAdapter` from `@dudousxd/nestjs-codegen-zod`, or
+     * `valibotAdapter`/`arktypeAdapter` from their packages.
      */
-    validation?: ValidationOption;
+    validation: ValidationOption;
     /** Inertia page discovery. Omit when you don't use Inertia. */
     pages?: {
         glob: string;
@@ -202,11 +236,11 @@ interface UserConfig {
      * This lets users configure baseUrl, headers, plugins (e.g. superjson).
      *
      * @example
-     * // nestjs-inertia.config.ts
+     * // nestjs-codegen.config.ts
      * fetcher: { importPath: '~/lib/api' }
      *
-     * // inertia/lib/api.ts
-     * import { createFetcher } from '@dudousxd/nestjs-inertia-client';
+     * // src/lib/api.ts
+     * import { createFetcher } from '@dudousxd/nestjs-client';
      * export const fetcher = createFetcher({ baseUrl: '/api' });
      */
     fetcher?: {
@@ -402,15 +436,11 @@ interface CodegenExtension {
      */
     apiMembers?(leaf: LeafModel, ctx: ExtensionContext): Record<string, string> | undefined;
     /**
-     * Claims **how** a single endpoint issues its request. When unset by every extension,
-     * the host falls back to the neutral fetcher transport. Example: the Inertia extension
-     * routes mutations through the Inertia router while GETs stay fetcher-typed.
-     */
-    apiTransport?: ApiTransport;
-    /**
-     * Claims **what** a leaf returns. When unset, a leaf is a bare callable returning a
-     * `Promise`. Example: the TanStack extension wraps each leaf into a handle exposing
-     * `{ fetch, queryKey, queryOptions | mutationOptions }`.
+     * Claims **what** a leaf returns and **how** it issues its request. At most one extension
+     * may claim it. When unset, a leaf is a bare awaitable callable backed by the neutral
+     * fetcher. Example: the TanStack extension wraps each leaf into a handle exposing
+     * `{ fetch, queryKey, queryOptions | mutationOptions }`, composing with the fetcher
+     * request the host passes in.
      */
     apiClientLayer?: ApiClientLayer;
 }
@@ -458,40 +488,30 @@ interface RequestModel {
     optsExpr: string;
     /** Response type access, e.g. `ApiRouter['users']['show']['response']`. */
     responseType: string;
-    /** Body type access, e.g. `ApiRouter['users']['create']['body']` (for mutation layers). */
-    bodyType: string;
     /** Stable query-key expression, e.g. `["users.show", input] as const`. */
     queryKeyExpr: string;
 }
 /**
- * Per-leaf model passed through the api.ts pipeline: transport → layer → member
- * contributors → render. `requestExpr` is set by the transport; `members`, when present,
- * flips the leaf from a bare callable to a handle.
+ * Per-leaf model passed through the api.ts pipeline: layer → member contributors → render.
+ * `requestExpr` is the host's neutral fetcher request; `members`, when present, flips the
+ * leaf from a bare callable to a handle.
  */
 interface LeafModel {
     route: RouteDescriptor;
     request: RequestModel;
-    /** The expression that issues the request (set by the transport, default = fetcher). */
+    /** The expression that issues the request (the host's neutral fetcher call). */
     requestExpr: string;
     /** When present, the leaf renders as a handle exposing these members (ordered). */
     members?: Record<string, string>;
 }
 /**
- * Top-level `api.ts` imports + helpers a transport or layer depends on. Functions of the
- * context so they can be route-aware (e.g. only import `mutationOptions` when a mutation
- * exists). Imports are deduped by the host across all extensions.
+ * Top-level `api.ts` imports a client layer depends on. A function of the context so it can
+ * be route-aware (e.g. only import `mutationOptions` when a mutation exists). Imports are
+ * deduped by the host across all extensions.
  */
 interface ApiModuleDeps {
     /** Raw import lines (e.g. `import { queryOptions as _q } from '@tanstack/react-query';`). */
     imports?(ctx: ExtensionContext): string[];
-    /** Module-level helper declarations the rendered expressions depend on. */
-    helpers?(ctx: ExtensionContext): string[];
-}
-/** Single-slot: decides how an endpoint issues its request. */
-interface ApiTransport extends ApiModuleDeps {
-    name: string;
-    /** Render the expression that issues this endpoint's request (e.g. `fetcher.get<Res>(url, opts)`). */
-    renderRequest(leaf: LeafModel, ctx: ExtensionContext): string;
 }
 /** Single-slot: decides what a leaf returns (the handle members). */
 interface ApiClientLayer extends ApiModuleDeps {
@@ -503,7 +523,30 @@ interface ApiClientLayer extends ApiModuleDeps {
      */
     buildMembers(requestExpr: string, leaf: LeafModel, ctx: ExtensionContext): Record<string, string>;
 }
+/**
+ * The four request-shape flags derived from a route's method + contract. Computed in ONE
+ * place ({@link requestShape}) and read by both the host emitter and client-layer
+ * extensions, so the "filter-search POST counts as a read" rule is encoded exactly once.
+ */
+interface RequestShape {
+    /** The route is a `GET`. */
+    isGet: boolean;
+    /** True for reads: a GET, or a filter-search route (carries `filterFields`) even when POST.
+     *  Client layers use this (not `isGet`) to decide query vs mutation helpers. */
+    isQuery: boolean;
+    /** The route carries a body contract (a mutation payload). */
+    hasBody: boolean;
+    /** The route can take a query string — always for GET; a mutation may too (query + body). */
+    hasQuery: boolean;
+}
+/**
+ * Compute the {@link RequestShape} flags for a route from its method and contract. This is
+ * the SINGLE source of truth for these flags — `buildRequestModel`, the TanStack layer's
+ * `imports()`, and any other reader must call this rather than re-deriving. The
+ * "filter-search POST counts as a read" rule lives here and nowhere else.
+ */
+declare function requestShape(route: RouteDescriptor): RequestShape;
 /** Identity helper for authoring extensions with full type inference. */
 declare function defineExtension(ext: CodegenExtension): CodegenExtension;
 
-export { type AdapterUsage as A, type CodegenExtension as C, type ExtensionContext as E, type LeafModel as L, type NumberCheck as N, type ResolvedConfig as R, type SchemaModule as S, type TypeRef as T, type UserConfig as U, type ValidationAdapter as V, type RouteDescriptor as a, type ResolvedFormsConfig as b, type ContractDescriptor as c, type ContractSource as d, type ControllerRef as e, type RenderContext as f, type RenderedModule as g, type SchemaNode as h, type ScopeConfig as i, type StringCheck as j, type ValidationOption as k, type ApiClientLayer as l, type ApiHeaderContribution as m, type ApiModuleDeps as n, type ApiTransport as o, type EmittedFile as p, type RequestModel as q, resolveAdapter as r, defineExtension as s };
+export { type AdapterUsage as A, type CodegenExtension as C, type ExtensionContext as E, type LeafModel as L, type NumberCheck as N, type ResolvedConfig as R, type SchemaNode as S, type TypeRef as T, type UserConfig as U, type ValidationAdapter as V, type RouteDescriptor as a, type SchemaModule as b, type ResolvedFormsConfig as c, type ContractDescriptor as d, type ContractSource as e, type ControllerRef as f, type RenderContext as g, type RenderedModule as h, type ScopeConfig as i, type StringCheck as j, type ValidationOption as k, type ApiClientLayer as l, type ApiHeaderContribution as m, type ApiModuleDeps as n, type EmittedFile as o, type RequestModel as p, type RequestShape as q, resolveAdapter as r, defineExtension as s, requestShape as t };