@apidevtools/json-schema-ref-parser - npm Package Compare versions

Comparing version 11.4.2 to 11.5.0

dist/lib/bundle.d.ts

@@ -1,2 +0,4 @@
-export default bundle;
+import type $RefParser from "./index";
+import type { ParserOptions } from "./index";
+import type { JSONSchema } from "./index";
 /**
@@ -10,2 +12,3 @@ * Bundles all external JSON references into the main JSON schema, thus resulting in a schema that
  */
-declare function bundle(parser: any, options: any): void;
+declare function bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(parser: $RefParser<S, O>, options: O): void;
+export default bundle;

dist/lib/bundle.js

@@ -32,3 +32,2 @@ "use strict";
 const url = __importStar(require("./util/url.js"));
-exports.default = bundle;
 /**
@@ -57,2 +56,3 @@ * Bundles all external JSON references into the main JSON schema, thus resulting in a schema that
  * @param pathFromRoot - The path of the property being crawled, from the schema root
+ * @param indirections
  * @param inventory - An array of already-inventoried $ref pointers
@@ -256,5 +256,4 @@ * @param $refs
 function findInInventory(inventory, $refParent, $refKey) {
-    for (let i = 0; i < inventory.length; i++) {
-        const existingEntry = inventory[i];
-        if (existingEntry.parent === $refParent && existingEntry.key === $refKey) {
+    for (const existingEntry of inventory) {
+        if (existingEntry && existingEntry.parent === $refParent && existingEntry.key === $refKey) {
             return existingEntry;
@@ -268,1 +267,2 @@ }
 }
+exports.default = bundle;

dist/lib/dereference.d.ts

@@ -0,1 +1,4 @@
+import type { ParserOptions } from "./options.js";
+import type { JSONSchema } from "./types";
+import type $RefParser from "./index";
 export default dereference;
@@ -9,2 +12,2 @@ /**
  */
-declare function dereference(parser: any, options: any): void;
+declare function dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(parser: $RefParser<S, O>, options: O): void;

dist/lib/dereference.js

@@ -66,4 +66,5 @@ "use strict";
     };
-    const isExcludedPath = options.dereference.excludedPathMatcher || (() => false);
-    if (options.dereference.circular === "ignore" || !processedObjects.has(obj)) {
+    const derefOptions = (options.dereference || {});
+    const isExcludedPath = derefOptions.excludedPathMatcher || (() => false);
+    if (derefOptions?.circular === "ignore" || !processedObjects.has(obj)) {
         if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
@@ -92,5 +93,3 @@ parents.add(obj);
                             obj[key] = dereferenced.value;
-                            if (options.dereference.onDereference) {
-                                options.dereference.onDereference(value.$ref, obj[key], obj, key);
-                            }
+                            derefOptions?.onDereference?.(value.$ref, obj[key], obj, key);
                         }
@@ -135,3 +134,3 @@ }
     const isExternalRef = ref_js_1.default.isExternal$Ref($ref);
-    const shouldResolveOnCwd = isExternalRef && options?.dereference.externalReferenceResolution === "root";
+    const shouldResolveOnCwd = isExternalRef && options?.dereference?.externalReferenceResolution === "root";
     const $refPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref);
@@ -176,3 +175,3 @@ const cache = dereferencedCache.get($refPath);
     }
-    if (circular && !directCircular && options.dereference.circular === "ignore") {
+    if (circular && !directCircular && options.dereference?.circular === "ignore") {
         // The user has chosen to "ignore" circular references, so don't change the value
@@ -179,0 +178,0 @@ dereferencedValue = $ref;

dist/lib/index.d.ts

 import $Refs from "./refs.js";
 import { JSONParserError, InvalidPointerError, MissingPointerError, ResolverError, ParserError, UnmatchedParserError, UnmatchedResolverError, isHandledError, JSONParserErrorGroup } from "./util/errors.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;
@@ -12,3 +12,3 @@ /**
  */
-export declare class $RefParser {
+export declare class $RefParser<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions> {
     /**
@@ -20,3 +20,3 @@ * The parsed (and possibly dereferenced) JSON schema object
      */
-    schema: JSONSchema | null;
+    schema: S | null;
     /**
@@ -28,3 +28,3 @@ * The resolved JSON references
      */
-    $refs: $Refs;
+    $refs: $Refs<S>;
     /**
@@ -41,14 +41,14 @@ * Parses the given JSON schema.
      */
-    parse(schema: RefParserSchema): Promise<JSONSchema>;
-    parse(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-    parse(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    parse(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-    parse(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    parse(baseUrl: string, schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-    static parse(schema: RefParserSchema): Promise<JSONSchema>;
-    static parse(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-    static parse(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    static parse(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-    static parse(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    static parse(baseUrl: string, schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
+    parse(schema: S | string): Promise<S>;
+    parse(schema: S | string, callback: SchemaCallback<S>): Promise<void>;
+    parse(schema: S | string, options: O): Promise<S>;
+    parse(schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+    parse(baseUrl: string, schema: S | string, options: O): Promise<S>;
+    parse(baseUrl: string, schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+    static parse<S extends JSONSchema = JSONSchema>(schema: S | string): Promise<S>;
+    static parse<S extends JSONSchema = JSONSchema>(schema: S | string, callback: SchemaCallback<S>): Promise<void>;
+    static parse<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string, options: O): Promise<S>;
+    static parse<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+    static parse<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(baseUrl: string, schema: S | string, options: O): Promise<S>;
+    static parse<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(baseUrl: string, schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
     /**
@@ -65,8 +65,8 @@ * *This method is used internally by other methods, such as `bundle` and `dereference`. You probably won't need to call this method yourself.*
      */
-    resolve(schema: RefParserSchema): Promise<$Refs>;
-    resolve(schema: RefParserSchema, callback: $RefsCallback): Promise<void>;
-    resolve(schema: RefParserSchema, options: ParserOptions): Promise<$Refs>;
-    resolve(schema: RefParserSchema, options: ParserOptions, callback: $RefsCallback): Promise<void>;
-    resolve(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<$Refs>;
-    resolve(baseUrl: string, schema: RefParserSchema, options: ParserOptions, callback: $RefsCallback): Promise<void>;
+    resolve(schema: S | string): Promise<$Refs<S>>;
+    resolve(schema: S | string, callback: $RefsCallback<S>): Promise<void>;
+    resolve(schema: S | string, options: O): Promise<$Refs<S>>;
+    resolve(schema: S | string, options: O, callback: $RefsCallback<S>): Promise<void>;
+    resolve(baseUrl: string, schema: S | string, options: O): Promise<$Refs<S>>;
+    resolve(baseUrl: string, schema: S | string, options: O, callback: $RefsCallback<S>): Promise<void>;
     /**
@@ -83,8 +83,8 @@ * *This method is used internally by other methods, such as `bundle` and `dereference`. You probably won't need to call this method yourself.*
      */
-    static resolve(schema: RefParserSchema): Promise<$Refs>;
-    static resolve(schema: RefParserSchema, callback: $RefsCallback): Promise<void>;
-    static resolve(schema: RefParserSchema, options: ParserOptions): Promise<$Refs>;
-    static resolve(schema: RefParserSchema, options: ParserOptions, callback: $RefsCallback): Promise<void>;
-    static resolve(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<$Refs>;
-    static resolve(baseUrl: string, schema: RefParserSchema, options: ParserOptions, callback: $RefsCallback): Promise<void>;
+    static resolve<S extends JSONSchema = JSONSchema>(schema: S | string): Promise<$Refs<S>>;
+    static resolve<S extends JSONSchema = JSONSchema>(schema: S | string, callback: $RefsCallback<S>): Promise<void>;
+    static resolve<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string, options: O): Promise<$Refs<S>>;
+    static resolve<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string, options: O, callback: $RefsCallback<S>): Promise<void>;
+    static resolve<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(baseUrl: string, schema: S | string, options: O): Promise<$Refs<S>>;
+    static resolve<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(baseUrl: string, schema: S | string, options: O, callback: $RefsCallback<S>): Promise<void>;
     /**
@@ -101,8 +101,8 @@ * 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.
      */
-    static bundle(schema: RefParserSchema): Promise<JSONSchema>;
-    static bundle(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-    static bundle(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    static bundle(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-    static bundle(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    static bundle(baseUrl: string, schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<JSONSchema>;
+    static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string): Promise<S>;
+    static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string, callback: SchemaCallback<S>): Promise<void>;
+    static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string, options: O): Promise<S>;
+    static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+    static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(baseUrl: string, schema: S | string, options: O): Promise<S>;
+    static bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(baseUrl: string, schema: S | string, options: O, callback: SchemaCallback<S>): Promise<S>;
     /**
@@ -119,8 +119,8 @@ * 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.
      */
-    bundle(schema: RefParserSchema): Promise<JSONSchema>;
-    bundle(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-    bundle(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    bundle(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-    bundle(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    bundle(baseUrl: string, schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
+    bundle(schema: S | string): Promise<S>;
+    bundle(schema: S | string, callback: SchemaCallback<S>): Promise<void>;
+    bundle(schema: S | string, options: O): Promise<S>;
+    bundle(schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+    bundle(baseUrl: string, schema: S | string, options: O): Promise<S>;
+    bundle(baseUrl: string, schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
     /**
@@ -137,8 +137,8 @@ * 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.
      */
-    static dereference(schema: RefParserSchema): Promise<JSONSchema>;
-    static dereference(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-    static dereference(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    static dereference(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-    static dereference(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    static dereference(baseUrl: string, schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
+    static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string): Promise<S>;
+    static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string, callback: SchemaCallback<S>): Promise<void>;
+    static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string, options: O): Promise<S>;
+    static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+    static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(baseUrl: string, schema: S | string, options: O): Promise<S>;
+    static dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(baseUrl: string, schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
     /**
@@ -151,2 +151,3 @@ * 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.
      *
+     * @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.
@@ -156,8 +157,8 @@ * @param options (optional)
      */
-    dereference(baseUrl: string, schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-    dereference(schema: RefParserSchema, options: ParserOptions, callback: SchemaCallback): Promise<void>;
-    dereference(schema: RefParserSchema, callback: SchemaCallback): Promise<void>;
-    dereference(baseUrl: string, schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    dereference(schema: RefParserSchema, options: ParserOptions): Promise<JSONSchema>;
-    dereference(schema: RefParserSchema): Promise<JSONSchema>;
+    dereference(baseUrl: string, schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+    dereference(schema: S | string, options: O, callback: SchemaCallback<S>): Promise<void>;
+    dereference(schema: S | string, callback: SchemaCallback<S>): Promise<void>;
+    dereference(baseUrl: string, schema: S | string, options: O): Promise<S>;
+    dereference(schema: S | string, options: O): Promise<S>;
+    dereference(schema: S | string): Promise<S>;
 }
@@ -169,2 +170,2 @@ export default $RefParser;
 export declare const dereference: typeof $RefParser.dereference;
-export { UnmatchedResolverError, JSONParserError, JSONSchema, InvalidPointerError, MissingPointerError, ResolverError, ParserError, UnmatchedParserError, ParserOptions, $RefsCallback, isHandledError, JSONParserErrorGroup, SchemaCallback, };
+export { UnmatchedResolverError, JSONParserError, JSONSchema, InvalidPointerError, MissingPointerError, ResolverError, ParserError, UnmatchedParserError, ParserOptions, $RefsCallback, isHandledError, JSONParserErrorGroup, SchemaCallback, FileInfo, Plugin, ResolverOptions, HTTPResolverOptions, };

dist/lib/normalize-args.d.ts

@@ -0,8 +1,8 @@
+import type { Options, ParserOptions } from "./options.js";
 import type { JSONSchema, SchemaCallback } from "./types";
-import type $RefParserOptions from "./options";
-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>;
 }
@@ -12,3 +12,3 @@ /**
  */
-export declare function normalizeArgs<T = $RefParserOptions>(_args: Partial<IArguments>): NormalizedArguments<T>;
+export declare function normalizeArgs<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(_args: Partial<IArguments>): NormalizedArguments<S, O>;
 export default normalizeArgs;

dist/lib/normalize-args.js

@@ -9,3 +9,6 @@ "use strict";
 function normalizeArgs(_args) {
-    let path, schema, options, callback;
+    let path;
+    let schema;
+    let options;
+    let callback;
     const args = Array.prototype.slice.call(_args);
@@ -12,0 +15,0 @@ if (typeof args[args.length - 1] === "function") {

dist/lib/options.d.ts

@@ -1,5 +0,36 @@
-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";
+}
 /**
@@ -11,3 +42,3 @@ * Options that determine how JSON schemas are parsed, resolved, and dereferenced.
  */
-export interface $RefParserOptions {
+export interface $RefParserOptions<S> {
     /**
@@ -37,6 +68,6 @@ * The `parse` options determine how different types of files will be parsed.
         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;
     };
@@ -52,44 +83,14 @@ /**
      */
-    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;
-        /**
-         * 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;
-    };
+    dereference: DereferenceOptions;
+    /**
+     * 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 declare const getJsonSchemaRefParserDefaultOptions: () => $RefParserOptions;
-export declare const getNewOptions: (options: DeepPartial<$RefParserOptions> | undefined) => $RefParserOptions;
-export type Options = $RefParserOptions;
-export type ParserOptions = DeepPartial<$RefParserOptions>;
+export declare const getJsonSchemaRefParserDefaultOptions: () => $RefParserOptions<JSONSchema>;
+export declare const getNewOptions: <S, O>(options: O | undefined) => O & $RefParserOptions<S>;
+export type Options = $RefParserOptions<JSONSchema>;
+export type ParserOptions = DeepPartial<$RefParserOptions<JSONSchema>>;
 export default $RefParserOptions;

dist/lib/parse.d.ts

 /// <reference types="node" />
 import type $Refs from "./refs.js";
 import type { Options } from "./options.js";
-export default parse;
+import type { JSONSchema } from "./types/index.js";
 /**
  * Reads and parses the specified file path or URL.
  */
-declare function parse(path: string, $refs: $Refs, options: Options): Promise<string | import("./types/index.js").JSONSchema | Buffer | undefined>;
+declare function parse<S extends JSONSchema = JSONSchema, O extends Options = Options>(path: string, $refs: $Refs<S>, options: O): Promise<string | Buffer | S | undefined>;
+export default parse;

dist/lib/parse.js

@@ -30,3 +30,2 @@ "use strict";
 const errors_js_1 = require("./util/errors.js");
-exports.default = parse;
 /**
@@ -76,3 +75,3 @@ * Reads and parses the specified file path or URL.
  * @param options
- *
+ * @param $refs
  * @returns
@@ -118,2 +117,3 @@ * The promise resolves with the raw file contents and the resolver that was used.
  * @param options
+ * @param $refs
  *
@@ -172,1 +172,2 @@ * @returns
 }
+exports.default = parse;

dist/lib/pointer.d.ts

 import type $RefParserOptions from "./options.js";
 import $Ref from "./ref.js";
+import type { JSONSchema } from "./types";
 /**
@@ -11,7 +12,7 @@ * This class represents a single JSON pointer and its resolved value.
  */
-declare class Pointer {
+declare class Pointer<S = JSONSchema> {
     /**
      * The {@link $Ref} object that contains this {@link Pointer} object.
      */
-    $ref: $Ref;
+    $ref: $Ref<S>;
     /**
@@ -40,3 +41,3 @@ * The file path or URL, containing the JSON pointer in the hash.
     indirections: number;
-    constructor($ref: $Ref, path: string, friendlyPath?: string);
+    constructor($ref: $Ref<S>, path: string, friendlyPath?: string);
     /**
@@ -55,3 +56,3 @@ * Resolves the value of a nested property within the given object.
      */
-    resolve(obj: any, options?: $RefParserOptions, pathFromRoot?: string): this;
+    resolve(obj: any, options?: $RefParserOptions<S>, pathFromRoot?: string): this;
     /**
@@ -67,3 +68,3 @@ * Sets the value of a nested property within the given object.
      */
-    set(obj: any, value: any, options?: $RefParserOptions): any;
+    set(obj: any, value: any, options?: $RefParserOptions<S>): any;
     /**
@@ -70,0 +71,0 @@ * Parses a JSON pointer (or a path containing a JSON pointer in the hash)

dist/lib/ref.d.ts

@@ -5,2 +5,3 @@ import Pointer from "./pointer.js";
 import type $RefParserOptions from "./options.js";
+import type { ParserOptions } from "./options.js";
 import type { JSONSchema } from "./types";
@@ -13,3 +14,3 @@ export type $RefError = JSONParserError | ResolverError | ParserError | MissingPointerError;
  */
-declare class $Ref {
+declare class $Ref<S = JSONSchema> {
     /**
@@ -38,3 +39,3 @@ * The file path or URL of the referenced file.
      */
-    $refs: $Refs;
+    $refs: $Refs<S>;
     /**
@@ -48,3 +49,3 @@ * Indicates the type of {@link $Ref#path} (e.g. "file", "http", etc.)
     errors: Array<$RefError>;
-    constructor($refs: $Refs);
+    constructor($refs: $Refs<S>);
     /**
@@ -64,3 +65,3 @@ * Pushes an error to errors array.
      */
-    exists(path: string, options?: $RefParserOptions): boolean;
+    exists(path: string, options?: $RefParserOptions<S>): boolean;
     /**
@@ -73,3 +74,3 @@ * Resolves the given JSON reference within this {@link $Ref#value} and returns the resolved value.
      */
-    get(path: any, options: $RefParserOptions): any;
+    get(path: string, options?: $RefParserOptions<S>): any;
     /**
@@ -84,3 +85,3 @@ * Resolves the given JSON reference within this {@link $Ref#value}.
      */
-    resolve(path: any, options?: $RefParserOptions, friendlyPath?: string, pathFromRoot?: string): Pointer | null;
+    resolve(path: string, options?: $RefParserOptions<S>, friendlyPath?: string, pathFromRoot?: string): Pointer<S> | null;
     /**
@@ -119,3 +120,3 @@ * Sets the value of a nested property within this {@link $Ref#value}.
      */
-    static isAllowed$Ref(value: unknown, options?: $RefParserOptions): true | undefined;
+    static isAllowed$Ref(value: unknown, options?: ParserOptions): true | undefined;
     /**
@@ -187,4 +188,4 @@ * Determines whether the given value is a JSON reference that "extends" its resolved value.
      */
-    static dereference($ref: $Ref, resolvedValue: JSONSchema): JSONSchema;
+    static dereference<S>($ref: $Ref<S>, resolvedValue: S): S;
 }
 export default $Ref;

dist/lib/ref.js

@@ -145,3 +145,3 @@ "use strict";
             }
-            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
@@ -148,0 +148,0 @@ return true;

dist/lib/refs.d.ts

 import $Ref from "./ref.js";
 import type { JSONSchema4Type, JSONSchema6Type, JSONSchema7Type } from "json-schema";
-import type { JSONSchema } from "./types/index.js";
 import type $RefParserOptions from "./options.js";
-interface $RefsMap {
-    [url: string]: $Ref;
+import type { JSONSchema } from "./types";
+interface $RefsMap<S> {
+    [url: string]: $Ref<S>;
 }
@@ -15,3 +15,3 @@ /**
  */
-export default class $Refs {
+export default class $Refs<S = JSONSchema> {
     /**
@@ -38,3 +38,3 @@ * 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.
      */
-    values(...types: string[]): JSONSchema;
+    values(...types: string[]): S;
     /**
@@ -62,10 +62,10 @@ * Returns `true` if the given path exists in the schema; otherwise, returns `false`
      */
-    get(path: string, options?: $RefParserOptions): JSONSchema4Type | JSONSchema6Type | JSONSchema7Type;
+    get(path: string, options?: $RefParserOptions<S>): JSONSchema4Type | JSONSchema6Type | JSONSchema7Type;
     /**
      * 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): void;
+    set(path: string, value: JSONSchema4Type | JSONSchema6Type | JSONSchema7Type): void;
     /**
@@ -78,3 +78,3 @@ * Returns the specified {@link $Ref} object, or undefined.
      */
-    _get$Ref(path: any): $Ref;
+    _get$Ref(path: any): $Ref<S>;
     /**
@@ -85,3 +85,3 @@ * Creates a new {@link $Ref} object and adds it to this {@link $Refs} object.
      */
-    _add(path: string): $Ref;
+    _add(path: string): $Ref<S>;
     /**
@@ -96,3 +96,3 @@ * Resolves the given JSON reference.
      */
-    _resolve(path: string, pathFromRoot: string, options?: any): import("./pointer.js").default | null;
+    _resolve(path: string, pathFromRoot: string, options?: any): import("./pointer.js").default<S> | null;
     /**
@@ -104,3 +104,3 @@ * A map of paths/urls to {@link $Ref} objects
      */
-    _$refs: $RefsMap;
+    _$refs: $RefsMap<S>;
     /**
@@ -112,3 +112,3 @@ * The {@link $Ref} object that is the root of the JSON schema.
      */
-    _root$Ref: $Ref;
+    _root$Ref: $Ref<S>;
     constructor();
@@ -133,4 +133,4 @@ /**
      */
-    toJSON: (...types: string[]) => JSONSchema;
+    toJSON: (...types: string[]) => S;
 }
 export {};

dist/lib/refs.js

@@ -105,3 +105,3 @@ "use strict";
      *
-     * @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.)
@@ -108,0 +108,0 @@ */

dist/lib/resolve-external.d.ts

@@ -1,4 +0,4 @@
-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;
 /**
@@ -14,2 +14,3 @@ * Crawls the JSON schema, finds all external JSON references, and resolves their values.
  */
-declare function resolveExternal(parser: $RefParser, options: Options): Promise<void> | Promise<any[]>;
+declare function resolveExternal<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(parser: $RefParser<S, O>, options: Options): Promise<void> | Promise<any[]>;
+export default resolveExternal;

dist/lib/resolve-external.js

@@ -34,3 +34,2 @@ "use strict";
 const errors_js_1 = require("./util/errors.js");
-exports.default = resolveExternal;
 /**
@@ -111,6 +110,6 @@ * Crawls the JSON schema, finds all external JSON references, and resolves their values.
     // 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);
     }
@@ -136,1 +135,2 @@ // Parse the $referenced file/url
 }
+exports.default = resolveExternal;

dist/lib/resolvers/file.d.ts

@@ -1,3 +0,3 @@
-import type { ResolverOptions } from "../types/index.js";
-declare const _default: ResolverOptions;
+import type { JSONSchema, ResolverOptions } from "../types/index.js";
+declare const _default: ResolverOptions<JSONSchema>;
 export default _default;

dist/lib/resolvers/http.d.ts

@@ -1,3 +0,3 @@
-import type { HTTPResolverOptions } from "../types/index.js";
-declare const _default: HTTPResolverOptions;
+import type { HTTPResolverOptions, JSONSchema } from "../types/index.js";
+declare const _default: HTTPResolverOptions<JSONSchema>;
 export default _default;

dist/lib/types/index.d.ts

@@ -6,8 +6,8 @@ /// <reference types="node" />
 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>> {
     /**
@@ -35,3 +35,3 @@ * 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.
  */
-export interface ResolverOptions {
+export interface ResolverOptions<S = JSONSchema> {
     name?: string;
@@ -53,3 +53,3 @@ /**
      */
-    read: string | object | ((file: FileInfo, callback?: (error: Error | null, data: string | null) => any) => string | Buffer | JSONSchema | Promise<string | Buffer | JSONSchema>);
+    read: string | object | ((file: FileInfo, callback?: (error: Error | null, data: string | null) => any) => string | Buffer | S | Promise<string | Buffer | S>);
 }
@@ -56,0 +56,0 @@ export interface Plugin {

dist/lib/util/errors.d.ts

 import type $RefParser from "../index.js";
+import type { ParserOptions } from "../index.js";
+import type { JSONSchema } from "../index.js";
 export type JSONParserErrorType = "EUNKNOWN" | "EPARSER" | "EUNMATCHEDPARSER" | "ERESOLVER" | "EUNMATCHEDRESOLVER" | "EMISSINGPOINTER" | "EINVALIDPOINTER";
@@ -12,6 +14,6 @@ export declare class JSONParserError extends Error {
 }
-export declare class JSONParserErrorGroup extends Error {
-    files: $RefParser;
-    constructor(parser: $RefParser);
-    static getParserErrors(parser: any): JSONParserError[];
+export declare class JSONParserErrorGroup<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions> extends Error {
+    files: $RefParser<S, O>;
+    constructor(parser: $RefParser<S, O>);
+    static getParserErrors<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(parser: $RefParser<S, O>): JSONParserError[];
     get errors(): Array<JSONParserError | InvalidPointerError | ResolverError | ParserError | MissingPointerError | UnmatchedParserError | UnmatchedResolverError>;
@@ -18,0 +20,0 @@ }

dist/lib/util/plugins.d.ts

@@ -7,3 +7,2 @@ /// <reference types="node" />
 import type { Plugin } from "../types/index.js";
-import type { JSONSchema } from "../types/index.js";
 /**
@@ -15,3 +14,3 @@ * Returns the given plugins as an array, rather than an object map.
  */
-export declare function all(plugins: $RefParserOptions["resolve"]): Plugin[];
+export declare function all<S>(plugins: $RefParserOptions<S>["resolve"]): Plugin[];
 /**
@@ -25,5 +24,5 @@ * Filters the given plugins, returning only the ones return `true` for the given method.
 export declare function sort(plugins: Plugin[]): Plugin[];
-export interface PluginResult {
+export interface PluginResult<S> {
     plugin: Plugin;
-    result?: string | Buffer | JSONSchema;
+    result?: string | Buffer | S;
     error?: any;
@@ -39,2 +38,2 @@ }
  */
-export declare function run(plugins: Plugin[], method: keyof Plugin | keyof ResolverOptions, file: FileInfo, $refs: $Refs): Promise<PluginResult>;
+export declare function run<S>(plugins: Plugin[], method: keyof Plugin | keyof ResolverOptions<S>, file: FileInfo, $refs: $Refs<S>): Promise<PluginResult<S>>;

lib/bundle.ts

 import $Ref from "./ref.js";
 import Pointer from "./pointer.js";
 import * as url from "./util/url.js";
-import type $RefParserOptions from "./options.js";
 import type $Refs from "./refs.js";
+import type $RefParser from "./index";
+import type { ParserOptions } from "./index";
+import type { JSONSchema } from "./index";
 
-export default bundle;
-
 /**
@@ -17,3 +17,6 @@ * Bundles all external JSON references into the main JSON schema, thus resulting in a schema that
  */
-function bundle(parser: any, options: any) {
+function bundle<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+  parser: $RefParser<S, O>,
+  options: O,
+) {
   // console.log('Bundling $ref pointers in %s', parser.$refs._root$Ref.path);
@@ -23,3 +26,3 @@
   const inventory: any = [];
-  crawl(parser, "schema", parser.$refs._root$Ref.path + "#", "#", 0, inventory, parser.$refs, options);
+  crawl<S, O>(parser, "schema", parser.$refs._root$Ref.path + "#", "#", 0, inventory, parser.$refs, options);
 
@@ -37,2 +40,3 @@ // Remap all $ref pointers
  * @param pathFromRoot - The path of the property being crawled, from the schema root
+ * @param indirections
  * @param inventory - An array of already-inventoried $ref pointers
@@ -42,11 +46,11 @@ * @param $refs
  */
-function crawl(
+function crawl<S, O>(
   parent: any,
-  key: any,
-  path: any,
-  pathFromRoot: any,
-  indirections: any,
-  inventory: any,
-  $refs: any,
-  options: any,
+  key: string | null,
+  path: string,
+  pathFromRoot: string,
+  indirections: number,
+  inventory: unknown[],
+  $refs: $Refs<S>,
+  options: O,
 ) {
@@ -105,3 +109,3 @@ const obj = key === null ? parent : parent[key];
  */
-function inventory$Ref(
+function inventory$Ref<S, O>(
   $refParent: any,
@@ -113,4 +117,4 @@ $refKey: any,
   inventory: any,
-  $refs: $Refs,
-  options: $RefParserOptions,
+  $refs: $Refs<S>,
+  options: O,
 ) {
@@ -257,5 +261,4 @@ const $ref = $refKey === null ? $refParent : $refParent[$refKey];
 function findInInventory(inventory: any, $refParent: any, $refKey: any) {
-  for (let i = 0; i < inventory.length; i++) {
-    const existingEntry = inventory[i];
-    if (existingEntry.parent === $refParent && existingEntry.key === $refKey) {
+  for (const existingEntry of inventory) {
+    if (existingEntry && existingEntry.parent === $refParent && existingEntry.key === $refKey) {
       return existingEntry;
@@ -270,1 +273,2 @@ }
 }
+export default bundle;

lib/dereference.ts

@@ -6,3 +6,5 @@ import $Ref from "./ref.js";
 import type $Refs from "./refs.js";
-import type $RefParserOptions from "./options.js";
+import type { DereferenceOptions, ParserOptions } from "./options.js";
+import type { JSONSchema } from "./types";
+import type $RefParser from "./index";
 
@@ -18,7 +20,10 @@ export default dereference;
  */
-function dereference(parser: any, options: any) {
+function dereference<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+  parser: $RefParser<S, O>,
+  options: O,
+) {
   // console.log('Dereferencing $ref pointers in %s', parser.$refs._root$Ref.path);
-  const dereferenced = crawl(
+  const dereferenced = crawl<S, O>(
     parser.schema,
-    parser.$refs._root$Ref.path,
+    parser.$refs._root$Ref.path!,
     "#",
@@ -48,3 +53,3 @@ new Set(),
  */
-function crawl(
+function crawl<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
   obj: any,
@@ -56,4 +61,4 @@ path: string,
   dereferencedCache: any,
-  $refs: $Refs,
-  options: $RefParserOptions,
+  $refs: $Refs<S>,
+  options: O,
 ) {
@@ -66,5 +71,6 @@ let dereferenced;
 
-  const isExcludedPath = options.dereference.excludedPathMatcher || (() => false);
+  const derefOptions = (options.dereference || {}) as DereferenceOptions;
+  const isExcludedPath = derefOptions.excludedPathMatcher || (() => false);
 
-  if (options.dereference.circular === "ignore" || !processedObjects.has(obj)) {
+  if (derefOptions?.circular === "ignore" || !processedObjects.has(obj)) {
     if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
@@ -114,5 +120,3 @@ parents.add(obj);
               obj[key] = dereferenced.value;
-              if (options.dereference.onDereference) {
-                options.dereference.onDereference(value.$ref, obj[key], obj, key);
-              }
+              derefOptions?.onDereference?.(value.$ref, obj[key], obj, key);
             }
@@ -166,3 +170,3 @@ } else {
  */
-function dereference$Ref(
+function dereference$Ref<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
   $ref: any,
@@ -174,7 +178,7 @@ path: string,
   dereferencedCache: any,
-  $refs: $Refs,
-  options: $RefParserOptions,
+  $refs: $Refs<S>,
+  options: O,
 ) {
   const isExternalRef = $Ref.isExternal$Ref($ref);
-  const shouldResolveOnCwd = isExternalRef && options?.dereference.externalReferenceResolution === "root";
+  const shouldResolveOnCwd = isExternalRef && options?.dereference?.externalReferenceResolution === "root";
   const $refPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref);
@@ -236,3 +240,3 @@
 
-  if (circular && !directCircular && options.dereference.circular === "ignore") {
+  if (circular && !directCircular && options.dereference?.circular === "ignore") {
     // The user has chosen to "ignore" circular references, so don't change the value
@@ -239,0 +243,0 @@ dereferencedValue = $ref;

lib/index.ts

@@ -22,3 +22,11 @@ import $Refs from "./refs.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";
 
@@ -33,3 +41,3 @@ export type RefParserSchema = string | JSONSchema;
  */
-export class $RefParser {
+export class $RefParser<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions> {
   /**
@@ -41,3 +49,3 @@ * The parsed (and possibly dereferenced) JSON schema object
    */
-  public schema: JSONSchema | null = null;
+  public schema: S | null = null;
 
@@ -50,3 +58,3 @@ /**
    */
-  $refs = new $Refs();
+  $refs = new $Refs<S>();
 
@@ -64,15 +72,10 @@ /**
    */
-  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;
@@ -120,3 +123,3 @@
       // 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);
     }
@@ -149,15 +152,31 @@
 
-  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);
@@ -177,15 +196,10 @@ }
    */
-  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);
 
@@ -213,15 +227,31 @@ try {
    */
-  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);
@@ -241,15 +271,33 @@ }
    */
-  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);
@@ -269,18 +317,13 @@ }
    */
-  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);
@@ -304,15 +347,33 @@ return maybe(args.callback, Promise.resolve(this.schema!));
    */
-  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);
@@ -328,2 +389,3 @@ }
    *
+   * @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.
@@ -333,15 +395,10 @@ * @param options (optional)
    */
-  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);
 
@@ -352,5 +409,5 @@ try {
       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));
     }
@@ -361,3 +418,5 @@ }
 
-function finalize(parser: any) {
+function finalize<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions>(
+  parser: $RefParser<S, O>,
+) {
   const errors = JSONParserErrorGroup.getParserErrors(parser);
@@ -388,2 +447,6 @@ if (errors.length > 0) {
   SchemaCallback,
+  FileInfo,
+  Plugin,
+  ResolverOptions,
+  HTTPResolverOptions,
 };

lib/normalize-args.ts

@@ -0,12 +1,12 @@
+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>;
 }
@@ -16,4 +16,9 @@ /**
  */
-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[];
@@ -46,3 +51,3 @@
   try {
-    options = getNewOptions(options);
+    options = getNewOptions<S, O>(options);
   } catch (e) {
@@ -49,0 +54,0 @@ console.error(`JSON Schema Ref Parser: Error normalizing options: ${e}`);

lib/options.ts

@@ -8,3 +8,3 @@ import jsonParser from "./parsers/json.js";
 
-import type { HTTPResolverOptions, JSONSchemaObject, Plugin, ResolverOptions } from "./types/index.js";
+import type { HTTPResolverOptions, JSONSchema, JSONSchemaObject, Plugin, ResolverOptions } from "./types/index.js";
 
@@ -16,2 +16,37 @@ export type DeepPartial<T> = T extends object
   : 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";
+}
+
 /**
@@ -23,3 +58,3 @@ * Options that determine how JSON schemas are parsed, resolved, and dereferenced.
  */
-export interface $RefParserOptions {
+export interface $RefParserOptions<S> {
   /**
@@ -48,6 +83,6 @@ * The `parse` options determine how different types of files will be parsed.
     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;
   };
@@ -65,43 +100,10 @@
    */
-  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";
+  dereference: DereferenceOptions;
 
-    /**
-     * 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";
-
-    /**
-     * 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;
 }
@@ -176,7 +178,7 @@
     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();
@@ -186,6 +188,6 @@ if (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>>;
 /**
@@ -192,0 +194,0 @@ * Merges the properties of the source object into the target object.

lib/parse.ts

@@ -13,10 +13,12 @@ import { ono } from "@jsdevtools/ono";
 import type { Options } from "./options.js";
-import type { FileInfo } from "./types/index.js";
+import type { FileInfo, JSONSchema } from "./types/index.js";
 
-export default parse;
-
 /**
  * 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
@@ -44,7 +46,7 @@ const hashIndex = path.indexOf("#");
   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;
@@ -69,7 +71,11 @@
  * @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);
@@ -111,2 +117,3 @@
  * @param options
+ * @param $refs
  *
@@ -116,3 +123,7 @@ * @returns
  */
-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.
@@ -128,3 +139,3 @@ // If none of the parsers are an exact match for this file, then we'll try ALL of them.
   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)) {
@@ -165,1 +176,2 @@ throw ono.syntax(`Error parsing "${file.url}" as ${parser.plugin.name}. \nParsed value is empty`);
 }
+export default parse;

lib/pointer.ts

@@ -6,2 +6,3 @@ import type $RefParserOptions from "./options.js";
 import { JSONParserError, InvalidPointerError, MissingPointerError, isHandledError } from "./util/errors.js";
+import type { JSONSchema } from "./types";
 
@@ -29,7 +30,7 @@ const slashes = /\//g;
  */
-class Pointer {
+class Pointer<S = JSONSchema> {
   /**
    * The {@link $Ref} object that contains this {@link Pointer} object.
    */
-  $ref: $Ref;
+  $ref: $Ref<S>;
 
@@ -63,3 +64,3 @@ /**
 
-  constructor($ref: $Ref, path: string, friendlyPath?: string) {
+  constructor($ref: $Ref<S>, path: string, friendlyPath?: string) {
     this.$ref = $ref;
@@ -91,3 +92,3 @@
    */
-  resolve(obj: any, options?: $RefParserOptions, pathFromRoot?: string) {
+  resolve(obj: any, options?: $RefParserOptions<S>, pathFromRoot?: string) {
     const tokens = Pointer.parse(this.path, this.originalPath);
@@ -150,3 +151,3 @@
    */
-  set(obj: any, value: any, options?: $RefParserOptions) {
+  set(obj: any, value: any, options?: $RefParserOptions<S>) {
     const tokens = Pointer.parse(this.path);
@@ -153,0 +154,0 @@ let token;

lib/ref.ts

@@ -7,2 +7,3 @@ import Pointer from "./pointer.js";
 import type $RefParserOptions from "./options.js";
+import type { ParserOptions } from "./options.js";
 import type { JSONSchema } from "./types";
@@ -17,3 +18,3 @@
  */
-class $Ref {
+class $Ref<S = JSONSchema> {
   /**
@@ -44,3 +45,3 @@ * The file path or URL of the referenced file.
    */
-  $refs: $Refs;
+  $refs: $Refs<S>;
 
@@ -57,3 +58,3 @@ /**
 
-  constructor($refs: $Refs) {
+  constructor($refs: $Refs<S>) {
     this.$refs = $refs;
@@ -94,3 +95,3 @@ }
    */
-  exists(path: string, options?: $RefParserOptions) {
+  exists(path: string, options?: $RefParserOptions<S>) {
     try {
@@ -111,3 +112,3 @@ this.resolve(path, options);
    */
-  get(path: any, options: $RefParserOptions) {
+  get(path: string, options?: $RefParserOptions<S>) {
     return this.resolve(path, options)?.value;
@@ -125,4 +126,4 @@ }
    */
-  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 {
@@ -195,3 +196,3 @@ return pointer.resolve(this.value, options, pathFromRoot);
    */
-  static isAllowed$Ref(value: unknown, options?: $RefParserOptions) {
+  static isAllowed$Ref(value: unknown, options?: ParserOptions) {
     if (this.is$Ref(value)) {
@@ -201,3 +202,3 @@ if (value.$ref.substring(0, 2) === "#/" || value.$ref === "#") {
         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
@@ -278,3 +279,3 @@ return true;
    */
-  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)) {
@@ -296,3 +297,3 @@ const merged = {};
 
-      return merged;
+      return merged as S;
     } else {
@@ -299,0 +300,0 @@ // Completely replace the original reference with the resolved value

lib/refs.ts

@@ -5,8 +5,8 @@ import { ono } from "@jsdevtools/ono";
 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>;
 }
@@ -20,3 +20,3 @@ /**
  */
-export default class $Refs {
+export default class $Refs<S = JSONSchema> {
   /**
@@ -50,3 +50,3 @@ * 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.
    */
-  values(...types: string[]): JSONSchema {
+  values(...types: string[]): S {
     const $refs = this._$refs;
@@ -57,3 +57,3 @@ const paths = getPaths($refs, types);
       return obj;
-    }, {});
+    }, {}) as S;
   }
@@ -91,3 +91,3 @@
    */
-  get(path: string, options?: $RefParserOptions): JSONSchema4Type | JSONSchema6Type | JSONSchema7Type {
+  get(path: string, options?: $RefParserOptions<S>): JSONSchema4Type | JSONSchema6Type | JSONSchema7Type {
     return this._resolve(path, "", options)!.value;
@@ -99,6 +99,6 @@ }
    *
-   * @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);
@@ -135,3 +135,3 @@ const withoutHash = url.stripHash(absPath);
 
-    const $ref = new $Ref(this);
+    const $ref = new $Ref<S>(this);
     $ref.path = withoutHash;
@@ -172,3 +172,3 @@
    */
-  _$refs: $RefsMap = {};
+  _$refs: $RefsMap<S> = {};
 
@@ -181,3 +181,3 @@ /**
    */
-  _root$Ref: $Ref;
+  _root$Ref: $Ref<S>;
 
@@ -227,3 +227,3 @@ constructor() {
  */
-function getPaths($refs: $RefsMap, types: string[]) {
+function getPaths<S>($refs: $RefsMap<S>, types: string[]) {
   let paths = Object.keys($refs);
@@ -230,0 +230,0 @@

lib/resolve-external.ts

@@ -7,8 +7,6 @@ import $Ref from "./ref.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;
-
 /**
@@ -24,3 +22,6 @@ * Crawls the JSON schema, finds all external JSON references, and resolves their values.
  */
-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) {
@@ -56,6 +57,6 @@ // Nothing to resolve, so exit early
  */
-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,
@@ -71,9 +72,9 @@ seen?: Set<any>,
     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));
@@ -98,3 +99,8 @@ }
  */
-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";
@@ -107,6 +113,6 @@ const resolvedPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref!);
   // 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);
   }
@@ -136,1 +142,2 @@
 }
+export default resolveExternal;

lib/resolvers/file.ts

@@ -5,3 +5,3 @@ import fs from "fs";
 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";
@@ -40,2 +40,2 @@
   },
-} as ResolverOptions;
+} as ResolverOptions<JSONSchema>;

lib/resolvers/http.ts

 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";
 
@@ -62,3 +62,3 @@ export default {
   },
-} as HTTPResolverOptions;
+} as HTTPResolverOptions<JSONSchema>;
 
@@ -70,3 +70,7 @@ /**
  */
-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);
@@ -110,3 +114,3 @@ const redirects = _redirects || [];
  */
-async function get(u: RequestInfo | URL, httpOptions: HTTPResolverOptions) {
+async function get<S>(u: RequestInfo | URL, httpOptions: HTTPResolverOptions<S>) {
   let controller: any;
@@ -113,0 +117,0 @@ let timeoutId: any;

lib/types/index.ts

@@ -13,4 +13,4 @@ import type {
 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;
 
@@ -21,3 +21,3 @@ /**
 
-export interface HTTPResolverOptions extends Partial<ResolverOptions> {
+export interface HTTPResolverOptions<S = JSONSchema> extends Partial<ResolverOptions<S>> {
   /**
@@ -49,3 +49,3 @@ * 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.
  */
-export interface ResolverOptions {
+export interface ResolverOptions<S = JSONSchema> {
   name?: string;
@@ -75,3 +75,3 @@ /**
         callback?: (error: Error | null, data: string | null) => any,
-      ) => string | Buffer | JSONSchema | Promise<string | Buffer | JSONSchema>);
+      ) => string | Buffer | S | Promise<string | Buffer | S>);
 }
@@ -78,0 +78,0 @@

lib/util/errors.ts

 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";
@@ -14,2 +16,3 @@
   | "EINVALIDPOINTER";
+
 export class JSONParserError extends Error {
@@ -38,6 +41,9 @@ public readonly name: string;
 
-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();
@@ -54,6 +60,8 @@
 
-  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) {
@@ -76,3 +84,3 @@ errors.push(...$ref.errors);
   > {
-    return JSONParserErrorGroup.getParserErrors(this.files);
+    return JSONParserErrorGroup.getParserErrors<S>(this.files);
   }
@@ -79,0 +87,0 @@ }

lib/util/plugins.ts

@@ -6,3 +6,2 @@ import type { FileInfo } from "../types/index.js";
 import type { Plugin } from "../types/index.js";
-import type { JSONSchema } from "../types/index.js";
 
@@ -15,3 +14,3 @@ /**
  */
-export function all(plugins: $RefParserOptions["resolve"]): Plugin[] {
+export function all<S>(plugins: $RefParserOptions<S>["resolve"]): Plugin[] {
   return Object.keys(plugins)
@@ -22,3 +21,3 @@ .filter((key) => {
     .map((key) => {
-      (plugins[key] as ResolverOptions)!.name = key;
+      (plugins[key] as ResolverOptions<S>)!.name = key;
       return plugins[key] as Plugin;
@@ -50,5 +49,5 @@ });
 
-export interface PluginResult {
+export interface PluginResult<S> {
   plugin: Plugin;
-  result?: string | Buffer | JSONSchema;
+  result?: string | Buffer | S;
   error?: any;
@@ -65,13 +64,13 @@ }
  */
-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();
@@ -103,3 +102,3 @@
 
-    function callback(err: PluginResult["error"], result: PluginResult["result"]) {
+    function callback(err: PluginResult<S>["error"], result: PluginResult<S>["result"]) {
       if (err) {
@@ -112,3 +111,3 @@ onError(err);
 
-    function onSuccess(result: PluginResult["result"]) {
+    function onSuccess(result: PluginResult<S>["result"]) {
       // console.log('    success');
@@ -121,3 +120,3 @@ resolve({
 
-    function onError(error: PluginResult["error"]) {
+    function onError(error: PluginResult<S>["error"]) {
       // console.log('    %s', err.message || err);
@@ -139,5 +138,5 @@ lastError = {
  */
-function getResult(
+function getResult<S>(
   obj: Plugin,
-  prop: keyof Plugin | keyof ResolverOptions,
+  prop: keyof Plugin | keyof ResolverOptions<S>,
   file: FileInfo,
@@ -144,0 +143,0 @@ callback?: (err?: Error, result?: any) => void,

package.json

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

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

302125

increased by1.98%

Lines of code

7239

increased by1.8%

No dependency changes