@dudousxd/nestjs-codegen 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-codegen",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DavideCarvalho/nestjs-codegen.git",
@@ -56,7 +56,8 @@
     "dist",
     "bin",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "skills"
   ],
   "dependencies": {
     "cac": "6.7.14",
@@ -92,6 +93,9 @@
   "engines": {
     "node": ">=20"
   },
+  "keywords": [
+    "tanstack-intent"
+  ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run",

package/skills/codegen-serialization-output/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: codegen-serialization-output
+description: >-
+  Understand what @dudousxd/nestjs-codegen emits and how the serialization seam shapes response
+  types. Covers the generated routes.ts (ROUTES, RouteName, RouteParams, the route() helper, @As
+  name overrides), api.ts (createApi factory), and forms.ts (validation schemas), plus the
+  serialization:'json'|'superjson' config. In 'json' (default) every response type is wrapped in
+  Jsonify<...> (Date->string, bigint->never, methods dropped); 'superjson' emits the raw controller
+  return type and MUST be paired with the /superjson runtime. Use when a Date arrives as a string,
+  when choosing json vs superjson, or when wiring route() and the generated outputs.
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-codegen"
+  library_version: 0.8.0
+  framework: nestjs
+---
+
+# Generated output & serialization
+
+A codegen run writes typed artifacts into `codegen.outDir`. The two that matter for every consumer
+are `routes.ts` (typed URLs) and `api.ts` (the client factory); `forms.ts` carries validation
+schemas. How response types are shaped depends on the `serialization` config.
+
+## Setup
+
+With the module wired (see the `codegen-setup` skill), a run emits e.g. `src/generated/routes.ts`,
+`src/generated/api.ts`, and `src/generated/forms.ts`. Consume them like this:
+
+```ts title="src/lib/api.ts"
+import { createApi } from '../generated/api';
+import { createFetcher } from '@dudousxd/nestjs-client';
+import { route } from '../generated/routes';
+
+export const api = createApi(createFetcher({ baseUrl: '/api' }));
+
+route('users.show', { id: '42' });            // → '/users/42'
+route('users.list', undefined, { page: 2 });  // → '/users?page=2'
+```
+
+## Core patterns
+
+### 1. routes.ts is the typed URL source of truth
+
+`routes.ts` exports a `ROUTES` map, a `RouteName` union, `RouteParams<K>`, and a runtime `route()`
+helper that interpolates params and appends a query string:
+
+```ts title="src/generated/routes.ts (emitted)"
+export const ROUTES = {
+  'users.list': '/users',
+  'users.show': '/users/:id',
+} as const;
+export type RouteName = 'users.list' | 'users.show';
+```
+
+Route names are `<controllerSegment>.<method>` (e.g. `UsersController#list` → `users.list`). Override
+either segment with `@As('…')` at the class or method level. A wrong/unknown route name is a type
+error; a missing required param throws at runtime.
+Source: `apps/docs/content/docs/client/routes.mdx`, `packages/core/src/emit/emit-routes.ts`,
+`packages/core/src/discovery/contracts-fast.ts` (`getDecorator('As')`).
+
+### 2. api.ts is a factory you inject the fetcher into
+
+`api.ts` exports `createApi(fetcher)` and an `Api` type — never a hardcoded transport. You build the
+client once with your fetcher; each leaf is an awaitable, fully-typed handle:
+
+```ts
+const users = await api.users.list();                 // typed response
+const user  = await api.users.show({ params: { id } });
+const made  = await api.users.create({ body });        // body typed from the DTO
+```
+
+Source: `apps/docs/content/docs/client/api-client.mdx`, `packages/core/src/emit/emit-api.ts`.
+
+### 3. serialization decides the response type shape
+
+`serialization` (config key, default `'json'`) controls whether the emitted `response` type models
+the JSON wire shape or the raw server type:
+
+```ts title="nestjs-codegen.config.ts"
+export default defineConfig({
+  // ...
+  serialization: 'json',      // default: wrap responses in Jsonify<...>
+  // serialization: 'superjson', // emit raw controller return types (revived at runtime)
+});
+```
+
+`'json'` wraps every `response` in the type-only `Jsonify<...>` from `@dudousxd/nestjs-client`:
+`Date` (and anything with `toJSON()`) → its serialized shape, arrays/objects recurse, non-serializable
+props are dropped, `bigint` → `never`. It's a compile-time transform with no runtime cost. `body`,
+`query`, `params`, and `error` are emitted as-is.
+Source: `packages/core/src/config/types.ts` (`serialization`), `apps/docs/content/docs/client/api-client.mdx`.
+
+## Common mistakes
+
+### Treating a json-mode response as a runtime Date
+
+```ts
+// ❌ Wrong — controller returns { createdAt: Date }, but under serialization:'json' the wire is JSON
+const u = await api.users.show({ params: { id } });
+u.createdAt.getFullYear(); // type error: createdAt is `string` (Jsonify maps Date -> string)
+```
+
+```ts
+// ✅ Correct — it's the ISO string the server actually sent
+const u = await api.users.show({ params: { id } });
+new Date(u.createdAt).getFullYear();
+```
+
+`JSON.stringify(new Date())` produces an ISO string, so `Jsonify` types `createdAt` as `string` to
+stop the type from lying about the wire.
+Source: `apps/docs/content/docs/client/api-client.mdx` ("Response types & serialization").
+
+### Flipping serialization:'superjson' without the runtime
+
+```ts
+// ❌ Wrong — config emits raw Date types, but the client still parses plain JSON → values are strings
+defineConfig({ serialization: 'superjson' });
+// (no /superjson fetcher options, no SuperjsonInterceptor on the server)
+```
+
+```ts
+// ✅ Correct — pair the config with the runtime that revives the types (see nestjs-client-runtime)
+import { superjsonFetcherOptions } from '@dudousxd/nestjs-client/superjson';
+createApi(createFetcher({ baseUrl: '/api', ...superjsonFetcherOptions() }));
+// + register SuperjsonInterceptor on the server
+```
+
+`serialization:'superjson'` only turns OFF compile-time `Jsonify` wrapping; the actual revival of
+`Date`/`Map`/`Set`/`BigInt` happens at runtime via the `/superjson` subpath and the server
+interceptor. Without both, the types claim `Date` but the value is still a string.
+Source: `apps/docs/content/docs/client/fetcher.mdx` ("superjson runtime"), `packages/client/src/superjson/index.ts`.
+
+### Not gating generated drift in CI
+
+```bash
+# ❌ Wrong — generate but never check, so a stale committed client silently ships
+npx nestjs-codegen codegen
+```
+
+```bash
+# ✅ Correct — fail the build when the committed artifacts are stale
+npx nestjs-codegen codegen
+git diff --exit-code src/generated
+```
+
+The dev watcher is skipped in production, so the artifacts you ship are whatever is committed —
+gate them or they drift from your routes.
+Source: `apps/docs/content/docs/getting-started.mdx` ("Generate in CI").

package/skills/codegen-setup/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: codegen-setup
+description: >-
+  Set up @dudousxd/nestjs-codegen in a NestJS app. Wire NestjsCodegenModule.forRoot from
+  @dudousxd/nestjs-codegen/nest with contracts.glob + codegen.outDir + a validation ADAPTER
+  INSTANCE (zodAdapter from @dudousxd/nestjs-codegen-zod, or valibotAdapter/arktypeAdapter).
+  Author one defineConfig nestjs-codegen.config.ts as the single source of truth and import it into
+  forRoot(); run the nestjs-codegen codegen / init / doctor CLI as a CI drift gate. Covers the
+  boot-time watcher (skipped when NODE_ENV=production), the enabled/cwd module fields, and why a
+  bare validation:'zod' string throws ConfigError. Use for install, wiring, config, CI generation.
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-codegen"
+  library_version: 0.8.0
+  framework: nestjs
+---
+
+# nestjs-codegen setup
+
+`@dudousxd/nestjs-codegen` discovers your NestJS controllers/contracts/DTOs and emits a typed
+client (`routes.ts`, `api.ts`, `forms.ts`) into an output dir. In dev the `NestjsCodegenModule`
+runs a watcher with your app; in CI the `nestjs-codegen` CLI does a one-shot, watch-free run.
+
+## Setup
+
+Install the codegen, the runtime the generated client imports from, and a validation adapter:
+
+```bash
+pnpm add -D @dudousxd/nestjs-codegen @dudousxd/nestjs-codegen-zod
+pnpm add @dudousxd/nestjs-client
+```
+
+Author one config file with `defineConfig` — this is the single source of truth the CLI loads and
+the module reuses:
+
+```ts title="nestjs-codegen.config.ts"
+import { defineConfig } from '@dudousxd/nestjs-codegen';
+import { zodAdapter } from '@dudousxd/nestjs-codegen-zod';
+
+export default defineConfig({
+  contracts: { glob: 'src/**/*.controller.ts' }, // controllers to scan for routes + contracts
+  codegen: { outDir: 'src/generated' },           // where routes.ts / api.ts / forms.ts land
+  validation: zodAdapter,                          // an ADAPTER INSTANCE, not the string 'zod'
+});
+```
+
+Wire the module into your root module and import that config so dev + CI never drift:
+
+```ts title="src/app.module.ts"
+import { Module } from '@nestjs/common';
+import { NestjsCodegenModule } from '@dudousxd/nestjs-codegen/nest';
+import codegenConfig from '../nestjs-codegen.config';
+
+@Module({
+  imports: [NestjsCodegenModule.forRoot(codegenConfig)],
+})
+export class AppModule {}
+```
+
+Run the app as usual (`nest start --watch`): the watcher does an initial generate, then regenerates
+as controllers/DTOs change. `@nestjs/common` is an optional peer — your Nest app already has it.
+
+## Core patterns
+
+### 1. forRoot() options ARE the config (plus two module-only fields)
+
+`CodegenModuleOptions` is `UserConfig` plus `enabled` and `cwd`. You can inline the options instead
+of importing a file, but a shared `defineConfig` file keeps the CLI in sync:
+
+```ts
+NestjsCodegenModule.forRoot({
+  contracts: { glob: 'src/**/*.controller.ts' },
+  codegen: { outDir: 'src/generated' },
+  validation: zodAdapter,
+  enabled: true,           // module-only: force the watcher on (see pattern 3)
+  cwd: process.cwd(),      // module-only: project root for glob/outDir resolution
+});
+```
+
+Source: `packages/core/src/nest/module.ts` (`CodegenModuleOptions`), `packages/core/src/config/types.ts`.
+
+### 2. The CLI is your CI drift gate
+
+The `nestjs-codegen` bin reads `nestjs-codegen.config.ts`. In CI, regenerate and fail on any diff so
+a stale committed client can never ship:
+
+```bash
+npx nestjs-codegen codegen           # one-shot generate
+npx nestjs-codegen codegen --watch   # same watcher, standalone
+npx nestjs-codegen init              # scaffold a starter config
+npx nestjs-codegen doctor            # diagnose missing config / unscanned controllers / drift
+git diff --exit-code src/generated   # non-zero (fails CI) if the client is stale
+```
+
+Source: `apps/docs/content/docs/cli.mdx`, `packages/core/bin/nestjs-codegen.js`.
+
+### 3. The watcher is a dev/CI concern — off in production by default
+
+`shouldRun` returns `false` when `process.env.NODE_ENV === 'production'` unless you set `enabled`
+explicitly. Codegen is a build step, not a runtime dependency, so leave it default and let prod skip
+it; only set `enabled: false` to turn it off everywhere or `enabled: true` to force it.
+
+Source: `packages/core/src/nest/module.ts` (`shouldRun`).
+
+## Common mistakes
+
+### Passing the validation library as a string
+
+```ts
+// ❌ Wrong — throws ConfigError at config-resolve time
+defineConfig({ validation: 'zod' });
+```
+
+```ts
+// ✅ Correct — import and pass the adapter instance
+import { zodAdapter } from '@dudousxd/nestjs-codegen-zod';
+defineConfig({ validation: zodAdapter });
+```
+
+No adapter is bundled in core; `resolveAdapter` throws a `ConfigError` for any string and tells you
+to install the package and pass the instance. (Some older docs show `validation: 'zod'` — the source
+is authoritative.) For valibot/arktype, import `valibotAdapter` / `arktypeAdapter` from their
+packages.
+Source: `packages/core/src/adapters/registry.ts` (`resolveAdapter`).
+
+### Maintaining a second, divergent config for the CLI
+
+```ts
+// ❌ Wrong — forRoot() inlines one set of options, the CLI reads a different file → drift
+NestjsCodegenModule.forRoot({ contracts: { glob: 'src/**/*.controller.ts' }, codegen: { outDir: 'gen' }, validation: zodAdapter });
+// nestjs-codegen.config.ts says outDir: 'src/generated' → CI generates to a different place
+```
+
+```ts
+// ✅ Correct — one defineConfig file, imported into forRoot()
+import codegenConfig from '../nestjs-codegen.config';
+NestjsCodegenModule.forRoot(codegenConfig);
+```
+
+The module (dev) and the CLI (CI) must resolve the same options or the CI drift check compares
+against artifacts the dev watcher never wrote.
+Source: `apps/docs/content/docs/getting-started.mdx` ("single source of truth").
+
+### Expecting the watcher to run in your production container
+
+```ts
+// ❌ Wrong — assuming forRoot() regenerates the client in prod
+NestjsCodegenModule.forRoot(codegenConfig); // does nothing when NODE_ENV=production
+```
+
+```ts
+// ✅ Correct — generate in CI before deploy; commit the artifacts
+// CI step:  npx nestjs-codegen codegen && git diff --exit-code src/generated
+NestjsCodegenModule.forRoot(codegenConfig); // dev-only watcher; prod ships committed files
+```
+
+The boot-time watcher is intentionally skipped in production; the generated files are meant to be
+generated in CI and committed, not produced at runtime.
+Source: `packages/core/src/nest/module.ts` (`onApplicationBootstrap` guards on `shouldRun`).