@speclynx/apidom-reference 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.9.0](https://github.com/speclynx/apidom/compare/v2.8.0...v2.9.0) (2026-02-08)
+
+### Features
+
+- **reference:** attach parse result as meta to Arazzo source descriptions ([#76](https://github.com/speclynx/apidom/issues/76)) ([448a099](https://github.com/speclynx/apidom/commit/448a099fc6af8189302346efdcc117c95c9b6e3b))
+- **reference:** avoid re-resolving Arazzo source descriptions during dereferencing ([#77](https://github.com/speclynx/apidom/issues/77)) ([0ad63e8](https://github.com/speclynx/apidom/commit/0ad63e8d204d991a0de47b486ad391d506eb66dc))
+- **reference:** expose low level API for dereferencing Arazzo source descriptions ([#75](https://github.com/speclynx/apidom/issues/75)) ([3b1e343](https://github.com/speclynx/apidom/commit/3b1e343c58ff983201ac0509bf841845bbf7eb83))
+
 # [2.8.0](https://github.com/speclynx/apidom/compare/v2.7.0...v2.8.0) (2026-02-06)
 
 ### Features

package/README.md

@@ -351,6 +351,80 @@ for (const element of parseResult) {
 }
 ```
 
+##### Accessing parsed documents via SourceDescriptionElement
+
+When source descriptions parsing is enabled, a `ParseResultElement` is attached to each
+`SourceDescriptionElement`'s meta as `'parseResult'`. This attachment always happens,
+regardless of success or failure:
+
+- **On success**: The parseResult contains the parsed API document
+- **On failure**: The parseResult contains error/warning annotations explaining what went wrong
+
+```js
+import { parse } from '@speclynx/apidom-reference';
+
+const parseResult = await parse('/path/to/arazzo.json', {
+  parse: { parserOpts: { sourceDescriptions: true } },
+});
+
+// Access parsed document from source description element
+const api = parseResult.api;
+const sourceDesc = api.sourceDescriptions.get(0);
+const parsedDoc = sourceDesc.meta.get('parseResult');
+
+// Check for errors before using
+if (parsedDoc.errors.length > 0) {
+  console.log('Parsing failed:', parsedDoc.errors);
+} else {
+  console.log(parsedDoc.api.element); // e.g., 'openApi3_1'
+}
+```
+
+##### Low-level API
+
+For advanced use cases where you need to parse source descriptions from an already-parsed Arazzo document
+(e.g., when using naked parser adapters directly), the `parseSourceDescriptions` function is exported.
+
+When called directly, this function always parses source descriptions (no need to pass `sourceDescriptions: true`).
+Use an array to filter by name:
+
+```js
+import { parse } from '@speclynx/apidom-parser-adapter-arazzo-json-1';
+import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
+import { options, mergeOptions } from '@speclynx/apidom-reference';
+
+// Parse using naked parser adapter
+const parseResult = await parse(arazzoJsonString);
+
+// Parse all source descriptions
+const sourceDescriptions = await parseSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.json',
+  options,
+);
+
+// Or filter by name
+const filtered = await parseSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.json',
+  mergeOptions(options, { parse: { parserOpts: { sourceDescriptions: ['petStore'] } } }),
+);
+
+// Access parsed document from source description element
+const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+const parsedDoc = sourceDesc.meta.get('parseResult');
+```
+
+The function signature is:
+```typescript
+parseSourceDescriptions(
+  parseResult: ParseResultElement,
+  parseResultRetrievalURI: string,
+  options: ReferenceOptions,
+  parserName?: string, // defaults to 'arazzo-json-1'
+): Promise<ParseResultElement[]>
+```
+
 #### [arazzo-yaml-1](https://github.com/speclynx/apidom/tree/main/packages/apidom-reference/src/parse/parsers/arazzo-yaml-1)
 
 Wraps [@speclynx/apidom-parser-adapter-arazzo-yaml-1](https://github.com/speclynx/apidom/tree/main/packages/apidom-parser-adapter-arazzo-yaml-1) package
@@ -385,6 +459,55 @@ Parser-specific options take precedence over global options. See [arazzo-json-1]
 
 See [arazzo-json-1 Error handling](#error-handling) - the behavior is identical for both JSON and YAML parsers.
 
+##### Accessing parsed documents via SourceDescriptionElement
+
+See [arazzo-json-1 Accessing parsed documents](#accessing-parsed-documents-via-sourcedescriptionelement) - the behavior is identical for both JSON and YAML parsers.
+
+##### Low-level API
+
+For advanced use cases where you need to parse source descriptions from an already-parsed Arazzo document
+(e.g., when using naked parser adapters directly), the `parseSourceDescriptions` function is exported.
+
+When called directly, this function always parses source descriptions (no need to pass `sourceDescriptions: true`).
+Use an array to filter by name:
+
+```js
+import { parse } from '@speclynx/apidom-parser-adapter-arazzo-yaml-1';
+import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-yaml-1';
+import { options, mergeOptions } from '@speclynx/apidom-reference';
+
+// Parse using naked parser adapter
+const parseResult = await parse(arazzoYamlString);
+
+// Parse all source descriptions
+const sourceDescriptions = await parseSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.yaml',
+  options,
+);
+
+// Or filter by name
+const filtered = await parseSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.yaml',
+  mergeOptions(options, { parse: { parserOpts: { sourceDescriptions: ['petStore'] } } }),
+);
+
+// Access parsed document from source description element
+const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+const parsedDoc = sourceDesc.meta.get('parseResult');
+```
+
+The function signature is:
+```typescript
+parseSourceDescriptions(
+  parseResult: ParseResultElement,
+  parseResultRetrievalURI: string,
+  options: ReferenceOptions,
+  parserName?: string, // defaults to 'arazzo-yaml-1'
+): Promise<ParseResultElement[]>
+```
+
 #### [json](https://github.com/speclynx/apidom/tree/main/packages/apidom-reference/src/parse/parsers/json)
 
 Wraps [@speclynx/apidom-parser-adapter-json](https://github.com/speclynx/apidom/tree/main/packages/apidom-parser-adapter-json) package
@@ -1677,6 +1800,80 @@ const resultFiltered = await dereference('/path/to/arazzo.json', {
 });
 ```
 
+###### Accessing dereferenced documents via SourceDescriptionElement
+
+When source descriptions dereferencing is enabled, a `ParseResultElement` is attached to each
+`SourceDescriptionElement`'s meta as `'parseResult'`. This attachment always happens,
+regardless of success or failure:
+
+- **On success**: The parseResult contains the dereferenced API document
+- **On failure**: The parseResult contains error/warning annotations explaining what went wrong
+
+```js
+import { dereference } from '@speclynx/apidom-reference';
+
+const parseResult = await dereference('/path/to/arazzo.json', {
+  dereference: { strategyOpts: { sourceDescriptions: true } },
+});
+
+// Access dereferenced document from source description element
+const api = parseResult.api;
+const sourceDesc = api.sourceDescriptions.get(0);
+const dereferencedDoc = sourceDesc.meta.get('parseResult');
+
+// Check for errors before using
+if (dereferencedDoc.errors.length > 0) {
+  console.log('Dereferencing failed:', dereferencedDoc.errors);
+} else {
+  console.log(dereferencedDoc.api.element); // e.g., 'openApi3_1'
+}
+```
+
+###### Low-level API
+
+For advanced use cases where you need to dereference source descriptions from an already-parsed (optionally dereferenced)
+Arazzo document (e.g., when using naked parser adapters directly), the `dereferenceSourceDescriptions` function is exported.
+
+When called directly, this function always dereferences source descriptions (no need to pass `sourceDescriptions: true`).
+Use an array to filter by name:
+
+```js
+import { parse } from '@speclynx/apidom-parser-adapter-arazzo-json-1';
+import { dereferenceSourceDescriptions } from '@speclynx/apidom-reference/dereference/strategies/arazzo-1';
+import { options, mergeOptions } from '@speclynx/apidom-reference';
+
+// Parse using naked parser adapter
+const parseResult = await parse(arazzoJsonString);
+
+// Dereference all source descriptions
+const sourceDescriptions = await dereferenceSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.json',
+  options,
+);
+
+// Or filter by name
+const filtered = await dereferenceSourceDescriptions(
+  parseResult,
+  '/path/to/arazzo.json',
+  mergeOptions(options, { dereference: { strategyOpts: { sourceDescriptions: ['petStore'] } } }),
+);
+
+// Access dereferenced document from source description element
+const sourceDesc = parseResult.api.sourceDescriptions.get(0);
+const dereferencedDoc = sourceDesc.meta.get('parseResult');
+```
+
+The function signature is:
+```typescript
+dereferenceSourceDescriptions(
+  parseResult: ParseResultElement,
+  parseResultRetrievalURI: string,
+  options: ReferenceOptions,
+  strategyName?: string, // defaults to 'arazzo-1'
+): Promise<ParseResultElement[]>
+```
+
 ##### [openapi-2](https://github.com/speclynx/apidom/tree/main/packages/apidom-reference/src/dereference/strategies/openapi-2)
 
 Dereference strategy for dereferencing [OpenApi 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) definitions.