Merge branch 'master' into docs/rewrite-template-tutorial-v3

Author: derberg

.dockerignore

@@ -39,3 +39,5 @@ test-results
 **/Dockerfile
 **/docker-compose*.yml
 **/docker-compose*.yaml
+!**/template/**/docker-compose*.yml
+!**/template/**/docker-compose*.yaml

.github/workflows/scripts/mailchimp/package-lock.json

@@ -31,7 +31,7 @@ git clone https://github.com/{your_username}/generator.git
 cd generator
 ```
 
-After cloning the repository, you should setup the fork properly and configure the `remote` repository as described [here](https://github.com/asyncapi/community/blob/master/git-workflow.md)
+After cloning the repository, you should setup the fork properly and configure the `remote` repository as described in the [AsyncAPI git workflow guidelines](https://github.com/asyncapi/community/blob/master/docs/010-contribution-guidelines/git-workflow.md)
 
 2. Install dependencies:
 
@@ -195,7 +195,7 @@ For the PR titles you can refer to [this guide](CONTRIBUTING.md?plain=1#L60)
 
 If you encounter any issues during development or testing, please check the following:
 
-1. Ensure you're using the correct Node.js version (18.20.8 or higher) and npm version (10.8.2 or higher).
+1. Ensure you're using the correct Node.js version (24.11 or higher) and npm version (11.5.1 or higher).
 2. Clear the `node_modules` directory and reinstall dependencies if you encounter unexpected behavior.
 3. For Docker-related issues, make sure Docker is running and you have sufficient permissions.
 

Development.md

@@ -1,4 +1,4 @@
-ARG NODE_VERSION=18
+ARG NODE_VERSION=24.11
 FROM node:${NODE_VERSION}-alpine AS base
 
 WORKDIR /app
@@ -28,6 +28,7 @@ FROM base AS final
 
 # Copy package.json files extracted by turbo prune
 COPY --from=installer /out/json/ .
+COPY --from=installer /app/jest.config.base.js ./jest.config.base.js
 COPY --from=installer /out/package-lock.json ./package-lock.json
 
 # Install dependencies only with package.json files to make use of cache
@@ -36,6 +37,9 @@ RUN npm ci --ignore-scripts
 # Copy the rest of the source code
 COPY --from=installer /out/full/ .
 
+# turbo prune excludes runtime template assets
+COPY --from=installer /app/packages/templates ./packages/templates
+
 # Change ownership of the /app directory to the node user
 RUN chown -R node:node /app
 

Dockerfile

@@ -1,5 +1,83 @@
 # @asyncapi/generator
 
+## 3.1.2
+
+### Patch Changes
+
+- 4a09f57: Bump @asyncapi/parser to 3.6.0 to support AsyncAPI 3.1.0
+
+## 3.1.1
+
+### Patch Changes
+
+- 2bfad27: Fix generator handling of template parameters with `false` default values, ensuring defaults are correctly injected and conditional generation works as expected.
+
+## 3.1.0
+
+### Minor Changes
+
+- 11a1b8d: - **Updated Component**: `OnMessage` (Python) - Added discriminator-based routing logic that automatically dispatches messages to operation-specific handlers before falling back to generic handlers
+
+  - **New Helpers**:
+    - `getMessageDiscriminatorData` - Extracts discriminator key and value from individual messages
+    - `getMessageDiscriminatorsFromOperations` - Collects all discriminator metadata from receive operations
+  - Enhanced Python webSocket client generation with **automatic operation-based message routing**:
+
+  ## How python routing works
+
+  - Generated WebSocket clients now automatically route incoming messages to operation-specific handlers based on message discriminators. Users can register handlers for specific message types without manually parsing or filtering messages.
+  - When a message arrives, the client checks it against registered discriminators (e.g., `type: "hello"`, `type: "events_api"`)
+  - If a match is found, the message is routed to the specific operation handler (e.g., `onHelloMessage`, `onEvent`)
+  - If no match is found, the message falls back to generic message handlers
+  - This enables clean separation of message handling logic based on message types
+
+  > `discriminator` is a `string` field that you can add to any AsyncAPI Schema. This also means that it is limited to AsyncAPI Schema only, and it won't work with other schema formats, like for example, Avro.
+
+  The implementation automatically derives discriminator information from your AsyncAPI document:
+
+  - Discriminator `key` is extracted from the `discriminator` field in your AsyncAPI spec
+  - Discriminator `value` is extracted from the `const` property defined in message schemas
+
+  Example AsyncAPI Schema with `discriminator` and `const`:
+
+  ```yaml
+  schemas:
+    hello:
+      type: object
+      discriminator: type # you specify name of property
+      properties:
+        type:
+          type: string
+          const: hello # you specify the value of the discriminator property that is used for routing
+          description: A hello string confirming WebSocket connection
+  ```
+
+  ## Fallback
+
+  When defaults aren't available in the AsyncAPI document, users must provide **both** `discriminator_key` and `discriminator_value` when registering handlers. Providing only one parameter is not supported - you must provide either both or neither.
+
+  > **Why this limitation exists**: When a receive operation has multiple messages sharing the same discriminator key (e.g., all use `"type"` field), we need the specific value (e.g., `"hello"`, `"disconnect"`) to distinguish between them. Without both pieces of information, the routing becomes ambiguous.
+
+  Example:
+
+  ```python
+  # Default case - discriminator info auto-derived from AsyncAPI doc
+  client.register_on_hello_message_handler(my_handler)
+
+  # Custom case - must provide both key AND value
+  client.register_on_hello_message_handler(
+      my_handler,
+      discriminator_key="message_type",
+      discriminator_value="custom_hello"
+  )
+  ```
+
+### Patch Changes
+
+- Updated dependencies [11a1b8d]
+  - @asyncapi/generator-components@0.5.0
+  - @asyncapi/generator-helpers@1.1.0
+
 ## 3.0.1
 
 ### Patch Changes

apps/generator/CHANGELOG.md

@@ -159,7 +159,7 @@ The `generator` property from `package.json` file must contain a JSON object and
 | `conditionalFiles[filePath].validation` | Object | The `validation` is a JSON Schema Draft 07 object. This JSON Schema definition will be applied to the JSON value resulting from the `subject` query. If validation doesn't have errors, the condition is met, and therefore the given file will be rendered. Otherwise, the file is ignored. Check [JSON Schema Validation](https://json-schema.org/draft-07/json-schema-validation.html#rfc.section.6) for a list of all possible validation keywords. **Note: It is deprecated and will be removed with future releases. Use `conditionalGeneration` instead.** |
 | `conditionalGeneration` | Object[String, `{ subject?: String, parameter?: String, validation: Object }`] | An object containing all the file paths or directory names that should be conditionally rendered. Each key represents a file path or directory name and each value must be an object with the keys `subject`, `parameter` and `validation`. You can use either subject or parameter according to the use case. The path should be relative to the `template` directory inside the template. **Note: conditionalGeneration and conditionalFile are mutually exclusive, which means both cannot be configured at the same time in the template**. |
 | `conditionalGeneration[filePath/directoryName].subject` | String | The `subject` is a [JMESPath](http://jmespath.org/) query to grab the value you want to apply the condition to. It queries an object with the whole AsyncAPI document and, when specified, the given server. The object looks like this: `{ asyncapi: { ... }, server: { ... } }`. If the template supports the `server` parameter, you can access server details like, for example, protocol this way: `server.protocol`. During validation with `conditionalGeneration`, only the server that the template user selected is available in the specification file. For more information about the `server` parameter [read about special parameters](#special-parameters). |
-| `conditionalGeneration[filePath/directoryName].parameter` | String | The `parameter` is the name of a custom template parameter passed through `templateParams` that controls whether a specific file or folder should be included in the generated output. You must define a `validation` rule using a JSON Schema fragment to apply the condition. For example, if you define `"parameter": "includeDocs"` with `"validation": { "const": true }`, the corresponding folder (e.g., `docs/`) will only be generated when the user passes `{ includeDocs: true }`. If `includeDocs` is `false`, it will be skipped. |
+| `conditionalGeneration[filePath/directoryName].parameter` | String | The `parameter` is the name of a custom template parameter passed through `templateParams` that controls whether a specific file or folder should be included in the generated output. You must define a `validation` rule using a JSON Schema fragment to apply the condition. For example, if you define `"parameter": "includeDocs"` with `"validation": { "const": true }`, the corresponding folder (e.g., `docs/`) will only be generated when the user passes `{ includeDocs: true }`. If `includeDocs` is `false`, it will be skipped. When you rely on a parameter here, make sure its default value declared in the `parameters` section uses the same data type your validation expects; mismatched types lead to failing conditions even when the defaults should allow generation. |
 | `conditionalGeneration[filePath/directoryName].validation` | Object (JSON Schema fragment) | The validation defines the condition under which the file or directory will be generated. It must be a valid JSON Schema fragment that validates the value of the parameter. For example, if you want to include a folder only when includeDocs is true, use "validation": `{ "const": true }`. You can also use more complex validation logic, like "enum": ["yes", "true"] or "type": "string" with a "pattern" constraint. If the parameter fails validation, the file or folder will not be included in the generated output. This allows for powerful and flexible control over template generation based on user input. |
 | `nonRenderableFiles` | [String] | A list of file paths or [globs](https://en.wikipedia.org/wiki/Glob_(programming)) that must be copied "as-is" to the target directory, i.e., without performing any rendering process. This is useful when you want to copy binary files. |
 | `generator` | [String] | A string representing the generator version-range the template is compatible with. This value must follow the [semver](https://nodejs.dev/learn/semantic-versioning-using-npm) syntax. E.g., `>=1.0.0`, `>=1.0.0 <=2.0.0`, `~1.0.0`, `^1.0.0`, `1.0.0`, etc. [Read more about semver](https://docs.npmjs.com/about-semantic-versioning). |

apps/generator/docs/configuration-file.md

@@ -5,7 +5,7 @@ weight: 200
 
 This guide will walk you through the process of enabling models/types generation in a template by using [Modelina](https://www.asyncapi.com/tools/modelina).
 
-Modelina is an AsyncAPI library designed for generating data models using inputs such as [AsyncAPI](generator/asyncapi-document), OpenAPI, or JSON schema inputs. Its functionality revolves around creating data models from the provided AsyncAPI document and the model template, which defines message payloads. It is better to use Modelina in your template to handle model generation rather than providing custom templates.
+Modelina is an AsyncAPI library designed for generating data models using inputs such as [AsyncAPI](asyncapi-document), OpenAPI, or JSON schema inputs. Its functionality revolves around creating data models from the provided AsyncAPI document and the model template, which defines message payloads. It is better to use Modelina in your template to handle model generation rather than providing custom templates.
 
 You can integrate the work shown in this guide into a template by following the [tutorial about creating a template](https://www.asyncapi.com/docs/tools/generator/generator-template).
 

apps/generator/docs/model-generation.md

@@ -29,7 +29,7 @@ Baked-in templates benefit from:
 
 In contrast, **standalone templates** (described below) are maintained as independent Node.js packages, may live in separate repositories, and can be managed or installed separately from the core generator.
 
-Learn more from document [Baked-in Templates](#baked-in-templates).
+Learn more from document [Baked-in Templates](baked-in-templates).
 
 ### Standalone templates
 

apps/generator/docs/template.md

@@ -40,29 +40,29 @@ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template
 
 **The shortest possible syntax:**
 ```bash
-asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.5.4
 ```
 
 **Generating from a URL:**
 ```bash
-asyncapi generate fromTemplate https://bit.ly/asyncapi @asyncapi/html-template@3.0.0 --use-new-generator
+asyncapi generate fromTemplate https://bit.ly/asyncapi @asyncapi/html-template@3.5.4 
 ```
 
 **Specify where to put the result:**
 ```bash
-asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator -o ./docs
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.5.4 -o ./docs
 ```
 
 **Passing parameters to templates:**
 ```bash
-asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator -o ./docs -p title='Hello from param'
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.5.4  -o ./docs -p title='Hello from param'
 ```
 
-In the template you can use it like this: ` {{ params.title }}`
+In the template you can use it like this: `{{ params.title }}`
 
 **Disabling the hooks:**
 ```bash
-asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator -o ./docs -d generate:before generate:after=foo,bar
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.5.4 -o ./docs -d generate:before generate:after=foo,bar
 ```
 
 The generator skips all hooks of the `generate:before` type and `foo`, `bar` hooks of the `generate:after` type.
@@ -81,7 +81,7 @@ asyncapi generate fromTemplate asyncapi.yaml https://github.com/asyncapi/html-te
 
 **Map schema references from baseUrl to local folder:**
 ```bash
-asyncapi generate fromTemplate test/docs/apiwithref.json @asyncapi/html-template@3.0.0 --use-new-generator -o ./build/ --force-write --map-base-url https://schema.example.com/crm/:./test/docs/
+asyncapi generate fromTemplate test/docs/apiwithref.json @asyncapi/html-template@3.5.4 -o ./build/ --force-write --map-base-url https://schema.example.com/crm/:./test/docs/
 ```
 
 The parameter `--map-base-url` maps external schema references to local folders.
@@ -104,7 +104,7 @@ docker run --rm -it \
    --user=root \
    -v ${PWD}/test/fixtures/asyncapi_v1.yml:/app/asyncapi.yml \
    -v ${PWD}/output:/app/output \
-   asyncapi/cli generate fromTemplate -o /app/output /app/asyncapi.yml @asyncapi/html-template@3.0.0 --use-new-generator --force-write
+   asyncapi/cli generate fromTemplate -o /app/output /app/asyncapi.yml @asyncapi/html-template@3.5.4 --force-write
 ```
 Note: Use ``` ` ``` instead of `\` for Windows.
 
@@ -115,7 +115,7 @@ Note: Use ``` ` ``` instead of `\` for Windows.
 Use the following npx command on your terminal:
 
 ```bash
-npx -p @asyncapi/cli asyncapi generate fromTemplate ./asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator
+npx -p @asyncapi/cli asyncapi generate fromTemplate ./asyncapi.yaml @asyncapi/html-template@3.5.4 
 ```
 
 ## Using as a module/package

apps/generator/docs/usage.md

@@ -18,10 +18,9 @@ It is better to lock a specific version of the template and the generator if you
 Generate HTML with the latest AsyncAPI CLI using the html-template.
 ```
 npm install -g @asyncapi/cli
-asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.5.4
 ```
 
-> AsyncAPI CLI has multiple versions of the generator, and to use the latest version, you may need to pass the `--use-new-generator` flag. For more details you can also check [asyncapi generate fromTemplate ASYNCAPI TEMPLATE](https://www.asyncapi.com/docs/tools/cli/usage#asyncapi-generate-fromtemplate-asyncapi-template)
 
 Generate HTML using a particular version of the AsyncAPI CLI using the html-template.