@jentic/arazzo-parser 1.0.0-alpha.3 → 1.0.0-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jentic/arazzo-parser",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "Parser for Arazzo Documents producing SpecLynx ApiDOM data model.",
   "keywords": [
     "arazzo",
@@ -48,13 +48,13 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-datamodel": "^2.3.0",
-    "@speclynx/apidom-error": "^2.3.0",
-    "@speclynx/apidom-ns-arazzo-1": "^2.3.0",
-    "@speclynx/apidom-parser": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^2.3.0",
-    "@speclynx/apidom-reference": "^2.3.0",
+    "@speclynx/apidom-datamodel": "2.5.1",
+    "@speclynx/apidom-error": "2.5.1",
+    "@speclynx/apidom-ns-arazzo-1": "2.5.1",
+    "@speclynx/apidom-parser": "2.5.1",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "2.5.1",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "2.5.1",
+    "@speclynx/apidom-reference": "2.5.1",
     "ramda-adjunct": "^6.0.0"
   },
   "files": [
@@ -67,5 +67,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "62a5b7c2722bd5e616884f9b6db5c212c459db04"
+  "gitHead": "65bd559465321bc72189e7367e5465b2d91565be"
 }

package/src/index.cjs

@@ -3,7 +3,7 @@
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 exports.__esModule = true;
-exports.defaultParseOptions = void 0;
+exports.defaultOptions = void 0;
 exports.parse = parse;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
@@ -18,19 +18,30 @@ var _httpAxios = _interopRequireDefault(require("@speclynx/apidom-reference/reso
 var _ramdaAdjunct = require("ramda-adjunct");
 var _ParseError = _interopRequireDefault(require("./errors/ParseError.cjs"));
 /**
- * Options for parsing Arazzo Documents.
+ * Default reference options for parsing Arazzo Documents.
  * @public
  */
-
-/**
- * Default options for parsing Arazzo Documents.
- * @public
- */
-const defaultParseOptions = exports.defaultParseOptions = {
-  strict: true,
-  sourceMap: false,
-  parserOpts: {},
-  resolverOpts: {}
+const defaultOptions = exports.defaultOptions = {
+  parse: {
+    parsers: [new _arazzoJson.default({
+      allowEmpty: false,
+      sourceMap: false
+    }), new _arazzoYaml.default({
+      allowEmpty: false,
+      sourceMap: false
+    })],
+    parserOpts: {}
+  },
+  resolve: {
+    resolvers: [new _file.default({
+      fileAllowList: ['*.json', '*.yaml', '*.yml']
+    }), new _httpAxios.default({
+      timeout: 5000,
+      redirects: 5,
+      withCredentials: false
+    })],
+    resolverOpts: {}
+  }
 };
 const parser = new _apidomParser.default();
 parser.use(jsonParserAdapter);
@@ -39,7 +50,7 @@ parser.use(yamlParserAdapter);
 /**
  * Parses an Arazzo Document from an object.
  * @param source - The Arazzo Document as a plain object
- * @param options - Parsing options
+ * @param options - Reference options (uses defaultOptions when not provided)
  * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
  * @public
  */
@@ -47,7 +58,7 @@ parser.use(yamlParserAdapter);
 /**
  * Parses an Arazzo Document from a string or URI.
  * @param source - The Arazzo Document as string content, or a file system path / HTTP(S) URL
- * @param options - Parsing options
+ * @param options - Reference options (uses defaultOptions when not provided)
  * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
  * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
  * @public
@@ -62,42 +73,47 @@ parser.use(yamlParserAdapter);
  * 3. URI string - treats as a file system path or HTTP(S) URL and resolves the document
  *
  * @param source - The Arazzo Document as an object, string content, or a file system path / HTTP(S) URL
- * @param options - Parsing options
+ * @param options - Reference options (uses defaultOptions when not provided)
  * @returns A promise that resolves to the parsed Arazzo 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
- * const result = await parse(\{ arazzo: '1.0.1', info: \{...\} \});
+ * Parse from object
+ * ```typescript
+ * const result = await parse({ arazzo: '1.0.1', info: {...} });
+ * ```
  *
  * @example
- * // Parse inline JSON
- * const result = await parse('\{"arazzo": "1.0.1", "info": \{...\}\}');
+ * Parse inline JSON
+ * ```typescript
+ * const result = await parse('{"arazzo": "1.0.1", "info": {...}}');
+ * ```
  *
  * @example
- * // Parse from file
+ * Parse from file
+ * ```typescript
  * const result = await parse('/path/to/arazzo.json');
+ * ```
  *
  * @example
- * // Parse from URL
+ * Parse from URL
+ * ```typescript
  * const result = await parse('https://example.com/arazzo.yaml');
+ * ```
+ *
+ * @example
+ * Parse with custom options
+ * ```typescript
+ * const result = await parse('/path/to/arazzo.json', customOptions);
+ * ```
  * @public
  */
 async function parse(source, options = {}) {
-  const mergedOptions = {
-    ...defaultParseOptions,
-    ...options
-  };
-  const {
-    strict,
-    sourceMap,
-    parserOpts,
-    resolverOpts
-  } = mergedOptions;
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
 
   // attempt to parse source as plain object
   if ((0, _ramdaAdjunct.isPlainObject)(source)) {
-    if (sourceMap) {
+    if (mergedOptions.parse?.parserOpts?.sourceMap) {
       throw new _ParseError.default('sourceMap option is not supported when parsing from object: source maps cannot be inferred from plain objects');
     }
     const parseResult = new _apidomDatamodel.ParseResultElement();
@@ -110,8 +126,8 @@ async function parse(source, options = {}) {
   // next try to parse the source assuming it contains Arazzo Document
   try {
     return await parser.parse(source, {
-      sourceMap,
-      strict
+      sourceMap: mergedOptions.parse?.parserOpts?.sourceMap,
+      strict: mergedOptions.parse?.parserOpts?.strict
     });
   } catch (error) {
     if (error instanceof _apidomParser.ParserError && error.message !== 'Source did not match any registered parsers') {
@@ -123,32 +139,11 @@ async function parse(source, options = {}) {
 
   // next we assume that source is either file system URI or HTTP(S) URL
   try {
-    return await (0, _empty.parse)(source, {
-      parse: {
-        parsers: [new _arazzoJson.default({
-          allowEmpty: false,
-          sourceMap,
-          strict
-        }), new _arazzoYaml.default({
-          allowEmpty: false,
-          sourceMap,
-          strict
-        })],
-        parserOpts
-      },
-      resolve: {
-        resolvers: [new _file.default({
-          fileAllowList: ['*.json', '*.yaml', '*.yml']
-        }), new _httpAxios.default({
-          timeout: 5000,
-          redirects: 5,
-          withCredentials: false
-        })],
-        resolverOpts
-      }
-    });
+    const parseResult = await (0, _empty.parse)(source, mergedOptions);
+    parseResult.meta.set('retrievalURI', source);
+    return parseResult;
   } catch (error) {
-    throw new _ParseError.default('Failed to parse Arazzo Document from URI', {
+    throw new _ParseError.default(`Failed to parse Arazzo Document from "${source}"`, {
       cause: error
     });
   }

package/src/index.mjs

@@ -3,7 +3,7 @@ import { refractArazzoSpecification1 } from '@speclynx/apidom-ns-arazzo-1';
 import ApiDOMParser, { ParserError } from '@speclynx/apidom-parser';
 import * as jsonParserAdapter from '@speclynx/apidom-parser-adapter-arazzo-json-1';
 import * as yamlParserAdapter from '@speclynx/apidom-parser-adapter-arazzo-yaml-1';
-import { parse as parseURI } from '@speclynx/apidom-reference/configuration/empty';
+import { parse as parseURI, mergeOptions } from '@speclynx/apidom-reference/configuration/empty';
 import ArazzoJSON1Parser from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
 import ArazzoYAML1Parser from '@speclynx/apidom-reference/parse/parsers/arazzo-yaml-1';
 import FileResolver from '@speclynx/apidom-reference/resolve/resolvers/file';
@@ -11,18 +11,30 @@ import HTTPResolverAxios from '@speclynx/apidom-reference/resolve/resolvers/http
 import { isPlainObject } from 'ramda-adjunct';
 import ParseError from "./errors/ParseError.mjs";
 /**
- * Options for parsing Arazzo Documents.
+ * Default reference options for parsing Arazzo Documents.
  * @public
  */
-/**
- * Default options for parsing Arazzo Documents.
- * @public
- */
-export const defaultParseOptions = {
-  strict: true,
-  sourceMap: false,
-  parserOpts: {},
-  resolverOpts: {}
+export const defaultOptions = {
+  parse: {
+    parsers: [new ArazzoJSON1Parser({
+      allowEmpty: false,
+      sourceMap: false
+    }), new ArazzoYAML1Parser({
+      allowEmpty: false,
+      sourceMap: false
+    })],
+    parserOpts: {}
+  },
+  resolve: {
+    resolvers: [new FileResolver({
+      fileAllowList: ['*.json', '*.yaml', '*.yml']
+    }), new HTTPResolverAxios({
+      timeout: 5000,
+      redirects: 5,
+      withCredentials: false
+    })],
+    resolverOpts: {}
+  }
 };
 const parser = new ApiDOMParser();
 parser.use(jsonParserAdapter);
@@ -31,7 +43,7 @@ parser.use(yamlParserAdapter);
 /**
  * Parses an Arazzo Document from an object.
  * @param source - The Arazzo Document as a plain object
- * @param options - Parsing options
+ * @param options - Reference options (uses defaultOptions when not provided)
  * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
  * @public
  */
@@ -39,7 +51,7 @@ parser.use(yamlParserAdapter);
 /**
  * Parses an Arazzo Document from a string or URI.
  * @param source - The Arazzo Document as string content, or a file system path / HTTP(S) URL
- * @param options - Parsing options
+ * @param options - Reference options (uses defaultOptions when not provided)
  * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
  * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
  * @public
@@ -54,42 +66,47 @@ parser.use(yamlParserAdapter);
  * 3. URI string - treats as a file system path or HTTP(S) URL and resolves the document
  *
  * @param source - The Arazzo Document as an object, string content, or a file system path / HTTP(S) URL
- * @param options - Parsing options
+ * @param options - Reference options (uses defaultOptions when not provided)
  * @returns A promise that resolves to the parsed Arazzo 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
- * const result = await parse(\{ arazzo: '1.0.1', info: \{...\} \});
+ * Parse from object
+ * ```typescript
+ * const result = await parse({ arazzo: '1.0.1', info: {...} });
+ * ```
  *
  * @example
- * // Parse inline JSON
- * const result = await parse('\{"arazzo": "1.0.1", "info": \{...\}\}');
+ * Parse inline JSON
+ * ```typescript
+ * const result = await parse('{"arazzo": "1.0.1", "info": {...}}');
+ * ```
  *
  * @example
- * // Parse from file
+ * Parse from file
+ * ```typescript
  * const result = await parse('/path/to/arazzo.json');
+ * ```
  *
  * @example
- * // Parse from URL
+ * Parse from URL
+ * ```typescript
  * const result = await parse('https://example.com/arazzo.yaml');
+ * ```
+ *
+ * @example
+ * Parse with custom options
+ * ```typescript
+ * const result = await parse('/path/to/arazzo.json', customOptions);
+ * ```
  * @public
  */
 export async function parse(source, options = {}) {
-  const mergedOptions = {
-    ...defaultParseOptions,
-    ...options
-  };
-  const {
-    strict,
-    sourceMap,
-    parserOpts,
-    resolverOpts
-  } = mergedOptions;
+  const mergedOptions = mergeOptions(defaultOptions, options);
 
   // attempt to parse source as plain object
   if (isPlainObject(source)) {
-    if (sourceMap) {
+    if (mergedOptions.parse?.parserOpts?.sourceMap) {
       throw new ParseError('sourceMap option is not supported when parsing from object: source maps cannot be inferred from plain objects');
     }
     const parseResult = new ParseResultElement();
@@ -102,8 +119,8 @@ export async function parse(source, options = {}) {
   // next try to parse the source assuming it contains Arazzo Document
   try {
     return await parser.parse(source, {
-      sourceMap,
-      strict
+      sourceMap: mergedOptions.parse?.parserOpts?.sourceMap,
+      strict: mergedOptions.parse?.parserOpts?.strict
     });
   } catch (error) {
     if (error instanceof ParserError && error.message !== 'Source did not match any registered parsers') {
@@ -115,32 +132,11 @@ export async function parse(source, options = {}) {
 
   // next we assume that source is either file system URI or HTTP(S) URL
   try {
-    return await parseURI(source, {
-      parse: {
-        parsers: [new ArazzoJSON1Parser({
-          allowEmpty: false,
-          sourceMap,
-          strict
-        }), new ArazzoYAML1Parser({
-          allowEmpty: false,
-          sourceMap,
-          strict
-        })],
-        parserOpts
-      },
-      resolve: {
-        resolvers: [new FileResolver({
-          fileAllowList: ['*.json', '*.yaml', '*.yml']
-        }), new HTTPResolverAxios({
-          timeout: 5000,
-          redirects: 5,
-          withCredentials: false
-        })],
-        resolverOpts
-      }
-    });
+    const parseResult = await parseURI(source, mergedOptions);
+    parseResult.meta.set('retrievalURI', source);
+    return parseResult;
   } catch (error) {
-    throw new ParseError('Failed to parse Arazzo Document from URI', {
+    throw new ParseError(`Failed to parse Arazzo Document from "${source}"`, {
       cause: error
     });
   }

package/types/arazzo-parser.d.ts

@@ -1,56 +1,35 @@
+import type { ApiDOMReferenceOptions } from '@speclynx/apidom-reference';
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
 
 /**
- * Default options for parsing Arazzo Documents.
+ * Default reference options for parsing Arazzo Documents.
  * @public
  */
-export declare const defaultParseOptions: Required<ParseOptions>;
+export declare const defaultOptions: Options;
+
+declare type Options = PartialDeep<ApiDOMReferenceOptions>;
 
 /**
  * Parses an Arazzo Document from an object.
  * @param source - The Arazzo Document as a plain object
- * @param options - Parsing options
+ * @param options - Reference options (uses defaultOptions when not provided)
  * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
  * @public
  */
-export declare function parse(source: Record<string, unknown>, options?: ParseOptions): Promise<ParseResultElement>;
+export declare function parse(source: Record<string, unknown>, options?: Options): Promise<ParseResultElement>;
 
 /**
  * Parses an Arazzo Document from a string or URI.
  * @param source - The Arazzo Document as string content, or a file system path / HTTP(S) URL
- * @param options - Parsing options
+ * @param options - Reference options (uses defaultOptions when not provided)
  * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
  * @throws ParseError - When parsing fails for any reason. The original error is available via the `cause` property.
  * @public
  */
-export declare function parse(source: string, options?: ParseOptions): Promise<ParseResultElement>;
+export declare function parse(source: string, options?: Options): Promise<ParseResultElement>;
 
-/**
- * Options for parsing Arazzo Documents.
- * @public
- */
-export declare interface ParseOptions {
-    /**
-     * Whether to enforce strict parsing mode.
-     * Strict parsing mode is using native JSON and YAML parsers without source maps and error recovery.
-     * @defaultValue true
-     */
-    readonly strict?: boolean;
-    /**
-     * Whether to include source maps in the parsed result.
-     * @defaultValue false
-     */
-    readonly sourceMap?: boolean;
-    /**
-     * Additional options passed to the underlying parsers.
-     * @defaultValue \{\}
-     */
-    readonly parserOpts?: Record<string, unknown>;
-    /**
-     * Additional options passed to the underlying resolvers.
-     * @defaultValue \{\}
-     */
-    readonly resolverOpts?: Record<string, unknown>;
-}
+declare type PartialDeep<T> = {
+    [P in keyof T]?: T[P] extends object ? PartialDeep<T[P]> : T[P];
+};
 
 export { }