@goast/core 0.7.0 → 0.7.1

package/dist/src/ast/node.d.ts

@@ -1,15 +1,58 @@
 import type { StringBuilder } from '../utils/string-builder/string-builder.ts';
 import type { AppendValue } from '../utils/string-builder/utils.ts';
 import type { Prettify } from '../utils/type.utils.ts';
+/**
+ * The injection points of an AST node. For each name `X` in `TInjects`, the node accepts an optional `beforeX` and
+ * `afterX` value, such as `beforeName` for the name of a declaration. `before` and `after` are always available and
+ * wrap the whole node.
+ * @template TBuilder The type of the builder that the node is written to.
+ * @template TInjects The names of the injection points that the node supports, in addition to `before` and `after`.
+ * @see AstNode.write
+ */
 export type AstNodeInject<TBuilder extends StringBuilder, TInjects extends string> = {
     [K in `${'after' | 'before'}${Capitalize<TInjects>}`]?: AppendValue<TBuilder>;
 };
+/**
+ * The options that are accepted by the constructor of an AST node class. They combine the options of the subclass with
+ * the options of its base class constructor, so that language packages can extend the options of their base nodes.
+ * @template TBase The class whose constructor options are included.
+ * @template TExtensions The additional options of the subclass.
+ */
 export type AstNodeOptions<TBase extends abstract new (...args: any) => any, TExtensions extends object = {}> = Prettify<TExtensions & ConstructorParameters<TBase>[0]>;
+/**
+ * Base class for AST nodes that write themselves to a `StringBuilder`. The language packages build their nodes on it,
+ * for example `TsNode` in `@goast/typescript` and `KtNode` in `@goast/kotlin`.
+ *
+ * A node is written with `write`, which runs in three steps:
+ * 1. The node is pushed onto a history stack that is kept per builder. Nodes that are written while it is on the stack
+ *    can find it through `getParentNode`, which allows a node to render differently depending on where it is placed.
+ * 2. The `before` injection is appended, followed by the node's own output, which the subclass renders in `onWrite`.
+ * 3. The `after` injection is appended, and the node is popped from the history stack again.
+ *
+ * Injection points let callers add custom content to a node without subclassing it. `before` and `after` wrap the whole
+ * node. The node-specific injections declared through `TInjects`, such as `beforeDecorators` or `afterBody`, are
+ * appended by the subclass around the matching part of its output. Injected values are appended like any other value,
+ * so they can be strings, builder functions or arrays.
+ * @template TBuilder The type of the builder that the node is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ */
 export declare abstract class AstNode<TBuilder extends StringBuilder = StringBuilder, TInjects extends string = never> {
+    /**
+     * The values that are injected before and after this node or its parts. See the class documentation for details.
+     */
     inject: AstNodeInject<TBuilder, TInjects | ''>;
+    /**
+     * Initializes a new instance of the AstNode class.
+     * @param options The options of the node. Only `inject` is read by this base class.
+     */
     constructor(options: {
         inject?: AstNode<TBuilder, TInjects>['inject'];
     });
+    /**
+     * Writes this node to the builder. The `before` injection wraps the output of the node, and the node is registered in
+     * the history of the builder while it is written.
+     * @param builder The builder to write the node to.
+     */
     write(builder: TBuilder): void;
     protected getParentNode(builder: TBuilder): AstNode | undefined;
     protected abstract onWrite(builder: TBuilder): void;

package/dist/src/ast/node.js

@@ -1,9 +1,38 @@
 const NODE_HISTORY_SYMBOL = Symbol('node-history');
+/**
+ * Base class for AST nodes that write themselves to a `StringBuilder`. The language packages build their nodes on it,
+ * for example `TsNode` in `@goast/typescript` and `KtNode` in `@goast/kotlin`.
+ *
+ * A node is written with `write`, which runs in three steps:
+ * 1. The node is pushed onto a history stack that is kept per builder. Nodes that are written while it is on the stack
+ *    can find it through `getParentNode`, which allows a node to render differently depending on where it is placed.
+ * 2. The `before` injection is appended, followed by the node's own output, which the subclass renders in `onWrite`.
+ * 3. The `after` injection is appended, and the node is popped from the history stack again.
+ *
+ * Injection points let callers add custom content to a node without subclassing it. `before` and `after` wrap the whole
+ * node. The node-specific injections declared through `TInjects`, such as `beforeDecorators` or `afterBody`, are
+ * appended by the subclass around the matching part of its output. Injected values are appended like any other value,
+ * so they can be strings, builder functions or arrays.
+ * @template TBuilder The type of the builder that the node is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ */
 export class AstNode {
+    /**
+     * The values that are injected before and after this node or its parts. See the class documentation for details.
+     */
     inject;
+    /**
+     * Initializes a new instance of the AstNode class.
+     * @param options The options of the node. Only `inject` is read by this base class.
+     */
     constructor(options) {
         this.inject = options.inject ?? {};
     }
+    /**
+     * Writes this node to the builder. The `before` injection wraps the output of the node, and the node is registered in
+     * the history of the builder while it is written.
+     * @param builder The builder to write the node to.
+     */
     write(builder) {
         let history = builder[NODE_HISTORY_SYMBOL];
         if (!history) {

package/dist/src/codegen/config.d.ts

@@ -1,5 +1,10 @@
 import type { OpenApiParserOptions } from '../parse/types.ts';
 import { type SourceBuilderOptions } from '../utils/source-builder.ts';
+/**
+ * The configuration of the `OpenApiGenerator`. It combines the source builder options and the parser options
+ * with the output settings of the generator.
+ * @see OpenApiGenerator
+ */
 export type OpenApiGeneratorConfig = SourceBuilderOptions & OpenApiParserOptions & {
     /**
      * The directory where the generated files should be saved.
@@ -32,4 +37,8 @@ export type OpenApiGeneratorConfig = SourceBuilderOptions & OpenApiParserOptions
      */
     existingFileBehavior: 'override' | 'skip' | 'error' | 'count';
 };
+/**
+ * The default configuration of the `OpenApiGenerator`. Options passed to its constructor are merged on top of these.
+ * @see OpenApiGeneratorConfig
+ */
 export declare const defaultOpenApiGeneratorConfig: OpenApiGeneratorConfig;

package/dist/src/codegen/config.js

@@ -1,5 +1,9 @@
 import { defaultOpenApiTransformerOptions } from '../transform/types.js';
 import { defaultSourceBuilderOptions } from '../utils/source-builder.js';
+/**
+ * The default configuration of the `OpenApiGenerator`. Options passed to its constructor are merged on top of these.
+ * @see OpenApiGeneratorConfig
+ */
 export const defaultOpenApiGeneratorConfig = {
     ...defaultSourceBuilderOptions,
     ...defaultOpenApiTransformerOptions,

package/dist/src/codegen/endpoints-generator.d.ts

@@ -2,13 +2,45 @@ import type { ApiEndpoint } from '../transform/api-types.ts';
 import type { MaybePromise } from '../utils/type.utils.ts';
 import { type DefaultGenerationProviderConfig, OpenApiGenerationProviderBase } from './generator.ts';
 import type { AnyConfig, OpenApiGenerationProviderContext, OpenApiGeneratorContext, OpenApiGeneratorInput, OpenApiGeneratorOutput } from './types.ts';
+/**
+ * The context that is passed to the methods of `OpenApiEndpointsGenerationProviderBase`.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by the provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @template TEndpointOutput The type of the result produced for each endpoint.
+ */
 export type OpenApiEndpointsGenerationProviderContext<TInput extends OpenApiGeneratorInput, TOutput extends OpenApiGeneratorOutput, TConfig extends AnyConfig, TEndpointOutput extends OpenApiGeneratorOutput> = OpenApiGenerationProviderContext<TInput, TConfig> & {
+    /**
+     * The results that have been generated so far, keyed by the ID of their endpoint.
+     */
     existingEndpointResults: Map<string, TEndpointOutput>;
+    /**
+     * The output of the provider. It is created by `initResult` and returned after all endpoints have been generated.
+     */
     output: TOutput;
 };
+/**
+ * Base class for generation providers that produce one result per API endpoint.
+ * Results are cached per endpoint, so each endpoint is generated only once. Subclasses implement `initResult`,
+ * `generateEndpoint` and `addEndpointResult`, and can override `generateAdditionalFiles` to produce output after all
+ * endpoints have been processed.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by the provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @template TEndpointOutput The type of the result produced for each endpoint.
+ * @template TContext The type of the context that is passed to the provider methods.
+ * @see OpenApiGenerationProviderBase
+ */
 export declare abstract class OpenApiEndpointsGenerationProviderBase<TInput extends OpenApiGeneratorInput, TOutput extends OpenApiGeneratorOutput, TConfig extends AnyConfig, TEndpointOutput extends OpenApiGeneratorOutput, TContext extends OpenApiEndpointsGenerationProviderContext<TInput, TOutput, TConfig, TEndpointOutput>> extends OpenApiGenerationProviderBase<TInput, TOutput, TConfig, TContext> {
     protected getProviderContext(context: OpenApiGeneratorContext<TInput>, config: Partial<TConfig> | undefined, defaultConfig: DefaultGenerationProviderConfig<TConfig>): OpenApiEndpointsGenerationProviderContext<TInput, TOutput, TConfig, TEndpointOutput>;
     protected onGenerate(ctx: TContext): Promise<TOutput>;
+    /**
+     * Gets the result for an endpoint. The result is generated on the first call and returned from the cache afterwards.
+     * In test mode, the source location of the endpoint is stored in the result.
+     * @param ctx The context of the provider.
+     * @param endpoint The endpoint to get the result for.
+     * @returns The result for the endpoint.
+     */
     getEndpointResult(ctx: TContext, endpoint: ApiEndpoint): Promise<TEndpointOutput>;
     protected abstract initResult(ctx: OpenApiGenerationProviderContext<TInput, TConfig>): TOutput;
     protected abstract generateEndpoint(ctx: TContext, endpoint: ApiEndpoint): Promise<TEndpointOutput>;

package/dist/src/codegen/endpoints-generator.js

@@ -1,5 +1,17 @@
 import { OpenApiGenerationProviderBase } from './generator.js';
 import { addSourceIfTest } from './internal-utils.js';
+/**
+ * Base class for generation providers that produce one result per API endpoint.
+ * Results are cached per endpoint, so each endpoint is generated only once. Subclasses implement `initResult`,
+ * `generateEndpoint` and `addEndpointResult`, and can override `generateAdditionalFiles` to produce output after all
+ * endpoints have been processed.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by the provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @template TEndpointOutput The type of the result produced for each endpoint.
+ * @template TContext The type of the context that is passed to the provider methods.
+ * @see OpenApiGenerationProviderBase
+ */
 export class OpenApiEndpointsGenerationProviderBase extends OpenApiGenerationProviderBase {
     getProviderContext(context, config, defaultConfig) {
         const ctx = super.getProviderContext(context, config, defaultConfig);
@@ -15,6 +27,13 @@ export class OpenApiEndpointsGenerationProviderBase extends OpenApiGenerationPro
         await this.generateAdditionalFiles(ctx);
         return ctx.output;
     }
+    /**
+     * Gets the result for an endpoint. The result is generated on the first call and returned from the cache afterwards.
+     * In test mode, the source location of the endpoint is stored in the result.
+     * @param ctx The context of the provider.
+     * @param endpoint The endpoint to get the result for.
+     * @returns The result for the endpoint.
+     */
     async getEndpointResult(ctx, endpoint) {
         const existingResult = ctx.existingEndpointResults.get(endpoint.id);
         if (existingResult)

package/dist/src/codegen/generator.d.ts

@@ -17,19 +17,127 @@ declare class _OpenApiGenerator<TOutput extends OpenApiGeneratorInput> {
     private readonly _config;
     private readonly _parser;
     constructor(config: OpenApiGeneratorConfig, providers: OpenApiGenerationProviders, parser: OpenApiParser);
+    /**
+     * Adds a generation provider to the pipeline. Providers run in the order they were added.
+     * @template PInput The input the provider requires. The output of the providers added so far must satisfy it.
+     * @template POutput The output produced by the provider.
+     * @template PConfig The type of the provider-specific configuration.
+     * @param provider The provider to add. Its output is deep-merged into the input of the following providers.
+     * @param config The provider-specific configuration that is passed to the provider when it runs.
+     * @returns A new generator whose output type includes the output of the added provider.
+     */
     use<PInput extends OpenApiGeneratorInput, POutput extends OpenApiGeneratorOutput, PConfig extends AnyConfig>(provider: ActionProvider<OpenApiGenerationProviderFn<VInput<PInput, TOutput>, POutput, PConfig>>, config?: Partial<PConfig>): _OpenApiGenerator<Merge<[TOutput, POutput]>>;
+    /**
+     * Adds a generation provider from a class. A new instance of the class is created when the generator runs,
+     * and its `generate` method is called to produce the output.
+     * @template PInput The input the provider requires. The output of the providers added so far must satisfy it.
+     * @template POutput The output produced by the provider.
+     * @template PConfig The type of the provider-specific configuration.
+     * @param type The class of the provider. It must have a constructor without parameters.
+     * @param config The provider-specific configuration that is passed to the provider when it runs.
+     * @returns A new generator whose output type includes the output of the added provider.
+     * @see OpenApiGenerationProvider
+     */
     useType<PInput extends OpenApiGeneratorInput, POutput extends OpenApiGeneratorOutput, PConfig extends AnyConfig>(type: EmptyConstructor<OpenApiGenerationProvider<VInput<PInput, TOutput>, POutput, PConfig>>, config?: Partial<PConfig>): _OpenApiGenerator<Merge<[TOutput, POutput]>>;
+    /**
+     * Adds a generation provider from a function. The function is called when the generator runs.
+     * @template PInput The input the function requires. The output of the providers added so far must satisfy it.
+     * @template POutput The output produced by the function.
+     * @template PConfig The type of the provider-specific configuration.
+     * @param fn The function that produces the output of the provider.
+     * @param config The provider-specific configuration that is passed to the function when it runs.
+     * @returns A new generator whose output type includes the output of the added provider.
+     * @see OpenApiGenerationProviderFn
+     */
     useFn<PInput extends TOutput, POutput extends OpenApiGeneratorOutput, PConfig extends AnyConfig>(fn: OpenApiGenerationProviderFn<VInput<PInput, TOutput>, POutput, PConfig>, config?: Partial<PConfig>): _OpenApiGenerator<Merge<[TOutput, POutput]>>;
+    /**
+     * Adds a generation provider from an object. Its `generate` method is called when the generator runs.
+     * @template PInput The input the provider requires. The output of the providers added so far must satisfy it.
+     * @template POutput The output produced by the provider.
+     * @template PConfig The type of the provider-specific configuration.
+     * @param value The object that produces the output of the provider.
+     * @param config The provider-specific configuration that is passed to the provider when it runs.
+     * @returns A new generator whose output type includes the output of the added provider.
+     * @see OpenApiGenerationProvider
+     */
     useValue<PInput extends TOutput, POutput extends OpenApiGeneratorOutput, PConfig extends AnyConfig>(value: OpenApiGenerationProvider<VInput<PInput, TOutput>, POutput, PConfig>, config?: Partial<PConfig>): _OpenApiGenerator<Merge<[TOutput, POutput]>>;
+    /**
+     * Runs all added generation providers in order on already parsed API data.
+     * The output directory and the `outputDir` of each provider that defines one are created, or emptied first if
+     * `clearOutputDir` is enabled. Each provider receives the merged output of the providers that ran before it.
+     * @template T The type of the parsed and transformed API data.
+     * @param data The parsed and transformed API data of the OpenAPI specifications.
+     * @returns The merged output of all providers.
+     */
     generate<T extends ApiData>(data: T): Promise<TOutput>;
+    /**
+     * Parses and transforms the given OpenAPI specification files, then runs the generation providers on the result.
+     * @param fileNames The paths of the specification files. Each argument can be a single path or an array of paths.
+     * @returns The merged output of all providers.
+     */
     parseAndGenerate(...fileNames: (string | string[])[]): Promise<TOutput>;
+    /**
+     * Parses and transforms all OpenAPI specification files in a directory, then runs the generation providers on the
+     * result. Only files with the extensions `.json`, `.yaml` and `.yml` are considered. The directory is scanned
+     * non-recursively unless `options.recursive` is enabled.
+     * @param dir The directory that contains the specification files.
+     * @param options Options for scanning the directory, including an optional filter for the files to consider.
+     * @returns The merged output of all providers.
+     */
     parseAndGenerateFromDir(dir: string, options?: Partial<DirectoryScanOptions>): Promise<TOutput>;
 }
+/**
+ * Generates output from OpenAPI specifications by running a pipeline of generation providers.
+ * Providers are added with `useType`, `useFn` or `useValue` and run in the order they were added. Each provider can
+ * read the output of the providers before it from `ctx.input`.
+ * @example
+ * ```ts
+ * import { OpenApiGenerator } from '@goast/core';
+ * import { TypeScriptModelsGenerator } from '@goast/typescript';
+ *
+ * const generator = new OpenApiGenerator()
+ *   // Add a generator using a class
+ *   .useType(TypeScriptModelsGenerator)
+ *   // Add a generator using a function that can read the output of the previous generator from `ctx.input`
+ *   .useFn((ctx, cfg) => {
+ *     // Do the generation
+ *     return {}; // Return information about the generated files so it can be used by other generators
+ *   });
+ *
+ * // Generate for all OpenAPI specification files in a directory
+ * await generator.parseAndGenerateFromDir('path/to/openapi/specs');
+ * ```
+ */
 export declare class OpenApiGenerator extends _OpenApiGenerator<{}> {
+    /**
+     * Initializes a new instance of the OpenApiGenerator class.
+     * @param config The configuration to use. Options that are not specified fall back to
+     * `defaultOpenApiGeneratorConfig`.
+     */
     constructor(config?: Partial<OpenApiGeneratorConfig>);
 }
+/**
+ * The default configuration of a generation provider. The options of `OpenApiGeneratorConfig` become optional and fall
+ * back to the generator configuration, while the provider-specific options keep their own optionality.
+ * @template T The type of the provider configuration.
+ */
 export type DefaultGenerationProviderConfig<T extends AnyConfig> = Omit<T, keyof OpenApiGeneratorConfig> & Partial<Pick<T, keyof OpenApiGeneratorConfig>>;
+/**
+ * Base class for generation providers. Subclasses implement `buildContext`, which creates a provider-specific context
+ * from the generator context and configuration, and `onGenerate`, which produces the output from that context.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by the provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @template TContext The type of the context that is created by `buildContext` and consumed by `onGenerate`.
+ * @see OpenApiGenerationProvider
+ */
 export declare abstract class OpenApiGenerationProviderBase<TInput extends OpenApiGeneratorInput, TOutput extends OpenApiGeneratorOutput, TConfig extends AnyConfig, TContext extends OpenApiGenerationProviderContext<TInput, TConfig>> implements OpenApiGenerationProvider<TInput, TOutput, TConfig> {
+    /**
+     * Generates the output of this provider by building its context and then calling `onGenerate` with it.
+     * @param context The context of the generator, including the output of the providers that ran before.
+     * @param config The provider-specific configuration, if any.
+     * @returns The output of this provider.
+     */
     generate(context: OpenApiGeneratorContext<TInput>, config?: Partial<TConfig> | undefined): Promise<TOutput>;
     protected getProviderContext(context: OpenApiGeneratorContext<TInput>, config: Partial<TConfig> | undefined, defaultConfig: DefaultGenerationProviderConfig<TConfig>): OpenApiGenerationProviderContext<TInput, TConfig>;
     protected abstract buildContext(context: OpenApiGeneratorContext<TInput>, config?: Partial<TConfig> | undefined): TContext | Promise<TContext>;

package/dist/src/codegen/generator.js

@@ -13,19 +13,67 @@ class _OpenApiGenerator {
         this._config = config;
         this._parser = parser;
     }
+    /**
+     * Adds a generation provider to the pipeline. Providers run in the order they were added.
+     * @template PInput The input the provider requires. The output of the providers added so far must satisfy it.
+     * @template POutput The output produced by the provider.
+     * @template PConfig The type of the provider-specific configuration.
+     * @param provider The provider to add. Its output is deep-merged into the input of the following providers.
+     * @param config The provider-specific configuration that is passed to the provider when it runs.
+     * @returns A new generator whose output type includes the output of the added provider.
+     */
     use(provider, config) {
         this._providers.push({ provider: provider, config });
         return new _OpenApiGenerator(this._config, [...this._providers], this._parser);
     }
+    /**
+     * Adds a generation provider from a class. A new instance of the class is created when the generator runs,
+     * and its `generate` method is called to produce the output.
+     * @template PInput The input the provider requires. The output of the providers added so far must satisfy it.
+     * @template POutput The output produced by the provider.
+     * @template PConfig The type of the provider-specific configuration.
+     * @param type The class of the provider. It must have a constructor without parameters.
+     * @param config The provider-specific configuration that is passed to the provider when it runs.
+     * @returns A new generator whose output type includes the output of the added provider.
+     * @see OpenApiGenerationProvider
+     */
     useType(type, config) {
         return this.use(ActionProvider.fromType(type, 'generate'), config);
     }
+    /**
+     * Adds a generation provider from a function. The function is called when the generator runs.
+     * @template PInput The input the function requires. The output of the providers added so far must satisfy it.
+     * @template POutput The output produced by the function.
+     * @template PConfig The type of the provider-specific configuration.
+     * @param fn The function that produces the output of the provider.
+     * @param config The provider-specific configuration that is passed to the function when it runs.
+     * @returns A new generator whose output type includes the output of the added provider.
+     * @see OpenApiGenerationProviderFn
+     */
     useFn(fn, config) {
         return this.use(ActionProvider.fromFn(fn), config);
     }
+    /**
+     * Adds a generation provider from an object. Its `generate` method is called when the generator runs.
+     * @template PInput The input the provider requires. The output of the providers added so far must satisfy it.
+     * @template POutput The output produced by the provider.
+     * @template PConfig The type of the provider-specific configuration.
+     * @param value The object that produces the output of the provider.
+     * @param config The provider-specific configuration that is passed to the provider when it runs.
+     * @returns A new generator whose output type includes the output of the added provider.
+     * @see OpenApiGenerationProvider
+     */
     useValue(value, config) {
         return this.use(ActionProvider.fromValue(value, 'generate'), config);
     }
+    /**
+     * Runs all added generation providers in order on already parsed API data.
+     * The output directory and the `outputDir` of each provider that defines one are created, or emptied first if
+     * `clearOutputDir` is enabled. Each provider receives the merged output of the providers that ran before it.
+     * @template T The type of the parsed and transformed API data.
+     * @param data The parsed and transformed API data of the OpenAPI specifications.
+     * @returns The merged output of all providers.
+     */
     async generate(data) {
         const absOutputPath = resolve(this._config.outputDir);
         if (this._config.clearOutputDir) {
@@ -59,16 +107,56 @@ class _OpenApiGenerator {
         }
         return input;
     }
+    /**
+     * Parses and transforms the given OpenAPI specification files, then runs the generation providers on the result.
+     * @param fileNames The paths of the specification files. Each argument can be a single path or an array of paths.
+     * @returns The merged output of all providers.
+     */
     async parseAndGenerate(...fileNames) {
         const data = await this._parser.parseApisAndTransform(...fileNames);
         return await this.generate(data);
     }
+    /**
+     * Parses and transforms all OpenAPI specification files in a directory, then runs the generation providers on the
+     * result. Only files with the extensions `.json`, `.yaml` and `.yml` are considered. The directory is scanned
+     * non-recursively unless `options.recursive` is enabled.
+     * @param dir The directory that contains the specification files.
+     * @param options Options for scanning the directory, including an optional filter for the files to consider.
+     * @returns The merged output of all providers.
+     */
     async parseAndGenerateFromDir(dir, options) {
         const filter = (file) => (file.endsWith('.yml') || file.endsWith('.yaml') || file.endsWith('.json')) && (options?.filter?.(file) ?? true);
         return this.parseAndGenerate(...(await getFiles(dir, { ...options, filter })));
     }
 }
+/**
+ * Generates output from OpenAPI specifications by running a pipeline of generation providers.
+ * Providers are added with `useType`, `useFn` or `useValue` and run in the order they were added. Each provider can
+ * read the output of the providers before it from `ctx.input`.
+ * @example
+ * ```ts
+ * import { OpenApiGenerator } from '@goast/core';
+ * import { TypeScriptModelsGenerator } from '@goast/typescript';
+ *
+ * const generator = new OpenApiGenerator()
+ *   // Add a generator using a class
+ *   .useType(TypeScriptModelsGenerator)
+ *   // Add a generator using a function that can read the output of the previous generator from `ctx.input`
+ *   .useFn((ctx, cfg) => {
+ *     // Do the generation
+ *     return {}; // Return information about the generated files so it can be used by other generators
+ *   });
+ *
+ * // Generate for all OpenAPI specification files in a directory
+ * await generator.parseAndGenerateFromDir('path/to/openapi/specs');
+ * ```
+ */
 export class OpenApiGenerator extends _OpenApiGenerator {
+    /**
+     * Initializes a new instance of the OpenApiGenerator class.
+     * @param config The configuration to use. Options that are not specified fall back to
+     * `defaultOpenApiGeneratorConfig`.
+     */
     constructor(config) {
         super({ ...defaultOpenApiGeneratorConfig, ...config }, [], new OpenApiParser({ ...defaultOpenApiGeneratorConfig, ...config }));
     }
@@ -97,7 +185,22 @@ function mergeDeep(target, ...sources) {
     }
     return mergeDeep(target, ...sources);
 }
+/**
+ * Base class for generation providers. Subclasses implement `buildContext`, which creates a provider-specific context
+ * from the generator context and configuration, and `onGenerate`, which produces the output from that context.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by the provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @template TContext The type of the context that is created by `buildContext` and consumed by `onGenerate`.
+ * @see OpenApiGenerationProvider
+ */
 export class OpenApiGenerationProviderBase {
+    /**
+     * Generates the output of this provider by building its context and then calling `onGenerate` with it.
+     * @param context The context of the generator, including the output of the providers that ran before.
+     * @param config The provider-specific configuration, if any.
+     * @returns The output of this provider.
+     */
     async generate(context, config) {
         const ctx = await this.buildContext(context, config);
         return await this.onGenerate(ctx);

package/dist/src/codegen/internal-utils.d.ts

@@ -1 +1,9 @@
+/**
+ * Stores the spec location of a generated result in its `__source__` property when running in test mode.
+ * The location is only recorded if `config.__test__` is set and the result does not have a `__source__` yet, so tests
+ * can trace a generated item back to the schema, endpoint or service it was created from.
+ * @param config The generator configuration. Only the `__test__` flag is read.
+ * @param result The generation result to annotate. It is mutated in place.
+ * @param sourceFn Returns the location to store, usually formatted as `file#path`.
+ */
 export declare function addSourceIfTest(config: any, result: any, sourceFn: () => any): void;

package/dist/src/codegen/internal-utils.js

@@ -1,3 +1,11 @@
+/**
+ * Stores the spec location of a generated result in its `__source__` property when running in test mode.
+ * The location is only recorded if `config.__test__` is set and the result does not have a `__source__` yet, so tests
+ * can trace a generated item back to the schema, endpoint or service it was created from.
+ * @param config The generator configuration. Only the `__test__` flag is read.
+ * @param result The generation result to annotate. It is mutated in place.
+ * @param sourceFn Returns the location to store, usually formatted as `file#path`.
+ */
 export function addSourceIfTest(config, result, sourceFn) {
     if (config.__test__ && !result.__source__) {
         result.__source__ = sourceFn();

package/dist/src/codegen/schemas-generator.d.ts

@@ -2,13 +2,46 @@ import type { ApiSchema } from '../transform/api-types.ts';
 import type { MaybePromise } from '../utils/type.utils.ts';
 import { type DefaultGenerationProviderConfig, OpenApiGenerationProviderBase } from './generator.ts';
 import type { AnyConfig, OpenApiGenerationProviderContext, OpenApiGeneratorContext, OpenApiGeneratorInput, OpenApiGeneratorOutput } from './types.ts';
+/**
+ * The context that is passed to the methods of `OpenApiSchemasGenerationProviderBase`.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by the provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @template TSchemaOutput The type of the result produced for each schema.
+ */
 export type OpenApiSchemasGenerationProviderContext<TInput extends OpenApiGeneratorInput, TOutput extends OpenApiGeneratorOutput, TConfig extends AnyConfig, TSchemaOutput extends OpenApiGeneratorOutput> = OpenApiGenerationProviderContext<TInput, TConfig> & {
+    /**
+     * The results that have been generated so far, keyed by the ID of their schema.
+     */
     existingSchemaResults: Map<string, TSchemaOutput>;
+    /**
+     * The output of the provider. It is created by `initResult` and returned after all schemas have been generated.
+     */
     output: TOutput;
 };
+/**
+ * Base class for generation providers that produce one result per schema.
+ * Results are cached per schema. A schema that is a reference to another schema reuses the result of the referenced
+ * schema. Subclasses implement `initResult`, `generateSchema` and `addSchemaResult`, and can override
+ * `generateAdditionalFiles` to produce output after all schemas have been processed.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by the provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @template TSchemaOutput The type of the result produced for each schema.
+ * @template TContext The type of the context that is passed to the provider methods.
+ * @see OpenApiGenerationProviderBase
+ */
 export declare abstract class OpenApiSchemasGenerationProviderBase<TInput extends OpenApiGeneratorInput, TOutput extends OpenApiGeneratorOutput, TConfig extends AnyConfig, TSchemaOutput extends OpenApiGeneratorOutput, TContext extends OpenApiSchemasGenerationProviderContext<TInput, TOutput, TConfig, TSchemaOutput>> extends OpenApiGenerationProviderBase<TInput, TOutput, TConfig, TContext> {
     protected getProviderContext(context: OpenApiGeneratorContext<TInput>, config: Partial<TConfig> | undefined, defaultConfig: DefaultGenerationProviderConfig<TConfig>): OpenApiSchemasGenerationProviderContext<TInput, TOutput, TConfig, TSchemaOutput>;
     protected onGenerate(ctx: TContext): Promise<TOutput>;
+    /**
+     * Gets the result for a schema. The result is generated on the first call and returned from the cache afterwards.
+     * If the schema is a reference to another schema, the result of the referenced schema is used.
+     * In test mode, the source location of the schema is stored in the result.
+     * @param ctx The context of the provider.
+     * @param schema The schema to get the result for.
+     * @returns The result for the schema.
+     */
     getSchemaResult(ctx: TContext, schema: ApiSchema): Promise<TSchemaOutput>;
     protected getSchemaReference(ctx: TContext, schema: ApiSchema): ApiSchema | undefined;
     protected abstract initResult(ctx: OpenApiGenerationProviderContext<TInput, TConfig>): TOutput;

package/dist/src/codegen/schemas-generator.js

@@ -1,6 +1,18 @@
 import { getSchemaReference } from '../utils/schema.utils.js';
 import { OpenApiGenerationProviderBase } from './generator.js';
 import { addSourceIfTest } from './internal-utils.js';
+/**
+ * Base class for generation providers that produce one result per schema.
+ * Results are cached per schema. A schema that is a reference to another schema reuses the result of the referenced
+ * schema. Subclasses implement `initResult`, `generateSchema` and `addSchemaResult`, and can override
+ * `generateAdditionalFiles` to produce output after all schemas have been processed.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by the provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @template TSchemaOutput The type of the result produced for each schema.
+ * @template TContext The type of the context that is passed to the provider methods.
+ * @see OpenApiGenerationProviderBase
+ */
 export class OpenApiSchemasGenerationProviderBase extends OpenApiGenerationProviderBase {
     getProviderContext(context, config, defaultConfig) {
         const ctx = super.getProviderContext(context, config, defaultConfig);
@@ -16,6 +28,14 @@ export class OpenApiSchemasGenerationProviderBase extends OpenApiGenerationProvi
         await this.generateAdditionalFiles(ctx);
         return ctx.output;
     }
+    /**
+     * Gets the result for a schema. The result is generated on the first call and returned from the cache afterwards.
+     * If the schema is a reference to another schema, the result of the referenced schema is used.
+     * In test mode, the source location of the schema is stored in the result.
+     * @param ctx The context of the provider.
+     * @param schema The schema to get the result for.
+     * @returns The result for the schema.
+     */
     async getSchemaResult(ctx, schema) {
         const existingResult = ctx.existingSchemaResults.get(schema.id);
         if (existingResult)

package/dist/src/codegen/services-generator.d.ts

@@ -2,10 +2,34 @@ import type { ApiService } from '../transform/api-types.ts';
 import type { MaybePromise } from '../utils/type.utils.ts';
 import { type DefaultGenerationProviderConfig, OpenApiGenerationProviderBase } from './generator.ts';
 import type { AnyConfig, OpenApiGenerationProviderContext, OpenApiGeneratorContext, OpenApiGeneratorInput, OpenApiGeneratorOutput } from './types.ts';
+/**
+ * The context that is passed to the methods of `OpenApiServicesGenerationProviderBase`.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by the provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @template TServiceOutput The type of the result produced for each service.
+ */
 export type OpenApiServicesGenerationProviderContext<TInput extends OpenApiGeneratorInput, TOutput extends OpenApiGeneratorOutput, TConfig extends AnyConfig, TServiceOutput extends OpenApiGeneratorOutput> = OpenApiGenerationProviderContext<TInput, TConfig> & {
+    /**
+     * The results that have been generated so far, keyed by the ID of their service.
+     */
     existingServiceResults: Map<string, TServiceOutput>;
+    /**
+     * The output of the provider. It is created by `initResult` and returned after all services have been generated.
+     */
     output: TOutput;
 };
+/**
+ * Base class for generation providers that produce one result per API service.
+ * Results are cached per service. Subclasses implement `initResult`, `generateService` and `addServiceResult`, and can
+ * override `generateAdditionalFiles` to produce output after all services have been processed.
+ * @template TInput The type of the merged output of the providers that ran before.
+ * @template TOutput The type of the output produced by the provider.
+ * @template TConfig The type of the provider-specific configuration.
+ * @template TServiceOutput The type of the result produced for each service.
+ * @template TContext The type of the context that is passed to the provider methods.
+ * @see OpenApiGenerationProviderBase
+ */
 export declare abstract class OpenApiServicesGenerationProviderBase<TInput extends OpenApiGeneratorInput, TOutput extends OpenApiGeneratorOutput, TConfig extends AnyConfig, TServiceOutput extends OpenApiGeneratorOutput, TContext extends OpenApiServicesGenerationProviderContext<TInput, TOutput, TConfig, TServiceOutput>> extends OpenApiGenerationProviderBase<TInput, TOutput, TConfig, TContext> {
     protected getProviderContext(context: OpenApiGeneratorContext<TInput>, config: Partial<TConfig> | undefined, defaultConfig: DefaultGenerationProviderConfig<TConfig>): OpenApiServicesGenerationProviderContext<TInput, TOutput, TConfig, TServiceOutput>;
     protected onGenerate(ctx: TContext): Promise<TOutput>;