@dudousxd/nestjs-codegen 0.2.0

package/dist/index-BwIRjOQA.d.ts

@@ -0,0 +1,509 @@
+import { Project } from 'ts-morph';
+
+/**
+ * Neutral validation IR. Produced by `dto-to-ir` (class-validator AST → IR) and,
+ * later, by parsing `defineContract` zod schemas back into the same shape. A
+ * `ValidationAdapter` renders a `SchemaNode` to source text in a concrete lib
+ * (zod today; valibot/arktype later).
+ *
+ * Design note: a few nodes (`raw`, `annotated`, message-carrying checks) preserve
+ * source-level detail so the zod adapter can reproduce the previous emitter's
+ * output byte-for-byte. Adapters for other libs read the semantic fields and may
+ * normalize incidental formatting (quote style, comment wording).
+ */
+/** A `{ message: '...' }` options arg, stored as the verbatim source text (e.g. `'Bad email'`). */
+type MessageRaw = string;
+type StringCheck = {
+    check: 'email';
+    messageRaw?: MessageRaw;
+} | {
+    check: 'url';
+    messageRaw?: MessageRaw;
+} | {
+    check: 'uuid';
+    messageRaw?: MessageRaw;
+} | {
+    check: 'regex';
+    pattern: string;
+} | {
+    check: 'min';
+    value: string;
+} | {
+    check: 'max';
+    value: string;
+};
+type NumberCheck = {
+    check: 'int';
+} | {
+    check: 'min';
+    value: string;
+} | {
+    check: 'max';
+    value: string;
+} | {
+    check: 'positive';
+} | {
+    check: 'negative';
+};
+type SchemaNode = {
+    kind: 'string';
+    checks: StringCheck[];
+} | {
+    kind: 'number';
+    checks: NumberCheck[];
+} | {
+    kind: 'boolean';
+} | {
+    kind: 'date';
+}
+/** Unknown/opaque value. `note`, when present, becomes a trailing comment
+ * (e.g. recursion degradation or unresolvable-enum fallback reasons). Kept
+ * neutral so each adapter renders its own lib's `unknown` + comment. */
+ | {
+    kind: 'unknown';
+    note?: string;
+} | {
+    kind: 'instanceof';
+    ctor: string;
+}
+/** Members are verbatim literal source texts (quote style preserved). */
+ | {
+    kind: 'enum';
+    literals: string[];
+} | {
+    kind: 'literal';
+    raw: string;
+} | {
+    kind: 'union';
+    options: SchemaNode[];
+} | {
+    kind: 'object';
+    fields: Array<{
+        key: string;
+        value: SchemaNode;
+    }>;
+    passthrough: boolean;
+} | {
+    kind: 'array';
+    element: SchemaNode;
+} | {
+    kind: 'optional';
+    inner: SchemaNode;
+}
+/** Reference to a hoisted named schema (emitted in `SchemaModule.named`). */
+ | {
+    kind: 'ref';
+    name: string;
+}
+/** Lazy reference to a hoisted named schema (recursion site). */
+ | {
+    kind: 'lazyRef';
+    name: string;
+}
+/** Wraps a node with trailing comments for unmappable decorators (by name). */
+ | {
+    kind: 'annotated';
+    inner: SchemaNode;
+    unmappable: string[];
+};
+/** A root schema plus hoisted named (nested/recursive) schemas. */
+interface SchemaModule {
+    root: SchemaNode;
+    named: Map<string, SchemaNode>;
+    warnings: string[];
+}
+
+/** Signals to an adapter what it must import to render the current output. */
+interface AdapterUsage {
+    /** Whether any schema is rendered at all (drives import emission). */
+    used: boolean;
+}
+interface RenderContext {
+    /** Hoisted named schemas being emitted alongside the root. */
+    named: Map<string, SchemaNode>;
+}
+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>;
+    warnings: string[];
+}
+/**
+ * Renders the neutral {@link SchemaNode} IR into a concrete validation lib's
+ * source text. Designed around the Standard Schema spec: a new lib is added by
+ * implementing `render`/`renderModule` + `importStatements`.
+ */
+interface ValidationAdapter {
+    /** 'zod' | 'valibot' | 'arktype'. */
+    name: string;
+    /** 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. */
+    render(node: SchemaNode, ctx: RenderContext): string;
+    /** Render a full module (root + hoisted named) to text. */
+    renderModule(mod: SchemaModule): RenderedModule;
+    /** TS expression for the inferred type of a schema const, e.g. `z.infer<typeof X>`. */
+    inferType(schemaConst: string): string;
+}
+
+/** 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.
+ *
+ * @example
+ * import { valibotAdapter } from '@dudousxd/nestjs-codegen-valibot';
+ * defineConfig({ validation: valibotAdapter });
+ */
+declare function resolveAdapter(option: ValidationOption): ValidationAdapter;
+
+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?: CodegenExtension[];
+    /**
+     * Validation library for emitted `forms.ts` schemas. `'zod'` (bundled, default)
+     * or an imported adapter instance (`valibotAdapter`/`arktypeAdapter`).
+     * @default 'zod'
+     */
+    validation?: ValidationOption;
+    /** Inertia page discovery. Omit when you don't use Inertia. */
+    pages?: {
+        glob: string;
+        propsExport?: string;
+        componentNameStrategy?: 'relative-no-ext' | 'kebab' | ((path: string) => string);
+    };
+    contracts?: {
+        /** Glob pattern (relative to cwd) for controller files. Default: `'src/**\/\*.controller.ts'` */
+        glob?: string;
+        /** Debounce delay in ms before re-running route discovery. Default: `500` */
+        debounceMs?: number;
+    };
+    scopes?: Record<string, ScopeConfig>;
+    codegen?: {
+        outDir?: string;
+        cwd?: string;
+    };
+    app?: {
+        moduleEntry: string;
+        tsconfig?: string;
+    } | null;
+    /**
+     * Custom fetcher configuration. When `importPath` is set, the codegen
+     * imports `fetcher` from that path instead of generating `createFetcher()`.
+     * This lets users configure baseUrl, headers, plugins (e.g. superjson).
+     *
+     * @example
+     * // nestjs-inertia.config.ts
+     * fetcher: { importPath: '~/lib/api' }
+     *
+     * // inertia/lib/api.ts
+     * import { createFetcher } from '@dudousxd/nestjs-inertia-client';
+     * export const fetcher = createFetcher({ baseUrl: '/api' });
+     */
+    fetcher?: {
+        importPath: string;
+    };
+    /**
+     * Typed-form schema emit (`forms.ts`). Re-exports / translates contract and
+     * class-validator-decorated DTO schemas into zod schemas for client-side
+     * validation.
+     */
+    forms?: {
+        /** Emit `forms.ts`. Default: `true` (when ≥1 validatable body exists). */
+        enabled?: boolean;
+        /** DTO glob to watch for form-schema regen. Default: `'src/**\/\*.dto.ts'`. */
+        watch?: string;
+        /** Module specifier for the `z` import. Default: `'zod'`. */
+        zodImport?: string;
+    };
+}
+interface ScopeConfig {
+    glob: string;
+    prefix?: string;
+}
+interface ResolvedPagesConfig {
+    glob: string;
+    propsExport: string;
+    componentNameStrategy: 'relative-no-ext' | 'kebab' | ((path: string) => string);
+}
+interface ResolvedContractsConfig {
+    /** Glob pattern relative to `codegen.cwd` for watching controller files. */
+    glob: string;
+    /** Debounce delay in ms before re-running route discovery. */
+    debounceMs: number;
+}
+interface ResolvedCodegenConfig {
+    outDir: string;
+    cwd: string;
+}
+interface ResolvedAppConfig {
+    moduleEntry: string;
+    tsconfig: string | null;
+}
+interface ResolvedFormsConfig {
+    enabled: boolean;
+    watch: string;
+    zodImport: string;
+}
+interface ResolvedConfig {
+    extensions: CodegenExtension[];
+    validation: ValidationAdapter;
+    pages: ResolvedPagesConfig | null;
+    contracts: ResolvedContractsConfig;
+    scopes: Record<string, ScopeConfig>;
+    codegen: ResolvedCodegenConfig;
+    app: ResolvedAppConfig | null;
+    fetcher: {
+        importPath: string;
+    } | null;
+    forms: ResolvedFormsConfig;
+}
+
+interface TypeRef {
+    name: string;
+    filePath: string;
+    isArray?: boolean;
+}
+type FieldTypeKind = 'string' | 'number' | 'boolean' | 'date' | 'json' | 'unknown';
+/**
+ * A classified filter field.
+ *
+ * INVARIANT — `typeRef` precedence: when `typeRef` is set it is the SOLE source
+ * of truth for the emitted type; `kind`/`enumValues`/`numericEnum` are then only
+ * a best-effort fallback recorded for non-emit consumers (tests/introspection),
+ * NOT something the emitter reads. A discriminated union would make "carries both
+ * a ref AND a literal kind" unrepresentable, but the producers and tests read
+ * `kind` and `typeRef` off the same object freely, so the union ripples too
+ * widely and fights the existing nullable handling. Instead this invariant is
+ * concentrated in the single normalizing constructor {@link toFilterFieldType}
+ * (the only place a `FilterFieldType` is built from a classification) and honored
+ * by the single emit-side reader (`emitFieldTypesLiteral`). Do not branch on
+ * `typeRef` vs `kind` anywhere else.
+ */
+interface FilterFieldType {
+    /** Field name, e.g. 'age' or 'tasks.id' (dot-notation for relations). */
+    name: string;
+    kind: FieldTypeKind;
+    /** String/number-literal union members (enums), if any. */
+    enumValues?: string[];
+    /** Whether the field's TS type includes null/undefined. */
+    nullable?: boolean;
+    /** True when enumValues are numeric literals (emit unquoted). */
+    numericEnum?: boolean;
+    /**
+     * When the field's type is a named enum / type alias / interface inferred from
+     * a `@FilterFor` method parameter, the importable reference to that symbol.
+     * The emitter references `typeRef.name` in the type map M and emits a real
+     * `import type { <name> } from '<path>'` at the top of the generated file.
+     * Takes precedence over `kind`/`enumValues` when present (see invariant above).
+     */
+    typeRef?: TypeRef;
+}
+interface ContractSource {
+    query: string | null;
+    body: string | null;
+    response: string;
+    queryRef?: TypeRef | null;
+    bodyRef?: TypeRef | null;
+    responseRef?: TypeRef | null;
+    filterFields?: string[] | null;
+    filterFieldTypes?: FilterFieldType[] | null;
+    filterSource?: 'body' | 'query' | null;
+    /** Raw zod source for the body schema (Path A inline, or Path B synthesized). */
+    bodyZodText?: string | null;
+    /** Importable named schema to re-export for the body (Path A). */
+    bodyZodRef?: TypeRef | null;
+    /** Raw zod source for the query schema (Path A inline, or Path B synthesized). */
+    queryZodText?: string | null;
+    /** Importable named schema to re-export for the query (Path A). */
+    queryZodRef?: TypeRef | null;
+    /** Hoisted nested schemas (name → zod text) referenced by body/query (Path B). */
+    formNestedSchemas?: Record<string, string> | null;
+    /** Unmappable-decorator warnings surfaced to console + a header comment. */
+    formWarnings?: string[];
+    /**
+     * Neutral validation IR for the body, when synthesized from a class-validator
+     * DTO. Lets `emit-forms` render via the configured adapter (valibot/arktype),
+     * not only zod. `null`/absent for `defineContract` (hand-written zod) bodies.
+     */
+    bodySchema?: SchemaModule | null;
+    /** Neutral validation IR for the query (class-validator DTO only). */
+    querySchema?: SchemaModule | null;
+}
+interface ContractDescriptor {
+    contractSource: ContractSource;
+}
+interface ControllerRef {
+    className: string;
+    methodName: string;
+    filePath: string;
+}
+interface RouteDescriptor {
+    method: string;
+    path: string;
+    name: string;
+    params: Array<{
+        name: string;
+        source: 'path' | 'query' | 'body' | 'header';
+    }>;
+    contract?: ContractDescriptor;
+    controllerRef?: ControllerRef;
+}
+
+/**
+ * The published, versioned extension contract for `@dudousxd/nestjs-codegen`.
+ *
+ * Extensions are **build-time** objects (usually returned by a factory so they can take
+ * options) registered explicitly via `forRoot({ extensions: [...] })`. The host runs them
+ * around the core discovery → IR → emit pipeline.
+ *
+ * Hooks split into **multi** (every extension runs; results accumulate or chain) and
+ * **single-slot** (at most one extension may claim it — two claimers is a hard error).
+ *
+ * @remarks Semver 0.x — the shape may change until 1.0. Out-of-repo extensions should pin
+ * a compatible `@dudousxd/nestjs-codegen` peer range.
+ */
+interface CodegenExtension {
+    /** Unique id. Used in conflict/collision errors and for deterministic ordering. */
+    name: string;
+    /**
+     * Mutate/augment the route IR before emit. Runs in registration order, chained
+     * (each extension sees the previous one's output). Return the new array, or mutate
+     * in place and return void. Example: the filter extension attaches `filterFields` to
+     * matching routes here.
+     */
+    transformRoutes?(routes: RouteDescriptor[], ctx: ExtensionContext): RouteDescriptor[] | undefined | Promise<RouteDescriptor[] | undefined>;
+    /**
+     * Contribute extra output files (additive). Paths are relative to `outDir`; a path
+     * claimed by two extensions is a hard error. Example: the Inertia extension does its
+     * own page discovery via `ctx.project()` and emits `pages.d.ts` + `components.json`.
+     */
+    emitFiles?(ctx: ExtensionContext): EmittedFile[] | Promise<EmittedFile[]>;
+    /**
+     * Contribute top-level code to `api.ts` (imports + statements). Runs in registration
+     * order; imports are deduped by the host. Example: the Inertia extension adds
+     * `import { router } from '@inertiajs/react'` and the `navigate()` helper.
+     */
+    apiHeader?(ctx: ExtensionContext): ApiHeaderContribution | undefined;
+    /**
+     * Add named members to a **handle** leaf. Only runs when a client layer is active
+     * (i.e. the leaf is a handle, not a bare callable). Member-name collisions across
+     * extensions are a hard error. Example: the filter extension adds `filterQuery` to
+     * leaves whose route carries `filterFields`.
+     */
+    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 }`.
+     */
+    apiClientLayer?: ApiClientLayer;
+}
+/** Shared, read-only context handed to every extension hook. */
+interface ExtensionContext {
+    cwd: string;
+    outDir: string;
+    routes: readonly RouteDescriptor[];
+    config: ResolvedConfig;
+    /** Lazily-created shared ts-morph Project for AST work (pages, custom decorators). */
+    project(): Project;
+}
+/** A file contributed by an extension's `emitFiles` hook. */
+interface EmittedFile {
+    /** Path relative to `outDir`. A collision across extensions throws. */
+    path: string;
+    contents: string;
+}
+/** Top-level `api.ts` contributions from an extension's `apiHeader` hook. */
+interface ApiHeaderContribution {
+    /** Raw import lines (e.g. `import { router } from '@inertiajs/react';`), deduped by the host. */
+    imports?: string[];
+    /** Top-level statements appended after the api factory (e.g. the `navigate()` helper). */
+    statements?: string[];
+}
+/**
+ * The neutral, per-endpoint request model the host builds for each leaf before any
+ * transport/layer runs. Extensions read this to render their output.
+ */
+interface RequestModel {
+    /** Dot-path route name, e.g. `users.show`. */
+    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. */
+    isQuery: boolean;
+    hasParams: boolean;
+    hasBody: boolean;
+    /** Type of the leaf's `input` arg, e.g. `{ params: ...; query?: ... }` or `Record<string, never>`. */
+    inputType: string;
+    /** URL expression, e.g. `route('users.show', input?.params) || '/api/users/:id'`. */
+    urlExpr: string;
+    /** Request-options expression, e.g. `{ query: ... }` or `{ body: input?.body }`. */
+    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.
+ */
+interface LeafModel {
+    route: RouteDescriptor;
+    request: RequestModel;
+    /** The expression that issues the request (set by the transport, default = fetcher). */
+    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.
+ */
+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 {
+    name: string;
+    /**
+     * Given the request expression (from the transport) and the leaf, return the handle's
+     * members as an ordered `name → value` map (value is the expression after `name: `).
+     * Returning members flips the leaf from a bare callable to a handle.
+     */
+    buildMembers(requestExpr: string, leaf: LeafModel, ctx: ExtensionContext): Record<string, string>;
+}
+/** 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 };