Public API

TypeScriptGenerator

class TypeScriptGenerator {
  constructor(options?: TypeScriptGeneratorOptions);
  generate(input: Record<string, unknown> | InputMetaModel): Promise<OutputModel[]>;
  generateCompleteModels(input: ..., options: ...): Promise<OutputModel[]>;
}

The primary entry point for generating TypeScript interfaces and classes. Instantiate with optional presets and constraints overrides, then call generate() with a raw AsyncAPI/OpenAPI/JSON Schema document or a pre-built InputMetaModel.

CSharpGenerator

class CSharpGenerator {
  constructor(options?: CSharpGeneratorOptions);
  generate(input: Record<string, unknown> | InputMetaModel): Promise<OutputModel[]>;
}

Generates C# classes, records, and enums. Supports presets for JSON serialization (JsonSerializerPreset, NewtonsoftSerializerPreset) and common attribute decoration (CommonPreset). Use when your consumer services are .NET-based.

Logger

const Logger: {
  setLogger(logger: ModelLoggingInterface): void;
};

interface ModelLoggingInterface {
  info(message: string, ...args: unknown[]): void;
  warn(message: string, ...args: unknown[]): void;
  debug(message: string, ...args: unknown[]): void;
  error(message: string, ...args: unknown[]): void;
}

Global logger singleton. Call Logger.setLogger(yourLogger) at startup to pipe Modelina's internal diagnostic messages into your application's log infrastructure (Winston, Pino, etc.).

CSHARP_DEFAULT_PRESET / CPLUSPLUS_DEFAULT_PRESET

const CSHARP_DEFAULT_PRESET: CSharpPreset;
const CPLUSPLUS_DEFAULT_PRESET: CplusplusPreset;

The built-in default preset for each language. Pass additional presets alongside these in the generator presets array to layer extra behaviour on top of the defaults.

Working examples

Scenario - Generate TypeScript models from a JSON Schema

A plain JSON Schema document is passed directly to the generator. The result array contains one OutputModel per discovered schema definition.

import { TypeScriptGenerator } from './modelina';

const schema = {
  $schema: 'http://json-schema.org/draft-07/schema',
  title: 'User',
  type: 'object',
  properties: {
    id:    { type: 'integer' },
    email: { type: 'string' },
    active: { type: 'boolean' }
  },
  required: ['id', 'email']
};

async function main() {
  const generator = new TypeScriptGenerator();
  const models = await generator.generate(schema);

  for (const model of models) {
    console.log(`// --- ${model.modelName}.ts ---`);
    console.log(model.result);
  }
}

main();

Scenario - Generate C# classes with Newtonsoft serialization preset

Use one of the built-in C# presets to add [JsonProperty] attributes automatically. Combine multiple presets by passing an array.

import {
  CSharpGenerator,
  CSHARP_DEFAULT_PRESET,
  NewtonsoftSerializerPreset
} from './modelina';

const schema = {
  title: 'Order',
  type: 'object',
  properties: {
    orderId: { type: 'string' },
    total:   { type: 'number' }
  }
};

async function main() {
  const generator = new CSharpGenerator({
    presets: [
      CSHARP_DEFAULT_PRESET,
      { preset: NewtonsoftSerializerPreset }
    ]
  });

  const models = await generator.generate(schema);
  for (const model of models) {
    console.log(model.result);
  }
}

main();

Scenario - Plug in a custom logger and use custom model-name constraints

Replace the default silent logger with Pino, and override the model-name constrainer to enforce a Dto suffix on every generated class name.

import pino from 'pino';
import { Logger, TypeScriptGenerator } from './modelina';
import type { ModelLoggingInterface } from './modelina';

const pinoLogger = pino();

const modelinaLogger: ModelLoggingInterface = {
  info:  (msg, ...a) => pinoLogger.info(a, msg),
  warn:  (msg, ...a) => pinoLogger.warn(a, msg),
  debug: (msg, ...a) => pinoLogger.debug(a, msg),
  error: (msg, ...a) => pinoLogger.error(a, msg)
};

Logger.setLogger(modelinaLogger);

const generator = new TypeScriptGenerator({
  constraints: {
    modelName: ({ modelName }) => `${modelName}Dto`
  }
});

const schema = {
  title: 'Product',
  type: 'object',
  properties: { sku: { type: 'string' }, price: { type: 'number' } }
};

generator.generate(schema).then(models => {
  models.forEach(m => console.log(m.result));
});

File walkthrough

• index.ts - Root barrel; re-exports everything from generators, helpers, models, processors, and selectively from utils (Logger, ModelLoggingInterface).
• generators/ - Contains one sub-directory per target language plus abstract base classes (AbstractGenerator, AbstractRenderer, AbstractDependencyManager, AbstractFileGenerator).
• generators/AbstractGenerator.ts - Base class all language generators extend; defines generate() and constraint/preset pipeline.
• generators/AbstractRenderer.ts - Base renderer with common rendering helpers used by every language-specific renderer.
• generators/AbstractDependencyManager.ts - Tracks import/dependency accumulation during code generation.
• generators/AbstractFileGenerator.ts - Adds file-system output capability on top of the base generator.
• helpers/ - Cross-cutting utility functions (naming, formatting) shared across the interpreter and generators.
• interpreter/ - Converts raw AsyncAPI/OpenAPI/JSON Schema inputs into the internal InputMetaModel format.
• models/ - Core meta-model classes: ConstrainedObjectModel, ConstrainedEnumModel, UnionModel, etc. These are what renderers operate on.
• processors/ - Dedicated input processor per schema format; normalises heterogeneous inputs before interpretation.
• utils/ - Logger singleton and ModelLoggingInterface type; only these two symbols are exported from index.ts.

Common pitfalls and fixes

• ESM/CJS interop errors - Modelina is CommonJS; if your project uses "type": "module", set "module": "commonjs" in tsconfig.json or use dynamic import() with an interop wrapper.
• $ref resolution fails at runtime - @apidevtools/json-schema-ref-parser makes HTTP requests to resolve remote $refs; ensure outbound HTTP is allowed in CI and that the schema host is reachable.
• TypeScript version below 4.7 - Template literal types and infer variance used internally will cause compile errors; pin typescript >= 4.7.0 in devDependencies.
• Duplicate symbol exports when mixing language generators - All generators re-export from the same root index.ts; use named imports rather than wildcard import * to avoid namespace collisions.
• Preset order matters - Presets are applied in array order; the default preset should appear first so custom presets can override specific hooks cleanly.
• typescript-json-schema requires reflect-metadata - If you invoke the TypeScript generator on TypeScript class source files rather than JSON Schema, add import 'reflect-metadata' at your entry point and enable emitDecoratorMetadata in tsconfig.json.

Vibe-coding prompt template

I have the Modelina source code located at `src/modelina/` in my project.
The integration guide is at `USAGE.md` (read it first for real import paths and API signatures).
The upstream npm package is `@asyncapi/modelina@5.10.1`.

Please help me integrate Modelina into my existing Node.js/TypeScript project step by step:

1. Read USAGE.md and src/modelina/index.ts to understand what is exported.
2. Install all required runtime dependencies listed in USAGE.md.
3. Update my tsconfig.json to compile the source alongside my project.
4. Create a `src/codegen/generate.ts` file that:
   - Reads an AsyncAPI or JSON Schema document from disk.
   - Uses the appropriate Modelina generator (ask me which target language).
   - Writes each OutputModel's `result` string to a file in `src/generated/`.
5. Wire the generator call into my existing Express app startup or a standalone CLI script.
6. Show me how to plug in my existing Winston logger using Logger.setLogger().

Only use imports and symbols that exist in src/modelina/index.ts and the files shown in USAGE.md.
Do not install the pre-built npm package; use the local source exclusively.

License and credit

Modelina is published under the Apache-2.0 license (see source/LICENSE if present, or the upstream repository). Upstream package: @asyncapi/modelina on npm — source and full documentation at https://www.modelina.org.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。