@apidevtools/json-schema-ref-parser 10.0.1 → 11.0.0

package/dist/lib/pointer.js

@@ -0,0 +1,256 @@
+"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 url = __importStar(require("./util/url.js"));
+const errors_js_1 = require("./util/errors.js");
+const slashes = /\//g;
+const tildes = /~/g;
+const escapedSlash = /~1/g;
+const escapedTilde = /~0/g;
+/**
+ * This class represents a single JSON pointer and its resolved value.
+ *
+ * @param $ref
+ * @param path
+ * @param [friendlyPath] - The original user-specified path (used for error messages)
+ * @class
+ */
+class Pointer {
+    constructor($ref, path, friendlyPath) {
+        this.$ref = $ref;
+        this.path = path;
+        this.originalPath = friendlyPath || path;
+        this.value = undefined;
+        this.circular = false;
+        this.indirections = 0;
+    }
+    /**
+     * Resolves the value of a nested property within the given object.
+     *
+     * @param obj - The object that will be crawled
+     * @param options
+     * @param pathFromRoot - the path of place that initiated resolving
+     *
+     * @returns
+     * Returns a JSON pointer whose {@link Pointer#value} is the resolved value.
+     * If resolving this value required resolving other JSON references, then
+     * the {@link Pointer#$ref} and {@link Pointer#path} will reflect the resolution path
+     * of the resolved value.
+     */
+    resolve(obj, options, pathFromRoot) {
+        const tokens = Pointer.parse(this.path, this.originalPath);
+        // Crawl the object, one token at a time
+        this.value = unwrapOrThrow(obj);
+        for (let i = 0; i < tokens.length; i++) {
+            if (resolveIf$Ref(this, options)) {
+                // The $ref path has changed, so append the remaining tokens to the path
+                this.path = Pointer.join(this.path, tokens.slice(i));
+            }
+            if (typeof this.value === "object" && this.value !== null && "$ref" in this.value) {
+                return this;
+            }
+            const token = tokens[i];
+            if (this.value[token] === undefined || this.value[token] === null) {
+                this.value = null;
+                throw new errors_js_1.MissingPointerError(token, decodeURI(this.originalPath));
+            }
+            else {
+                this.value = this.value[token];
+            }
+        }
+        // Resolve the final value
+        if (!this.value || (this.value.$ref && url.resolve(this.path, this.value.$ref) !== pathFromRoot)) {
+            resolveIf$Ref(this, options);
+        }
+        return this;
+    }
+    /**
+     * Sets the value of a nested property within the given object.
+     *
+     * @param obj - The object that will be crawled
+     * @param value - the value to assign
+     * @param options
+     *
+     * @returns
+     * Returns the modified object, or an entirely new object if the entire object is overwritten.
+     */
+    set(obj, value, options) {
+        const tokens = Pointer.parse(this.path);
+        let token;
+        if (tokens.length === 0) {
+            // There are no tokens, replace the entire object with the new value
+            this.value = value;
+            return value;
+        }
+        // Crawl the object, one token at a time
+        this.value = unwrapOrThrow(obj);
+        for (let i = 0; i < tokens.length - 1; i++) {
+            resolveIf$Ref(this, options);
+            token = tokens[i];
+            if (this.value && this.value[token] !== undefined) {
+                // The token exists
+                this.value = this.value[token];
+            }
+            else {
+                // The token doesn't exist, so create it
+                this.value = setValue(this, token, {});
+            }
+        }
+        // Set the value of the final token
+        resolveIf$Ref(this, options);
+        token = tokens[tokens.length - 1];
+        setValue(this, token, value);
+        // Return the updated object
+        return obj;
+    }
+    /**
+     * Parses a JSON pointer (or a path containing a JSON pointer in the hash)
+     * and returns an array of the pointer's tokens.
+     * (e.g. "schema.json#/definitions/person/name" => ["definitions", "person", "name"])
+     *
+     * The pointer is parsed according to RFC 6901
+     * {@link https://tools.ietf.org/html/rfc6901#section-3}
+     *
+     * @param path
+     * @param [originalPath]
+     * @returns
+     */
+    static parse(path, originalPath) {
+        // Get the JSON pointer from the path's hash
+        let pointer = url.getHash(path).substr(1);
+        // If there's no pointer, then there are no tokens,
+        // so return an empty array
+        if (!pointer) {
+            return [];
+        }
+        // Split into an array
+        pointer = pointer.split("/");
+        // Decode each part, according to RFC 6901
+        for (let i = 0; i < pointer.length; i++) {
+            pointer[i] = decodeURIComponent(pointer[i].replace(escapedSlash, "/").replace(escapedTilde, "~"));
+        }
+        if (pointer[0] !== "") {
+            throw new errors_js_1.InvalidPointerError(pointer, originalPath === undefined ? path : originalPath);
+        }
+        return pointer.slice(1);
+    }
+    /**
+     * Creates a JSON pointer path, by joining one or more tokens to a base path.
+     *
+     * @param base - The base path (e.g. "schema.json#/definitions/person")
+     * @param tokens - The token(s) to append (e.g. ["name", "first"])
+     * @returns
+     */
+    static join(base, tokens) {
+        // Ensure that the base path contains a hash
+        if (base.indexOf("#") === -1) {
+            base += "#";
+        }
+        // Append each token to the base path
+        tokens = Array.isArray(tokens) ? tokens : [tokens];
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            // Encode the token, according to RFC 6901
+            base += "/" + encodeURIComponent(token.replace(tildes, "~0").replace(slashes, "~1"));
+        }
+        return base;
+    }
+}
+/**
+ * If the given pointer's {@link Pointer#value} is a JSON reference,
+ * then the reference is resolved and {@link Pointer#value} is replaced with the resolved value.
+ * In addition, {@link Pointer#path} and {@link Pointer#$ref} are updated to reflect the
+ * resolution path of the new value.
+ *
+ * @param pointer
+ * @param options
+ * @returns - Returns `true` if the resolution path changed
+ */
+function resolveIf$Ref(pointer, options) {
+    // Is the value a JSON reference? (and allowed?)
+    if (ref_js_1.default.isAllowed$Ref(pointer.value, options)) {
+        const $refPath = url.resolve(pointer.path, pointer.value.$ref);
+        if ($refPath === pointer.path) {
+            // The value is a reference to itself, so there's nothing to do.
+            pointer.circular = true;
+        }
+        else {
+            const resolved = pointer.$ref.$refs._resolve($refPath, pointer.path, options);
+            if (resolved === null) {
+                return false;
+            }
+            pointer.indirections += resolved.indirections + 1;
+            if (ref_js_1.default.isExtended$Ref(pointer.value)) {
+                // This JSON reference "extends" the resolved value, rather than simply pointing to it.
+                // So the resolved path does NOT change.  Just the value does.
+                pointer.value = ref_js_1.default.dereference(pointer.value, resolved.value);
+                return false;
+            }
+            else {
+                // Resolve the reference
+                pointer.$ref = resolved.$ref;
+                pointer.path = resolved.path;
+                pointer.value = resolved.value;
+            }
+            return true;
+        }
+    }
+}
+exports.default = Pointer;
+/**
+ * Sets the specified token value of the {@link Pointer#value}.
+ *
+ * The token is evaluated according to RFC 6901.
+ * {@link https://tools.ietf.org/html/rfc6901#section-4}
+ *
+ * @param pointer - The JSON Pointer whose value will be modified
+ * @param token - A JSON Pointer token that indicates how to modify `obj`
+ * @param value - The value to assign
+ * @returns - Returns the assigned value
+ */
+function setValue(pointer, token, value) {
+    if (pointer.value && typeof pointer.value === "object") {
+        if (token === "-" && Array.isArray(pointer.value)) {
+            pointer.value.push(value);
+        }
+        else {
+            pointer.value[token] = value;
+        }
+    }
+    else {
+        throw new errors_js_1.JSONParserError(`Error assigning $ref pointer "${pointer.path}". \nCannot set "${token}" of a non-object.`);
+    }
+    return value;
+}
+function unwrapOrThrow(value) {
+    if ((0, errors_js_1.isHandledError)(value)) {
+        throw value;
+    }
+    return value;
+}

package/dist/lib/ref.d.ts

@@ -0,0 +1,180 @@
+import Pointer from "./pointer.js";
+import type { JSONParserError, MissingPointerError, ParserError, ResolverError } from "./util/errors.js";
+import type $Refs from "./refs.js";
+import type $RefParserOptions from "./options.js";
+type $RefError = JSONParserError | ResolverError | ParserError | MissingPointerError;
+/**
+ * This class represents a single JSON reference and its resolved value.
+ *
+ * @class
+ */
+declare class $Ref {
+    /**
+     * The file path or URL of the referenced file.
+     * This path is relative to the path of the main JSON schema file.
+     *
+     * This path does NOT contain document fragments (JSON pointers). It always references an ENTIRE file.
+     * Use methods such as {@link $Ref#get}, {@link $Ref#resolve}, and {@link $Ref#exists} to get
+     * specific JSON pointers within the file.
+     *
+     * @type {string}
+     */
+    path: undefined | string;
+    /**
+     * The resolved value of the JSON reference.
+     * Can be any JSON type, not just objects. Unknown file types are represented as Buffers (byte arrays).
+     *
+     * @type {?*}
+     */
+    value: any;
+    /**
+     * The {@link $Refs} object that contains this {@link $Ref} object.
+     *
+     * @type {$Refs}
+     */
+    $refs: $Refs;
+    /**
+     * Indicates the type of {@link $Ref#path} (e.g. "file", "http", etc.)
+     */
+    pathType: string | unknown;
+    /**
+     * List of all errors. Undefined if no errors.
+     */
+    errors: Array<$RefError>;
+    constructor($refs: $Refs);
+    /**
+     * Pushes an error to errors array.
+     *
+     * @param err - The error to be pushed
+     * @returns
+     */
+    addError(err: $RefError): void;
+    /**
+     * Determines whether the given JSON reference exists within this {@link $Ref#value}.
+     *
+     * @param path - The full path being resolved, optionally with a JSON pointer in the hash
+     * @param options
+     * @returns
+     */
+    exists(path: string, options: any): boolean;
+    /**
+     * Resolves the given JSON reference within this {@link $Ref#value} and returns the resolved value.
+     *
+     * @param path - The full path being resolved, optionally with a JSON pointer in the hash
+     * @param options
+     * @returns - Returns the resolved value
+     */
+    get(path: any, options: any): any;
+    /**
+     * Resolves the given JSON reference within this {@link $Ref#value}.
+     *
+     * @param path - The full path being resolved, optionally with a JSON pointer in the hash
+     * @param options
+     * @param friendlyPath - The original user-specified path (used for error messages)
+     * @param pathFromRoot - The path of `obj` from the schema root
+     * @returns
+     */
+    resolve(path: any, options?: $RefParserOptions, friendlyPath?: string, pathFromRoot?: string): Pointer | null;
+    /**
+     * Sets the value of a nested property within this {@link $Ref#value}.
+     * If the property, or any of its parents don't exist, they will be created.
+     *
+     * @param path - The full path of the property to set, optionally with a JSON pointer in the hash
+     * @param value - The value to assign
+     */
+    set(path: any, value: any): void;
+    /**
+     * Determines whether the given value is a JSON reference.
+     *
+     * @param value - The value to inspect
+     * @returns
+     */
+    static is$Ref(value: any): value is {
+        $ref: string;
+        length?: number;
+    };
+    /**
+     * Determines whether the given value is an external JSON reference.
+     *
+     * @param value - The value to inspect
+     * @returns
+     */
+    static isExternal$Ref(value: any): boolean;
+    /**
+     * Determines whether the given value is a JSON reference, and whether it is allowed by the options.
+     * For example, if it references an external file, then options.resolve.external must be true.
+     *
+     * @param value - The value to inspect
+     * @param options
+     * @returns
+     */
+    static isAllowed$Ref(value: any, options: any): true | undefined;
+    /**
+     * Determines whether the given value is a JSON reference that "extends" its resolved value.
+     * That is, it has extra properties (in addition to "$ref"), so rather than simply pointing to
+     * an existing value, this $ref actually creates a NEW value that is a shallow copy of the resolved
+     * value, plus the extra properties.
+     *
+     * @example: {
+       person: {
+         properties: {
+           firstName: { type: string }
+           lastName: { type: string }
+         }
+       }
+       employee: {
+         properties: {
+           $ref: #/person/properties
+           salary: { type: number }
+         }
+       }
+     }
+     *  In this example, "employee" is an extended $ref, since it extends "person" with an additional
+     *  property (salary).  The result is a NEW value that looks like this:
+     *
+     *  {
+     *    properties: {
+     *      firstName: { type: string }
+     *      lastName: { type: string }
+     *      salary: { type: number }
+     *    }
+     *  }
+     *
+     * @param value - The value to inspect
+     * @returns
+     */
+    static isExtended$Ref(value: any): boolean;
+    /**
+     * Returns the resolved value of a JSON Reference.
+     * If necessary, the resolved value is merged with the JSON Reference to create a new object
+     *
+     * @example: {
+    person: {
+      properties: {
+        firstName: { type: string }
+        lastName: { type: string }
+      }
+    }
+    employee: {
+      properties: {
+        $ref: #/person/properties
+        salary: { type: number }
+      }
+    }
+    } When "person" and "employee" are merged, you end up with the following object:
+     *
+     *  {
+     *    properties: {
+     *      firstName: { type: string }
+     *      lastName: { type: string }
+     *      salary: { type: number }
+     *    }
+     *  }
+     *
+     * @param $ref - The JSON reference object (the one with the "$ref" property)
+     * @param resolvedValue - The resolved value, which can be any type
+     * @returns - Returns the dereferenced value
+     */
+    static dereference($ref: $Ref, resolvedValue: any): any;
+}
+export default $Ref;

package/dist/lib/ref.js

@@ -0,0 +1,238 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const pointer_js_1 = __importDefault(require("./pointer.js"));
+const errors_js_1 = require("./util/errors.js");
+const url_js_1 = require("./util/url.js");
+/**
+ * This class represents a single JSON reference and its resolved value.
+ *
+ * @class
+ */
+class $Ref {
+    constructor($refs) {
+        /**
+         * List of all errors. Undefined if no errors.
+         */
+        this.errors = [];
+        this.$refs = $refs;
+    }
+    /**
+     * Pushes an error to errors array.
+     *
+     * @param err - The error to be pushed
+     * @returns
+     */
+    addError(err) {
+        if (this.errors === undefined) {
+            this.errors = [];
+        }
+        const existingErrors = this.errors.map(({ footprint }) => footprint);
+        // the path has been almost certainly set at this point,
+        // but just in case something went wrong, normalizeError injects path if necessary
+        // moreover, certain errors might point at the same spot, so filter them out to reduce noise
+        if ("errors" in err && Array.isArray(err.errors)) {
+            this.errors.push(...err.errors.map(errors_js_1.normalizeError).filter(({ footprint }) => !existingErrors.includes(footprint)));
+        }
+        else if (!("footprint" in err) || !existingErrors.includes(err.footprint)) {
+            this.errors.push((0, errors_js_1.normalizeError)(err));
+        }
+    }
+    /**
+     * Determines whether the given JSON reference exists within this {@link $Ref#value}.
+     *
+     * @param path - The full path being resolved, optionally with a JSON pointer in the hash
+     * @param options
+     * @returns
+     */
+    exists(path, options) {
+        try {
+            this.resolve(path, options);
+            return true;
+        }
+        catch (e) {
+            return false;
+        }
+    }
+    /**
+     * Resolves the given JSON reference within this {@link $Ref#value} and returns the resolved value.
+     *
+     * @param path - The full path being resolved, optionally with a JSON pointer in the hash
+     * @param options
+     * @returns - Returns the resolved value
+     */
+    get(path, options) {
+        return this.resolve(path, options)?.value;
+    }
+    /**
+     * Resolves the given JSON reference within this {@link $Ref#value}.
+     *
+     * @param path - The full path being resolved, optionally with a JSON pointer in the hash
+     * @param options
+     * @param friendlyPath - The original user-specified path (used for error messages)
+     * @param pathFromRoot - The path of `obj` from the schema root
+     * @returns
+     */
+    resolve(path, options, friendlyPath, pathFromRoot) {
+        const pointer = new pointer_js_1.default(this, path, friendlyPath);
+        try {
+            return pointer.resolve(this.value, options, pathFromRoot);
+        }
+        catch (err) {
+            if (!options || !options.continueOnError || !(0, errors_js_1.isHandledError)(err)) {
+                throw err;
+            }
+            if (err.path === null) {
+                err.path = (0, url_js_1.safePointerToPath)((0, url_js_1.getHash)(pathFromRoot));
+            }
+            if (err instanceof errors_js_1.InvalidPointerError) {
+                err.source = decodeURI((0, url_js_1.stripHash)(pathFromRoot));
+            }
+            this.addError(err);
+            return null;
+        }
+    }
+    /**
+     * Sets the value of a nested property within this {@link $Ref#value}.
+     * If the property, or any of its parents don't exist, they will be created.
+     *
+     * @param path - The full path of the property to set, optionally with a JSON pointer in the hash
+     * @param value - The value to assign
+     */
+    set(path, value) {
+        // @ts-expect-error TS(2554): Expected 3 arguments, but got 2.
+        const pointer = new pointer_js_1.default(this, path);
+        this.value = pointer.set(this.value, value);
+    }
+    /**
+     * Determines whether the given value is a JSON reference.
+     *
+     * @param value - The value to inspect
+     * @returns
+     */
+    static is$Ref(value) {
+        return value && typeof value === "object" && typeof value.$ref === "string" && value.$ref.length > 0;
+    }
+    /**
+     * Determines whether the given value is an external JSON reference.
+     *
+     * @param value - The value to inspect
+     * @returns
+     */
+    static isExternal$Ref(value) {
+        return $Ref.is$Ref(value) && value.$ref[0] !== "#";
+    }
+    /**
+     * Determines whether the given value is a JSON reference, and whether it is allowed by the options.
+     * For example, if it references an external file, then options.resolve.external must be true.
+     *
+     * @param value - The value to inspect
+     * @param options
+     * @returns
+     */
+    static isAllowed$Ref(value, options) {
+        if (this.is$Ref(value)) {
+            if (value.$ref.substring(0, 2) === "#/" || value.$ref === "#") {
+                // It's a JSON Pointer reference, which is always allowed
+                return true;
+            }
+            else if (value.$ref[0] !== "#" && (!options || options.resolve.external)) {
+                // It's an external reference, which is allowed by the options
+                return true;
+            }
+        }
+    }
+    /**
+     * Determines whether the given value is a JSON reference that "extends" its resolved value.
+     * That is, it has extra properties (in addition to "$ref"), so rather than simply pointing to
+     * an existing value, this $ref actually creates a NEW value that is a shallow copy of the resolved
+     * value, plus the extra properties.
+     *
+     * @example: {
+       person: {
+         properties: {
+           firstName: { type: string }
+           lastName: { type: string }
+         }
+       }
+       employee: {
+         properties: {
+           $ref: #/person/properties
+           salary: { type: number }
+         }
+       }
+     }
+     *  In this example, "employee" is an extended $ref, since it extends "person" with an additional
+     *  property (salary).  The result is a NEW value that looks like this:
+     *
+     *  {
+     *    properties: {
+     *      firstName: { type: string }
+     *      lastName: { type: string }
+     *      salary: { type: number }
+     *    }
+     *  }
+     *
+     * @param value - The value to inspect
+     * @returns
+     */
+    static isExtended$Ref(value) {
+        return $Ref.is$Ref(value) && Object.keys(value).length > 1;
+    }
+    /**
+     * Returns the resolved value of a JSON Reference.
+     * If necessary, the resolved value is merged with the JSON Reference to create a new object
+     *
+     * @example: {
+    person: {
+      properties: {
+        firstName: { type: string }
+        lastName: { type: string }
+      }
+    }
+    employee: {
+      properties: {
+        $ref: #/person/properties
+        salary: { type: number }
+      }
+    }
+    } When "person" and "employee" are merged, you end up with the following object:
+     *
+     *  {
+     *    properties: {
+     *      firstName: { type: string }
+     *      lastName: { type: string }
+     *      salary: { type: number }
+     *    }
+     *  }
+     *
+     * @param $ref - The JSON reference object (the one with the "$ref" property)
+     * @param resolvedValue - The resolved value, which can be any type
+     * @returns - Returns the dereferenced value
+     */
+    static dereference($ref, resolvedValue) {
+        if (resolvedValue && typeof resolvedValue === "object" && $Ref.isExtended$Ref($ref)) {
+            const merged = {};
+            for (const key of Object.keys($ref)) {
+                if (key !== "$ref") {
+                    // @ts-expect-error TS(7053): Element implicitly has an 'any' type because expre... Remove this comment to see the full error message
+                    merged[key] = $ref[key];
+                }
+            }
+            for (const key of Object.keys(resolvedValue)) {
+                if (!(key in merged)) {
+                    // @ts-expect-error TS(7053): Element implicitly has an 'any' type because expre... Remove this comment to see the full error message
+                    merged[key] = resolvedValue[key];
+                }
+            }
+            return merged;
+        }
+        else {
+            // Completely replace the original reference with the resolved value
+            return resolvedValue;
+        }
+    }
+}
+exports.default = $Ref;