@goast/core 0.7.0 → 0.7.1

package/dist/src/parse/parser.d.ts

@@ -1,12 +1,50 @@
 import type { ApiData } from '../transform/api-types.ts';
 import type { OpenApiDocument } from './openapi-types.ts';
 import { type Deref, type OpenApiParserOptions } from './types.ts';
+/**
+ * Loads OpenAPI 2.0, 3.0 and 3.1 documents from files or HTTP(S) URLs, in JSON or YAML, and resolves their `$ref`
+ * references, both local and remote. Dereferenced documents are then transformed into `ApiData`.
+ *
+ * Each document is loaded once per parser instance and cached. Relative file names are resolved against the current
+ * working directory, and relative `$ref` targets are resolved against the file that contains the reference.
+ * @example
+ * ```ts
+ * const parser = new OpenApiParser();
+ * const apiData = await parser.parseApisAndTransform('./petstore.yaml');
+ * ```
+ */
 export declare class OpenApiParser {
     private readonly _loadedDocuments;
     private readonly _config;
+    /**
+     * Creates a parser.
+     * @param config Options that override the defaults in `defaultOpenApiParserOptions`.
+     */
     constructor(config?: Partial<OpenApiParserOptions>);
+    /**
+     * Parses one or more documents and transforms them into a single `ApiData` model. Each argument can be one file name
+     * or URL, or an array of them. Documents are parsed in parallel.
+     * @param fileNames File paths or HTTP(S) URLs, given individually or as arrays.
+     * @returns The API data built from all parsed documents.
+     */
     parseApisAndTransform(...fileNames: (string | string[])[]): Promise<ApiData>;
+    /**
+     * Loads and dereferences a single document without transforming it. Relative paths are resolved against the current
+     * working directory, and HTTP(S) URLs are downloaded.
+     * @param fileName File path or HTTP(S) URL of the document.
+     * @returns The dereferenced document. Its `$ref` references are followed when properties are read.
+     * @example
+     * ```ts
+     * const doc = await parser.parseApi('./petstore.yaml');
+     * const title = doc.info?.title;
+     * ```
+     */
     parseApi(fileName: string): Promise<Deref<OpenApiDocument>>;
+    /**
+     * Collects and transforms documents that were already dereferenced, for example by `parseApi`.
+     * @param apis The dereferenced documents to transform together.
+     * @returns The API data built from all given documents.
+     */
     transformApis(apis: Deref<OpenApiDocument>[]): ApiData;
     private dereference;
     private resolveReference;

package/dist/src/parse/parser.js

@@ -7,23 +7,61 @@ import { isNullish } from '../utils/common.utils.js';
 import { getLineInfo, parseYamlWithInfo } from '../utils/yaml-info.js';
 import { createDerefProxy } from './deref-proxy.js';
 import { defaultOpenApiParserOptions } from './types.js';
+/**
+ * Loads OpenAPI 2.0, 3.0 and 3.1 documents from files or HTTP(S) URLs, in JSON or YAML, and resolves their `$ref`
+ * references, both local and remote. Dereferenced documents are then transformed into `ApiData`.
+ *
+ * Each document is loaded once per parser instance and cached. Relative file names are resolved against the current
+ * working directory, and relative `$ref` targets are resolved against the file that contains the reference.
+ * @example
+ * ```ts
+ * const parser = new OpenApiParser();
+ * const apiData = await parser.parseApisAndTransform('./petstore.yaml');
+ * ```
+ */
 export class OpenApiParser {
     _loadedDocuments = new Map();
     _config;
+    /**
+     * Creates a parser.
+     * @param config Options that override the defaults in `defaultOpenApiParserOptions`.
+     */
     constructor(config) {
         this._config = { ...defaultOpenApiParserOptions, ...config };
     }
+    /**
+     * Parses one or more documents and transforms them into a single `ApiData` model. Each argument can be one file name
+     * or URL, or an array of them. Documents are parsed in parallel.
+     * @param fileNames File paths or HTTP(S) URLs, given individually or as arrays.
+     * @returns The API data built from all parsed documents.
+     */
     async parseApisAndTransform(...fileNames) {
         const flatFileNames = [].concat(...fileNames);
         const apis = await Promise.all(flatFileNames.map((fileName) => this.parseApi(fileName)));
         const transformed = this.transformApis(apis);
         return transformed;
     }
+    /**
+     * Loads and dereferences a single document without transforming it. Relative paths are resolved against the current
+     * working directory, and HTTP(S) URLs are downloaded.
+     * @param fileName File path or HTTP(S) URL of the document.
+     * @returns The dereferenced document. Its `$ref` references are followed when properties are read.
+     * @example
+     * ```ts
+     * const doc = await parser.parseApi('./petstore.yaml');
+     * const title = doc.info?.title;
+     * ```
+     */
     async parseApi(fileName) {
         const absoluteFilePath = this.isUrl(fileName) ? fileName : path.resolve(cwd(), fileName);
         const doc = await this.loadDocument(absoluteFilePath);
         return await this.dereference(absoluteFilePath, [], doc.document);
     }
+    /**
+     * Collects and transforms documents that were already dereferenced, for example by `parseApi`.
+     * @param apis The dereferenced documents to transform together.
+     * @returns The API data built from all given documents.
+     */
     transformApis(apis) {
         const collectedData = collectOpenApi(apis);
         const transformedData = transformOpenApi(collectedData, this._config);

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

@@ -1,13 +1,34 @@
 import { type OpenApiTransformerOptions } from '../transform/types.ts';
 import type { OpenApiDiscriminator, OpenApiDocument, OpenApiReference, OpenApiSchema } from './openapi-types.ts';
+/**
+ * Provenance of a dereferenced object, exposed on every such object as `$src`.
+ * Records the document the raw object was read from and where it sits in that document.
+ * @template T The raw OpenAPI object type that this source describes.
+ */
 export type DerefSource<T> = {
+    /**
+     * Absolute file path, or URL, of the document the object was loaded from.
+     */
     file: string;
+    /**
+     * Line and column of the object within that document.
+     */
     pos: {
         line: number;
         col: number;
     };
+    /**
+     * Slash-separated path from the document root to the object, such as `/components/schemas/Pet`.
+     * Segments are not JSON Pointer-escaped.
+     */
     path: string;
+    /**
+     * The dereferenced root document of the file that contains the object.
+     */
     document: Deref<OpenApiDocument>;
+    /**
+     * The raw, unresolved object as it was parsed, before any `$ref` was followed.
+     */
     originalComponent: T;
 };
 type _DerefDiscriminator = Omit<OpenApiDiscriminator, 'mapping'> & {
@@ -19,8 +40,24 @@ type _Deref<T extends object> = T extends OpenApiDiscriminator ? _DerefDiscrimin
     $src: DerefSource<T>;
     $ref?: Deref<T>;
 };
+/**
+ * Consumer-facing view of the OpenAPI value `T`. Object properties and array elements are mapped recursively, the raw
+ * `$ref` key is replaced by `$ref?: Deref<T>` pointing at the resolved target, and every object gains
+ * `$src: DerefSource<T>`. Properties that a referencing object does not define are read from its target at runtime
+ * (see `createDerefProxy`).
+ * @template T The raw OpenAPI type being dereferenced.
+ * @see DerefSource
+ */
 export type Deref<T> = T extends object ? (T extends (infer A)[] ? Deref<A>[] : _Deref<T>) : T;
+/**
+ * Options that control parsing. The parser accepts the same options as the transformer and passes them on unchanged.
+ * @see OpenApiTransformerOptions
+ */
 export type OpenApiParserOptions = OpenApiTransformerOptions;
+/**
+ * Default parser options, a shallow copy of `defaultOpenApiTransformerOptions`.
+ * @see defaultOpenApiTransformerOptions
+ */
 export declare const defaultOpenApiParserOptions: {
     unknownTypeBehavior: 'keep-unknown' | 'object-if-properties' | 'always-object';
 };

package/dist/src/parse/types.js

@@ -1,2 +1,6 @@
 import { defaultOpenApiTransformerOptions } from '../transform/types.js';
+/**
+ * Default parser options, a shallow copy of `defaultOpenApiTransformerOptions`.
+ * @see defaultOpenApiTransformerOptions
+ */
 export const defaultOpenApiParserOptions = { ...defaultOpenApiTransformerOptions };