@apidevtools/json-schema-ref-parser 11.4.2 → 11.5.0

package/lib/pointer.ts

@@ -3,6 +3,7 @@ import type $RefParserOptions from "./options.js";
 import $Ref from "./ref.js";
 import * as url from "./util/url.js";
 import { JSONParserError, InvalidPointerError, MissingPointerError, isHandledError } from "./util/errors.js";
+import type { JSONSchema } from "./types";
 
 const slashes = /\//g;
 const tildes = /~/g;
@@ -25,11 +26,11 @@ const safeDecodeURIComponent = (encodedURIComponent: string): string => {
  * @param [friendlyPath] - The original user-specified path (used for error messages)
  * @class
  */
-class Pointer {
+class Pointer<S = JSONSchema> {
   /**
    * The {@link $Ref} object that contains this {@link Pointer} object.
    */
-  $ref: $Ref;
+  $ref: $Ref<S>;
 
   /**
    * The file path or URL, containing the JSON pointer in the hash.
@@ -58,7 +59,7 @@ class Pointer {
    */
   indirections: number;
 
-  constructor($ref: $Ref, path: string, friendlyPath?: string) {
+  constructor($ref: $Ref<S>, path: string, friendlyPath?: string) {
     this.$ref = $ref;
 
     this.path = path;
@@ -85,7 +86,7 @@ class Pointer {
    * the {@link Pointer#$ref} and {@link Pointer#path} will reflect the resolution path
    * of the resolved value.
    */
-  resolve(obj: any, options?: $RefParserOptions, pathFromRoot?: string) {
+  resolve(obj: any, options?: $RefParserOptions<S>, pathFromRoot?: string) {
     const tokens = Pointer.parse(this.path, this.originalPath);
 
     // Crawl the object, one token at a time
@@ -143,7 +144,7 @@ class Pointer {
    * @returns
    * Returns the modified object, or an entirely new object if the entire object is overwritten.
    */
-  set(obj: any, value: any, options?: $RefParserOptions) {
+  set(obj: any, value: any, options?: $RefParserOptions<S>) {
     const tokens = Pointer.parse(this.path);
     let token;
 

package/lib/ref.ts

@@ -4,6 +4,7 @@ import { InvalidPointerError, isHandledError, normalizeError } from "./util/erro
 import { safePointerToPath, stripHash, getHash } from "./util/url.js";
 import type $Refs from "./refs.js";
 import type $RefParserOptions from "./options.js";
+import type { ParserOptions } from "./options.js";
 import type { JSONSchema } from "./types";
 
 export type $RefError = JSONParserError | ResolverError | ParserError | MissingPointerError;
@@ -13,7 +14,7 @@ export type $RefError = JSONParserError | ResolverError | ParserError | MissingP
  *
  * @class
  */
-class $Ref {
+class $Ref<S = JSONSchema> {
   /**
    * The file path or URL of the referenced file.
    * This path is relative to the path of the main JSON schema file.
@@ -39,7 +40,7 @@ class $Ref {
    *
    * @type {$Refs}
    */
-  $refs: $Refs;
+  $refs: $Refs<S>;
 
   /**
    * Indicates the type of {@link $Ref#path} (e.g. "file", "http", etc.)
@@ -51,7 +52,7 @@ class $Ref {
    */
   errors: Array<$RefError> = [];
 
-  constructor($refs: $Refs) {
+  constructor($refs: $Refs<S>) {
     this.$refs = $refs;
   }
 
@@ -87,7 +88,7 @@ class $Ref {
    * @param options
    * @returns
    */
-  exists(path: string, options?: $RefParserOptions) {
+  exists(path: string, options?: $RefParserOptions<S>) {
     try {
       this.resolve(path, options);
       return true;
@@ -103,7 +104,7 @@ class $Ref {
    * @param options
    * @returns - Returns the resolved value
    */
-  get(path: any, options: $RefParserOptions) {
+  get(path: string, options?: $RefParserOptions<S>) {
     return this.resolve(path, options)?.value;
   }
 
@@ -116,8 +117,8 @@ class $Ref {
    * @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);
+  resolve(path: string, options?: $RefParserOptions<S>, friendlyPath?: string, pathFromRoot?: string) {
+    const pointer = new Pointer<S>(this, path, friendlyPath);
     try {
       return pointer.resolve(this.value, options, pathFromRoot);
     } catch (err: any) {
@@ -185,12 +186,12 @@ class $Ref {
    * @param options
    * @returns
    */
-  static isAllowed$Ref(value: unknown, options?: $RefParserOptions) {
+  static isAllowed$Ref(value: unknown, options?: ParserOptions) {
     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)) {
+      } else if (value.$ref[0] !== "#" && (!options || options.resolve?.external)) {
         // It's an external reference, which is allowed by the options
         return true;
       }
@@ -266,7 +267,7 @@ class $Ref {
    * @param resolvedValue - The resolved value, which can be any type
    * @returns - Returns the dereferenced value
    */
-  static dereference($ref: $Ref, resolvedValue: JSONSchema): JSONSchema {
+  static dereference<S>($ref: $Ref<S>, resolvedValue: S): S {
     if (resolvedValue && typeof resolvedValue === "object" && $Ref.isExtended$Ref($ref)) {
       const merged = {};
       for (const key of Object.keys($ref)) {
@@ -283,7 +284,7 @@ class $Ref {
         }
       }
 
-      return merged;
+      return merged as S;
     } else {
       // Completely replace the original reference with the resolved value
       return resolvedValue;

package/lib/refs.ts

@@ -2,12 +2,12 @@ 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";
 import convertPathToPosix from "./util/convert-path-to-posix";
+import type { JSONSchema } from "./types";
 
-interface $RefsMap {
-  [url: string]: $Ref;
+interface $RefsMap<S> {
+  [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.
@@ -16,7 +16,7 @@ interface $RefsMap {
  *
  * See https://apitools.dev/json-schema-ref-parser/docs/refs.html
  */
-export default class $Refs {
+export default class $Refs<S = 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.
    *
@@ -45,13 +45,13 @@ export default class $Refs {
    *
    * @param types (optional) Optionally only return values from certain locations ("file", "http", etc.)
    */
-  values(...types: string[]): JSONSchema {
+  values(...types: string[]): S {
     const $refs = this._$refs;
     const paths = getPaths($refs, types);
     return paths.reduce<Record<string, any>>((obj, path) => {
       obj[convertPathToPosix(path.decoded)] = $refs[path.encoded].value;
       return obj;
-    }, {});
+    }, {}) as S;
   }
 
   /**
@@ -84,17 +84,17 @@ export default class $Refs {
    * @param [options]
    * @returns - Returns the resolved value
    */
-  get(path: string, options?: $RefParserOptions): JSONSchema4Type | JSONSchema6Type | JSONSchema7Type {
+  get(path: string, options?: $RefParserOptions<S>): 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 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: any, value: JSONSchema4Type | JSONSchema6Type | JSONSchema7Type) {
+  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];
@@ -126,7 +126,7 @@ export default class $Refs {
   _add(path: string) {
     const withoutHash = url.stripHash(path);
 
-    const $ref = new $Ref(this);
+    const $ref = new $Ref<S>(this);
     $ref.path = withoutHash;
 
     this._$refs[withoutHash] = $ref;
@@ -162,7 +162,7 @@ export default class $Refs {
    * @type {object}
    * @protected
    */
-  _$refs: $RefsMap = {};
+  _$refs: $RefsMap<S> = {};
 
   /**
    * The {@link $Ref} object that is the root of the JSON schema.
@@ -170,7 +170,7 @@ export default class $Refs {
    * @type {$Ref}
    * @protected
    */
-  _root$Ref: $Ref;
+  _root$Ref: $Ref<S>;
 
   constructor() {
     /**
@@ -215,7 +215,7 @@ export default class $Refs {
  * @param [types] - Only return paths of the given types ("file", "http", etc.)
  * @returns
  */
-function getPaths($refs: $RefsMap, types: string[]) {
+function getPaths<S>($refs: $RefsMap<S>, types: string[]) {
   let paths = Object.keys($refs);
 
   // Filter the paths by type

package/lib/resolve-external.ts

@@ -4,12 +4,10 @@ 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 { Options, ParserOptions } from "./options.js";
 import type { JSONSchema } from "./types/index.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}.
@@ -20,7 +18,10 @@ export default resolveExternal;
  * 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: $RefParser, options: Options) {
+function resolveExternal<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+  parser: $RefParser<S, O>,
+  options: Options,
+) {
   if (!options.resolve.external) {
     // Nothing to resolve, so exit early
     return Promise.resolve();
@@ -51,10 +52,10 @@ function resolveExternal(parser: $RefParser, options: Options) {
  * 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: string | Buffer | JSONSchema | undefined | null,
+function crawl<S extends JSONSchema = JSONSchema>(
+  obj: string | Buffer | S | undefined | null,
   path: string,
-  $refs: $Refs,
+  $refs: $Refs<S>,
   options: Options,
   seen?: Set<any>,
   external?: boolean,
@@ -65,13 +66,13 @@ function crawl(
   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));
+      promises.push(resolve$Ref<S>(obj, path, $refs, options));
     }
 
-    const keys = Object.keys(obj) as (keyof typeof obj)[];
+    const keys = Object.keys(obj) as string[];
     for (const key of keys) {
       const keyPath = Pointer.join(path, key);
-      const value = obj[key] as string | JSONSchema | Buffer | undefined;
+      const value = obj[key as keyof typeof obj] as string | JSONSchema | Buffer | undefined;
       promises = promises.concat(crawl(value, keyPath, $refs, options, seen, external));
     }
   }
@@ -91,7 +92,12 @@ function crawl(
  * 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: JSONSchema, path: string, $refs: $Refs, options: Options) {
+async function resolve$Ref<S extends JSONSchema = JSONSchema>(
+  $ref: S,
+  path: string,
+  $refs: $Refs<S>,
+  options: Options,
+) {
   const shouldResolveOnCwd = options.dereference.externalReferenceResolution === "root";
   const resolvedPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref!);
   const withoutHash = url.stripHash(resolvedPath);
@@ -99,10 +105,10 @@ async function resolve$Ref($ref: JSONSchema, path: string, $refs: $Refs, options
   // $ref.$ref = url.relative($refs._root$Ref.path, resolvedPath);
 
   // Do we already have this $ref?
-  $ref = $refs._$refs[withoutHash];
-  if ($ref) {
+  const ref = $refs._$refs[withoutHash];
+  if (ref) {
     // We've already parsed this $ref, so use the existing value
-    return Promise.resolve($ref.value);
+    return Promise.resolve(ref.value);
   }
 
   // Parse the $referenced file/url
@@ -127,3 +133,4 @@ async function resolve$Ref($ref: JSONSchema, path: string, $refs: $Refs, options
     return [];
   }
 }
+export default resolveExternal;

package/lib/resolvers/file.ts

@@ -2,7 +2,7 @@ import fs from "fs";
 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 { JSONSchema, ResolverOptions } from "../types/index.js";
 import type { FileInfo } from "../types/index.js";
 
 export default {
@@ -36,4 +36,4 @@ export default {
       throw new ResolverError(ono(err, `Error opening file "${path}"`), path);
     }
   },
-} as ResolverOptions;
+} as ResolverOptions<JSONSchema>;

package/lib/resolvers/http.ts

@@ -1,7 +1,7 @@
 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";
+import type { FileInfo, HTTPResolverOptions, JSONSchema } from "../types/index.js";
 
 export default {
   /**
@@ -59,14 +59,18 @@ export default {
 
     return download(u, this);
   },
-} as HTTPResolverOptions;
+} as HTTPResolverOptions<JSONSchema>;
 
 /**
  * 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> {
+async function download<S>(
+  u: URL | string,
+  httpOptions: HTTPResolverOptions<S>,
+  _redirects?: string[],
+): Promise<Buffer> {
   u = url.parse(u);
   const redirects = _redirects || [];
   redirects.push(u.href);
@@ -105,7 +109,7 @@ async function download(u: URL | string, httpOptions: HTTPResolverOptions, _redi
  * Sends an HTTP GET request.
  * The promise resolves with the HTTP Response object.
  */
-async function get(u: RequestInfo | URL, httpOptions: HTTPResolverOptions) {
+async function get<S>(u: RequestInfo | URL, httpOptions: HTTPResolverOptions<S>) {
   let controller: any;
   let timeoutId: any;
   if (httpOptions.timeout) {

package/lib/types/index.ts

@@ -10,14 +10,14 @@ 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 | null) => any;
-export type $RefsCallback = (err: Error | null, $refs?: $Refs) => any;
+export type SchemaCallback<S = JSONSchema> = (err: Error | null, schema?: S | object | null) => any;
+export type $RefsCallback<S = JSONSchema> = (err: Error | null, $refs?: $Refs<S>) => any;
 
 /**
  * See https://apitools.dev/json-schema-ref-parser/docs/options.html
  */
 
-export interface HTTPResolverOptions extends Partial<ResolverOptions> {
+export interface HTTPResolverOptions<S = JSONSchema> extends Partial<ResolverOptions<S>> {
   /**
    * 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.
    */
@@ -44,7 +44,7 @@ export interface HTTPResolverOptions extends Partial<ResolverOptions> {
  *
  * See https://apitools.dev/json-schema-ref-parser/docs/plugins/resolvers.html
  */
-export interface ResolverOptions {
+export interface ResolverOptions<S = JSONSchema> {
   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.
@@ -69,7 +69,7 @@ export interface ResolverOptions {
     | ((
         file: FileInfo,
         callback?: (error: Error | null, data: string | null) => any,
-      ) => string | Buffer | JSONSchema | Promise<string | Buffer | JSONSchema>);
+      ) => string | Buffer | S | Promise<string | Buffer | S>);
 }
 
 export interface Plugin {

package/lib/util/errors.ts

@@ -1,6 +1,8 @@
 import { Ono } from "@jsdevtools/ono";
 import { stripHash, toFileSystemPath } from "./url.js";
 import type $RefParser from "../index.js";
+import type { ParserOptions } from "../index.js";
+import type { JSONSchema } from "../index.js";
 import type $Ref from "../ref";
 
 export type JSONParserErrorType =
@@ -11,6 +13,7 @@ export type JSONParserErrorType =
   | "EUNMATCHEDRESOLVER"
   | "EMISSINGPOINTER"
   | "EINVALIDPOINTER";
+
 export class JSONParserError extends Error {
   public readonly name: string;
   public readonly message: string;
@@ -34,10 +37,13 @@ export class JSONParserError extends Error {
   }
 }
 
-export class JSONParserErrorGroup extends Error {
-  files: $RefParser;
+export class JSONParserErrorGroup<
+  S extends JSONSchema = JSONSchema,
+  O extends ParserOptions = ParserOptions,
+> extends Error {
+  files: $RefParser<S, O>;
 
-  constructor(parser: $RefParser) {
+  constructor(parser: $RefParser<S, O>) {
     super();
 
     this.files = parser;
@@ -49,10 +55,12 @@ export class JSONParserErrorGroup extends Error {
     Ono.extend(this);
   }
 
-  static getParserErrors(parser: any) {
+  static getParserErrors<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    parser: $RefParser<S, O>,
+  ) {
     const errors = [];
 
-    for (const $ref of Object.values(parser.$refs._$refs) as $Ref[]) {
+    for (const $ref of Object.values(parser.$refs._$refs) as $Ref<unknown>[]) {
       if ($ref.errors) {
         errors.push(...$ref.errors);
       }
@@ -70,7 +78,7 @@ export class JSONParserErrorGroup extends Error {
     | UnmatchedParserError
     | UnmatchedResolverError
   > {
-    return JSONParserErrorGroup.getParserErrors(this.files);
+    return JSONParserErrorGroup.getParserErrors<S>(this.files);
   }
 }
 

package/lib/util/plugins.ts

@@ -3,7 +3,6 @@ import type $RefParserOptions from "../options.js";
 import type { ResolverOptions } from "../types/index.js";
 import type $Refs from "../refs.js";
 import type { Plugin } from "../types/index.js";
-import type { JSONSchema } from "../types/index.js";
 
 /**
  * Returns the given plugins as an array, rather than an object map.
@@ -11,13 +10,13 @@ import type { JSONSchema } from "../types/index.js";
  *
  * @returns
  */
-export function all(plugins: $RefParserOptions["resolve"]): Plugin[] {
+export function all<S>(plugins: $RefParserOptions<S>["resolve"]): Plugin[] {
   return Object.keys(plugins)
     .filter((key) => {
       return typeof plugins[key] === "object";
     })
     .map((key) => {
-      (plugins[key] as ResolverOptions)!.name = key;
+      (plugins[key] as ResolverOptions<S>)!.name = key;
       return plugins[key] as Plugin;
     });
 }
@@ -44,9 +43,9 @@ export function sort(plugins: Plugin[]) {
   });
 }
 
-export interface PluginResult {
+export interface PluginResult<S> {
   plugin: Plugin;
-  result?: string | Buffer | JSONSchema;
+  result?: string | Buffer | S;
   error?: any;
 }
 
@@ -58,17 +57,17 @@ export interface PluginResult {
  * If the promise rejects, or the callback is called with an error, then the next plugin is called.
  * If ALL plugins fail, then the last error is thrown.
  */
-export async function run(
+export async function run<S>(
   plugins: Plugin[],
-  method: keyof Plugin | keyof ResolverOptions,
+  method: keyof Plugin | keyof ResolverOptions<S>,
   file: FileInfo,
-  $refs: $Refs,
+  $refs: $Refs<S>,
 ) {
   let plugin: Plugin;
-  let lastError: PluginResult;
+  let lastError: PluginResult<S>;
   let index = 0;
 
-  return new Promise<PluginResult>((resolve, reject) => {
+  return new Promise<PluginResult<S>>((resolve, reject) => {
     runNextPlugin();
 
     function runNextPlugin() {
@@ -95,7 +94,7 @@ export async function run(
       }
     }
 
-    function callback(err: PluginResult["error"], result: PluginResult["result"]) {
+    function callback(err: PluginResult<S>["error"], result: PluginResult<S>["result"]) {
       if (err) {
         onError(err);
       } else {
@@ -103,7 +102,7 @@ export async function run(
       }
     }
 
-    function onSuccess(result: PluginResult["result"]) {
+    function onSuccess(result: PluginResult<S>["result"]) {
       // console.log('    success');
       resolve({
         plugin,
@@ -111,7 +110,7 @@ export async function run(
       });
     }
 
-    function onError(error: PluginResult["error"]) {
+    function onError(error: PluginResult<S>["error"]) {
       // console.log('    %s', err.message || err);
       lastError = {
         plugin,
@@ -128,9 +127,9 @@ export async function run(
  * If the value is a RegExp, then it will be tested against the file URL.
  * If the value is an array, then it will be compared against the file extension.
  */
-function getResult(
+function getResult<S>(
   obj: Plugin,
-  prop: keyof Plugin | keyof ResolverOptions,
+  prop: keyof Plugin | keyof ResolverOptions<S>,
   file: FileInfo,
   callback?: (err?: Error, result?: any) => void,
   $refs?: any,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apidevtools/json-schema-ref-parser",
-  "version": "11.4.2",
+  "version": "11.5.0",
   "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
   "keywords": [
     "json",