@goast/core 0.7.0 → 0.7.1

package/dist/src/utils/asset-manager.d.ts

@@ -1,8 +1,30 @@
 import { URL } from 'node:url';
+/**
+ * Reads and copies asset files, such as templates, that are shipped with a generator package. The assets base URL can
+ * be a `file:` URL, in which case files are read from the local file system, or an HTTP(S) URL, in which case files
+ * are fetched over the network. Relative paths are resolved against the base URL.
+ */
 export declare class AssetManager {
     private readonly _assetsBaseUrl;
+    /**
+     * Initializes a new instance of the AssetManager class.
+     * @param assetsBaseUrl The base URL of the asset directory. Either a `file:` URL or an HTTP(S) URL.
+     */
     constructor(assetsBaseUrl: URL);
+    /**
+     * Gets the content of an asset file as text. The file is read from disk for `file:` base URLs and fetched for HTTP(S)
+     * base URLs. Rejects if the file cannot be read, or if the HTTP response is not successful.
+     * @param relativePath The path of the asset file, relative to the assets base URL.
+     * @returns The text content of the asset file.
+     */
     getAssetFileContent(relativePath: string): Promise<string>;
+    /**
+     * Copies an asset file into the specified directory under its base name, overwriting any existing file at that path.
+     * @param relativePath The path of the asset file, relative to the assets base URL.
+     * @param destDir The directory to copy the file into.
+     * @param logName The name to show in the log message. Nothing is logged if omitted; an empty string logs the relative
+     * path instead.
+     */
     copyAssetFile(relativePath: string, destDir: string, logName?: string): Promise<void>;
     private fetchAssetFile;
 }

package/dist/src/utils/asset-manager.js

@@ -1,11 +1,26 @@
 import { basename, resolve } from 'node:path';
 import { fileURLToPath, URL } from 'node:url';
 import fs from 'fs-extra';
+/**
+ * Reads and copies asset files, such as templates, that are shipped with a generator package. The assets base URL can
+ * be a `file:` URL, in which case files are read from the local file system, or an HTTP(S) URL, in which case files
+ * are fetched over the network. Relative paths are resolved against the base URL.
+ */
 export class AssetManager {
     _assetsBaseUrl;
+    /**
+     * Initializes a new instance of the AssetManager class.
+     * @param assetsBaseUrl The base URL of the asset directory. Either a `file:` URL or an HTTP(S) URL.
+     */
     constructor(assetsBaseUrl) {
         this._assetsBaseUrl = assetsBaseUrl;
     }
+    /**
+     * Gets the content of an asset file as text. The file is read from disk for `file:` base URLs and fetched for HTTP(S)
+     * base URLs. Rejects if the file cannot be read, or if the HTTP response is not successful.
+     * @param relativePath The path of the asset file, relative to the assets base URL.
+     * @returns The text content of the asset file.
+     */
     async getAssetFileContent(relativePath) {
         if (this._assetsBaseUrl.protocol === 'file:') {
             return await fs.readFile(resolve(fileURLToPath(this._assetsBaseUrl), relativePath), 'utf8');
@@ -14,6 +29,13 @@ export class AssetManager {
             return await this.fetchAssetFile(relativePath);
         }
     }
+    /**
+     * Copies an asset file into the specified directory under its base name, overwriting any existing file at that path.
+     * @param relativePath The path of the asset file, relative to the assets base URL.
+     * @param destDir The directory to copy the file into.
+     * @param logName The name to show in the log message. Nothing is logged if omitted; an empty string logs the relative
+     * path instead.
+     */
     async copyAssetFile(relativePath, destDir, logName) {
         const targetPath = resolve(destDir, basename(relativePath));
         if (logName !== undefined) {

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

@@ -1,7 +1,29 @@
+/**
+ * Groups the specified items by the first class in the classification that they are an instance of. Items that match
+ * none of the classes are collected in the `rest` array.
+ * @template TItem The type of the items to classify.
+ * @template TClassification The record that maps property names to the classes to test against.
+ * @param items The items to classify.
+ * @param classification An object that maps property names to classes. Each key becomes an array in the result.
+ * @returns An object with one array per classification key and a `rest` array for the unclassified items.
+ */
 export declare function classifyArray<TItem, TClassification extends Record<string, abstract new (...args: any[]) => any>>(items: Iterable<TItem>, classification: TClassification): {
     [P in keyof TClassification]: InstanceType<TClassification[P]>[];
 } & {
     rest: Exclude<TItem, InstanceType<TClassification[string]>>[];
 };
+/**
+ * Checks whether the specified item is an instance of the specified class.
+ * @template T The type to check for.
+ * @param item The item to check.
+ * @param type The class to check against.
+ * @returns `true` if the item is an instance of the class; otherwise, `false`.
+ */
 export declare function isInstanceOf<T>(item: unknown, type: abstract new (...args: any[]) => T): item is T;
+/**
+ * Creates a type guard that checks whether an item is an instance of the specified class.
+ * @template T The type to check for.
+ * @param type The class to create the type guard for.
+ * @returns A function that returns `true` if its argument is an instance of the class; otherwise, `false`.
+ */
 export declare function getIsInstanceOf<T>(type: abstract new (...args: any[]) => T): (item: unknown) => item is T;

package/dist/src/utils/class.utils.js

@@ -1,3 +1,12 @@
+/**
+ * Groups the specified items by the first class in the classification that they are an instance of. Items that match
+ * none of the classes are collected in the `rest` array.
+ * @template TItem The type of the items to classify.
+ * @template TClassification The record that maps property names to the classes to test against.
+ * @param items The items to classify.
+ * @param classification An object that maps property names to classes. Each key becomes an array in the result.
+ * @returns An object with one array per classification key and a `rest` array for the unclassified items.
+ */
 export function classifyArray(items, classification) {
     const result = { rest: [] };
     for (const key in classification) {
@@ -19,9 +28,22 @@ export function classifyArray(items, classification) {
     }
     return result;
 }
+/**
+ * Checks whether the specified item is an instance of the specified class.
+ * @template T The type to check for.
+ * @param item The item to check.
+ * @param type The class to check against.
+ * @returns `true` if the item is an instance of the class; otherwise, `false`.
+ */
 export function isInstanceOf(item, type) {
     return item instanceof type;
 }
+/**
+ * Creates a type guard that checks whether an item is an instance of the specified class.
+ * @template T The type to check for.
+ * @param type The class to create the type guard for.
+ * @returns A function that returns `true` if its argument is an instance of the class; otherwise, `false`.
+ */
 export function getIsInstanceOf(type) {
     return (item) => item instanceof type;
 }

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

@@ -1,15 +1,96 @@
 import type { SingleOrMultiple } from './type.utils.ts';
+/**
+ * Checks whether the specified value is `null` or `undefined`.
+ * @param value The value to check.
+ * @returns `true` if the value is `null` or `undefined`; otherwise, `false`.
+ */
 export declare function isNullish(value: unknown): value is null | undefined;
+/**
+ * Checks whether the specified value is neither `null` nor `undefined`. Can be used as a type guard in filters.
+ * @template T The type of the value.
+ * @param value The value to check.
+ * @returns `true` if the value is neither `null` nor `undefined`; otherwise, `false`.
+ */
 export declare function notNullish<T>(value: T): value is NonNullable<T>;
+/**
+ * Concatenates one or more single or multiple values into one. A single argument is returned as-is, while multiple
+ * arguments are combined into a new array in which array arguments are flattened by one level.
+ * @template T The type of the items.
+ * @param values The single or multiple values to concatenate.
+ * @returns The single argument, or a new array containing the items of all arguments.
+ */
 export declare function concatSingleOrMultiple<T>(...values: SingleOrMultiple<T>[]): SingleOrMultiple<T>;
+/**
+ * Checks whether the specified value is a non-null object that implements the iterable protocol. Strings are not
+ * considered iterable by this check, because they are primitive values.
+ * @param value The value to check.
+ * @returns `true` if the value is an iterable object; otherwise, `false`.
+ */
 export declare function isIterable(value: unknown): value is Iterable<unknown>;
+/**
+ * Converts the specified value to an array. Arrays are returned as-is, other iterables are copied into a new array, and
+ * any other value (including a string) is wrapped in a single-item array.
+ * @template T The type of the items.
+ * @param value The value to convert.
+ * @returns An array containing the items of the value.
+ */
 export declare function toArray<T>(value: T | T[] | Iterable<T>): T[];
+/**
+ * Invokes the callback with the specified value if it is neither `null` nor `undefined`, and returns the value.
+ * The callback can change the value in place.
+ * @template T The type of the value.
+ * @param value The value to modify.
+ * @param callback The callback that receives the value if it is not nullish.
+ * @returns The original value.
+ */
 export declare function modify<T>(value: T, callback: (value: NonNullable<T>) => void): T;
+/**
+ * Invokes the callback with the specified value and returns the value. Useful for performing side effects in a chain.
+ * @template T The type of the value.
+ * @param value The value to pass to the callback.
+ * @param callback The callback to invoke with the value.
+ * @returns The original value.
+ */
 export declare function run<T>(value: T, callback: (value: T) => void): T;
+/**
+ * Passes the specified value to the callback and returns the result of the callback.
+ * @template T The type of the input value.
+ * @template U The type of the result.
+ * @param value The value to transform.
+ * @param callback The callback that computes the result from the value.
+ * @returns The result of the callback.
+ */
 export declare function transform<T, U>(value: T, callback: (value: T) => U): U;
 type IterableItem<T> = T extends Iterable<infer U> ? U : never;
+/**
+ * Invokes the callback for each item of the specified iterable that is neither `null` nor `undefined`, and returns the
+ * iterable. Nullish items are skipped.
+ * @template T The type of the iterable.
+ * @param values The iterable whose non-nullish items are passed to the callback.
+ * @param callback The callback that receives each non-nullish item.
+ * @returns The original iterable.
+ */
 export declare function modifyEach<T extends Iterable<unknown>>(values: T, callback: (value: NonNullable<IterableItem<T>>) => void): T;
+/**
+ * Invokes the callback for each item of the specified iterable, including nullish items, and returns the iterable.
+ * @template T The type of the iterable.
+ * @param values The iterable whose items are passed to the callback.
+ * @param callback The callback to invoke for each item.
+ * @returns The original iterable.
+ */
 export declare function runEach<T extends Iterable<unknown>>(values: T, callback: (value: IterableItem<T>) => void): T;
+/**
+ * Maps each item of the specified iterable with the callback and returns the results as a new array.
+ * @template T The type of the input items.
+ * @template U The type of the mapped items.
+ * @param values The iterable whose items are transformed.
+ * @param callback The callback that maps each item to a new value.
+ * @returns A new array containing the mapped items.
+ */
 export declare function transformEach<T, U>(values: Iterable<T>, callback: (value: T) => U): U[];
+/**
+ * Ignores the specified value and returns nothing. Useful for explicitly discarding the result of an expression.
+ * @param _ The value to ignore.
+ */
 export declare function asVoid(_: unknown): void;
 export {};

package/dist/src/utils/common.utils.js

@@ -1,9 +1,27 @@
+/**
+ * Checks whether the specified value is `null` or `undefined`.
+ * @param value The value to check.
+ * @returns `true` if the value is `null` or `undefined`; otherwise, `false`.
+ */
 export function isNullish(value) {
     return value === null || value === undefined;
 }
+/**
+ * Checks whether the specified value is neither `null` nor `undefined`. Can be used as a type guard in filters.
+ * @template T The type of the value.
+ * @param value The value to check.
+ * @returns `true` if the value is neither `null` nor `undefined`; otherwise, `false`.
+ */
 export function notNullish(value) {
     return !isNullish(value);
 }
+/**
+ * Concatenates one or more single or multiple values into one. A single argument is returned as-is, while multiple
+ * arguments are combined into a new array in which array arguments are flattened by one level.
+ * @template T The type of the items.
+ * @param values The single or multiple values to concatenate.
+ * @returns The single argument, or a new array containing the items of all arguments.
+ */
 export function concatSingleOrMultiple(...values) {
     if (values.length === 1) {
         return values[0];
@@ -19,9 +37,22 @@ export function concatSingleOrMultiple(...values) {
     }
     return result;
 }
+/**
+ * Checks whether the specified value is a non-null object that implements the iterable protocol. Strings are not
+ * considered iterable by this check, because they are primitive values.
+ * @param value The value to check.
+ * @returns `true` if the value is an iterable object; otherwise, `false`.
+ */
 export function isIterable(value) {
     return typeof value === 'object' && value !== null && Symbol.iterator in value;
 }
+/**
+ * Converts the specified value to an array. Arrays are returned as-is, other iterables are copied into a new array, and
+ * any other value (including a string) is wrapped in a single-item array.
+ * @template T The type of the items.
+ * @param value The value to convert.
+ * @returns An array containing the items of the value.
+ */
 export function toArray(value) {
     if (Array.isArray(value)) {
         return value;
@@ -31,19 +62,50 @@ export function toArray(value) {
     }
     return [value];
 }
+/**
+ * Invokes the callback with the specified value if it is neither `null` nor `undefined`, and returns the value.
+ * The callback can change the value in place.
+ * @template T The type of the value.
+ * @param value The value to modify.
+ * @param callback The callback that receives the value if it is not nullish.
+ * @returns The original value.
+ */
 export function modify(value, callback) {
     if (notNullish(value)) {
         callback(value);
     }
     return value;
 }
+/**
+ * Invokes the callback with the specified value and returns the value. Useful for performing side effects in a chain.
+ * @template T The type of the value.
+ * @param value The value to pass to the callback.
+ * @param callback The callback to invoke with the value.
+ * @returns The original value.
+ */
 export function run(value, callback) {
     callback(value);
     return value;
 }
+/**
+ * Passes the specified value to the callback and returns the result of the callback.
+ * @template T The type of the input value.
+ * @template U The type of the result.
+ * @param value The value to transform.
+ * @param callback The callback that computes the result from the value.
+ * @returns The result of the callback.
+ */
 export function transform(value, callback) {
     return callback(value);
 }
+/**
+ * Invokes the callback for each item of the specified iterable that is neither `null` nor `undefined`, and returns the
+ * iterable. Nullish items are skipped.
+ * @template T The type of the iterable.
+ * @param values The iterable whose non-nullish items are passed to the callback.
+ * @param callback The callback that receives each non-nullish item.
+ * @returns The original iterable.
+ */
 export function modifyEach(values, callback) {
     for (const value of values) {
         if (notNullish(value)) {
@@ -52,12 +114,27 @@ export function modifyEach(values, callback) {
     }
     return values;
 }
+/**
+ * Invokes the callback for each item of the specified iterable, including nullish items, and returns the iterable.
+ * @template T The type of the iterable.
+ * @param values The iterable whose items are passed to the callback.
+ * @param callback The callback to invoke for each item.
+ * @returns The original iterable.
+ */
 export function runEach(values, callback) {
     for (const value of values) {
         callback(value);
     }
     return values;
 }
+/**
+ * Maps each item of the specified iterable with the callback and returns the results as a new array.
+ * @template T The type of the input items.
+ * @template U The type of the mapped items.
+ * @param values The iterable whose items are transformed.
+ * @param callback The callback that maps each item to a new value.
+ * @returns A new array containing the mapped items.
+ */
 export function transformEach(values, callback) {
     const result = [];
     for (const value of values) {
@@ -65,6 +142,10 @@ export function transformEach(values, callback) {
     }
     return result;
 }
+/**
+ * Ignores the specified value and returns nothing. Useful for explicitly discarding the result of an expression.
+ * @param _ The value to ignore.
+ */
 export function asVoid(_) {
     // Do nothing
 }

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

@@ -1,3 +1,25 @@
+/**
+ * A boolean value, or a function that returns one. If `T` is `never`, the function takes no arguments; otherwise, it
+ * receives a context value of type `T`.
+ * @template T The type of the context value passed to a condition function.
+ * @example
+ * ```ts
+ * const longName: Condition<string> = (name) => name.length > 10;
+ * evalCondition(longName, 'example-name'); // true
+ * ```
+ */
 export type Condition<T = never> = boolean | ([T] extends [never] ? () => boolean : (ctx: T) => boolean);
+/**
+ * Evaluates the specified condition. A function condition is invoked without a context value.
+ * @param condition The boolean value or condition function to evaluate.
+ * @returns The boolean result of the condition.
+ */
 export declare function evalCondition(condition: Condition<never>): boolean;
+/**
+ * Evaluates the specified condition with a context value. A function condition is invoked with the context value.
+ * @template T The type of the context value.
+ * @param condition The boolean value or condition function to evaluate.
+ * @param ctx The context value to pass to a condition function.
+ * @returns The boolean result of the condition.
+ */
 export declare function evalCondition<T>(condition: Condition<T>, ctx: T): boolean;

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

@@ -1,2 +1,14 @@
 import type { ApiEndpoint } from '../transform/api-types.ts';
+/**
+ * Builds a preview of the URL of an endpoint that shows its query parameters as templates. Required query parameters
+ * are written as `name={name}` and optional ones as `[name={name}]`. The path is kept as written in the spec, so path
+ * parameters keep their `{name}` placeholders.
+ * @param endpoint The endpoint to build the URL preview for.
+ * @returns The endpoint path, followed by `?` and the query templates joined with `&` if there are query parameters.
+ * @example
+ * ```ts
+ * // For GET /pets with a required `limit` and an optional `offset` query parameter:
+ * getEndpointUrlPreview(endpoint); // '/pets?limit={limit}&[offset={offset}]'
+ * ```
+ */
 export declare function getEndpointUrlPreview(endpoint: ApiEndpoint): string;

package/dist/src/utils/endpoint.utils.js

@@ -1,3 +1,15 @@
+/**
+ * Builds a preview of the URL of an endpoint that shows its query parameters as templates. Required query parameters
+ * are written as `name={name}` and optional ones as `[name={name}]`. The path is kept as written in the spec, so path
+ * parameters keep their `{name}` placeholders.
+ * @param endpoint The endpoint to build the URL preview for.
+ * @returns The endpoint path, followed by `?` and the query templates joined with `&` if there are query parameters.
+ * @example
+ * ```ts
+ * // For GET /pets with a required `limit` and an optional `offset` query parameter:
+ * getEndpointUrlPreview(endpoint); // '/pets?limit={limit}&[offset={offset}]'
+ * ```
+ */
 export function getEndpointUrlPreview(endpoint) {
     let url = endpoint.path;
     const queryParams = endpoint.parameters.filter((p) => p.target === 'query');

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

@@ -1 +1,7 @@
+/**
+ * Throws an `Error` with the specified message. Useful in expressions that must produce a value, such as the right-hand
+ * side of `??`.
+ * @param message The message of the error to throw.
+ * @returns This function never returns, because it always throws.
+ */
 export declare function throwExp(message: string): never;

package/dist/src/utils/error.utils.js

@@ -1,3 +1,9 @@
+/**
+ * Throws an `Error` with the specified message. Useful in expressions that must produce a value, such as the right-hand
+ * side of `??`.
+ * @param message The message of the error to throw.
+ * @returns This function never returns, because it always throws.
+ */
 export function throwExp(message) {
     throw new Error(message);
 }

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

@@ -9,12 +9,57 @@ type FactoryProvider<T, TArgs extends unknown[]> = {
     kind: 'value';
     factory: T;
 };
+/**
+ * Creates values on demand. A factory is backed by a constructor, a function or a fixed value, which lets callers
+ * supply an alternative implementation, such as a custom generator, without changing the code that uses it.
+ * @template T The type of the created values.
+ * @template TArgs The types of the arguments passed to the constructor or function.
+ * @example
+ * ```ts
+ * const byFn = Factory.fromFn((name: string) => new MyGenerator(name));
+ * const byValue = Factory.fromValue(new MyGenerator('default'));
+ *
+ * const generator = byFn.create('custom'); // A new instance on every call.
+ * const same = byValue.create(); // Always the same instance.
+ * ```
+ */
 export declare class Factory<T, TArgs extends unknown[]> {
     private readonly _provider;
+    /**
+     * Initializes a new instance of the Factory class. Prefer the static `fromType`, `fromFn` and `fromValue` methods.
+     * @param provider The provider that determines how values are created.
+     */
     constructor(provider: FactoryProvider<T, TArgs>);
+    /**
+     * Creates a value. Constructors are invoked with `new` and functions are called with the arguments. Fixed values
+     * are returned as-is, so the same value is returned on every call.
+     * @param args The arguments to pass to the constructor or function. Ignored for fixed values.
+     * @returns The created value.
+     */
     create(...args: TArgs): T;
+    /**
+     * Creates a factory that instantiates the specified class with `new` on every call to `create`.
+     * @template T The type of the created values.
+     * @template TArgs The types of the constructor arguments.
+     * @param type The constructor to invoke.
+     * @returns A new factory that creates values with the constructor.
+     */
     static fromType<T, TArgs extends unknown[]>(type: Constructor<T, TArgs>): Factory<T, TArgs>;
+    /**
+     * Creates a factory that calls the specified function on every call to `create`.
+     * @template T The type of the created values.
+     * @template TArgs The types of the function arguments.
+     * @param fn The function that creates the values.
+     * @returns A new factory that creates values with the function.
+     */
     static fromFn<T, TArgs extends unknown[]>(fn: (...args: TArgs) => T): Factory<T, TArgs>;
+    /**
+     * Creates a factory that always returns the specified value. The value is not copied, so every call to `create`
+     * returns the same value.
+     * @template T The type of the value.
+     * @param value The value to return from `create`.
+     * @returns A new factory that returns the value.
+     */
     static fromValue<T>(value: T): Factory<T, []>;
 }
 export {};

package/dist/src/utils/factory.js

@@ -1,8 +1,32 @@
+/**
+ * Creates values on demand. A factory is backed by a constructor, a function or a fixed value, which lets callers
+ * supply an alternative implementation, such as a custom generator, without changing the code that uses it.
+ * @template T The type of the created values.
+ * @template TArgs The types of the arguments passed to the constructor or function.
+ * @example
+ * ```ts
+ * const byFn = Factory.fromFn((name: string) => new MyGenerator(name));
+ * const byValue = Factory.fromValue(new MyGenerator('default'));
+ *
+ * const generator = byFn.create('custom'); // A new instance on every call.
+ * const same = byValue.create(); // Always the same instance.
+ * ```
+ */
 export class Factory {
     _provider;
+    /**
+     * Initializes a new instance of the Factory class. Prefer the static `fromType`, `fromFn` and `fromValue` methods.
+     * @param provider The provider that determines how values are created.
+     */
     constructor(provider) {
         this._provider = provider;
     }
+    /**
+     * Creates a value. Constructors are invoked with `new` and functions are called with the arguments. Fixed values
+     * are returned as-is, so the same value is returned on every call.
+     * @param args The arguments to pass to the constructor or function. Ignored for fixed values.
+     * @returns The created value.
+     */
     create(...args) {
         switch (this._provider.kind) {
             case 'ctor':
@@ -13,12 +37,33 @@ export class Factory {
                 return this._provider.factory;
         }
     }
+    /**
+     * Creates a factory that instantiates the specified class with `new` on every call to `create`.
+     * @template T The type of the created values.
+     * @template TArgs The types of the constructor arguments.
+     * @param type The constructor to invoke.
+     * @returns A new factory that creates values with the constructor.
+     */
     static fromType(type) {
         return new Factory({ kind: 'ctor', factory: type });
     }
+    /**
+     * Creates a factory that calls the specified function on every call to `create`.
+     * @template T The type of the created values.
+     * @template TArgs The types of the function arguments.
+     * @param fn The function that creates the values.
+     * @returns A new factory that creates values with the function.
+     */
     static fromFn(fn) {
         return new Factory({ kind: 'fn', factory: fn });
     }
+    /**
+     * Creates a factory that always returns the specified value. The value is not copied, so every call to `create`
+     * returns the same value.
+     * @template T The type of the value.
+     * @param value The value to return from `create`.
+     * @returns A new factory that returns the value.
+     */
     static fromValue(value) {
         return new Factory({ kind: 'value', factory: value });
     }

package/dist/src/utils/file-system.utils.d.ts

@@ -1,10 +1,47 @@
 import type { OpenApiGeneratorConfig } from '../codegen/config.ts';
 import type { Nullable } from './type.utils.ts';
+/**
+ * Options for scanning a directory with `getFiles`.
+ * @see getFiles
+ */
 export type DirectoryScanOptions = {
+    /**
+     * Whether to include the files of subdirectories.
+     * @default false
+     */
     recursive: boolean;
+    /**
+     * The maximum number of subdirectory levels to scan when `recursive` is `true`. `null` or `0` prevents subdirectories
+     * from being entered.
+     * @default 5
+     */
     maxDepth: Nullable<number>;
+    /**
+     * A predicate that receives the name of each file (without its directory) and returns whether to include it.
+     * All files are included if omitted.
+     */
     filter?: (file: string) => boolean;
 };
+/**
+ * Default options for `getFiles`. Subdirectories are not scanned, and a maximum depth of 5 applies once `recursive` is
+ * enabled.
+ */
 export declare const defaultDirectoryScanOptions: DirectoryScanOptions;
+/**
+ * Gets the absolute paths of the files in the specified directory. Subdirectories are only scanned if `recursive` is
+ * enabled. Symbolic links are not followed; a link is returned like a regular file.
+ * @param dir The directory to scan.
+ * @param options The scan options. Merged with `defaultDirectoryScanOptions`, so omitted options use their defaults.
+ * @returns A promise that resolves to the absolute paths of the matching files.
+ */
 export declare function getFiles(dir: string, options?: Partial<DirectoryScanOptions>): Promise<string[]>;
+/**
+ * Writes generated content to the specified file, creating missing parent directories. If the file already exists, the
+ * `existingFileBehavior` of the configuration decides what happens.
+ * @param config The generator configuration. Its `existingFileBehavior` applies when the file already exists:
+ * `'override'` overwrites it, `'error'` throws, `'skip'` leaves it unchanged, and `'count'` writes to the next free
+ * path such as `file_1.ts`.
+ * @param filePath The path of the file to write.
+ * @param content The content to write.
+ */
 export declare function writeGeneratedFile(config: OpenApiGeneratorConfig, filePath: string, content: string): void;

package/dist/src/utils/file-system.utils.js

@@ -1,9 +1,20 @@
 import { basename, dirname, join, resolve } from 'node:path';
 import fs from 'fs-extra';
+/**
+ * Default options for `getFiles`. Subdirectories are not scanned, and a maximum depth of 5 applies once `recursive` is
+ * enabled.
+ */
 export const defaultDirectoryScanOptions = {
     recursive: false,
     maxDepth: 5,
 };
+/**
+ * Gets the absolute paths of the files in the specified directory. Subdirectories are only scanned if `recursive` is
+ * enabled. Symbolic links are not followed; a link is returned like a regular file.
+ * @param dir The directory to scan.
+ * @param options The scan options. Merged with `defaultDirectoryScanOptions`, so omitted options use their defaults.
+ * @returns A promise that resolves to the absolute paths of the matching files.
+ */
 export async function getFiles(dir, options) {
     const opts = { ...defaultDirectoryScanOptions, ...options };
     const files = [];
@@ -56,6 +67,15 @@ function getCountedFilePath(filePath) {
     }
     return candidate;
 }
+/**
+ * Writes generated content to the specified file, creating missing parent directories. If the file already exists, the
+ * `existingFileBehavior` of the configuration decides what happens.
+ * @param config The generator configuration. Its `existingFileBehavior` applies when the file already exists:
+ * `'override'` overwrites it, `'error'` throws, `'skip'` leaves it unchanged, and `'count'` writes to the next free
+ * path such as `file_1.ts`.
+ * @param filePath The path of the file to write.
+ * @param content The content to write.
+ */
 export function writeGeneratedFile(config, filePath, content) {
     let targetPath = filePath;
     if (config.existingFileBehavior !== 'override' && fs.existsSync(filePath)) {