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

package/lib/index.ts

@@ -19,7 +19,15 @@ import {
 import { ono } from "@jsdevtools/ono";
 import maybe from "./util/maybe.js";
 import type { ParserOptions } from "./options.js";
-import type { $RefsCallback, JSONSchema, SchemaCallback } from "./types/index.js";
+import type {
+  $RefsCallback,
+  JSONSchema,
+  SchemaCallback,
+  FileInfo,
+  Plugin,
+  ResolverOptions,
+  HTTPResolverOptions,
+} from "./types/index.js";
 
 export type RefParserSchema = string | JSONSchema;
 
@@ -29,14 +37,14 @@ export type RefParserSchema = string | JSONSchema;
  *
  * @class
  */
-export class $RefParser {
+export class $RefParser<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions> {
   /**
    * The parsed (and possibly dereferenced) JSON schema object
    *
    * @type {object}
    * @readonly
    */
-  public schema: JSONSchema | null = null;
+  public schema: S | null = null;
 
   /**
    * The resolved JSON references
@@ -44,7 +52,7 @@ export class $RefParser {
    * @type {$Refs}
    * @readonly
    */
-  $refs = new $Refs();
+  $refs = new $Refs<S>();
 
   /**
    * Parses the given JSON schema.
@@ -57,19 +65,14 @@ export class $RefParser {
    * @param [callback] - An error-first callback. The second parameter is the parsed JSON schema object.
    * @returns - The returned promise resolves with the parsed JSON schema object.
    */
-  public parse(schema: RefParserSchema): Promise<JSONSchema>;
-  public parse(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-  public parse(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public parse(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-  public parse(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public parse(
-    baseUrl: string,
-    schema: RefParserSchema,
-    options: ParserOptions,
-    callback: SchemaCallback,
-  ): Promise<void>;
+  public parse(schema: S | string): Promise<S>;
+  public parse(schema: S | string, callback: SchemaCallback<S>): Promise<void>;
+  public parse(schema: S | string, options: O): Promise<S>;
+  public parse(schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+  public parse(baseUrl: string, schema: S | string, options: O): Promise<S>;
+  public parse(baseUrl: string, schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
   async parse() {
-    const args = normalizeArgs(arguments as any);
+    const args = normalizeArgs<S, O>(arguments as any);
     let promise;
 
     if (!args.path && !args.schema) {
@@ -112,7 +115,7 @@ export class $RefParser {
       promise = Promise.resolve(args.schema);
     } else {
       // Parse the schema file/url
-      promise = _parse(args.path, this.$refs, args.options);
+      promise = _parse<S, typeof args.options>(args.path, this.$refs, args.options);
     }
 
     try {
@@ -140,19 +143,35 @@ export class $RefParser {
     }
   }
 
-  public static parse(schema: RefParserSchema): Promise<JSONSchema>;
-  public static parse(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-  public static parse(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public static parse(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-  public static parse(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public static parse(
+  public static parse<S extends JSONSchema = JSONSchema>(schema: S | string): Promise<S>;
+  public static parse<S extends JSONSchema = JSONSchema>(
+    schema: S | string,
+    callback: SchemaCallback<S>,
+  ): Promise<void>;
+  public static parse<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+    options: O,
+  ): Promise<S>;
+  public static parse<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+    options: O,
+    callback: SchemaCallback<S>,
+  ): Promise<void>;
+  public static parse<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
     baseUrl: string,
-    schema: RefParserSchema,
-    options: ParserOptions,
-    callback: SchemaCallback,
+    schema: S | string,
+    options: O,
+  ): Promise<S>;
+  public static parse<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    baseUrl: string,
+    schema: S | string,
+    options: O,
+    callback: SchemaCallback<S>,
   ): Promise<void>;
-  public static parse(): Promise<JSONSchema> | Promise<void> {
-    const parser = new $RefParser();
+  public static parse<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>():
+    | Promise<S>
+    | Promise<void> {
+    const parser = new $RefParser<S, O>();
     return parser.parse.apply(parser, arguments as any);
   }
 
@@ -167,32 +186,14 @@ export class $RefParser {
    * @param options (optional)
    * @param callback (optional) A callback that will receive a `$Refs` object
    */
-  public resolve(schema: RefParserSchema): Promise<$Refs>;
-  public resolve(schema: RefParserSchema, callback: $RefsCallback): Promise<void>;
-  public resolve(schema: RefParserSchema, options: ParserOptions): Promise<$Refs>;
-  public resolve(schema: RefParserSchema, options: ParserOptions, callback: $RefsCallback): Promise<void>;
-  public resolve(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<$Refs>;
-  public resolve(
-    baseUrl: string,
-    schema: RefParserSchema,
-    options: ParserOptions,
-    callback: $RefsCallback,
-  ): Promise<void>;
-  /**
-   * Parses the given JSON schema and resolves any JSON references, including references in
-   * externally-referenced files.
-   *
-   * @param [path] - The file path or URL of the JSON schema
-   * @param [schema] - A JSON schema object. This object will be used instead of reading from `path`.
-   * @param [options] - Options that determine how the schema is parsed and resolved
-   * @param [callback]
-   * - An error-first callback. The second parameter is a {@link $Refs} object containing the resolved JSON references
-   *
-   * @returns
-   * The returned promise resolves with a {@link $Refs} object containing the resolved JSON references
-   */
+  public resolve(schema: S | string): Promise<$Refs<S>>;
+  public resolve(schema: S | string, callback: $RefsCallback<S>): Promise<void>;
+  public resolve(schema: S | string, options: O): Promise<$Refs<S>>;
+  public resolve(schema: S | string, options: O, callback: $RefsCallback<S>): Promise<void>;
+  public resolve(baseUrl: string, schema: S | string, options: O): Promise<$Refs<S>>;
+  public resolve(baseUrl: string, schema: S | string, options: O, callback: $RefsCallback<S>): Promise<void>;
   async resolve() {
-    const args = normalizeArgs(arguments);
+    const args = normalizeArgs<S, O>(arguments);
 
     try {
       await this.parse(args.path, args.schema, args.options);
@@ -215,33 +216,38 @@ export class $RefParser {
    * @param options (optional)
    * @param callback (optional) A callback that will receive a `$Refs` object
    */
-  public static resolve(schema: RefParserSchema): Promise<$Refs>;
-  public static resolve(schema: RefParserSchema, callback: $RefsCallback): Promise<void>;
-  public static resolve(schema: RefParserSchema, options: ParserOptions): Promise<$Refs>;
-  public static resolve(schema: RefParserSchema, options: ParserOptions, callback: $RefsCallback): Promise<void>;
-  public static resolve(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<$Refs>;
-  public static resolve(
+  public static resolve<S extends JSONSchema = JSONSchema>(schema: S | string): Promise<$Refs<S>>;
+  public static resolve<S extends JSONSchema = JSONSchema>(
+    schema: S | string,
+    callback: $RefsCallback<S>,
+  ): Promise<void>;
+  public static resolve<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+    options: O,
+  ): Promise<$Refs<S>>;
+  public static resolve<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+    options: O,
+    callback: $RefsCallback<S>,
+  ): Promise<void>;
+  public static resolve<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    baseUrl: string,
+    schema: S | string,
+    options: O,
+  ): Promise<$Refs<S>>;
+  public static resolve<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
     baseUrl: string,
-    schema: RefParserSchema,
-    options: ParserOptions,
-    callback: $RefsCallback,
+    schema: S | string,
+    options: O,
+    callback: $RefsCallback<S>,
   ): Promise<void>;
-  static resolve(): Promise<JSONSchema> | Promise<void> {
-    const instance = new $RefParser();
+  static resolve<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>():
+    | Promise<S>
+    | Promise<void> {
+    const instance = new $RefParser<S, O>();
     return instance.resolve.apply(instance, arguments as any);
   }
 
-  /**
-   * Parses the given JSON schema, resolves any JSON references, and bundles all external references
-   * into the main JSON schema. This produces a JSON schema that only has *internal* references,
-   * not any *external* references.
-   *
-   * @param [path] - The file path or URL of the JSON schema
-   * @param [schema] - A JSON schema object. This object will be used instead of reading from `path`.
-   * @param [options] - Options that determine how the schema is parsed, resolved, and dereferenced
-   * @param [callback] - An error-first callback. The second parameter is the bundled JSON schema object
-   * @returns - The returned promise resolves with the bundled JSON schema object.
-   */
   /**
    * Bundles all referenced files/URLs into a single schema that only has internal `$ref` pointers. This lets you split-up your schema however you want while you're building it, but easily combine all those files together when it's time to package or distribute the schema to other people. The resulting schema size will be small, since it will still contain internal JSON references rather than being fully-dereferenced.
    *
@@ -253,33 +259,40 @@ export class $RefParser {
    * @param options (optional)
    * @param callback (optional) A callback that will receive the bundled schema object
    */
-  public static bundle(schema: RefParserSchema): Promise<JSONSchema>;
-  public static bundle(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-  public static bundle(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public static bundle(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-  public static bundle(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public static bundle(
+  public static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+  ): Promise<S>;
+  public static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+    callback: SchemaCallback<S>,
+  ): Promise<void>;
+  public static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+    options: O,
+  ): Promise<S>;
+  public static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+    options: O,
+    callback: SchemaCallback<S>,
+  ): Promise<void>;
+  public static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    baseUrl: string,
+    schema: S | string,
+    options: O,
+  ): Promise<S>;
+  public static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
     baseUrl: string,
-    schema: RefParserSchema,
-    options: ParserOptions,
-    callback: SchemaCallback,
-  ): Promise<JSONSchema>;
-  static bundle(): Promise<JSONSchema> | Promise<void> {
-    const instance = new $RefParser();
+    schema: S | string,
+    options: O,
+    callback: SchemaCallback<S>,
+  ): Promise<S>;
+  static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>():
+    | Promise<S>
+    | Promise<void> {
+    const instance = new $RefParser<S, O>();
     return instance.bundle.apply(instance, arguments as any);
   }
 
-  /**
-   * Parses the given JSON schema, resolves any JSON references, and bundles all external references
-   * into the main JSON schema. This produces a JSON schema that only has *internal* references,
-   * not any *external* references.
-   *
-   * @param [path] - The file path or URL of the JSON schema
-   * @param [schema] - A JSON schema object. This object will be used instead of reading from `path`.
-   * @param [options] - Options that determine how the schema is parsed, resolved, and dereferenced
-   * @param [callback] - An error-first callback. The second parameter is the bundled JSON schema object
-   * @returns - The returned promise resolves with the bundled JSON schema object.
-   */
   /**
    * Bundles all referenced files/URLs into a single schema that only has internal `$ref` pointers. This lets you split-up your schema however you want while you're building it, but easily combine all those files together when it's time to package or distribute the schema to other people. The resulting schema size will be small, since it will still contain internal JSON references rather than being fully-dereferenced.
    *
@@ -291,22 +304,17 @@ export class $RefParser {
    * @param options (optional)
    * @param callback (optional) A callback that will receive the bundled schema object
    */
-  public bundle(schema: RefParserSchema): Promise<JSONSchema>;
-  public bundle(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-  public bundle(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public bundle(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-  public bundle(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public bundle(
-    baseUrl: string,
-    schema: RefParserSchema,
-    options: ParserOptions,
-    callback: SchemaCallback,
-  ): Promise<void>;
+  public bundle(schema: S | string): Promise<S>;
+  public bundle(schema: S | string, callback: SchemaCallback<S>): Promise<void>;
+  public bundle(schema: S | string, options: O): Promise<S>;
+  public bundle(schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+  public bundle(baseUrl: string, schema: S | string, options: O): Promise<S>;
+  public bundle(baseUrl: string, schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
   async bundle() {
-    const args = normalizeArgs(arguments);
+    const args = normalizeArgs<S, O>(arguments);
     try {
       await this.resolve(args.path, args.schema, args.options);
-      _bundle(this, args.options);
+      _bundle<S, O>(this, args.options);
       finalize(this);
       return maybe(args.callback, Promise.resolve(this.schema!));
     } catch (err) {
@@ -314,16 +322,6 @@ export class $RefParser {
     }
   }
 
-  /**
-   * Parses the given JSON schema, resolves any JSON references, and dereferences the JSON schema.
-   * That is, all JSON references are replaced with their resolved values.
-   *
-   * @param [path] - The file path or URL of the JSON schema
-   * @param [schema] - A JSON schema object. This object will be used instead of reading from `path`.
-   * @param [options] - Options that determine how the schema is parsed, resolved, and dereferenced
-   * @param [callback] - An error-first callback. The second parameter is the dereferenced JSON schema object
-   * @returns - The returned promise resolves with the dereferenced JSON schema object.
-   */
   /**
    * Dereferences all `$ref` pointers in the JSON Schema, replacing each reference with its resolved value. This results in a schema object that does not contain any `$ref` pointers. Instead, it's a normal JavaScript object tree that can easily be crawled and used just like any other JavaScript object. This is great for programmatic usage, especially when using tools that don't understand JSON references.
    *
@@ -335,32 +333,40 @@ export class $RefParser {
    * @param options (optional)
    * @param callback (optional) A callback that will receive the dereferenced schema object
    */
-  public static dereference(schema: RefParserSchema): Promise<JSONSchema>;
-  public static dereference(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-  public static dereference(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public static dereference(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-  public static dereference(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public static dereference(
+  public static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+  ): Promise<S>;
+  public static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+    callback: SchemaCallback<S>,
+  ): Promise<void>;
+  public static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+    options: O,
+  ): Promise<S>;
+  public static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    schema: S | string,
+    options: O,
+    callback: SchemaCallback<S>,
+  ): Promise<void>;
+  public static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
     baseUrl: string,
-    schema: RefParserSchema,
-    options: ParserOptions,
-    callback: SchemaCallback,
+    schema: S | string,
+    options: O,
+  ): Promise<S>;
+  public static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    baseUrl: string,
+    schema: S | string,
+    options: O,
+    callback: SchemaCallback<S>,
   ): Promise<void>;
-  static dereference(): Promise<JSONSchema> | Promise<void> {
-    const instance = new $RefParser();
+  static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>():
+    | Promise<S>
+    | Promise<void> {
+    const instance = new $RefParser<S, O>();
     return instance.dereference.apply(instance, arguments as any);
   }
 
-  /**
-   * Parses the given JSON schema, resolves any JSON references, and dereferences the JSON schema.
-   * That is, all JSON references are replaced with their resolved values.
-   *
-   * @param [path] - The file path or URL of the JSON schema
-   * @param [schema] - A JSON schema object. This object will be used instead of reading from `path`.
-   * @param [options] - Options that determine how the schema is parsed, resolved, and dereferenced
-   * @param [callback] - An error-first callback. The second parameter is the dereferenced JSON schema object
-   * @returns - The returned promise resolves with the dereferenced JSON schema object.
-   */
   /**
    * Dereferences all `$ref` pointers in the JSON Schema, replacing each reference with its resolved value. This results in a schema object that does not contain any `$ref` pointers. Instead, it's a normal JavaScript object tree that can easily be crawled and used just like any other JavaScript object. This is great for programmatic usage, especially when using tools that don't understand JSON references.
    *
@@ -368,37 +374,35 @@ export class $RefParser {
    *
    * See https://apitools.dev/json-schema-ref-parser/docs/ref-parser.html#dereferenceschema-options-callback
    *
+   * @param baseUrl
    * @param schema A JSON Schema object, or the file path or URL of a JSON Schema file. See the `parse` method for more info.
    * @param options (optional)
    * @param callback (optional) A callback that will receive the dereferenced schema object
    */
-  public dereference(
-    baseUrl: string,
-    schema: RefParserSchema,
-    options: ParserOptions,
-    callback: SchemaCallback,
-  ): Promise<void>;
-  public dereference(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-  public dereference(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-  public dereference(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public dereference(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-  public dereference(schema: RefParserSchema): Promise<JSONSchema>;
+  public dereference(baseUrl: string, schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+  public dereference(schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+  public dereference(schema: S | string, callback: SchemaCallback<S>): Promise<void>;
+  public dereference(baseUrl: string, schema: S | string, options: O): Promise<S>;
+  public dereference(schema: S | string, options: O): Promise<S>;
+  public dereference(schema: S | string): Promise<S>;
   async dereference() {
-    const args = normalizeArgs(arguments);
+    const args = normalizeArgs<S, O>(arguments);
 
     try {
       await this.resolve(args.path, args.schema, args.options);
       _dereference(this, args.options);
       finalize(this);
-      return maybe(args.callback, Promise.resolve(this.schema));
+      return maybe<S>(args.callback, Promise.resolve(this.schema!) as Promise<S>);
     } catch (err) {
-      return maybe(args.callback, Promise.reject(err));
+      return maybe<S>(args.callback, Promise.reject(err));
     }
   }
 }
 export default $RefParser;
 
-function finalize(parser: any) {
+function finalize<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+  parser: $RefParser<S, O>,
+) {
   const errors = JSONParserErrorGroup.getParserErrors(parser);
   if (errors.length > 0) {
     throw new JSONParserErrorGroup(parser);
@@ -424,4 +428,8 @@ export {
   isHandledError,
   JSONParserErrorGroup,
   SchemaCallback,
+  FileInfo,
+  Plugin,
+  ResolverOptions,
+  HTTPResolverOptions,
 };

package/lib/normalize-args.ts

@@ -1,22 +1,25 @@
+import type { Options, ParserOptions } from "./options.js";
 import { getNewOptions } from "./options.js";
 import type { JSONSchema, SchemaCallback } from "./types";
-import type $RefParserOptions from "./options";
-
-export default normalizeArgs;
 
 // I really dislike this function and the way it's written. It's not clear what it's doing, and it's way too flexible
 // In the future, I'd like to deprecate the api and accept only named parameters in index.ts
-export interface NormalizedArguments {
+export interface NormalizedArguments<S, O> {
   path: string;
-  schema: JSONSchema;
-  options: $RefParserOptions;
-  callback: SchemaCallback;
+  schema: S;
+  options: O & Options;
+  callback: SchemaCallback<S>;
 }
 /**
  * Normalizes the given arguments, accounting for optional args.
  */
-function normalizeArgs(_args: Partial<IArguments>): NormalizedArguments {
-  let path, schema, options, callback;
+export function normalizeArgs<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+  _args: Partial<IArguments>,
+): NormalizedArguments<S, O> {
+  let path;
+  let schema;
+  let options: Options & O;
+  let callback;
   const args = Array.prototype.slice.call(_args) as any[];
 
   if (typeof args[args.length - 1] === "function") {
@@ -44,7 +47,7 @@ function normalizeArgs(_args: Partial<IArguments>): NormalizedArguments {
   }
 
   try {
-    options = getNewOptions(options);
+    options = getNewOptions<S, O>(options);
   } catch (e) {
     console.error(`JSON Schema Ref Parser: Error normalizing options: ${e}`);
   }
@@ -61,3 +64,5 @@ function normalizeArgs(_args: Partial<IArguments>): NormalizedArguments {
     callback,
   };
 }
+
+export default normalizeArgs;

package/lib/options.ts

@@ -5,20 +5,55 @@ import binaryParser from "./parsers/binary.js";
 import fileResolver from "./resolvers/file.js";
 import httpResolver from "./resolvers/http.js";
 
-import type { HTTPResolverOptions, JSONSchemaObject, Plugin, ResolverOptions } from "./types/index.js";
+import type { HTTPResolverOptions, JSONSchema, JSONSchemaObject, Plugin, ResolverOptions } from "./types/index.js";
 
 export type DeepPartial<T> = T extends object
   ? {
       [P in keyof T]?: DeepPartial<T[P]>;
     }
   : T;
+export interface DereferenceOptions {
+  /**
+   * Determines whether circular `$ref` pointers are handled.
+   *
+   * If set to `false`, then a `ReferenceError` will be thrown if the schema contains any circular references.
+   *
+   * If set to `"ignore"`, then circular references will simply be ignored. No error will be thrown, but the `$Refs.circular` property will still be set to `true`.
+   */
+  circular?: boolean | "ignore";
+
+  /**
+   * A function, called for each path, which can return true to stop this path and all
+   * subpaths from being dereferenced further. This is useful in schemas where some
+   * subpaths contain literal $ref keys that should not be dereferenced.
+   */
+  excludedPathMatcher?(path: string): boolean;
+
+  /**
+   * Callback invoked during dereferencing.
+   *
+   * @argument {string} path - The path being dereferenced (ie. the `$ref` string)
+   * @argument {JSONSchemaObject} value - The JSON-Schema that the `$ref` resolved to
+   * @argument {JSONSchemaObject} parent - The parent of the dereferenced object
+   * @argument {string} parentPropName - The prop name of the parent object whose value was dereferenced
+   */
+  onDereference?(path: string, value: JSONSchemaObject, parent?: JSONSchemaObject, parentPropName?: string): void;
+
+  /**
+   * Whether a reference should resolve relative to its directory/path, or from the cwd
+   *
+   * Default: `relative`
+   */
+  externalReferenceResolution?: "relative" | "root";
+}
+
 /**
  * Options that determine how JSON schemas are parsed, resolved, and dereferenced.
  *
  * @param [options] - Overridden options
  * @class
  */
-export interface $RefParserOptions {
+export interface $RefParserOptions<S> {
   /**
    * The `parse` options determine how different types of files will be parsed.
    *
@@ -42,10 +77,10 @@ export interface $RefParserOptions {
      * Determines whether external $ref pointers will be resolved. If this option is disabled, then external `$ref` pointers will simply be ignored.
      */
     external?: boolean;
-    file?: Partial<ResolverOptions> | boolean;
-    http?: HTTPResolverOptions | boolean;
+    file?: Partial<ResolverOptions<S>> | boolean;
+    http?: HTTPResolverOptions<S> | boolean;
   } & {
-    [key: string]: Partial<ResolverOptions> | HTTPResolverOptions | boolean | undefined;
+    [key: string]: Partial<ResolverOptions<S>> | HTTPResolverOptions<S> | boolean | undefined;
   };
 
   /**
@@ -58,47 +93,14 @@ export interface $RefParserOptions {
   /**
    * The `dereference` options control how JSON Schema `$Ref` Parser will dereference `$ref` pointers within the JSON schema.
    */
-  dereference: {
-    /**
-     * Determines whether circular `$ref` pointers are handled.
-     *
-     * If set to `false`, then a `ReferenceError` will be thrown if the schema contains any circular references.
-     *
-     * If set to `"ignore"`, then circular references will simply be ignored. No error will be thrown, but the `$Refs.circular` property will still be set to `true`.
-     */
-    circular?: boolean | "ignore";
-
-    /**
-     * A function, called for each path, which can return true to stop this path and all
-     * subpaths from being dereferenced further. This is useful in schemas where some
-     * subpaths contain literal $ref keys that should not be dereferenced.
-     */
-    excludedPathMatcher?(path: string): boolean;
-
-    /**
-     * Callback invoked during dereferencing.
-     *
-     * @argument {string} path - The path being dereferenced (ie. the `$ref` string)
-     * @argument {JSONSchemaObject} value - The JSON-Schema that the `$ref` resolved to
-     * @argument {JSONSchemaObject} parent - The parent of the dereferenced object
-     * @argument {string} parentPropName - The prop name of the parent object whose value was dereferenced
-     */
-    onDereference?(path: string, value: JSONSchemaObject, parent?: JSONSchemaObject, parentPropName?: string): void;
+  dereference: DereferenceOptions;
 
-    /**
-     * Whether a reference should resolve relative to its directory/path, or from the cwd
-     *
-     * Default: `relative`
-     */
-    externalReferenceResolution?: "relative" | "root";
-
-    /**
-     * Whether to clone the schema before dereferencing it.
-     * This is useful when you want to dereference the same schema multiple times, but you don't want to modify the original schema.
-     * Default: `true` due to mutating the input being the default behavior historically
-     */
-    mutateInputSchema?: boolean;
-  };
+  /**
+   * Whether to clone the schema before dereferencing it.
+   * This is useful when you want to dereference the same schema multiple times, but you don't want to modify the original schema.
+   * Default: `true` due to mutating the input being the default behavior historically
+   */
+  mutateInputSchema?: boolean;
 }
 
 export const getJsonSchemaRefParserDefaultOptions = () => {
@@ -168,19 +170,19 @@ export const getJsonSchemaRefParserDefaultOptions = () => {
     },
 
     mutateInputSchema: true,
-  } as $RefParserOptions;
+  } as $RefParserOptions<JSONSchema>;
   return defaults;
 };
 
-export const getNewOptions = (options: DeepPartial<$RefParserOptions> | undefined): $RefParserOptions => {
+export const getNewOptions = <S, O>(options: O | undefined): O & $RefParserOptions<S> => {
   const newOptions = getJsonSchemaRefParserDefaultOptions();
   if (options) {
     merge(newOptions, options);
   }
-  return newOptions;
+  return newOptions as O & $RefParserOptions<S>;
 };
-export type Options = $RefParserOptions;
-export type ParserOptions = DeepPartial<$RefParserOptions>;
+export type Options = $RefParserOptions<JSONSchema>;
+export type ParserOptions = DeepPartial<$RefParserOptions<JSONSchema>>;
 /**
  * Merges the properties of the source object into the target object.
  *