From 6e8d99c250c33533dab43417d91d2b8c48e2f743 Mon Sep 17 00:00:00 2001 From: jonaslagoni Date: Sat, 1 Aug 2026 19:51:12 +0000 Subject: [PATCH] chore(release): v0.82.0 --- docs/usage.md | 8 +- mcp-server/lib/resources/bundled-docs.ts | 24 +- package-lock.json | 4 +- package.json | 2 +- website/static/codegen.browser.mjs | 910 +++++++++++++++++++++-- 5 files changed, 877 insertions(+), 71 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 61877f63..91ccf561 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -8,7 +8,7 @@ $ npm install -g @the-codegen-project/cli $ codegen COMMAND running command... $ codegen (--version) -@the-codegen-project/cli/0.81.1 node- +@the-codegen-project/cli/0.82.0 node- $ codegen --help [COMMAND] USAGE $ codegen COMMAND @@ -92,7 +92,7 @@ DESCRIPTION configuration. ``` -_See code: [src/commands/generate.ts](https://github.com/the-codegen-project/cli/blob/v0.81.1/src/commands/generate.ts)_ +_See code: [src/commands/generate.ts](https://github.com/the-codegen-project/cli/blob/v0.82.0/src/commands/generate.ts)_ ## `codegen help [COMMAND]` @@ -167,7 +167,7 @@ DESCRIPTION Initialize The Codegen Project in your project ``` -_See code: [src/commands/init.ts](https://github.com/the-codegen-project/cli/blob/v0.81.1/src/commands/init.ts)_ +_See code: [src/commands/init.ts](https://github.com/the-codegen-project/cli/blob/v0.82.0/src/commands/init.ts)_ ## `codegen telemetry ACTION` @@ -200,7 +200,7 @@ EXAMPLES $ codegen telemetry disable ``` -_See code: [src/commands/telemetry.ts](https://github.com/the-codegen-project/cli/blob/v0.81.1/src/commands/telemetry.ts)_ +_See code: [src/commands/telemetry.ts](https://github.com/the-codegen-project/cli/blob/v0.82.0/src/commands/telemetry.ts)_ ## `codegen version` diff --git a/mcp-server/lib/resources/bundled-docs.ts b/mcp-server/lib/resources/bundled-docs.ts index 79cba8f7..7dd89d1b 100644 --- a/mcp-server/lib/resources/bundled-docs.ts +++ b/mcp-server/lib/resources/bundled-docs.ts @@ -1,7 +1,7 @@ /** * Auto-generated documentation bundle. * DO NOT EDIT - regenerate with: npm run bundle-docs - * Generated at: 2026-07-31T10:00:51.580Z + * Generated at: 2026-08-01T19:51:11.587Z */ export interface DocEntry { @@ -12,7 +12,7 @@ export interface DocEntry { export const docs: Record = { "index": { title: "Documentation", - content: "# Documentation\n\n\n\n\n\n- [Configurations](#configurations)\n- [Getting Started](#getting-started)\n- [Contributing](#contributing)\n- [Usage](#usage)\n- [Generators](#generators)\n- [Architectural Decisions](#architectural-decisions)\n- [Inputs](#inputs)\n- [Protocols](#protocols)\n- [Migrations](#migrations)\n- [Telemetry](#telemetry)\n- [AI Assistants](#ai-assistants)\n\n\n\nThis document gives the overview of all the available documentation for The Codegen Project.\n\n### [Configurations](./configurations.md)\nContains all the information about the how the configuration file works and how it's loaded and in what order.\n\n### [Getting Started](./getting-started/)\nGet started in 5 minutes :fire:\n\n### [Contributing](./contributing.md)\nGet an overview of how to contribute to the project\n\n### [Usage](./usage.md)\nContains all the information about what the CLI can do and how.\n\n### [Generators](./generators/README.md)\nFor all available generators, this document describes what is possible.\n\n### Architectural Decisions\nIf there has been a decision about certain technical solutions it will be marked in the architectural decision document.\n- [TypeScript](./architectural-decisions/typescript.md)\n\n### Inputs\nEach input has its own limitations, corner cases, and features; thus, each has separate documentation.\n- [AsyncAPI](./inputs/asyncapi.md)\n- [OpenAPI](./inputs/openapi.md)\n- [JSON Schema](./inputs/jsonschema.md)\n\n### Protocols\nEach protocol has its own limitations, corner cases, and features; thus, each has separate documentation.\n- [NATS](./protocols/nats.md)\n- [AMQP](./protocols/amqp.md)\n- [Kafka](./protocols/kafka.md)\n- [MQTT](./protocols/mqtt.md)\n- [EventSource](./protocols/eventsource.md)\n- [HTTP Client](./protocols/http_client.md)\n- [WebSocket client and server](./protocols/websocket.md)\n\n### [Migrations](./migrations/README.md)\nGet an overview of how to contribute to the project\n\n### [Telemetry](./telemetry.md)\nGet an overview of how telemetry works for this project\n\n### [AI Assistants](./ai-assistants.md)\nConnect AI assistants like Claude Code, Cursor, and Windsurf to The Codegen Project via MCP (Model Context Protocol) for intelligent code generation assistance.", + content: "# Documentation\n\n\n\n\n\n- [Configurations](#configurations)\n- [Getting Started](#getting-started)\n- [Contributing](#contributing)\n- [Usage](#usage)\n- [Generators](#generators)\n- [Architectural Decisions](#architectural-decisions)\n- [Inputs](#inputs)\n- [Protocols](#protocols)\n- [Migrations](#migrations)\n- [Telemetry](#telemetry)\n- [AI Assistants](#ai-assistants)\n\n\n\nThis document gives the overview of all the available documentation for The Codegen Project.\n\n### [Configurations](./configurations.md)\nContains all the information about the how the configuration file works and how it's loaded and in what order.\n\n### [Getting Started](./getting-started/)\nGet started in 5 minutes :fire:\n\n### [Contributing](./contributing.md)\nGet an overview of how to contribute to the project\n\n### [Usage](./usage.md)\nContains all the information about what the CLI can do and how.\n\n### [Generators](./generators/README.md)\nFor all available generators, this document describes what is possible.\n\n### Architectural Decisions\nIf there has been a decision about certain technical solutions it will be marked in the architectural decision document.\n- [TypeScript](./architectural-decisions/typescript.md)\n\n### Inputs\nEach input has its own limitations, corner cases, and features; thus, each has separate documentation.\n- [AsyncAPI](./inputs/asyncapi.md)\n- [OpenAPI](./inputs/openapi.md)\n- [JSON Schema](./inputs/jsonschema.md)\n\n### Protocols\nEach protocol has its own limitations, corner cases, and features; thus, each has separate documentation.\n- [NATS](./protocols/nats.md)\n- [AMQP](./protocols/amqp.md)\n- [Kafka](./protocols/kafka.md)\n- [MQTT](./protocols/mqtt.md)\n- [EventSource](./protocols/eventsource.md)\n- [HTTP Client](./protocols/http_client.md)\n- [HTTP Server](./protocols/http_server.md)\n- [WebSocket client and server](./protocols/websocket.md)\n\n### [Migrations](./migrations/README.md)\nGet an overview of how to contribute to the project\n\n### [Telemetry](./telemetry.md)\nGet an overview of how telemetry works for this project\n\n### [AI Assistants](./ai-assistants.md)\nConnect AI assistants like Claude Code, Cursor, and Windsurf to The Codegen Project via MCP (Model Context Protocol) for intelligent code generation assistance.", }, "ai-assistants": { title: "AI Assistants", @@ -36,11 +36,11 @@ export const docs: Record = { }, "generators": { title: "Generators", - content: "# Generators\nGenerators, or preset's are the core of **The Codegen Project**, that determines what is generated for your project.\n\nEach language and inputs have specific generators;\n\nAll available generators, across languages and inputs:\n- [`payloads`](./payloads.md)\n- [`parameters`](./parameters.md)\n- [`headers`](./headers.md)\n- [`types`](./types.md)\n- [`channels`](./channels.md)\n- [`client`](./client.md)\n- [`models`](./models.md)\n- [`custom`](./custom.md)\n\n| **Inputs** | [`payloads`](./payloads.md) | [`parameters`](./parameters.md) | [`headers`](./headers.md) | [`types`](./types.md) | [`channels`](./channels.md) | [`client`](./client.md) | [`models`](./models.md) | [`custom`](./custom.md) |\n|---|---|---|---|---|---|---|---|---|\n| AsyncAPI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| OpenAPI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| JSON Schema | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |\n\n> OpenAPI `channels` and `client` generate an HTTP client — see the [`openapi-http-client` example](https://github.com/the-codegen-project/cli/tree/main/examples/openapi-http-client).\n\n| **Languages** | [`payloads`](./payloads.md) | [`parameters`](./parameters.md) | [`headers`](./headers.md) | [`types`](./types.md) | [`channels`](./channels.md) | [`client`](./client.md) | [`models`](./models.md) | [`custom`](./custom.md) |\n|---|---|---|---|---|---|---|---|---|\n| TypeScript | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |", + content: "# Generators\nGenerators, or preset's are the core of **The Codegen Project**, that determines what is generated for your project.\n\nEach language and inputs have specific generators;\n\nAll available generators, across languages and inputs:\n- [`payloads`](./payloads.md)\n- [`parameters`](./parameters.md)\n- [`headers`](./headers.md)\n- [`types`](./types.md)\n- [`channels`](./channels.md)\n- [`client`](./client.md)\n- [`models`](./models.md)\n- [`custom`](./custom.md)\n\n| **Inputs** | [`payloads`](./payloads.md) | [`parameters`](./parameters.md) | [`headers`](./headers.md) | [`types`](./types.md) | [`channels`](./channels.md) | [`client`](./client.md) | [`models`](./models.md) | [`custom`](./custom.md) |\n|---|---|---|---|---|---|---|---|---|\n| AsyncAPI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| OpenAPI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| JSON Schema | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |\n\n> OpenAPI `channels` and `client` generate an HTTP client — see the [`openapi-http-client` example](https://github.com/the-codegen-project/cli/tree/main/examples/openapi-http-client). OpenAPI `channels` can also generate the *server* side with the [`http_server`](../protocols/http_server.md) protocol — see the [`openapi-http-server` example](https://github.com/the-codegen-project/cli/tree/main/examples/openapi-http-server).\n\n| **Languages** | [`payloads`](./payloads.md) | [`parameters`](./parameters.md) | [`headers`](./headers.md) | [`types`](./types.md) | [`channels`](./channels.md) | [`client`](./client.md) | [`models`](./models.md) | [`custom`](./custom.md) |\n|---|---|---|---|---|---|---|---|---|\n| TypeScript | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |", }, "generators/channels": { title: "Channels", - content: "# Channels\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'channels',\n outputPath: './src/__gen__/', \n language: 'typescript',\n protocols: ['nats']\n }\n ]\n};\n```\n\n`channels` preset generates support functions for each operation based on the selected protocol.\n\nThis generator uses [`payloads`](./payloads.md), [`headers`](./headers.md) and [`parameters`](./parameters.md) generators, in case you dont have any defined, it will automatically include them with default values.\n\nThis is supported through the following inputs: [`asyncapi`](../inputs/asyncapi.md), [`openapi`](../inputs/openapi.md)\n\nIt supports the following languages; [`typescript`](#typescript)\n\nIt supports the following protocols; [`nats`](../protocols/nats.md), [`kafka`](../protocols/kafka.md), [`mqtt`](../protocols/mqtt.md), [`amqp`](../protocols/amqp.md), [`event_source`](../protocols/eventsource.md), [`http_client`](../protocols/http_client.md), [`websocket`](../protocols/websocket.md)\n\n## Options\nThese are the available options for the `channels` generator; \n\n| **Option** | Default | Type | Description |\n|---|---|---|---|\n| asyncapiReverseOperations | `false` | Boolean | Used in conjunction with AsyncAPI input, and reverses the operation actions i.e. send becomes receive and receive becomes send. Often used in testing scenarios to act as the reverse API. |\n| asyncapiGenerateForOperations | `true` | Boolean | Used in conjunction with AsyncAPI input, which if `true` generate the functions upholding how operations are defined. If `false` the functions are generated regardless of what operations define. I.e. `send` and `receive` does not matter. |\n| functionTypeMapping | `{}` | Record\\ | Used in conjunction with AsyncAPI input, can define channel ID along side the type of functions that should be rendered. |\n| kafkaTopicSeparator | `'.'` | String | Used with AsyncAPI to ensure the right character separate topics, example if address is my/resource/path it will be converted to my.resource.path |\n| eventSourceDependency | `'@microsoft/fetch-event-source'` | String | Because @microsoft/fetch-event-source is out-dated in some areas we allow you to change the fork/variant that can be used instead |\n| organization | `'flat'` | `'flat' \\| 'tag' \\| 'path'` | Controls how generated channel functions are organized in the barrel `index.ts`. `flat` re-exports each function directly under its protocol namespace (default, unchanged). `tag` groups them under their API tag (operation tag first, then a v3 channel tag, otherwise an `untagged` bucket). `path` nests them by URL path / channel address segments; the leaf is the HTTP method for OpenAPI and a clean action verb (`publish`, `subscribe`, `jetStreamPublish`, …) for AsyncAPI. Only the barrel shape changes — the per-protocol function code is identical across styles. [See Organization](#organization) |\n\n## TypeScript\nRegardless of protocol, these are the dependencies: \n- If validation enabled, [ajv](https://ajv.js.org/guide/getting-started.html): ^8.17.1\n- If validation enabled, [ajv-formats](https://github.com/ajv-validator/ajv-formats): ^3.0.1\n \nDepending on which protocol, these are the dependencies:\n- `NATS`: https://github.com/nats-io/nats.js v2\n- `Kafka`: https://github.com/tulios/kafkajs v2\n- `MQTT`: https://github.com/mqttjs/MQTT.js v5\n- `AMQP`: https://github.com/amqp-node/amqplib v0\n- `EventSource`: `event_source_fetch`: https://github.com/Azure/fetch-event-source v2, `event_source_express`: https://github.com/expressjs/express v4\n- `HTTP`: none — uses the global `fetch` built into Node.js 18+ (the generated client relies on the native `fetch`/`Headers`; swap in `node-fetch`, `axios`, etc. via the `makeRequest` hook if needed)\n- `WebSocket`: https://github.com/websockets/ws v8\n\nFor TypeScript, the generator creates one file per protocol plus an index file that re-exports all protocols as namespaces. For example;\n\n```ts\n// Import specific functions from a protocol file\nimport {\n jetStreamPublishToSendUserSignedup,\n subscribeToReceiveUserSignedup,\n publishToSendUserSignedup\n} from 'src/__gen__/nats';\n\n// Or import the entire protocol namespace\nimport * as nats from 'src/__gen__/nats';\n\n// Or import all protocols from the index\nimport { nats, kafka, mqtt, amqp, event_source } from 'src/__gen__/index';\n```\n\nThe generated file structure is:\n```\noutputPath/\n├── index.ts # Re-exports all protocol namespaces\n├── nats.ts # NATS-specific functions\n├── kafka.ts # Kafka-specific functions\n├── mqtt.ts # MQTT-specific functions\n├── amqp.ts # AMQP-specific functions\n├── event_source.ts # EventSource-specific functions\n├── http_client.ts # HTTP client-specific functions\n└── websocket.ts # WebSocket-specific functions\n```\n\nEach protocol file contains standalone exported functions for interacting with channels defined in your AsyncAPI document.\n\n### Organization\n\nThe `organization` option controls how the generated functions are surfaced in the barrel `index.ts`. The per-protocol `.ts` files are **identical** across every style — only the re-export shape changes, so switching styles never changes the generated function code.\n\n| Value | Behavior |\n|---|---|\n| `flat` (default) | Every function is re-exported directly under its protocol namespace. Byte-identical to previous versions. |\n| `tag` | Functions are grouped under their API tag. |\n| `path` | Functions are nested by their URL path / channel address segments. |\n\n#### `flat` (default)\n\n```ts\nimport { http_client } from './channels';\nawait http_client.updatePet({ /* ... */ });\n```\n\n#### `tag`\n\nFunctions are grouped one level deep under their first tag. Leaf names are kept **verbatim** (the operationId / generated function name is unchanged).\n\n- **OpenAPI**: the tag comes from the operation's `tags`.\n- **AsyncAPI**: the tag comes from the operation's `tags` first; if the operation has none, the (AsyncAPI v3-only) channel `tags` are used. AsyncAPI v2 channels have no tags. Functions with no resolvable tag fall into an `untagged` bucket.\n\n```ts\nimport { http_client } from './channels';\nawait http_client.pet.updatePet({ /* ... */ }); // OpenAPI, grouped by tag \"pet\"\n\nimport { nats } from './channels';\nawait nats.user.publishToSendUserSignedup({ /* ... */ }); // AsyncAPI operation tagged \"user\"\nawait nats.untagged.publishToSendSystemPing({ /* ... */ }); // operation with no tag\n```\n\n#### `path`\n\nFunctions are nested through the static segments of the URL path (OpenAPI) or channel address (AsyncAPI); `{parameter}` placeholders and empty segments are dropped. The leaf differs by input:\n\n- **OpenAPI**: the leaf is the lowercased HTTP **method** (so `POST /pet` and `PUT /pet` coexist as `pet.post` and `pet.put`).\n- **AsyncAPI**: the leaf is a clean **action verb** derived from the function type — `publish`, `subscribe`, `request`, `reply`, `jetStreamPublish`, `jetStreamPullSubscribe`, `jetStreamPushSubscribe`, etc. — mirroring the OpenAPI method leaf (an address has no HTTP method). If two functions would resolve to the same leaf at the same node, the second falls back to its full function name so nothing is ever dropped.\n\n```ts\nimport { http_client } from './channels';\nawait http_client.pet.put({ /* ... */ }); // PUT /pet\nawait http_client.pet.findByStatus.get({ /* ... */ }); // GET /pet/findByStatus/{status}/{categoryId}\n\nimport { nats } from './channels';\nawait nats.user.signedup.publish({ /* ... */ }); // address user/signedup/{id}\nawait nats.user.signedup.jetStreamPublish({ /* ... */ });\n```\n\nConfigure it per channels generator:\n\n```js\n{\n preset: 'channels',\n outputPath: './src/__gen__/channels',\n protocols: ['http_client'],\n organization: 'tag' // 'flat' | 'tag' | 'path'\n}\n```", + content: "# Channels\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'channels',\n outputPath: './src/__gen__/', \n language: 'typescript',\n protocols: ['nats']\n }\n ]\n};\n```\n\n`channels` preset generates support functions for each operation based on the selected protocol.\n\nThis generator uses [`payloads`](./payloads.md), [`headers`](./headers.md) and [`parameters`](./parameters.md) generators, in case you dont have any defined, it will automatically include them with default values.\n\nThis is supported through the following inputs: [`asyncapi`](../inputs/asyncapi.md), [`openapi`](../inputs/openapi.md)\n\nIt supports the following languages; [`typescript`](#typescript)\n\nIt supports the following protocols; [`nats`](../protocols/nats.md), [`kafka`](../protocols/kafka.md), [`mqtt`](../protocols/mqtt.md), [`amqp`](../protocols/amqp.md), [`event_source`](../protocols/eventsource.md), [`http_client`](../protocols/http_client.md), [`http_server`](../protocols/http_server.md), [`websocket`](../protocols/websocket.md)\n\n## Options\nThese are the available options for the `channels` generator; \n\n| **Option** | Default | Type | Description |\n|---|---|---|---|\n| asyncapiReverseOperations | `false` | Boolean | Used in conjunction with AsyncAPI input, and reverses the operation actions i.e. send becomes receive and receive becomes send. Often used in testing scenarios to act as the reverse API. |\n| asyncapiGenerateForOperations | `true` | Boolean | Used in conjunction with AsyncAPI input, which if `true` generate the functions upholding how operations are defined. If `false` the functions are generated regardless of what operations define. I.e. `send` and `receive` does not matter. |\n| functionTypeMapping | `{}` | Record\\ | Used in conjunction with AsyncAPI input, can define channel ID along side the type of functions that should be rendered. |\n| kafkaTopicSeparator | `'.'` | String | Used with AsyncAPI to ensure the right character separate topics, example if address is my/resource/path it will be converted to my.resource.path |\n| eventSourceDependency | `'@microsoft/fetch-event-source'` | String | Because @microsoft/fetch-event-source is out-dated in some areas we allow you to change the fork/variant that can be used instead |\n| organization | `'flat'` | `'flat' \\| 'tag' \\| 'path'` | Controls how generated channel functions are organized in the barrel `index.ts`. `flat` re-exports each function directly under its protocol namespace (default, unchanged). `tag` groups them under their API tag (operation tag first, then a v3 channel tag, otherwise an `untagged` bucket). `path` nests them by URL path / channel address segments; the leaf is the HTTP method for OpenAPI and a clean action verb (`publish`, `subscribe`, `jetStreamPublish`, …) for AsyncAPI. Only the barrel shape changes — the per-protocol function code is identical across styles. [See Organization](#organization) |\n\n## TypeScript\nRegardless of protocol, these are the dependencies: \n- If validation enabled, [ajv](https://ajv.js.org/guide/getting-started.html): ^8.17.1\n- If validation enabled, [ajv-formats](https://github.com/ajv-validator/ajv-formats): ^3.0.1\n \nDepending on which protocol, these are the dependencies:\n- `NATS`: https://github.com/nats-io/nats.js v2\n- `Kafka`: https://github.com/tulios/kafkajs v2\n- `MQTT`: https://github.com/mqttjs/MQTT.js v5\n- `AMQP`: https://github.com/amqp-node/amqplib v0\n- `EventSource`: `event_source_fetch`: https://github.com/Azure/fetch-event-source v2, `event_source_express`: https://github.com/expressjs/express v4\n- `HTTP`: `http_client`: none — uses the global `fetch` built into Node.js 18+ (the generated client relies on the native `fetch`/`Headers`; swap in `node-fetch`, `axios`, etc. via the `makeRequest` hook if needed), `http_server`: https://github.com/expressjs/express v4\n- `WebSocket`: https://github.com/websockets/ws v8\n\nFor TypeScript, the generator creates one file per protocol plus an index file that re-exports all protocols as namespaces. For example;\n\n```ts\n// Import specific functions from a protocol file\nimport {\n jetStreamPublishToSendUserSignedup,\n subscribeToReceiveUserSignedup,\n publishToSendUserSignedup\n} from 'src/__gen__/nats';\n\n// Or import the entire protocol namespace\nimport * as nats from 'src/__gen__/nats';\n\n// Or import all protocols from the index\nimport { nats, kafka, mqtt, amqp, event_source } from 'src/__gen__/index';\n```\n\nThe generated file structure is:\n```\noutputPath/\n├── index.ts # Re-exports all protocol namespaces\n├── nats.ts # NATS-specific functions\n├── kafka.ts # Kafka-specific functions\n├── mqtt.ts # MQTT-specific functions\n├── amqp.ts # AMQP-specific functions\n├── event_source.ts # EventSource-specific functions\n├── http_client.ts # HTTP client-specific functions\n└── websocket.ts # WebSocket-specific functions\n```\n\nEach protocol file contains standalone exported functions for interacting with channels defined in your AsyncAPI document.\n\n### Organization\n\nThe `organization` option controls how the generated functions are surfaced in the barrel `index.ts`. The per-protocol `.ts` files are **identical** across every style — only the re-export shape changes, so switching styles never changes the generated function code.\n\n| Value | Behavior |\n|---|---|\n| `flat` (default) | Every function is re-exported directly under its protocol namespace. Byte-identical to previous versions. |\n| `tag` | Functions are grouped under their API tag. |\n| `path` | Functions are nested by their URL path / channel address segments. |\n\n#### `flat` (default)\n\n```ts\nimport { http_client } from './channels';\nawait http_client.updatePet({ /* ... */ });\n```\n\n#### `tag`\n\nFunctions are grouped one level deep under their first tag. Leaf names are kept **verbatim** (the operationId / generated function name is unchanged).\n\n- **OpenAPI**: the tag comes from the operation's `tags`.\n- **AsyncAPI**: the tag comes from the operation's `tags` first; if the operation has none, the (AsyncAPI v3-only) channel `tags` are used. AsyncAPI v2 channels have no tags. Functions with no resolvable tag fall into an `untagged` bucket.\n\n```ts\nimport { http_client } from './channels';\nawait http_client.pet.updatePet({ /* ... */ }); // OpenAPI, grouped by tag \"pet\"\n\nimport { nats } from './channels';\nawait nats.user.publishToSendUserSignedup({ /* ... */ }); // AsyncAPI operation tagged \"user\"\nawait nats.untagged.publishToSendSystemPing({ /* ... */ }); // operation with no tag\n```\n\n#### `path`\n\nFunctions are nested through the static segments of the URL path (OpenAPI) or channel address (AsyncAPI); `{parameter}` placeholders and empty segments are dropped. The leaf differs by input:\n\n- **OpenAPI**: the leaf is the lowercased HTTP **method** (so `POST /pet` and `PUT /pet` coexist as `pet.post` and `pet.put`).\n- **AsyncAPI**: the leaf is a clean **action verb** derived from the function type — `publish`, `subscribe`, `request`, `reply`, `jetStreamPublish`, `jetStreamPullSubscribe`, `jetStreamPushSubscribe`, etc. — mirroring the OpenAPI method leaf (an address has no HTTP method). If two functions would resolve to the same leaf at the same node, the second falls back to its full function name so nothing is ever dropped.\n\n```ts\nimport { http_client } from './channels';\nawait http_client.pet.put({ /* ... */ }); // PUT /pet\nawait http_client.pet.findByStatus.get({ /* ... */ }); // GET /pet/findByStatus/{status}/{categoryId}\n\nimport { nats } from './channels';\nawait nats.user.signedup.publish({ /* ... */ }); // address user/signedup/{id}\nawait nats.user.signedup.jetStreamPublish({ /* ... */ });\n```\n\nConfigure it per channels generator:\n\n```js\n{\n preset: 'channels',\n outputPath: './src/__gen__/channels',\n protocols: ['http_client'],\n organization: 'tag' // 'flat' | 'tag' | 'path'\n}\n```", }, "generators/client": { title: "Client", @@ -55,16 +55,16 @@ export const docs: Record = { content: "# Headers\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'headers',\n outputPath: './src/headers',\n serializationType: 'json',\n includeValidation: true,\n language: 'typescript',\n }\n ]\n};\n```\n\n`headers` preset is for generating models that represent typed models representing headers.\n\nThis is supported through the following inputs: [`asyncapi`](#inputs), [`openapi`](#inputs)\n\nIt supports the following languages; `typescript`\n\n## Inputs\n\n### `asyncapi`\nThe `headers` preset with `asyncapi` input generates all the message headers for each channel in the AsyncAPI document.\n\nThe return type is a map of channels and the model that represent the headers. \n\n### `openapi`\nThe `headers` preset with `openapi` input generates all the headers for each path in the OpenAPI document.\n\nThe return type is a map of paths and the model that represent the headers. \n\n## Options\nThese are the available options for the `headers` generator;\n\n| **Option** | Default | Type | Description |\n|---|---|---|---|\n| id | `'headers-typescript'` | String | Unique identifier for this generator instance. The `channels`/`client` generators reference it as their `headerGeneratorId`. |\n| dependencies | `[]` | String[] | IDs of other generators that must run before this one. |\n| outputPath | `'src/__gen__/headers'` | String | Directory the generated header models are written to. |\n| serializationType | `'json'` | `'json'` | Serialization format used by the generated models. Only `json` is supported. |\n| includeValidation | `true` | Boolean | Include the built-in JSON Schema `validate`/`createValidator` methods. Requires `ajv` and `ajv-formats` (see [Dependencies](#typescript)). |\n\n## Typescript\nDependencies: \n- If validation enabled, [ajv](https://ajv.js.org/guide/getting-started.html): ^8.17.1\n- If validation enabled, [ajv-formats](https://github.com/ajv-validator/ajv-formats): ^3.0.1\n\n### Validation\nEach generated class includes built-in JSON Schema validation capabilities through two static methods:\n\n- `validate`: Validates headers against the schema. Use this method when you want to validate data.\n\n```typescript\n// Example\nconst result = UserSignedUpHeaders.validate({ data: headers });\nif (!result.valid) {\n console.error('Validation errors:', result.errors);\n}\n```\n\n- `createValidator`: Creates a reusable validator function. Use this when you need to validate multiple instances of the same type and want to avoid recreating the validator each time.\n\n```typescript\n// Example\nconst validator = UserSignedUpHeaders.createValidator();\nconst result = UserSignedUpHeaders.validate({ data: headers, ajvValidatorFunction: validator });\nif (!result.valid) {\n console.error('Validation errors:', result.errors);\n}\n```\n\nBoth methods support custom Ajv instances and options for advanced validation scenarios.", }, "generators/models": { - title: "🏗️ Models", - content: "# 🏗️ Models\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'models',\n outputPath: './src/models',\n language: 'typescript',\n renderers: [...],\n options: {...}\n }\n ]\n};\n```\n\nThe `models` preset provides native integration with [AsyncAPI Modelina](https://modelina.org) for generating TypeScript models directly from AsyncAPI, OpenAPI, and JSON Schema documents. This generator exposes Modelina's full capabilities, giving you complete control over model generation.\n\nThis is supported through the following inputs: `asyncapi`, `openapi`, `jsonschema`\n\nIt supports the following languages; [`typescript`](#typescript)\n\n## Core Features\n\n- **Native Modelina Integration**: Direct access to Modelina's TypeScript generator\n- **Custom Presets**: Full control over generated code through Modelina's preset system\n- **Flexible Options**: Configure all TypeScript generation options\n- **Production Ready**: Generate models that are immediately usable in your applications\n\n## Configuration\n\n### `renderers`\n\nThe `renderers` property exposes Modelina's [preset system](https://raw.githubusercontent.com/asyncapi/modelina/refs/heads/master/docs/presets.md), allowing you to customize every aspect of the generated models.\n\nPresets can:\n- Add custom content to classes, interfaces, enums, and types\n- Override default rendering behavior\n- Inject validation logic, serialization methods, or custom properties\n- Apply consistent formatting and documentation\n\n### `options`\n\nThe `options` property provides access to all [Modelina TypeScript options](https://github.com/asyncapi/modelina/blob/master/docs/languages/TypeScript.md), including:\n\n- Model types (class, interface, type alias)\n- Enum generation styles\n- Property naming conventions\n- Module system preferences\n- Type mappings and constraints\n\n## Examples\n\n### Basic Usage\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n outputPath: './src/models'\n }\n ]\n};\n```\n\n### Using Built-in Presets\n\n```js\nimport { modelina } from '@the-codegen-project/cli';\nconst { TS_COMMON_PRESET } = modelina;\n\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n renderers: [\n {\n preset: TS_COMMON_PRESET,\n options: {\n marshalling: true\n }\n }\n ],\n outputPath: './src/models'\n }\n ]\n};\n```\n\n### Custom Presets\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n renderers: [\n {\n class: {\n self: ({model}) => `class ${model.name} {}`\n },\n interface: {\n self: ({model}) => `interface ${model.name} {}`\n },\n type: {\n self: ({model}) => `type ${model.name} = string;`\n }\n }\n ],\n outputPath: './src/models'\n }\n ]\n};\n```\n\n### Advanced Configuration with Options\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n options: {\n modelType: 'interface',\n enumType: 'union',\n mapType: 'indexedObject',\n moduleSystem: 'ESM',\n rawPropertyNames: false,\n useJavascriptReservedKeywords: false\n },\n renderers: [\n {\n interface: {\n property: ({ content, property }) => {\n return `/** ${property.property.description || 'Auto-generated property'} */\\n${content}`;\n }\n }\n }\n ],\n outputPath: './src/models'\n }\n ]\n};\n```\n\n### JSON Schema Input\n\n```js\nexport default {\n inputType: 'jsonschema',\n inputPath: 'user-schema.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n options: {\n modelType: 'class',\n enumType: 'enum'\n },\n renderers: [\n {\n class: {\n additionalContent: ({ content, model }) => {\n return `${content}\\n\\n // Custom validation method\\n public validate(): boolean {\\n return true;\\n }`;\n }\n }\n }\n ],\n outputPath: './src/models'\n }\n ]\n};\n```\n\n## Languages\n\n### TypeScript\n\nThe TypeScript implementation provides full access to Modelina's TypeScript generator capabilities.\n\n**Dependencies**: None (generates plain TypeScript)\n\n**Supported Features**:\n- Classes, interfaces, type aliases, and enums\n- Complex nested types and circular references\n- Union types and discriminated unions\n- Optional and required properties\n- Custom property naming and constraints\n- Marshalling and unmarshalling methods (with TS_COMMON_PRESET)\n- JSON Schema validation (with custom presets)\n\n**Common Options**:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `modelType` | `'class' \\| 'interface'` | `'class'` | Type of models to generate |\n| `enumType` | `'enum' \\| 'union'` | `'enum'` | How to render enum types |\n| `mapType` | `'indexedObject' \\| 'map' \\| 'record'` | `'map'` | How to render map/dictionary types |\n| `moduleSystem` | `'CJS' \\| 'ESM'` | `'ESM'` | Module system to use |\n| `rawPropertyNames` | `boolean` | `false` | Use raw property names without transformation |\n| `useJavascriptReservedKeywords` | `boolean` | `true` | Allow JavaScript reserved keywords |\n| `isolatedModules` | `boolean` | `false` | Emit `export type` / `import type` for type-only models. Required for projects using TypeScript's `isolatedModules` (Next.js, SWC, esbuild) |\n\n**Common Presets**:\n\n| Preset | Description |\n|--------|-------------|\n| `TS_COMMON_PRESET` | Adds marshalling/unmarshalling methods |\n| `TS_DESCRIPTION_PRESET` | Adds JSDoc descriptions from schemas |\n| Custom presets | Define your own rendering behavior |\n\n**Generated Code Structure**:\n\n```typescript\n// Example generated class with TS_COMMON_PRESET\nexport class UserProfile {\n private _id?: string;\n private _email?: string;\n private _name?: string;\n\n constructor(input: {\n id?: string;\n email?: string;\n name?: string;\n }) {\n this._id = input.id;\n this._email = input.email;\n this._name = input.name;\n }\n\n get id(): string | undefined { return this._id; }\n set id(id: string | undefined) { this._id = id; }\n\n get email(): string | undefined { return this._email; }\n set email(email: string | undefined) { this._email = email; }\n\n get name(): string | undefined { return this._name; }\n set name(name: string | undefined) { this._name = name; }\n\n public marshal(): string {\n return JSON.stringify({\n id: this.id,\n email: this.email,\n name: this.name\n });\n }\n\n public static unmarshal(data: string): UserProfile {\n const obj = JSON.parse(data);\n return new UserProfile(obj);\n }\n}\n```\n\n## Integration Examples\n\n### With Channels Generator\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n renderers: [\n {\n preset: TS_COMMON_PRESET,\n options: { marshalling: true }\n }\n ],\n outputPath: './src/models'\n },\n {\n preset: 'channels',\n outputPath: './src/channels',\n protocols: ['nats', 'kafka']\n }\n ]\n};\n```\n\n### With Custom Validation\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n renderers: [\n {\n class: {\n additionalContent: ({ content, model }) => {\n return `${content}\n \n public validate(): boolean {\n // Custom validation logic\n return true;\n }`;\n }\n }\n }\n ],\n outputPath: './src/models'\n }\n ]\n};\n```\n\n## Resources\n\n- [Modelina Presets Documentation](https://github.com/asyncapi/modelina/blob/master/refs/heads/master/docs/presets.md)\n- [Modelina TypeScript Options](https://github.com/asyncapi/modelina/blob/master/docs/languages/TypeScript.md)\n- [Modelina Examples](https://github.com/asyncapi/modelina/tree/master/examples)", + title: "Models", + content: "# Models\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'models',\n outputPath: './src/models',\n language: 'typescript',\n renderers: [...],\n options: {...}\n }\n ]\n};\n```\n\nThe `models` preset provides native integration with [AsyncAPI Modelina](https://modelina.org) for generating TypeScript models directly from AsyncAPI, OpenAPI, and JSON Schema documents. This generator exposes Modelina's full capabilities, giving you complete control over model generation.\n\nThis is supported through the following inputs: `asyncapi`, `openapi`, `jsonschema`\n\nIt supports the following languages; [`typescript`](#typescript)\n\n## Core Features\n\n- **Native Modelina Integration**: Direct access to Modelina's TypeScript generator\n- **Custom Presets**: Full control over generated code through Modelina's preset system\n- **Flexible Options**: Configure all TypeScript generation options\n- **Production Ready**: Generate models that are immediately usable in your applications\n\n## Configuration\n\n### `renderers`\n\nThe `renderers` property exposes Modelina's [preset system](https://raw.githubusercontent.com/asyncapi/modelina/refs/heads/master/docs/presets.md), allowing you to customize every aspect of the generated models.\n\nPresets can:\n- Add custom content to classes, interfaces, enums, and types\n- Override default rendering behavior\n- Inject validation logic, serialization methods, or custom properties\n- Apply consistent formatting and documentation\n\n### `options`\n\nThe `options` property provides access to all [Modelina TypeScript options](https://github.com/asyncapi/modelina/blob/master/docs/languages/TypeScript.md), including:\n\n- Model types (class, interface, type alias)\n- Enum generation styles\n- Property naming conventions\n- Module system preferences\n- Type mappings and constraints\n\n## Examples\n\n### Basic Usage\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n outputPath: './src/models'\n }\n ]\n};\n```\n\n### Using Built-in Presets\n\n```js\nimport { modelina } from '@the-codegen-project/cli';\nconst { TS_COMMON_PRESET } = modelina;\n\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n renderers: [\n {\n preset: TS_COMMON_PRESET,\n options: {\n marshalling: true\n }\n }\n ],\n outputPath: './src/models'\n }\n ]\n};\n```\n\n### Custom Presets\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n renderers: [\n {\n class: {\n self: ({model}) => `class ${model.name} {}`\n },\n interface: {\n self: ({model}) => `interface ${model.name} {}`\n },\n type: {\n self: ({model}) => `type ${model.name} = string;`\n }\n }\n ],\n outputPath: './src/models'\n }\n ]\n};\n```\n\n### Advanced Configuration with Options\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n options: {\n modelType: 'interface',\n enumType: 'union',\n mapType: 'indexedObject',\n moduleSystem: 'ESM',\n rawPropertyNames: false,\n useJavascriptReservedKeywords: false\n },\n renderers: [\n {\n interface: {\n property: ({ content, property }) => {\n return `/** ${property.property.description || 'Auto-generated property'} */\\n${content}`;\n }\n }\n }\n ],\n outputPath: './src/models'\n }\n ]\n};\n```\n\n### JSON Schema Input\n\n```js\nexport default {\n inputType: 'jsonschema',\n inputPath: 'user-schema.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n options: {\n modelType: 'class',\n enumType: 'enum'\n },\n renderers: [\n {\n class: {\n additionalContent: ({ content, model }) => {\n return `${content}\\n\\n // Custom validation method\\n public validate(): boolean {\\n return true;\\n }`;\n }\n }\n }\n ],\n outputPath: './src/models'\n }\n ]\n};\n```\n\n## Languages\n\n### TypeScript\n\nThe TypeScript implementation provides full access to Modelina's TypeScript generator capabilities.\n\n**Dependencies**: None (generates plain TypeScript)\n\n**Supported Features**:\n- Classes, interfaces, type aliases, and enums\n- Complex nested types and circular references\n- Union types and discriminated unions\n- Optional and required properties\n- Custom property naming and constraints\n- Marshalling and unmarshalling methods (with TS_COMMON_PRESET)\n- JSON Schema validation (with custom presets)\n\n**Common Options**:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `modelType` | `'class' \\| 'interface'` | `'class'` | Type of models to generate |\n| `enumType` | `'enum' \\| 'union'` | `'enum'` | How to render enum types |\n| `mapType` | `'indexedObject' \\| 'map' \\| 'record'` | `'map'` | How to render map/dictionary types |\n| `moduleSystem` | `'CJS' \\| 'ESM'` | `'ESM'` | Module system to use |\n| `rawPropertyNames` | `boolean` | `false` | Use raw property names without transformation |\n| `useJavascriptReservedKeywords` | `boolean` | `true` | Allow JavaScript reserved keywords |\n| `isolatedModules` | `boolean` | `false` | Emit `export type` / `import type` for type-only models. Required for projects using TypeScript's `isolatedModules` (Next.js, SWC, esbuild) |\n\n**Common Presets**:\n\n| Preset | Description |\n|--------|-------------|\n| `TS_COMMON_PRESET` | Adds marshalling/unmarshalling methods |\n| `TS_DESCRIPTION_PRESET` | Adds JSDoc descriptions from schemas |\n| Custom presets | Define your own rendering behavior |\n\n**Generated Code Structure**:\n\n```typescript\n// Example generated class with TS_COMMON_PRESET\nexport class UserProfile {\n private _id?: string;\n private _email?: string;\n private _name?: string;\n\n constructor(input: {\n id?: string;\n email?: string;\n name?: string;\n }) {\n this._id = input.id;\n this._email = input.email;\n this._name = input.name;\n }\n\n get id(): string | undefined { return this._id; }\n set id(id: string | undefined) { this._id = id; }\n\n get email(): string | undefined { return this._email; }\n set email(email: string | undefined) { this._email = email; }\n\n get name(): string | undefined { return this._name; }\n set name(name: string | undefined) { this._name = name; }\n\n public marshal(): string {\n return JSON.stringify({\n id: this.id,\n email: this.email,\n name: this.name\n });\n }\n\n public static unmarshal(data: string): UserProfile {\n const obj = JSON.parse(data);\n return new UserProfile(obj);\n }\n}\n```\n\n## Integration Examples\n\n### With Channels Generator\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n renderers: [\n {\n preset: TS_COMMON_PRESET,\n options: { marshalling: true }\n }\n ],\n outputPath: './src/models'\n },\n {\n preset: 'channels',\n outputPath: './src/channels',\n protocols: ['nats', 'kafka']\n }\n ]\n};\n```\n\n### With Custom Validation\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: 'asyncapi.json',\n language: 'typescript',\n generators: [\n {\n preset: 'models',\n renderers: [\n {\n class: {\n additionalContent: ({ content, model }) => {\n return `${content}\n \n public validate(): boolean {\n // Custom validation logic\n return true;\n }`;\n }\n }\n }\n ],\n outputPath: './src/models'\n }\n ]\n};\n```\n\n## Resources\n\n- [Modelina Presets Documentation](https://github.com/asyncapi/modelina/blob/master/refs/heads/master/docs/presets.md)\n- [Modelina TypeScript Options](https://github.com/asyncapi/modelina/blob/master/docs/languages/TypeScript.md)\n- [Modelina Examples](https://github.com/asyncapi/modelina/tree/master/examples)", }, "generators/parameters": { title: "Parameters", content: "# Parameters\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'parameters',\n outputPath: './src/parameters',\n serializationType: 'json',\n language: 'typescript',\n }\n ]\n};\n```\n\n`parameters` preset is for generating models that represent typed models for parameters used in API operations.\n\nThis is supported through the following inputs: [`asyncapi`](#inputs), [`openapi`](#inputs)\n\nIt supports the following languages; `typescript`\n\n## Companion Interface\n\nEvery generated parameter model file exports **two** symbols: the parameter\nclass (`Parameters`) and a plain-data companion interface\n(`ParametersInterface`) declared above it. The class constructor takes the\ninterface (`constructor(input: ParametersInterface)`), so the two always\nstay in sync.\n\n```typescript\nexport { FindPetsByStatusParameters, FindPetsByStatusParametersInterface };\n```\n\nThis lets you pass a **plain object** wherever a channel expects parameters —\nyou do not have to construct the class yourself:\n\n```typescript\n// Both of these are accepted by every generated channel helper:\nawait publishToUserSignedup({ message, parameters: { myParameter: 'test', enumParameter: 'openapi' }, nc });\nawait publishToUserSignedup({ message, parameters: new UserSignedupParameters({ myParameter: 'test', enumParameter: 'openapi' }), nc });\n```\n\nChannel consumers type their parameter argument as the union\n`ParametersInterface | Parameters` and normalize it to a class\ninstance internally (via an `instanceof` guard) before using the rich class\nbehavior (`getChannelWithParameters`, serialization, etc.). The plain-object\nform is purely an ergonomic convenience; the generated code always operates on a\nclass instance. See the [protocols documentation](../protocols) for how each\nchannel accepts parameters.\n\n## Inputs\n\n### `asyncapi`\nThe `parameters` preset with `asyncapi` input generates all the parameters for each channel in the AsyncAPI document.\n\nThe return type is a map of channels and the model that represent the parameters.\n\n### `openapi`\nThe `parameters` preset with `openapi` input generates all the parameters for each operation in the OpenAPI document, including both path and query parameters.\n\nThe return type is a map of operations and the model that represent the parameters.\n\n## Typescript\n\n### AsyncAPI Functions\n\nEach generated AsyncAPI parameter class includes the following methods:\n\n#### Channel Parameter Substitution\n- `getChannelWithParameters(channel: string): string`: Replaces parameter placeholders in the channel/topic string with actual parameter values.\n\n```typescript\n// Example\nconst params = new UserSignedupParameters({\n myParameter: 'test',\n enumParameter: 'openapi'\n});\nconst channel = params.getChannelWithParameters('user/{my_parameter}/signup/{enum_parameter}');\n// Result: 'user/test/signup/openapi'\n```\n\n#### Static Factory Method\n- `static createFromChannel(msgSubject: string, channel: string, regex: RegExp): ParameterClass`: Creates a parameter instance by extracting values from a message subject using the provided channel template and regex.\n\n```typescript\n// Example\nconst params = UserSignedupParameters.createFromChannel(\n 'user.test.signup.openapi',\n 'user/{my_parameter}/signup/{enum_parameter}',\n /user\\.(.+)\\.signup\\.(.+)/\n);\n```\n\n### OpenAPI Functions\n\nEach generated OpenAPI parameter class includes comprehensive serialization and deserialization capabilities:\n\n#### Path Parameter Serialization\n- `serializePathParameters(): Record`: Serializes path parameters according to OpenAPI 2.0/3.x specification for URL path substitution.\n\n```typescript\n// Example\nconst params = new FindPetsByStatusParameters({\n status: 'available',\n categoryId: 123\n});\nconst pathParams = params.serializePathParameters();\n// Result: { status: 'available', categoryId: '123' }\n```\n\n#### Query Parameter Serialization\n- `serializeQueryParameters(): URLSearchParams`: Serializes query parameters according to OpenAPI specification with proper encoding and style handling.\n\n```typescript\n// Example\nconst queryParams = params.serializeQueryParameters();\nconst queryString = queryParams.toString();\n// Result: 'limit=10&offset=0&tags=dog,cat'\n```\n\n#### Complete URL Serialization\n- `serializeUrl(basePath: string): string`: Generates the complete URL with both path and query parameters properly serialized.\n\n```typescript\n// Example\nconst url = params.serializeUrl('/pet/findByStatus/{status}/{categoryId}');\n// Result: '/pet/findByStatus/available/123?limit=10&offset=0&tags=dog,cat'\n```\n\n#### URL Deserialization\n- `deserializeUrl(url: string): void`: Parses a URL and populates the instance properties from query parameters.\n\n```typescript\n// Example\nconst params = new FindPetsByStatusParameters({ status: 'available', categoryId: 123 });\nparams.deserializeUrl('/pet/findByStatus/available/123?limit=5&tags=dog,cat');\n// params.limit is now 5, params.tags is now ['dog', 'cat']\n```\n\n#### Static Factory Methods\n- `static fromUrl(url: string, basePath: string, ...requiredDefaults): ParameterClass`: Creates a new parameter instance from a complete URL by extracting both path and query parameters.\n\n```typescript\n// Example\nconst params = FindPetsByStatusParameters.fromUrl(\n '/pet/findByStatus/available/123?limit=5&tags=dog',\n '/pet/findByStatus/{status}/{categoryId}'\n);\n// params.status is 'available', params.categoryId is 123, params.limit is 5\n```\n\n### Parameter Style Support\n\nThe OpenAPI generator supports all OpenAPI parameter styles and serialization formats:\n\n#### Path Parameters\n- **simple** (default): `value1,value2` or `key1,value1,key2,value2`\n- **label**: `.value1.value2` or `.key1.value1.key2.value2`\n- **matrix**: `;param=value1,value2` or `;key1=value1;key2=value2`\n\n#### Query Parameters\n- **form** (default): `param=value1¶m=value2` (exploded) or `param=value1,value2`\n- **spaceDelimited**: `param=value1 value2`\n- **pipeDelimited**: `param=value1|value2`\n- **deepObject**: `param[key1]=value1¶m[key2]=value2`\n\n### Type Safety\n\nAll parameter classes are fully typed with:\n- Enum parameter types for restricted values\n- Required vs optional parameter distinction\n- Proper TypeScript casting for different parameter types (string, number, boolean, arrays)\n- Support for complex parameter schemas including nested objects and arrays\n\n### OpenAPI 2.0 Compatibility\n\nThe generator supports OpenAPI 2.0 `collectionFormat` parameter serialization:\n- `csv`: Comma-separated values\n- `ssv`: Space-separated values \n- `tsv`: Tab-separated values (treated as CSV)\n- `pipes`: Pipe-separated values\n- `multi`: Multiple parameter instances\n\nThese are automatically converted to equivalent OpenAPI 3.0 style/explode combinations for consistent handling.", }, "generators/payloads": { - title: "🐔 Payloads", - content: "# 🐔 Payloads\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'payloads',\n outputPath: './src/payloads',\n serializationType: 'json', \n language: 'typescript'\n }\n ]\n};\n```\n\n`payloads` preset is for generating models that represent typed models that can be serialized into message payloads for communication use-cases.\n\nThis is supported through the following inputs: `asyncapi`, `openapi`\n\nIt supports the following languages; [`typescript`](#typescript)\n\n## Companion Interface\n\nEvery generated **object** payload file exports **two** symbols: the payload\nclass (``) and a plain-data companion interface (`Interface`)\ndeclared above it. The class constructor takes the interface\n(`constructor(input: Interface)`), so the two always stay in sync.\n\n```typescript\nexport { UserSignedUp, UserSignedUpInterface };\n```\n\nThis lets you pass a **plain object** wherever a channel expects a payload —\nyou do not have to construct the class yourself:\n\n```typescript\n// Both of these are accepted by every generated publish/request helper:\nawait publishToUserSignedup({ message: { displayName: 'Jane', email: 'jane@example.com' }, nc });\nawait publishToUserSignedup({ message: new UserSignedUp({ displayName: 'Jane', email: 'jane@example.com' }), nc });\n```\n\nChannel consumers type their message argument as the union\n`Interface | ` and normalize it to a class instance internally (via\nan `instanceof` guard) before calling `.marshal()`. The plain-object form is\npurely an ergonomic convenience; the generated code always marshals a class\ninstance.\n\nThis applies to **object** payloads only. Non-object payloads\n(unions, primitives, arrays, and enums) keep their `type`/`enum` shape and\nfree-function marshalling — they have no companion interface and are exported as\na single symbol. See the [protocols documentation](../protocols) for how each\nchannel accepts payloads.\n\n## Options\nThese are the available options for the `payloads` generator;\n\n| **Option** | Default | Type | Description |\n|---|---|---|---|\n| id | `'payloads-typescript'` | String | Unique identifier for this generator instance. Other generators reference it as a dependency, and the `channels`/`client` generators use it as their `payloadGeneratorId`. |\n| dependencies | `[]` | String[] | IDs of other generators that must run before this one. |\n| outputPath | `'src/__gen__/payloads'` | String | Directory the generated payload models are written to. |\n| serializationType | `'json'` | `'json'` | Serialization format used by the generated models. Only `json` is supported. |\n| enum | `'enum'` | `'enum' \\| 'union'` | Render enums as TypeScript `enum`s, or as string/number union types. |\n| map | `'record'` | `'indexedObject' \\| 'map' \\| 'record'` | Render dictionary/map types as `Record`, the `Map` class, or an index signature. |\n| useForJavaScript | `true` | Boolean | Apply JavaScript restrictions so the models stay valid when transpiled to JavaScript (for example avoiding reserved keywords as identifiers). |\n| includeValidation | `true` | Boolean | Include the built-in JSON Schema `validate`/`createValidator` methods. Requires `ajv` and `ajv-formats` (see [Dependencies](#typescript)). |\n| rawPropertyNames | `false` | Boolean | Keep the raw property names from the input schema. Consumers then access them with `obj[\"propertyName\"]` instead of `obj.propertyName`. |\n\nThe global [`importExtension`](../configurations.md#import-extensions-node16nodenextverbatimmodulesyntax) option also applies to the imports between generated payload models.\n\n## Languages\nEach language has a set of constraints which means that some typed model types are either supported or not, or it might just be the code generation library that does not yet support it.\n\n| | Circular models | Enums | Tuples | Arrays | Nested Arrays | Dictionaries | Json Serialization | Validation |\n|---|---|---|---|---|---|---|---|---|\n| **TypeScript** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n\n### TypeScript\n\nDependencies: \n- If validation enabled, [ajv](https://ajv.js.org/guide/getting-started.html): ^8.17.1\n- If validation enabled, [ajv-formats](https://github.com/ajv-validator/ajv-formats): ^3.0.1\n\n> `ajv-formats` v3 follows RFC 3339 more strictly than v2 did. Most notably,\n> `format: time` now requires a time offset, so `\"10:30:00\"` is rejected while\n> `\"10:30:00Z\"` and `\"10:30:00+02:00\"` are accepted. Pin `ajv-formats@^2` if you\n> need the previous, more lenient behaviour.\n\n#### Validation\nEach generated class includes built-in JSON Schema validation capabilities through two static methods:\n\n- `validate`: Validates data against the schema. Use this method when you want to validate data.\n\n```typescript\n// Example\nconst result = UserSignedUp.validate({ data: userData });\nif (!result.valid) {\n console.error('Validation errors:', result.errors);\n}\n```\n\n- `createValidator`: Creates a reusable validator function. Use this when you need to validate multiple instances of the same type and want to avoid recreating the validator each time.\n\n```typescript\n// Example\nconst validator = UserSignedUp.createValidator();\nconst result = UserSignedUp.validate({ data: userData, ajvValidatorFunction: validator });\nif (!result.valid) {\n console.error('Validation errors:', result.errors);\n}\n```\n\nBoth methods support custom Ajv instances and options for advanced validation scenarios.", + title: "Payloads", + content: "# Payloads\n\n```js\nexport default {\n ...,\n generators: [\n {\n preset: 'payloads',\n outputPath: './src/payloads',\n serializationType: 'json', \n language: 'typescript'\n }\n ]\n};\n```\n\n`payloads` preset is for generating models that represent typed models that can be serialized into message payloads for communication use-cases.\n\nThis is supported through the following inputs: `asyncapi`, `openapi`\n\nIt supports the following languages; [`typescript`](#typescript)\n\n## Companion Interface\n\nEvery generated **object** payload file exports **two** symbols: the payload\nclass (``) and a plain-data companion interface (`Interface`)\ndeclared above it. The class constructor takes the interface\n(`constructor(input: Interface)`), so the two always stay in sync.\n\n```typescript\nexport { UserSignedUp, UserSignedUpInterface };\n```\n\nThis lets you pass a **plain object** wherever a channel expects a payload —\nyou do not have to construct the class yourself:\n\n```typescript\n// Both of these are accepted by every generated publish/request helper:\nawait publishToUserSignedup({ message: { displayName: 'Jane', email: 'jane@example.com' }, nc });\nawait publishToUserSignedup({ message: new UserSignedUp({ displayName: 'Jane', email: 'jane@example.com' }), nc });\n```\n\nChannel consumers type their message argument as the union\n`Interface | ` and normalize it to a class instance internally (via\nan `instanceof` guard) before calling `.marshal()`. The plain-object form is\npurely an ergonomic convenience; the generated code always marshals a class\ninstance.\n\nThis applies to **object** payloads only. Non-object payloads\n(unions, primitives, arrays, and enums) keep their `type`/`enum` shape and\nfree-function marshalling — they have no companion interface and are exported as\na single symbol. See the [protocols documentation](../protocols) for how each\nchannel accepts payloads.\n\n## Options\nThese are the available options for the `payloads` generator;\n\n| **Option** | Default | Type | Description |\n|---|---|---|---|\n| id | `'payloads-typescript'` | String | Unique identifier for this generator instance. Other generators reference it as a dependency, and the `channels`/`client` generators use it as their `payloadGeneratorId`. |\n| dependencies | `[]` | String[] | IDs of other generators that must run before this one. |\n| outputPath | `'src/__gen__/payloads'` | String | Directory the generated payload models are written to. |\n| serializationType | `'json'` | `'json'` | Serialization format used by the generated models. Only `json` is supported. |\n| enum | `'enum'` | `'enum' \\| 'union'` | Render enums as TypeScript `enum`s, or as string/number union types. |\n| map | `'record'` | `'indexedObject' \\| 'map' \\| 'record'` | Render dictionary/map types as `Record`, the `Map` class, or an index signature. |\n| useForJavaScript | `true` | Boolean | Apply JavaScript restrictions so the models stay valid when transpiled to JavaScript (for example avoiding reserved keywords as identifiers). |\n| includeValidation | `true` | Boolean | Include the built-in JSON Schema `validate`/`createValidator` methods. Requires `ajv` and `ajv-formats` (see [Dependencies](#typescript)). |\n| rawPropertyNames | `false` | Boolean | Keep the raw property names from the input schema. Consumers then access them with `obj[\"propertyName\"]` instead of `obj.propertyName`. |\n\nThe global [`importExtension`](../configurations.md#import-extensions-node16nodenextverbatimmodulesyntax) option also applies to the imports between generated payload models.\n\n## Languages\nEach language has a set of constraints which means that some typed model types are either supported or not, or it might just be the code generation library that does not yet support it.\n\n| | Circular models | Enums | Tuples | Arrays | Nested Arrays | Dictionaries | Json Serialization | Validation |\n|---|---|---|---|---|---|---|---|---|\n| **TypeScript** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n\n### TypeScript\n\nDependencies: \n- If validation enabled, [ajv](https://ajv.js.org/guide/getting-started.html): ^8.17.1\n- If validation enabled, [ajv-formats](https://github.com/ajv-validator/ajv-formats): ^3.0.1\n\n> `ajv-formats` v3 follows RFC 3339 more strictly than v2 did. Most notably,\n> `format: time` now requires a time offset, so `\"10:30:00\"` is rejected while\n> `\"10:30:00Z\"` and `\"10:30:00+02:00\"` are accepted. Pin `ajv-formats@^2` if you\n> need the previous, more lenient behaviour.\n\n#### Validation\nEach generated class includes built-in JSON Schema validation capabilities through two static methods:\n\n- `validate`: Validates data against the schema. Use this method when you want to validate data.\n\n```typescript\n// Example\nconst result = UserSignedUp.validate({ data: userData });\nif (!result.valid) {\n console.error('Validation errors:', result.errors);\n}\n```\n\n- `createValidator`: Creates a reusable validator function. Use this when you need to validate multiple instances of the same type and want to avoid recreating the validator each time.\n\n```typescript\n// Example\nconst validator = UserSignedUp.createValidator();\nconst result = UserSignedUp.validate({ data: userData, ajvValidatorFunction: validator });\nif (!result.valid) {\n console.error('Validation errors:', result.errors);\n}\n```\n\nBoth methods support custom Ajv instances and options for advanced validation scenarios.", }, "generators/types": { title: "Types", @@ -80,7 +80,7 @@ export const docs: Record = { }, "getting-started/protocols": { title: "Understanding Protocols", - content: "# Understanding Protocols\n\nThe Codegen Project supports multiple messaging protocols, allowing you to generate protocol-specific code for your message-driven applications. This enables type-safe, production-ready communication code for various messaging systems.\n\n## What Are Protocols?\n\nProtocols define how messages are sent and received in distributed systems. The Codegen Project generates protocol-specific functions that handle the low-level details of message communication, so you can focus on your business logic.\n\n## Supported Protocols\n\nThe Codegen Project currently supports these messaging protocols:\n\n| Protocol | Description | Use Cases |\n|----------|-------------|-----------|\n| **[NATS](../protocols/nats.md)** | High-performance, cloud-native messaging system | Microservices, real-time systems, IoT |\n| **[Kafka](../protocols/kafka.md)** | Distributed event streaming platform | Event streaming, log aggregation, real-time analytics |\n| **[MQTT](../protocols/mqtt.md)** | Lightweight messaging protocol for IoT | IoT devices, mobile apps, low-bandwidth scenarios |\n| **[AMQP](../protocols/amqp.md)** | Advanced Message Queuing Protocol | Enterprise messaging, reliable message delivery |\n| **[EventSource](../protocols/eventsource.md)** | Server-Sent Events (SSE) protocol | Real-time web updates, streaming data to browsers |\n| **[HTTP Client](../protocols/http_client.md)** | RESTful API communication | HTTP APIs, REST services |\n| **[WebSocket](../protocols/websocket.md)** | Full-duplex communication protocol | Real-time web applications, bidirectional communication |\n\n## How Protocol Support Works\nEach protocol usually requires specific dependencies and should be installed in your project (if its noy already are). Make sure to check the documentation for each protocol to figure out which one you need!\n\n### 1. Protocol Configuration\n\nProtocols are configured through the [`channels`](../generators/channels.md) generator:\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: './my-api.yaml',\n generators: [\n {\n preset: 'channels',\n outputPath: './src/__gen__/',\n language: 'typescript',\n protocols: ['nats', 'kafka'] // Specify which protocols to generate\n }\n ]\n};\n```\n\n### 2. Generated Protocol Functions\n\nThe `channels` generator creates protocol-specific functions for each channel in your AsyncAPI specification:\n\nEach protocol is exported as its own namespace from the generated barrel file,\nand every generated function takes a single object argument:\n\n```typescript\nimport { nats, kafka } from './src/__gen__/channels';\n\n// NATS functions\nawait nats.publishToUserSignup({ message, nc: connection });\nawait nats.subscribeToUserSignup({ onDataCallback: callback, nc: connection });\n\n// Kafka functions — note Kafka uses produceTo/consumeFrom\nawait kafka.produceToUserSignup({ message, kafka: kafkaClient });\nawait kafka.consumeFromUserSignup({\n onDataCallback: callback,\n kafka: kafkaClient,\n options: { fromBeginning: true, groupId: 'my-group' }\n});\n```\n\nThe exact parameters depend on the channel — channels with parameters also take\n`parameters`, and channels with headers accept `headers`. See each protocol's\npage for the full generated signatures.\n\nEach protocol has unique features that are reflected in the generated code:\n\n**NATS** supports:\n- Core publish/subscribe\n- JetStream (persistent messaging)\n- Request/reply patterns\n\n**Kafka** supports:\n- Producer/consumer patterns\n- Consumer groups\n- Topic partitioning\n\n**MQTT** supports:\n- QoS levels (0, 1, 2)\n- Retained messages\n- User properties (headers)\n\n**AMQP** supports:\n- Exchanges and queues\n- Routing patterns\n- Message acknowledgments\n\n## Protocol Selection\n\n### Single Protocol\nGenerate code for one protocol:\n\n```js\n{\n preset: 'channels',\n protocols: ['nats']\n}\n```\nor generate for multiple protocols at once:\n\n```js\n{\n preset: 'channels',\n protocols: ['nats', 'kafka', 'mqtt']\n}\n```\n\n\n## Protocol-Specific Options\n\nSome generators support protocol-specific configuration options:\n\n```js\n{\n preset: 'channels',\n protocols: ['kafka'],\n kafkaTopicSeparator: '.', // Customize topic separator\n eventSourceDependency: '@microsoft/fetch-event-source' // Custom EventSource dependency\n}\n```\n\n## Generated Code Structure\n\nProtocol functions are organized by protocol:\n\n```typescript\nexport const Protocols = {\n nats: {\n publishToUserSignup: ...,\n subscribeToUserSignup: ...,\n jetStreamPublishToUserSignup: ...\n },\n kafka: {\n publishToUserSignup: ...,\n subscribeToUserSignup: ...\n },\n // ... other protocols\n};\n```\n\n## Next Steps\n\n- **[Explore Protocol Documentation](../protocols/)** - Detailed docs for each protocol\n- **[Learn about Channels Generator](../generators/channels.md)** - How to configure protocol generation\n- **[Check Out Examples](https://github.com/the-codegen-project/cli/tree/main/examples)** - See the code generation in action\n- **[Understanding Generators](./generators.md)** - Learn how generators work", + content: "# Understanding Protocols\n\nThe Codegen Project supports multiple messaging protocols, allowing you to generate protocol-specific code for your message-driven applications. This enables type-safe, production-ready communication code for various messaging systems.\n\n## What Are Protocols?\n\nProtocols define how messages are sent and received in distributed systems. The Codegen Project generates protocol-specific functions that handle the low-level details of message communication, so you can focus on your business logic.\n\n## Supported Protocols\n\nThe Codegen Project currently supports these messaging protocols:\n\n| Protocol | Description | Use Cases |\n|----------|-------------|-----------|\n| **[NATS](../protocols/nats.md)** | High-performance, cloud-native messaging system | Microservices, real-time systems, IoT |\n| **[Kafka](../protocols/kafka.md)** | Distributed event streaming platform | Event streaming, log aggregation, real-time analytics |\n| **[MQTT](../protocols/mqtt.md)** | Lightweight messaging protocol for IoT | IoT devices, mobile apps, low-bandwidth scenarios |\n| **[AMQP](../protocols/amqp.md)** | Advanced Message Queuing Protocol | Enterprise messaging, reliable message delivery |\n| **[EventSource](../protocols/eventsource.md)** | Server-Sent Events (SSE) protocol | Real-time web updates, streaming data to browsers |\n| **[HTTP Client](../protocols/http_client.md)** | RESTful API communication | HTTP APIs, REST services |\n| **[HTTP Server](../protocols/http_server.md)** | Typed Express handler stubs from an OpenAPI document | Implementing a REST API against its specification |\n| **[WebSocket](../protocols/websocket.md)** | Full-duplex communication protocol | Real-time web applications, bidirectional communication |\n\n## How Protocol Support Works\nEach protocol usually requires specific dependencies and should be installed in your project (if its noy already are). Make sure to check the documentation for each protocol to figure out which one you need!\n\n### 1. Protocol Configuration\n\nProtocols are configured through the [`channels`](../generators/channels.md) generator:\n\n```js\nexport default {\n inputType: 'asyncapi',\n inputPath: './my-api.yaml',\n generators: [\n {\n preset: 'channels',\n outputPath: './src/__gen__/',\n language: 'typescript',\n protocols: ['nats', 'kafka'] // Specify which protocols to generate\n }\n ]\n};\n```\n\n### 2. Generated Protocol Functions\n\nThe `channels` generator creates protocol-specific functions for each channel in your AsyncAPI specification:\n\nEach protocol is exported as its own namespace from the generated barrel file,\nand every generated function takes a single object argument:\n\n```typescript\nimport { nats, kafka } from './src/__gen__/channels';\n\n// NATS functions\nawait nats.publishToUserSignup({ message, nc: connection });\nawait nats.subscribeToUserSignup({ onDataCallback: callback, nc: connection });\n\n// Kafka functions — note Kafka uses produceTo/consumeFrom\nawait kafka.produceToUserSignup({ message, kafka: kafkaClient });\nawait kafka.consumeFromUserSignup({\n onDataCallback: callback,\n kafka: kafkaClient,\n options: { fromBeginning: true, groupId: 'my-group' }\n});\n```\n\nThe exact parameters depend on the channel — channels with parameters also take\n`parameters`, and channels with headers accept `headers`. See each protocol's\npage for the full generated signatures.\n\nEach protocol has unique features that are reflected in the generated code:\n\n**NATS** supports:\n- Core publish/subscribe\n- JetStream (persistent messaging)\n- Request/reply patterns\n\n**Kafka** supports:\n- Producer/consumer patterns\n- Consumer groups\n- Topic partitioning\n\n**MQTT** supports:\n- QoS levels (0, 1, 2)\n- Retained messages\n- User properties (headers)\n\n**AMQP** supports:\n- Exchanges and queues\n- Routing patterns\n- Message acknowledgments\n\n## Protocol Selection\n\n### Single Protocol\nGenerate code for one protocol:\n\n```js\n{\n preset: 'channels',\n protocols: ['nats']\n}\n```\nor generate for multiple protocols at once:\n\n```js\n{\n preset: 'channels',\n protocols: ['nats', 'kafka', 'mqtt']\n}\n```\n\n\n## Protocol-Specific Options\n\nSome generators support protocol-specific configuration options:\n\n```js\n{\n preset: 'channels',\n protocols: ['kafka'],\n kafkaTopicSeparator: '.', // Customize topic separator\n eventSourceDependency: '@microsoft/fetch-event-source' // Custom EventSource dependency\n}\n```\n\n## Generated Code Structure\n\nProtocol functions are organized by protocol:\n\n```typescript\nexport const Protocols = {\n nats: {\n publishToUserSignup: ...,\n subscribeToUserSignup: ...,\n jetStreamPublishToUserSignup: ...\n },\n kafka: {\n publishToUserSignup: ...,\n subscribeToUserSignup: ...\n },\n // ... other protocols\n};\n```\n\n## Next Steps\n\n- **[Explore Protocol Documentation](../protocols/)** - Detailed docs for each protocol\n- **[Learn about Channels Generator](../generators/channels.md)** - How to configure protocol generation\n- **[Check Out Examples](https://github.com/the-codegen-project/cli/tree/main/examples)** - See the code generation in action\n- **[Understanding Generators](./generators.md)** - Learn how generators work", }, "inputs/asyncapi": { title: "AsyncAPI", @@ -122,6 +122,10 @@ export const docs: Record = { title: "HTTP(S)", content: "# HTTP(S)\n\nHTTP client generator creates type-safe functions for making HTTP requests based on your API specification. It supports various authentication methods, retry logic, and extensibility hooks.\n\nIt is currently available through the generators ([channels](../generators/channels.md)):\n\nThis is available through [AsyncAPI](../inputs/asyncapi.md) ([requires the HTTP `method` binding for operations and `statusCode` for messages](../inputs/asyncapi.md#http-client)) and directly from [OpenAPI](../inputs/openapi.md) documents (see [From OpenAPI](#from-openapi) below).\n\n## TypeScript\n\n| **Feature** | Is supported? |\n|---|---|\n| Download | ❌ |\n| Upload | ❌ |\n| Retry with backoff | ✅ |\n| OAuth2 Authorization code | ❌ (browser-only) |\n| OAuth2 Implicit | ❌ (browser-only) |\n| OAuth2 Password | ✅ |\n| OAuth2 Client Credentials | ✅ |\n| OAuth2 Token Refresh | ✅ |\n| Username/password Authentication | ✅ |\n| Bearer Authentication | ✅ |\n| Basic Authentication | ✅ |\n| API Key Authentication | ✅ |\n| Request/Response Hooks | ✅ |\n| XML Based API | ❌ |\n| JSON Based API | ✅ |\n| POST | ✅ |\n| GET | ✅ |\n| PATCH | ✅ |\n| DELETE | ✅ |\n| PUT | ✅ |\n| HEAD | ✅ |\n| OPTIONS | ✅ |\n\n## Channels\n\nRead more about the [channels generator here](../generators/channels.md).\n\n\n\n \n \n \n \n\n\n \n \n \n \n\n
Input (AsyncAPI)Using the code
\n\n```yaml\nasyncapi: 3.0.0\ninfo:\n title: User API\n version: 1.0.0\nchannels:\n ping:\n address: /ping\n messages:\n pingRequest:\n $ref: '#/components/messages/PingRequest'\n pongResponse:\n $ref: '#/components/messages/PongResponse'\noperations:\n postPing:\n action: send\n channel:\n $ref: '#/channels/ping'\n bindings:\n http:\n method: POST\n reply:\n channel:\n $ref: '#/channels/ping'\n messages:\n - $ref: '#/channels/ping/messages/pongResponse'\ncomponents:\n messages:\n PingRequest:\n payload:\n type: object\n properties:\n message:\n type: string\n PongResponse:\n payload:\n type: object\n properties:\n response:\n type: string\n bindings:\n http:\n statusCode: 200\n```\n\n\n```ts\n// Location depends on the payload generator configurations\nimport { PingRequest } from './__gen__/payloads/PingRequest';\nimport { PongResponse } from './__gen__/payloads/PongResponse';\n// Location depends on the channel generator configurations\nimport { http_client } from './__gen__/channels';\nconst { postPostPing } = http_client;\n\n// Create a request payload\nconst pingMessage = new PingRequest({ message: 'Hello!' });\n\n// Make a simple request\nconst response = await postPostPing({\n payload: pingMessage,\n baseUrl: 'https://api.example.com'\n});\n\n// Access the response\nconsole.log(response.data.response); // The deserialized Pong\nconsole.log(response.status); // 200\nconsole.log(response.headers); // Response headers\nconsole.log(response.rawData); // Raw JSON response\n```\n
\n\n### From OpenAPI\n\nThe `http_client` protocol is also generated directly from an OpenAPI document (2.0/3.0/3.1). Each path + method becomes one function. Configure the `channels` generator with `inputType: 'openapi'` and `protocols: ['http_client']`.\n\nFunction names come from each operation's `operationId` (camel-cased). When an operation has **no** `operationId`, a name is synthesized from the method and path, e.g. `GET /v2/connect/{referenceId}` → `getV2ConnectReferenceId`. Give your operations `operationId`s for the cleanest client.\n\nAs a consumer you work with three generated pieces: the **call functions** (`http_client.ts`), the **request/response body models** (`payload/`), and the **path/query parameter models** (`parameter/`):\n\n```ts\nimport { http_client } from './__gen__/channels';\nimport { PostV2ConnectRequest } from './__gen__/channels/payload/PostV2ConnectRequest';\nimport { GetV2ConnectReferenceIdParameters } from './__gen__/channels/parameter/GetV2ConnectReferenceIdParameters';\n\n// Request with a body: build the model, pass it as `payload`.\nconst created = await http_client.postV2Connect({\n baseUrl: 'https://api.example.com',\n payload: new PostV2ConnectRequest({ returnUrl: 'https://shop.example/return' })\n});\nconsole.log(created.data.connectUrl); // typed response model\n\n// Request with a path parameter: supply it through the parameter model.\nconst connect = await http_client.getV2ConnectReferenceId({\n baseUrl: 'https://api.example.com',\n parameters: new GetV2ConnectReferenceIdParameters({ referenceId: 'ref_123' })\n});\nconsole.log(connect.data.safepayAccountId);\n```\n\nSee the runnable [`openapi-http-client` example](https://github.com/the-codegen-project/cli/tree/main/examples/openapi-http-client) for a complete, self-contained setup.\n\n## Base URL\n\nEvery generated call accepts an optional `baseUrl`. The value used at runtime follows this precedence, highest first:\n\n1. **`context.baseUrl`** passed to the call (e.g. `getUser({ baseUrl: 'https://api.example.com' })`) — always wins.\n2. **The document's first HTTP(S) server** — when the AsyncAPI `servers` (or OpenAPI `servers`) section declares an `http`/`https` server, its URL becomes the generated default. Non-HTTP servers (nats, kafka, …), relative URLs, and OpenAPI server URLs whose variables have no default are skipped.\n3. **`http://localhost:3000`** — the fallback when the document declares no usable HTTP(S) server.\n\nSo a document with `servers: [{ url: 'https://api.example.com' }]` generates clients that target `https://api.example.com` by default, and you only pass `baseUrl` to override it (for example, to point at a staging environment).\n\n## Authentication\n\nThe HTTP client uses a discriminated union for authentication, providing excellent TypeScript autocomplete support.\n\n### Bearer Token\n\n```typescript\nconst response = await postPostPing({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'bearer',\n token: 'your-jwt-token'\n }\n});\n```\n\n### Basic Authentication\n\n```typescript\nconst response = await postPostPing({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'basic',\n username: 'user',\n password: 'pass'\n }\n});\n```\n\n### API Key\n\n```typescript\n// API Key in header (default)\nconst response = await postPostPing({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'apiKey',\n key: 'your-api-key',\n name: 'X-API-Key', // Header name (default: 'X-API-Key')\n in: 'header' // 'header' or 'query'\n }\n});\n\n// API Key in query parameter\nconst response = await postPostPing({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'apiKey',\n key: 'your-api-key',\n name: 'api_key',\n in: 'query'\n }\n});\n```\n\n### OAuth2 Client Credentials\n\nFor server-to-server authentication:\n\n```typescript\nconst response = await postPostPing({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'oauth2',\n flow: 'client_credentials',\n clientId: 'your-client-id',\n clientSecret: 'your-client-secret',\n tokenUrl: 'https://auth.example.com/oauth/token',\n scopes: ['read', 'write'],\n onTokenRefresh: (tokens) => {\n // Called when tokens are obtained/refreshed\n console.log('New access token:', tokens.accessToken);\n }\n }\n});\n```\n\n### OAuth2 Password Flow\n\nFor legacy applications requiring username/password:\n\n```typescript\nconst response = await postPostPing({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'oauth2',\n flow: 'password',\n clientId: 'your-client-id',\n username: 'user@example.com',\n password: 'user-password',\n tokenUrl: 'https://auth.example.com/oauth/token',\n onTokenRefresh: (tokens) => {\n // Store tokens for future use\n saveTokens(tokens);\n }\n }\n});\n```\n\n### OAuth2 with Pre-obtained Token\n\nFor tokens obtained via browser-based flows (implicit, authorization code):\n\n```typescript\n// Token obtained from browser OAuth flow\nconst accessToken = getTokenFromBrowserFlow();\n\nconst response = await postPostPing({\n payload: message,\n baseUrl: 'https://api.example.com',\n auth: {\n type: 'oauth2',\n accessToken: accessToken,\n refreshToken: refreshToken, // Optional: for auto-refresh on 401\n tokenUrl: 'https://auth.example.com/oauth/token',\n clientId: 'your-client-id',\n onTokenRefresh: (tokens) => {\n // Update stored tokens\n updateStoredTokens(tokens);\n }\n }\n});\n```\n\n## Retry with Exponential Backoff\n\nConfigure automatic retry for failed requests:\n\n```typescript\nconst response = await postPostPing({\n payload: message,\n baseUrl: 'https://api.example.com',\n retry: {\n maxRetries: 3, // Maximum retry attempts (default: 3)\n initialDelayMs: 1000, // Initial delay before first retry (default: 1000)\n maxDelayMs: 30000, // Maximum delay between retries (default: 30000)\n backoffMultiplier: 2, // Exponential backoff multiplier (default: 2)\n retryableStatusCodes: [408, 429, 500, 502, 503, 504], // Status codes to retry\n retryOnNetworkError: true, // Retry on network failures\n onRetry: (attempt, delay, error) => {\n console.log(`Retry attempt ${attempt} after ${delay}ms: ${error.message}`);\n }\n }\n});\n```\n\n## Error Handling\n\nNon-OK HTTP responses **throw** a typed `HttpError` instead of returning. `HttpError` extends the built-in `Error` and carries the HTTP `status`, `statusText`, and the parsed response `body`:\n\n```typescript\nexport class HttpError extends Error {\n status: number;\n statusText: string;\n body?: unknown; // the parsed JSON error body, when present\n}\n```\n\nConsume it with an `instanceof` check:\n\n```typescript\nimport { getGetUser, HttpError } from './__gen__/channels/http_client';\n\ntry {\n const response = await getGetUser({ baseUrl: 'https://api.example.com' });\n // response.data is the typed, unmarshalled success payload\n} catch (error) {\n if (error instanceof HttpError) {\n console.error(error.status); // e.g. 404\n console.error(error.statusText); // e.g. 'Not Found'\n console.error(error.body); // parsed error body (unknown)\n }\n}\n```\n\n## Request/Response Hooks\n\nCustomize request behavior with hooks:\n\n```typescript\nconst response = await postPostPing({\n payload: message,\n baseUrl: 'https://api.example.com',\n hooks: {\n // Modify request before sending\n beforeRequest: async (params) => {\n console.log('Making request to:', params.url);\n // Add custom header\n return {\n ...params,\n headers: {\n ...params.headers,\n 'X-Request-ID': generateRequestId()\n }\n };\n },\n\n // Replace the default fetch implementation\n makeRequest: async (params) => {\n // Use axios, got, or any HTTP client\n const axiosResponse = await axios({\n url: params.url,\n method: params.method,\n headers: params.headers,\n data: params.body\n });\n return {\n ok: axiosResponse.status >= 200 && axiosResponse.status < 300,\n status: axiosResponse.status,\n statusText: axiosResponse.statusText,\n headers: axiosResponse.headers,\n json: () => axiosResponse.data\n };\n },\n\n // Process response after receiving\n afterResponse: async (response, params) => {\n console.log(`Response ${response.status} from ${params.url}`);\n return response;\n },\n\n // Handle errors\n onError: async (error, params) => {\n console.error(`Request failed: ${error.message}`);\n // Optionally transform the error\n return error;\n }\n }\n});\n```\n\n## Path Parameters\n\nFor operations with path parameters, the generator creates typed parameter classes:\n\n```typescript\nimport { UserItemsParameters } from './__gen__/parameters/UserItemsParameters';\n\n// Create parameters with type safety\nconst params = new UserItemsParameters({\n userId: 'user-123',\n itemId: 456\n});\n\nconst response = await getGetUserItem({\n baseUrl: 'https://api.example.com',\n parameters: params // Replaces {userId} and {itemId} in path\n});\n```\n\n## Typed Headers\n\nFor operations with defined headers, the generator creates typed header classes:\n\n```typescript\nimport { ItemRequestHeaders } from './__gen__/headers/ItemRequestHeaders';\n\nconst headers = new ItemRequestHeaders({\n xCorrelationId: 'corr-123',\n xRequestId: 'req-456'\n});\n\nconst response = await putUpdateUserItem({\n baseUrl: 'https://api.example.com',\n parameters: params,\n payload: itemData,\n requestHeaders: headers // Type-safe headers\n});\n```\n\n## Additional Headers and Query Parameters\n\nAdd custom headers or query parameters to any request:\n\n```typescript\nconst response = await postPostPing({\n payload: message,\n baseUrl: 'https://api.example.com',\n additionalHeaders: {\n 'X-Custom-Header': 'value',\n 'Accept-Language': 'en-US'\n },\n additionalQueryParams: {\n include: 'metadata',\n format: 'detailed'\n }\n});\n```\n\n## Multi-Status Responses\n\nFor operations that return different payloads based on status code, the generator creates union types:\n\n```yaml\n# AsyncAPI spec with multiple response types\noperations:\n getItem:\n reply:\n messages:\n - $ref: '#/components/messages/ItemResponse' # 200\n - $ref: '#/components/messages/NotFoundError' # 404\n```\n\n```typescript\nconst response = await getItemRequest({\n baseUrl: 'https://api.example.com',\n parameters: params\n});\n\n// Response type is union: ItemResponse | NotFoundError\n// Use response.status to discriminate\nif (response.status === 200) {\n console.log('Item:', response.data); // ItemResponse\n} else if (response.status === 404) {\n console.log('Not found:', response.data); // NotFoundError\n}\n```", }, + "protocols/http_server": { + title: "HTTP Server", + content: "# HTTP Server\n\nThe HTTP server generator creates typed [Express](https://expressjs.com/) handler stubs from your API specification — the structural inverse of the [HTTP client](./http_client.md). For every operation you get a `register(context)` function that mounts a route on a `Router` you supply, hands your handler typed path/query parameters, a typed request body and typed request headers, and marshals whatever your handler returns.\n\nIt is currently available through the generators ([channels](../generators/channels.md)).\n\nThis is available **only from [OpenAPI](../inputs/openapi.md) documents** (Swagger 2.0, OpenAPI 3.0 and 3.1). AsyncAPI input generates nothing for this protocol.\n\n## TypeScript\n\nDependency: [express](https://github.com/expressjs/express) v4.\n\n| **Feature** | Is supported? |\n|---|---|\n| Typed path & query parameters | ✅ |\n| Typed request headers | ✅ |\n| Typed request body | ✅ |\n| Typed, status-code-discriminated responses | ✅ |\n| Request payload validation | ✅ (via the [`payloads`](../generators/payloads.md) generator's `includeValidation`) |\n| Handler hooks (before/after/onError) | ✅ |\n| Router mounting under a prefix | ✅ |\n| JSON based API | ✅ |\n| XML based API | ❌ |\n| Authentication / authorization enforcement | ❌ (see [Security requirements](#security-requirements)) |\n| Typed response headers | ❌ |\n| Frameworks | Express |\n| Server / listener construction | ❌ (you construct and mount the router) |\n| POST / GET / PUT / PATCH / DELETE / HEAD / OPTIONS | ✅ |\n\n## Configuration\n\n```js\nexport default {\n inputType: 'openapi',\n inputPath: './openapi.json',\n generators: [\n {\n preset: 'channels',\n outputPath: './src/__gen__/channels',\n language: 'typescript',\n protocols: ['http_server']\n }\n ]\n};\n```\n\n`http_server` and `http_client` can be listed together. They produce two independent files, each with its own copy of the shared types (including `HttpError`), so generating both sides of the same document is a supported and useful setup — see the [`openapi-http-server` example](https://github.com/the-codegen-project/cli/tree/main/examples/openapi-http-server).\n\n## What is generated\n\nFor each operation, three things:\n\n| Generated | What it is |\n|---|---|\n| `ServerResponse` | A status-code-discriminated union of everything the operation may answer with, assembled from the operation's declared `responses`. |\n| `RegisterContext` | The register function's argument: `router`, your `callback`, and the shared `HttpServerContext` options. |\n| `register(context)` | Mounts the route and handles parsing, parameter extraction, header deserialization, validation, response marshalling and error mapping. |\n\n```ts\nexport type GetPetByIdServerResponse =\n | {status: 200; body: APetInterface | APet; headers?: Record}\n | {status: 404; headers?: Record};\n\nexport interface RegisterGetPetByIdContext extends HttpServerContext {\n router: Router;\n callback: (params: {\n parameters: GetPetByIdParameters;\n requestHeaders: GetPetByIdHeaders;\n request: Request;\n }) => GetPetByIdServerResponse | Promise;\n}\n```\n\nUsing it:\n\n```ts\nimport {Router} from 'express';\nimport {registerGetPetById} from './__gen__/channels/http_server';\n\nconst router = Router();\n\nregisterGetPetById({\n router,\n callback: ({parameters}) => {\n const pet = petStore.get(parameters.petId);\n if (!pet) {\n return {status: 404}; // declared by the document\n }\n return {status: 200, body: pet};\n }\n});\n```\n\nReturning a status the document does not declare is a **compile error**, not a runtime surprise.\n\n### The handler callback\n\nThe callback takes a single destructured object:\n\n| Field | When it is present |\n|---|---|\n| `body` | Body-carrying methods (`POST`, `PUT`, `PATCH`) whose request body has a JSON schema. Already unmarshalled into the payload model. |\n| `parameters` | The operation declares path or query parameters. A parsed instance of the generated parameter model. |\n| `requestHeaders` | The operation declares header parameters. A typed object produced by the generated `deserializeHeaders`. |\n| `request` | Always. The raw Express `Request`, for anything not modelled (cookies, raw auth headers, the socket). |\n\nThe callback's return value is the response — `response` and `next` are not passed in. Use `request` for anything the models do not cover.\n\nThe returned `body` accepts either a plain object literal or a model instance — object bodies are normalized to the model before `marshal()`, so the wire-name mapping is always applied.\n\n## `HttpServerContext`\n\nEvery `RegisterContext` extends it:\n\n| Option | Type | Description |\n|---|---|---|\n| `additionalHeaders` | `Record` | Headers added to every response the route sends. A per-response `headers` field wins over these. |\n| `hooks` | `HttpServerHooks` | `beforeHandler`, `afterHandler` and `onError` — see below. |\n| `skipRequestValidation` | `boolean` | Skip validating the incoming request payload against its JSON Schema. |\n\n### Hooks\n\n```ts\nexport interface HttpServerHooks {\n beforeHandler?: (params: {request: Request}) => void | Promise;\n afterHandler?: (params: {request: Request; status: number; body?: string}) => void | Promise;\n onError?: (params: {error: HttpGlobalError; request: Request}) =>\n {status: number; body?: unknown} | undefined | Promise<{status: number; body?: unknown} | undefined>;\n}\n```\n\n`beforeHandler` runs before the request is read — throw an `HttpError` there to reject a request before it reaches your handler. `afterHandler` receives the JSON text that was sent. `onError` may return a replacement response, or `undefined` to keep the mapped one.\n\n## Errors\n\nThrow an `HttpError` (exported from the generated file) to answer with a specific status:\n\n```ts\nthrow new HttpError('pet is not for sale', 409, 'Conflict', {petId});\n```\n\nAnything else you throw maps to a generic `500` — an internal error message is **never** leaked into the response body. If the response has already started (`headersSent`), the error is passed to Express' error middleware instead, so mount one if you need to observe those.\n\n`HttpError` is shape-compatible with the one the generated HTTP client throws, so the same class reads the same on both sides of the wire.\n\n## Request validation\n\nWhen the [`payloads`](../generators/payloads.md) generator has `includeValidation` enabled (the default), request bodies are validated against their JSON Schema before your callback runs. A failing body is answered with `400` and the validation causes. Validation costs no per-request compilation — the validator is built when the route is registered.\n\nThere is no separate configuration option — set `skipRequestValidation: true` on the context to turn it off per route.\n\n## Mounting and prefixes\n\nGenerated code never calls `app.listen`, never constructs a `Router` and never mounts anything:\n\n```ts\nconst app = express();\napp.use(express.json()); // optional — the stubs also read the raw stream\napp.use('/api/v2', router);\n```\n\nMounting under a prefix needs no extra configuration — there is no `basePath` option. Express makes `request.url` mount-relative, so path parameters resolve the same whether the router is mounted at `/` or at `/api/v2`.\n\n`express.json()` is optional. `readJsonBody` returns an already-parsed body when a body parser populated one, and otherwise reads the raw stream itself.\n\n## Multiple response bodies\n\nWhen an operation declares several body-carrying responses, the response payload becomes a *union* model. A non-object member of that union — an array or a primitive — has no importable module of its own, so its body is marshalled with `JSON.stringify` rather than the model's `marshal()`, and no wire-name mapping is applied to that variant. If the operation's schemas rename properties on the wire, return an object variant for those responses. Single-response operations and object union members are unaffected.\n\n## Security requirements\n\nPer-operation `security` requirements are read from the document but not enforced: no credential verification is generated. Mount your own middleware on the router before the generated routes, and throw an [`HttpError`](#errors) from it to reject a request.", + }, "protocols/kafka": { title: "Kafka", content: "# Kafka\nKafka is currently supported through the following generators ([channels](#channels)):\n\n| **Languages** | Publish | Subscribe\n|---|---|---|\n| TypeScript | ✅ | ✅ |\n\nAll of this is available through [AsyncAPI](../inputs/asyncapi.md). If you use \n\n## Channels\nRead more about the [channels](../generators/channels.md) generator here before continuing.\n\nThis generator provides support functions for each resource ensuring you the right payload and parameter are used. \n\n\n \n \n \n \n\n\n \n \n \n \n\n
Input (AsyncAPI)Using the code
\n\n```yaml\nasyncapi: 3.0.0\ninfo:\n title: Account Service\n version: 1.0.0\n description: This service is in charge of processing user signups\nchannels:\n userSignups:\n address: user/signedup\n messages:\n userSignedup:\n $ref: '#/components/messages/UserSignedUp'\noperations:\n publishUserSignups:\n action: send\n channel:\n $ref: '#/channels/userSignups'\n consumeUserSignups:\n action: receive\n channel:\n $ref: '#/channels/userSignups'\ncomponents:\n messages:\n UserSignedUp:\n payload:\n type: object\n properties:\n displayName:\n type: string\n description: Name of the user\n email:\n type: string\n format: email\n description: Email of the user\n\n```\n\n\n```ts\nimport { Kafka } from 'kafkajs';\n// Location depends on the payload generator configurations\nimport { UserSignedup } from './__gen__/payloads/UserSignedup';\n// Location depends on the channel generator configurations\nimport { kafka } from './__gen__/channels';\nconst { consumeFromConsumeUserSignups, produceToPublishUserSignups } = kafka;\n\n/**\n * Setup the regular client\n */\nconst kafkaClient = new Kafka({\n clientId: 'test',\n brokers: ['localhost:9093'],\n});\n\nconst myPayload = new UserSignedup({displayName: 'test', email: 'test@test.dk'});\n\n// Consume the messages with the generated channel function\nconst consumerCallback = (\n err?: Error,\n msg?: UserSignedup,\n parameters?: UserSignedupParameters,\n headers?: UserSignedupHeaders,\n kafkaMsg?: EachMessagePayload\n ) => {\n // Do stuff once you consume from the topic\n};\nconst consumer = await consumeFromConsumeUserSignups({\n onDataCallback: consumerCallback,\n parameters: myParameters,\n kafka: kafkaClient,\n options: {\n fromBeginning: true,\n groupId: 'testId1'\n }\n});\n\n// Produce the messages with the generated channel function\nconst producer = await produceToPublishUserSignups({\n message: myPayload,\n parameters: myParameters,\n kafka: kafkaClient\n});\n```\t\n
", @@ -144,7 +148,7 @@ export const docs: Record = { }, "usage": { title: "Untitled", - content: "\n```sh-session\n$ npm install -g @the-codegen-project/cli\n$ codegen COMMAND\nrunning command...\n$ codegen (--version)\n@the-codegen-project/cli/0.81.1 linux-x64 node-v22.23.1\n$ codegen --help [COMMAND]\nUSAGE\n $ codegen COMMAND\n...\n```\n\n\n## Table of contents\n\n\n\n\n\n## Commands\n\n\n* [`codegen autocomplete [SHELL]`](#codegen-autocomplete-shell)\n* [`codegen generate [FILE]`](#codegen-generate-file)\n* [`codegen help [COMMAND]`](#codegen-help-command)\n* [`codegen init`](#codegen-init)\n* [`codegen telemetry ACTION`](#codegen-telemetry-action)\n* [`codegen version`](#codegen-version)\n\n## `codegen autocomplete [SHELL]`\n\nDisplay autocomplete installation instructions.\n\n```\nUSAGE\n $ codegen autocomplete [SHELL] [-r]\n\nARGUMENTS\n SHELL (zsh|bash|powershell) Shell type\n\nFLAGS\n -r, --refresh-cache Refresh cache (ignores displaying instructions)\n\nDESCRIPTION\n Display autocomplete installation instructions.\n\nEXAMPLES\n $ codegen autocomplete\n\n $ codegen autocomplete bash\n\n $ codegen autocomplete zsh\n\n $ codegen autocomplete powershell\n\n $ codegen autocomplete --refresh-cache\n```\n\n_See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v3.2.45/src/commands/autocomplete/index.ts)_\n\n## `codegen generate [FILE]`\n\nGenerate code based on your configuration, use `init` to get started, `generate` to generate code from the configuration.\n\n```\nUSAGE\n $ codegen generate [FILE] [--json] [--no-color] [--debug | [-q | -v | --silent] | ] [--help] [-w] [-p\n ]\n\nARGUMENTS\n FILE Path or URL to the configuration file, defaults to root of where the command is run\n\nFLAGS\n -p, --watchPath= Optional path to watch for changes when --watch flag is used. If not provided, watches the\n input file from configuration\n -q, --quiet Only show errors and warnings\n -v, --verbose Show detailed output\n -w, --watch Watch for file changes and regenerate code automatically\n --debug Show debug information\n --help Show CLI help.\n --json Output results as JSON for scripting\n --no-color Disable colored output\n --silent Suppress all output except fatal errors\n\nDESCRIPTION\n Generate code based on your configuration, use `init` to get started, `generate` to generate code from the\n configuration.\n```\n\n_See code: [src/commands/generate.ts](https://github.com/the-codegen-project/cli/blob/v0.81.1/src/commands/generate.ts)_\n\n## `codegen help [COMMAND]`\n\nDisplay help for codegen.\n\n```\nUSAGE\n $ codegen help [COMMAND...] [-n]\n\nARGUMENTS\n COMMAND... Command to show help for.\n\nFLAGS\n -n, --nested-commands Include all nested commands in the output.\n\nDESCRIPTION\n Display help for codegen.\n```\n\n_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.0.22/src/commands/help.ts)_\n\n## `codegen init`\n\nInitialize The Codegen Project in your project\n\n```\nUSAGE\n $ codegen init [--json] [--no-color] [--debug | | [--silent | -v | -q]] [--help] [--input-file ]\n [--config-name ] [--input-type asyncapi|openapi|jsonschema] [--output-directory ] [--config-type\n esm|json|yaml|ts] [--languages typescript] [--channels-protocols\n nats|kafka|mqtt|amqp|event_source|http_client|websocket] [--no-tty] [--include-payloads] [--include-headers]\n [--include-client] [--include-parameters] [--include-channels] [--include-types] [--include-models]\n [--gitignore-generated]\n\nFLAGS\n -q, --quiet Only show errors and warnings\n -v, --verbose Show detailed output\n --channels-protocols=