@hey-api/json-schema-ref-parser 1.2.3 → 1.3.0

package/{lib → src}/dereference.ts

@@ -1,40 +1,12 @@
-import $Ref from "./ref.js";
-import cloneDeep from "lodash/cloneDeep";
-import Pointer from "./pointer.js";
-import { ono } from "@jsdevtools/ono";
-import * as url from "./util/url.js";
-import type $Refs from "./refs.js";
-import type { DereferenceOptions, ParserOptions } from "./options.js";
-import type { JSONSchema } from "./types";
-import type { $RefParser } from "./index";
-import { TimeoutError } from "./util/errors";
+import { ono } from '@jsdevtools/ono';
 
-export default dereference;
-
-/**
- * Crawls the JSON schema, finds all JSON references, and dereferences them.
- * This method mutates the JSON schema object, replacing JSON references with their resolved value.
- *
- * @param parser
- * @param options
- */
-function dereference(parser: $RefParser, options: ParserOptions) {
-  const start = Date.now();
-  // console.log('Dereferencing $ref pointers in %s', parser.$refs._root$Ref.path);
-  const dereferenced = crawl<JSONSchema>(
-    parser.schema,
-    parser.$refs._root$Ref.path!,
-    "#",
-    new Set(),
-    new Set(),
-    new Map(),
-    parser.$refs,
-    options,
-    start,
-  );
-  parser.$refs.circular = dereferenced.circular;
-  parser.schema = dereferenced.value;
-}
+import type { DereferenceOptions, ParserOptions } from './options';
+import Pointer from './pointer';
+import $Ref from './ref';
+import type $Refs from './refs';
+import type { JSONSchema } from './types';
+import { TimeoutError } from './util/errors';
+import * as url from './util/url';
 
 /**
  * Recursively crawls the given value, and dereferences any JSON references.
@@ -63,8 +35,8 @@ function crawl<S extends object = JSONSchema>(
 ) {
   let dereferenced;
   const result = {
-    value: obj,
     circular: false,
+    value: obj,
   };
 
   if (options && options.timeoutMs) {
@@ -75,8 +47,13 @@ function crawl<S extends object = JSONSchema>(
   const derefOptions = (options.dereference || {}) as DereferenceOptions;
   const isExcludedPath = derefOptions.excludedPathMatcher || (() => false);
 
-  if (derefOptions?.circular === "ignore" || !processedObjects.has(obj)) {
-    if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
+  if (derefOptions?.circular === 'ignore' || !processedObjects.has(obj)) {
+    if (
+      obj &&
+      typeof obj === 'object' &&
+      !ArrayBuffer.isView(obj) &&
+      !isExcludedPath(pathFromRoot)
+    ) {
       parents.add(obj);
       processedObjects.add(obj);
 
@@ -191,19 +168,19 @@ function dereference$Ref<S extends object = JSONSchema>(
     if (refKeys.length > 1) {
       const extraKeys = {};
       for (const key of refKeys) {
-        if (key !== "$ref" && !(key in cache.value)) {
+        if (key !== '$ref' && !(key in cache.value)) {
           // @ts-expect-error TS(7053): Element implicitly has an 'any' type because expre... Remove this comment to see the full error message
           extraKeys[key] = $ref[key];
         }
       }
       return {
         circular: cache.circular,
-        value: Object.assign({}, cloneDeep(cache.value), extraKeys),
+        value: Object.assign({}, structuredClone(cache.value), extraKeys),
       };
     }
 
     // Return a deep-cloned value so each occurrence is an independent copy
-    return { circular: cache.circular, value: cloneDeep(cache.value) };
+    return { circular: cache.circular, value: structuredClone(cache.value) };
   }
 
   const pointer = $refs._resolve($refPath, path, options);
@@ -243,7 +220,7 @@ function dereference$Ref<S extends object = JSONSchema>(
     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/{lib → src}/index.ts

@@ -1,35 +1,35 @@
-import $Refs from "./refs.js";
-import { newFile, parseFile } from "./parse.js";
-import { resolveExternal } from "./resolve-external.js";
-import { bundle as _bundle } from "./bundle.js";
-import _dereference from "./dereference.js";
-import * as url from "./util/url.js";
-import { isHandledError, JSONParserErrorGroup } from "./util/errors.js";
-import { ono } from "@jsdevtools/ono";
-import { getJsonSchemaRefParserDefaultOptions } from "./options.js";
-import type { JSONSchema } from "./types/index.js";
-import { urlResolver } from "./resolvers/url.js";
-import { fileResolver } from "./resolvers/file.js";
+import { ono } from '@jsdevtools/ono';
+
+import { bundle as _bundle } from './bundle';
+import { getJsonSchemaRefParserDefaultOptions } from './options';
+import { newFile, parseFile } from './parse';
+import $Refs from './refs';
+import { resolveExternal } from './resolve-external';
+import { fileResolver } from './resolvers/file';
+import { urlResolver } from './resolvers/url';
+import type { JSONSchema } from './types';
+import { isHandledError, JSONParserErrorGroup } from './util/errors';
+import * as url from './util/url';
 
 interface ResolvedInput {
   path: string;
   schema: string | JSONSchema | Buffer | Awaited<JSONSchema> | undefined;
-  type: "file" | "json" | "url";
+  type: 'file' | 'json' | 'url';
 }
 
-export const getResolvedInput = ({
+export function getResolvedInput({
   pathOrUrlOrSchema,
 }: {
   pathOrUrlOrSchema: JSONSchema | string | unknown;
-}): ResolvedInput => {
+}): ResolvedInput {
   if (!pathOrUrlOrSchema) {
     throw ono(`Expected a file path, URL, or object. Got ${pathOrUrlOrSchema}`);
   }
 
   const resolvedInput: ResolvedInput = {
-    path: typeof pathOrUrlOrSchema === "string" ? pathOrUrlOrSchema : "",
+    path: typeof pathOrUrlOrSchema === 'string' ? pathOrUrlOrSchema : '',
     schema: undefined,
-    type: "url",
+    type: 'url',
   };
 
   // If the path is a filesystem path, then convert it to a URL.
@@ -40,34 +40,27 @@ export const getResolvedInput = ({
   // If it doesn't work for your use-case, then use a URL instead.
   if (resolvedInput.path && url.isFileSystemPath(resolvedInput.path)) {
     resolvedInput.path = url.fromFileSystemPath(resolvedInput.path);
-    resolvedInput.type = "file";
-  } else if (!resolvedInput.path && pathOrUrlOrSchema && typeof pathOrUrlOrSchema === "object") {
-    if ("$id" in pathOrUrlOrSchema && pathOrUrlOrSchema.$id) {
+    resolvedInput.type = 'file';
+  } else if (!resolvedInput.path && pathOrUrlOrSchema && typeof pathOrUrlOrSchema === 'object') {
+    if ('$id' in pathOrUrlOrSchema && pathOrUrlOrSchema.$id) {
       // when schema id has defined an URL should use that hostname to request the references,
       // instead of using the current page URL
       const { hostname, protocol } = new URL(pathOrUrlOrSchema.$id as string);
-      resolvedInput.path = `${protocol}//${hostname}:${protocol === "https:" ? 443 : 80}`;
-      resolvedInput.type = "url";
+      resolvedInput.path = `${protocol}//${hostname}:${protocol === 'https:' ? 443 : 80}`;
+      resolvedInput.type = 'url';
     } else {
       resolvedInput.schema = pathOrUrlOrSchema;
-      resolvedInput.type = "json";
+      resolvedInput.type = 'json';
     }
   }
 
-  if (resolvedInput.type !== "json") {
+  if (resolvedInput.type !== 'json') {
     // resolve the absolute path of the schema
     resolvedInput.path = url.resolve(url.cwd(), resolvedInput.path);
   }
 
   return resolvedInput;
-};
-
-const _ensureResolvedInputPath = (input: ResolvedInput, fallbackPath: string): ResolvedInput => {
-  if (input.type === "json" && (!input.path || input.path.length === 0)) {
-    return { ...input, path: fallbackPath };
-  }
-  return input;
-};
+}
 
 // NOTE: previously used helper removed as unused
 
@@ -168,39 +161,6 @@ export class $RefParser {
     return this.schema!;
   }
 
-  /**
-   * 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.
-   *
-   * The dereference method maintains object reference equality, meaning that all `$ref` pointers that point to the same object will be replaced with references to the same object. Again, this is great for programmatic usage, but it does introduce the risk of circular references, so be careful if you intend to serialize the schema using `JSON.stringify()`. Consider using the bundle method instead, which does not create circular references.
-   *
-   * See https://apitools.dev/json-schema-ref-parser/docs/ref-parser.html#dereferenceschema-options-callback
-   *
-   * @param pathOrUrlOrSchema A JSON Schema object, or the file path or URL of a JSON Schema file.
-   */
-  public async dereference({
-    fetch,
-    pathOrUrlOrSchema,
-  }: {
-    fetch?: RequestInit;
-    pathOrUrlOrSchema: JSONSchema | string | unknown;
-  }): Promise<JSONSchema> {
-    await this.parse({
-      fetch,
-      pathOrUrlOrSchema,
-    });
-    await resolveExternal(this, this.options);
-    const errors = JSONParserErrorGroup.getParserErrors(this);
-    if (errors.length > 0) {
-      throw new JSONParserErrorGroup(this);
-    }
-    _dereference(this, this.options);
-    const errors2 = JSONParserErrorGroup.getParserErrors(this);
-    if (errors2.length > 0) {
-      throw new JSONParserErrorGroup(this);
-    }
-    return this.schema!;
-  }
-
   /**
    * Parses the given JSON schema.
    * This method does not resolve any JSON references.
@@ -231,9 +191,9 @@ export class $RefParser {
     if (schema) {
       // immediately add a new $Ref with the schema object as value
       const $ref = this.$refs._add(path);
-      $ref.pathType = url.isFileSystemPath(path) ? "file" : "http";
+      $ref.pathType = url.isFileSystemPath(path) ? 'file' : 'http';
       $ref.value = schema;
-    } else if (type !== "json") {
+    } else if (type !== 'json') {
       const file = newFile(path);
 
       // Add a new $Ref for this file, even though we don't have the value yet.
@@ -241,25 +201,24 @@ export class $RefParser {
       const $refAdded = this.$refs._add(file.url);
       $refAdded.pathType = type;
       try {
-        const resolver = type === "file" ? fileResolver : urlResolver;
+        const resolver = type === 'file' ? fileResolver : urlResolver;
         await resolver.handler({
           arrayBuffer,
           fetch,
           file,
         });
-        const parseResult = await parseFile(file, this.options);
+        const parseResult = await parseFile(file, this.options.parse);
         $refAdded.value = parseResult.result;
         schema = parseResult.result;
-      } catch (err) {
-        if (isHandledError(err)) {
-          $refAdded.value = err;
+      } catch (error) {
+        if (isHandledError(error)) {
+          $refAdded.value = error;
         }
-
-        throw err;
+        throw error;
       }
     }
 
-    if (schema === null || typeof schema !== "object" || Buffer.isBuffer(schema)) {
+    if (schema === null || typeof schema !== 'object' || Buffer.isBuffer(schema)) {
       throw ono.syntax(`"${this.$refs._root$Ref.path || schema}" is not a valid JSON Schema`);
     }
 
@@ -282,20 +241,23 @@ export class $RefParser {
     resolvedInputs?: ResolvedInput[];
   }): Promise<{ schemaMany: JSONSchema[] }> {
     const resolvedInputs = [...(_resolvedInputs || [])];
-    resolvedInputs.push(...(pathOrUrlOrSchemas.map((schema) => getResolvedInput({ pathOrUrlOrSchema: schema })) || []));
+    resolvedInputs.push(
+      ...(pathOrUrlOrSchemas.map((schema) => getResolvedInput({ pathOrUrlOrSchema: schema })) ||
+        []),
+    );
 
     this.schemaMany = [];
     this.schemaManySources = [];
     this.sourcePathToPrefix = new Map();
 
     for (let i = 0; i < resolvedInputs.length; i++) {
-      const resolvedInput = resolvedInputs[i];
+      const resolvedInput = resolvedInputs[i]!;
       const { path, type } = resolvedInput;
       let { schema } = resolvedInput;
 
       if (schema) {
         // keep schema as-is
-      } else if (type !== "json") {
+      } else if (type !== 'json') {
         const file = newFile(path);
 
         // Add a new $Ref for this file, even though we don't have the value yet.
@@ -303,25 +265,24 @@ export class $RefParser {
         const $refAdded = this.$refs._add(file.url);
         $refAdded.pathType = type;
         try {
-          const resolver = type === "file" ? fileResolver : urlResolver;
+          const resolver = type === 'file' ? fileResolver : urlResolver;
           await resolver.handler({
             arrayBuffer: arrayBuffer?.[i],
             fetch,
             file,
           });
-          const parseResult = await parseFile(file, this.options);
+          const parseResult = await parseFile(file, this.options.parse);
           $refAdded.value = parseResult.result;
           schema = parseResult.result;
-        } catch (err) {
-          if (isHandledError(err)) {
-            $refAdded.value = err;
+        } catch (error) {
+          if (isHandledError(error)) {
+            $refAdded.value = error;
           }
-
-          throw err;
+          throw error;
         }
       }
 
-      if (schema === null || typeof schema !== "object" || Buffer.isBuffer(schema)) {
+      if (schema === null || typeof schema !== 'object' || Buffer.isBuffer(schema)) {
         throw ono.syntax(`"${this.$refs._root$Ref.path || schema}" is not a valid JSON Schema`);
       }
 
@@ -337,7 +298,7 @@ export class $RefParser {
   public mergeMany(): JSONSchema {
     const schemas = this.schemaMany || [];
     if (schemas.length === 0) {
-      throw ono("mergeMany called with no schemas. Did you run parseMany?");
+      throw ono('mergeMany called with no schemas. Did you run parseMany?');
     }
 
     const merged: any = {};
@@ -346,19 +307,19 @@ export class $RefParser {
     let chosenOpenapi: string | undefined;
     let chosenSwagger: string | undefined;
     for (const s of schemas) {
-      if (!chosenOpenapi && s && typeof (s as any).openapi === "string") {
+      if (!chosenOpenapi && s && typeof (s as any).openapi === 'string') {
         chosenOpenapi = (s as any).openapi;
       }
-      if (!chosenSwagger && s && typeof (s as any).swagger === "string") {
+      if (!chosenSwagger && s && typeof (s as any).swagger === 'string') {
         chosenSwagger = (s as any).swagger;
       }
       if (chosenOpenapi && chosenSwagger) {
         break;
       }
     }
-    if (typeof chosenOpenapi === "string") {
+    if (typeof chosenOpenapi === 'string') {
       merged.openapi = chosenOpenapi;
-    } else if (typeof chosenSwagger === "string") {
+    } else if (typeof chosenSwagger === 'string') {
       merged.swagger = chosenSwagger;
     }
 
@@ -366,7 +327,7 @@ export class $RefParser {
     const infoAccumulator: any = {};
     for (const s of schemas) {
       const info = (s as any)?.info;
-      if (info && typeof info === "object") {
+      if (info && typeof info === 'object') {
         for (const [k, v] of Object.entries(info)) {
           if (infoAccumulator[k] === undefined && v !== undefined) {
             infoAccumulator[k] = JSON.parse(JSON.stringify(v));
@@ -385,8 +346,8 @@ export class $RefParser {
       const arr = (s as any)?.servers;
       if (Array.isArray(arr)) {
         for (const srv of arr) {
-          if (srv && typeof srv === "object") {
-            const key = `${srv.url || ""}|${srv.description || ""}`;
+          if (srv && typeof srv === 'object') {
+            const key = `${srv.url || ''}|${srv.description || ''}`;
             if (!seenServers.has(key)) {
               seenServers.add(key);
               servers.push(JSON.parse(JSON.stringify(srv)));
@@ -403,15 +364,15 @@ export class $RefParser {
     merged.components = {};
 
     const componentSections = [
-      "schemas",
-      "parameters",
-      "requestBodies",
-      "responses",
-      "headers",
-      "securitySchemes",
-      "examples",
-      "links",
-      "callbacks",
+      'schemas',
+      'parameters',
+      'requestBodies',
+      'responses',
+      'headers',
+      'securitySchemes',
+      'examples',
+      'links',
+      'callbacks',
     ];
     for (const sec of componentSections) {
       merged.components[sec] = {};
@@ -423,14 +384,14 @@ export class $RefParser {
 
     const baseName = (p: string) => {
       try {
-        const withoutHash = p.split("#")[0];
-        const parts = withoutHash.split("/");
-        const filename = parts[parts.length - 1] || "schema";
-        const dot = filename.lastIndexOf(".");
+        const withoutHash = p.split('#')[0]!;
+        const parts = withoutHash.split('/');
+        const filename = parts[parts.length - 1] || 'schema';
+        const dot = filename.lastIndexOf('.');
         const raw = dot > 0 ? filename.substring(0, dot) : filename;
-        return raw.replace(/[^A-Za-z0-9_-]/g, "_");
+        return raw.replace(/[^A-Za-z0-9_-]/g, '_');
       } catch {
-        return "schema";
+        return 'schema';
       }
     };
     const unique = (set: Set<string>, proposed: string) => {
@@ -450,7 +411,7 @@ export class $RefParser {
         const base = `#/components/${m[1]}/${m[2]}`;
         const mapped = refMap.get(base);
         if (mapped) {
-          return mapped + (m[3] || "");
+          return mapped + (m[3] || '');
         }
       }
       // OAS2: #/definitions/{name}...
@@ -460,7 +421,7 @@ export class $RefParser {
         const mapped = refMap.get(base);
         if (mapped) {
           // map definitions -> components/schemas
-          return mapped + (m[2] || "");
+          return mapped + (m[2] || '');
         }
       }
       return ref;
@@ -479,28 +440,28 @@ export class $RefParser {
       if (Array.isArray(obj)) {
         return obj.map((v) => cloneAndRewrite(v, refMap, tagMap, opIdPrefix, basePath));
       }
-      if (typeof obj !== "object") {
+      if (typeof obj !== 'object') {
         return obj;
       }
 
       const out: any = {};
       for (const [k, v] of Object.entries(obj)) {
-        if (k === "$ref" && typeof v === "string") {
+        if (k === '$ref' && typeof v === 'string') {
           const s = v as string;
-          if (s.startsWith("#")) {
+          if (s.startsWith('#')) {
             out[k] = rewriteRef(s, refMap);
           } else {
             const proto = url.getProtocol(s);
             if (proto === undefined) {
               // relative external ref -> absolutize against source base path
-              out[k] = url.resolve(basePath + "#", s);
+              out[k] = url.resolve(basePath + '#', s);
             } else {
               out[k] = s;
             }
           }
-        } else if (k === "tags" && Array.isArray(v) && v.every((x) => typeof x === "string")) {
+        } else if (k === 'tags' && Array.isArray(v) && v.every((x) => typeof x === 'string')) {
           out[k] = v.map((t) => tagMap.get(t) || t);
-        } else if (k === "operationId" && typeof v === "string") {
+        } else if (k === 'operationId' && typeof v === 'string') {
           out[k] = unique(usedOpIds, `${opIdPrefix}_${v}`);
         } else {
           out[k] = cloneAndRewrite(v as any, refMap, tagMap, opIdPrefix, basePath);
@@ -517,7 +478,12 @@ export class $RefParser {
       // Track prefix for this source path (strip hash). Only map real file/http paths
       const withoutHash = url.stripHash(sourcePath);
       const protocol = url.getProtocol(withoutHash);
-      if (protocol === undefined || protocol === "file" || protocol === "http" || protocol === "https") {
+      if (
+        protocol === undefined ||
+        protocol === 'file' ||
+        protocol === 'http' ||
+        protocol === 'https'
+      ) {
         this.sourcePathToPrefix.set(withoutHash, prefix);
       }
 
@@ -535,7 +501,7 @@ export class $RefParser {
 
       const srcTags: any[] = Array.isArray(schema.tags) ? schema.tags : [];
       for (const t of srcTags) {
-        if (!t || typeof t !== "object" || typeof t.name !== "string") {
+        if (!t || typeof t !== 'object' || typeof t.name !== 'string') {
           continue;
         }
         const desired = t.name;
@@ -551,7 +517,13 @@ export class $RefParser {
         const group = (schema.components && schema.components[sec]) || {};
         for (const [name, val] of Object.entries(group)) {
           const newName = `${prefix}_${name}`;
-          merged.components[sec][newName] = cloneAndRewrite(val, refMap, tagMap, prefix, url.stripHash(sourcePath));
+          merged.components[sec][newName] = cloneAndRewrite(
+            val,
+            refMap,
+            tagMap,
+            prefix,
+            url.stripHash(sourcePath),
+          );
         }
       }
 
@@ -559,10 +531,16 @@ export class $RefParser {
       for (const [p, item] of Object.entries(srcPaths)) {
         let targetPath = p;
         if (merged.paths[p]) {
-          const trimmed = p.startsWith("/") ? p.substring(1) : p;
+          const trimmed = p.startsWith('/') ? p.substring(1) : p;
           targetPath = `/${prefix}/${trimmed}`;
         }
-        merged.paths[targetPath] = cloneAndRewrite(item, refMap, tagMap, prefix, url.stripHash(sourcePath));
+        merged.paths[targetPath] = cloneAndRewrite(
+          item,
+          refMap,
+          tagMap,
+          prefix,
+          url.stripHash(sourcePath),
+        );
       }
     }
 
@@ -574,12 +552,12 @@ export class $RefParser {
     const rootPath = this.schemaManySources[0] || url.cwd();
     this.$refs = new $Refs();
     const rootRef = this.$refs._add(rootPath);
-    rootRef.pathType = url.isFileSystemPath(rootPath) ? "file" : "http";
+    rootRef.pathType = url.isFileSystemPath(rootPath) ? 'file' : 'http';
     rootRef.value = merged;
     this.schema = merged;
     return merged as JSONSchema;
   }
 }
 
-export { sendRequest } from "./resolvers/url.js";
-export type { JSONSchema } from "./types/index.js";
+export { sendRequest } from './resolvers/url';
+export type { JSONSchema } from './types';

package/{lib → src}/options.ts

@@ -1,9 +1,8 @@
-import { jsonParser } from "./parsers/json.js";
-import { yamlParser } from "./parsers/yaml.js";
-import { textParser } from "./parsers/text.js";
-import { binaryParser } from "./parsers/binary.js";
-
-import type { JSONSchemaObject, Plugin } from "./types/index.js";
+import { binaryParser } from './parsers/binary';
+import { jsonParser } from './parsers/json';
+import { textParser } from './parsers/text';
+import { yamlParser } from './parsers/yaml';
+import type { JSONSchemaObject, Plugin } from './types';
 
 export interface DereferenceOptions {
   /**
@@ -13,7 +12,7 @@ export interface DereferenceOptions {
    *
    * 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";
+  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
@@ -28,7 +27,12 @@ export interface DereferenceOptions {
    * @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;
+  onDereference?(
+    path: string,
+    value: JSONSchemaObject,
+    parent?: JSONSchemaObject,
+    parentPropName?: string,
+  ): void;
 }
 
 /**
@@ -82,7 +86,7 @@ export const getJsonSchemaRefParserDefaultOptions = (): $RefParserOptions => ({
      */
     excludedPathMatcher: () => false,
     // @ts-expect-error
-    referenceResolution: "relative",
+    referenceResolution: 'relative',
   },
   /**
    * Determines how different types of files will be parsed.