@apidevtools/json-schema-ref-parser 11.4.2 → 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: S | string,
+    options: O,
+  ): Promise<S>;
+  public static parse<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
     baseUrl: string,
-    schema: RefParserSchema,
-    options: ParserOptions,
-    callback: SchemaCallback,
+    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,19 +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>;
+  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);
@@ -202,19 +216,35 @@ 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: RefParserSchema,
-    options: ParserOptions,
-    callback: $RefsCallback,
+    schema: S | string,
+    options: O,
+  ): Promise<$Refs<S>>;
+  public static resolve<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    baseUrl: string,
+    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);
   }
 
@@ -229,19 +259,37 @@ 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: RefParserSchema,
-    options: ParserOptions,
-    callback: SchemaCallback,
-  ): Promise<JSONSchema>;
-  static bundle(): Promise<JSONSchema> | Promise<void> {
-    const instance = new $RefParser();
+    schema: S | string,
+    options: O,
+  ): Promise<S>;
+  public static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+    baseUrl: string,
+    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);
   }
 
@@ -256,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) {
@@ -290,19 +333,37 @@ 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: S | string,
+    options: O,
+  ): Promise<S>;
+  public static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
     baseUrl: string,
-    schema: RefParserSchema,
-    options: ParserOptions,
-    callback: SchemaCallback,
+    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);
   }
 
@@ -313,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);
@@ -369,4 +428,8 @@ export {
   isHandledError,
   JSONParserErrorGroup,
   SchemaCallback,
+  FileInfo,
+  Plugin,
+  ResolverOptions,
+  HTTPResolverOptions,
 };

package/lib/normalize-args.ts

@@ -1,20 +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";
 
 // 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<T = $RefParserOptions> {
+export interface NormalizedArguments<S, O> {
   path: string;
-  schema: JSONSchema;
-  options: T;
-  callback: SchemaCallback;
+  schema: S;
+  options: O & Options;
+  callback: SchemaCallback<S>;
 }
 /**
  * Normalizes the given arguments, accounting for optional args.
  */
-export function normalizeArgs<T = $RefParserOptions>(_args: Partial<IArguments>): NormalizedArguments<T> {
-  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") {
@@ -42,7 +47,7 @@ export function normalizeArgs<T = $RefParserOptions>(_args: Partial<IArguments>)
   }
 
   try {
-    options = getNewOptions(options);
+    options = getNewOptions<S, O>(options);
   } catch (e) {
     console.error(`JSON Schema Ref Parser: Error normalizing options: ${e}`);
   }

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.
  *

package/lib/parse.ts

@@ -10,14 +10,16 @@ import {
 } from "./util/errors.js";
 import type $Refs from "./refs.js";
 import type { Options } from "./options.js";
-import type { FileInfo } from "./types/index.js";
-
-export default parse;
+import type { FileInfo, JSONSchema } from "./types/index.js";
 
 /**
  * Reads and parses the specified file path or URL.
  */
-async function parse(path: string, $refs: $Refs, options: Options) {
+async function parse<S extends JSONSchema = JSONSchema, O extends Options = Options>(
+  path: string,
+  $refs: $Refs<S>,
+  options: O,
+) {
   // Remove the URL fragment, if any
   const hashIndex = path.indexOf("#");
   let hash = "";
@@ -40,11 +42,11 @@ async function parse(path: string, $refs: $Refs, options: Options) {
 
   // Read the file and then parse the data
   try {
-    const resolver = await readFile(file, options, $refs);
+    const resolver = await readFile<S, O>(file, options, $refs);
     $ref.pathType = resolver.plugin.name;
     file.data = resolver.result;
 
-    const parser = await parseFile(file, options, $refs);
+    const parser = await parseFile<S, O>(file, options, $refs);
     $ref.value = parser.result;
 
     return parser.result;
@@ -64,11 +66,15 @@ async function parse(path: string, $refs: $Refs, options: Options) {
  * @param file.url       - The full URL of the referenced file
  * @param file.extension - The lowercased file extension (e.g. ".txt", ".html", etc.)
  * @param options
- *
+ * @param $refs
  * @returns
  * The promise resolves with the raw file contents and the resolver that was used.
  */
-async function readFile(file: FileInfo, options: Options, $refs: $Refs): Promise<any> {
+async function readFile<S extends JSONSchema = JSONSchema, O extends Options = Options>(
+  file: FileInfo,
+  options: O,
+  $refs: $Refs<S>,
+): Promise<any> {
   // console.log('Reading %s', file.url);
 
   // Find the resolvers that can read this file
@@ -105,11 +111,16 @@ async function readFile(file: FileInfo, options: Options, $refs: $Refs): Promise
  * @param file.extension - The lowercased file extension (e.g. ".txt", ".html", etc.)
  * @param file.data      - The file contents. This will be whatever data type was returned by the resolver
  * @param options
+ * @param $refs
  *
  * @returns
  * The promise resolves with the parsed file contents and the parser that was used.
  */
-async function parseFile(file: FileInfo, options: Options, $refs: $Refs) {
+async function parseFile<S extends JSONSchema = JSONSchema, O extends Options = Options>(
+  file: FileInfo,
+  options: O,
+  $refs: $Refs<S>,
+) {
   // Find the parsers that can read this file type.
   // If none of the parsers are an exact match for this file, then we'll try ALL of them.
   // This handles situations where the file IS a supported type, just with an unknown extension.
@@ -120,7 +131,7 @@ async function parseFile(file: FileInfo, options: Options, $refs: $Refs) {
   // Run the parsers, in order, until one of them succeeds
   plugins.sort(parsers);
   try {
-    const parser = await plugins.run(parsers, "parse", file, $refs);
+    const parser = await plugins.run<S>(parsers, "parse", file, $refs);
     if (!parser.plugin.allowEmpty && isEmpty(parser.result)) {
       throw ono.syntax(`Error parsing "${file.url}" as ${parser.plugin.name}. \nParsed value is empty`);
     } else {
@@ -156,3 +167,4 @@ function isEmpty(value: any) {
     (Buffer.isBuffer(value) && value.length === 0)
   );
 }
+export default parse;