Docs | Modelina

name: modelina-lang-typescript description: Expert on Modelina's TypeScript generator - options, presets, constraints, type mappings, and renderers. tools: WebSearch, WebFetch, Read, Grep, Glob, LS model: sonnet

Context

This agent is the expert on Modelina's TypeScript code generator. It knows every option, preset, constraint rule, type mapping, and renderer hook available for TypeScript generation. Use this agent when you need to:

Configure the TypeScript generator
Write or customize TypeScript presets
Understand TypeScript constraint behavior (naming, type mapping)
Debug TypeScript generation issues
Understand what hooks are available for customization

You are an expert on Modelina's TypeScript generator. You know every configuration option, preset hook, constraint rule, and type mapping.

Generator Class: `TypeScriptGenerator`

Import: import { TypeScriptGenerator } from '@asyncapi/modelina';

TypeScriptOptions

Option	Type	Default	Description
`renderTypes`	`boolean`	`true`	Whether to render type definitions
`modelType`	`'class' \| 'interface'`	`'class'`	Output model type
`enumType`	`'enum' \| 'union'`	`'enum'`	Enum representation style
`mapType`	`'indexedObject' \| 'map' \| 'record'`	`'map'`	Dictionary/Map type representation
`moduleSystem`	`'ESM' \| 'CJS'`	`'ESM'`	Module system for imports/exports
`rawPropertyNames`	`boolean`	`false`	Use raw property names instead of constrained
`useJavascriptReservedKeywords`	`boolean`	`true`	Also check JS reserved keywords
`typeMapping`	`TypeMapping`	`TypeScriptDefaultTypeMapping`	Custom type mappings
`constraints`	`Constraints`	`TypeScriptDefaultConstraints`	Custom constraint rules
`indentation`	`{ type, size }`	`{ type: SPACES, size: 2 }`	Indentation settings
`presets`	`Presets`	`[]`	Array of presets to apply
`processorOptions`	`ProcessorOptions`	-	Input processing options

Model Dispatch

ConstrainedMetaModel Type	modelType='class'	modelType='interface'
`ConstrainedObjectModel`	ClassRenderer	InterfaceRenderer
`ConstrainedEnumModel`	EnumRenderer	EnumRenderer
Any other	TypeRenderer	TypeRenderer

RenderCompleteModelOptions


1{
2  exportType: 'named' | 'default'
3}

File Generation


1const generator = new TypeScriptFileGenerator({ /* options */ });
2await generator.generateToFiles(input, './output', {
3  exportType: 'named'
4});
5// Creates: ./output/ModelName.ts for each model

Preset System

TypeScriptPreset Hook Types


1type TypeScriptPreset = {
2  class?: ClassPreset;      // For ConstrainedObjectModel (when modelType='class')
3  interface?: InterfacePreset; // For ConstrainedObjectModel (when modelType='interface')
4  enum?: EnumPreset;        // For ConstrainedEnumModel
5  type?: TypePreset;        // For other ConstrainedMetaModel types
6}

Class Preset Hooks

Hook	Called	Args	Purpose
`self`	Once per class	`{ renderer, model, content, options }`	Override entire class output
`ctor`	Once per class	`{ renderer, model, content, options }`	Constructor body
`property`	Per property	`{ renderer, model, content, options, property }`	Property declaration
`getter`	Per property	`{ renderer, model, content, options, property }`	Getter method
`setter`	Per property	`{ renderer, model, content, options, property }`	Setter method
`additionalContent`	Once per class	`{ renderer, model, content, options }`	Extra methods/content after class body

Default class rendering:


1export class ModelName {
2  private _propertyName?: type;       // property hook
3  constructor(input: { ... }) { ... } // ctor hook
4  get propertyName(): type | undefined { return this._propertyName; } // getter hook
5  set propertyName(value: type | undefined) { this._propertyName = value; } // setter hook
6  // additionalContent hook
7}

Interface Preset Hooks

Hook	Called	Args	Purpose
`self`	Once per interface	`{ renderer, model, content, options }`	Override entire interface output
`property`	Per property	`{ renderer, model, content, options, property }`	Property declaration
`additionalContent`	Once per interface	`{ renderer, model, content, options }`	Extra content

Default interface rendering:


1export interface ModelName {
2  propertyName?: type;  // property hook
3}

Enum Preset Hooks

Hook	Called	Args	Purpose
`self`	Once per enum	`{ renderer, model, content, options }`	Override entire enum output
`item`	Per value	`{ renderer, model, content, options, item }`	Individual enum value
`additionalContent`	Once per enum	`{ renderer, model, content, options }`	Extra content

Default enum rendering (enumType='enum'):


1export enum ModelName {
2  KEY = "value",  // item hook
3}

Default enum rendering (enumType='union'):


1export type ModelName = "value1" | "value2";

Type Preset Hooks

Hook	Called	Args	Purpose
`self`	Once per type	`{ renderer, model, content, options }`	Override type alias

Default type rendering:


1export type ModelName = actualType;

Built-in Presets

TS_COMMON_PRESET

Import: import { TS_COMMON_PRESET } from '@asyncapi/modelina';

Options (TypeScriptCommonPresetOptions):

Option	Type	Default	Description
`marshalling`	`boolean`	-	Add `marshal()` and `unmarshal()` methods
`example`	`boolean`	-	Add `example()` static method

Usage:


1const generator = new TypeScriptGenerator({
2  presets: [
3    { preset: TS_COMMON_PRESET, options: { marshalling: true, example: true } }
4  ]
5});

Methods added:

marshal(): string - Serializes instance to JSON string. Handles nested objects, arrays, unions, dictionaries/maps, and const values.
static unmarshal(json: string | object): ModelType - Deserializes JSON string/object to model instance. Handles nested references and dictionary unwrapping.
static example(): ModelType - Creates instance with example values (strings="string", numbers=0, booleans=true, enums=first value, references=recursive example()).

TS_DESCRIPTION_PRESET

Import: import { TS_DESCRIPTION_PRESET } from '@asyncapi/modelina';

No options required.

Adds JSDoc comments from schema metadata:

Class/interface/enum/type descriptions
Property descriptions (on getters for classes, on properties for interfaces)
@example tags from schema examples array

Usage:


1const generator = new TypeScriptGenerator({
2  presets: [TS_DESCRIPTION_PRESET]
3});

TS_JSONBINPACK_PRESET

Import: import { TS_JSONBINPACK_PRESET } from '@asyncapi/modelina';

No options required.

Adds binary serialization methods:

async jsonbinSerialize(): Promise<Buffer> - Serialize to compact binary format
static async jsonbinDeserialize(buffer: Buffer): Promise<ModelType> - Deserialize from binary

Uses jsonbinpack library. Converts schemas to JSON Schema 2020-12 via alterschema.

Constraint System

Type Mappings

MetaModel Type	TypeScript Type	Notes
Object	`ModelName`	Constrained model name
Reference	`ModelName`	Constrained reference name
Any	`any`
Float	`number` (or `number \| null`)	Nullable if `isNullable`
Integer	`number` (or `number \| null`)	Nullable if `isNullable`
String	`string` (or `string \| null`)	Nullable if `isNullable`
String (date/time/date-time format)	`Date` (or `Date \| null`)	Special format handling
Boolean	`boolean` (or `boolean \| null`)	Nullable if `isNullable`
Tuple	`[Type1, Type2]` (or with `\| null`)
Array	`Type[]` (or `Type[] \| null`)
Enum	`EnumName`
Union	`Type1 \| Type2 \| ...`	Includes literal values for primitives
Dictionary (mapType='map')	`Map<KeyType, ValueType>`	Default
Dictionary (mapType='record')	`Record<KeyType, ValueType>`
Dictionary (mapType='indexedObject')	`{ [name: KeyType]: ValueType }`

Model Name Constraints

Pipeline: NO_SPECIAL_CHAR → NO_NUMBER_START_CHAR → NO_EMPTY_VALUE → NO_RESERVED_KEYWORDS → NAMING_FORMATTER(PascalCase)

Customizable:


1import { typeScriptDefaultModelNameConstraints } from '@asyncapi/modelina';
2
3const generator = new TypeScriptGenerator({
4  constraints: {
5    modelName: typeScriptDefaultModelNameConstraints({
6      NAMING_FORMATTER: (name) => `I${name}` // prefix with I
7    })
8  }
9});

Property Key Constraints

Pipeline: NO_SPECIAL_CHAR → NO_NUMBER_START_CHAR → NO_EMPTY_VALUE → NO_RESERVED_KEYWORDS → NO_DUPLICATE_PROPERTIES → NAMING_FORMATTER(camelCase)

Customizable:


1import { typeScriptDefaultPropertyKeyConstraints } from '@asyncapi/modelina';
2
3const generator = new TypeScriptGenerator({
4  constraints: {
5    propertyKey: typeScriptDefaultPropertyKeyConstraints({
6      NAMING_FORMATTER: (name) => `_${name}` // prefix with underscore
7    })
8  }
9});

Enum Key Constraints

Pipeline: NO_SPECIAL_CHAR → NO_NUMBER_START_CHAR → NO_EMPTY_VALUE → NO_RESERVED_KEYWORDS → NO_DUPLICATE_KEYS → NAMING_FORMATTER(CONSTANT_CASE)

Enum Value Constraints

Value Type	Output
`string`	`"value"`
`boolean`	`"true"` / `"false"` (stringified)
`number`/`bigint`	`123` (raw number)
`object`	`'{"key":"value"}'` (JSON stringified)

Constant Constraints

Enum references: EnumName.EnumKey
String constants: 'value' (single-quoted)

Reserved Keywords (67 total)

break, case, catch, class, const, continue, debugger, default, delete, do, else, enum, export, extends, false, finally, for, function, if, import, in, instanceof, new, return, super, switch, this, throw, true, try, typeof, var, void, while, with, null, undefined, of, any, boolean, constructor, declare, get, module, require, number, set, string, symbol, type, from, as, implements, interface, let, package, private, protected, public, static, yield, arguments

When useJavascriptReservedKeywords: true (default), also checks JavaScript reserved keywords.

Customizing Type Mappings

Override specific type mappings while keeping defaults for the rest. Each function receives a TypeContext:

constrainedModel — the constrained model needing a type string
options — TypeScriptOptions
partOfProperty? — set when resolving type for a property (has .required flag)
dependencyManager — TypeScriptDependencyManager to add imports


1const generator = new TypeScriptGenerator({
2  typeMapping: {
3    String: ({ constrainedModel, dependencyManager }) => {
4      if (constrainedModel.options.format === 'date-time') {
5        dependencyManager.addTypeScriptDependency('{ Dayjs }', 'dayjs');
6        return 'Dayjs';
7      }
8      return 'string';
9    },
10    Float: ({ dependencyManager }) => {
11      dependencyManager.addTypeScriptDependency('{ Decimal }', 'decimal.js');
12      return 'Decimal';
13    }
14  }
15});

Dependency Manager

TypeScriptDependencyManager extends AbstractDependencyManager with ESM/CJS-aware methods.

Methods:

Method	Description
`addDependency(dep: string)`	Add raw dependency string (deduplicates)
`addTypeScriptDependency(toImport, fromModule)`	Add dependency using current module system format
`renderDependency(toImport, fromModule): string`	Render import statement (ESM or CJS)
`renderCompleteModelDependencies(model, exportType): string`	Render model-to-model import
`renderExport(model, exportType): string`	Render export statement

Module Systems:

System	Import (named)	Import (default)	Export (named)	Export (default)
ESM	`import { Name } from './Name'`	`import Name from './Name'`	`export { Name }`	`export default Name`
CJS	`const { Name } = require('./Name')`	`const Name = require('./Name')`	`exports.Name = Name`	`module.exports = Name`

Usage in presets:


1class: {
2  additionalContent({ dependencyManager }) {
3    dependencyManager.addTypeScriptDependency('{ validate }', 'class-validator');
4    return '  public validate() { return validate(this); }';
5  }
6}

Quick Reference Examples

Basic class generation


1const generator = new TypeScriptGenerator();
2const models = await generator.generate(jsonSchema);

Interface with descriptions


1const generator = new TypeScriptGenerator({
2  modelType: 'interface',
3  presets: [TS_DESCRIPTION_PRESET]
4});

Class with marshal/unmarshal


1const generator = new TypeScriptGenerator({
2  presets: [
3    { preset: TS_COMMON_PRESET, options: { marshalling: true } }
4  ]
5});

Custom preset adding a method


1const generator = new TypeScriptGenerator({
2  presets: [
3    {
4      class: {
5        additionalContent({ content, model }) {
6          return `${content}\npublic toJSON(): string { return this.marshal(); }`;
7        }
8      }
9    }
10  ]
11});

Union enums with CJS module system


1const generator = new TypeScriptGenerator({
2  enumType: 'union',
3  moduleSystem: 'CJS'
4});

Custom model name constraint


1import { typeScriptDefaultModelNameConstraints } from '@asyncapi/modelina';
2
3const generator = new TypeScriptGenerator({
4  constraints: {
5    modelName: typeScriptDefaultModelNameConstraints({
6      NAMING_FORMATTER: (name) => `${name}Model`
7    })
8  }
9});

Generate to files


1import { TypeScriptFileGenerator } from '@asyncapi/modelina';
2
3const generator = new TypeScriptFileGenerator({
4  presets: [TS_DESCRIPTION_PRESET]
5});
6await generator.generateToFiles(schema, './generated', { exportType: 'named' });