@speclynx/apidom-reference 2.13.1 → 3.1.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.1.0](https://github.com/speclynx/apidom/compare/v3.0.0...v3.1.0) (2026-03-08)
+
+### Features
+
+- **reference:** introduce continueOnError option for dereferencing ([#140](https://github.com/speclynx/apidom/issues/140)) ([a4b21fe](https://github.com/speclynx/apidom/commit/a4b21fe1ea7b6330d0f05c8bbbd713a0579b5115))
+
+# [3.0.0](https://github.com/speclynx/apidom/compare/v2.13.1...v3.0.0) (2026-03-05)
+
+### Features
+
+- introduce new memory efficient meta data management ([#129](https://github.com/speclynx/apidom/issues/129)) ([82ae0d7](https://github.com/speclynx/apidom/commit/82ae0d7cc2e9ee7037c3d9681817add2ca18dc92))
+
+### BREAKING CHANGES
+
+- meta data use to be elements before, now they are simple primitives
+
 ## [2.13.1](https://github.com/speclynx/apidom/compare/v2.13.0...v2.13.1) (2026-02-28)
 
 ### Bug Fixes

package/README.md

@@ -346,9 +346,9 @@ const parseResultFiltered = await parse('/path/to/arazzo.json', {
 // Access parsed source descriptions
 for (const element of parseResult) {
   if (element.classes.includes('source-description')) {
-    console.log(toValue(element.meta.get('name'))); // e.g., 'petStore'
-    console.log(toValue(element.meta.get('type'))); // e.g., 'openapi'
-    console.log(toValue(element.meta.get('retrievalURI'))); // e.g., '/path/to/petstore.json'
+    console.log(element.meta.get('name')); // e.g., 'petStore'
+    console.log(element.meta.get('type')); // e.g., 'openapi'
+    console.log(element.meta.get('retrievalURI')); // e.g., '/path/to/petstore.json'
   }
 }
 ```
@@ -380,7 +380,7 @@ if (parsedDoc.errors.length > 0) {
   console.log('Parsing failed:', parsedDoc.errors);
 } else {
   console.log(parsedDoc.api.element); // e.g., 'openApi3_1'
-  console.log(toValue(parsedDoc.meta.get('retrievalURI'))); // URI where it was fetched from
+  console.log(parsedDoc.meta.get('retrievalURI')); // URI where it was fetched from
 }
 ```
 
@@ -1889,7 +1889,7 @@ if (dereferencedDoc.errors.length > 0) {
   console.log('Dereferencing failed:', dereferencedDoc.errors);
 } else {
   console.log(dereferencedDoc.api.element); // e.g., 'openApi3_1'
-  console.log(toValue(dereferencedDoc.meta.get('retrievalURI'))); // URI where it was fetched from
+  console.log(dereferencedDoc.meta.get('retrievalURI')); // URI where it was fetched from
 }
 ```
 
@@ -2099,6 +2099,103 @@ await dereference('https://raw.githubusercontent.com/OAI/OpenAPI-Specification/m
 });
 ```
 
+##### Continue on error
+
+By default, dereferencing fails fast on the first unresolvable reference. The `continueOnError` option
+allows dereferencing to continue past broken references, collecting errors instead of throwing.
+
+**Type:** `false | true | ((error: UnresolvableReferenceError) => void)`
+
+**Default:** `false`
+
+| Value | Behavior |
+|---|---|
+| `false` | Fail fast — throws `UnresolvableReferenceError` on first broken reference |
+| `true` | Skip unresolvable references silently |
+| callback | Called for each unresolvable reference with structured error context |
+
+**Collecting errors with a callback:**
+
+```js
+import { dereference, UnresolvableReferenceError } from '@speclynx/apidom-reference';
+
+const errors = [];
+
+await dereference('/home/user/oas.json', {
+  parse: { mediaType: 'application/openapi+json;version=3.1.2' },
+  dereference: {
+    continueOnError: (error) => {
+      errors.push(error);
+    },
+  },
+});
+
+// errors is an array of UnresolvableReferenceError instances
+```
+
+Each `UnresolvableReferenceError` (extends `DereferenceError`) carries structured context:
+
+| Property | Type | Description |
+|---|---|---|
+| `message` | `string` | Contextual description (e.g., "Error while dereferencing Reference Object. Cannot resolve $ref ...") |
+| `type` | `string` | Element type that failed (e.g., `"reference"`, `"pathItem"`, `"schema"`, `"link"`, `"example"`) |
+| `uri` | `string` | Document URI where the error occurred |
+| `location` | `string` | JSON Pointer to the element within the document |
+| `codeFrame` | `string` | YAML snippet of the referencing element |
+| `refFieldName` | `string` | Reference field name (e.g., `"$ref"`, `"operationRef"`, `"externalValue"`) |
+| `refFieldValue` | `string` | Reference field value |
+| `trace` | `Array` | Chain of reference hops from entry document to the failure |
+| `cause` | `Error` | The underlying error |
+
+Each entry in the `trace` array has the shape `{ uri, type, refFieldName, refFieldValue, location, codeFrame }`,
+representing one hop in the reference chain that led to the failure. The trace is ordered from outermost (entry document)
+to innermost (closest to the failing reference). For direct failures in the entry document, the trace is empty.
+
+**Example output for a 3-hop chain** (`root.yaml → inventory.yaml → items.yaml → missing.yaml`):
+
+```
+error.uri        = "items.yaml"
+error.location   = "/ItemList/items"
+error.refFieldValue = "./missing.yaml#/Item"
+error.trace = [
+  { uri: "root.yaml", location: "/paths/~1inventory/get/.../schema", refFieldValue: "./inventory.yaml#/InventorySchema" },
+  { uri: "inventory.yaml", location: "/InventorySchema/properties/items", refFieldValue: "./items.yaml#/ItemList" },
+]
+```
+
+If the callback **throws**, dereferencing stops immediately. This can be used to abort after a threshold:
+
+```js
+await dereference('/home/user/oas.json', {
+  parse: { mediaType: 'application/openapi+json;version=3.1.2' },
+  dereference: {
+    continueOnError: (error) => {
+      errors.push(error);
+      if (errors.length >= 10) throw new Error('Too many errors');
+    },
+  },
+});
+```
+
+The structured error context enables rich, user-friendly error reporting with full traceability:
+
+```
+[1] schemas/items.yaml at #/ItemList/items                           ← where the broken $ref is (file + JSON Pointer)
+
+  Error while reading file "schemas/no-such-item.yaml"              ← what went wrong (the cause)
+
+    | $ref: ./no-such-item.yaml#/Item                                ← code frame of the failing element
+
+  referenced from root.yaml at #/paths/.../schema                   ← trace: the entry document entry point
+    | $ref: ./schemas/inventory.yaml#/InventorySchema                ← code frame of the root reference
+  referenced from schemas/inventory.yaml at #/.../properties/items   ← trace: intermediate hop
+    | $ref: ./items.yaml#/ItemList                                   ← code frame of the intermediate reference
+```
+
+Reading top to bottom: the `$ref` at `/ItemList/items` in `schemas/items.yaml` cannot resolve `no-such-item.yaml`.
+We arrived there via: `root.yaml` referenced `inventory.yaml#/InventorySchema`, which referenced `items.yaml#/ItemList`,
+which contains the broken `$ref`.
+
 ##### Creating new dereference strategy
 
 Dereference component can be extended by additional strategies. Every strategy is an object that