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

package/dist/lib/bundle.d.ts

@@ -1,4 +1,6 @@
-export default bundle;
+import type $RefParser from "./index";
+import type { ParserOptions } from "./index";
+import type { JSONSchema } from "./index";
 /**
  * Bundles all external JSON references into the main JSON schema, thus resulting in a schema that
  * only has *internal* references, not any *external* references.
@@ -7,4 +9,5 @@ export default bundle;
  * @param parser
  * @param options
  */
-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;

package/dist/lib/bundle.js

@@ -29,7 +29,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const ref_js_1 = __importDefault(require("./ref.js"));
 const pointer_js_1 = __importDefault(require("./pointer.js"));
 const url = __importStar(require("./util/url.js"));
-exports.default = bundle;
 /**
  * Bundles all external JSON references into the main JSON schema, thus resulting in a schema that
  * only has *internal* references, not any *external* references.
@@ -53,6 +52,7 @@ function bundle(parser, options) {
  * @param key - The property key of `parent` to be crawled
  * @param path - The full path of the property being crawled, possibly with a JSON Pointer in the hash
  * @param pathFromRoot - The path of the property being crawled, from the schema root
+ * @param indirections
  * @param inventory - An array of already-inventoried $ref pointers
  * @param $refs
  * @param options
@@ -251,9 +251,8 @@ function remap(inventory) {
  * TODO
  */
 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;
         }
     }
@@ -262,3 +261,4 @@ function removeFromInventory(inventory, entry) {
     const index = inventory.indexOf(entry);
     inventory.splice(index, 1);
 }
+exports.default = bundle;

package/dist/lib/dereference.d.ts

@@ -1,3 +1,6 @@
+import type { ParserOptions } from "./options.js";
+import type { JSONSchema } from "./types";
+import type $RefParser from "./index";
 export default dereference;
 /**
  * Crawls the JSON schema, finds all JSON references, and dereferences them.
@@ -6,4 +9,4 @@ export default dereference;
  * @param parser
  * @param options
  */
-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;

package/dist/lib/dereference.js

@@ -63,8 +63,9 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
         value: obj,
         circular: false,
     };
-    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)) {
             parents.add(obj);
             processedObjects.add(obj);
@@ -88,9 +89,7 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
                         // Avoid pointless mutations; breaks frozen objects to no profit
                         if (obj[key] !== dereferenced.value) {
                             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);
                         }
                     }
                     else {
@@ -130,7 +129,7 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
  */
 function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options) {
     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);
     const cache = dereferencedCache.get($refPath);
     if (cache) {
@@ -170,7 +169,7 @@ function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, de
         circular = dereferenced.circular;
         dereferencedValue = dereferenced.value;
     }
-    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
         dereferencedValue = $ref;
     }

package/dist/lib/index.d.ts

@@ -1,7 +1,7 @@
 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;
 /**
  * This class parses a JSON schema, builds a map of its JSON references and their resolved values,
@@ -9,21 +9,21 @@ export type RefParserSchema = string | JSONSchema;
  *
  * @class
  */
-export declare class $RefParser {
+export declare class $RefParser<S extends JSONSchema = JSONSchema, O extends ParserOptions = ParserOptions> {
     /**
      * The parsed (and possibly dereferenced) JSON schema object
      *
      * @type {object}
      * @readonly
      */
-    schema: JSONSchema | null;
+    schema: S | null;
     /**
      * The resolved JSON references
      *
      * @type {$Refs}
      * @readonly
      */
-    $refs: $Refs;
+    $refs: $Refs<S>;
     /**
      * Parses the given JSON schema.
      * This method does not resolve any JSON references.
@@ -35,18 +35,18 @@ export declare 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.
      */
-    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>;
     /**
      * *This method is used internally by other methods, such as `bundle` and `dereference`. You probably won't need to call this method yourself.*
      *
@@ -58,12 +58,12 @@ export declare class $RefParser {
      * @param options (optional)
      * @param callback (optional) A callback that will receive a `$Refs` object
      */
-    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>;
     /**
      * *This method is used internally by other methods, such as `bundle` and `dereference`. You probably won't need to call this method yourself.*
      *
@@ -75,12 +75,12 @@ export declare class $RefParser {
      * @param options (optional)
      * @param callback (optional) A callback that will receive a `$Refs` object
      */
-    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>;
     /**
      * 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.
      *
@@ -92,12 +92,12 @@ export declare class $RefParser {
      * @param options (optional)
      * @param callback (optional) A callback that will receive the bundled schema object
      */
-    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>;
     /**
      * 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.
      *
@@ -109,12 +109,12 @@ export declare class $RefParser {
      * @param options (optional)
      * @param callback (optional) A callback that will receive the bundled schema object
      */
-    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>;
     /**
      * 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.
      *
@@ -126,12 +126,12 @@ export declare class $RefParser {
      * @param options (optional)
      * @param callback (optional) A callback that will receive the dereferenced schema object
      */
-    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>;
     /**
      * 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.
      *
@@ -139,20 +139,21 @@ export declare 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
      */
-    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>;
 }
 export default $RefParser;
 export declare const parse: typeof $RefParser.parse;
 export declare const resolve: typeof $RefParser.resolve;
 export declare const bundle: typeof $RefParser.bundle;
 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, };

package/dist/lib/normalize-args.d.ts

@@ -1,13 +1,13 @@
+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>;
 }
 /**
  * Normalizes the given arguments, accounting for optional args.
  */
-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;

package/dist/lib/normalize-args.js

@@ -6,7 +6,10 @@ const options_js_1 = require("./options.js");
  * Normalizes the given arguments, accounting for optional args.
  */
 function normalizeArgs(_args) {
-    let path, schema, options, callback;
+    let path;
+    let schema;
+    let options;
+    let callback;
     const args = Array.prototype.slice.call(_args);
     if (typeof args[args.length - 1] === "function") {
         // The last parameter is a callback function

package/dist/lib/options.d.ts

@@ -1,14 +1,45 @@
-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.
      *
@@ -33,10 +64,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;
     };
     /**
      * By default, JSON Schema $Ref Parser throws the first error it encounters. Setting `continueOnError` to `true`
@@ -47,46 +78,16 @@ 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;
-        /**
-         * 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;

package/dist/lib/parse.d.ts

@@ -1,8 +1,9 @@
 /// <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;

package/dist/lib/parse.js

@@ -27,7 +27,6 @@ const ono_1 = require("@jsdevtools/ono");
 const url = __importStar(require("./util/url.js"));
 const plugins = __importStar(require("./util/plugins.js"));
 const errors_js_1 = require("./util/errors.js");
-exports.default = parse;
 /**
  * Reads and parses the specified file path or URL.
  */
@@ -72,7 +71,7 @@ async function parse(path, $refs, 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.
  */
@@ -113,6 +112,7 @@ async function readFile(file, options, $refs) {
  * @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.
@@ -166,3 +166,4 @@ function isEmpty(value) {
         (typeof value === "string" && value.trim().length === 0) ||
         (Buffer.isBuffer(value) && value.length === 0));
 }
+exports.default = parse;

package/dist/lib/pointer.d.ts

@@ -1,5 +1,6 @@
 import type $RefParserOptions from "./options.js";
 import $Ref from "./ref.js";
+import type { JSONSchema } from "./types";
 /**
  * This class represents a single JSON pointer and its resolved value.
  *
@@ -8,11 +9,11 @@ import $Ref from "./ref.js";
  * @param [friendlyPath] - The original user-specified path (used for error messages)
  * @class
  */
-declare class Pointer {
+declare class Pointer<S = JSONSchema> {
     /**
      * The {@link $Ref} object that contains this {@link Pointer} object.
      */
-    $ref: $Ref;
+    $ref: $Ref<S>;
     /**
      * The file path or URL, containing the JSON pointer in the hash.
      * This path is relative to the path of the main JSON schema file.
@@ -36,7 +37,7 @@ declare class Pointer {
      * Resolving a single pointer may require resolving multiple $Refs.
      */
     indirections: number;
-    constructor($ref: $Ref, path: string, friendlyPath?: string);
+    constructor($ref: $Ref<S>, path: string, friendlyPath?: string);
     /**
      * Resolves the value of a nested property within the given object.
      *
@@ -50,7 +51,7 @@ declare class Pointer {
      * the {@link Pointer#$ref} and {@link Pointer#path} will reflect the resolution path
      * of the resolved value.
      */
-    resolve(obj: any, options?: $RefParserOptions, pathFromRoot?: string): this;
+    resolve(obj: any, options?: $RefParserOptions<S>, pathFromRoot?: string): this;
     /**
      * Sets the value of a nested property within the given object.
      *
@@ -61,7 +62,7 @@ declare class Pointer {
      * @returns
      * Returns the modified object, or an entirely new object if the entire object is overwritten.
      */
-    set(obj: any, value: any, options?: $RefParserOptions): any;
+    set(obj: any, value: any, options?: $RefParserOptions<S>): any;
     /**
      * Parses a JSON pointer (or a path containing a JSON pointer in the hash)
      * and returns an array of the pointer's tokens.

package/dist/lib/ref.d.ts

@@ -2,6 +2,7 @@ import Pointer from "./pointer.js";
 import type { JSONParserError, MissingPointerError, ParserError, ResolverError } from "./util/errors.js";
 import type $Refs from "./refs.js";
 import type $RefParserOptions from "./options.js";
+import type { ParserOptions } from "./options.js";
 import type { JSONSchema } from "./types";
 export type $RefError = JSONParserError | ResolverError | ParserError | MissingPointerError;
 /**
@@ -9,7 +10,7 @@ export type $RefError = JSONParserError | ResolverError | ParserError | MissingP
  *
  * @class
  */
-declare class $Ref {
+declare class $Ref<S = JSONSchema> {
     /**
      * The file path or URL of the referenced file.
      * This path is relative to the path of the main JSON schema file.
@@ -33,7 +34,7 @@ declare class $Ref {
      *
      * @type {$Refs}
      */
-    $refs: $Refs;
+    $refs: $Refs<S>;
     /**
      * Indicates the type of {@link $Ref#path} (e.g. "file", "http", etc.)
      */
@@ -42,7 +43,7 @@ declare class $Ref {
      * List of all errors. Undefined if no errors.
      */
     errors: Array<$RefError>;
-    constructor($refs: $Refs);
+    constructor($refs: $Refs<S>);
     /**
      * Pushes an error to errors array.
      *
@@ -57,7 +58,7 @@ declare class $Ref {
      * @param options
      * @returns
      */
-    exists(path: string, options?: $RefParserOptions): boolean;
+    exists(path: string, options?: $RefParserOptions<S>): boolean;
     /**
      * Resolves the given JSON reference within this {@link $Ref#value} and returns the resolved value.
      *
@@ -65,7 +66,7 @@ declare class $Ref {
      * @param options
      * @returns - Returns the resolved value
      */
-    get(path: any, options: $RefParserOptions): any;
+    get(path: string, options?: $RefParserOptions<S>): any;
     /**
      * Resolves the given JSON reference within this {@link $Ref#value}.
      *
@@ -75,7 +76,7 @@ declare class $Ref {
      * @param pathFromRoot - The path of `obj` from the schema root
      * @returns
      */
-    resolve(path: any, options?: $RefParserOptions, friendlyPath?: string, pathFromRoot?: string): Pointer | null;
+    resolve(path: string, options?: $RefParserOptions<S>, friendlyPath?: string, pathFromRoot?: string): Pointer<S> | null;
     /**
      * Sets the value of a nested property within this {@link $Ref#value}.
      * If the property, or any of its parents don't exist, they will be created.
@@ -109,7 +110,7 @@ declare class $Ref {
      * @param options
      * @returns
      */
-    static isAllowed$Ref(value: unknown, options?: $RefParserOptions): true | undefined;
+    static isAllowed$Ref(value: unknown, options?: ParserOptions): true | undefined;
     /**
      * Determines whether the given value is a JSON reference that "extends" its resolved value.
      * That is, it has extra properties (in addition to "$ref"), so rather than simply pointing to
@@ -176,6 +177,6 @@ declare class $Ref {
      * @param resolvedValue - The resolved value, which can be any type
      * @returns - Returns the dereferenced value
      */
-    static dereference($ref: $Ref, resolvedValue: JSONSchema): JSONSchema;
+    static dereference<S>($ref: $Ref<S>, resolvedValue: S): S;
 }
 export default $Ref;

package/dist/lib/ref.js

@@ -142,7 +142,7 @@ class $Ref {
                 // It's a JSON Pointer reference, which is always allowed
                 return true;
             }
-            else if (value.$ref[0] !== "#" && (!options || options.resolve.external)) {
+            else if (value.$ref[0] !== "#" && (!options || options.resolve?.external)) {
                 // It's an external reference, which is allowed by the options
                 return true;
             }