@goast/core 0.7.0 → 0.7.1

package/dist/src/transform/helpers.d.ts

@@ -8,6 +8,15 @@ export declare function asTypeArray(type: string | string[] | undefined | null):
 export declare function withoutNullType(types: (string | null)[]): string[];
 /** Whether the `type` keyword declares `null`, either as a scalar type or as a member of a 3.1 type array. */
 export declare function hasNullType(type: string | string[] | undefined | null): boolean;
+/**
+ * Determines the `ApiSchemaKind` of a schema from its keywords. `oneOf` is checked first, then `allOf`/`anyOf`
+ * (unless the schema is typed `object`), then type arrays, then the scalar `type`. A schema with `allOf`/`anyOf`
+ * is `object` if it also declares properties and `combined` otherwise.
+ * @template T The schema-like object type that provides the keywords the kind is derived from.
+ * @param ctx The transformer context, whose `unknownTypeBehavior` decides schemas without a recognised type.
+ * @param schema The schema to classify.
+ * @returns The kind of the schema.
+ */
 export declare function determineSchemaKind<T extends {
     oneOf?: unknown;
     allOf?: unknown;
@@ -16,6 +25,13 @@ export declare function determineSchemaKind<T extends {
     properties?: Record<string, unknown>;
     additionalProperties?: unknown;
 }>(ctx: OpenApiTransformerContext, schema: T): ApiSchemaKind;
+/**
+ * Derives the name of a schema. A `title` takes precedence. Otherwise the name comes from the schema's place in the
+ * document: its component or `definitions` key, a parameter, response or request body, or its parent property.
+ * @param schema The schema with its `$src` location and optional `title`.
+ * @param id The generated identifier, used as the name when nothing better can be derived.
+ * @returns The name, and whether it was generated rather than taken from the document.
+ */
 export declare function determineSchemaName(schema: {
     title?: string;
     $src: DerefSource<unknown>;
@@ -23,10 +39,22 @@ export declare function determineSchemaName(schema: {
     name: string;
     isGenerated: boolean;
 };
+/**
+ * Maps the `readOnly` and `writeOnly` flags of a schema to its accessibility. Setting both flags yields `none`.
+ * @param schema The schema whose flags are read.
+ * @returns The accessibility of the schema.
+ */
 export declare function determineSchemaAccessibility(schema: {
     readOnly?: boolean;
     writeOnly?: boolean;
 }): ApiSchemaAccessibility;
+/**
+ * Narrows an accessibility that is already known by the flags of another schema, such as one reached through `allOf`.
+ * A flag that contradicts the current accessibility yields `none`, and `all` takes the flags of the schema.
+ * @param accessibility The accessibility determined so far.
+ * @param schema The schema whose flags are merged in.
+ * @returns The combined accessibility.
+ */
 export declare function updateSchemaAccessibility(accessibility: ApiSchemaAccessibility, schema: {
     readOnly?: boolean;
     writeOnly?: boolean;
@@ -34,7 +62,20 @@ export declare function updateSchemaAccessibility(accessibility: ApiSchemaAccess
 type CustomFields<T extends Record<string, unknown>> = {
     [K in keyof T as K extends `x-${string}` ? K : never]: T[K];
 };
+/**
+ * Collects the `x-` extension fields of an OpenAPI object. The prefix is removed from each key, so `x-foo`
+ * becomes `foo`.
+ * @template T The type of the OpenAPI object.
+ * @param schema The OpenAPI object to read the extensions from.
+ * @returns The extensions, keyed by their name without the `x-` prefix.
+ */
 export declare function getCustomFields<T extends Record<string, unknown>>(schema: T): CustomFields<T>;
+/**
+ * Determines the name of an endpoint. The `operationId` is used if present. Otherwise the name is built from the method
+ * and the path, with `{param}` turned into `:param` and slashes into underscores, such as `get_pets_:id`.
+ * @param endpointInfo The method, path and operation of the endpoint.
+ * @returns The name of the endpoint.
+ */
 export declare function determineEndpointName(endpointInfo: {
     method: string;
     path: string;
@@ -42,16 +83,48 @@ export declare function determineEndpointName(endpointInfo: {
         operationId?: string;
     };
 }): string;
+/**
+ * Transforms the `additionalProperties` keyword. A boolean is returned as written and a schema is transformed.
+ * @template TAdditionalProperties The raw type of the `additionalProperties` keyword.
+ * @param context The transformer context.
+ * @param schema The schema that may declare `additionalProperties`.
+ * @param transformSchema The function that transforms a schema object.
+ * @returns `undefined` if the keyword is absent, the boolean as written, or the transformed schema.
+ */
 export declare function transformAdditionalProperties<TAdditionalProperties>(context: OpenApiTransformerContext, schema: {
     additionalProperties?: TAdditionalProperties;
 }, transformSchema: (context: OpenApiTransformerContext, schema: Exclude<TAdditionalProperties, undefined | boolean>) => ApiSchema): boolean | ApiSchema | undefined;
+/**
+ * Transforms the `properties` of a schema into a map keyed by property name. Keys starting with `$` or `x-`
+ * are skipped.
+ * @template TProperties The raw type of a property schema.
+ * @param context The transformer context.
+ * @param schema The schema that may declare `properties`.
+ * @param transformSchema The function that transforms a property schema.
+ * @returns The transformed properties, or an empty map if the schema declares none.
+ */
 export declare function transformSchemaProperties<TProperties>(context: OpenApiTransformerContext, schema: {
     properties?: Record<string, TProperties>;
     required?: string[];
 }, transformSchema: (context: OpenApiTransformerContext, schema: TProperties) => ApiSchema): Map<string, ApiSchemaProperty>;
+/**
+ * Generates identifiers of the form `<name>-<n>`. The counter is kept per name, so identifiers are unique within one
+ * transform run.
+ */
 export declare class IdGenerator {
     private readonly _idMap;
+    /**
+     * Generates the next identifier for the given name.
+     * @param name The prefix of the identifier, such as `schema` or `endpoint`.
+     * @returns The next identifier, such as `schema-1` and then `schema-2`.
+     */
     generateId(name: string): string;
 }
+/**
+ * Builds the key that identifies an OpenAPI object by its source file and JSON path. The transformer uses it to reuse
+ * the entries it has already created for the same object.
+ * @param obj The OpenAPI object to identify.
+ * @returns The key, in the form `file#path`.
+ */
 export declare function getOpenApiObjectIdentifier(obj: Deref<OpenApiObject<string>>): string;
 export {};

package/dist/src/transform/helpers.js

@@ -21,6 +21,15 @@ export function withoutNullType(types) {
 export function hasNullType(type) {
     return asTypeArray(type).some(isNullType);
 }
+/**
+ * Determines the `ApiSchemaKind` of a schema from its keywords. `oneOf` is checked first, then `allOf`/`anyOf`
+ * (unless the schema is typed `object`), then type arrays, then the scalar `type`. A schema with `allOf`/`anyOf`
+ * is `object` if it also declares properties and `combined` otherwise.
+ * @template T The schema-like object type that provides the keywords the kind is derived from.
+ * @param ctx The transformer context, whose `unknownTypeBehavior` decides schemas without a recognised type.
+ * @param schema The schema to classify.
+ * @returns The kind of the schema.
+ */
 export function determineSchemaKind(ctx, schema) {
     // An OpenAPI 3.1 type array that reduces to at most one non-null type is normalised away by
     // `transformSchema`, which replaces `type` with the narrowed scalar (or `'null'`) and then asks this
@@ -58,6 +67,13 @@ export function determineSchemaKind(ctx, schema) {
             Object.keys(schema.properties).length > 0);
     return treadAsObject ? 'object' : 'unknown';
 }
+/**
+ * Derives the name of a schema. A `title` takes precedence. Otherwise the name comes from the schema's place in the
+ * document: its component or `definitions` key, a parameter, response or request body, or its parent property.
+ * @param schema The schema with its `$src` location and optional `title`.
+ * @param id The generated identifier, used as the name when nothing better can be derived.
+ * @returns The name, and whether it was generated rather than taken from the document.
+ */
 export function determineSchemaName(schema, id) {
     if (schema.title)
         return { name: schema.title, isGenerated: false };
@@ -119,6 +135,11 @@ export function determineSchemaName(schema, id) {
     }
     return { name: id, isGenerated: true };
 }
+/**
+ * Maps the `readOnly` and `writeOnly` flags of a schema to its accessibility. Setting both flags yields `none`.
+ * @param schema The schema whose flags are read.
+ * @returns The accessibility of the schema.
+ */
 export function determineSchemaAccessibility(schema) {
     if (schema.readOnly === true) {
         return schema.writeOnly === true ? 'none' : 'readOnly';
@@ -127,6 +148,13 @@ export function determineSchemaAccessibility(schema) {
         return schema.writeOnly === true ? 'writeOnly' : 'all';
     }
 }
+/**
+ * Narrows an accessibility that is already known by the flags of another schema, such as one reached through `allOf`.
+ * A flag that contradicts the current accessibility yields `none`, and `all` takes the flags of the schema.
+ * @param accessibility The accessibility determined so far.
+ * @param schema The schema whose flags are merged in.
+ * @returns The combined accessibility.
+ */
 export function updateSchemaAccessibility(accessibility, schema) {
     if (accessibility === 'none')
         return 'none';
@@ -136,6 +164,13 @@ export function updateSchemaAccessibility(accessibility, schema) {
         return schema.readOnly === true ? 'none' : 'writeOnly';
     return determineSchemaAccessibility(schema);
 }
+/**
+ * Collects the `x-` extension fields of an OpenAPI object. The prefix is removed from each key, so `x-foo`
+ * becomes `foo`.
+ * @template T The type of the OpenAPI object.
+ * @param schema The OpenAPI object to read the extensions from.
+ * @returns The extensions, keyed by their name without the `x-` prefix.
+ */
 export function getCustomFields(schema) {
     const result = {};
     for (const key in schema) {
@@ -146,11 +181,25 @@ export function getCustomFields(schema) {
     }
     return result;
 }
+/**
+ * Determines the name of an endpoint. The `operationId` is used if present. Otherwise the name is built from the method
+ * and the path, with `{param}` turned into `:param` and slashes into underscores, such as `get_pets_:id`.
+ * @param endpointInfo The method, path and operation of the endpoint.
+ * @returns The name of the endpoint.
+ */
 export function determineEndpointName(endpointInfo) {
     if (endpointInfo.operation.operationId)
         return endpointInfo.operation.operationId;
     return endpointInfo.method + endpointInfo.path.replace(/\{([^}]+)\}/g, ':$1').replace(/\//g, '_');
 }
+/**
+ * Transforms the `additionalProperties` keyword. A boolean is returned as written and a schema is transformed.
+ * @template TAdditionalProperties The raw type of the `additionalProperties` keyword.
+ * @param context The transformer context.
+ * @param schema The schema that may declare `additionalProperties`.
+ * @param transformSchema The function that transforms a schema object.
+ * @returns `undefined` if the keyword is absent, the boolean as written, or the transformed schema.
+ */
 export function transformAdditionalProperties(context, schema, transformSchema) {
     if (isNullish(schema.additionalProperties))
         return undefined;
@@ -158,6 +207,15 @@ export function transformAdditionalProperties(context, schema, transformSchema)
         return schema.additionalProperties;
     return transformSchema(context, schema.additionalProperties);
 }
+/**
+ * Transforms the `properties` of a schema into a map keyed by property name. Keys starting with `$` or `x-`
+ * are skipped.
+ * @template TProperties The raw type of a property schema.
+ * @param context The transformer context.
+ * @param schema The schema that may declare `properties`.
+ * @param transformSchema The function that transforms a property schema.
+ * @returns The transformed properties, or an empty map if the schema declares none.
+ */
 export function transformSchemaProperties(context, schema, transformSchema) {
     const result = new Map();
     if (!schema.properties)
@@ -172,14 +230,29 @@ export function transformSchemaProperties(context, schema, transformSchema) {
     }
     return result;
 }
+/**
+ * Generates identifiers of the form `<name>-<n>`. The counter is kept per name, so identifiers are unique within one
+ * transform run.
+ */
 export class IdGenerator {
     _idMap = new Map();
+    /**
+     * Generates the next identifier for the given name.
+     * @param name The prefix of the identifier, such as `schema` or `endpoint`.
+     * @returns The next identifier, such as `schema-1` and then `schema-2`.
+     */
     generateId(name) {
         const id = this._idMap.get(name) ?? 1;
         this._idMap.set(name, id + 1);
         return `${name}-${id}`;
     }
 }
+/**
+ * Builds the key that identifies an OpenAPI object by its source file and JSON path. The transformer uses it to reuse
+ * the entries it has already created for the same object.
+ * @param obj The OpenAPI object to identify.
+ * @returns The key, in the form `file#path`.
+ */
 export function getOpenApiObjectIdentifier(obj) {
     return obj.$src.file + '#' + obj.$src.path;
 }

package/dist/src/transform/transform-document.d.ts

@@ -1,4 +1,11 @@
 import type { OpenApiDocument } from '../parse/openapi-types.ts';
 import type { Deref } from '../parse/types.ts';
 import type { OpenApiTransformerContext } from './types.ts';
+/**
+ * Transforms the top-level `tags` of an OpenAPI document into services. Each tag becomes a service named after it,
+ * keeping the tag's `description`. Operations are attached to these services later, by tag name, in
+ * `transformEndpoint`.
+ * @param context The transformer context that collects the services.
+ * @param document The document whose tags are transformed.
+ */
 export declare function transformDocument(context: OpenApiTransformerContext, document: Deref<OpenApiDocument>): void;

package/dist/src/transform/transform-document.js

@@ -1,4 +1,11 @@
 import { getOpenApiObjectIdentifier } from './helpers.js';
+/**
+ * Transforms the top-level `tags` of an OpenAPI document into services. Each tag becomes a service named after it,
+ * keeping the tag's `description`. Operations are attached to these services later, by tag name, in
+ * `transformEndpoint`.
+ * @param context The transformer context that collects the services.
+ * @param document The document whose tags are transformed.
+ */
 export function transformDocument(context, document) {
     for (const tag of document.tags ?? []) {
         transformTag(context, tag);

package/dist/src/transform/transform-endpoint.d.ts

@@ -1,4 +1,12 @@
 import type { OpenApiCollectorEndpointInfo } from '../collect/types.ts';
 import type { ApiEndpoint } from './api-types.ts';
 import type { OpenApiTransformerContext } from './types.ts';
+/**
+ * Transforms one operation into an `ApiEndpoint` and registers it with its path and with the service of each of its
+ * tags. Operations without tags go to a service with a generated name. Tags that no document declares create implicit
+ * services, which have no `$src`.
+ * @param context The transformer context.
+ * @param endpointInfo The collected path, method, path item and operation.
+ * @returns The transformed endpoint.
+ */
 export declare function transformEndpoint(context: OpenApiTransformerContext, endpointInfo: OpenApiCollectorEndpointInfo): ApiEndpoint;

package/dist/src/transform/transform-endpoint.js

@@ -1,6 +1,14 @@
 import { isOpenApiObjectProperty } from '../internal-utils.js';
 import { determineEndpointName, getCustomFields, getOpenApiObjectIdentifier } from './helpers.js';
 import { transformSchema } from './transform-schema.js';
+/**
+ * Transforms one operation into an `ApiEndpoint` and registers it with its path and with the service of each of its
+ * tags. Operations without tags go to a service with a generated name. Tags that no document declares create implicit
+ * services, which have no `$src`.
+ * @param context The transformer context.
+ * @param endpointInfo The collected path, method, path item and operation.
+ * @returns The transformed endpoint.
+ */
 export function transformEndpoint(context, endpointInfo) {
     const apiPath = transformApiPath(context, endpointInfo.path, endpointInfo.pathItem);
     const endpoint = {

package/dist/src/transform/transform-schema.d.ts

@@ -2,4 +2,14 @@ import type { OpenApiSchema } from '../parse/openapi-types.ts';
 import type { Deref } from '../parse/types.ts';
 import type { ApiSchema } from './api-types.ts';
 import type { OpenApiTransformerContext } from './types.ts';
+/**
+ * Transforms an OpenAPI schema into an `ApiSchema`, together with every schema it references through `$ref`, `items`,
+ * `properties`, `allOf` and the other keywords. Each source schema is transformed once and then reused. A type array
+ * that narrows to one non-null type is normalized to that type, and its `null` member sets `nullable` instead.
+ * @template T The type of the source schema object.
+ * @param ctx The transformer context.
+ * @param schema The schema to transform.
+ * @returns The transformed schema.
+ * @throws Error if no schema is given.
+ */
 export declare function transformSchema<T extends Deref<OpenApiSchema>>(ctx: OpenApiTransformerContext, schema: T): ApiSchema;

package/dist/src/transform/transform-schema.js

@@ -1,5 +1,15 @@
 import { createOverwriteProxy } from '../utils/object.utils.js';
 import { asTypeArray, determineSchemaAccessibility, determineSchemaKind, determineSchemaName, getCustomFields, getOpenApiObjectIdentifier, hasNullType, transformAdditionalProperties, transformSchemaProperties, withoutNullType, } from './helpers.js';
+/**
+ * Transforms an OpenAPI schema into an `ApiSchema`, together with every schema it references through `$ref`, `items`,
+ * `properties`, `allOf` and the other keywords. Each source schema is transformed once and then reused. A type array
+ * that narrows to one non-null type is normalized to that type, and its `null` member sets `nullable` instead.
+ * @template T The type of the source schema object.
+ * @param ctx The transformer context.
+ * @param schema The schema to transform.
+ * @returns The transformed schema.
+ * @throws Error if no schema is given.
+ */
 export function transformSchema(ctx, schema) {
     if (!schema) {
         throw new Error('Schema is required.');

package/dist/src/transform/transformer.d.ts

@@ -1,4 +1,11 @@
 import type { OpenApiCollectorData } from '../collect/types.ts';
 import type { ApiData } from './api-types.ts';
 import { type OpenApiTransformerOptions } from './types.ts';
+/**
+ * Transforms collected OpenAPI documents into the normalized `ApiData` model that the generators consume.
+ * Documents are processed first, so their tags become services, then all collected schemas, then all endpoints.
+ * @param data The documents, schemas and endpoints gathered by the collector.
+ * @param options Transformer options. Values that are not given fall back to the defaults.
+ * @returns The transformed documents, services, endpoints and schemas.
+ */
 export declare function transformOpenApi(data: OpenApiCollectorData, options?: Partial<OpenApiTransformerOptions>): ApiData;

package/dist/src/transform/transformer.js

@@ -3,6 +3,13 @@ import { transformDocument } from './transform-document.js';
 import { transformEndpoint } from './transform-endpoint.js';
 import { transformSchema } from './transform-schema.js';
 import { defaultOpenApiTransformerOptions, } from './types.js';
+/**
+ * Transforms collected OpenAPI documents into the normalized `ApiData` model that the generators consume.
+ * Documents are processed first, so their tags become services, then all collected schemas, then all endpoints.
+ * @param data The documents, schemas and endpoints gathered by the collector.
+ * @param options Transformer options. Values that are not given fall back to the defaults.
+ * @returns The transformed documents, services, endpoints and schemas.
+ */
 export function transformOpenApi(data, options) {
     const context = {
         config: { ...defaultOpenApiTransformerOptions, ...options },

package/dist/src/transform/types.d.ts

@@ -2,6 +2,10 @@ import type { OpenApiCollectorData } from '../collect/types.ts';
 import type { ArrayItem } from '../utils/type.utils.ts';
 import type { ApiContent, ApiData, ApiHeader, ApiParameter, ApiPath, ApiRequestBody, ApiResponse, ApiSchema, ApiSchemaExtensions, ApiSchemaKind, ApiService } from './api-types.ts';
 import type { IdGenerator } from './helpers.ts';
+/**
+ * Options that control how OpenAPI documents are transformed into the `ApiData` model.
+ * @see transformOpenApi
+ */
 export type OpenApiTransformerOptions = {
     /**
      * Determines how schemas without a `type` property should be treated.
@@ -12,22 +16,79 @@ export type OpenApiTransformerOptions = {
      */
     unknownTypeBehavior: 'keep-unknown' | 'object-if-properties' | 'always-object';
 };
+/**
+ * The default transformer options, used for every option that the caller does not set.
+ * @see OpenApiTransformerOptions
+ */
 export declare const defaultOpenApiTransformerOptions: OpenApiTransformerOptions;
+/**
+ * A schema whose kind-specific fields are not filled in yet. It is registered while the schema's own sub-schemas are
+ * being transformed, so that circular references resolve to the same instance.
+ * @see ApiSchema
+ */
 export type IncompleteApiSchema = Omit<ApiSchema, Exclude<keyof ApiSchemaExtensions<ApiSchemaKind>, 'kind'>>;
+/**
+ * The mutable state that all transform steps of one `transformOpenApi` call share.
+ * @see transformOpenApi
+ */
 export type OpenApiTransformerContext = {
+    /**
+     * The transformer options in effect for this run.
+     */
     config: OpenApiTransformerOptions;
+    /**
+     * Generates the identifiers of the entries created during this run.
+     */
     idGenerator: IdGenerator;
+    /**
+     * The collected documents, schemas and endpoints that are being transformed.
+     */
     input: OpenApiCollectorData;
+    /**
+     * Schemas that are currently being transformed, keyed by `file:path`. A circular reference finds its entry here
+     * instead of recursing forever.
+     */
     incompleteSchemas: Map<string, IncompleteApiSchema>;
+    /**
+     * The path entries created so far, keyed by path template. All operations of one path share one entry.
+     */
     paths: Map<string, ApiPath>;
+    /**
+     * Entries already created for each source object, keyed by `getOpenApiObjectIdentifier`, so that every object is
+     * transformed only once.
+     */
     transformed: {
+        /**
+         * The services created from tags, keyed by source object identifier.
+         */
         services: Map<string, ApiService>;
+        /**
+         * The path entries created from path items, keyed by source object identifier.
+         */
         paths: Map<string, ApiPath>;
+        /**
+         * The parameters, keyed by source object identifier.
+         */
         parameters: Map<string, ApiParameter>;
+        /**
+         * The request bodies, keyed by source object identifier.
+         */
         requestBodies: Map<string, ApiRequestBody>;
+        /**
+         * The responses, keyed by source object identifier.
+         */
         responses: Map<string, ApiResponse>;
+        /**
+         * The media type entries, keyed by source object identifier.
+         */
         content: Map<string, ApiContent>;
+        /**
+         * The headers, keyed by source object identifier.
+         */
         headers: Map<string, ApiHeader>;
+        /**
+         * The schemas, keyed by source object identifier.
+         */
         schemas: Map<string, ApiSchema>;
     };
 } & {

package/dist/src/transform/types.js

@@ -1,3 +1,7 @@
+/**
+ * The default transformer options, used for every option that the caller does not set.
+ * @see OpenApiTransformerOptions
+ */
 export const defaultOpenApiTransformerOptions = {
     unknownTypeBehavior: 'object-if-properties',
 };

package/dist/src/utils/action-provider.d.ts

@@ -17,12 +17,50 @@ type ValueActionRunner<T, TAction> = {
     functionName: MatchingFunctionNames<T, TAction>;
 };
 type ActionRunner<TAction> = CtorActionRunner<any, TAction> | FnActionRunner<TAction> | ValueActionRunner<any, TAction>;
+/**
+ * Provides an action that can be run later. The action is either a method of a class that is instantiated for each run,
+ * a plain function, or a method of an object that is shared across runs.
+ * @template TAction The signature of the action.
+ */
 export declare class ActionProvider<TAction extends (...args: any[]) => any> {
     private readonly _runner;
+    /**
+     * Initializes a new instance of the ActionProvider class. Prefer the static `fromType`, `fromFn` and `fromValue`
+     * methods.
+     * @param runner The runner that determines how the action is invoked.
+     */
     constructor(runner: ActionRunner<TAction>);
+    /**
+     * Runs the action with the specified arguments. For class-based providers, a new instance is created on each run.
+     * @param args The arguments to pass to the action.
+     * @returns The result of the action.
+     */
     run(...args: Parameters<TAction>): ReturnType<TAction>;
+    /**
+     * Creates an action provider that calls a method on a new instance of the specified class each time it runs.
+     * @template T The type of the class instance.
+     * @template TName The name of the method to call.
+     * @param type The class to instantiate. Its constructor must not require arguments.
+     * @param functionName The name of the method to call on the instance.
+     * @returns A new action provider.
+     */
     static fromType<T, TName extends FunctionNames<T>>(type: EmptyConstructor<T>, functionName: TName): ActionProvider<T[TName] extends (...args: any[]) => any ? T[TName] : never>;
+    /**
+     * Creates an action provider that calls the specified function each time it runs.
+     * @template TAction The signature of the function.
+     * @param fn The function to call.
+     * @returns A new action provider.
+     */
     static fromFn<TAction extends (...args: any[]) => any>(fn: TAction): ActionProvider<TAction>;
+    /**
+     * Creates an action provider that calls a method on the specified object each time it runs. The object is shared
+     * across runs.
+     * @template T The type of the object.
+     * @template TName The name of the method to call.
+     * @param value The object that contains the method.
+     * @param functionName The name of the method to call on the object.
+     * @returns A new action provider.
+     */
     static fromValue<T, TName extends FunctionNames<T>>(value: T, functionName: TName): ActionProvider<T[TName] extends (...args: any[]) => any ? T[TName] : never>;
 }
 export {};

package/dist/src/utils/action-provider.js

@@ -1,8 +1,23 @@
+/**
+ * Provides an action that can be run later. The action is either a method of a class that is instantiated for each run,
+ * a plain function, or a method of an object that is shared across runs.
+ * @template TAction The signature of the action.
+ */
 export class ActionProvider {
     _runner;
+    /**
+     * Initializes a new instance of the ActionProvider class. Prefer the static `fromType`, `fromFn` and `fromValue`
+     * methods.
+     * @param runner The runner that determines how the action is invoked.
+     */
     constructor(runner) {
         this._runner = runner;
     }
+    /**
+     * Runs the action with the specified arguments. For class-based providers, a new instance is created on each run.
+     * @param args The arguments to pass to the action.
+     * @returns The result of the action.
+     */
     run(...args) {
         switch (this._runner.kind) {
             case 'ctor':
@@ -13,12 +28,35 @@ export class ActionProvider {
                 return this._runner.value[this._runner.functionName](...args);
         }
     }
+    /**
+     * Creates an action provider that calls a method on a new instance of the specified class each time it runs.
+     * @template T The type of the class instance.
+     * @template TName The name of the method to call.
+     * @param type The class to instantiate. Its constructor must not require arguments.
+     * @param functionName The name of the method to call on the instance.
+     * @returns A new action provider.
+     */
     static fromType(type, functionName) {
         return new ActionProvider({ kind: 'ctor', factory: type, functionName: functionName });
     }
+    /**
+     * Creates an action provider that calls the specified function each time it runs.
+     * @template TAction The signature of the function.
+     * @param fn The function to call.
+     * @returns A new action provider.
+     */
     static fromFn(fn) {
         return new ActionProvider({ kind: 'fn', action: fn });
     }
+    /**
+     * Creates an action provider that calls a method on the specified object each time it runs. The object is shared
+     * across runs.
+     * @template T The type of the object.
+     * @template TName The name of the method to call.
+     * @param value The object that contains the method.
+     * @param functionName The name of the method to call on the object.
+     * @returns A new action provider.
+     */
     static fromValue(value, functionName) {
         return new ActionProvider({ kind: 'value', value, functionName: functionName });
     }

package/dist/src/utils/api-data.utils.d.ts

@@ -1,2 +1,11 @@
 import type { ApiComponent, ApiData } from '../transform/api-types.ts';
+/**
+ * Gets a display name for the source location of a component in the form `<relative file path>#<source path>`. The
+ * file path is relative to the common base path of all documents in `data`, which is computed on first use and cached
+ * on `data`.
+ * @template T The OpenAPI type of the component.
+ * @param data The API data that contains the documents of the component.
+ * @param component The component to get the display name for.
+ * @returns The display name of the component's source location.
+ */
 export declare function getSourceDisplayName<T>(data: ApiData, component: ApiComponent<T>): string;

package/dist/src/utils/api-data.utils.js

@@ -1,6 +1,15 @@
 import { dirname, relative } from 'node:path';
 import process from 'node:process';
 const DOCUMENTS_BASE_PATH = Symbol('documentsBasePath');
+/**
+ * Gets a display name for the source location of a component in the form `<relative file path>#<source path>`. The
+ * file path is relative to the common base path of all documents in `data`, which is computed on first use and cached
+ * on `data`.
+ * @template T The OpenAPI type of the component.
+ * @param data The API data that contains the documents of the component.
+ * @param component The component to get the display name for.
+ * @returns The display name of the component's source location.
+ */
 export function getSourceDisplayName(data, component) {
     let basePath = data[DOCUMENTS_BASE_PATH];
     if (basePath === undefined) {

package/dist/src/utils/array.utils.d.ts

@@ -1 +1,8 @@
+/**
+ * Removes all items that match a predicate from an array. The array is modified in place.
+ * @template T The type of the items.
+ * @param array The array to remove items from.
+ * @param predicate The function that returns `true` for items to remove. It is called once per item, from the last item
+ * to the first.
+ */
 export declare function removeItems<T>(array: T[], predicate: (item: T) => boolean): void;

package/dist/src/utils/array.utils.js

@@ -1,3 +1,10 @@
+/**
+ * Removes all items that match a predicate from an array. The array is modified in place.
+ * @template T The type of the items.
+ * @param array The array to remove items from.
+ * @param predicate The function that returns `true` for items to remove. It is called once per item, from the last item
+ * to the first.
+ */
 export function removeItems(array, predicate) {
     for (let i = array.length - 1; i >= 0; i--) {
         if (predicate(array[i])) {