@chanx-js/codegen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Huy Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @chanx-js/codegen
+
+Generate typed channel descriptors for the [`@chanx-js/client`](https://www.npmjs.com/package/@chanx-js/client)
+WebSocket client from a [chanx](https://github.com/huynguyengl99/chanx) AsyncAPI 3 schema.
+
+**[Documentation](https://huynguyengl99.github.io/chanx-js/guide/codegen)**
+
+```bash
+npx @chanx-js/codegen http://localhost:8000/asyncapi.json -o src/generated
+```
+
+- TypeScript output by default, or JavaScript with `.d.ts` via `--emit js`.
+- Optional zod validators with `--validation zod`.
+- Reuse types you already have with `--reuse-from`, and check they still match the
+  schema with `--reuse-strict`.
+
+MIT licensed.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/cli.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { n as generate, t as loadSchema } from "./loader-DtCKhsCU.mjs";
+import { cac } from "cac";
+//#region src/cli.ts
+const cli = cac("chanx-codegen");
+cli.command("[schema]", "Generate a typed client from a chanx AsyncAPI 3 schema").option("-s, --schema <input>", "URL or path to the AsyncAPI document").option("-o, --out <dir>", "Output directory", { default: "src/generated" }).option("--validation <mode>", "none | zod", { default: "none" }).option("--emit <target>", "ts | js (js writes .js alongside .d.ts)", { default: "ts" }).option("--reuse-from <glob>", "Glob of files declaring types to reuse (repeatable)").option("--reuse-strict", "Emit compile-time assertions that reused types still match").option("--ambient", "Skip reused types without importing them (global script output)").option("--alias <mapping>", "Import path rewrite, e.g. src/=@/ (repeatable)").option("--no-format", "Skip prettier formatting").action(async (positional, flags) => {
+	const input = flags.schema ?? positional;
+	if (!input) {
+		console.error("Pass a schema: chanx-codegen <url|path> -o src/generated");
+		process.exit(1);
+	}
+	const alias = Object.fromEntries(toArray(flags.alias).map((entry) => {
+		const index = entry.indexOf("=");
+		if (index === -1) throw new Error(`--alias expects prefix=replacement, got "${entry}"`);
+		return [entry.slice(0, index), entry.slice(index + 1)];
+	}));
+	console.log(`Loading ${input}`);
+	const document = await loadSchema(input);
+	console.log(`  ${document.info?.title ?? "untitled"} ${document.info?.version ?? ""}`);
+	const result = await generate(document, {
+		outDir: flags.out,
+		validation: flags.validation,
+		emit: flags.emit,
+		reuseFrom: toArray(flags.reuseFrom),
+		reuseStrict: Boolean(flags.reuseStrict),
+		ambient: Boolean(flags.ambient),
+		alias,
+		format: flags.format !== false
+	});
+	console.log(`  ${result.channels} channels, ${result.topics} topics, ${result.generatedTypes} types`);
+	if (result.reusedTypes.length) {
+		console.log(`  reused ${result.reusedTypes.length}: ${result.reusedTypes.join(", ")}`);
+		if (!flags.reuseStrict) console.log("  (pass --reuse-strict to check the reused shapes still match)");
+	}
+	for (const file of result.files) console.log(`  wrote ${file}`);
+});
+function toArray(value) {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+}
+cli.help();
+cli.parse();
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,201 @@
+//#region src/schema.d.ts
+/** The slice of AsyncAPI 3 that chanx emits. Deliberately permissive. */
+interface JsonSchema {
+  $ref?: string;
+  title?: string;
+  description?: string;
+  type?: string | string[];
+  const?: unknown;
+  enum?: unknown[];
+  default?: unknown;
+  format?: string;
+  nullable?: boolean;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  additionalProperties?: boolean | JsonSchema;
+  anyOf?: JsonSchema[];
+  oneOf?: JsonSchema[];
+  allOf?: JsonSchema[];
+  discriminator?: string | {
+    propertyName?: string;
+  };
+  [key: string]: unknown;
+}
+interface TopicExtension {
+  name?: string;
+  pattern: string;
+  parameters?: string[];
+}
+interface ChannelObject {
+  address?: string;
+  title?: string;
+  description?: string;
+  messages?: Record<string, {
+    $ref?: string;
+  }>;
+  parameters?: Record<string, unknown>;
+  'x-topic'?: TopicExtension;
+}
+interface OperationObject {
+  action?: 'send' | 'receive';
+  channel?: {
+    $ref?: string;
+  };
+  messages?: Array<{
+    $ref?: string;
+  }>;
+  reply?: {
+    messages?: Array<{
+      $ref?: string;
+    }>;
+  };
+}
+interface AsyncAPIDocument {
+  asyncapi?: string;
+  info?: {
+    title?: string;
+    version?: string;
+    description?: string;
+  };
+  channels?: Record<string, ChannelObject>;
+  operations?: Record<string, OperationObject>;
+  components?: {
+    schemas?: Record<string, JsonSchema>;
+    messages?: Record<string, {
+      payload?: JsonSchema;
+    }>;
+  };
+}
+//#endregion
+//#region src/analyze.d.ts
+interface ChannelInfo {
+  /** Key in `channels`. */
+  key: string;
+  /** chanx's own name for the channel, used as the descriptor's `name`. */
+  name: string;
+  address: string;
+  description?: string;
+  toServer: string[];
+  toClient: string[];
+  topic?: TopicExtension;
+  /** Sends `ping` and receives `pong`, so the runtime may heartbeat it. */
+  heartbeat: boolean;
+}
+interface ConnectionInfo extends ChannelInfo {
+  topics: ChannelInfo[];
+}
+/**
+ * Split channels into connections and the topics riding on them.
+ *
+ * A topic channel shares its connection's address, which is what groups the two;
+ * chanx's own Python generator uses the same rule. A topic channel with no plain
+ * channel at its address owns its connection, so it is emitted as both.
+ */
+export declare function analyze(document: AsyncAPIDocument): ConnectionInfo[];
+//#endregion
+//#region src/emit-channels.d.ts
+interface ChannelEmitOptions {
+  withZod: boolean;
+  schemasModule: string;
+  zodModule: string;
+  /** `ts` emits one typed module; `js` splits runtime and declarations. */
+  target: 'ts' | 'js';
+}
+/** The descriptor values. Valid TypeScript or JavaScript depending on `target`. */
+export declare function emitChannels(connections: ConnectionInfo[], messageNames: string[], options: ChannelEmitOptions): string;
+/**
+ * The `.d.ts` companion to a JavaScript `channels.js`.
+ *
+ * Declares the same descriptors with their full generic arguments, so a plain-JS project
+ * still gets narrowing, address-param checking and topic typing from its editor.
+ */
+export declare function emitChannelsDeclaration(connections: ConnectionInfo[], messageNames: string[], options: ChannelEmitOptions): string;
+//#endregion
+//#region src/emit-types.d.ts
+export declare function tsType(schema: JsonSchema | undefined, indent?: string): string;
+/** Emit a named declaration, preferring `interface` for plain object shapes. */
+export declare function declareType(name: string, schema: JsonSchema): string;
+export declare function emitSchemas(schemas: Record<string, JsonSchema>, skip: ReadonlySet<string>): string;
+//#endregion
+//#region src/emit-zod.d.ts
+export declare function emitZod(schemas: Record<string, JsonSchema>, connections: ConnectionInfo[], skip: ReadonlySet<string>): string;
+/**
+ * The `.d.ts` companion to a JavaScript `schemas.zod.js`.
+ *
+ * Each validator is declared as `z.ZodType<T>`, which is what `parse` needs to return
+ * the right type; reproducing the precise zod class by hand buys nothing.
+ */
+export declare function emitZodDeclaration(schemas: Record<string, JsonSchema>, connections: ConnectionInfo[], skip: ReadonlySet<string>, schemasModule: string, channelsModule: string): string;
+//#endregion
+//#region src/reuse.d.ts
+interface ReuseOptions {
+  /** Globs scanned for types that already exist, e.g. `src/types/backend/**\/*.ts`. */
+  reuseFrom?: string[];
+  /** Explicit overrides: type name to module specifier. Wins over the scan. */
+  reuseMap?: Record<string, string>;
+  /**
+   * Treat found types as ambient globals and emit no imports, matching a setup where
+   * generated files are non-module scripts merged into the global scope.
+   */
+  ambient?: boolean;
+  /** Path prefix rewrites applied to import specifiers, e.g. `{ "src/": "@/" }`. */
+  alias?: Record<string, string>;
+}
+interface ReuseResolution {
+  /** Type names that exist elsewhere and must not be generated. */
+  skip: Set<string>;
+  /** Module specifier to the names imported from it. Empty in ambient mode. */
+  imports: Map<string, Set<string>>;
+  /** Where each reused name was found, for the report and the strict check. */
+  sources: Map<string, string>;
+}
+/**
+ * Find types the project already declares so they are referenced rather than regenerated.
+ *
+ * Uses the TypeScript AST rather than a line regex: `export type X`, `interface X` and
+ * indented declarations are all real cases a regex over `^type\s+(\w+)\s*=` misses.
+ * `ts-morph` is loaded only here, so a run without `reuseFrom` never pays for it.
+ */
+export declare function resolveReuse(wanted: ReadonlySet<string>, outDir: string, options: ReuseOptions): Promise<ReuseResolution>;
+export declare function renderImports(imports: Map<string, Set<string>>): string;
+//#endregion
+//#region src/generate.d.ts
+interface GenerateOptions extends ReuseOptions {
+  outDir: string;
+  /** Also emit zod schemas and wire them into the descriptors' validators. */
+  validation?: 'none' | 'zod';
+  /** Emit a file asserting reused types still match the schema. */
+  reuseStrict?: boolean;
+  /**
+   * `ts` writes one typed module per concern. `js` splits each into a runtime `.js` and
+   * a `.d.ts`, so a plain JavaScript project can import the descriptors and still get
+   * narrowing from its editor.
+   */
+  emit?: 'ts' | 'js';
+  format?: boolean;
+}
+interface GenerateResult {
+  files: string[];
+  generatedTypes: number;
+  reusedTypes: string[];
+  channels: number;
+  topics: number;
+}
+export declare function generate(document: AsyncAPIDocument, options: GenerateOptions): Promise<GenerateResult>;
+//#endregion
+//#region src/loader.d.ts
+/** Load an AsyncAPI document from a URL or a path. JSON and YAML both parse. */
+export declare function loadSchema(input: string): Promise<AsyncAPIDocument>;
+//#endregion
+//#region src/naming.d.ts
+/**
+ * PascalCase that preserves casing inside each part.
+ *
+ * `ag_ui_run` becomes `AgUiRun`, and `PingMessage` stays `PingMessage`. A
+ * `title()`-style pass would flatten it to `Pingmessage`.
+ */
+export declare function pascalCase(value: string): string;
+export declare function camelCase(value: string): string;
+//#endregion
+export type { AsyncAPIDocument, ChannelEmitOptions, ChannelInfo, ChannelObject, ConnectionInfo, GenerateOptions, GenerateResult, JsonSchema, OperationObject, ReuseOptions, ReuseResolution };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { a as emitZod, c as emitSchemas, d as emitChannelsDeclaration, f as camelCase, i as resolveReuse, l as tsType, m as analyze, n as generate, o as emitZodDeclaration, p as pascalCase, r as renderImports, s as declareType, t as loadSchema, u as emitChannels } from "./loader-DtCKhsCU.mjs";
+export { analyze, camelCase, declareType, emitChannels, emitChannelsDeclaration, emitSchemas, emitZod, emitZodDeclaration, generate, loadSchema, pascalCase, renderImports, resolveReuse, tsType };

package/dist/loader-DtCKhsCU.mjs

@@ -0,0 +1,603 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { parse } from "yaml";
+//#region src/schema.ts
+function refName(ref) {
+	return ref.slice(ref.lastIndexOf("/") + 1);
+}
+/** Resolve `#/components/messages/x` to the schema name behind its payload. */
+function messageSchemaName(document, ref) {
+	if (!ref) return null;
+	const payloadRef = (document.components?.messages?.[refName(ref)])?.payload?.$ref;
+	return payloadRef ? refName(payloadRef) : null;
+}
+//#endregion
+//#region src/analyze.ts
+function directions(document) {
+	const result = /* @__PURE__ */ new Map();
+	for (const key of Object.keys(document.channels ?? {})) result.set(key, {
+		toServer: /* @__PURE__ */ new Set(),
+		toClient: /* @__PURE__ */ new Set()
+	});
+	for (const operation of Object.values(document.operations ?? {})) {
+		const channelKey = refName(operation.channel?.$ref ?? "");
+		const bucket = result.get(channelKey);
+		if (!bucket) continue;
+		const target = operation.action === "send" ? bucket.toClient : bucket.toServer;
+		for (const message of operation.messages ?? []) {
+			const name = messageSchemaName(document, message.$ref);
+			if (name) target.add(name);
+		}
+		for (const message of operation.reply?.messages ?? []) {
+			const name = messageSchemaName(document, message.$ref);
+			if (name) bucket.toClient.add(name);
+		}
+	}
+	return result;
+}
+/** The `action` constant a message schema pins, if it pins one. */
+function actionOf$1(document, schemaName) {
+	return document.components?.schemas?.[schemaName]?.properties?.action?.const;
+}
+function describe(document, key, channel, buckets) {
+	const bucket = buckets.get(key);
+	const toServer = [...bucket?.toServer ?? []].sort();
+	const toClient = [...bucket?.toClient ?? []].sort();
+	const info = {
+		key,
+		name: channel.title ?? key,
+		address: channel.address ?? "",
+		toServer,
+		toClient,
+		heartbeat: toServer.some((name) => actionOf$1(document, name) === "ping") && toClient.some((name) => actionOf$1(document, name) === "pong")
+	};
+	if (channel.description) info.description = channel.description;
+	if (channel["x-topic"]) info.topic = channel["x-topic"];
+	return info;
+}
+/**
+* Split channels into connections and the topics riding on them.
+*
+* A topic channel shares its connection's address, which is what groups the two;
+* chanx's own Python generator uses the same rule. A topic channel with no plain
+* channel at its address owns its connection, so it is emitted as both.
+*/
+function analyze(document) {
+	const buckets = directions(document);
+	const channels = Object.entries(document.channels ?? {}).map(([key, channel]) => describe(document, key, channel, buckets));
+	const connections = channels.filter((channel) => !channel.topic);
+	const topics = channels.filter((channel) => channel.topic);
+	const byAddress = /* @__PURE__ */ new Map();
+	const result = connections.map((channel) => {
+		const connection = {
+			...channel,
+			topics: []
+		};
+		byAddress.set(channel.address, connection);
+		return connection;
+	});
+	for (const topic of topics) {
+		const parent = byAddress.get(topic.address);
+		if (parent) {
+			parent.topics.push(topic);
+			continue;
+		}
+		const standalone = {
+			...topic,
+			topics: [topic]
+		};
+		byAddress.set(topic.address, standalone);
+		result.push(standalone);
+	}
+	return result.sort((a, b) => a.key.localeCompare(b.key));
+}
+//#endregion
+//#region src/naming.ts
+const SEPARATORS = /[^A-Za-z0-9]+/;
+/**
+* PascalCase that preserves casing inside each part.
+*
+* `ag_ui_run` becomes `AgUiRun`, and `PingMessage` stays `PingMessage`. A
+* `title()`-style pass would flatten it to `Pingmessage`.
+*/
+function pascalCase(value) {
+	return value.split(SEPARATORS).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function camelCase(value) {
+	const pascal = pascalCase(value);
+	return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+/** Quote a key only when it is not a valid identifier. */
+function propertyKey(name) {
+	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+function docComment(text, indent = "") {
+	if (!text) return "";
+	const collapsed = text.replace(/\s+/g, " ").trim();
+	if (!collapsed) return "";
+	return `${indent}/** ${collapsed.replace(/\*\//g, "*\\/")} */\n`;
+}
+//#endregion
+//#region src/emit-channels.ts
+function unionType(name, members) {
+	return `export type ${name} = ${members.length ? members.join(" | ") : "never"};\n`;
+}
+function validatorsLiteral(prefix, indent) {
+	return `${indent}validators: {\n${indent}  toServer: (value) => ${prefix}ToServerSchema.parse(value),\n${indent}  toClient: (value) => ${prefix}ToClientSchema.parse(value),\n${indent}},\n`;
+}
+/** Type arguments are erased in JS, so the runtime file calls the plain form. */
+function typeArgs(prefix, target) {
+	return target === "ts" ? `<${prefix}ToServer, ${prefix}ToClient>` : "";
+}
+function renderTopic(topic, options, indent) {
+	const prefix = pascalCase(topic.name);
+	const key = camelCase(topic.topic?.name ?? topic.name);
+	const inner = `${indent}  `;
+	return docComment(topic.description, indent) + `${indent}${propertyKey(key)}: defineTopic${typeArgs(prefix, options.target)}()({\n${inner}name: ${JSON.stringify(topic.topic?.name ?? topic.name)},\n${inner}pattern: ${JSON.stringify(topic.topic?.pattern ?? "")},\n` + (options.withZod ? validatorsLiteral(prefix, inner) : "") + `${indent}}),\n`;
+}
+function collectPrefixes(connection) {
+	return [connection, ...connection.topics].map((channel) => pascalCase(channel.name));
+}
+function zodImport(connections, zodModule) {
+	return `import {\n  ${[...new Set(connections.flatMap(collectPrefixes))].sort().flatMap((prefix) => [`${prefix}ToServerSchema`, `${prefix}ToClientSchema`]).join(",\n  ")},\n} from '${zodModule}';\n`;
+}
+/** Declare each channel's message unions exactly once. */
+function unions(connections) {
+	const lines = [];
+	const declared = /* @__PURE__ */ new Set();
+	for (const connection of connections) {
+		for (const channel of [connection, ...connection.topics]) {
+			const prefix = pascalCase(channel.name);
+			if (declared.has(prefix)) continue;
+			declared.add(prefix);
+			lines.push(unionType(`${prefix}ToServer`, channel.toServer));
+			lines.push(unionType(`${prefix}ToClient`, channel.toClient));
+		}
+		lines.push("\n");
+	}
+	return lines.join("");
+}
+/** The descriptor values. Valid TypeScript or JavaScript depending on `target`. */
+function emitChannels(connections, messageNames, options) {
+	const lines = [`import { defineChannel, defineTopic } from '@chanx-js/client';\n\n`];
+	if (options.target === "ts") {
+		if (messageNames.length) {
+			const imported = [...messageNames].sort().join(",\n  ");
+			lines.push(`import type {\n  ${imported},\n} from '${options.schemasModule}';\n`);
+		}
+	}
+	if (options.withZod) lines.push(zodImport(connections, options.zodModule));
+	lines.push("\n");
+	if (options.target === "ts") lines.push(unions(connections));
+	for (const connection of connections) {
+		const prefix = pascalCase(connection.name);
+		const constName = camelCase(connection.name);
+		lines.push(docComment(connection.description));
+		lines.push(`export const ${constName} = defineChannel${typeArgs(prefix, options.target)}()({\n`);
+		lines.push(`  name: ${JSON.stringify(connection.name)},\n`);
+		lines.push(`  address: ${JSON.stringify(connection.address)},\n`);
+		if (connection.heartbeat) lines.push("  heartbeat: true,\n");
+		if (options.withZod) lines.push(validatorsLiteral(prefix, "  "));
+		if (connection.topics.length) {
+			lines.push("  topics: {\n");
+			for (const topic of connection.topics) lines.push(renderTopic(topic, options, "    "));
+			lines.push("  },\n");
+		}
+		lines.push("});\n\n");
+	}
+	const registry = connections.map((connection) => `  ${propertyKey(camelCase(connection.name))}`).join(",\n");
+	const asConst = options.target === "ts" ? " as const" : "";
+	lines.push(`export const channels = {\n${registry},\n}${asConst};\n`);
+	return lines.join("");
+}
+/**
+* The `.d.ts` companion to a JavaScript `channels.js`.
+*
+* Declares the same descriptors with their full generic arguments, so a plain-JS project
+* still gets narrowing, address-param checking and topic typing from its editor.
+*/
+function emitChannelsDeclaration(connections, messageNames, options) {
+	const lines = [`import type { ChannelDescriptor, TopicDescriptor } from '@chanx-js/client';\n`];
+	if (messageNames.length) {
+		const imported = [...messageNames].sort().join(",\n  ");
+		lines.push(`import type {\n  ${imported},\n} from '${options.schemasModule}';\n`);
+	}
+	lines.push("\n");
+	lines.push(unions(connections));
+	for (const connection of connections) {
+		const prefix = pascalCase(connection.name);
+		const constName = camelCase(connection.name);
+		const address = JSON.stringify(connection.address);
+		const topics = connection.topics.map((topic) => {
+			const topicPrefix = pascalCase(topic.name);
+			const key = camelCase(topic.topic?.name ?? topic.name);
+			const pattern = JSON.stringify(topic.topic?.pattern ?? "");
+			return `  ${propertyKey(key)}: TopicDescriptor<${topicPrefix}ToServer, ${topicPrefix}ToClient, ${pattern}>;`;
+		}).join("\n");
+		const topicsType = connection.topics.length ? `{\n${topics}\n}` : "Record<never, never>";
+		lines.push(docComment(connection.description));
+		lines.push(`export declare const ${constName}: ChannelDescriptor<${prefix}ToServer, ${prefix}ToClient, ${address}, ${topicsType}>;\n\n`);
+	}
+	const registry = connections.map((connection) => {
+		const constName = camelCase(connection.name);
+		return `  ${propertyKey(constName)}: typeof ${constName};`;
+	}).join("\n");
+	lines.push(`export declare const channels: {\n${registry}\n};\n`);
+	return lines.join("");
+}
+//#endregion
+//#region src/emit-types.ts
+const SCALARS$1 = {
+	string: "string",
+	integer: "number",
+	number: "number",
+	boolean: "boolean",
+	null: "null"
+};
+/**
+* Whether a property is always present on the wire.
+*
+* chanx gives every message's `action` a `const` *and* a default, so Pydantic leaves it
+* out of `required`. Emitting it optional would put `undefined` in the discriminant's
+* domain and break both narrowing and exhaustiveness checks, so a `const` counts as
+* present regardless of `required`.
+*/
+function isAlwaysPresent(name, property, required) {
+	return required.has(name) || property.const !== void 0;
+}
+function tsType(schema, indent = "") {
+	if (!schema) return "unknown";
+	if (schema.$ref) return refName(schema.$ref);
+	if (schema.const !== void 0) return JSON.stringify(schema.const);
+	if (schema.enum) return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
+	const variants = schema.anyOf ?? schema.oneOf;
+	if (variants) return [...new Set(variants.map((variant) => tsType(variant, indent)))].join(" | ");
+	if (schema.allOf?.length === 1) return tsType(schema.allOf[0], indent);
+	if (schema.allOf?.length) return schema.allOf.map((part) => tsType(part, indent)).join(" & ");
+	const suffix = schema.nullable ? " | null" : "";
+	const type = schema.type;
+	if (Array.isArray(type)) return type.map((entry) => tsType({
+		...schema,
+		type: entry
+	}, indent)).join(" | ");
+	if (type === "array") return `Array<${tsType(schema.items, indent)}>${suffix}`;
+	if (type === "object" || schema.properties) {
+		if (schema.properties) return objectBody(schema, indent) + suffix;
+		const additional = schema.additionalProperties;
+		if (additional && typeof additional === "object") return `Record<string, ${tsType(additional, indent)}>${suffix}`;
+		return `Record<string, unknown>${suffix}`;
+	}
+	if (typeof type === "string" && type in SCALARS$1) return `${SCALARS$1[type]}${suffix}`;
+	return `unknown${suffix}`;
+}
+function objectBody(schema, indent) {
+	const required = new Set(schema.required ?? []);
+	const inner = `${indent}  `;
+	const lines = Object.entries(schema.properties ?? {}).map(([name, property]) => {
+		const optional = isAlwaysPresent(name, property, required) ? "" : "?";
+		return `${docComment(property.description, inner)}${inner}${propertyKey(name)}${optional}: ${tsType(property, inner)};`;
+	});
+	if (lines.length === 0) return "Record<string, never>";
+	return `{\n${lines.join("\n")}\n${indent}}`;
+}
+/** Emit a named declaration, preferring `interface` for plain object shapes. */
+function declareType(name, schema) {
+	const doc = docComment(schema.description);
+	if (Boolean(schema.properties) && !schema.anyOf && !schema.oneOf && !schema.allOf && !schema.$ref) return `${doc}export interface ${name} ${objectBody(schema, "")}\n`;
+	return `${doc}export type ${name} = ${tsType(schema)};\n`;
+}
+function emitSchemas(schemas, skip) {
+	return Object.keys(schemas).sort().filter((name) => !skip.has(name)).map((name) => declareType(name, schemas[name])).join("\n");
+}
+//#endregion
+//#region src/emit-zod.ts
+const SCALARS = {
+	string: "z.string()",
+	integer: "z.number().int()",
+	number: "z.number()",
+	boolean: "z.boolean()",
+	null: "z.null()"
+};
+function zodType(schema) {
+	if (!schema) return "z.unknown()";
+	if (schema.$ref) return `z.lazy(() => ${refName(schema.$ref)}Schema)`;
+	if (schema.const !== void 0) return `z.literal(${JSON.stringify(schema.const)})`;
+	if (schema.enum) {
+		const members = schema.enum.map((value) => `z.literal(${JSON.stringify(value)})`);
+		return members.length === 1 ? members[0] : `z.union([${members.join(", ")}])`;
+	}
+	const variants = schema.anyOf ?? schema.oneOf;
+	if (variants?.length) {
+		if (variants.length === 1) return zodType(variants[0]);
+		return `z.union([${variants.map(zodType).join(", ")}])`;
+	}
+	if (schema.allOf?.length === 1) return zodType(schema.allOf[0]);
+	if (schema.allOf?.length) return schema.allOf.map(zodType).reduce((left, right) => `z.intersection(${left}, ${right})`);
+	const type = schema.type;
+	if (Array.isArray(type)) return `z.union([${type.map((entry) => zodType({
+		...schema,
+		type: entry
+	})).join(", ")}])`;
+	if (type === "array") return `z.array(${zodType(schema.items)})`;
+	if (type === "object" || schema.properties) {
+		if (schema.properties) return zodObject(schema);
+		const additional = schema.additionalProperties;
+		return typeof additional === "object" ? `z.record(z.string(), ${zodType(additional)})` : "z.record(z.string(), z.unknown())";
+	}
+	const base = (typeof type === "string" ? SCALARS[type] : void 0) ?? "z.unknown()";
+	return schema.nullable ? `${base}.nullable()` : base;
+}
+function zodObject(schema) {
+	const required = new Set(schema.required ?? []);
+	return `z.object({\n${Object.entries(schema.properties ?? {}).map(([name, property]) => {
+		const present = required.has(name) || property.const !== void 0;
+		const value = zodType(property);
+		return `  ${propertyKey(name)}: ${present ? value : `${value}.optional()`},`;
+	}).join("\n")}\n})`;
+}
+/** The `action` constant a message schema pins, if it pins one. */
+function actionOf(schema) {
+	return schema?.properties?.action?.const;
+}
+function emitZod(schemas, connections, skip) {
+	const lines = [`import { z } from 'zod';\n\n`];
+	const generated = Object.keys(schemas).sort().filter((name) => !skip.has(name));
+	for (const name of [...skip].sort()) {
+		const action = actionOf(schemas[name]);
+		const schema = action === void 0 ? "z.unknown()" : `z.object({ action: z.literal(${JSON.stringify(action)}) }).catchall(z.unknown())`;
+		lines.push(`export const ${name}Schema = ${schema};\n`);
+	}
+	if (skip.size) lines.push("\n");
+	for (const name of generated) lines.push(`export const ${name}Schema = ${zodType(schemas[name])};\n\n`);
+	const declared = /* @__PURE__ */ new Set();
+	for (const connection of connections) for (const channel of [connection, ...connection.topics]) {
+		const prefix = pascalCase(channel.name);
+		if (declared.has(prefix)) continue;
+		declared.add(prefix);
+		lines.push(union(`${prefix}ToServerSchema`, channel.toServer, schemas));
+		lines.push(union(`${prefix}ToClientSchema`, channel.toClient, schemas));
+	}
+	return lines.join("");
+}
+/**
+* The `.d.ts` companion to a JavaScript `schemas.zod.js`.
+*
+* Each validator is declared as `z.ZodType<T>`, which is what `parse` needs to return
+* the right type; reproducing the precise zod class by hand buys nothing.
+*/
+function emitZodDeclaration(schemas, connections, skip, schemasModule, channelsModule) {
+	const generated = Object.keys(schemas).sort().filter((name) => !skip.has(name));
+	const unionNames = [];
+	const declared = /* @__PURE__ */ new Set();
+	for (const connection of connections) for (const channel of [connection, ...connection.topics]) {
+		const prefix = pascalCase(channel.name);
+		if (declared.has(prefix)) continue;
+		declared.add(prefix);
+		unionNames.push(`${prefix}ToServer`, `${prefix}ToClient`);
+	}
+	const lines = [`import type { z } from 'zod';\n`];
+	if (generated.length) lines.push(`import type {\n  ${generated.join(",\n  ")},\n} from '${schemasModule}';\n`);
+	if (unionNames.length) lines.push(`import type {\n  ${unionNames.join(",\n  ")},\n} from '${channelsModule}';\n`);
+	lines.push("\n");
+	for (const name of [...skip].sort()) lines.push(`export declare const ${name}Schema: z.ZodType<unknown>;\n`);
+	for (const name of generated) lines.push(`export declare const ${name}Schema: z.ZodType<${name}>;\n`);
+	for (const name of unionNames) lines.push(`export declare const ${name}Schema: z.ZodType<${name}>;\n`);
+	return lines.join("");
+}
+function union(name, members, schemas) {
+	if (members.length === 0) return `export const ${name} = z.never();\n`;
+	if (members.length === 1) return `export const ${name} = ${members[0]}Schema;\n`;
+	const refs = members.map((member) => `${member}Schema`).join(", ");
+	const actions = members.map((member) => actionOf(schemas[member]));
+	return actions.every((action) => action !== void 0) && new Set(actions).size === actions.length ? `export const ${name} = z.discriminatedUnion('action', [${refs}]);\n` : `export const ${name} = z.union([${refs}]);\n`;
+}
+//#endregion
+//#region src/reuse.ts
+function applyAlias(path, alias) {
+	if (!alias) return null;
+	const prefixes = Object.keys(alias).sort((a, b) => b.length - a.length);
+	for (const prefix of prefixes) if (path.startsWith(prefix)) return alias[prefix] + path.slice(prefix.length);
+	return null;
+}
+function toSpecifier(filePath, outDir, alias) {
+	const aliased = applyAlias(relative(process.cwd(), filePath).replace(/\\/g, "/").replace(/\.(d\.)?tsx?$/, ""), alias);
+	if (aliased) return aliased;
+	let relativePath = relative(resolve(outDir), filePath).replace(/\\/g, "/");
+	relativePath = relativePath.replace(/\.(d\.)?tsx?$/, "");
+	return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+}
+function isInside(filePath, dir) {
+	const path = relative(resolve(dir), filePath);
+	return path !== "" && !path.startsWith("..") && !isAbsolute(path);
+}
+/**
+* Find types the project already declares so they are referenced rather than regenerated.
+*
+* Uses the TypeScript AST rather than a line regex: `export type X`, `interface X` and
+* indented declarations are all real cases a regex over `^type\s+(\w+)\s*=` misses.
+* `ts-morph` is loaded only here, so a run without `reuseFrom` never pays for it.
+*/
+async function resolveReuse(wanted, outDir, options) {
+	const skip = /* @__PURE__ */ new Set();
+	const imports = /* @__PURE__ */ new Map();
+	const sources = /* @__PURE__ */ new Map();
+	const addImport = (specifier, name) => {
+		if (options.ambient) return;
+		let names = imports.get(specifier);
+		if (!names) {
+			names = /* @__PURE__ */ new Set();
+			imports.set(specifier, names);
+		}
+		names.add(name);
+	};
+	if (options.reuseFrom?.length) {
+		const { Project } = await import("ts-morph");
+		const project = new Project({
+			skipAddingFilesFromTsConfig: true,
+			compilerOptions: { allowJs: false }
+		});
+		project.addSourceFilesAtPaths(options.reuseFrom);
+		for (const file of project.getSourceFiles()) {
+			if (isInside(file.getFilePath(), outDir)) continue;
+			const declared = [
+				...file.getTypeAliases(),
+				...file.getInterfaces(),
+				...file.getEnums(),
+				...file.getClasses()
+			].filter((declaration) => options.ambient || declaration.isExported()).map((declaration) => declaration.getName() ?? "");
+			for (const name of declared) {
+				if (!name || !wanted.has(name) || skip.has(name)) continue;
+				skip.add(name);
+				sources.set(name, file.getFilePath());
+				addImport(toSpecifier(file.getFilePath(), outDir, options.alias), name);
+			}
+		}
+	}
+	for (const [name, specifier] of Object.entries(options.reuseMap ?? {})) {
+		if (!wanted.has(name)) continue;
+		skip.add(name);
+		sources.set(name, specifier);
+		addImport(specifier, name);
+	}
+	return {
+		skip,
+		imports,
+		sources
+	};
+}
+function renderImports(imports) {
+	if (imports.size === 0) return "";
+	return `${[...imports.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([specifier, names]) => {
+		return `import type { ${[...names].sort().join(", ")} } from '${specifier}';`;
+	}).join("\n")}\n\n`;
+}
+//#endregion
+//#region src/generate.ts
+const HEADER = `// Generated by @chanx-js/codegen. Do not edit.\n// Regenerate with: npx @chanx-js/codegen\n\n`;
+async function maybeFormat(code, filePath, enabled) {
+	if (!enabled) return code;
+	let prettier;
+	try {
+		prettier = await import("prettier");
+	} catch {
+		return code;
+	}
+	const config = await prettier.resolveConfig(filePath);
+	return prettier.format(code, {
+		...config,
+		filepath: filePath
+	});
+}
+/**
+* Fail before writing anything if two schema elements would emit the same identifier.
+* Names are derived by case conversion, so `chat-room` and `chat_room` both become
+* `ChatRoom`, and the output would not compile.
+*/
+function checkNames(connections, schemaNames) {
+	const problems = [];
+	const claim = (owners, name, owner) => {
+		const existing = owners.get(name);
+		if (existing === void 0) owners.set(name, owner);
+		else if (existing !== owner) problems.push(`"${name}" would be emitted for both ${existing} and ${owner}`);
+	};
+	const identifiers = /* @__PURE__ */ new Map([["channels", "the channel registry"]]);
+	for (const name of schemaNames) {
+		claim(identifiers, name, `schema ${name}`);
+		claim(identifiers, `${name}Schema`, `schema ${name}`);
+	}
+	for (const connection of connections) {
+		claim(identifiers, camelCase(connection.name), `channel "${connection.key}"`);
+		const topicKeys = /* @__PURE__ */ new Map();
+		for (const channel of [connection, ...connection.topics]) {
+			const owner = `channel "${channel.key}"`;
+			const prefix = pascalCase(channel.name);
+			for (const suffix of [
+				"ToServer",
+				"ToClient",
+				"ToServerSchema",
+				"ToClientSchema"
+			]) claim(identifiers, prefix + suffix, owner);
+		}
+		for (const topic of connection.topics) claim(topicKeys, camelCase(topic.topic?.name ?? topic.name), `channel "${topic.key}"`);
+	}
+	if (problems.length) throw new Error(`Generated names would clash:\n  ${problems.join("\n  ")}\nRename the channels, topics or schemas on the server.`);
+}
+function emitReuseCheck(reusedNames, schemas, imports) {
+	const declarations = reusedNames.map((name) => declareType(`Generated${name}`, schemas[name])).join("\n");
+	const assertions = reusedNames.map((name) => `export type Check${name} = Assert<MutuallyAssignable<${name}, Generated${name}>>;`).join("\n");
+	return HEADER + "// Each assertion fails to compile if a reused type has drifted from the schema.\n// Reusing a type assumes the name and the shape both still match.\n\n" + renderImports(imports) + "type MutuallyAssignable<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;\ntype Assert<T extends true> = T;\n\n" + declarations + "\n" + assertions + "\n";
+}
+async function generate(document, options) {
+	const target = options.emit ?? "ts";
+	if (target !== "ts" && target !== "js") throw new Error(`emit must be "ts" or "js", got "${String(target)}"`);
+	const validation = options.validation ?? "none";
+	if (validation !== "none" && validation !== "zod") throw new Error(`validation must be "none" or "zod", got "${String(validation)}"`);
+	const outDir = resolve(options.outDir);
+	const schemas = document.components?.schemas ?? {};
+	const connections = analyze(document);
+	checkNames(connections, Object.keys(schemas));
+	const format = options.format ?? true;
+	const withZod = validation === "zod";
+	const reuse = await resolveReuse(new Set(Object.keys(schemas)), outDir, options);
+	const reusedNames = [...reuse.skip].sort();
+	await mkdir(outDir, { recursive: true });
+	const files = [];
+	const write = async (name, code) => {
+		const filePath = join(outDir, name);
+		await writeFile(filePath, await maybeFormat(code, filePath, format), "utf-8");
+		files.push(filePath);
+	};
+	const isJs = target === "js";
+	await write(isJs ? "schemas.d.ts" : "schemas.ts", HEADER + renderImports(reuse.imports) + emitSchemas(schemas, reuse.skip));
+	const messageNames = [...new Set(connections.flatMap((connection) => [connection, ...connection.topics].flatMap((channel) => [...channel.toServer, ...channel.toClient])))];
+	const channelOptions = {
+		withZod,
+		schemasModule: "./schemas",
+		zodModule: isJs ? "./schemas.zod.js" : "./schemas.zod",
+		target
+	};
+	await write(isJs ? "channels.js" : "channels.ts", HEADER + emitChannels(connections, messageNames, channelOptions));
+	if (isJs) await write("channels.d.ts", HEADER + emitChannelsDeclaration(connections, messageNames, channelOptions));
+	if (withZod) {
+		await write(isJs ? "schemas.zod.js" : "schemas.zod.ts", HEADER + emitZod(schemas, connections, reuse.skip));
+		if (isJs) await write("schemas.zod.d.ts", HEADER + emitZodDeclaration(schemas, connections, reuse.skip, "./schemas", "./channels"));
+	}
+	if (options.reuseStrict && reusedNames.length) await write(isJs ? "reuse-check.d.ts" : "reuse-check.ts", emitReuseCheck(reusedNames, schemas, reuse.imports));
+	if (isJs) {
+		const runtime = ["export * from './channels.js';"];
+		if (withZod) runtime.push("export * from './schemas.zod.js';");
+		await write("index.js", HEADER + runtime.join("\n") + "\n");
+		const declarations = ["export * from './schemas';", "export * from './channels';"];
+		if (withZod) declarations.push("export * from './schemas.zod';");
+		await write("index.d.ts", HEADER + declarations.join("\n") + "\n");
+	} else {
+		const exports = ["export * from './schemas';", "export * from './channels';"];
+		if (withZod) exports.push("export * from './schemas.zod';");
+		await write("index.ts", HEADER + exports.join("\n") + "\n");
+	}
+	return {
+		files,
+		generatedTypes: Object.keys(schemas).length - reuse.skip.size,
+		reusedTypes: reusedNames,
+		channels: connections.length,
+		topics: connections.reduce((total, connection) => total + connection.topics.length, 0)
+	};
+}
+//#endregion
+//#region src/loader.ts
+/** Load an AsyncAPI document from a URL or a path. JSON and YAML both parse. */
+async function loadSchema(input) {
+	let text;
+	if (/^https?:\/\//.test(input)) {
+		const response = await fetch(input, { signal: AbortSignal.timeout(3e4) });
+		if (!response.ok) throw new Error(`Failed to fetch schema: ${response.status} ${response.statusText}`);
+		text = await response.text();
+	} else text = await readFile(resolve(input), "utf-8");
+	const document = parse(text);
+	if (!document || typeof document !== "object") throw new Error("Schema did not parse to an object");
+	if (!document.channels) throw new Error("Schema has no `channels`: is this an AsyncAPI document?");
+	if (!String(document.asyncapi ?? "").startsWith("3.")) throw new Error(`Expected an AsyncAPI 3 document, got asyncapi: ${String(document.asyncapi ?? "missing")}`);
+	return document;
+}
+//#endregion
+export { emitZod as a, emitSchemas as c, emitChannelsDeclaration as d, camelCase as f, resolveReuse as i, tsType as l, analyze as m, generate as n, emitZodDeclaration as o, pascalCase as p, renderImports as r, declareType as s, loadSchema as t, emitChannels as u };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@chanx-js/codegen",
+  "version": "0.1.0",
+  "description": "Generate TypeScript channel descriptors and message types from a chanx AsyncAPI 3 schema.",
+  "license": "MIT",
+  "author": "Huy Nguyen",
+  "homepage": "https://huynguyengl99.github.io/chanx-js/guide/codegen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huynguyengl99/chanx-js.git",
+    "directory": "packages/codegen"
+  },
+  "bugs": "https://github.com/huynguyengl99/chanx-js/issues",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "chanx-codegen": "./dist/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/cli.ts --format esm --dts --clean",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "cac": "^6.7.14",
+    "ts-morph": "^28.0.0",
+    "yaml": "^2.7.0"
+  },
+  "peerDependencies": {
+    "prettier": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "prettier": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "asyncapi",
+    "@chanx-js/client",
+    "codegen",
+    "typescript",
+    "websocket"
+  ],
+  "devDependencies": {
+    "zod": "^3.25.76"
+  }
+}