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

package/lib/resolvers/file.ts

@@ -0,0 +1,40 @@
+import fs from "fs/promises";
+import { ono } from "@jsdevtools/ono";
+import * as url from "../util/url.js";
+import { ResolverError } from "../util/errors.js";
+import type { ResolverOptions } from "../types/index.js";
+import type { FileInfo } from "../types/index.js";
+
+export 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: FileInfo) {
+    return url.isFileSystemPath(file.url);
+  },
+
+  /**
+   * Reads the given file and returns its raw contents as a Buffer.
+   */
+  async read(file: FileInfo): Promise<Buffer> {
+    let path: string | undefined;
+    try {
+      path = url.toFileSystemPath(file.url);
+    } catch (err: any) {
+      throw new ResolverError(ono.uri(err, `Malformed URI: ${file.url}`), file.url);
+    }
+    try {
+      const data = await fs.readFile(path);
+      return data;
+    } catch (err: any) {
+      throw new ResolverError(ono(err, `Error opening file "${path}"`), path);
+    }
+  },
+} as ResolverOptions;

package/lib/resolvers/http.ts

@@ -0,0 +1,136 @@
+import { ono } from "@jsdevtools/ono";
+import * as url from "../util/url.js";
+import { ResolverError } from "../util/errors.js";
+import type { FileInfo, HTTPResolverOptions } from "../types/index.js";
+
+export default {
+  /**
+   * The order that this resolver will run, in relation to other resolvers.
+   */
+  order: 200,
+
+  /**
+   * HTTP headers to send when downloading files.
+   *
+   * @example:
+   * {
+   *   "User-Agent": "JSON Schema $Ref Parser",
+   *   Accept: "application/json"
+   * }
+   */
+  headers: null,
+
+  /**
+   * HTTP request timeout (in milliseconds).
+   */
+  timeout: 5000, // 5 seconds
+
+  /**
+   * The maximum number of HTTP redirects to follow.
+   * To disable automatic following of redirects, set this to zero.
+   */
+  redirects: 5,
+
+  /**
+   * The `withCredentials` option of XMLHttpRequest.
+   * Set this to `true` if you're downloading files from a CORS-enabled server that requires authentication
+   */
+  withCredentials: false,
+
+  /**
+   * 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: FileInfo) {
+    return url.isHttp(file.url);
+  },
+
+  /**
+   * Reads the given URL and returns its raw contents as a Buffer.
+   */
+  read(file: FileInfo) {
+    const u = url.parse(file.url);
+
+    if (typeof window !== "undefined" && !u.protocol) {
+      // Use the protocol of the current page
+      u.protocol = url.parse(location.href).protocol;
+    }
+
+    return download(u, this);
+  },
+} as HTTPResolverOptions;
+
+/**
+ * Downloads the given file.
+ * @returns
+ * The promise resolves with the raw downloaded data, or rejects if there is an HTTP error.
+ */
+async function download(u: URL | string, httpOptions: HTTPResolverOptions, _redirects?: string[]): Promise<Buffer> {
+  u = url.parse(u);
+  const redirects = _redirects || [];
+  redirects.push(u.href);
+
+  try {
+    const res = await get(u, httpOptions);
+    if (res.status >= 400) {
+      throw ono({ status: res.status }, `HTTP ERROR ${res.status}`);
+    } else if (res.status >= 300) {
+      if (!Number.isNaN(httpOptions.redirects) && redirects.length > httpOptions.redirects!) {
+        throw new ResolverError(
+          ono(
+            { status: res.status },
+            `Error downloading ${redirects[0]}. \nToo many redirects: \n  ${redirects.join(" \n  ")}`,
+          ),
+        );
+      } else if (!("location" in res.headers) || !res.headers.location) {
+        throw ono({ status: res.status }, `HTTP ${res.status} redirect with no location header`);
+      } else {
+        const redirectTo = url.resolve(u, res.headers.location);
+        return download(redirectTo, httpOptions, redirects);
+      }
+    } else {
+      if (res.body) {
+        const buf = await res.arrayBuffer();
+        return Buffer.from(buf);
+      }
+      return Buffer.alloc(0);
+    }
+  } catch (err: any) {
+    throw new ResolverError(ono(err, `Error downloading ${u.href}`), u.href);
+  }
+}
+
+/**
+ * Sends an HTTP GET request.
+ * The promise resolves with the HTTP Response object.
+ */
+async function get(u: RequestInfo | URL, httpOptions: HTTPResolverOptions) {
+  let controller: any;
+  let timeoutId: any;
+  if (httpOptions.timeout) {
+    controller = new AbortController();
+    timeoutId = setTimeout(() => controller.abort(), httpOptions.timeout);
+  }
+
+  if (!global.fetch) {
+    const { default: fetch, Request, Headers } = await import("node-fetch");
+    // @ts-ignore
+    global.fetch = fetch;
+    // @ts-ignore
+    global.Request = Request;
+    // @ts-ignore
+    global.Headers = Headers;
+  }
+  const response = await fetch(u, {
+    method: "GET",
+    headers: httpOptions.headers || {},
+    credentials: httpOptions.withCredentials ? "include" : "same-origin",
+    signal: controller ? controller.signal : null,
+  });
+  if (timeoutId) {
+    clearTimeout(timeoutId);
+  }
+
+  return response;
+}

package/lib/tsconfig.json

@@ -0,0 +1,103 @@
+{
+  "compilerOptions": {
+    /* Visit https://aka.ms/tsconfig to read more about this file */
+
+    /* Projects */
+    // "incremental": true,                              /* Save .tsbuildinfo files to allow for incremental compilation of projects. */
+    // "composite": true,                                /* Enable constraints that allow a TypeScript project to be used with project references. */
+    // "tsBuildInfoFile": "./.tsbuildinfo",              /* Specify the path to .tsbuildinfo incremental compilation file. */
+    // "disableSourceOfProjectReferenceRedirect": true,  /* Disable preferring source files instead of declaration files when referencing composite projects. */
+    // "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
+    // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
+
+    /* Language and Environment */
+    "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+    // "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
+    // "jsx": "preserve",                                /* Specify what JSX code is generated. */
+    // "experimentalDecorators": true,                   /* Enable experimental support for TC39 stage 2 draft decorators. */
+    // "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
+    // "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
+    // "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
+    // "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
+    // "reactNamespace": "",                             /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
+    // "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
+    // "useDefineForClassFields": true,                  /* Emit ECMAScript-standard-compliant class fields. */
+    // "moduleDetection": "auto",                        /* Control what method is used to detect module-format JS files. */
+
+    /* Modules */
+    "module": "commonjs",                                /* Specify what module code is generated. */
+    // "rootDir": "./",                                  /* Specify the root folder within your source files. */
+    // "moduleResolution": "node",                       /* Specify how TypeScript looks up a file from a given module specifier. */
+    // "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
+    // "paths": {},                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
+    // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
+    // "typeRoots": [],                                  /* Specify multiple folders that act like './node_modules/@types'. */
+    // "types": [],                                      /* Specify type package names to be included without being referenced in a source file. */
+    // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
+    // "moduleSuffixes": [],                             /* List of file name suffixes to search when resolving a module. */
+    // "resolveJsonModule": true,                        /* Enable importing .json files. */
+    // "noResolve": true,                                /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
+
+    /* JavaScript Support */
+    // "allowJs": true,                                  /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
+    // "checkJs": true,                                  /* Enable error reporting in type-checked JavaScript files. */
+    // "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
+
+    /* Emit */
+    // "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+    // "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
+    // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
+    // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
+    // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
+    // "outDir": "./",                                   /* Specify an output folder for all emitted files. */
+    // "removeComments": true,                           /* Disable emitting comments. */
+    // "noEmit": true,                                   /* Disable emitting files from a compilation. */
+    // "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
+    // "importsNotUsedAsValues": "remove",               /* Specify emit/checking behavior for imports that are only used for types. */
+    // "downlevelIteration": true,                       /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
+    // "sourceRoot": "",                                 /* Specify the root path for debuggers to find the reference source code. */
+    // "mapRoot": "",                                    /* Specify the location where debugger should locate map files instead of generated locations. */
+    // "inlineSourceMap": true,                          /* Include sourcemap files inside the emitted JavaScript. */
+    // "inlineSources": true,                            /* Include source code in the sourcemaps inside the emitted JavaScript. */
+    // "emitBOM": true,                                  /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
+    // "newLine": "crlf",                                /* Set the newline character for emitting files. */
+    // "stripInternal": true,                            /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
+    // "noEmitHelpers": true,                            /* Disable generating custom helper functions like '__extends' in compiled output. */
+    // "noEmitOnError": true,                            /* Disable emitting files if any type checking errors are reported. */
+    // "preserveConstEnums": true,                       /* Disable erasing 'const enum' declarations in generated code. */
+    // "declarationDir": "./",                           /* Specify the output directory for generated declaration files. */
+    // "preserveValueImports": true,                     /* Preserve unused imported values in the JavaScript output that would otherwise be removed. */
+
+    /* Interop Constraints */
+    // "isolatedModules": true,                          /* Ensure that each file can be safely transpiled without relying on other imports. */
+    // "allowSyntheticDefaultImports": true,             /* Allow 'import x from y' when a module doesn't have a default export. */
+    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
+    // "preserveSymlinks": true,                         /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
+    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+
+    /* Type Checking */
+    "strict": true,                                      /* Enable all strict type-checking options. */
+    // "noImplicitAny": true,                            /* Enable error reporting for expressions and declarations with an implied 'any' type. */
+    // "strictNullChecks": true,                         /* When type checking, take into account 'null' and 'undefined'. */
+    // "strictFunctionTypes": true,                      /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
+    // "strictBindCallApply": true,                      /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
+    // "strictPropertyInitialization": true,             /* Check for class properties that are declared but not set in the constructor. */
+    // "noImplicitThis": true,                           /* Enable error reporting when 'this' is given the type 'any'. */
+    // "useUnknownInCatchVariables": true,               /* Default catch clause variables as 'unknown' instead of 'any'. */
+    // "alwaysStrict": true,                             /* Ensure 'use strict' is always emitted. */
+    // "noUnusedLocals": true,                           /* Enable error reporting when local variables aren't read. */
+    // "noUnusedParameters": true,                       /* Raise an error when a function parameter isn't read. */
+    // "exactOptionalPropertyTypes": true,               /* Interpret optional property types as written, rather than adding 'undefined'. */
+    // "noImplicitReturns": true,                        /* Enable error reporting for codepaths that do not explicitly return in a function. */
+    // "noFallthroughCasesInSwitch": true,               /* Enable error reporting for fallthrough cases in switch statements. */
+    // "noUncheckedIndexedAccess": true,                 /* Add 'undefined' to a type when accessed using an index. */
+    // "noImplicitOverride": true,                       /* Ensure overriding members in derived classes are marked with an override modifier. */
+    // "noPropertyAccessFromIndexSignature": true,       /* Enforces using indexed accessors for keys declared using an indexed type. */
+    // "allowUnusedLabels": true,                        /* Disable error reporting for unused labels. */
+    // "allowUnreachableCode": true,                     /* Disable error reporting for unreachable code. */
+
+    /* Completeness */
+    // "skipDefaultLibCheck": true,                      /* Skip type checking .d.ts files that are included with TypeScript. */
+    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
+  }
+}

package/lib/types/index.ts

@@ -0,0 +1,135 @@
+import type {
+  JSONSchema4,
+  JSONSchema4Object,
+  JSONSchema6,
+  JSONSchema6Object,
+  JSONSchema7,
+  JSONSchema7Object,
+} from "json-schema";
+import type $Refs from "../refs.js";
+
+export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
+export type JSONSchemaObject = JSONSchema4Object | JSONSchema6Object | JSONSchema7Object;
+export type SchemaCallback = (err: Error | null, schema?: JSONSchema | object) => any;
+export type $RefsCallback = (err: Error | null, $refs?: $Refs) => any;
+
+/**
+ * See https://apitools.dev/json-schema-ref-parser/docs/options.html
+ */
+
+export interface HTTPResolverOptions extends Partial<ResolverOptions> {
+  /**
+   * You can specify any HTTP headers that should be sent when downloading files. For example, some servers may require you to set the `Accept` or `Referrer` header.
+   */
+  headers?: HeadersInit | null;
+
+  /**
+   * The amount of time (in milliseconds) to wait for a response from the server when downloading files. The default is 5 seconds.
+   */
+  timeout?: number;
+
+  /**
+   * The maximum number of HTTP redirects to follow per file. The default is 5. To disable automatic following of redirects, set this to zero.
+   */
+  redirects?: number;
+
+  /**
+   * Set this to `true` if you're downloading files from a CORS-enabled server that requires authentication
+   */
+  withCredentials?: boolean;
+}
+
+/**
+ * JSON Schema `$Ref` Parser comes with built-in resolvers for HTTP and HTTPS URLs, as well as local filesystem paths (when running in Node.js). You can add your own custom resolvers to support additional protocols, or even replace any of the built-in resolvers with your own custom implementation.
+ *
+ * See https://apitools.dev/json-schema-ref-parser/docs/plugins/resolvers.html
+ */
+export interface ResolverOptions {
+  name?: string;
+  /**
+   * All resolvers have an order property, even the built-in resolvers. If you don't specify an order property, then your resolver will run last. Specifying `order: 1`, like we did in this example, will make your resolver run first. Or you can squeeze your resolver in-between some of the built-in resolvers. For example, `order: 101` would make it run after the file resolver, but before the HTTP resolver. You can see the order of all the built-in resolvers by looking at their source code.
+   *
+   * The order property and canRead property are related to each other. For each file that JSON Schema $Ref Parser needs to resolve, it first determines which resolvers can read that file by checking their canRead property. If only one resolver matches a file, then only that one resolver is called, regardless of its order. If multiple resolvers match a file, then those resolvers are tried in order until one of them successfully reads the file. Once a resolver successfully reads the file, the rest of the resolvers are skipped.
+   */
+  order?: number;
+
+  /**
+   * The `canRead` property tells JSON Schema `$Ref` Parser what kind of files your resolver can read. In this example, we've simply specified a regular expression that matches "mogodb://" URLs, but we could have used a simple boolean, or even a function with custom logic to determine which files to resolve. Here are examples of each approach:
+   */
+  canRead: boolean | RegExp | string | string[] | ((file: FileInfo) => boolean);
+
+  /**
+   * This is where the real work of a resolver happens. The `read` method accepts the same file info object as the `canRead` function, but rather than returning a boolean value, the `read` method should return the contents of the file. The file contents should be returned in as raw a form as possible, such as a string or a byte array. Any further parsing or processing should be done by parsers.
+   *
+   * Unlike the `canRead` function, the `read` method can also be asynchronous. This might be important if your resolver needs to read data from a database or some other external source. You can return your asynchronous value using either an ES6 Promise or a Node.js-style error-first callback. Of course, if your resolver has the ability to return its data synchronously, then that's fine too. Here are examples of all three approaches:
+   */
+  read:
+    | string
+    | object
+    | ((
+        file: FileInfo,
+        callback?: (error: Error | null, data: string | null) => any,
+      ) => string | Buffer | JSONSchema | Promise<string | Buffer | JSONSchema>);
+}
+
+export interface Plugin {
+  name?: string;
+  /**
+   * Parsers run in a specific order, relative to other parsers. For example, a parser with `order: 5` will run before a parser with `order: 10`. If a parser is unable to successfully parse a file, then the next parser is tried, until one succeeds or they all fail.
+   *
+   * You can change the order in which parsers run, which is useful if you know that most of your referenced files will be a certain type, or if you add your own custom parser that you want to run first.
+   */
+  order?: number;
+
+  /**
+   * All of the built-in parsers allow empty files by default. The JSON and YAML parsers will parse empty files as `undefined`. The text parser will parse empty files as an empty string. The binary parser will parse empty files as an empty byte array.
+   *
+   * You can set `allowEmpty: false` on any parser, which will cause an error to be thrown if a file empty.
+   */
+  allowEmpty?: boolean;
+
+  /**
+   * The encoding that the text is expected to be in.
+   */
+  encoding?: BufferEncoding;
+  /**
+   * Determines which parsers will be used for which files.
+   *
+   * A regular expression can be used to match files by their full path. A string (or array of strings) can be used to match files by their file extension. Or a function can be used to perform more complex matching logic. See the custom parser docs for details.
+   */
+  canParse?: boolean | RegExp | string | string[] | ((file: FileInfo) => boolean);
+
+  /**
+   * This is where the real work of a parser happens. The `parse` method accepts the same file info object as the `canParse` function, but rather than returning a boolean value, the `parse` method should return a JavaScript representation of the file contents.  For our CSV parser, that is a two-dimensional array of lines and values.  For your parser, it might be an object, a string, a custom class, or anything else.
+   *
+   * Unlike the `canParse` function, the `parse` method can also be asynchronous. This might be important if your parser needs to retrieve data from a database or if it relies on an external HTTP service to return the parsed value.  You can return your asynchronous value via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or a Node.js-style error-first callback.  Here are examples of both approaches:
+   */
+  parse:
+    | ((file: FileInfo, callback?: (error: Error | null, data: string | null) => any) => unknown | Promise<unknown>)
+    | number
+    | string;
+}
+
+/**
+ * JSON Schema `$Ref` Parser supports plug-ins, such as resolvers and parsers. These plug-ins can have methods such as `canRead()`, `read()`, `canParse()`, and `parse()`. All of these methods accept the same object as their parameter: an object containing information about the file being read or parsed.
+ *
+ * The file info object currently only consists of a few properties, but it may grow in the future if plug-ins end up needing more information.
+ *
+ * See https://apitools.dev/json-schema-ref-parser/docs/plugins/file-info-object.html
+ */
+export interface FileInfo {
+  /**
+   * The full URL of the file. This could be any type of URL, including "http://", "https://", "file://", "ftp://", "mongodb://", or even a local filesystem path (when running in Node.js).
+   */
+  url: string;
+
+  /**
+   * The lowercase file extension, such as ".json", ".yaml", ".txt", etc.
+   */
+  extension: string;
+
+  /**
+   * The raw file contents, in whatever form they were returned by the resolver that read the file.
+   */
+  data: string | Buffer;
+}

package/lib/util/errors.ts

@@ -0,0 +1,141 @@
+import { Ono } from "@jsdevtools/ono";
+import { stripHash, toFileSystemPath } from "./url.js";
+import type $RefParser from "../index.js";
+
+export type JSONParserErrorType =
+  | "EUNKNOWN"
+  | "EPARSER"
+  | "EUNMATCHEDPARSER"
+  | "ERESOLVER"
+  | "EUNMATCHEDRESOLVER"
+  | "EMISSINGPOINTER"
+  | "EINVALIDPOINTER";
+export class JSONParserError extends Error {
+  public readonly name: string;
+  public readonly message: string;
+  public source: string | undefined;
+  public path: Array<string | number> | null;
+  public readonly code: JSONParserErrorType;
+  public constructor(message: string, source?: string) {
+    super();
+
+    this.code = "EUNKNOWN";
+    this.name = "JSONParserError";
+    this.message = message;
+    this.source = source;
+    this.path = null;
+
+    Ono.extend(this);
+  }
+
+  get footprint() {
+    return `${this.path}+${this.source}+${this.code}+${this.message}`;
+  }
+}
+
+export class JSONParserErrorGroup extends Error {
+  files: $RefParser;
+
+  constructor(parser: $RefParser) {
+    super();
+
+    this.files = parser;
+    this.name = "JSONParserErrorGroup";
+    this.message = `${this.errors.length} error${
+      this.errors.length > 1 ? "s" : ""
+    } occurred while reading '${toFileSystemPath(parser.$refs._root$Ref!.path)}'`;
+
+    Ono.extend(this);
+  }
+
+  static getParserErrors(parser: any) {
+    const errors = [];
+
+    for (const $ref of Object.values(parser.$refs._$refs)) {
+      // @ts-expect-error TS(2571): Object is of type 'unknown'.
+      if ($ref.errors) {
+        // @ts-expect-error TS(2571): Object is of type 'unknown'.
+        errors.push(...$ref.errors);
+      }
+    }
+
+    return errors;
+  }
+
+  get errors(): Array<
+    | JSONParserError
+    | InvalidPointerError
+    | ResolverError
+    | ParserError
+    | MissingPointerError
+    | UnmatchedParserError
+    | UnmatchedResolverError
+  > {
+    return JSONParserErrorGroup.getParserErrors(this.files);
+  }
+}
+
+export class ParserError extends JSONParserError {
+  code = "EPARSER" as JSONParserErrorType;
+  name = "ParserError";
+  constructor(message: any, source: any) {
+    super(`Error parsing ${source}: ${message}`, source);
+  }
+}
+
+export class UnmatchedParserError extends JSONParserError {
+  code = "EUNMATCHEDPARSER" as JSONParserErrorType;
+  name = "UnmatchedParserError";
+
+  constructor(source: string) {
+    super(`Could not find parser for "${source}"`, source);
+  }
+}
+
+export class ResolverError extends JSONParserError {
+  code = "ERESOLVER" as JSONParserErrorType;
+  name = "ResolverError";
+  ioErrorCode?: string;
+  constructor(ex: Error | any, source?: string) {
+    super(ex.message || `Error reading file "${source}"`, source);
+    if ("code" in ex) {
+      this.ioErrorCode = String(ex.code);
+    }
+  }
+}
+
+export class UnmatchedResolverError extends JSONParserError {
+  code = "EUNMATCHEDRESOLVER" as JSONParserErrorType;
+  name = "UnmatchedResolverError";
+  constructor(source: any) {
+    super(`Could not find resolver for "${source}"`, source);
+  }
+}
+
+export class MissingPointerError extends JSONParserError {
+  code = "EUNMATCHEDRESOLVER" as JSONParserErrorType;
+  name = "MissingPointerError";
+  constructor(token: any, path: any) {
+    super(`Token "${token}" does not exist.`, stripHash(path));
+  }
+}
+
+export class InvalidPointerError extends JSONParserError {
+  code = "EUNMATCHEDRESOLVER" as JSONParserErrorType;
+  name = "InvalidPointerError";
+  constructor(pointer: any, path: any) {
+    super(`Invalid $ref pointer "${pointer}". Pointers must begin with "#/"`, stripHash(path));
+  }
+}
+
+export function isHandledError(err: any): err is JSONParserError {
+  return err instanceof JSONParserError || err instanceof JSONParserErrorGroup;
+}
+
+export function normalizeError(err: any) {
+  if (err.path === null) {
+    err.path = [];
+  }
+
+  return err;
+}

package/lib/util/maybe.ts

@@ -0,0 +1,22 @@
+import next from "./next.js";
+
+type MaybeParams<T> = (err: Error | any | null, result?: T) => void;
+export default function maybe<T>(cb: MaybeParams<T> | undefined, promise: Promise<T>): Promise<T> | void {
+  if (cb) {
+    promise.then(
+      function (result) {
+        next(function () {
+          cb(null, result);
+        });
+      },
+      function (err) {
+        next(function () {
+          cb(err);
+        });
+      },
+    );
+    return undefined;
+  } else {
+    return promise;
+  }
+}

package/lib/util/next.ts

@@ -0,0 +1,13 @@
+function makeNext() {
+  if (typeof process === "object" && typeof process.nextTick === "function") {
+    return process.nextTick;
+  } else if (typeof setImmediate === "function") {
+    return setImmediate;
+  } else {
+    return function next(f: () => void) {
+      setTimeout(f, 0);
+    };
+  }
+}
+
+export default makeNext();