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

package/dist/lib/options.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNewOptions = void 0;
+const json_js_1 = __importDefault(require("./parsers/json.js"));
+const yaml_js_1 = __importDefault(require("./parsers/yaml.js"));
+const text_js_1 = __importDefault(require("./parsers/text.js"));
+const binary_js_1 = __importDefault(require("./parsers/binary.js"));
+const file_js_1 = __importDefault(require("./resolvers/file.js"));
+const http_js_1 = __importDefault(require("./resolvers/http.js"));
+const lodash_clonedeep_1 = __importDefault(require("lodash.clonedeep"));
+const getDefaults = () => {
+    const defaults = {
+        /**
+         * Determines how different types of files will be parsed.
+         *
+         * You can add additional parsers of your own, replace an existing one with
+         * your own implementation, or disable any parser by setting it to false.
+         */
+        parse: {
+            json: json_js_1.default,
+            yaml: yaml_js_1.default,
+            text: text_js_1.default,
+            binary: binary_js_1.default,
+        },
+        /**
+         * Determines how JSON References will be resolved.
+         *
+         * You can add additional resolvers of your own, replace an existing one with
+         * your own implementation, or disable any resolver by setting it to false.
+         */
+        resolve: {
+            file: file_js_1.default,
+            http: http_js_1.default,
+            /**
+             * Determines whether external $ref pointers will be resolved.
+             * If this option is disabled, then none of above resolvers will be called.
+             * Instead, external $ref pointers will simply be ignored.
+             *
+             * @type {boolean}
+             */
+            external: true,
+        },
+        /**
+         * By default, JSON Schema $Ref Parser throws the first error it encounters. Setting `continueOnError` to `true`
+         * causes it to keep processing as much as possible and then throw a single error that contains all errors
+         * that were encountered.
+         */
+        continueOnError: false,
+        /**
+         * Determines the types of JSON references that are allowed.
+         */
+        dereference: {
+            /**
+             * Dereference circular (recursive) JSON references?
+             * If false, then a {@link ReferenceError} will be thrown if a circular reference is found.
+             * If "ignore", then circular references will not be dereferenced.
+             *
+             * @type {boolean|string}
+             */
+            circular: true,
+            /**
+             * A function, called for each path, which can return true to stop this path and all
+             * subpaths from being dereferenced further. This is useful in schemas where some
+             * subpaths contain literal $ref keys that should not be dereferenced.
+             *
+             * @type {function}
+             */
+            excludedPathMatcher: () => false,
+        },
+    };
+    return (0, lodash_clonedeep_1.default)(defaults);
+};
+const getNewOptions = (options) => {
+    const newOptions = getDefaults();
+    if (options) {
+        merge(newOptions, options);
+    }
+    return newOptions;
+};
+exports.getNewOptions = getNewOptions;
+/**
+ * Merges the properties of the source object into the target object.
+ *
+ * @param target - The object that we're populating
+ * @param source - The options that are being merged
+ * @returns
+ */
+function merge(target, source) {
+    if (isMergeable(source)) {
+        const keys = Object.keys(source);
+        for (let i = 0; i < keys.length; i++) {
+            const key = keys[i];
+            const sourceSetting = source[key];
+            const targetSetting = target[key];
+            if (isMergeable(sourceSetting)) {
+                // It's a nested object, so merge it recursively
+                target[key] = merge(targetSetting || {}, sourceSetting);
+            }
+            else if (sourceSetting !== undefined) {
+                // It's a scalar value, function, or array. No merging necessary. Just overwrite the target value.
+                target[key] = sourceSetting;
+            }
+        }
+    }
+    return target;
+}
+/**
+ * Determines whether the given value can be merged,
+ * or if it is a scalar value that should just override the target value.
+ *
+ * @param val
+ * @returns
+ */
+function isMergeable(val) {
+    return val && typeof val === "object" && !Array.isArray(val) && !(val instanceof RegExp) && !(val instanceof Date);
+}

package/dist/lib/parse.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="node" />
+import type $Refs from "./refs.js";
+import type { Options } from "./options.js";
+export default parse;
+/**
+ * Reads and parses the specified file path or URL.
+ */
+declare function parse(path: string, $refs: $Refs, options: Options): Promise<string | import("./types/index.js").JSONSchema | Buffer | undefined>;

package/dist/lib/parse.js

@@ -0,0 +1,177 @@
+"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 __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ono_1 = require("@jsdevtools/ono");
+const url = __importStar(require("./util/url.js"));
+const plugins = __importStar(require("./util/plugins.js"));
+const errors_js_1 = require("./util/errors.js");
+exports.default = parse;
+/**
+ * Reads and parses the specified file path or URL.
+ */
+function parse(path, $refs, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Remove the URL fragment, if any
+        path = url.stripHash(path);
+        // Add a new $Ref for this file, even though we don't have the value yet.
+        // This ensures that we don't simultaneously read & parse the same file multiple times
+        const $ref = $refs._add(path);
+        // This "file object" will be passed to all resolvers and parsers.
+        const file = {
+            url: path,
+            extension: url.getExtension(path),
+        };
+        // Read the file and then parse the data
+        try {
+            const resolver = yield readFile(file, options, $refs);
+            $ref.pathType = resolver.plugin.name;
+            file.data = resolver.result;
+            const parser = yield parseFile(file, options, $refs);
+            $ref.value = parser.result;
+            return parser.result;
+        }
+        catch (err) {
+            if ((0, errors_js_1.isHandledError)(err)) {
+                $ref.value = err;
+            }
+            throw err;
+        }
+    });
+}
+/**
+ * Reads the given file, using the configured resolver plugins
+ *
+ * @param file           - An object containing information about the referenced file
+ * @param file.url       - The full URL of the referenced file
+ * @param file.extension - The lowercased file extension (e.g. ".txt", ".html", etc.)
+ * @param options
+ *
+ * @returns
+ * The promise resolves with the raw file contents and the resolver that was used.
+ */
+function readFile(file, options, $refs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // console.log('Reading %s', file.url);
+        // Find the resolvers that can read this file
+        let resolvers = plugins.all(options.resolve);
+        resolvers = plugins.filter(resolvers, "canRead", file);
+        // Run the resolvers, in order, until one of them succeeds
+        plugins.sort(resolvers);
+        try {
+            const data = yield plugins.run(resolvers, "read", file, $refs);
+            return data;
+        }
+        catch (err) {
+            if (!err && options.continueOnError) {
+                // No resolver could be matched
+                throw new errors_js_1.UnmatchedResolverError(file.url);
+            }
+            else if (!err || !("error" in err)) {
+                // Throw a generic, friendly error.
+                throw ono_1.ono.syntax(`Unable to resolve $ref pointer "${file.url}"`);
+            }
+            // Throw the original error, if it's one of our own (user-friendly) errors.
+            else if (err.error instanceof errors_js_1.ResolverError) {
+                throw err.error;
+            }
+            else {
+                throw new errors_js_1.ResolverError(err, file.url);
+            }
+        }
+    });
+}
+/**
+ * Parses the given file's contents, using the configured parser plugins.
+ *
+ * @param file           - An object containing information about the referenced file
+ * @param file.url       - The full URL of the referenced file
+ * @param file.extension - The lowercased file extension (e.g. ".txt", ".html", etc.)
+ * @param file.data      - The file contents. This will be whatever data type was returned by the resolver
+ * @param options
+ *
+ * @returns
+ * The promise resolves with the parsed file contents and the parser that was used.
+ */
+function parseFile(file, options, $refs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // console.log('Parsing %s', file.url);
+        // Find the parsers that can read this file type.
+        // If none of the parsers are an exact match for this file, then we'll try ALL of them.
+        // This handles situations where the file IS a supported type, just with an unknown extension.
+        const allParsers = plugins.all(options.parse);
+        const filteredParsers = plugins.filter(allParsers, "canParse", file);
+        const parsers = filteredParsers.length > 0 ? filteredParsers : allParsers;
+        // Run the parsers, in order, until one of them succeeds
+        plugins.sort(parsers);
+        try {
+            const parser = yield plugins.run(parsers, "parse", file, $refs);
+            if (!parser.plugin.allowEmpty && isEmpty(parser.result)) {
+                throw ono_1.ono.syntax(`Error parsing "${file.url}" as ${parser.plugin.name}. \nParsed value is empty`);
+            }
+            else {
+                return parser;
+            }
+        }
+        catch (err) {
+            if (!err && options.continueOnError) {
+                // No resolver could be matched
+                throw new errors_js_1.UnmatchedParserError(file.url);
+            }
+            else if (err && err.message && err.message.startsWith("Error parsing")) {
+                throw err;
+            }
+            else if (!err || !("error" in err)) {
+                throw ono_1.ono.syntax(`Unable to parse ${file.url}`);
+            }
+            else if (err.error instanceof errors_js_1.ParserError) {
+                throw err.error;
+            }
+            else {
+                throw new errors_js_1.ParserError(err.error.message, file.url);
+            }
+        }
+    });
+}
+/**
+ * Determines whether the parsed value is "empty".
+ *
+ * @param value
+ * @returns
+ */
+function isEmpty(value) {
+    return (value === undefined ||
+        (typeof value === "object" && Object.keys(value).length === 0) ||
+        (typeof value === "string" && value.trim().length === 0) ||
+        (Buffer.isBuffer(value) && value.length === 0));
+}

package/dist/lib/parsers/binary.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "../types/index.js";
+declare const _default: Plugin;
+export default _default;

package/dist/lib/parsers/binary.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const BINARY_REGEXP = /\.(jpeg|jpg|gif|png|bmp|ico)$/i;
+exports.default = {
+    /**
+     * The order that this parser will run, in relation to other parsers.
+     */
+    order: 400,
+    /**
+     * Whether to allow "empty" files (zero bytes).
+     */
+    allowEmpty: true,
+    /**
+     * Determines whether this parser can parse a given file reference.
+     * Parsers that return true will be tried, in order, until one successfully parses the file.
+     * Parsers that return false will be skipped, UNLESS all parsers returned false, in which case
+     * every parser will be tried.
+     */
+    canParse(file) {
+        // Use this parser if the file is a Buffer, and has a known binary extension
+        return Buffer.isBuffer(file.data) && BINARY_REGEXP.test(file.url);
+    },
+    /**
+     * Parses the given data as a Buffer (byte array).
+     */
+    parse(file) {
+        if (Buffer.isBuffer(file.data)) {
+            return file.data;
+        }
+        else {
+            // This will reject if data is anything other than a string or typed array
+            return Buffer.from(file.data);
+        }
+    },
+};

package/dist/lib/parsers/json.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "../types/index.js";
+declare const _default: Plugin;
+export default _default;

package/dist/lib/parsers/json.js

@@ -0,0 +1,57 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const errors_js_1 = require("../util/errors.js");
+exports.default = {
+    /**
+     * The order that this parser will run, in relation to other parsers.
+     */
+    order: 100,
+    /**
+     * Whether to allow "empty" files. This includes zero-byte files, as well as empty JSON objects.
+     */
+    allowEmpty: true,
+    /**
+     * Determines whether this parser can parse a given file reference.
+     * Parsers that match will be tried, in order, until one successfully parses the file.
+     * Parsers that don't match will be skipped, UNLESS none of the parsers match, in which case
+     * every parser will be tried.
+     */
+    canParse: ".json",
+    /**
+     * Parses the given file as JSON
+     */
+    parse(file) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let data = file.data;
+            if (Buffer.isBuffer(data)) {
+                data = data.toString();
+            }
+            if (typeof data === "string") {
+                if (data.trim().length === 0) {
+                    return; // This mirrors the YAML behavior
+                }
+                else {
+                    try {
+                        return JSON.parse(data);
+                    }
+                    catch (e) {
+                        throw new errors_js_1.ParserError(e.message, file.url);
+                    }
+                }
+            }
+            else {
+                // data is already a JavaScript value (object, array, number, null, NaN, etc.)
+                return data;
+            }
+        });
+    },
+};

package/dist/lib/parsers/text.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "../types/index.js";
+declare const _default: Plugin;
+export default _default;

package/dist/lib/parsers/text.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const errors_js_1 = require("../util/errors.js");
+const TEXT_REGEXP = /\.(txt|htm|html|md|xml|js|min|map|css|scss|less|svg)$/i;
+exports.default = {
+    /**
+     * The order that this parser will run, in relation to other parsers.
+     */
+    order: 300,
+    /**
+     * Whether to allow "empty" files (zero bytes).
+     */
+    allowEmpty: true,
+    /**
+     * The encoding that the text is expected to be in.
+     */
+    encoding: "utf8",
+    /**
+     * Determines whether this parser can parse a given file reference.
+     * Parsers that return true will be tried, in order, until one successfully parses the file.
+     * Parsers that return false will be skipped, UNLESS all parsers returned false, in which case
+     * every parser will be tried.
+     */
+    canParse(file) {
+        // Use this parser if the file is a string or Buffer, and has a known text-based extension
+        return (typeof file.data === "string" || Buffer.isBuffer(file.data)) && TEXT_REGEXP.test(file.url);
+    },
+    /**
+     * Parses the given file as text
+     */
+    parse(file) {
+        if (typeof file.data === "string") {
+            return file.data;
+        }
+        else if (Buffer.isBuffer(file.data)) {
+            return file.data.toString(this.encoding);
+        }
+        else {
+            throw new errors_js_1.ParserError("data is not text", file.url);
+        }
+    },
+};

package/dist/lib/parsers/yaml.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "../types/index.js";
+declare const _default: Plugin;
+export default _default;

package/dist/lib/parsers/yaml.js

@@ -0,0 +1,65 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const errors_js_1 = require("../util/errors.js");
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const js_yaml_2 = require("js-yaml");
+exports.default = {
+    /**
+     * The order that this parser will run, in relation to other parsers.
+     */
+    order: 200,
+    /**
+     * Whether to allow "empty" files. This includes zero-byte files, as well as empty JSON objects.
+     */
+    allowEmpty: true,
+    /**
+     * Determines whether this parser can parse a given file reference.
+     * Parsers that match will be tried, in order, until one successfully parses the file.
+     * Parsers that don't match will be skipped, UNLESS none of the parsers match, in which case
+     * every parser will be tried.
+     */
+    canParse: [".yaml", ".yml", ".json"],
+    /**
+     * Parses the given file as YAML
+     *
+     * @param file           - An object containing information about the referenced file
+     * @param file.url       - The full URL of the referenced file
+     * @param file.extension - The lowercased file extension (e.g. ".txt", ".html", etc.)
+     * @param file.data      - The file contents. This will be whatever data type was returned by the resolver
+     * @returns
+     */
+    parse(file) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // eslint-disable-line require-await
+            let data = file.data;
+            if (Buffer.isBuffer(data)) {
+                data = data.toString();
+            }
+            if (typeof data === "string") {
+                try {
+                    return js_yaml_1.default.load(data, { schema: js_yaml_2.JSON_SCHEMA });
+                }
+                catch (e) {
+                    // @ts-expect-error TS(2571): Object is of type 'unknown'.
+                    throw new errors_js_1.ParserError(e.message, file.url);
+                }
+            }
+            else {
+                // data is already a JavaScript value (object, array, number, null, NaN, etc.)
+                return data;
+            }
+        });
+    },
+};

package/dist/lib/pointer.d.ts

@@ -0,0 +1,87 @@
+import type $RefParserOptions from "./options.js";
+import $Ref from "./ref.js";
+/**
+ * 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
+ */
+declare class Pointer {
+    /**
+     * The {@link $Ref} object that contains this {@link Pointer} object.
+     */
+    $ref: $Ref;
+    /**
+     * The file path or URL, containing the JSON pointer in the hash.
+     * This path is relative to the path of the main JSON schema file.
+     */
+    path: string;
+    /**
+     * The original path or URL, used for error messages.
+     */
+    originalPath: string;
+    /**
+     * The value of the JSON pointer.
+     * Can be any JSON type, not just objects. Unknown file types are represented as Buffers (byte arrays).
+     */
+    value: any;
+    /**
+     * Indicates whether the pointer references itself.
+     */
+    circular: boolean;
+    /**
+     * The number of indirect references that were traversed to resolve the value.
+     * Resolving a single pointer may require resolving multiple $Refs.
+     */
+    indirections: number;
+    constructor($ref: any, path: any, friendlyPath: any);
+    /**
+     * 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: any, options: any, pathFromRoot: any): 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: any, value: any, options?: $RefParserOptions): any;
+    /**
+     * 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: string, originalPath?: string): any;
+    /**
+     * 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: any, tokens: any): any;
+}
+export default Pointer;