@speclynx/apidom-reference 2.9.0 → 2.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "2.9.0",
+  "version": "2.10.1",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "publishConfig": {
     "access": "public",
@@ -231,29 +231,29 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "^2.9.0",
-    "@speclynx/apidom-datamodel": "^2.9.0",
-    "@speclynx/apidom-error": "^2.9.0",
-    "@speclynx/apidom-json-pointer": "^2.9.0",
-    "@speclynx/apidom-ns-arazzo-1": "^2.9.0",
-    "@speclynx/apidom-ns-asyncapi-2": "^2.9.0",
-    "@speclynx/apidom-ns-json-schema-2020-12": "^2.9.0",
-    "@speclynx/apidom-ns-openapi-2": "^2.9.0",
-    "@speclynx/apidom-ns-openapi-3-0": "^2.9.0",
-    "@speclynx/apidom-ns-openapi-3-1": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-json": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "^2.9.0",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "^2.9.0",
-    "@speclynx/apidom-traverse": "^2.9.0",
+    "@speclynx/apidom-core": "^2.10.1",
+    "@speclynx/apidom-datamodel": "^2.10.1",
+    "@speclynx/apidom-error": "^2.10.1",
+    "@speclynx/apidom-json-pointer": "^2.10.1",
+    "@speclynx/apidom-ns-arazzo-1": "^2.10.1",
+    "@speclynx/apidom-ns-asyncapi-2": "^2.10.1",
+    "@speclynx/apidom-ns-json-schema-2020-12": "^2.10.1",
+    "@speclynx/apidom-ns-openapi-2": "^2.10.1",
+    "@speclynx/apidom-ns-openapi-3-0": "^2.10.1",
+    "@speclynx/apidom-ns-openapi-3-1": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-json": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "^2.10.1",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "^2.10.1",
+    "@speclynx/apidom-traverse": "^2.10.1",
     "@swaggerexpert/arazzo-runtime-expression": "^2.0.2",
     "axios": "^1.13.0",
     "minimatch": "^7.4.6",
@@ -274,5 +274,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "171956df4417a88238134c1854a5ff823aa144d8"
+  "gitHead": "c17dde40295b5156a2fab55d247a5cbe0cd4ddf3"
 }

package/src/dereference/strategies/arazzo-1/source-descriptions.cjs

@@ -39,6 +39,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
 
   // normalize URI for consistent cycle detection and refSet cache key matching
   const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
+  parseResult.setMetaProperty('retrievalURI', retrievalURI);
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -152,7 +153,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  *   in `dereference.strategyOpts` to filter which source descriptions to process.
  * @param strategyName - Strategy name for options lookup (defaults to 'arazzo-1')
  * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
- *   (each with class 'source-description' and name/type metadata).
+ *   (each with class 'source-description' and metadata: name, type, retrievalURI).
  *   May return early with a single-element array containing a warning annotation when:
  *   - The API is not an Arazzo specification
  *   - The sourceDescriptions field is missing or not an array
@@ -161,6 +162,8 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  *
  * @example
  * ```typescript
+ * import { toValue } from '@speclynx/apidom-core';
+ *
  * // Dereference all source descriptions
  * await dereferenceSourceDescriptions(parseResult, uri, options);
  *
@@ -172,6 +175,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  * // Access dereferenced document from source description element
  * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
  * const dereferencedDoc = sourceDesc.meta.get('parseResult');
+ * const retrievalURI = toValue(dereferencedDoc.meta.get('retrievalURI'));
  * ```
  *
  * @public

package/src/dereference/strategies/arazzo-1/source-descriptions.mjs

@@ -34,6 +34,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
 
   // normalize URI for consistent cycle detection and refSet cache key matching
   const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
+  parseResult.setMetaProperty('retrievalURI', retrievalURI);
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -147,7 +148,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  *   in `dereference.strategyOpts` to filter which source descriptions to process.
  * @param strategyName - Strategy name for options lookup (defaults to 'arazzo-1')
  * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
- *   (each with class 'source-description' and name/type metadata).
+ *   (each with class 'source-description' and metadata: name, type, retrievalURI).
  *   May return early with a single-element array containing a warning annotation when:
  *   - The API is not an Arazzo specification
  *   - The sourceDescriptions field is missing or not an array
@@ -156,6 +157,8 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  *
  * @example
  * ```typescript
+ * import { toValue } from '@speclynx/apidom-core';
+ *
  * // Dereference all source descriptions
  * await dereferenceSourceDescriptions(parseResult, uri, options);
  *
@@ -167,6 +170,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  * // Access dereferenced document from source description element
  * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
  * const dereferencedDoc = sourceDesc.meta.get('parseResult');
+ * const retrievalURI = toValue(dereferencedDoc.meta.get('retrievalURI'));
  * ```
  *
  * @public

package/src/parse/parsers/arazzo-json-1/source-descriptions.cjs

@@ -43,6 +43,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
 
   // normalize URI for consistent cycle detection and cache key matching
   const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
+  parseResult.setMetaProperty('retrievalURI', retrievalURI);
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -124,7 +125,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
  *   in `parse.parserOpts` to filter which source descriptions to process.
  * @param parserName - Parser name for options lookup (defaults to 'arazzo-json-1')
  * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
- *   (each with class 'source-description' and name/type metadata).
+ *   (each with class 'source-description' and metadata: name, type, retrievalURI).
  *   May return early with a single-element array containing a warning annotation when:
  *   - The API is not an Arazzo specification
  *   - The sourceDescriptions field is missing or not an array
@@ -133,6 +134,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
  *
  * @example
  * ```typescript
+ * import { toValue } from '@speclynx/apidom-core';
  * import { options, mergeOptions } from '@speclynx/apidom-reference';
  * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
  *
@@ -147,6 +149,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
  * // Access parsed document from source description element
  * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
  * const parsedDoc = sourceDesc.meta.get('parseResult');
+ * const retrievalURI = toValue(parsedDoc.meta.get('retrievalURI'));
  * ```
  *
  * @public

package/src/parse/parsers/arazzo-json-1/source-descriptions.mjs

@@ -36,6 +36,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
 
   // normalize URI for consistent cycle detection and cache key matching
   const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
+  parseResult.setMetaProperty('retrievalURI', retrievalURI);
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -117,7 +118,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
  *   in `parse.parserOpts` to filter which source descriptions to process.
  * @param parserName - Parser name for options lookup (defaults to 'arazzo-json-1')
  * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
- *   (each with class 'source-description' and name/type metadata).
+ *   (each with class 'source-description' and metadata: name, type, retrievalURI).
  *   May return early with a single-element array containing a warning annotation when:
  *   - The API is not an Arazzo specification
  *   - The sourceDescriptions field is missing or not an array
@@ -126,6 +127,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
  *
  * @example
  * ```typescript
+ * import { toValue } from '@speclynx/apidom-core';
  * import { options, mergeOptions } from '@speclynx/apidom-reference';
  * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
  *
@@ -140,6 +142,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
  * // Access parsed document from source description element
  * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
  * const parsedDoc = sourceDesc.meta.get('parseResult');
+ * const retrievalURI = toValue(parsedDoc.meta.get('retrievalURI'));
  * ```
  *
  * @public

package/types/dereference/strategies/arazzo-1/source-descriptions.d.ts

@@ -14,7 +14,7 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  *   in `dereference.strategyOpts` to filter which source descriptions to process.
  * @param strategyName - Strategy name for options lookup (defaults to 'arazzo-1')
  * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
- *   (each with class 'source-description' and name/type metadata).
+ *   (each with class 'source-description' and metadata: name, type, retrievalURI).
  *   May return early with a single-element array containing a warning annotation when:
  *   - The API is not an Arazzo specification
  *   - The sourceDescriptions field is missing or not an array
@@ -23,6 +23,8 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  *
  * @example
  * ```typescript
+ * import { toValue } from '@speclynx/apidom-core';
+ *
  * // Dereference all source descriptions
  * await dereferenceSourceDescriptions(parseResult, uri, options);
  *
@@ -34,6 +36,7 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  * // Access dereferenced document from source description element
  * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
  * const dereferencedDoc = sourceDesc.meta.get('parseResult');
+ * const retrievalURI = toValue(dereferencedDoc.meta.get('retrievalURI'));
  * ```
  *
  * @public

package/types/parse/parsers/arazzo-json-1/source-descriptions.d.ts

@@ -14,7 +14,7 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  *   in `parse.parserOpts` to filter which source descriptions to process.
  * @param parserName - Parser name for options lookup (defaults to 'arazzo-json-1')
  * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
- *   (each with class 'source-description' and name/type metadata).
+ *   (each with class 'source-description' and metadata: name, type, retrievalURI).
  *   May return early with a single-element array containing a warning annotation when:
  *   - The API is not an Arazzo specification
  *   - The sourceDescriptions field is missing or not an array
@@ -23,6 +23,7 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  *
  * @example
  * ```typescript
+ * import { toValue } from '@speclynx/apidom-core';
  * import { options, mergeOptions } from '@speclynx/apidom-reference';
  * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
  *
@@ -37,6 +38,7 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  * // Access parsed document from source description element
  * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
  * const parsedDoc = sourceDesc.meta.get('parseResult');
+ * const retrievalURI = toValue(parsedDoc.meta.get('retrievalURI'));
  * ```
  *
  * @public