@goast/typescript 0.9.0 → 0.9.1

package/dist/src/ast/utils/write-ts-nodes.js

@@ -1,5 +1,12 @@
 import { notNullish, toArray, } from '@goast/core';
 import { TsNode } from '../node.js';
+/**
+ * Writes a single node or value to a builder.
+ * A `TsNode` writes itself. Any other value is passed to the builder's `append` method.
+ * @template TBuilder The type of the source builder the node is written to.
+ * @param builder The builder to write to.
+ * @param node The node or value to write.
+ */
 export function writeTsNode(builder, node) {
     if (node instanceof TsNode) {
         node.write(builder);
@@ -8,6 +15,15 @@ export function writeTsNode(builder, node) {
         builder.append(node);
     }
 }
+/**
+ * Writes one or more nodes or values to a builder, one after another.
+ * Nullish entries are skipped, and nothing is written when no entries remain. Without a separator, the entries are
+ * written back to back, so any line break has to come from the nodes themselves.
+ * @template TBuilder The type of the source builder the nodes are written to.
+ * @param builder The builder to write to.
+ * @param nodes The nodes or values to write. A single entry is also accepted.
+ * @param options Options for writing. `separator` is written between each pair of written entries.
+ */
 export function writeTsNodes(builder, nodes, options) {
     const filteredNodes = toArray(nodes).filter(notNullish);
     if (filteredNodes.length === 1) {

package/dist/src/ast/utils/write-ts-parameters.d.ts

@@ -1,3 +1,12 @@
 import { type AppendValue, type Nullable, type SingleOrMultiple, type SourceBuilder } from '@goast/core';
 import type { TsNode } from '../node.ts';
+/**
+ * Writes a parameter list in parentheses, such as `(a: string, b: number)`.
+ * The parameters are written on one line, separated by `, `, unless there are more than two of them or any of them has
+ * decorators. Otherwise each parameter is written on its own line, separated by `,` and a line break, and the closing
+ * parenthesis is written on its own line. Nullish entries are skipped.
+ * @template TBuilder The type of the source builder the parameters are written to.
+ * @param builder The builder to write to.
+ * @param nodes The parameters to write. A single parameter is also accepted.
+ */
 export declare function writeTsParameters<TBuilder extends SourceBuilder>(builder: TBuilder, nodes: SingleOrMultiple<Nullable<TsNode<TBuilder> | AppendValue<TBuilder>>>): void;

package/dist/src/ast/utils/write-ts-parameters.js

@@ -1,5 +1,14 @@
 import { notNullish, toArray, } from '@goast/core';
 import { writeTsNodes } from './write-ts-nodes.js';
+/**
+ * Writes a parameter list in parentheses, such as `(a: string, b: number)`.
+ * The parameters are written on one line, separated by `, `, unless there are more than two of them or any of them has
+ * decorators. Otherwise each parameter is written on its own line, separated by `,` and a line break, and the closing
+ * parenthesis is written on its own line. Nullish entries are skipped.
+ * @template TBuilder The type of the source builder the parameters are written to.
+ * @param builder The builder to write to.
+ * @param nodes The parameters to write. A single parameter is also accepted.
+ */
 export function writeTsParameters(builder, nodes) {
     const filteredNodes = toArray(nodes).filter(notNullish);
     const multiline = filteredNodes.length > 2 ||

package/dist/src/common-results.d.ts

@@ -1,24 +1,89 @@
 import type { TypeScriptExportOptions } from './import-collection.ts';
+/**
+ * The kind of TypeScript declaration that a generated component is. The models index file re-exports components of
+ * kind `type` and `interface` with `export type`.
+ */
 export type TypeScriptComponentOutputKind = 'interface' | 'type' | 'enum' | 'class' | 'function' | 'variable';
+/**
+ * Describes a component (a type, interface, enum, class, ...) that a generator wrote or declared. The models generator
+ * publishes one of these for each schema as `typescript.models[schemaId]`, so that later generators can reference the
+ * component with `TypeScriptFileBuilder.appendModelUsage` without knowing how it was generated.
+ */
 export type TypeScriptComponentOutput = {
+    /**
+     * The name of the component. For an unnamed schema that is inlined, this is the type declaration itself.
+     */
     component: string;
+    /**
+     * The path of the file that the component was saved to. Omitted if the component is not saved in a file of its own.
+     */
     filePath?: string;
+    /**
+     * The imports that are required to use the component. For a component saved in a file, this is the import from
+     * that file.
+     */
     imports: TypeScriptImport[];
+    /**
+     * Other names that the file at `filePath` exports besides `component`. Strings are value exports, and objects can
+     * set the export type with `type`. The models index file re-exports them.
+     */
     additionalExports?: string[] | ({
         name: string;
     } & TypeScriptExportOptions)[];
+    /**
+     * The kind of declaration of the component, if known. See `TypeScriptComponentOutputKind`.
+     */
     kind?: TypeScriptComponentOutputKind;
 };
+/**
+ * A component that a generator wrote to a file of its own, so the file path is always known. The `type` option of
+ * `TypeScriptExportOptions` sets how the component is exported.
+ */
 export type TypeScriptExportOutput = {
+    /**
+     * The name of the exported component.
+     */
     component: string;
+    /**
+     * The path of the file that the component was written to.
+     */
     filePath: string;
 } & TypeScriptExportOptions;
+/**
+ * How the module path of an import is resolved. A `file` is a project file whose path ends in `.ts`, `.js` or `.json`.
+ * Its path is written relative to the importing file and transformed by `importModuleTransformer`. A `module` is a
+ * package name, such as `rxjs`, which is written as it is.
+ */
 export type TypeScriptImportKind = 'module' | 'file';
+/**
+ * The form of an import statement. `import` writes `import { X } from '...';`, `type-import` writes
+ * `import type { X } from '...';`, and `js-doc` writes the name in an `@import` tag inside a JSDoc comment.
+ */
 export type TypeScriptImportType = 'import' | 'type-import' | 'js-doc';
+/**
+ * The form of a re-export statement. `export` writes `export { X } from '...';`, and `type-export` writes
+ * `export type { X } from '...';`.
+ */
 export type TypeScriptExportType = 'export' | 'type-export';
+/**
+ * A single named import that a component needs. The imports are collected by `ImportExportCollection` and written as
+ * import statements at the top of the file by `TypeScriptFileBuilder`.
+ */
 export type TypeScriptImport = {
+    /**
+     * Whether `modulePath` is a project file or a package. See `TypeScriptImportKind`.
+     */
     kind: TypeScriptImportKind;
+    /**
+     * The form of the import statement. See `TypeScriptImportType`.
+     */
     type: TypeScriptImportType;
+    /**
+     * The path of the file that exports the name for a `file` import, or the package name for a `module` import.
+     */
     modulePath: string;
+    /**
+     * The name that is imported.
+     */
     name: string;
 };

package/dist/src/config.d.ts

@@ -1,13 +1,32 @@
 import type { DefaultGenerationProviderConfig, ExtendedStringCasing, OpenApiGeneratorConfig } from '@goast/core';
 import type { ImportModuleTransformer } from './utils.ts';
+/**
+ * The configuration that is shared by all TypeScript generators, on top of the `OpenApiGeneratorConfig` options.
+ * It controls the casing of generated names, how import module paths are written, and some output style settings.
+ * @see defaultTypeScriptGeneratorConfig
+ */
 export type TypeScriptGeneratorConfig = OpenApiGeneratorConfig & {
     /**
      * The transformer to use for transforming import module paths.
+     * It only applies to imports of project files (paths ending in `.ts`, `.js` or `.json`) into a file with a known
+     * path.
+     * A function receives the relative path, such as `../models/user.ts`, and returns the path to write.
+     * @example
+     * ```ts
+     * // Importing `src/models/user.ts` from `src/services/api.ts` produces:
+     * // 'omit-extension': '../models/user'
+     * // 'with-extension': '../models/user.ts'
+     * // 'js-extension': '../models/user.js'
+     * ```
      * @default 'omit-extension'
      */
     importModuleTransformer: ImportModuleTransformer;
     /**
      * The casing to use for file names.
+     * @example
+     * ```ts
+     * // With 'kebab', a model named `UserProfile` is written to `user-profile.ts`.
+     * ```
      * @default 'kebab'
      */
     fileNameCasing: ExtendedStringCasing;
@@ -33,11 +52,19 @@ export type TypeScriptGeneratorConfig = OpenApiGeneratorConfig & {
     enumValueNameCasing: ExtendedStringCasing;
     /**
      * The casing to use for constant names.
+     * @example
+     * ```ts
+     * // With the default, `fooBar` is written as `FOO_BAR`.
+     * ```
      * @default { casing: 'snake', wordCasing: 'all-upper' }
      */
     constantNameCasing: ExtendedStringCasing;
     /**
      * The casing to use for generic parameter names.
+     * @example
+     * ```ts
+     * // With the default, the discriminator property `kind` gets the generic parameter `TKind`.
+     * ```
      * @default { casing: 'pascal', prefix: 'T' }
      */
     genericParamNameCasing: ExtendedStringCasing;
@@ -62,4 +89,9 @@ export type TypeScriptGeneratorConfig = OpenApiGeneratorConfig & {
      */
     includeSourceInDocs: boolean;
 };
+/**
+ * The default values of the common TypeScript generator configuration. A generator uses these values for every
+ * property that is not set explicitly.
+ * @see TypeScriptGeneratorConfig
+ */
 export declare const defaultTypeScriptGeneratorConfig: DefaultGenerationProviderConfig<TypeScriptGeneratorConfig>;

package/dist/src/config.js

@@ -1,3 +1,8 @@
+/**
+ * The default values of the common TypeScript generator configuration. A generator uses these values for every
+ * property that is not set explicitly.
+ * @see TypeScriptGeneratorConfig
+ */
 export const defaultTypeScriptGeneratorConfig = {
     indent: { type: 'spaces', count: 2 },
     importModuleTransformer: 'omit-extension',

package/dist/src/file-builder.d.ts

@@ -3,27 +3,131 @@ import { TsNode } from './ast/node.ts';
 import { type TypeScriptGeneratorConfig } from './config.ts';
 import type { TypeScriptModelGeneratorOutput } from './generators/index.ts';
 import { ImportExportCollection, type TypeScriptExportOptions, type TypeScriptImportOptions } from './import-collection.ts';
+/**
+ * A value that can be appended to a `TypeScriptFileBuilder`: a TypeScript node, which is written together with its
+ * imports, or one of the additional values.
+ * @template TAdditionalAppends The additional value types that the builder accepts.
+ */
 export type TypeScriptAppends<TAdditionalAppends> = TsNode<TypeScriptFileBuilder> | TAdditionalAppends;
+/**
+ * The parameter type of the `append` methods of a `TypeScriptFileBuilder`: a single value, an array of values, or a
+ * function that appends content to the builder.
+ * @template TBuilder The type of the builder that the value is appended to.
+ * @template TAdditionalAppends The additional value types that the builder accepts.
+ */
 export type TypeScriptAppendParam<TBuilder extends TypeScriptFileBuilder, TAdditionalAppends> = AppendParam<TBuilder, TypeScriptAppends<TAdditionalAppends>>;
+/**
+ * Checks whether a value can be appended to a TypeScript file builder. This is the case for TypeScript nodes and for
+ * the values that a `SourceBuilder` accepts.
+ * @template TBuilder The type of the builder that the value is appended to.
+ * @param value The value to check.
+ * @returns `true` if the value can be appended, otherwise `false`.
+ */
 export declare function isTypeScriptAppendValue<TBuilder extends TypeScriptFileBuilder = TypeScriptFileBuilder>(value: unknown): value is AppendValue<TBuilder>;
+/**
+ * Builds a TypeScript source file. Content is appended like with any `SourceBuilder`, and the imports and exports that
+ * the content needs are collected next to it.
+ *
+ * Imports are rarely added by hand. A `TsReference` node that has a module name or a file path, such as
+ * `tsReference('User', '/out/models/user.ts')`, adds its import to the builder when the node is written, because
+ * `appendSingle` calls `write` on every TypeScript node. The collected imports are kept in `imports`, and `toString`
+ * writes them as import statements above the content. The statements therefore always end up at the top of the file,
+ * whatever the order of the appends was.
+ *
+ * File paths are turned into relative module paths based on the `filePath` of this builder, and the
+ * `importModuleTransformer` option decides how their extensions are written. See `ImportExportCollection`.
+ *
+ * @template TAdditionalAppends The additional value types that the builder accepts besides TypeScript nodes.
+ * @example
+ * ```ts
+ * const builder = new TypeScriptFileBuilder('/out/services/user.ts', defaultTypeScriptGeneratorConfig);
+ * builder.append(tsReference('User', '/out/models/user.ts'));
+ * builder.toString(); // => "import { User } from '../models/user';\n\nUser\n"
+ * ```
+ */
 export declare class TypeScriptFileBuilder<TAdditionalAppends = never> extends SourceBuilder<TypeScriptAppends<TAdditionalAppends>> {
+    /**
+     * The path of the file that this builder writes to, or `undefined` if the path is not known. Relative module paths of
+     * the imports are calculated from it.
+     */
     readonly filePath: string | undefined;
+    /**
+     * The imports and re-exports that the content of this builder needs. `toString` writes them above the content.
+     */
     readonly imports: ImportExportCollection;
+    /**
+     * Gets the TypeScript generator options that this builder uses.
+     */
     get options(): TypeScriptGeneratorConfig;
+    /**
+     * Initializes a new instance of the TypeScriptFileBuilder class.
+     * @param filePath The path of the file that the content is written to. Used by `writeToFile` and for relative
+     * imports.
+     * @param options The generator options. Defaults to `defaultTypeScriptGeneratorConfig`.
+     */
     constructor(filePath?: string, options?: TypeScriptGeneratorConfig);
+    /**
+     * Adds a named import to the file. The import is written above the content by `toString`. Adding the same name from
+     * the same module more than once writes it only once.
+     * @param name The name to import.
+     * @param moduleNameOrfilePath The module name, such as `rxjs`, or the path of the file that exports the name.
+     * @param options The options of the import, such as the import type. Defaults to a value import.
+     * @returns This builder, for chaining.
+     */
     addImport(name: string, moduleNameOrfilePath: string, options?: TypeScriptImportOptions): this;
+    /**
+     * Adds a re-export of a named export from a file, such as `export { User } from '../models/user';`. The re-export is
+     * written above the content by `toString`, after the imports.
+     * @param name The name to re-export.
+     * @param filePath The path of the file that exports the name.
+     * @param options The options of the export, such as the export type. Defaults to a value export.
+     * @returns This builder, for chaining.
+     */
     addExport(name: string, filePath: string, options?: TypeScriptExportOptions): this;
+    /**
+     * Removes all appended content, imports and re-exports from the builder.
+     */
     clear(): void;
+    /**
+     * Renders the complete file: the imports and re-exports first, then the appended content. A `// @ts-check` comment is
+     * added at the top for files with a `.js`, `.cjs` or `.mjs` extension.
+     * @param addPadding Whether to separate the imports from the content with a blank line, and to end the output with a
+     * line break. Defaults to `true`.
+     * @returns The source code of the file.
+     */
     toString(addPadding?: boolean): string;
     protected appendSingle(value: TypeScriptAppendParam<this, TAdditionalAppends>): void;
+    /**
+     * Appends the component of a model that another generator published, and adds the imports that the component needs.
+     * Use it to reference a model from `typescript.models`. With the `js-doc` import type, the JSDoc comments are removed
+     * from the component text and the imports are written as `@import` tags instead.
+     * @param type The published output of the model.
+     * @param options The import options, such as the import type, that apply to the imports of the model.
+     * @returns This builder, for chaining.
+     */
     appendModelUsage(type: TypeScriptModelGeneratorOutput, options?: TypeScriptImportOptions): this;
+    /**
+     * Writes the rendered file to disk with the generator options. Throws if no path is given and this builder has none.
+     * @param filePath The path of the file to write to. Defaults to the `filePath` of this builder.
+     */
     writeToFile(filePath?: string): void;
+    /**
+     * Creates a file builder for the file path, lets the generator callback fill it, and writes the file. Nothing happens
+     * if the path is empty. See `tryGenerate` for the details.
+     * @param options The file path, the optional log name, the generator options, and the callback that appends content.
+     */
     static generate(options: {
         filePath: string;
         logName?: Nullable<string>;
         options?: TypeScriptGeneratorConfig;
         generator: (builder: TypeScriptFileBuilder) => void;
     }): void;
+    /**
+     * Creates a file builder for the file path, lets the generator callback fill it, and writes the file. Unlike
+     * `generate`, a nullish path is accepted. In that case nothing is generated and the callback is not called.
+     * @param options The file path, the generator callback, the optional log name, and the generator options. The log
+     * name is logged as `Generating <log name> to <file path>...` before the file is generated.
+     */
     static tryGenerate({ filePath, generator, options, logName, }: {
         filePath: Nullable<string>;
         logName?: Nullable<string>;

package/dist/src/file-builder.js

@@ -2,15 +2,59 @@ import { isAppendValue, SourceBuilder, writeGeneratedFile, } from '@goast/core';
 import { TsNode } from './ast/node.js';
 import { defaultTypeScriptGeneratorConfig } from './config.js';
 import { ImportExportCollection, } from './import-collection.js';
+/**
+ * Checks whether a value can be appended to a TypeScript file builder. This is the case for TypeScript nodes and for
+ * the values that a `SourceBuilder` accepts.
+ * @template TBuilder The type of the builder that the value is appended to.
+ * @param value The value to check.
+ * @returns `true` if the value can be appended, otherwise `false`.
+ */
 export function isTypeScriptAppendValue(value) {
     return isAppendValue(value) || value instanceof TsNode;
 }
+/**
+ * Builds a TypeScript source file. Content is appended like with any `SourceBuilder`, and the imports and exports that
+ * the content needs are collected next to it.
+ *
+ * Imports are rarely added by hand. A `TsReference` node that has a module name or a file path, such as
+ * `tsReference('User', '/out/models/user.ts')`, adds its import to the builder when the node is written, because
+ * `appendSingle` calls `write` on every TypeScript node. The collected imports are kept in `imports`, and `toString`
+ * writes them as import statements above the content. The statements therefore always end up at the top of the file,
+ * whatever the order of the appends was.
+ *
+ * File paths are turned into relative module paths based on the `filePath` of this builder, and the
+ * `importModuleTransformer` option decides how their extensions are written. See `ImportExportCollection`.
+ *
+ * @template TAdditionalAppends The additional value types that the builder accepts besides TypeScript nodes.
+ * @example
+ * ```ts
+ * const builder = new TypeScriptFileBuilder('/out/services/user.ts', defaultTypeScriptGeneratorConfig);
+ * builder.append(tsReference('User', '/out/models/user.ts'));
+ * builder.toString(); // => "import { User } from '../models/user';\n\nUser\n"
+ * ```
+ */
 export class TypeScriptFileBuilder extends SourceBuilder {
+    /**
+     * The path of the file that this builder writes to, or `undefined` if the path is not known. Relative module paths of
+     * the imports are calculated from it.
+     */
     filePath;
+    /**
+     * The imports and re-exports that the content of this builder needs. `toString` writes them above the content.
+     */
     imports;
+    /**
+     * Gets the TypeScript generator options that this builder uses.
+     */
     get options() {
         return super.options;
     }
+    /**
+     * Initializes a new instance of the TypeScriptFileBuilder class.
+     * @param filePath The path of the file that the content is written to. Used by `writeToFile` and for relative
+     * imports.
+     * @param options The generator options. Defaults to `defaultTypeScriptGeneratorConfig`.
+     */
     constructor(filePath, options) {
         super(options ?? defaultTypeScriptGeneratorConfig);
         this.filePath = filePath;
@@ -20,18 +64,44 @@ export class TypeScriptFileBuilder extends SourceBuilder {
             useSingleQuotes: this.options.useSingleQuotes,
         });
     }
+    /**
+     * Adds a named import to the file. The import is written above the content by `toString`. Adding the same name from
+     * the same module more than once writes it only once.
+     * @param name The name to import.
+     * @param moduleNameOrfilePath The module name, such as `rxjs`, or the path of the file that exports the name.
+     * @param options The options of the import, such as the import type. Defaults to a value import.
+     * @returns This builder, for chaining.
+     */
     addImport(name, moduleNameOrfilePath, options) {
         this.imports.addImport(name, moduleNameOrfilePath, options);
         return this;
     }
+    /**
+     * Adds a re-export of a named export from a file, such as `export { User } from '../models/user';`. The re-export is
+     * written above the content by `toString`, after the imports.
+     * @param name The name to re-export.
+     * @param filePath The path of the file that exports the name.
+     * @param options The options of the export, such as the export type. Defaults to a value export.
+     * @returns This builder, for chaining.
+     */
     addExport(name, filePath, options) {
         this.imports.addExport(name, filePath, options);
         return this;
     }
+    /**
+     * Removes all appended content, imports and re-exports from the builder.
+     */
     clear() {
         super.clear();
         this.imports.clear();
     }
+    /**
+     * Renders the complete file: the imports and re-exports first, then the appended content. A `// @ts-check` comment is
+     * added at the top for files with a `.js`, `.cjs` or `.mjs` extension.
+     * @param addPadding Whether to separate the imports from the content with a blank line, and to end the output with a
+     * line break. Defaults to `true`.
+     * @returns The source code of the file.
+     */
     toString(addPadding = true) {
         const builder = new SourceBuilder(this.options);
         if (this.filePath?.match(/\.[cm]?js$/)) {
@@ -55,6 +125,14 @@ export class TypeScriptFileBuilder extends SourceBuilder {
             value.write(this);
         }
     }
+    /**
+     * Appends the component of a model that another generator published, and adds the imports that the component needs.
+     * Use it to reference a model from `typescript.models`. With the `js-doc` import type, the JSDoc comments are removed
+     * from the component text and the imports are written as `@import` tags instead.
+     * @param type The published output of the model.
+     * @param options The import options, such as the import type, that apply to the imports of the model.
+     * @returns This builder, for chaining.
+     */
     appendModelUsage(type, options) {
         this.append(options?.type === 'js-doc' ? type.component.replace(/\/\*\*.*\*\/\s*/gs, '') : type.component);
         for (const i of type.imports) {
@@ -62,6 +140,10 @@ export class TypeScriptFileBuilder extends SourceBuilder {
         }
         return this;
     }
+    /**
+     * Writes the rendered file to disk with the generator options. Throws if no path is given and this builder has none.
+     * @param filePath The path of the file to write to. Defaults to the `filePath` of this builder.
+     */
     writeToFile(filePath) {
         if (!filePath)
             filePath = this.filePath;
@@ -69,9 +151,20 @@ export class TypeScriptFileBuilder extends SourceBuilder {
             throw new Error('File path is required');
         writeGeneratedFile(this.options, filePath, this.toString());
     }
+    /**
+     * Creates a file builder for the file path, lets the generator callback fill it, and writes the file. Nothing happens
+     * if the path is empty. See `tryGenerate` for the details.
+     * @param options The file path, the optional log name, the generator options, and the callback that appends content.
+     */
     static generate(options) {
         TypeScriptFileBuilder.tryGenerate(options);
     }
+    /**
+     * Creates a file builder for the file path, lets the generator callback fill it, and writes the file. Unlike
+     * `generate`, a nullish path is accepted. In that case nothing is generated and the callback is not called.
+     * @param options The file path, the generator callback, the optional log name, and the generator options. The log
+     * name is logged as `Generating <log name> to <file path>...` before the file is generated.
+     */
     static tryGenerate({ filePath, generator, options, logName, }) {
         if (!filePath)
             return;

package/dist/src/generators/file-generator.d.ts

@@ -1,7 +1,21 @@
 import type { MaybePromise, OpenApiGenerationProviderContext, OpenApiGeneratorInput, SourceBuilder } from '@goast/core';
 import { ts } from '../ast/index.ts';
 import type { TypeScriptGeneratorConfig } from '../config.ts';
+/**
+ * Base class for the TypeScript generators that turn an OpenAPI generation context into TypeScript files.
+ *
+ * It only provides shared helpers. Subclasses such as the model and Angular service generators write their own files
+ * with `TypeScriptFileBuilder` and return the information that later generators need to reference them.
+ *
+ * @template TContext The type of the generation context, including the TypeScript generator configuration.
+ * @template TOutput The type of the output that `generate` returns.
+ */
 export declare abstract class TypeScriptFileGenerator<TContext extends OpenApiGenerationProviderContext<OpenApiGeneratorInput, TypeScriptGeneratorConfig>, TOutput> {
+    /**
+     * Generates the TypeScript files for the given context and returns the information about them.
+     * @param context The generation context, including the TypeScript generator configuration.
+     * @returns The output of the generator, or a promise that resolves to it.
+     */
     abstract generate(context: TContext): MaybePromise<TOutput>;
     protected getAnyType(context: TContext): ts.Reference<SourceBuilder>;
 }

package/dist/src/generators/file-generator.js

@@ -1,4 +1,13 @@
 import { ts } from '../ast/index.js';
+/**
+ * Base class for the TypeScript generators that turn an OpenAPI generation context into TypeScript files.
+ *
+ * It only provides shared helpers. Subclasses such as the model and Angular service generators write their own files
+ * with `TypeScriptFileBuilder` and return the information that later generators need to reference them.
+ *
+ * @template TContext The type of the generation context, including the TypeScript generator configuration.
+ * @template TOutput The type of the output that `generate` returns.
+ */
 export class TypeScriptFileGenerator {
     getAnyType(context) {
         return context.config.preferUnknown ? ts.refs.unknown() : ts.refs.any();

package/dist/src/generators/models/model-generator.d.ts

@@ -7,10 +7,34 @@ import type { TypeScriptModelGeneratorContext, TypeScriptModelGeneratorOutput }
 type Context = TypeScriptModelGeneratorContext;
 type Output = TypeScriptModelGeneratorOutput;
 type Builder = TypeScriptFileBuilder;
+/**
+ * Generates the model of a single schema. Implement it to replace the default model generation.
+ * @template TOutput The type of the result that is returned for the schema.
+ */
 export interface TypeScriptModelGenerator<TOutput extends Output = Output> {
+    /**
+     * Generates the model of the schema in the context.
+     * @param ctx The context of the schema to generate, including its configuration.
+     * @returns The result of the model, or a promise that resolves to it.
+     */
     generate(ctx: Context): MaybePromise<TOutput>;
 }
+/**
+ * The default model generator. It generates a schema as a type declaration (`type` or `interface`) or as an enum,
+ * depending on the `enumGeneration` and `typeDeclaration` options. Discriminator schemas also get a base type named
+ * with `discriminatorBaseTypeCasing`.
+ *
+ * A schema that is declared as its own type is written to `{outputDir}/{modelsDir}/{name}.ts`, with the file name
+ * cased by `modelFileNameCasing` (or `fileNameCasing`). Other schemas are only rendered as a type expression that is
+ * inlined where it is used, and no file is written for them.
+ */
 export declare class DefaultTypeScriptModelGenerator extends TypeScriptFileGenerator<Context, Output> implements TypeScriptModelGenerator {
+    /**
+     * Generates the model of the schema in the context and writes its file, if it has one.
+     * @param ctx The context of the schema to generate, including its configuration.
+     * @returns The component name, the imports and, if a file was written, its path. For an inline schema, the component
+     * is the type expression.
+     */
     generate(ctx: Context): MaybePromise<Output>;
     protected getNodeKind(node: unknown): TypeScriptComponentOutputKind | undefined;
     protected getFileContent(ctx: Context): AppendValueGroup<Builder>;

package/dist/src/generators/models/model-generator.js

@@ -4,7 +4,22 @@ import { ts } from '../../ast/index.js';
 import { TypeScriptFileBuilder } from '../../file-builder.js';
 import { getSourceDocLine } from '../../utils.js';
 import { TypeScriptFileGenerator } from '../file-generator.js';
+/**
+ * The default model generator. It generates a schema as a type declaration (`type` or `interface`) or as an enum,
+ * depending on the `enumGeneration` and `typeDeclaration` options. Discriminator schemas also get a base type named
+ * with `discriminatorBaseTypeCasing`.
+ *
+ * A schema that is declared as its own type is written to `{outputDir}/{modelsDir}/{name}.ts`, with the file name
+ * cased by `modelFileNameCasing` (or `fileNameCasing`). Other schemas are only rendered as a type expression that is
+ * inlined where it is used, and no file is written for them.
+ */
 export class DefaultTypeScriptModelGenerator extends TypeScriptFileGenerator {
+    /**
+     * Generates the model of the schema in the context and writes its file, if it has one.
+     * @param ctx The context of the schema to generate, including its configuration.
+     * @returns The component name, the imports and, if a file was written, its path. For an inline schema, the component
+     * is the type expression.
+     */
     generate(ctx) {
         if (this.shouldGenerateTypeDeclaration(ctx, ctx.schema)) {
             const name = this.getDeclarationTypeName(ctx, ctx.schema);

package/dist/src/generators/models/models-generator.d.ts

@@ -7,8 +7,24 @@ type Output = TypeScriptModelsGeneratorOutput;
 type Config = TypeScriptModelsGeneratorConfig;
 type SchemaOutput = TypeScriptModelGeneratorOutput;
 type Context = TypeScriptModelsGeneratorContext;
+/**
+ * Generates the models for all OpenAPI schemas.
+ *
+ * Each schema is generated by a `TypeScriptModelGenerator`, by default a `DefaultTypeScriptModelGenerator`. A schema
+ * that is declared as its own type is written to `{outputDir}/{modelsDir}/{name}.ts`. An index file that re-exports
+ * all models is written to `{outputDir}/{modelsIndexFile}`, unless `modelsIndexFile` is nullish.
+ *
+ * It publishes the following data for later generators:
+ * - `typescript.models`: The result of each schema, keyed by the schema ID (`ApiSchema['id']`).
+ * - `typescript.indexFiles.models`: The path of the index file, or `null` if no index file was generated.
+ */
 export declare class TypeScriptModelsGenerator extends OpenApiSchemasGenerationProviderBase<Input, Output, Config, SchemaOutput, Context> {
     private readonly _modelGeneratorFactory;
+    /**
+     * Initializes a new instance of the TypeScriptModelsGenerator class.
+     * @param modelGeneratorFactory The factory that creates the model generator used for each schema. If omitted, a
+     * `DefaultTypeScriptModelGenerator` is used.
+     */
     constructor(modelGeneratorFactory?: Factory<TypeScriptModelGenerator, []>);
     protected initResult(): Output;
     protected buildContext(context: OpenApiGeneratorContext<TypeScriptModelsGeneratorInput>, config?: Partial<Config> | undefined): Context;

package/dist/src/generators/models/models-generator.js

@@ -4,8 +4,24 @@ import { ts } from '../../ast/index.js';
 import { TypeScriptFileBuilder } from '../../file-builder.js';
 import { DefaultTypeScriptModelGenerator } from './model-generator.js';
 import { defaultTypeScriptModelsGeneratorConfig, } from './models.js';
+/**
+ * Generates the models for all OpenAPI schemas.
+ *
+ * Each schema is generated by a `TypeScriptModelGenerator`, by default a `DefaultTypeScriptModelGenerator`. A schema
+ * that is declared as its own type is written to `{outputDir}/{modelsDir}/{name}.ts`. An index file that re-exports
+ * all models is written to `{outputDir}/{modelsIndexFile}`, unless `modelsIndexFile` is nullish.
+ *
+ * It publishes the following data for later generators:
+ * - `typescript.models`: The result of each schema, keyed by the schema ID (`ApiSchema['id']`).
+ * - `typescript.indexFiles.models`: The path of the index file, or `null` if no index file was generated.
+ */
 export class TypeScriptModelsGenerator extends OpenApiSchemasGenerationProviderBase {
     _modelGeneratorFactory;
+    /**
+     * Initializes a new instance of the TypeScriptModelsGenerator class.
+     * @param modelGeneratorFactory The factory that creates the model generator used for each schema. If omitted, a
+     * `DefaultTypeScriptModelGenerator` is used.
+     */
     constructor(modelGeneratorFactory) {
         super();
         this._modelGeneratorFactory = modelGeneratorFactory ?? Factory.fromValue(new DefaultTypeScriptModelGenerator());