@jentic/arazzo-parser 1.0.0-alpha.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@jentic/arazzo-parser",
+  "version": "1.0.0-alpha.0",
+  "description": "Parser for Arazzo Documents producing SpecLynx ApiDOM data model.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "latest"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "unpkg": "./dist/jentic-arazzo-parser.browser.min.js",
+  "main": "./src/index.cjs",
+  "exports": {
+    "types": "./types/arazzo-parser.d.ts",
+    "import": "./src/index.mjs",
+    "require": "./src/index.cjs"
+  },
+  "types": "./types/arazzo-parser.d.ts",
+  "scripts": {
+    "build": "npm run clean && run-p --max-parallel ${CPU_CORES:-2} typescript:declaration build:es build:cjs build:umd:browser",
+    "build:es": "cross-env BABEL_ENV=es babel src --out-dir src --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward'",
+    "build:cjs": "cross-env BABEL_ENV=cjs babel src --out-dir src --extensions '.ts' --out-file-extension '.cjs' --root-mode 'upward'",
+    "build:umd:browser": "cross-env BABEL_ENV=browser webpack --config config/webpack/browser.config.js --progress",
+    "lint": "eslint ./",
+    "lint:fix": "eslint ./ --fix",
+    "clean": "rimraf --glob 'src/**/*.mjs' 'src/**/*.cjs' 'test/**/*.mjs' ./dist ./types",
+    "typescript:check-types": "tsc --noEmit",
+    "typescript:declaration": "tsc -p tsconfig.declaration.json && api-extractor run -l -c ./config/api-extractor/api-extractor.json",
+    "test": "npm run build:es && cross-env BABEL_ENV=es babel test --out-dir test --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward' && cross-env NODE_ENV=test mocha",
+    "prepack": "copyfiles -u 2 ../../LICENSE . && copyfiles -u 2 ../../NOTICE .",
+    "postpack": "rimraf NOTICE LICENSE"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jentic/jentic-arazzo-tools.git"
+  },
+  "author": "Jentic <hello@jentic.com>",
+  "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",
+    "ramda-adjunct": "^6.0.0"
+  },
+  "files": [
+    "src/**/*.mjs",
+    "src/**/*.cjs",
+    "dist/",
+    "types/arazzo-parser.d.ts",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md"
+  ]
+}

package/src/errors/ParseError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomError = require("@speclynx/apidom-error");
+class ParseError extends _apidomError.ApiDOMError {
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+var _default = exports.default = ParseError;

package/src/errors/ParseError.mjs

@@ -0,0 +1,7 @@
+import { ApiDOMError } from '@speclynx/apidom-error';
+class ParseError extends ApiDOMError {
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+export default ParseError;

package/src/index.cjs

@@ -0,0 +1,155 @@
+"use strict";
+
+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.parse = parse;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _apidomParser = _interopRequireWildcard(require("@speclynx/apidom-parser"));
+var jsonParserAdapter = _interopRequireWildcard(require("@speclynx/apidom-parser-adapter-arazzo-json-1"));
+var yamlParserAdapter = _interopRequireWildcard(require("@speclynx/apidom-parser-adapter-arazzo-yaml-1"));
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _arazzoJson = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/arazzo-json-1"));
+var _arazzoYaml = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/arazzo-yaml-1"));
+var _file = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/resolvers/file"));
+var _httpAxios = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/resolvers/http-axios"));
+var _ramdaAdjunct = require("ramda-adjunct");
+var _ParseError = _interopRequireDefault(require("./errors/ParseError.cjs"));
+/**
+ * Options for parsing Arazzo Documents.
+ * @public
+ */
+
+/**
+ * Default options for parsing Arazzo Documents.
+ * @public
+ */
+const defaultParseOptions = exports.defaultParseOptions = {
+  strict: true,
+  sourceMap: false,
+  parserOpts: {},
+  resolverOpts: {}
+};
+const parser = new _apidomParser.default();
+parser.use(jsonParserAdapter);
+parser.use(yamlParserAdapter);
+
+/**
+ * Parses an Arazzo Document from an object.
+ * @param source - The Arazzo Document as a plain object
+ * @param options - Parsing options
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @public
+ */
+
+/**
+ * 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
+ * @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
+ */
+
+/**
+ * Parses an Arazzo Document from a string, object, or URI.
+ *
+ * The function handles three types of input:
+ * 1. Object - directly refracts the object into an Arazzo specification element
+ * 2. String content - attempts to parse as an inline Arazzo Document (JSON or YAML)
+ * 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
+ * @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: \{...\} \});
+ *
+ * @example
+ * // Parse inline JSON
+ * const result = await parse('\{"arazzo": "1.0.1", "info": \{...\}\}');
+ *
+ * @example
+ * // Parse from file
+ * const result = await parse('/path/to/arazzo.json');
+ *
+ * @example
+ * // Parse from URL
+ * const result = await parse('https://example.com/arazzo.yaml');
+ * @public
+ */
+async function parse(source, options = {}) {
+  const mergedOptions = {
+    ...defaultParseOptions,
+    ...options
+  };
+  const {
+    strict,
+    sourceMap,
+    parserOpts,
+    resolverOpts
+  } = mergedOptions;
+
+  // attempt to parse source as plain object
+  if ((0, _ramdaAdjunct.isPlainObject)(source)) {
+    if (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();
+    const element = (0, _apidomNsArazzo.refractArazzoSpecification1)(source);
+    element.classes.push('result');
+    parseResult.push(element);
+    return parseResult;
+  }
+
+  // next try to parse the source assuming it contains Arazzo Document
+  try {
+    return await parser.parse(source, {
+      sourceMap,
+      strict
+    });
+  } catch (error) {
+    if (error instanceof _apidomParser.ParserError && error.message !== 'Source did not match any registered parsers') {
+      throw new _ParseError.default('Failed to parse Arazzo Document', {
+        cause: error
+      });
+    }
+  }
+
+  // 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
+      }
+    });
+  } catch (error) {
+    throw new _ParseError.default('Failed to parse Arazzo Document from URI', {
+      cause: error
+    });
+  }
+}

package/src/index.mjs

@@ -0,0 +1,147 @@
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+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 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';
+import HTTPResolverAxios from '@speclynx/apidom-reference/resolve/resolvers/http-axios';
+import { isPlainObject } from 'ramda-adjunct';
+import ParseError from "./errors/ParseError.mjs";
+/**
+ * Options for parsing Arazzo Documents.
+ * @public
+ */
+/**
+ * Default options for parsing Arazzo Documents.
+ * @public
+ */
+export const defaultParseOptions = {
+  strict: true,
+  sourceMap: false,
+  parserOpts: {},
+  resolverOpts: {}
+};
+const parser = new ApiDOMParser();
+parser.use(jsonParserAdapter);
+parser.use(yamlParserAdapter);
+
+/**
+ * Parses an Arazzo Document from an object.
+ * @param source - The Arazzo Document as a plain object
+ * @param options - Parsing options
+ * @returns A promise that resolves to the parsed Arazzo Document as ApiDOM data model
+ * @public
+ */
+
+/**
+ * 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
+ * @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
+ */
+
+/**
+ * Parses an Arazzo Document from a string, object, or URI.
+ *
+ * The function handles three types of input:
+ * 1. Object - directly refracts the object into an Arazzo specification element
+ * 2. String content - attempts to parse as an inline Arazzo Document (JSON or YAML)
+ * 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
+ * @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: \{...\} \});
+ *
+ * @example
+ * // Parse inline JSON
+ * const result = await parse('\{"arazzo": "1.0.1", "info": \{...\}\}');
+ *
+ * @example
+ * // Parse from file
+ * const result = await parse('/path/to/arazzo.json');
+ *
+ * @example
+ * // Parse from URL
+ * const result = await parse('https://example.com/arazzo.yaml');
+ * @public
+ */
+export async function parse(source, options = {}) {
+  const mergedOptions = {
+    ...defaultParseOptions,
+    ...options
+  };
+  const {
+    strict,
+    sourceMap,
+    parserOpts,
+    resolverOpts
+  } = mergedOptions;
+
+  // attempt to parse source as plain object
+  if (isPlainObject(source)) {
+    if (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();
+    const element = refractArazzoSpecification1(source);
+    element.classes.push('result');
+    parseResult.push(element);
+    return parseResult;
+  }
+
+  // next try to parse the source assuming it contains Arazzo Document
+  try {
+    return await parser.parse(source, {
+      sourceMap,
+      strict
+    });
+  } catch (error) {
+    if (error instanceof ParserError && error.message !== 'Source did not match any registered parsers') {
+      throw new ParseError('Failed to parse Arazzo Document', {
+        cause: error
+      });
+    }
+  }
+
+  // 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
+      }
+    });
+  } catch (error) {
+    throw new ParseError('Failed to parse Arazzo Document from URI', {
+      cause: error
+    });
+  }
+}

package/types/arazzo-parser.d.ts

@@ -0,0 +1,56 @@
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+
+/**
+ * Default options for parsing Arazzo Documents.
+ * @public
+ */
+export declare const defaultParseOptions: Required<ParseOptions>;
+
+/**
+ * Parses an Arazzo Document from an object.
+ * @param source - The Arazzo Document as a plain object
+ * @param options - Parsing options
+ * @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>;
+
+/**
+ * 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
+ * @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>;
+
+/**
+ * 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>;
+}
+
+export { }