@jentic/arazzo-parser 1.0.0-alpha.24 → 1.0.0-alpha.26

package/src/parse-openapi.mjs

@@ -0,0 +1,227 @@
+import { parse as parseURI, mergeOptions } from '@speclynx/apidom-reference/configuration/empty';
+import OpenApiJSON2Parser from '@speclynx/apidom-reference/parse/parsers/openapi-json-2';
+import OpenApiYAML2Parser from '@speclynx/apidom-reference/parse/parsers/openapi-yaml-2';
+import OpenApiJSON3_0Parser from '@speclynx/apidom-reference/parse/parsers/openapi-json-3-0';
+import OpenApiYAML3_0Parser from '@speclynx/apidom-reference/parse/parsers/openapi-yaml-3-0';
+import OpenApiJSON3_1Parser from '@speclynx/apidom-reference/parse/parsers/openapi-json-3-1';
+import OpenApiYAML3_1Parser from '@speclynx/apidom-reference/parse/parsers/openapi-yaml-3-1';
+import { detect as detectOpenApiJSON3_1 } from '@speclynx/apidom-parser-adapter-openapi-json-3-1';
+import { detect as detectOpenApiYAML3_1 } from '@speclynx/apidom-parser-adapter-openapi-yaml-3-1';
+import { detect as detectOpenApiJSON3_0 } from '@speclynx/apidom-parser-adapter-openapi-json-3-0';
+import { detect as detectOpenApiYAML3_0 } from '@speclynx/apidom-parser-adapter-openapi-yaml-3-0';
+import { detect as detectOpenApiJSON2 } from '@speclynx/apidom-parser-adapter-openapi-json-2';
+import { detect as detectOpenApiYAML2 } from '@speclynx/apidom-parser-adapter-openapi-yaml-2';
+import { isPlainObject } from 'ramda-adjunct';
+import ParseError from "./errors/ParseError.mjs";
+import MemoryResolver from "./resolve/resolvers/memory/index.mjs";
+import { defaultOptions as arazzoDefaultOptions } from "./parse-arazzo.mjs";
+/**
+ * Options for parsing OpenAPI Documents.
+ * @public
+ */
+/**
+ * Default reference options for parsing OpenAPI Documents.
+ * @public
+ */
+export const defaultOptions = {
+  parse: {
+    parsers: [new OpenApiJSON2Parser({
+      allowEmpty: false
+    }), new OpenApiYAML2Parser({
+      allowEmpty: false
+    }), new OpenApiJSON3_0Parser({
+      allowEmpty: false
+    }), new OpenApiYAML3_0Parser({
+      allowEmpty: false
+    }), new OpenApiJSON3_1Parser({
+      allowEmpty: false
+    }), new OpenApiYAML3_1Parser({
+      allowEmpty: false
+    })],
+    parserOpts: {
+      ...arazzoDefaultOptions.parse.parserOpts
+    }
+  },
+  resolve: {
+    resolvers: [new MemoryResolver(), ...arazzoDefaultOptions.resolve.resolvers.filter(r => r.name !== 'memory')],
+    resolverOpts: {}
+  }
+};
+
+/**
+ * Parses an OpenAPI Document from an object.
+ * @param source - The OpenAPI Document as a plain object
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed OpenAPI Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+
+/**
+ * Parses an OpenAPI Document from a string or URI.
+ * @param source - The OpenAPI Document as string content, or a file system path / HTTP(S) URL
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed OpenAPI Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+
+/**
+ * Parses an OpenAPI Document from a string, object, or URI.
+ * @param source - The OpenAPI Document as a plain object, string content, or URI
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed OpenAPI Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ * @public
+ */
+
+/**
+ * Parses an OpenAPI Document from a string, object, or URI.
+ *
+ * The function handles three types of input:
+ * 1. Object - converts to JSON string and parses (source maps supported with `strict: false`)
+ * 2. String content - uses OpenAPI detection to identify and parse inline JSON or YAML content
+ * 3. URI string - if not detected as OpenAPI content, treats as file system path or HTTP(S) URL
+ *
+ * @param source - The OpenAPI Document as an object, string content, or a file system path / HTTP(S) URL
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the parsed OpenAPI Document as ApiDOM data model
+ * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
+ *
+ * @example
+ * Parse from object
+ * ```typescript
+ * const result = await parseOpenAPI({ openapi: '3.1.0', info: {...} });
+ * ```
+ *
+ * @example
+ * Parse inline JSON
+ * ```typescript
+ * const result = await parseOpenAPI('{"openapi": "3.1.0", "info": {...}}');
+ * ```
+ *
+ * @example
+ * Parse from file
+ * ```typescript
+ * const result = await parseOpenAPI('/path/to/openapi.json');
+ * ```
+ *
+ * @example
+ * Parse from URL
+ * ```typescript
+ * const result = await parseOpenAPI('https://example.com/openapi.yaml');
+ * ```
+ *
+ * @example
+ * Parse with custom options
+ * ```typescript
+ * const result = await parseOpenAPI('/path/to/openapi.json', customOptions);
+ * ```
+ * @public
+ */
+export async function parse(source, options = {}) {
+  let mergedOptions = mergeOptions(defaultOptions, options);
+  const strict = mergedOptions.parse?.parserOpts?.strict ?? true;
+  let sourceProvenance;
+  if (isPlainObject(source)) {
+    const document = JSON.stringify(source, null, 2);
+    mergedOptions = mergeOptions(mergedOptions, {
+      resolve: {
+        resolverOpts: {
+          document
+        }
+      }
+    });
+    source = 'memory://openapi.json';
+    sourceProvenance = '[object]';
+  } else if (await detectOpenApiJSON2(source, {
+    strict
+  })) {
+    mergedOptions = mergeOptions(mergedOptions, {
+      resolve: {
+        resolverOpts: {
+          document: source
+        }
+      }
+    });
+    source = 'memory://openapi.json';
+    sourceProvenance = '[inline JSON]';
+  } else if (await detectOpenApiYAML2(source, {
+    strict
+  })) {
+    mergedOptions = mergeOptions(mergedOptions, {
+      resolve: {
+        resolverOpts: {
+          document: source
+        }
+      }
+    });
+    source = 'memory://openapi.yaml';
+    sourceProvenance = '[inline YAML]';
+  } else if (await detectOpenApiJSON3_0(source, {
+    strict
+  })) {
+    mergedOptions = mergeOptions(mergedOptions, {
+      resolve: {
+        resolverOpts: {
+          document: source
+        }
+      }
+    });
+    source = 'memory://openapi.json';
+    sourceProvenance = '[inline JSON]';
+  } else if (await detectOpenApiYAML3_0(source, {
+    strict
+  })) {
+    mergedOptions = mergeOptions(mergedOptions, {
+      resolve: {
+        resolverOpts: {
+          document: source
+        }
+      }
+    });
+    source = 'memory://openapi.yaml';
+    sourceProvenance = '[inline YAML]';
+  } else if (await detectOpenApiJSON3_1(source, {
+    strict
+  })) {
+    mergedOptions = mergeOptions(mergedOptions, {
+      resolve: {
+        resolverOpts: {
+          document: source
+        }
+      }
+    });
+    source = 'memory://openapi.json';
+    sourceProvenance = '[inline JSON]';
+  } else if (await detectOpenApiYAML3_1(source, {
+    strict
+  })) {
+    mergedOptions = mergeOptions(mergedOptions, {
+      resolve: {
+        resolverOpts: {
+          document: source
+        }
+      }
+    });
+    source = 'memory://openapi.yaml';
+    sourceProvenance = '[inline YAML]';
+  } else {
+    sourceProvenance = source;
+  }
+
+  // next we assume that source is either file system URI or HTTP(S) URL
+  try {
+    const parseResult = await parseURI(source, mergedOptions);
+
+    // set retrievalURI metadata for file/URL sources (not for inline content)
+    if (!source.startsWith('memory://')) {
+      parseResult.meta.set('retrievalURI', source);
+    }
+    return parseResult;
+  } catch (error) {
+    throw new ParseError(`Failed to parse OpenAPI Document from "${sourceProvenance}"`, {
+      cause: error
+    });
+  }
+}

package/src/resolve/resolvers/memory/index.cjs

@@ -0,0 +1,29 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+/**
+ * @public
+ */
+class MemoryResolver extends _empty.Resolver {
+  constructor() {
+    super({
+      name: 'memory'
+    });
+  }
+  canRead(file) {
+    return file.uri.startsWith('memory://') && this.document !== undefined;
+  }
+  async read(file) {
+    try {
+      const encoder = new TextEncoder();
+      return encoder.encode(this.document);
+    } catch (error) {
+      throw new _empty.ResolverError(`Error opening file "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+var _default = exports.default = MemoryResolver;

package/src/resolve/resolvers/memory/index.mjs

@@ -0,0 +1,25 @@
+import { Resolver, ResolverError } from '@speclynx/apidom-reference/configuration/empty';
+/**
+ * @public
+ */
+class MemoryResolver extends Resolver {
+  constructor() {
+    super({
+      name: 'memory'
+    });
+  }
+  canRead(file) {
+    return file.uri.startsWith('memory://') && this.document !== undefined;
+  }
+  async read(file) {
+    try {
+      const encoder = new TextEncoder();
+      return encoder.encode(this.document);
+    } catch (error) {
+      throw new ResolverError(`Error opening file "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+export default MemoryResolver;

package/types/arazzo-parser.d.ts

@@ -2,29 +2,17 @@ import type { ApiDOMReferenceOptions } from '@speclynx/apidom-reference';
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
 import type { PartialDeep } from 'type-fest';
 
-/**
- * Options for parsing Arazzo Documents.
- * @public
- */
-export declare type ArazzoOptions = PartialDeep<ApiDOMReferenceOptions>;
-
 /**
  * Default reference options for parsing Arazzo Documents.
  * @public
  */
-export declare const defaultArazzoOptions: ArazzoOptions;
+export declare const defaultParseArazzoOptions: ParseArazzoOptions;
 
 /**
  * Default reference options for parsing OpenAPI Documents.
  * @public
  */
-export declare const defaultOpenAPIOptions: OpenAPIOptions;
-
-/**
- * Options for parsing OpenAPI Documents.
- * @public
- */
-export declare type OpenAPIOptions = PartialDeep<ApiDOMReferenceOptions>;
+export declare const defaultParseOpenAPIOptions: ParseOpenAPIOptions;
 
 /**
  * Parses an Arazzo Document from an object.
@@ -34,7 +22,7 @@ export declare type OpenAPIOptions = PartialDeep<ApiDOMReferenceOptions>;
  * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
  * @public
  */
-export declare function parseArazzo(source: Record<string, unknown>, options?: ArazzoOptions): Promise<ParseResultElement>;
+export declare function parseArazzo(source: Record<string, unknown>, options?: ParseArazzoOptions): Promise<ParseResultElement>;
 
 /**
  * Parses an Arazzo Document from a string or URI.
@@ -44,7 +32,7 @@ export declare function parseArazzo(source: Record<string, unknown>, options?: A
  * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
  * @public
  */
-export declare function parseArazzo(source: string, options?: ArazzoOptions): Promise<ParseResultElement>;
+export declare function parseArazzo(source: string, options?: ParseArazzoOptions): Promise<ParseResultElement>;
 
 /**
  * Parses an Arazzo Document from a string, object, or URI.
@@ -54,7 +42,13 @@ export declare function parseArazzo(source: string, options?: ArazzoOptions): Pr
  * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
  * @public
  */
-export declare function parseArazzo(source: string | Record<string, unknown>, options?: ArazzoOptions): Promise<ParseResultElement>;
+export declare function parseArazzo(source: string | Record<string, unknown>, options?: ParseArazzoOptions): Promise<ParseResultElement>;
+
+/**
+ * Options for parsing Arazzo Documents.
+ * @public
+ */
+export declare type ParseArazzoOptions = PartialDeep<ApiDOMReferenceOptions>;
 
 /**
  * Parses an OpenAPI Document from an object.
@@ -64,7 +58,7 @@ export declare function parseArazzo(source: string | Record<string, unknown>, op
  * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
  * @public
  */
-export declare function parseOpenAPI(source: Record<string, unknown>, options?: OpenAPIOptions): Promise<ParseResultElement>;
+export declare function parseOpenAPI(source: Record<string, unknown>, options?: ParseOpenAPIOptions): Promise<ParseResultElement>;
 
 /**
  * Parses an OpenAPI Document from a string or URI.
@@ -74,7 +68,7 @@ export declare function parseOpenAPI(source: Record<string, unknown>, options?:
  * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
  * @public
  */
-export declare function parseOpenAPI(source: string, options?: OpenAPIOptions): Promise<ParseResultElement>;
+export declare function parseOpenAPI(source: string, options?: ParseOpenAPIOptions): Promise<ParseResultElement>;
 
 /**
  * Parses an OpenAPI Document from a string, object, or URI.
@@ -84,7 +78,13 @@ export declare function parseOpenAPI(source: string, options?: OpenAPIOptions):
  * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
  * @public
  */
-export declare function parseOpenAPI(source: string | Record<string, unknown>, options?: OpenAPIOptions): Promise<ParseResultElement>;
+export declare function parseOpenAPI(source: string | Record<string, unknown>, options?: ParseOpenAPIOptions): Promise<ParseResultElement>;
+
+/**
+ * Options for parsing OpenAPI Documents.
+ * @public
+ */
+export declare type ParseOpenAPIOptions = PartialDeep<ApiDOMReferenceOptions>;
 
 export { ParseResultElement }