@hey-api/json-schema-ref-parser 0.0.1

package/lib/refs.ts

@@ -0,0 +1,239 @@
+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 { ParserOptions } from "./options.js";
+import convertPathToPosix from "./util/convert-path-to-posix";
+import type { JSONSchema } from "./types";
+
+interface $RefsMap<S extends object = JSONSchema> {
+  [url: string]: $Ref<S>;
+}
+/**
+ * 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<S extends object = JSONSchema> {
+  /**
+   * 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[])[]): string[] {
+    const paths = getPaths(this._$refs, types.flat());
+    return paths.map((path) => {
+      return convertPathToPosix(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 | string[])[]): S {
+    const $refs = this._$refs;
+    const paths = getPaths($refs, types.flat());
+    return paths.reduce<Record<string, any>>((obj, path) => {
+      obj[convertPathToPosix(path.decoded)] = $refs[path.encoded].value;
+      return obj;
+    }, {}) as S;
+  }
+
+  /**
+   * 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 {
+      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?: ParserOptions): 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 path 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: string, 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: string) {
+    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<S>(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?: ParserOptions) {
+    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<S> = {};
+
+  /**
+   * The {@link $Ref} object that is the root of the JSON schema.
+   *
+   * @type {$Ref}
+   * @protected
+   */
+  _root$Ref: $Ref<S>;
+
+  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<S extends object = JSONSchema>(
+  $refs: $RefsMap<S>,
+  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.ts

@@ -0,0 +1,141 @@
+import $Ref from "./ref.js";
+import Pointer from "./pointer.js";
+import { newFile, parseFile } from "./parse.js";
+import * as url from "./util/url.js";
+import type $Refs from "./refs.js";
+import type { $RefParserOptions } from "./options.js";
+import type { JSONSchema } from "./types/index.js";
+import { getResolvedInput } from "./index.js";
+import type { $RefParser } from "./index.js";
+import { isHandledError } from "./util/errors.js";
+import { fileResolver } from "./resolvers/file.js";
+import { urlResolver } from "./resolvers/url.js";
+
+/**
+ * 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.
+ */
+export function resolveExternal(
+  parser: $RefParser,
+  options: $RefParserOptions,
+) {
+  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<S extends object = JSONSchema>(
+  obj: string | Buffer | S | undefined | null,
+  path: string,
+  $refs: $Refs<S>,
+  options: $RefParserOptions,
+  seen?: Set<any>,
+  external?: boolean,
+) {
+  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<S>(obj, path, $refs, options));
+    }
+
+    const keys = Object.keys(obj) as string[];
+    for (const key of keys) {
+      const keyPath = Pointer.join(path, key);
+      const value = obj[key as keyof typeof obj] as string | JSONSchema | Buffer | undefined;
+      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<S extends object = JSONSchema>(
+  $ref: S,
+  path: string,
+  $refs: $Refs<S>,
+  options: $RefParserOptions,
+) {
+  const resolvedPath = url.resolve(path, ($ref as JSONSchema).$ref!);
+  const withoutHash = url.stripHash(resolvedPath);
+
+  // $ref.$ref = url.relative($refs._root$Ref.path, resolvedPath);
+
+  // Do we already have this $ref?
+  const 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
+  const file = newFile(resolvedPath)
+
+  // 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 $refAdded = $refs._add(file.url);
+
+  try {
+    const resolvedInput = getResolvedInput({ pathOrUrlOrSchema: resolvedPath })
+
+    $refAdded.pathType = resolvedInput.type;
+
+    let promises: any = [];
+
+    if (resolvedInput.type !== 'json') {
+      const resolver = resolvedInput.type === 'file' ? fileResolver : urlResolver;
+      await resolver.handler(file);
+      const parseResult = await parseFile(file, options);
+      $refAdded.value = parseResult.result;
+      promises = crawl(parseResult.result, `${withoutHash}#`, $refs, options, new Set(), true);
+    }
+
+    return Promise.all(promises);
+  } catch (err) {
+    if (isHandledError(err)) {
+      $refAdded.value = err;
+    }
+
+    throw err;
+  }
+}

package/lib/resolvers/file.ts

@@ -0,0 +1,24 @@
+import fs from "fs";
+import { ono } from "@jsdevtools/ono";
+import * as url from "../util/url.js";
+import { ResolverError } from "../util/errors.js";
+import type { FileInfo } from "../types/index.js";
+
+export const fileResolver = {
+  handler: async (file: FileInfo): Promise<void> => {
+    let path: string | undefined;
+
+    try {
+      path = url.toFileSystemPath(file.url);
+    } catch (error: any) {
+      throw new ResolverError(ono.uri(error, `Malformed URI: ${file.url}`), file.url);
+    }
+
+    try {
+      const data = await fs.promises.readFile(path);
+      file.data = data;
+    } catch (error: any) {
+      throw new ResolverError(ono(error, `Error opening file "${path}"`), path);
+    }
+  },
+};

package/lib/resolvers/url.ts

@@ -0,0 +1,78 @@
+import { ono } from "@jsdevtools/ono";
+import { resolve } from "../util/url.js";
+import { ResolverError } from "../util/errors.js";
+import type { FileInfo } from "../types/index.js";
+
+export const sendRequest = async ({
+  init,
+  redirects = [],
+  url,
+}: {
+  init?: RequestInit;
+  redirects?: string[];
+  url: URL | string;
+}): Promise<{
+  response: Response;
+}> => {
+  url = new URL(url);
+  redirects.push(url.href);
+
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort();
+    }, 60_000);
+    const response = await fetch(url, {
+      signal: controller.signal,
+      ...init,
+    });
+    clearTimeout(timeoutId);
+
+    if (response.status >= 400) {
+      throw ono({ status: response.status }, `HTTP ERROR ${response.status}`);
+    }
+    
+    if (response.status >= 300) {
+      if (redirects.length > 5) {
+        throw new ResolverError(
+          ono(
+            { status: response.status },
+            `Error requesting ${redirects[0]}. \nToo many redirects: \n  ${redirects.join(" \n  ")}`,
+          ),
+        );
+      }
+      
+      if (!("location" in response.headers) || !response.headers.location) {
+        throw ono({ status: response.status }, `HTTP ${response.status} redirect with no location header`);
+      }
+      
+      return sendRequest({
+        init,
+        redirects,
+        url: resolve(url.href, response.headers.location as string),
+      });
+    }
+
+    return { response };
+  } catch (error: any) {
+    throw new ResolverError(ono(error, `Error requesting ${url.href}`), url.href);
+  }
+}
+
+export const urlResolver = {
+  handler: async (file: FileInfo, arrayBuffer?: ArrayBuffer): Promise<void> => {
+    let data = arrayBuffer;
+
+    if (!data) {
+      const { response } = await sendRequest({
+        init: {
+          method: 'GET',
+        },
+        url: file.url,
+      });
+      data = response.body ? await response.arrayBuffer() : new ArrayBuffer(0)
+    }
+
+    file.data = Buffer.from(data);
+  },
+};

package/lib/types/index.ts

@@ -0,0 +1,51 @@
+import type {
+  JSONSchema4,
+  JSONSchema4Object,
+  JSONSchema6,
+  JSONSchema6Object,
+  JSONSchema7,
+  JSONSchema7Object,
+} from "json-schema";
+
+export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
+export type JSONSchemaObject = JSONSchema4Object | JSONSchema6Object | JSONSchema7Object;
+
+export interface Plugin {
+  /**
+   * Can this parser be used to process this file?
+   */
+  canHandle: (file: FileInfo) => boolean;
+  /**
+   * This is where the real work of a parser happens. The `parse` method accepts the same file info object as the `canHandle` 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 `canHandle` 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:
+   */
+  handler: (file: FileInfo) => string | Buffer | JSONSchema | Promise<{ data: Buffer }> | Promise<string | Buffer | JSONSchema>;
+  name: 'binary' | 'file' | 'http' | 'json' | 'text' | 'yaml';
+}
+
+/**
+ * JSON Schema `$Ref` Parser supports plug-ins, such as resolvers and parsers. These plug-ins can have methods such as `canHandle()`, `read()`, `canHandle()`, 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 raw file contents, in whatever form they were returned by the resolver that read the file.
+   */
+  data: string | Buffer;
+  /**
+   * The lowercase file extension, such as ".json", ".yaml", ".txt", etc.
+   */
+  extension: string;
+  /**
+   * The hash (URL fragment) of the file URL, including the # symbol. If the URL doesn't have a hash, then this will be an empty string.
+   */
+  hash: string;
+  /**
+   * 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;
+}

package/lib/util/convert-path-to-posix.ts

@@ -0,0 +1,11 @@
+import path from "path";
+
+export default function convertPathToPosix(filePath: string) {
+  const isExtendedLengthPath = filePath.startsWith("\\\\?\\");
+
+  if (isExtendedLengthPath) {
+    return filePath;
+  }
+
+  return filePath.split(path?.win32?.sep).join(path?.posix?.sep ?? "/");
+}

package/lib/util/errors.ts

@@ -0,0 +1,153 @@
+import { Ono } from "@jsdevtools/ono";
+import { getHash, stripHash, toFileSystemPath } from "./url.js";
+import type { $RefParser } from "../index.js";
+import type { JSONSchema } from "../types/index.js";
+import type $Ref from "../ref";
+
+export type JSONParserErrorType =
+  | "EUNKNOWN"
+  | "EPARSER"
+  | "EUNMATCHEDPARSER"
+  | "ETIMEOUT"
+  | "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<S extends object = JSONSchema> 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<S extends object = JSONSchema>(
+    parser: $RefParser,
+  ) {
+    const errors = [];
+
+    for (const $ref of Object.values(parser.$refs._$refs) as $Ref<S>[]) {
+      if ($ref.errors) {
+        errors.push(...$ref.errors);
+      }
+    }
+
+    return errors;
+  }
+
+  get errors(): Array<
+    | JSONParserError
+    | InvalidPointerError
+    | ResolverError
+    | ParserError
+    | MissingPointerError
+    | UnmatchedParserError
+    | UnmatchedResolverError
+  > {
+    return JSONParserErrorGroup.getParserErrors<S>(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 = "EMISSINGPOINTER" as JSONParserErrorType;
+  name = "MissingPointerError";
+  constructor(token: string, path: string) {
+    super(`Missing $ref pointer "${getHash(path)}". Token "${token}" does not exist.`, stripHash(path));
+  }
+}
+
+export class TimeoutError extends JSONParserError {
+  code = "ETIMEOUT" as JSONParserErrorType;
+  name = "TimeoutError";
+  constructor(timeout: number) {
+    super(`Dereferencing timeout reached: ${timeout}ms`);
+  }
+}
+
+export class InvalidPointerError extends JSONParserError {
+  code = "EUNMATCHEDRESOLVER" as JSONParserErrorType;
+  name = "InvalidPointerError";
+  constructor(pointer: string, path: string) {
+    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;
+}