@usearazzo/resolver 1.0.1-alpha.2

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@usearazzo/resolver",
+  "version": "1.0.1-alpha.2",
+  "description": "Resolver for Arazzo Documents.",
+  "keywords": [
+    "arazzo",
+    "arazzo-specification",
+    "resolver",
+    "resolve",
+    "dereference",
+    "workflow",
+    "workflows"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": false,
+    "tag": "latest"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "unpkg": "./dist/arazzo-resolver.browser.min.js",
+  "main": "./src/index.cjs",
+  "exports": {
+    "types": "./types/resolver.d.ts",
+    "import": "./src/index.mjs",
+    "require": "./src/index.cjs"
+  },
+  "types": "./types/resolver.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/usearazzo/arazzo-toolkit.git"
+  },
+  "author": "Vladimir Gorej <vladimir.gorej@gmail.com>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@babel/runtime-corejs3": "^8.0.5",
+    "@speclynx/apidom-datamodel": "^5.2.5",
+    "@speclynx/apidom-error": "^5.2.5",
+    "@speclynx/apidom-ns-arazzo-1": "^5.2.5",
+    "@speclynx/apidom-ns-openapi-2": "^5.2.5",
+    "@speclynx/apidom-ns-openapi-3-0": "^5.2.5",
+    "@speclynx/apidom-ns-openapi-3-1": "^5.2.5",
+    "@speclynx/apidom-reference": "^5.2.5",
+    "@usearazzo/parser": "1.0.1-alpha.2",
+    "type-fest": "^5.4.4"
+  },
+  "devDependencies": {
+    "@speclynx/apidom-core": "^5.2.5"
+  },
+  "files": [
+    "src/**/*.mjs",
+    "src/**/*.cjs",
+    "dist/",
+    "types/resolver.d.ts",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md"
+  ]
+}

package/src/bundle/arazzo.cjs

@@ -0,0 +1,92 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.bundle = bundle;
+exports.defaultOptions = void 0;
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _arazzo = _interopRequireDefault(require("@speclynx/apidom-reference/bundle/strategies/arazzo-1"));
+var _openapi = _interopRequireDefault(require("@speclynx/apidom-reference/bundle/strategies/openapi-2"));
+var _openapi2 = _interopRequireDefault(require("@speclynx/apidom-reference/bundle/strategies/openapi-3-0"));
+var _openapi3 = _interopRequireDefault(require("@speclynx/apidom-reference/bundle/strategies/openapi-3-1"));
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _arazzo2 = require("../dereference/arazzo.cjs");
+var _BundleError = _interopRequireDefault(require("../errors/BundleError.cjs"));
+/**
+ * Options for bundling Arazzo Documents.
+ * @public
+ */
+
+/**
+ * Default reference options for bundling Arazzo Documents.
+ *
+ * Bundling reads only the bundle strategies plus the resolvers and parsers that fetch
+ * external documents, so no resolve or dereference strategies are configured.
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {
+  resolve: {
+    resolvers: [..._arazzo2.defaultOptions.resolve.resolvers]
+  },
+  parse: {
+    parsers: [..._arazzo2.defaultOptions.parse.parsers],
+    parserOpts: {
+      ..._arazzo2.defaultOptions.parse.parserOpts
+    }
+  },
+  bundle: {
+    strategies: [new _arazzo.default(), new _openapi.default(), new _openapi2.default(), new _openapi3.default()]
+  }
+};
+
+/**
+ * Bundles an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function embeds every external JSON Schema resource reached through
+ * JSON References ($ref) into the Components Object of the Arazzo Document,
+ * producing a single compound document.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the Arazzo Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the bundled Arazzo Document as ApiDOM element
+ * @throws BundleError - When bundling fails or document is not an Arazzo specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Bundle from file
+ * const result = await bundleArazzo('/path/to/arazzo.json');
+ *
+ * @example
+ * // Bundle from URL
+ * const result = await bundleArazzo('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * // Bundle with custom options
+ * const result = await bundleArazzo('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+async function bundle(uri, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+
+  // a relative file system path resolves against the current working directory; the string
+  // doubles as the base URI for relative references, where a relative base resolves against
+  // the filesystem root instead of the document. A leading slash or backslash (UNC,
+  // drive-rooted) is already rooted and passes through untouched. `uri` itself is left as
+  // is so error messages below quote what the caller passed in.
+  const retrievalURI = !_empty.url.isHttpUrl(uri) && _empty.url.getProtocol(uri) !== 'file' && !/^[\\/]/.test(uri) ? _empty.url.resolve(_empty.url.fromFileSystemPath(_empty.url.cwd()), uri) : uri;
+  try {
+    const parseResult = await (0, _empty.bundle)(retrievalURI, mergedOptions);
+
+    // validate that the bundled document is an Arazzo specification
+    if (!(0, _apidomNsArazzo.isArazzoSpecification1Element)(parseResult.api)) {
+      throw new _empty.UnmatchedBundleStrategyError(`Could not find a bundle strategy that can bundle "${uri}" as an Arazzo specification`);
+    }
+    parseResult.meta.set('retrievalURI', retrievalURI);
+    return parseResult;
+  } catch (error) {
+    throw new _BundleError.default(`Failed to bundle Arazzo Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}

package/src/bundle/arazzo.mjs

@@ -0,0 +1,83 @@
+import { url, bundle as bundleURI, mergeOptions, UnmatchedBundleStrategyError } from '@speclynx/apidom-reference/configuration/empty';
+import Arazzo1BundleStrategy from '@speclynx/apidom-reference/bundle/strategies/arazzo-1';
+import OpenAPI2BundleStrategy from '@speclynx/apidom-reference/bundle/strategies/openapi-2';
+import OpenAPI30BundleStrategy from '@speclynx/apidom-reference/bundle/strategies/openapi-3-0';
+import OpenAPI31BundleStrategy from '@speclynx/apidom-reference/bundle/strategies/openapi-3-1';
+import { isArazzoSpecification1Element } from '@speclynx/apidom-ns-arazzo-1';
+import { defaultOptions as dereferenceDefaultOptions } from "../dereference/arazzo.mjs";
+import BundleError from "../errors/BundleError.mjs";
+/**
+ * Options for bundling Arazzo Documents.
+ * @public
+ */
+/**
+ * Default reference options for bundling Arazzo Documents.
+ *
+ * Bundling reads only the bundle strategies plus the resolvers and parsers that fetch
+ * external documents, so no resolve or dereference strategies are configured.
+ * @public
+ */
+export const defaultOptions = {
+  resolve: {
+    resolvers: [...dereferenceDefaultOptions.resolve.resolvers]
+  },
+  parse: {
+    parsers: [...dereferenceDefaultOptions.parse.parsers],
+    parserOpts: {
+      ...dereferenceDefaultOptions.parse.parserOpts
+    }
+  },
+  bundle: {
+    strategies: [new Arazzo1BundleStrategy(), new OpenAPI2BundleStrategy(), new OpenAPI30BundleStrategy(), new OpenAPI31BundleStrategy()]
+  }
+};
+
+/**
+ * Bundles an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function embeds every external JSON Schema resource reached through
+ * JSON References ($ref) into the Components Object of the Arazzo Document,
+ * producing a single compound document.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the Arazzo Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the bundled Arazzo Document as ApiDOM element
+ * @throws BundleError - When bundling fails or document is not an Arazzo specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Bundle from file
+ * const result = await bundleArazzo('/path/to/arazzo.json');
+ *
+ * @example
+ * // Bundle from URL
+ * const result = await bundleArazzo('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * // Bundle with custom options
+ * const result = await bundleArazzo('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+export async function bundle(uri, options = {}) {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+
+  // a relative file system path resolves against the current working directory; the string
+  // doubles as the base URI for relative references, where a relative base resolves against
+  // the filesystem root instead of the document. A leading slash or backslash (UNC,
+  // drive-rooted) is already rooted and passes through untouched. `uri` itself is left as
+  // is so error messages below quote what the caller passed in.
+  const retrievalURI = !url.isHttpUrl(uri) && url.getProtocol(uri) !== 'file' && !/^[\\/]/.test(uri) ? url.resolve(url.fromFileSystemPath(url.cwd()), uri) : uri;
+  try {
+    const parseResult = await bundleURI(retrievalURI, mergedOptions);
+
+    // validate that the bundled document is an Arazzo specification
+    if (!isArazzoSpecification1Element(parseResult.api)) {
+      throw new UnmatchedBundleStrategyError(`Could not find a bundle strategy that can bundle "${uri}" as an Arazzo specification`);
+    }
+    parseResult.meta.set('retrievalURI', retrievalURI);
+    return parseResult;
+  } catch (error) {
+    throw new BundleError(`Failed to bundle Arazzo Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}

package/src/bundle/openapi.cjs

@@ -0,0 +1,101 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.bundle = bundle;
+exports.defaultOptions = void 0;
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _openapi = _interopRequireDefault(require("@speclynx/apidom-reference/bundle/strategies/openapi-2"));
+var _openapi2 = _interopRequireDefault(require("@speclynx/apidom-reference/bundle/strategies/openapi-3-0"));
+var _openapi3 = _interopRequireDefault(require("@speclynx/apidom-reference/bundle/strategies/openapi-3-1"));
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
+var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
+var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
+var _openapi4 = require("../dereference/openapi.cjs");
+var _BundleError = _interopRequireDefault(require("../errors/BundleError.cjs"));
+/**
+ * Options for bundling OpenAPI Documents.
+ * @public
+ */
+
+/**
+ * Default reference options for bundling OpenAPI Documents.
+ *
+ * Bundling reads only the bundle strategies plus the resolvers and parsers that fetch
+ * external documents, so no resolve or dereference strategies are configured.
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {
+  resolve: {
+    resolvers: [..._openapi4.defaultOptions.resolve.resolvers]
+  },
+  parse: {
+    parsers: [..._openapi4.defaultOptions.parse.parsers],
+    parserOpts: {
+      ..._openapi4.defaultOptions.parse.parserOpts
+    }
+  },
+  bundle: {
+    strategies: [new _openapi.default(), new _openapi2.default(), new _openapi3.default()]
+  }
+};
+
+/**
+ * Bundles an OpenAPI Document from a file system path or HTTP(S) URL.
+ *
+ * This function hoists every external document reached through JSON References ($ref)
+ * into the components of the OpenAPI Document, producing a single compound document.
+ *
+ * Supports OpenAPI 2.0 (Swagger), OpenAPI 3.0.x, and OpenAPI 3.1.x.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the OpenAPI Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the bundled OpenAPI Document as ApiDOM element
+ * @throws BundleError - When bundling fails or document is not an OpenAPI specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Bundle from file
+ * const result = await bundleOpenAPI('/path/to/openapi.json');
+ *
+ * @example
+ * // Bundle from URL
+ * const result = await bundleOpenAPI('https://example.com/openapi.yaml');
+ *
+ * @example
+ * // Bundle with custom options
+ * const result = await bundleOpenAPI('/path/to/openapi.json', customReferenceOptions);
+ * @public
+ */
+async function bundle(uri, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+
+  // a relative file system path resolves against the current working directory; the string
+  // doubles as the base URI for relative references, where a relative base resolves against
+  // the filesystem root instead of the document. A leading slash or backslash (UNC,
+  // drive-rooted) is already rooted and passes through untouched. `uri` itself is left as
+  // is so error messages below quote what the caller passed in.
+  const retrievalURI = !_empty.url.isHttpUrl(uri) && _empty.url.getProtocol(uri) !== 'file' && !/^[\\/]/.test(uri) ? _empty.url.resolve(_empty.url.fromFileSystemPath(_empty.url.cwd()), uri) : uri;
+  try {
+    const parseResult = await (0, _empty.bundle)(retrievalURI, mergedOptions);
+
+    // validate that the bundled document is an OpenAPI specification
+    if (!isOpenApiElement(parseResult.api)) {
+      throw new _empty.UnmatchedBundleStrategyError(`Could not find a bundle strategy that can bundle "${uri}" as an OpenAPI specification`);
+    }
+    parseResult.meta.set('retrievalURI', retrievalURI);
+    return parseResult;
+  } catch (error) {
+    throw new _BundleError.default(`Failed to bundle OpenAPI Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Checks if the element is a valid OpenAPI specification element.
+ */
+function isOpenApiElement(element) {
+  return (0, _apidomNsOpenapi.isSwaggerElement)(element) || (0, _apidomNsOpenapi2.isOpenApi3_0Element)(element) || (0, _apidomNsOpenapi3.isOpenApi3_1Element)(element);
+}

package/src/bundle/openapi.mjs

@@ -0,0 +1,92 @@
+import { url, bundle as bundleURI, mergeOptions, UnmatchedBundleStrategyError } from '@speclynx/apidom-reference/configuration/empty';
+import OpenAPI2BundleStrategy from '@speclynx/apidom-reference/bundle/strategies/openapi-2';
+import OpenAPI3_0BundleStrategy from '@speclynx/apidom-reference/bundle/strategies/openapi-3-0';
+import OpenAPI3_1BundleStrategy from '@speclynx/apidom-reference/bundle/strategies/openapi-3-1';
+import { isSwaggerElement } from '@speclynx/apidom-ns-openapi-2';
+import { isOpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';
+import { isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
+import { defaultOptions as dereferenceDefaultOptions } from "../dereference/openapi.mjs";
+import BundleError from "../errors/BundleError.mjs";
+/**
+ * Options for bundling OpenAPI Documents.
+ * @public
+ */
+/**
+ * Default reference options for bundling OpenAPI Documents.
+ *
+ * Bundling reads only the bundle strategies plus the resolvers and parsers that fetch
+ * external documents, so no resolve or dereference strategies are configured.
+ * @public
+ */
+export const defaultOptions = {
+  resolve: {
+    resolvers: [...dereferenceDefaultOptions.resolve.resolvers]
+  },
+  parse: {
+    parsers: [...dereferenceDefaultOptions.parse.parsers],
+    parserOpts: {
+      ...dereferenceDefaultOptions.parse.parserOpts
+    }
+  },
+  bundle: {
+    strategies: [new OpenAPI2BundleStrategy(), new OpenAPI3_0BundleStrategy(), new OpenAPI3_1BundleStrategy()]
+  }
+};
+
+/**
+ * Bundles an OpenAPI Document from a file system path or HTTP(S) URL.
+ *
+ * This function hoists every external document reached through JSON References ($ref)
+ * into the components of the OpenAPI Document, producing a single compound document.
+ *
+ * Supports OpenAPI 2.0 (Swagger), OpenAPI 3.0.x, and OpenAPI 3.1.x.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the OpenAPI Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the bundled OpenAPI Document as ApiDOM element
+ * @throws BundleError - When bundling fails or document is not an OpenAPI specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Bundle from file
+ * const result = await bundleOpenAPI('/path/to/openapi.json');
+ *
+ * @example
+ * // Bundle from URL
+ * const result = await bundleOpenAPI('https://example.com/openapi.yaml');
+ *
+ * @example
+ * // Bundle with custom options
+ * const result = await bundleOpenAPI('/path/to/openapi.json', customReferenceOptions);
+ * @public
+ */
+export async function bundle(uri, options = {}) {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+
+  // a relative file system path resolves against the current working directory; the string
+  // doubles as the base URI for relative references, where a relative base resolves against
+  // the filesystem root instead of the document. A leading slash or backslash (UNC,
+  // drive-rooted) is already rooted and passes through untouched. `uri` itself is left as
+  // is so error messages below quote what the caller passed in.
+  const retrievalURI = !url.isHttpUrl(uri) && url.getProtocol(uri) !== 'file' && !/^[\\/]/.test(uri) ? url.resolve(url.fromFileSystemPath(url.cwd()), uri) : uri;
+  try {
+    const parseResult = await bundleURI(retrievalURI, mergedOptions);
+
+    // validate that the bundled document is an OpenAPI specification
+    if (!isOpenApiElement(parseResult.api)) {
+      throw new UnmatchedBundleStrategyError(`Could not find a bundle strategy that can bundle "${uri}" as an OpenAPI specification`);
+    }
+    parseResult.meta.set('retrievalURI', retrievalURI);
+    return parseResult;
+  } catch (error) {
+    throw new BundleError(`Failed to bundle OpenAPI Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Checks if the element is a valid OpenAPI specification element.
+ */
+function isOpenApiElement(element) {
+  return isSwaggerElement(element) || isOpenApi3_0Element(element) || isOpenApi3_1Element(element);
+}