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

package/dist/lib/refs.d.ts

@@ -0,0 +1,127 @@
+import $Ref from "./ref.js";
+import type { JSONSchema4Type, JSONSchema6Type, JSONSchema7Type } from "json-schema";
+import type { JSONSchema } from "./types/index.js";
+import type $RefParserOptions from "./options.js";
+interface $RefsMap {
+    [url: string]: $Ref;
+}
+/**
+ * When you call the resolve method, the value that gets passed to the callback function (or Promise) is a $Refs object. This same object is accessible via the parser.$refs property of $RefParser objects.
+ *
+ * This object is a map of JSON References and their resolved values. It also has several convenient helper methods that make it easy for you to navigate and manipulate the JSON References.
+ *
+ * See https://apitools.dev/json-schema-ref-parser/docs/refs.html
+ */
+export default class $Refs {
+    /**
+     * This property is true if the schema contains any circular references. You may want to check this property before serializing the dereferenced schema as JSON, since JSON.stringify() does not support circular references by default.
+     *
+     * See https://apitools.dev/json-schema-ref-parser/docs/refs.html#circular
+     */
+    circular: boolean;
+    /**
+     * Returns the paths/URLs of all the files in your schema (including the main schema file).
+     *
+     * See https://apitools.dev/json-schema-ref-parser/docs/refs.html#pathstypes
+     *
+     * @param types (optional) Optionally only return certain types of paths ("file", "http", etc.)
+     */
+    paths(...types: string[]): string[];
+    /**
+     * Returns a map of paths/URLs and their correspond values.
+     *
+     * See https://apitools.dev/json-schema-ref-parser/docs/refs.html#valuestypes
+     *
+     * @param types (optional) Optionally only return values from certain locations ("file", "http", etc.)
+     */
+    values(...types: string[]): JSONSchema;
+    /**
+     * Returns `true` if the given path exists in the schema; otherwise, returns `false`
+     *
+     * See https://apitools.dev/json-schema-ref-parser/docs/refs.html#existsref
+     *
+     * @param $ref The JSON Reference path, optionally with a JSON Pointer in the hash
+     */
+    /**
+     * Determines whether the given JSON reference exists.
+     *
+     * @param path - The 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 and returns the resolved value.
+     *
+     * @param path - The path being resolved, with a JSON pointer in the hash
+     * @param [options]
+     * @returns - Returns the resolved value
+     */
+    get(path: string, options?: $RefParserOptions): JSONSchema4Type | JSONSchema6Type | JSONSchema7Type;
+    /**
+     * Sets the value at the given path in the schema. If the property, or any of its parents, don't exist, they will be created.
+     *
+     * @param $ref The JSON Reference path, optionally with a JSON Pointer in the hash
+     * @param value The value to assign. Can be anything (object, string, number, etc.)
+     */
+    set(path: any, value: JSONSchema4Type | JSONSchema6Type | JSONSchema7Type): void;
+    /**
+     * Returns the specified {@link $Ref} object, or undefined.
+     *
+     * @param path - The path being resolved, optionally with a JSON pointer in the hash
+     * @returns
+     * @protected
+     */
+    _get$Ref(path: any): $Ref;
+    /**
+     * Creates a new {@link $Ref} object and adds it to this {@link $Refs} object.
+     *
+     * @param path  - The file path or URL of the referenced file
+     */
+    _add(path: string): $Ref;
+    /**
+     * Resolves the given JSON reference.
+     *
+     * @param path - The path being resolved, optionally with a JSON pointer in the hash
+     * @param pathFromRoot - The path of `obj` from the schema root
+     * @param [options]
+     * @returns
+     * @protected
+     */
+    _resolve(path: string, pathFromRoot: string, options?: any): import("./pointer.js").default | null;
+    /**
+     * A map of paths/urls to {@link $Ref} objects
+     *
+     * @type {object}
+     * @protected
+     */
+    _$refs: $RefsMap;
+    /**
+     * The {@link $Ref} object that is the root of the JSON schema.
+     *
+     * @type {$Ref}
+     * @protected
+     */
+    _root$Ref: $Ref;
+    constructor();
+    /**
+     * Returns the paths of all the files/URLs that are referenced by the JSON schema,
+     * including the schema itself.
+     *
+     * @param [types] - Only return paths of the given types ("file", "http", etc.)
+     * @returns
+     */
+    /**
+     * Returns the map of JSON references and their resolved values.
+     *
+     * @param [types] - Only return references of the given types ("file", "http", etc.)
+     * @returns
+     */
+    /**
+     * Returns a POJO (plain old JavaScript object) for serialization as JSON.
+     *
+     * @returns {object}
+     */
+    toJSON: (...types: string[]) => JSONSchema;
+}
+export {};

package/dist/lib/refs.js

@@ -0,0 +1,222 @@
+"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 ono_1 = require("@jsdevtools/ono");
+const ref_js_1 = __importDefault(require("./ref.js"));
+const url = __importStar(require("./util/url.js"));
+const convert_path_to_posix_1 = __importDefault(require("./util/convert-path-to-posix"));
+/**
+ * When you call the resolve method, the value that gets passed to the callback function (or Promise) is a $Refs object. This same object is accessible via the parser.$refs property of $RefParser objects.
+ *
+ * This object is a map of JSON References and their resolved values. It also has several convenient helper methods that make it easy for you to navigate and manipulate the JSON References.
+ *
+ * See https://apitools.dev/json-schema-ref-parser/docs/refs.html
+ */
+class $Refs {
+    /**
+     * Returns the paths/URLs of all the files in your schema (including the main schema file).
+     *
+     * See https://apitools.dev/json-schema-ref-parser/docs/refs.html#pathstypes
+     *
+     * @param types (optional) Optionally only return certain types of paths ("file", "http", etc.)
+     */
+    paths(...types) {
+        const paths = getPaths(this._$refs, types);
+        return paths.map((path) => {
+            return (0, convert_path_to_posix_1.default)(path.decoded);
+        });
+    }
+    /**
+     * Returns a map of paths/URLs and their correspond values.
+     *
+     * See https://apitools.dev/json-schema-ref-parser/docs/refs.html#valuestypes
+     *
+     * @param types (optional) Optionally only return values from certain locations ("file", "http", etc.)
+     */
+    values(...types) {
+        const $refs = this._$refs;
+        const paths = getPaths($refs, types);
+        return paths.reduce((obj, path) => {
+            obj[(0, convert_path_to_posix_1.default)(path.decoded)] = $refs[path.encoded].value;
+            return obj;
+        }, {});
+    }
+    /**
+     * Returns `true` if the given path exists in the schema; otherwise, returns `false`
+     *
+     * See https://apitools.dev/json-schema-ref-parser/docs/refs.html#existsref
+     *
+     * @param $ref The JSON Reference path, optionally with a JSON Pointer in the hash
+     */
+    /**
+     * Determines whether the given JSON reference exists.
+     *
+     * @param path - The 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 and returns the resolved value.
+     *
+     * @param path - The path being resolved, with a JSON pointer in the hash
+     * @param [options]
+     * @returns - Returns the resolved value
+     */
+    get(path, options) {
+        return this._resolve(path, "", options).value;
+    }
+    /**
+     * Sets the value at the given path in the schema. If the property, or any of its parents, don't exist, they will be created.
+     *
+     * @param $ref The JSON Reference path, optionally with a JSON Pointer in the hash
+     * @param value The value to assign. Can be anything (object, string, number, etc.)
+     */
+    set(path, value) {
+        const absPath = url.resolve(this._root$Ref.path, path);
+        const withoutHash = url.stripHash(absPath);
+        const $ref = this._$refs[withoutHash];
+        if (!$ref) {
+            throw (0, ono_1.ono)(`Error resolving $ref pointer "${path}". \n"${withoutHash}" not found.`);
+        }
+        $ref.set(absPath, value);
+    }
+    /**
+     * Returns the specified {@link $Ref} object, or undefined.
+     *
+     * @param path - The path being resolved, optionally with a JSON pointer in the hash
+     * @returns
+     * @protected
+     */
+    _get$Ref(path) {
+        path = url.resolve(this._root$Ref.path, path);
+        const withoutHash = url.stripHash(path);
+        return this._$refs[withoutHash];
+    }
+    /**
+     * Creates a new {@link $Ref} object and adds it to this {@link $Refs} object.
+     *
+     * @param path  - The file path or URL of the referenced file
+     */
+    _add(path) {
+        const withoutHash = url.stripHash(path);
+        const $ref = new ref_js_1.default(this);
+        $ref.path = withoutHash;
+        this._$refs[withoutHash] = $ref;
+        this._root$Ref = this._root$Ref || $ref;
+        return $ref;
+    }
+    /**
+     * Resolves the given JSON reference.
+     *
+     * @param path - The path being resolved, optionally with a JSON pointer in the hash
+     * @param pathFromRoot - The path of `obj` from the schema root
+     * @param [options]
+     * @returns
+     * @protected
+     */
+    _resolve(path, pathFromRoot, options) {
+        const absPath = url.resolve(this._root$Ref.path, path);
+        const withoutHash = url.stripHash(absPath);
+        const $ref = this._$refs[withoutHash];
+        if (!$ref) {
+            throw (0, ono_1.ono)(`Error resolving $ref pointer "${path}". \n"${withoutHash}" not found.`);
+        }
+        return $ref.resolve(absPath, options, path, pathFromRoot);
+    }
+    constructor() {
+        /**
+         * A map of paths/urls to {@link $Ref} objects
+         *
+         * @type {object}
+         * @protected
+         */
+        this._$refs = {};
+        /**
+         * Returns the paths of all the files/URLs that are referenced by the JSON schema,
+         * including the schema itself.
+         *
+         * @param [types] - Only return paths of the given types ("file", "http", etc.)
+         * @returns
+         */
+        /**
+         * Returns the map of JSON references and their resolved values.
+         *
+         * @param [types] - Only return references of the given types ("file", "http", etc.)
+         * @returns
+         */
+        /**
+         * Returns a POJO (plain old JavaScript object) for serialization as JSON.
+         *
+         * @returns {object}
+         */
+        this.toJSON = this.values;
+        /**
+         * Indicates whether the schema contains any circular references.
+         *
+         * @type {boolean}
+         */
+        this.circular = false;
+        this._$refs = {};
+        // @ts-ignore
+        this._root$Ref = null;
+    }
+}
+exports.default = $Refs;
+/**
+ * Returns the encoded and decoded paths keys of the given object.
+ *
+ * @param $refs - The object whose keys are URL-encoded paths
+ * @param [types] - Only return paths of the given types ("file", "http", etc.)
+ * @returns
+ */
+function getPaths($refs, types) {
+    let paths = Object.keys($refs);
+    // Filter the paths by type
+    types = Array.isArray(types[0]) ? types[0] : Array.prototype.slice.call(types);
+    if (types.length > 0 && types[0]) {
+        paths = paths.filter((key) => {
+            return types.includes($refs[key].pathType);
+        });
+    }
+    // Decode local filesystem paths
+    return paths.map((path) => {
+        return {
+            encoded: path,
+            decoded: $refs[path].pathType === "file" ? url.toFileSystemPath(path, true) : path,
+        };
+    });
+}

package/dist/lib/resolve-external.d.ts

@@ -0,0 +1,14 @@
+import type { Options } from "./options.js";
+import type $RefParser from "./index.js";
+export default resolveExternal;
+/**
+ * Crawls the JSON schema, finds all external JSON references, and resolves their values.
+ * This method does not mutate the JSON schema. The resolved values are added to {@link $RefParser#$refs}.
+ *
+ * NOTE: We only care about EXTERNAL references here. INTERNAL references are only relevant when dereferencing.
+ *
+ * @returns
+ * The promise resolves once all JSON references in the schema have been resolved,
+ * including nested references that are contained in externally-referenced files.
+ */
+declare function resolveExternal(parser: $RefParser, options: Options): Promise<void> | Promise<any[]>;

package/dist/lib/resolve-external.js

@@ -0,0 +1,133 @@
+"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 parse_js_1 = __importDefault(require("./parse.js"));
+const url = __importStar(require("./util/url.js"));
+const errors_js_1 = require("./util/errors.js");
+exports.default = resolveExternal;
+/**
+ * Crawls the JSON schema, finds all external JSON references, and resolves their values.
+ * This method does not mutate the JSON schema. The resolved values are added to {@link $RefParser#$refs}.
+ *
+ * NOTE: We only care about EXTERNAL references here. INTERNAL references are only relevant when dereferencing.
+ *
+ * @returns
+ * The promise resolves once all JSON references in the schema have been resolved,
+ * including nested references that are contained in externally-referenced files.
+ */
+function resolveExternal(parser, options) {
+    if (!options.resolve.external) {
+        // Nothing to resolve, so exit early
+        return Promise.resolve();
+    }
+    try {
+        // console.log('Resolving $ref pointers in %s', parser.$refs._root$Ref.path);
+        const promises = crawl(parser.schema, parser.$refs._root$Ref.path + "#", parser.$refs, options);
+        return Promise.all(promises);
+    }
+    catch (e) {
+        return Promise.reject(e);
+    }
+}
+/**
+ * Recursively crawls the given value, and resolves any external 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 {boolean} external - Whether `obj` was found in an external document.
+ * @param $refs
+ * @param options
+ * @param seen - Internal.
+ *
+ * @returns
+ * Returns an array of promises. There will be one promise for each JSON reference in `obj`.
+ * If `obj` does not contain any JSON references, then the array will be empty.
+ * If any of the JSON references point to files that contain additional JSON references,
+ * then the corresponding promise will internally reference an array of promises.
+ */
+function crawl(obj, path, $refs, options, seen, external) {
+    seen || (seen = new Set());
+    let promises = [];
+    if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !seen.has(obj)) {
+        seen.add(obj); // Track previously seen objects to avoid infinite recursion
+        if (ref_js_1.default.isExternal$Ref(obj)) {
+            promises.push(resolve$Ref(obj, path, $refs, options));
+        }
+        const keys = Object.keys(obj);
+        for (const key of keys) {
+            const keyPath = pointer_js_1.default.join(path, key);
+            const value = obj[key];
+            promises = promises.concat(crawl(value, keyPath, $refs, options, seen, external));
+        }
+    }
+    return promises;
+}
+/**
+ * Resolves 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 $refs
+ * @param options
+ *
+ * @returns
+ * The promise resolves once all JSON references in the object have been resolved,
+ * including nested references that are contained in externally-referenced files.
+ */
+async function resolve$Ref($ref, path, $refs, options) {
+    // console.log('Resolving $ref pointer "%s" at %s', $ref.$ref, path);
+    const resolvedPath = url.resolve(path, $ref.$ref);
+    const withoutHash = url.stripHash(resolvedPath);
+    // $ref.$ref = url.relative($refs._root$Ref.path, resolvedPath);
+    // Do we already have this $ref?
+    $ref = $refs._$refs[withoutHash];
+    if ($ref) {
+        // We've already parsed this $ref, so use the existing value
+        return Promise.resolve($ref.value);
+    }
+    // Parse the $referenced file/url
+    try {
+        const result = await (0, parse_js_1.default)(resolvedPath, $refs, options);
+        // Crawl the parsed value
+        // console.log('Resolving $ref pointers in %s', withoutHash);
+        const promises = crawl(result, withoutHash + "#", $refs, options, new Set(), true);
+        return Promise.all(promises);
+    }
+    catch (err) {
+        if (!options?.continueOnError || !(0, errors_js_1.isHandledError)(err)) {
+            throw err;
+        }
+        if ($refs._$refs[withoutHash]) {
+            err.source = decodeURI(url.stripHash(path));
+            err.path = url.safePointerToPath(url.getHash(path));
+        }
+        return [];
+    }
+}

package/dist/lib/resolvers/file.d.ts

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

package/dist/lib/resolvers/file.js

@@ -0,0 +1,62 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const ono_1 = require("@jsdevtools/ono");
+const url = __importStar(require("../util/url.js"));
+const errors_js_1 = require("../util/errors.js");
+exports.default = {
+    /**
+     * The order that this resolver will run, in relation to other resolvers.
+     */
+    order: 100,
+    /**
+     * Determines whether this resolver can read a given file reference.
+     * Resolvers that return true will be tried, in order, until one successfully resolves the file.
+     * Resolvers that return false will not be given a chance to resolve the file.
+     */
+    canRead(file) {
+        return url.isFileSystemPath(file.url);
+    },
+    /**
+     * Reads the given file and returns its raw contents as a Buffer.
+     */
+    async read(file) {
+        let path;
+        try {
+            path = url.toFileSystemPath(file.url);
+        }
+        catch (err) {
+            throw new errors_js_1.ResolverError(ono_1.ono.uri(err, `Malformed URI: ${file.url}`), file.url);
+        }
+        try {
+            const data = await fs_1.promises.readFile(path);
+            return data;
+        }
+        catch (err) {
+            throw new errors_js_1.ResolverError((0, ono_1.ono)(err, `Error opening file "${path}"`), path);
+        }
+    },
+};

package/dist/lib/resolvers/http.d.ts

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