feat: add headers validation (#223)

- Fixed header property names not being accurate
- Added filtering on the website blog post to only show those who are live i.e. date is past.
- Added AsyncAPI headers example
- Added AsyncAPI headers blog post
- Added AsyncAPI payloads example
- Added AsyncAPI payloads blog post
- Improved headers docs
- Added headers validation functions

Author: jonaslagoni

docs/configurations.md

@@ -12,6 +12,23 @@ For example, with the [`custom`](./generators/custom.md) generator, you provide
 
 Reason those two exist, is because adding a `.js` configuration file to a Java project, might confuse developers, and if you dont need to take advantage of the customization features that require callback, it will probably be better to use one of the other two.
 
+## Creating Configurations with the CLI
+
+The easiest way to create a configuration file is by using the `codegen init` command. This interactive command will guide you through setting up a configuration file for your project, allowing you to specify:
+
+- Input file (AsyncAPI or OpenAPI document)
+- Configuration file type (`esm`, `json`, `yaml`, `ts`)
+- Output directory
+- Language and generation options
+
+```sh
+codegen init --input-file ./ecommerce.yml --input-type asyncapi --config-type ts --languages typescript
+```
+
+For detailed usage instructions and all available options, see the [CLI usage documentation](./usage.md#codegen-init).
+
+## Configuration File Lookup
+
 If no explicit configuration file is sat, it will be looked for in the following order:
 - package.json
 - .codegenrc

docs/generators/headers.md

@@ -35,3 +35,33 @@ The return type is a map of channels and the model that represent the headers.
 The `headers` preset with `openapi` input generates all the headers for each path in the OpenAPI document.
 
 The return type is a map of paths and the model that represent the headers. 
+
+## Typescript
+Dependencies: 
+- If validation enabled, [ajv](https://ajv.js.org/guide/getting-started.html): ^8.17.1
+
+### Validation
+Each generated class includes built-in JSON Schema validation capabilities through two static methods:
+
+- `validate`: Validates headers against the schema. Use this method when you want to validate data.
+
+```typescript
+// Example
+const result = UserSignedUpHeaders.validate({ data: headers });
+if (!result.valid) {
+  console.error('Validation errors:', result.errors);
+}
+```
+
+- `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.
+
+```typescript
+// Example
+const validator = UserSignedUpHeaders.createValidator();
+const result = UserSignedUpHeaders.validate({ data: headers, ajvValidatorFunction: validator });
+if (!result.valid) {
+  console.error('Validation errors:', result.errors);
+}
+```
+
+Both methods support custom Ajv instances and options for advanced validation scenarios.

docs/migrations/v0.md

@@ -57,10 +57,3 @@ const subscriber = await jetStreamPullSubscribeToReceiveUserSignedup({
   config
 });
 ```
-
-
-
-
-
-
-

examples/README.md

@@ -10,5 +10,18 @@ A complete example showing how to generate a TypeScript library from OpenAPI spe
 ### [TypeScript Next.js](./typescript-nextjs/)
 An example demonstrating integration with Next.js applications.
 
-### [E-commerce Payload Models](./ecommerce-payloads/)
+### [E-commerce AsyncAPI Payload](./ecommerce-asyncapi-payload/)
 A comprehensive example showing how to generate TypeScript payload models from AsyncAPI specifications for an e-commerce order processing system.
+
+### [E-commerce AsyncAPI Headers](./ecommerce-asyncapi-headers/)
+A comprehensive example showing how to generate TypeScript header models from AsyncAPI specifications for an e-commerce messaging system, covering authentication, tracing, routing, and metadata management.
+
+## Getting Started
+
+1. Choose an example that matches your use case
+2. Copy the relevant files to your project
+3. Modify the configuration to match your specifications
+4. Run the generator
+5. Integrate the generated code into your application
+
+For more detailed information, see the [documentation](https://the-codegen-project.org/docs/).

examples/ecommerce-asyncapi-headers/README.md

@@ -0,0 +1,30 @@
+# E-commerce Header Models
+A comprehensive example showing how to generate TypeScript header models from AsyncAPI specifications for an e-commerce messaging system.
+
+**Files:**
+- `ecommerce-messaging-system.yaml` - AsyncAPI specification with comprehensive header patterns
+- `codegen.config.js` - Configuration for generating TypeScript header models
+- `src/index.ts` - Demo script showing header usage patterns
+- `src/generated` - All the generated files
+
+**Features demonstrated:**
+- Authentication headers (JWT tokens, API keys)
+- Distributed tracing headers (correlation IDs, request IDs)
+- Multi-tenant routing headers
+- Event metadata headers (actor info, reason codes, priorities)
+- Payment processing headers (provider info, risk scores, idempotency)
+- Type-safe TypeScript classes with serialization/deserialization
+
+**Usage:**
+```bash
+# Install dependencies
+npm install
+
+# Generate header models
+npm run generate
+
+# Run the demo script
+npm run demo
+```
+
+The generated header models can be used with any messaging infrastructure (NATS, Kafka, RabbitMQ, HTTP APIs, etc.) while providing type safety and automatic serialization.

examples/ecommerce-asyncapi-headers/codegen.config.js

@@ -0,0 +1,39 @@
+/**
+ * Configuration file for generating header models from the e-commerce AsyncAPI specification
+ * 
+ * This configuration demonstrates how to set up The Codegen Project to generate
+ * TypeScript header models from an AsyncAPI document.
+ * 
+ * Usage:
+ * 1. Place this file in your project root
+ * 2. Run: npx @the-codegen-project/cli generate
+ * 
+ * The generated models will include:
+ * - Type-safe TypeScript classes for message headers
+ * - Serialization/deserialization methods
+ * - Support for complex header patterns like authentication, tracing, and metadata
+ */
+
+/** @type {import("@the-codegen-project/cli").TheCodegenConfiguration} **/
+export default {
+  // Input specification type and path
+  inputType: 'asyncapi',
+  inputPath: './ecommerce-messaging-system.yaml',
+  
+  // Global language setting
+  language: 'typescript',
+  
+  // Generator configuration
+  generators: [
+    {
+      // Use the headers preset for generating header models
+      preset: 'headers',
+      
+      // Output directory for generated header models
+      outputPath: './src/generated/headers',
+      
+      // Serialization type
+      serializationType: 'json'
+    }
+  ]
+};