@apidevtools/json-schema-ref-parser 10.0.0 → 10.1.0

package/dist/lib/bundle.d.ts

@@ -0,0 +1,10 @@
+export default bundle;
+/**
+ * Bundles all external JSON references into the main JSON schema, thus resulting in a schema that
+ * only has *internal* references, not any *external* references.
+ * This method mutates the JSON schema object, adding new references and re-mapping existing ones.
+ *
+ * @param parser
+ * @param options
+ */
+declare function bundle(parser: any, options: any): void;

package/dist/lib/bundle.js

@@ -0,0 +1,265 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ref_js_1 = __importDefault(require("./ref.js"));
+const pointer_js_1 = __importDefault(require("./pointer.js"));
+const url = __importStar(require("./util/url.js"));
+exports.default = bundle;
+/**
+ * Bundles all external JSON references into the main JSON schema, thus resulting in a schema that
+ * only has *internal* references, not any *external* references.
+ * This method mutates the JSON schema object, adding new references and re-mapping existing ones.
+ *
+ * @param parser
+ * @param options
+ */
+function bundle(parser, options) {
+    // console.log('Bundling $ref pointers in %s', parser.$refs._root$Ref.path);
+    // Build an inventory of all $ref pointers in the JSON Schema
+    const inventory = [];
+    crawl(parser, "schema", parser.$refs._root$Ref.path + "#", "#", 0, inventory, parser.$refs, options);
+    // Remap all $ref pointers
+    remap(inventory);
+}
+/**
+ * Recursively crawls the given value, and inventories all JSON references.
+ *
+ * @param parent - The object containing the value to crawl. If the value is not an object or array, it will be ignored.
+ * @param key - The property key of `parent` to be crawled
+ * @param path - The full path of the property being crawled, possibly with a JSON Pointer in the hash
+ * @param pathFromRoot - The path of the property being crawled, from the schema root
+ * @param inventory - An array of already-inventoried $ref pointers
+ * @param $refs
+ * @param options
+ */
+function crawl(parent, key, path, pathFromRoot, indirections, inventory, $refs, options) {
+    const obj = key === null ? parent : parent[key];
+    if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj)) {
+        // @ts-expect-error TS(2554): Expected 2 arguments, but got 1.
+        if (ref_js_1.default.isAllowed$Ref(obj)) {
+            inventory$Ref(parent, key, path, pathFromRoot, indirections, inventory, $refs, options);
+        }
+        else {
+            // Crawl the object in a specific order that's optimized for bundling.
+            // This is important because it determines how `pathFromRoot` gets built,
+            // which later determines which keys get dereferenced and which ones get remapped
+            const keys = Object.keys(obj).sort((a, b) => {
+                // Most people will expect references to be bundled into the the "definitions" property,
+                // so we always crawl that property first, if it exists.
+                if (a === "definitions") {
+                    return -1;
+                }
+                else if (b === "definitions") {
+                    return 1;
+                }
+                else {
+                    // Otherwise, crawl the keys based on their length.
+                    // This produces the shortest possible bundled references
+                    return a.length - b.length;
+                }
+            });
+            // eslint-disable-next-line no-shadow
+            for (const key of keys) {
+                const keyPath = pointer_js_1.default.join(path, key);
+                const keyPathFromRoot = pointer_js_1.default.join(pathFromRoot, key);
+                const value = obj[key];
+                // @ts-expect-error TS(2554): Expected 2 arguments, but got 1.
+                if (ref_js_1.default.isAllowed$Ref(value)) {
+                    inventory$Ref(obj, key, path, keyPathFromRoot, indirections, inventory, $refs, options);
+                }
+                else {
+                    crawl(obj, key, keyPath, keyPathFromRoot, indirections, inventory, $refs, options);
+                }
+            }
+        }
+    }
+}
+/**
+ * Inventories the given JSON Reference (i.e. records detailed information about it so we can
+ * optimize all $refs in the schema), and then crawls the resolved value.
+ *
+ * @param $refParent - The object that contains a JSON Reference as one of its keys
+ * @param $refKey - The key in `$refParent` that is a JSON Reference
+ * @param path - The full path of the JSON Reference at `$refKey`, possibly with a JSON Pointer in the hash
+ * @param pathFromRoot - The path of the JSON Reference at `$refKey`, from the schema root
+ * @param inventory - An array of already-inventoried $ref pointers
+ * @param $refs
+ * @param options
+ */
+function inventory$Ref($refParent, $refKey, path, pathFromRoot, indirections, inventory, $refs, options) {
+    const $ref = $refKey === null ? $refParent : $refParent[$refKey];
+    const $refPath = url.resolve(path, $ref.$ref);
+    const pointer = $refs._resolve($refPath, pathFromRoot, options);
+    if (pointer === null) {
+        return;
+    }
+    const depth = pointer_js_1.default.parse(pathFromRoot).length;
+    const file = url.stripHash(pointer.path);
+    const hash = url.getHash(pointer.path);
+    const external = file !== $refs._root$Ref.path;
+    const extended = ref_js_1.default.isExtended$Ref($ref);
+    indirections += pointer.indirections;
+    const existingEntry = findInInventory(inventory, $refParent, $refKey);
+    if (existingEntry) {
+        // This $Ref has already been inventoried, so we don't need to process it again
+        if (depth < existingEntry.depth || indirections < existingEntry.indirections) {
+            removeFromInventory(inventory, existingEntry);
+        }
+        else {
+            return;
+        }
+    }
+    inventory.push({
+        $ref,
+        parent: $refParent,
+        key: $refKey,
+        pathFromRoot,
+        depth,
+        file,
+        hash,
+        value: pointer.value,
+        circular: pointer.circular,
+        extended,
+        external,
+        indirections, // The number of indirect references that were traversed to resolve the value
+    });
+    // Recursively crawl the resolved value
+    if (!existingEntry || external) {
+        crawl(pointer.value, null, pointer.path, pathFromRoot, indirections + 1, inventory, $refs, options);
+    }
+}
+/**
+ * Re-maps every $ref pointer, so that they're all relative to the root of the JSON Schema.
+ * Each referenced value is dereferenced EXACTLY ONCE.  All subsequent references to the same
+ * value are re-mapped to point to the first reference.
+ *
+ * @example: {
+ *    first: { $ref: somefile.json#/some/part },
+ *    second: { $ref: somefile.json#/another/part },
+ *    third: { $ref: somefile.json },
+ *    fourth: { $ref: somefile.json#/some/part/sub/part }
+ *  }
+ *
+ * In this example, there are four references to the same file, but since the third reference points
+ * to the ENTIRE file, that's the only one we need to dereference.  The other three can just be
+ * remapped to point inside the third one.
+ *
+ * On the other hand, if the third reference DIDN'T exist, then the first and second would both need
+ * to be dereferenced, since they point to different parts of the file. The fourth reference does NOT
+ * need to be dereferenced, because it can be remapped to point inside the first one.
+ *
+ * @param inventory
+ */
+function remap(inventory) {
+    // Group & sort all the $ref pointers, so they're in the order that we need to dereference/remap them
+    inventory.sort((a, b) => {
+        if (a.file !== b.file) {
+            // Group all the $refs that point to the same file
+            return a.file < b.file ? -1 : +1;
+        }
+        else if (a.hash !== b.hash) {
+            // Group all the $refs that point to the same part of the file
+            return a.hash < b.hash ? -1 : +1;
+        }
+        else if (a.circular !== b.circular) {
+            // If the $ref points to itself, then sort it higher than other $refs that point to this $ref
+            return a.circular ? -1 : +1;
+        }
+        else if (a.extended !== b.extended) {
+            // If the $ref extends the resolved value, then sort it lower than other $refs that don't extend the value
+            return a.extended ? +1 : -1;
+        }
+        else if (a.indirections !== b.indirections) {
+            // Sort direct references higher than indirect references
+            return a.indirections - b.indirections;
+        }
+        else if (a.depth !== b.depth) {
+            // Sort $refs by how close they are to the JSON Schema root
+            return a.depth - b.depth;
+        }
+        else {
+            // Determine how far each $ref is from the "definitions" property.
+            // Most people will expect references to be bundled into the the "definitions" property if possible.
+            const aDefinitionsIndex = a.pathFromRoot.lastIndexOf("/definitions");
+            const bDefinitionsIndex = b.pathFromRoot.lastIndexOf("/definitions");
+            if (aDefinitionsIndex !== bDefinitionsIndex) {
+                // Give higher priority to the $ref that's closer to the "definitions" property
+                return bDefinitionsIndex - aDefinitionsIndex;
+            }
+            else {
+                // All else is equal, so use the shorter path, which will produce the shortest possible reference
+                return a.pathFromRoot.length - b.pathFromRoot.length;
+            }
+        }
+    });
+    let file, hash, pathFromRoot;
+    for (const entry of inventory) {
+        // console.log('Re-mapping $ref pointer "%s" at %s', entry.$ref.$ref, entry.pathFromRoot);
+        if (!entry.external) {
+            // This $ref already resolves to the main JSON Schema file
+            entry.$ref.$ref = entry.hash;
+        }
+        else if (entry.file === file && entry.hash === hash) {
+            // This $ref points to the same value as the prevous $ref, so remap it to the same path
+            entry.$ref.$ref = pathFromRoot;
+        }
+        else if (entry.file === file && entry.hash.indexOf(hash + "/") === 0) {
+            // This $ref points to a sub-value of the prevous $ref, so remap it beneath that path
+            entry.$ref.$ref = pointer_js_1.default.join(pathFromRoot, pointer_js_1.default.parse(entry.hash.replace(hash, "#")));
+        }
+        else {
+            // We've moved to a new file or new hash
+            file = entry.file;
+            hash = entry.hash;
+            pathFromRoot = entry.pathFromRoot;
+            // This is the first $ref to point to this value, so dereference the value.
+            // Any other $refs that point to the same value will point to this $ref instead
+            entry.$ref = entry.parent[entry.key] = ref_js_1.default.dereference(entry.$ref, entry.value);
+            if (entry.circular) {
+                // This $ref points to itself
+                entry.$ref.$ref = entry.pathFromRoot;
+            }
+        }
+        // console.log('    new value: %s', (entry.$ref && entry.$ref.$ref) ? entry.$ref.$ref : '[object Object]');
+    }
+}
+/**
+ * TODO
+ */
+function findInInventory(inventory, $refParent, $refKey) {
+    for (let i = 0; i < inventory.length; i++) {
+        const existingEntry = inventory[i];
+        if (existingEntry.parent === $refParent && existingEntry.key === $refKey) {
+            return existingEntry;
+        }
+    }
+}
+function removeFromInventory(inventory, entry) {
+    const index = inventory.indexOf(entry);
+    inventory.splice(index, 1);
+}

package/dist/lib/dereference.d.ts

@@ -0,0 +1,9 @@
+export default dereference;
+/**
+ * Crawls the JSON schema, finds all JSON references, and dereferences them.
+ * This method mutates the JSON schema object, replacing JSON references with their resolved value.
+ *
+ * @param parser
+ * @param options
+ */
+declare function dereference(parser: any, options: any): void;

package/dist/lib/dereference.js

@@ -0,0 +1,206 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ref_js_1 = __importDefault(require("./ref.js"));
+const pointer_js_1 = __importDefault(require("./pointer.js"));
+const ono_1 = require("@jsdevtools/ono");
+const url = __importStar(require("./util/url.js"));
+exports.default = dereference;
+/**
+ * Crawls the JSON schema, finds all JSON references, and dereferences them.
+ * This method mutates the JSON schema object, replacing JSON references with their resolved value.
+ *
+ * @param parser
+ * @param options
+ */
+function dereference(parser, options) {
+    // console.log('Dereferencing $ref pointers in %s', parser.$refs._root$Ref.path);
+    const dereferenced = crawl(parser.schema, parser.$refs._root$Ref.path, "#", new Set(), new Set(), new Map(), parser.$refs, options);
+    parser.$refs.circular = dereferenced.circular;
+    parser.schema = dereferenced.value;
+}
+/**
+ * Recursively crawls the given value, and dereferences any JSON references.
+ *
+ * @param obj - The value to crawl. If it's not an object or array, it will be ignored.
+ * @param path - The full path of `obj`, possibly with a JSON Pointer in the hash
+ * @param pathFromRoot - The path of `obj` from the schema root
+ * @param parents - An array of the parent objects that have already been dereferenced
+ * @param processedObjects - An array of all the objects that have already been processed
+ * @param dereferencedCache - An map of all the dereferenced objects
+ * @param $refs
+ * @param options
+ * @returns
+ */
+function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options) {
+    let dereferenced;
+    const result = {
+        value: obj,
+        circular: false,
+    };
+    const isExcludedPath = options.dereference.excludedPathMatcher || (() => false);
+    if (options.dereference.circular === "ignore" || !processedObjects.has(obj)) {
+        if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
+            parents.add(obj);
+            processedObjects.add(obj);
+            if (ref_js_1.default.isAllowed$Ref(obj, options)) {
+                dereferenced = dereference$Ref(obj, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options);
+                result.circular = dereferenced.circular;
+                result.value = dereferenced.value;
+            }
+            else {
+                for (const key of Object.keys(obj)) {
+                    const keyPath = pointer_js_1.default.join(path, key);
+                    const keyPathFromRoot = pointer_js_1.default.join(pathFromRoot, key);
+                    if (isExcludedPath(keyPathFromRoot)) {
+                        continue;
+                    }
+                    const value = obj[key];
+                    let circular = false;
+                    if (ref_js_1.default.isAllowed$Ref(value, options)) {
+                        dereferenced = dereference$Ref(value, keyPath, keyPathFromRoot, parents, processedObjects, dereferencedCache, $refs, options);
+                        circular = dereferenced.circular;
+                        // Avoid pointless mutations; breaks frozen objects to no profit
+                        if (obj[key] !== dereferenced.value) {
+                            obj[key] = dereferenced.value;
+                            if (options.dereference.onDereference) {
+                                options.dereference.onDereference(value.$ref, obj[key]);
+                            }
+                        }
+                    }
+                    else {
+                        if (!parents.has(value)) {
+                            dereferenced = crawl(value, keyPath, keyPathFromRoot, parents, processedObjects, dereferencedCache, $refs, options);
+                            circular = dereferenced.circular;
+                            // Avoid pointless mutations; breaks frozen objects to no profit
+                            if (obj[key] !== dereferenced.value) {
+                                obj[key] = dereferenced.value;
+                            }
+                        }
+                        else {
+                            circular = foundCircularReference(keyPath, $refs, options);
+                        }
+                    }
+                    // Set the "isCircular" flag if this or any other property is circular
+                    result.circular = result.circular || circular;
+                }
+            }
+            parents.delete(obj);
+        }
+    }
+    return result;
+}
+/**
+ * Dereferences the given JSON Reference, and then crawls the resulting value.
+ *
+ * @param $ref - The JSON Reference to resolve
+ * @param path - The full path of `$ref`, possibly with a JSON Pointer in the hash
+ * @param pathFromRoot - The path of `$ref` from the schema root
+ * @param parents - An array of the parent objects that have already been dereferenced
+ * @param processedObjects - An array of all the objects that have already been dereferenced
+ * @param dereferencedCache - An map of all the dereferenced objects
+ * @param $refs
+ * @param options
+ * @returns
+ */
+function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options) {
+    // console.log('Dereferencing $ref pointer "%s" at %s', $ref.$ref, path);
+    const $refPath = url.resolve(path, $ref.$ref);
+    const cache = dereferencedCache.get($refPath);
+    if (cache) {
+        const refKeys = Object.keys($ref);
+        if (refKeys.length > 1) {
+            const extraKeys = {};
+            for (const key of refKeys) {
+                if (key !== "$ref" && !(key in cache.value)) {
+                    // @ts-expect-error TS(7053): Element implicitly has an 'any' type because expre... Remove this comment to see the full error message
+                    extraKeys[key] = $ref[key];
+                }
+            }
+            return {
+                circular: cache.circular,
+                value: Object.assign({}, cache.value, extraKeys),
+            };
+        }
+        return cache;
+    }
+    const pointer = $refs._resolve($refPath, path, options);
+    if (pointer === null) {
+        return {
+            circular: false,
+            value: null,
+        };
+    }
+    // Check for circular references
+    const directCircular = pointer.circular;
+    let circular = directCircular || parents.has(pointer.value);
+    circular && foundCircularReference(path, $refs, options);
+    // Dereference the JSON reference
+    let dereferencedValue = ref_js_1.default.dereference($ref, pointer.value);
+    // Crawl the dereferenced value (unless it's circular)
+    if (!circular) {
+        // Determine if the dereferenced value is circular
+        const dereferenced = crawl(dereferencedValue, pointer.path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options);
+        circular = dereferenced.circular;
+        dereferencedValue = dereferenced.value;
+    }
+    if (circular && !directCircular && options.dereference.circular === "ignore") {
+        // The user has chosen to "ignore" circular references, so don't change the value
+        dereferencedValue = $ref;
+    }
+    if (directCircular) {
+        // The pointer is a DIRECT circular reference (i.e. it references itself).
+        // So replace the $ref path with the absolute path from the JSON Schema root
+        dereferencedValue.$ref = pathFromRoot;
+    }
+    const dereferencedObject = {
+        circular,
+        value: dereferencedValue,
+    };
+    // only cache if no extra properties than $ref
+    if (Object.keys($ref).length === 1) {
+        dereferencedCache.set($refPath, dereferencedObject);
+    }
+    return dereferencedObject;
+}
+/**
+ * Called when a circular reference is found.
+ * It sets the {@link $Refs#circular} flag, and throws an error if options.dereference.circular is false.
+ *
+ * @param keyPath - The JSON Reference path of the circular reference
+ * @param $refs
+ * @param options
+ * @returns - always returns true, to indicate that a circular reference was found
+ */
+function foundCircularReference(keyPath, $refs, options) {
+    $refs.circular = true;
+    if (!options.dereference.circular) {
+        throw ono_1.ono.reference(`Circular $ref pointer found at ${keyPath}`);
+    }
+    return true;
+}