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

package/lib/ref.ts

@@ -0,0 +1,288 @@
+import Pointer from "./pointer.js";
+import type { JSONParserError, MissingPointerError, ParserError, ResolverError } from "./util/errors.js";
+import { InvalidPointerError, isHandledError, normalizeError } from "./util/errors.js";
+import { safePointerToPath, stripHash, getHash } from "./util/url.js";
+import type $Refs from "./refs.js";
+import type $RefParserOptions from "./options.js";
+import type { JSONSchema } from "./types";
+
+type $RefError = JSONParserError | ResolverError | ParserError | MissingPointerError;
+
+/**
+ * This class represents a single JSON reference and its resolved value.
+ *
+ * @class
+ */
+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) {
+    this.$refs = $refs;
+  }
+
+  /**
+   * Pushes an error to errors array.
+   *
+   * @param err - The error to be pushed
+   * @returns
+   */
+  addError(err: $RefError) {
+    if (this.errors === undefined) {
+      this.errors = [];
+    }
+
+    const existingErrors = this.errors.map(({ footprint }: any) => 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(normalizeError).filter(({ footprint }: any) => !existingErrors.includes(footprint)),
+      );
+    } else if (!("footprint" in err) || !existingErrors.includes(err.footprint)) {
+      this.errors.push(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: string, options: any) {
+    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: any, options: any) {
+    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: any, options?: $RefParserOptions, friendlyPath?: string, pathFromRoot?: string) {
+    const pointer = new Pointer(this, path, friendlyPath);
+    try {
+      return pointer.resolve(this.value, options, pathFromRoot);
+    } catch (err: any) {
+      if (!options || !options.continueOnError || !isHandledError(err)) {
+        throw err;
+      }
+
+      if (err.path === null) {
+        err.path = safePointerToPath(getHash(pathFromRoot));
+      }
+
+      if (err instanceof InvalidPointerError) {
+        err.source = decodeURI(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: any, value: any) {
+    // @ts-expect-error TS(2554): Expected 3 arguments, but got 2.
+    const pointer = new Pointer(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: any): value is { $ref: string; length?: number } {
+    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: any): value is JSONSchema {
+    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: any, options: any) {
+    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: any) {
+    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: $Ref, resolvedValue: any) {
+    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;
+    }
+  }
+}
+
+export default $Ref;

package/lib/refs.ts

@@ -0,0 +1,238 @@
+import { ono } from "@jsdevtools/ono";
+import $Ref from "./ref.js";
+import * as url from "./util/url.js";
+import type { JSONSchema4Type, JSONSchema6Type, JSONSchema7Type } from "json-schema";
+import type { JSONSchema } from "./types/index.js";
+import type $RefParserOptions from "./options.js";
+
+const isWindows = /^win/.test(globalThis.process ? globalThis.process.platform : "");
+const getPathFromOs = (filePath: string): string => (isWindows ? filePath.replace(/\\/g, "/") : filePath);
+
+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
+   */
+  public 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[] {
+    const paths = getPaths(this._$refs, types);
+    return paths.map((path) => {
+      return getPathFromOs(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: string[]): JSONSchema {
+    const $refs = this._$refs;
+    const paths = getPaths($refs, types);
+    return paths.reduce<Record<string, any>>((obj, path) => {
+      obj[getPathFromOs(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: string, options: any) {
+    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: string, options?: $RefParserOptions): JSONSchema4Type | JSONSchema6Type | JSONSchema7Type {
+    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: any, value: JSONSchema4Type | JSONSchema6Type | JSONSchema7Type) {
+    const absPath = url.resolve(this._root$Ref.path, path);
+    const withoutHash = url.stripHash(absPath);
+    const $ref = this._$refs[withoutHash];
+
+    if (!$ref) {
+      throw 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: any) {
+    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: string) {
+    const withoutHash = url.stripHash(path);
+
+    const $ref = new $Ref(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: string, pathFromRoot: string, options?: any) {
+    const absPath = url.resolve(this._root$Ref.path, path);
+    const withoutHash = url.stripHash(absPath);
+    const $ref = this._$refs[withoutHash];
+
+    if (!$ref) {
+      throw ono(`Error resolving $ref pointer "${path}". \n"${withoutHash}" not found.`);
+    }
+
+    return $ref.resolve(absPath, options, path, pathFromRoot);
+  }
+
+  /**
+   * 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() {
+    /**
+     * Indicates whether the schema contains any circular references.
+     *
+     * @type {boolean}
+     */
+    this.circular = false;
+
+    this._$refs = {};
+
+    // @ts-ignore
+    this._root$Ref = null;
+  }
+
+  /**
+   * 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 = this.values;
+}
+
+/**
+ * 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: $RefsMap, types: string[]) {
+  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 as string);
+    });
+  }
+
+  // Decode local filesystem paths
+  return paths.map((path) => {
+    return {
+      encoded: path,
+      decoded: $refs[path].pathType === "file" ? url.toFileSystemPath(path, true) : path,
+    };
+  });
+}

package/lib/{resolve-external.js → resolve-external.ts}

@@ -3,6 +3,10 @@ import Pointer from "./pointer.js";
 import parse from "./parse.js";
 import * as url from "./util/url.js";
 import { isHandledError } from "./util/errors.js";
+import type $Refs from "./refs.js";
+import type { Options } from "./options.js";
+import type { JSONSchema } from "./types/index.js";
+import type $RefParser from "./index.js";
 
 export default resolveExternal;
 
@@ -12,14 +16,11 @@ export default resolveExternal;
  *
  * NOTE: We only care about EXTERNAL references here. INTERNAL references are only relevant when dereferencing.
  *
- * @param {$RefParser} parser
- * @param {$RefParserOptions} options
- *
- * @returns {Promise}
+ * @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) {
+function resolveExternal(parser: $RefParser, options: Options) {
   if (!options.resolve.external) {
     // Nothing to resolve, so exit early
     return Promise.resolve();
@@ -27,10 +28,9 @@ function resolveExternal (parser, options) {
 
   try {
     // console.log('Resolving $ref pointers in %s', parser.$refs._root$Ref.path);
-    let promises = crawl(parser.schema, parser.$refs._root$Ref.path + "#", parser.$refs, options);
+    const promises = crawl(parser.schema, parser.$refs._root$Ref.path + "#", parser.$refs, options);
     return Promise.all(promises);
-  }
-  catch (e) {
+  } catch (e) {
     return Promise.reject(e);
   }
 }
@@ -38,36 +38,40 @@ function resolveExternal (parser, options) {
 /**
  * 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 {string} path - The full path of `obj`, possibly with a JSON Pointer in the hash
- * @param {$Refs} $refs
- * @param {$RefParserOptions} options
- * @param {Set} seen - Internal.
+ * @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 $refs
+ * @param options
+ * @param seen - Internal.
  *
- * @returns {Promise[]}
+ * @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) {
-  seen = seen || new Set();
-  let promises = [];
+function crawl(
+  obj: string | Buffer | JSONSchema | undefined | null,
+  path: string,
+  $refs: $Refs,
+  options: Options,
+  seen?: Set<any>,
+) {
+  seen ||= new Set();
+  let promises: any = [];
 
   if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !seen.has(obj)) {
     seen.add(obj); // Track previously seen objects to avoid infinite recursion
     if ($Ref.isExternal$Ref(obj)) {
       promises.push(resolve$Ref(obj, path, $refs, options));
-    }
-    else {
-      for (let key of Object.keys(obj)) {
-        let keyPath = Pointer.join(path, key);
-        let value = obj[key];
+    } else {
+      for (const key of Object.keys(obj)) {
+        const keyPath = Pointer.join(path, key);
+        const value = obj[key] as string | JSONSchema | Buffer | undefined;
 
         if ($Ref.isExternal$Ref(value)) {
           promises.push(resolve$Ref(value, keyPath, $refs, options));
-        }
-        else {
+        } else {
           promises = promises.concat(crawl(value, keyPath, $refs, options, seen));
         }
       }
@@ -80,20 +84,20 @@ function crawl (obj, path, $refs, options, seen) {
 /**
  * Resolves the given JSON Reference, and then crawls the resulting value.
  *
- * @param {{$ref: string}} $ref - The JSON Reference to resolve
- * @param {string} path - The full path of `$ref`, possibly with a JSON Pointer in the hash
- * @param {$Refs} $refs
- * @param {$RefParserOptions} options
+ * @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 {Promise}
+ * @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) {
+async function resolve$Ref($ref: JSONSchema, path: string, $refs: $Refs, options: Options) {
   // console.log('Resolving $ref pointer "%s" at %s', $ref.$ref, path);
 
-  let resolvedPath = url.resolve(path, $ref.$ref);
-  let withoutHash = url.stripHash(resolvedPath);
+  const resolvedPath = url.resolve(path, $ref.$ref);
+  const withoutHash = url.stripHash(resolvedPath);
 
   // Do we already have this $ref?
   $ref = $refs._$refs[withoutHash];
@@ -108,12 +112,11 @@ async function resolve$Ref ($ref, path, $refs, options) {
 
     // Crawl the parsed value
     // console.log('Resolving $ref pointers in %s', withoutHash);
-    let promises = crawl(result, withoutHash + "#", $refs, options);
+    const promises = crawl(result, withoutHash + "#", $refs, options);
 
     return Promise.all(promises);
-  }
-  catch (err) {
-    if (!options.continueOnError || !isHandledError(err)) {
+  } catch (err) {
+    if (!options?.continueOnError || !isHandledError(err)) {
       throw err;
     }