@apidevtools/json-schema-ref-parser 11.2.4 → 11.4.0

package/README.md

@@ -9,11 +9,23 @@
 [![License](https://img.shields.io/npm/l/@apidevtools/json-schema-ref-parser.svg)](LICENSE)
 [![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://plant.treeware.earth/APIDevTools/json-schema-ref-parser)
 
+Installation
+--------------------------
+Install using [npm](https://docs.npmjs.com/about-npm/):
+
+```bash
+npm install @apidevtools/json-schema-ref-parser
+yarn add @apidevtools/json-schema-ref-parser
+bun add @apidevtools/json-schema-ref-parser
+```
+
 The Problem:
 --------------------------
-You've got a JSON Schema with `$ref` pointers to other files and/or URLs.  Maybe you know all the referenced files ahead of time.  Maybe you don't.  Maybe some are local files, and others are remote URLs.  Maybe they are a mix of JSON and YAML format.  Maybe some of the files contain cross-references to each other.
+You've got a JSON Schema with `$ref` pointers to other files and/or URLs. Maybe you know all the referenced files ahead
+of time. Maybe you don't. Maybe some are local files, and others are remote URLs. Maybe they are a mix of JSON and YAML
+format. Maybe some of the files contain cross-references to each other.
 
-```javascript
+```json
 {
   "definitions": {
     "person": {
@@ -36,44 +48,41 @@ You've got a JSON Schema with `$ref` pointers to other files and/or URLs.  Maybe
 }
 ```
 
-
 The Solution:
 --------------------------
-JSON Schema $Ref Parser is a full [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and [JSON Pointer](https://tools.ietf.org/html/rfc6901) implementation that crawls even the most complex [JSON Schemas](http://json-schema.org/latest/json-schema-core.html) and gives you simple, straightforward JavaScript objects.
+JSON Schema $Ref Parser is a full [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03)
+and [JSON Pointer](https://tools.ietf.org/html/rfc6901) implementation that crawls even the most
+complex [JSON Schemas](http://json-schema.org/latest/json-schema-core.html) and gives you simple, straightforward
+JavaScript objects.
 
 - Use **JSON** or **YAML** schemas — or even a mix of both!
-- Supports `$ref` pointers to external files and URLs, as well as [custom sources](https://apitools.dev/json-schema-ref-parser/docs/plugins/resolvers.html) such as databases
-- Can [bundle](https://apitools.dev/json-schema-ref-parser/docs/ref-parser.html#bundlepath-options-callback) multiple files into a single schema that only has _internal_ `$ref` pointers
-- Can [dereference](https://apitools.dev/json-schema-ref-parser/docs/ref-parser.html#dereferencepath-options-callback) your schema, producing a plain-old JavaScript object that's easy to work with
-- Supports [circular references](https://apitools.dev/json-schema-ref-parser/docs/#circular-refs), nested references, back-references, and cross-references between files
-- Maintains object reference equality — `$ref` pointers to the same value always resolve to the same object instance
-- Tested in Node v10, v12, & v14, and all major web browsers on Windows, Mac, and Linux
-
+- Supports `$ref` pointers to external files and URLs, as well
+  as [custom sources](https://apitools.dev/json-schema-ref-parser/docs/plugins/resolvers.html) such as databases
+- Can [bundle](https://apitools.dev/json-schema-ref-parser/docs/ref-parser.html#bundlepath-options-callback) multiple
+  files into a single schema that only has _internal_ `$ref` pointers
+- Can [dereference](https://apitools.dev/json-schema-ref-parser/docs/ref-parser.html#dereferencepath-options-callback)
+  your schema, producing a plain-old JavaScript object that's easy to work with
+- Supports [circular references](https://apitools.dev/json-schema-ref-parser/docs/#circular-refs), nested references,
+  back-references, and cross-references between files
+- Maintains object reference equality — `$ref` pointers to the same value always resolve to the same object
+  instance
+- Compatible with Node LTS and beyond, and all major web browsers on Windows, Mac, and Linux
 
 Example
 --------------------------
 
 ```javascript
-$RefParser.dereference(mySchema, (err, schema) => {
-  if (err) {
-    console.error(err);
-  }
-  else {
-    // `schema` is just a normal JavaScript object that contains your entire JSON Schema,
-    // including referenced files, combined into a single object
-    console.log(schema.definitions.person.properties.firstName);
-  }
-})
-```
-
-Or use `async`/`await` syntax instead. The following example is the same as above:
+import $RefParser from "@apidevtools/json-schema-ref-parser";
 
-```javascript
 try {
-  let schema = await $RefParser.dereference(mySchema);
-  console.log(schema.definitions.person.properties.firstName);
-}
-catch(err) {
+  await $RefParser.dereference(mySchema);
+  // note - by default, mySchema is modified in place, and the returned value is a reference to the same object
+  console.log(mySchema.definitions.person.properties.firstName);
+
+  // if you want to avoid modifying the original schema, you can disable the `mutateInputSchema` option
+  let clonedSchema = await $RefParser.dereference(mySchema, { mutateInputSchema: false });
+  console.log(clonedSchema.definitions.person.properties.firstName);
+} catch (err) {
   console.error(err);
 }
 ```
@@ -81,99 +90,80 @@ catch(err) {
 For more detailed examples, please see the [API Documentation](https://apitools.dev/json-schema-ref-parser/docs/)
 
 
-
-Installation
+Polyfills
 --------------------------
-Install using [npm](https://docs.npmjs.com/about-npm/):
 
-```bash
-npm install @apidevtools/json-schema-ref-parser
-```
 
+If you are using Node.js < 18, you'll need a polyfill for `fetch`,
+like [node-fetch](https://github.com/node-fetch/node-fetch):
 
-
-Usage
---------------------------
-When using JSON Schema $Ref Parser in Node.js apps, you'll probably want to use **CommonJS** syntax:
-
-```javascript
-const $RefParser = require("@apidevtools/json-schema-ref-parser");
-```
-
-When using a transpiler such as [Babel](https://babeljs.io/) or [TypeScript](https://www.typescriptlang.org/), or a bundler such as [Webpack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/), you can use **ECMAScript modules** syntax instead:
-
-```javascript
-import $RefParser from "@apidevtools/json-schema-ref-parser";
-```
-
-If you are using Node.js < 18, you'll need a polyfill for `fetch`, like [node-fetch](https://github.com/node-fetch/node-fetch):
 ```javascript
 import fetch from "node-fetch";
 
 globalThis.fetch = fetch;
 ```
 
-
-
 Browser support
 --------------------------
-JSON Schema $Ref Parser supports recent versions of every major web browser.  Older browsers may require [Babel](https://babeljs.io/) and/or [polyfills](https://babeljs.io/docs/en/next/babel-polyfill).
-
-To use JSON Schema $Ref Parser in a browser, you'll need to use a bundling tool such as [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), [Parcel](https://parceljs.org/), or [Browserify](http://browserify.org/). Some bundlers may require a bit of configuration, such as setting `browser: true` in [rollup-plugin-resolve](https://github.com/rollup/rollup-plugin-node-resolve).
+JSON Schema $Ref Parser supports recent versions of every major web browser. Older browsers may
+require [Babel](https://babeljs.io/) and/or [polyfills](https://babeljs.io/docs/en/next/babel-polyfill).
 
+To use JSON Schema $Ref Parser in a browser, you'll need to use a bundling tool such
+as [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), [Parcel](https://parceljs.org/),
+or [Browserify](http://browserify.org/). Some bundlers may require a bit of configuration, such as
+setting `browser: true` in [rollup-plugin-resolve](https://github.com/rollup/rollup-plugin-node-resolve).
 
 #### Webpack 5
-Webpack 5 has dropped the default export of node core modules in favour of polyfills, you'll need to set them up yourself ( after npm-installing them )
+
+Webpack 5 has dropped the default export of node core modules in favour of polyfills, you'll need to set them up
+yourself ( after npm-installing them )
 Edit your `webpack.config.js` :
+
 ```js
-  config.resolve.fallback = {
-    "path": require.resolve("path-browserify"),
-    'util': require.resolve('util/'),
-    'fs': require.resolve('browserify-fs'),
-    "buffer": require.resolve("buffer/"),
-    "http": require.resolve("stream-http"),
-    "https": require.resolve("https-browserify"),
-    "url": require.resolve("url"),
-  }
+config.resolve.fallback = {
+  "path": require.resolve("path-browserify"),
+  'fs': require.resolve('browserify-fs')
+}
 
-  config.plugins.push(
-    new webpack.ProvidePlugin({
-      Buffer: [ 'buffer', 'Buffer']
-    })
-  )
+config.plugins.push(
+  new webpack.ProvidePlugin({
+    Buffer: ['buffer', 'Buffer']
+  })
+)
 
 ```
 
-
 API Documentation
 --------------------------
 Full API documentation is available [right here](https://apitools.dev/json-schema-ref-parser/docs/)
 
 
-
 Contributing
 --------------------------
-I welcome any contributions, enhancements, and bug-fixes.  [Open an issue](https://github.com/APIDevTools/json-schema-ref-parser/issues) on GitHub and [submit a pull request](https://github.com/APIDevTools/json-schema-ref-parser/pulls).
+I welcome any contributions, enhancements, and
+bug-fixes.  [Open an issue](https://github.com/APIDevTools/json-schema-ref-parser/issues) on GitHub
+and [submit a pull request](https://github.com/APIDevTools/json-schema-ref-parser/pulls).
 
 #### Building/Testing
+
 To build/test the project locally on your computer:
 
 1. __Clone this repo__<br>
-`git clone https://github.com/APIDevTools/json-schema-ref-parser.git`
+   `git clone https://github.com/APIDevTools/json-schema-ref-parser.git`
 
 2. __Install dependencies__<br>
-`npm install`
+   `yarn install`
 
 3. __Run the tests__<br>
-`npm test`
-
-
+   `yarn test`
 
 License
 --------------------------
 JSON Schema $Ref Parser is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
 
-This package is [Treeware](http://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/APIDevTools/json-schema-ref-parser) to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
+This package is [Treeware](http://treeware.earth). If you use it in production, then we ask that you [**buy the world a
+tree**](https://plant.treeware.earth/APIDevTools/json-schema-ref-parser) to thank us for our work. By contributing to
+the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
 
 
 

package/dist/lib/dereference.js

@@ -129,7 +129,6 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
  * @returns
  */
 function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options) {
-    // console.log('Dereferencing $ref pointer "%s" at %s', $ref.$ref, path);
     const isExternalRef = ref_js_1.default.isExternal$Ref($ref);
     const shouldResolveOnCwd = isExternalRef && options?.dereference.externalReferenceResolution === "root";
     const $refPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref);

package/dist/lib/index.d.ts

@@ -1,9 +1,15 @@
 import $Refs from "./refs.js";
 import { JSONParserError, InvalidPointerError, MissingPointerError, ResolverError, ParserError, UnmatchedParserError, UnmatchedResolverError } from "./util/errors.js";
 import type { ParserOptions } from "./options.js";
-import type { Plugin, $RefsCallback, JSONSchema, SchemaCallback, HTTPResolverOptions, FileInfo, ResolverOptions, JSONSchemaObject } from "./types/index.js";
-export { JSONSchemaObject, ResolverOptions, ParserError, UnmatchedResolverError, ResolverError, HTTPResolverOptions, FileInfo, UnmatchedParserError, ParserOptions, MissingPointerError, InvalidPointerError, JSONParserError, Plugin, JSONSchema, $RefsCallback, SchemaCallback, };
-export type RefParserSchema = string | JSONSchema;
+import type { $RefsCallback, JSONSchema, SchemaCallback } from "./types/index.js";
+export { JSONParserError };
+export { InvalidPointerError };
+export { MissingPointerError };
+export { ResolverError };
+export { ParserError };
+export { UnmatchedParserError };
+export { UnmatchedResolverError };
+type RefParserSchema = string | JSONSchema;
 /**
  * This class parses a JSON schema, builds a map of its JSON references and their resolved values,
  * and provides methods for traversing, manipulating, and dereferencing those references.

package/dist/lib/index.js

@@ -26,7 +26,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dereference = exports.bundle = exports.resolve = exports.parse = exports.$RefParser = exports.JSONParserError = exports.InvalidPointerError = exports.MissingPointerError = exports.UnmatchedParserError = exports.ResolverError = exports.UnmatchedResolverError = exports.ParserError = void 0;
+exports.dereference = exports.bundle = exports.resolve = exports.parse = exports.$RefParser = exports.UnmatchedResolverError = exports.UnmatchedParserError = exports.ParserError = exports.ResolverError = exports.MissingPointerError = exports.InvalidPointerError = exports.JSONParserError = void 0;
 const refs_js_1 = __importDefault(require("./refs.js"));
 const parse_js_1 = __importDefault(require("./parse.js"));
 const normalize_args_js_1 = __importDefault(require("./normalize-args.js"));

package/dist/lib/normalize-args.js

@@ -38,6 +38,10 @@ function normalizeArgs(_args) {
     catch (e) {
         console.log(e);
     }
+    if (!options.mutateInputSchema) {
+        // Make a deep clone of the schema, so that we don't alter the original object
+        schema = JSON.parse(JSON.stringify(schema));
+    }
     return {
         path,
         schema,

package/dist/lib/options.d.ts

@@ -77,6 +77,12 @@ interface $RefParserOptions {
          * 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;
     };
 }
 export declare const getNewOptions: (options: DeepPartial<$RefParserOptions>) => $RefParserOptions;

package/dist/lib/options.js

@@ -70,6 +70,7 @@ const getDefaults = () => {
             excludedPathMatcher: () => false,
             referenceResolution: "relative",
         },
+        mutateInputSchema: true,
     };
     return defaults;
 };

package/dist/lib/parse.js

@@ -33,13 +33,20 @@ exports.default = parse;
  */
 async function parse(path, $refs, options) {
     // Remove the URL fragment, if any
-    path = url.stripHash(path);
+    const hashIndex = path.indexOf("#");
+    let hash = "";
+    if (hashIndex >= 0) {
+        hash = path.substring(hashIndex);
+        // Remove the URL fragment, if any
+        path = path.substring(0, hashIndex);
+    }
     // Add a new $Ref for this file, even though we don't have the value yet.
     // This ensures that we don't simultaneously read & parse the same file multiple times
     const $ref = $refs._add(path);
     // This "file object" will be passed to all resolvers and parsers.
     const file = {
         url: path,
+        hash,
         extension: url.getExtension(path),
     };
     // Read the file and then parse the data
@@ -111,7 +118,6 @@ async function readFile(file, options, $refs) {
  * The promise resolves with the parsed file contents and the parser that was used.
  */
 async function parseFile(file, options, $refs) {
-    // console.log('Parsing %s', file.url);
     // Find the parsers that can read this file type.
     // If none of the parsers are an exact match for this file, then we'll try ALL of them.
     // This handles situations where the file IS a supported type, just with an unknown extension.

package/dist/lib/parsers/json.js

@@ -17,6 +17,10 @@ exports.default = {
      * every parser will be tried.
      */
     canParse: ".json",
+    /**
+     * Allow JSON files with byte order marks (BOM)
+     */
+    allowBOM: true,
     /**
      * Parses the given file as JSON
      */
@@ -34,6 +38,18 @@ exports.default = {
                     return JSON.parse(data);
                 }
                 catch (e) {
+                    if (this.allowBOM) {
+                        try {
+                            // find the first curly brace
+                            const firstCurlyBrace = data.indexOf("{");
+                            // remove any characters before the first curly brace
+                            data = data.slice(firstCurlyBrace);
+                            return JSON.parse(data);
+                        }
+                        catch (e) {
+                            throw new errors_js_1.ParserError(e.message, file.url);
+                        }
+                    }
                     throw new errors_js_1.ParserError(e.message, file.url);
                 }
             }

package/dist/lib/pointer.d.ts

@@ -36,7 +36,7 @@ declare class Pointer {
      * Resolving a single pointer may require resolving multiple $Refs.
      */
     indirections: number;
-    constructor($ref: any, path: any, friendlyPath?: string);
+    constructor($ref: $Ref, path: string, friendlyPath?: string);
     /**
      * Resolves the value of a nested property within the given object.
      *
@@ -74,7 +74,7 @@ declare class Pointer {
      * @param [originalPath]
      * @returns
      */
-    static parse(path: string, originalPath?: string): any;
+    static parse(path: string, originalPath?: string): string[];
     /**
      * Creates a JSON pointer path, by joining one or more tokens to a base path.
      *

package/dist/lib/pointer.js

@@ -85,6 +85,20 @@ class Pointer {
             }
             const token = tokens[i];
             if (this.value[token] === undefined || (this.value[token] === null && i === tokens.length - 1)) {
+                // one final case is if the entry itself includes slashes, and was parsed out as a token - we can join the remaining tokens and try again
+                let didFindSubstringSlashMatch = false;
+                for (let j = tokens.length - 1; j > i; j--) {
+                    const joinedToken = tokens.slice(i, j + 1).join("/");
+                    if (this.value[joinedToken] !== undefined) {
+                        this.value = this.value[joinedToken];
+                        i = j;
+                        didFindSubstringSlashMatch = true;
+                        break;
+                    }
+                }
+                if (didFindSubstringSlashMatch) {
+                    continue;
+                }
                 this.value = null;
                 throw new errors_js_1.MissingPointerError(token, decodeURI(this.originalPath));
             }
@@ -151,22 +165,22 @@ class Pointer {
      */
     static parse(path, originalPath) {
         // Get the JSON pointer from the path's hash
-        let pointer = url.getHash(path).substr(1);
+        const pointer = url.getHash(path).substring(1);
         // If there's no pointer, then there are no tokens,
         // so return an empty array
         if (!pointer) {
             return [];
         }
         // Split into an array
-        pointer = pointer.split("/");
+        const split = pointer.split("/");
         // Decode each part, according to RFC 6901
-        for (let i = 0; i < pointer.length; i++) {
-            pointer[i] = safeDecodeURIComponent(pointer[i].replace(escapedSlash, "/").replace(escapedTilde, "~"));
+        for (let i = 0; i < split.length; i++) {
+            split[i] = safeDecodeURIComponent(split[i].replace(escapedSlash, "/").replace(escapedTilde, "~"));
         }
-        if (pointer[0] !== "") {
-            throw new errors_js_1.InvalidPointerError(pointer, originalPath === undefined ? path : originalPath);
+        if (split[0] !== "") {
+            throw new errors_js_1.InvalidPointerError(split, originalPath === undefined ? path : originalPath);
         }
-        return pointer.slice(1);
+        return split.slice(1);
     }
     /**
      * Creates a JSON pointer path, by joining one or more tokens to a base path.

package/dist/lib/types/index.d.ts

@@ -64,6 +64,12 @@ export interface Plugin {
      * You can set `allowEmpty: false` on any parser, which will cause an error to be thrown if a file empty.
      */
     allowEmpty?: boolean;
+    /**
+     * Specifies whether a Byte Order Mark (BOM) is allowed or not. Only applies to JSON parsing
+     *
+     * @type {boolean} @default true
+     */
+    allowBOM?: boolean;
     /**
      * The encoding that the text is expected to be in.
      */
@@ -93,6 +99,10 @@ export interface FileInfo {
      * The full URL of the file. This could be any type of URL, including "http://", "https://", "file://", "ftp://", "mongodb://", or even a local filesystem path (when running in Node.js).
      */
     url: string;
+    /**
+     * The hash (URL fragment) of the file URL, including the # symbol. If the URL doesn't have a hash, then this will be an empty string.
+     */
+    hash: string;
     /**
      * The lowercase file extension, such as ".json", ".yaml", ".txt", etc.
      */

package/dist/lib/util/url.d.ts

@@ -40,21 +40,21 @@ export declare function stripQuery(path: any): any;
  * @param path
  * @returns
  */
-export declare function getHash(path: any): any;
+export declare function getHash(path: undefined | string): string;
 /**
  * Removes the hash (URL fragment), if any, from the given path.
  *
  * @param path
  * @returns
  */
-export declare function stripHash(path: any): any;
+export declare function stripHash(path?: string | undefined): string;
 /**
  * Determines whether the given path is an HTTP(S) URL.
  *
  * @param path
  * @returns
  */
-export declare function isHttp(path: any): boolean;
+export declare function isHttp(path: string): boolean;
 /**
  * Determines whether the given path is a filesystem path.
  * This includes "file://" URLs.

package/dist/lib/util/url.js

@@ -52,12 +52,13 @@ exports.parse = parse;
 function resolve(from, to) {
     const fromUrl = new URL((0, convert_path_to_posix_1.default)(from), "resolve://");
     const resolvedUrl = new URL((0, convert_path_to_posix_1.default)(to), fromUrl);
+    const endSpaces = to.match(/(\s*)$/)?.[1] || "";
     if (resolvedUrl.protocol === "resolve:") {
         // `from` is a relative URL.
         const { pathname, search, hash } = resolvedUrl;
-        return pathname + search + hash;
+        return pathname + search + hash + endSpaces;
     }
-    return resolvedUrl.toString();
+    return resolvedUrl.toString() + endSpaces;
 }
 exports.resolve = resolve;
 /**
@@ -129,9 +130,12 @@ exports.stripQuery = stripQuery;
  * @returns
  */
 function getHash(path) {
+    if (!path) {
+        return "#";
+    }
     const hashIndex = path.indexOf("#");
     if (hashIndex >= 0) {
-        return path.substr(hashIndex);
+        return path.substring(hashIndex);
     }
     return "#";
 }
@@ -143,9 +147,12 @@ exports.getHash = getHash;
  * @returns
  */
 function stripHash(path) {
+    if (!path) {
+        return "";
+    }
     const hashIndex = path.indexOf("#");
     if (hashIndex >= 0) {
-        path = path.substr(0, hashIndex);
+        path = path.substring(0, hashIndex);
     }
     return path;
 }

package/lib/dereference.ts

@@ -159,16 +159,14 @@ function crawl(
  */
 function dereference$Ref(
   $ref: any,
-  path: any,
-  pathFromRoot: any,
-  parents: any,
+  path: string,
+  pathFromRoot: string,
+  parents: Set<any>,
   processedObjects: any,
   dereferencedCache: any,
-  $refs: any,
-  options: any,
+  $refs: $Refs,
+  options: $RefParserOptions,
 ) {
-  // console.log('Dereferencing $ref pointer "%s" at %s', $ref.$ref, path);
-
   const isExternalRef = $Ref.isExternal$Ref($ref);
   const shouldResolveOnCwd = isExternalRef && options?.dereference.externalReferenceResolution === "root";
   const $refPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref);

package/lib/index.ts

@@ -19,37 +19,17 @@ import {
 import { ono } from "@jsdevtools/ono";
 import maybe from "./util/maybe.js";
 import type { ParserOptions } from "./options.js";
-import type {
-  Plugin,
-  $RefsCallback,
-  JSONSchema,
-  SchemaCallback,
-  HTTPResolverOptions,
-  FileInfo,
-  ResolverOptions,
-  JSONSchemaObject,
-} from "./types/index.js";
+import type { $RefsCallback, JSONSchema, SchemaCallback } from "./types/index.js";
 
-export {
-  JSONSchemaObject,
-  ResolverOptions,
-  ParserError,
-  UnmatchedResolverError,
-  ResolverError,
-  HTTPResolverOptions,
-  FileInfo,
-  UnmatchedParserError,
-  ParserOptions,
-  MissingPointerError,
-  InvalidPointerError,
-  JSONParserError,
-  Plugin,
-  JSONSchema,
-  $RefsCallback,
-  SchemaCallback,
-};
+export { JSONParserError };
+export { InvalidPointerError };
+export { MissingPointerError };
+export { ResolverError };
+export { ParserError };
+export { UnmatchedParserError };
+export { UnmatchedResolverError };
 
-export type RefParserSchema = string | JSONSchema;
+type RefParserSchema = string | JSONSchema;
 
 /**
  * This class parses a JSON schema, builds a map of its JSON references and their resolved values,

package/lib/normalize-args.ts

@@ -39,6 +39,11 @@ function normalizeArgs(_args: Partial<IArguments>) {
     console.log(e);
   }
 
+  if (!options.mutateInputSchema) {
+    // Make a deep clone of the schema, so that we don't alter the original object
+    schema = JSON.parse(JSON.stringify(schema));
+  }
+
   return {
     path,
     schema,

package/lib/options.ts

@@ -91,6 +91,13 @@ interface $RefParserOptions {
      * 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;
   };
 }
 
@@ -159,6 +166,8 @@ const getDefaults = () => {
       excludedPathMatcher: () => false,
       referenceResolution: "relative",
     },
+
+    mutateInputSchema: true,
   } as $RefParserOptions;
   return defaults;
 };

package/lib/parse.ts

@@ -19,7 +19,13 @@ export default parse;
  */
 async function parse(path: string, $refs: $Refs, options: Options) {
   // Remove the URL fragment, if any
-  path = url.stripHash(path);
+  const hashIndex = path.indexOf("#");
+  let hash = "";
+  if (hashIndex >= 0) {
+    hash = path.substring(hashIndex);
+    // Remove the URL fragment, if any
+    path = path.substring(0, hashIndex);
+  }
 
   // Add a new $Ref for this file, even though we don't have the value yet.
   // This ensures that we don't simultaneously read & parse the same file multiple times
@@ -28,6 +34,7 @@ async function parse(path: string, $refs: $Refs, options: Options) {
   // This "file object" will be passed to all resolvers and parsers.
   const file = {
     url: path,
+    hash,
     extension: url.getExtension(path),
   } as FileInfo;
 
@@ -103,8 +110,6 @@ async function readFile(file: FileInfo, options: Options, $refs: $Refs): Promise
  * The promise resolves with the parsed file contents and the parser that was used.
  */
 async function parseFile(file: FileInfo, options: Options, $refs: $Refs) {
-  // console.log('Parsing %s', file.url);
-
   // Find the parsers that can read this file type.
   // If none of the parsers are an exact match for this file, then we'll try ALL of them.
   // This handles situations where the file IS a supported type, just with an unknown extension.

package/lib/parsers/json.ts

@@ -21,6 +21,11 @@ export default {
    */
   canParse: ".json",
 
+  /**
+   * Allow JSON files with byte order marks (BOM)
+   */
+  allowBOM: true,
+
   /**
    * Parses the given file as JSON
    */
@@ -37,6 +42,17 @@ export default {
         try {
           return JSON.parse(data);
         } catch (e: any) {
+          if (this.allowBOM) {
+            try {
+              // find the first curly brace
+              const firstCurlyBrace = data.indexOf("{");
+              // remove any characters before the first curly brace
+              data = data.slice(firstCurlyBrace);
+              return JSON.parse(data);
+            } catch (e: any) {
+              throw new ParserError(e.message, file.url);
+            }
+          }
           throw new ParserError(e.message, file.url);
         }
       }

package/lib/pointer.ts

@@ -3,6 +3,7 @@ import type $RefParserOptions from "./options.js";
 import $Ref from "./ref.js";
 import * as url from "./util/url.js";
 import { JSONParserError, InvalidPointerError, MissingPointerError, isHandledError } from "./util/errors.js";
+
 const slashes = /\//g;
 const tildes = /~/g;
 const escapedSlash = /~1/g;
@@ -57,7 +58,7 @@ class Pointer {
    */
   indirections: number;
 
-  constructor($ref: any, path: any, friendlyPath?: string) {
+  constructor($ref: $Ref, path: string, friendlyPath?: string) {
     this.$ref = $ref;
 
     this.path = path;
@@ -102,6 +103,21 @@ class Pointer {
 
       const token = tokens[i];
       if (this.value[token] === undefined || (this.value[token] === null && i === tokens.length - 1)) {
+        // one final case is if the entry itself includes slashes, and was parsed out as a token - we can join the remaining tokens and try again
+        let didFindSubstringSlashMatch = false;
+        for (let j = tokens.length - 1; j > i; j--) {
+          const joinedToken = tokens.slice(i, j + 1).join("/");
+          if (this.value[joinedToken] !== undefined) {
+            this.value = this.value[joinedToken];
+            i = j;
+            didFindSubstringSlashMatch = true;
+            break;
+          }
+        }
+        if (didFindSubstringSlashMatch) {
+          continue;
+        }
+
         this.value = null;
         throw new MissingPointerError(token, decodeURI(this.originalPath));
       } else {
@@ -174,9 +190,9 @@ class Pointer {
    * @param [originalPath]
    * @returns
    */
-  static parse(path: string, originalPath?: string) {
+  static parse(path: string, originalPath?: string): string[] {
     // Get the JSON pointer from the path's hash
-    let pointer = url.getHash(path).substr(1);
+    const pointer = url.getHash(path).substring(1);
 
     // If there's no pointer, then there are no tokens,
     // so return an empty array
@@ -185,18 +201,18 @@ class Pointer {
     }
 
     // Split into an array
-    pointer = pointer.split("/");
+    const split = pointer.split("/");
 
     // Decode each part, according to RFC 6901
-    for (let i = 0; i < pointer.length; i++) {
-      pointer[i] = safeDecodeURIComponent(pointer[i].replace(escapedSlash, "/").replace(escapedTilde, "~"));
+    for (let i = 0; i < split.length; i++) {
+      split[i] = safeDecodeURIComponent(split[i].replace(escapedSlash, "/").replace(escapedTilde, "~"));
     }
 
-    if (pointer[0] !== "") {
-      throw new InvalidPointerError(pointer, originalPath === undefined ? path : originalPath);
+    if (split[0] !== "") {
+      throw new InvalidPointerError(split, originalPath === undefined ? path : originalPath);
     }
 
-    return pointer.slice(1);
+    return split.slice(1);
   }
 
   /**

package/lib/types/index.ts

@@ -88,6 +88,13 @@ export interface Plugin {
    */
   allowEmpty?: boolean;
 
+  /**
+   * Specifies whether a Byte Order Mark (BOM) is allowed or not. Only applies to JSON parsing
+   *
+   * @type {boolean} @default true
+   */
+  allowBOM?: boolean;
+
   /**
    * The encoding that the text is expected to be in.
    */
@@ -123,6 +130,11 @@ export interface FileInfo {
    */
   url: string;
 
+  /**
+   * The hash (URL fragment) of the file URL, including the # symbol. If the URL doesn't have a hash, then this will be an empty string.
+   */
+  hash: string;
+
   /**
    * The lowercase file extension, such as ".json", ".yaml", ".txt", etc.
    */

package/lib/util/url.ts

@@ -28,12 +28,13 @@ export const parse = (u: string | URL) => new URL(u);
 export function resolve(from: string, to: string) {
   const fromUrl = new URL(convertPathToPosix(from), "resolve://");
   const resolvedUrl = new URL(convertPathToPosix(to), fromUrl);
+  const endSpaces = to.match(/(\s*)$/)?.[1] || "";
   if (resolvedUrl.protocol === "resolve:") {
     // `from` is a relative URL.
     const { pathname, search, hash } = resolvedUrl;
-    return pathname + search + hash;
+    return pathname + search + hash + endSpaces;
   }
-  return resolvedUrl.toString();
+  return resolvedUrl.toString() + endSpaces;
 }
 
 /**
@@ -105,10 +106,13 @@ export function stripQuery(path: any) {
  * @param path
  * @returns
  */
-export function getHash(path: any) {
+export function getHash(path: undefined | string) {
+  if (!path) {
+    return "#";
+  }
   const hashIndex = path.indexOf("#");
   if (hashIndex >= 0) {
-    return path.substr(hashIndex);
+    return path.substring(hashIndex);
   }
   return "#";
 }
@@ -119,10 +123,13 @@ export function getHash(path: any) {
  * @param path
  * @returns
  */
-export function stripHash(path: any) {
+export function stripHash(path?: string | undefined) {
+  if (!path) {
+    return "";
+  }
   const hashIndex = path.indexOf("#");
   if (hashIndex >= 0) {
-    path = path.substr(0, hashIndex);
+    path = path.substring(0, hashIndex);
   }
   return path;
 }
@@ -133,7 +140,7 @@ export function stripHash(path: any) {
  * @param path
  * @returns
  */
-export function isHttp(path: any) {
+export function isHttp(path: string) {
   const protocol = getProtocol(path);
   if (protocol === "http" || protocol === "https") {
     return true;

package/package.json

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

package/lib/tsconfig.json

@@ -1,103 +0,0 @@
-{
-  "compilerOptions": {
-    /* Visit https://aka.ms/tsconfig to read more about this file */
-
-    /* Projects */
-    // "incremental": true,                              /* Save .tsbuildinfo files to allow for incremental compilation of projects. */
-    // "composite": true,                                /* Enable constraints that allow a TypeScript project to be used with project references. */
-    // "tsBuildInfoFile": "./.tsbuildinfo",              /* Specify the path to .tsbuildinfo incremental compilation file. */
-    // "disableSourceOfProjectReferenceRedirect": true,  /* Disable preferring source files instead of declaration files when referencing composite projects. */
-    // "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
-    // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
-
-    /* Language and Environment */
-    "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
-    // "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
-    // "jsx": "preserve",                                /* Specify what JSX code is generated. */
-    // "experimentalDecorators": true,                   /* Enable experimental support for TC39 stage 2 draft decorators. */
-    // "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
-    // "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
-    // "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
-    // "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
-    // "reactNamespace": "",                             /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
-    // "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
-    // "useDefineForClassFields": true,                  /* Emit ECMAScript-standard-compliant class fields. */
-    // "moduleDetection": "auto",                        /* Control what method is used to detect module-format JS files. */
-
-    /* Modules */
-    "module": "commonjs",                                /* Specify what module code is generated. */
-    // "rootDir": "./",                                  /* Specify the root folder within your source files. */
-    // "moduleResolution": "node",                       /* Specify how TypeScript looks up a file from a given module specifier. */
-    // "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
-    // "paths": {},                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
-    // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
-    // "typeRoots": [],                                  /* Specify multiple folders that act like './node_modules/@types'. */
-    // "types": [],                                      /* Specify type package names to be included without being referenced in a source file. */
-    // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
-    // "moduleSuffixes": [],                             /* List of file name suffixes to search when resolving a module. */
-    // "resolveJsonModule": true,                        /* Enable importing .json files. */
-    // "noResolve": true,                                /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
-
-    /* JavaScript Support */
-    // "allowJs": true,                                  /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
-    // "checkJs": true,                                  /* Enable error reporting in type-checked JavaScript files. */
-    // "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
-
-    /* Emit */
-    // "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
-    // "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
-    // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
-    // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
-    // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
-    // "outDir": "./",                                   /* Specify an output folder for all emitted files. */
-    // "removeComments": true,                           /* Disable emitting comments. */
-    // "noEmit": true,                                   /* Disable emitting files from a compilation. */
-    // "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
-    // "importsNotUsedAsValues": "remove",               /* Specify emit/checking behavior for imports that are only used for types. */
-    // "downlevelIteration": true,                       /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
-    // "sourceRoot": "",                                 /* Specify the root path for debuggers to find the reference source code. */
-    // "mapRoot": "",                                    /* Specify the location where debugger should locate map files instead of generated locations. */
-    // "inlineSourceMap": true,                          /* Include sourcemap files inside the emitted JavaScript. */
-    // "inlineSources": true,                            /* Include source code in the sourcemaps inside the emitted JavaScript. */
-    // "emitBOM": true,                                  /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
-    // "newLine": "crlf",                                /* Set the newline character for emitting files. */
-    // "stripInternal": true,                            /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
-    // "noEmitHelpers": true,                            /* Disable generating custom helper functions like '__extends' in compiled output. */
-    // "noEmitOnError": true,                            /* Disable emitting files if any type checking errors are reported. */
-    // "preserveConstEnums": true,                       /* Disable erasing 'const enum' declarations in generated code. */
-    // "declarationDir": "./",                           /* Specify the output directory for generated declaration files. */
-    // "preserveValueImports": true,                     /* Preserve unused imported values in the JavaScript output that would otherwise be removed. */
-
-    /* Interop Constraints */
-    // "isolatedModules": true,                          /* Ensure that each file can be safely transpiled without relying on other imports. */
-    // "allowSyntheticDefaultImports": true,             /* Allow 'import x from y' when a module doesn't have a default export. */
-    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
-    // "preserveSymlinks": true,                         /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
-    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
-
-    /* Type Checking */
-    "strict": true,                                      /* Enable all strict type-checking options. */
-    // "noImplicitAny": true,                            /* Enable error reporting for expressions and declarations with an implied 'any' type. */
-    // "strictNullChecks": true,                         /* When type checking, take into account 'null' and 'undefined'. */
-    // "strictFunctionTypes": true,                      /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
-    // "strictBindCallApply": true,                      /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
-    // "strictPropertyInitialization": true,             /* Check for class properties that are declared but not set in the constructor. */
-    // "noImplicitThis": true,                           /* Enable error reporting when 'this' is given the type 'any'. */
-    // "useUnknownInCatchVariables": true,               /* Default catch clause variables as 'unknown' instead of 'any'. */
-    // "alwaysStrict": true,                             /* Ensure 'use strict' is always emitted. */
-    // "noUnusedLocals": true,                           /* Enable error reporting when local variables aren't read. */
-    // "noUnusedParameters": true,                       /* Raise an error when a function parameter isn't read. */
-    // "exactOptionalPropertyTypes": true,               /* Interpret optional property types as written, rather than adding 'undefined'. */
-    // "noImplicitReturns": true,                        /* Enable error reporting for codepaths that do not explicitly return in a function. */
-    // "noFallthroughCasesInSwitch": true,               /* Enable error reporting for fallthrough cases in switch statements. */
-    // "noUncheckedIndexedAccess": true,                 /* Add 'undefined' to a type when accessed using an index. */
-    // "noImplicitOverride": true,                       /* Ensure overriding members in derived classes are marked with an override modifier. */
-    // "noPropertyAccessFromIndexSignature": true,       /* Enforces using indexed accessors for keys declared using an indexed type. */
-    // "allowUnusedLabels": true,                        /* Disable error reporting for unused labels. */
-    // "allowUnreachableCode": true,                     /* Disable error reporting for unreachable code. */
-
-    /* Completeness */
-    // "skipDefaultLibCheck": true,                      /* Skip type checking .d.ts files that are included with TypeScript. */
-    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
-  }
-}