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

package/{lib → src}/parse.ts

@@ -1,10 +1,11 @@
-import { ono } from "@jsdevtools/ono";
-import { getExtension } from "./util/url.js";
-import * as plugins from "./util/plugins.js";
-import type { PluginResult } from "./util/plugins.js";
-import { ParserError } from "./util/errors.js";
-import type { $RefParserOptions } from "./options.js";
-import type { FileInfo } from "./types/index.js";
+import { ono } from '@jsdevtools/ono';
+
+import type { $RefParserOptions } from './options';
+import type { FileInfo } from './types';
+import { ParserError } from './util/errors';
+import type { PluginResult } from './util/plugins';
+import * as plugins from './util/plugins';
+import { getExtension } from './util/url';
 
 /**
  * Prepares the file object so we can populate it with data and other values
@@ -14,8 +15,8 @@ import type { FileInfo } from "./types/index.js";
 export function newFile(path: string): FileInfo {
   let url = path;
   // Remove the URL fragment, if any
-  const hashIndex = url.indexOf("#");
-  let hash = "";
+  const hashIndex = url.indexOf('#');
+  let hash = '';
   if (hashIndex > -1) {
     hash = url.substring(hashIndex);
     url = url.substring(0, hashIndex);
@@ -30,23 +31,26 @@ export function newFile(path: string): FileInfo {
 /**
  * Parses the given file's contents, using the configured parser plugins.
  */
-export const parseFile = async (file: FileInfo, options: $RefParserOptions): Promise<PluginResult> => {
+export async function parseFile(
+  file: FileInfo,
+  options: $RefParserOptions['parse'],
+): Promise<PluginResult> {
   try {
     // If none of the parsers are a match for this file, try all of them. This
     // handles situations where the file is a supported type, just with an
     // unknown extension.
-    const parsers = [options.parse.json, options.parse.yaml, options.parse.text, options.parse.binary];
+    const parsers = [options.json, options.yaml, options.text, options.binary];
     const filtered = parsers.filter((plugin) => plugin.canHandle(file));
     return await plugins.run(filtered.length ? filtered : parsers, file);
   } catch (error: any) {
-    if (error && error.message && error.message.startsWith("Error parsing")) {
+    if (error && error.message && error.message.startsWith('Error parsing')) {
       throw error;
     }
-    
-    if (!error || !("error" in error)) {
+
+    if (!error || !('error' in error)) {
       throw ono.syntax(`Unable to parse ${file.url}`);
     }
-    
+
     if (error.error instanceof ParserError) {
       throw error.error;
     }

package/src/parsers/binary.ts

@@ -0,0 +1,13 @@
+import type { FileInfo, Plugin } from '../types';
+
+const BINARY_REGEXP = /\.(jpeg|jpg|gif|png|bmp|ico)$/i;
+
+export const binaryParser: Plugin = {
+  canHandle: (file: FileInfo) => Buffer.isBuffer(file.data) && BINARY_REGEXP.test(file.url),
+  handler: (file: FileInfo): Buffer =>
+    Buffer.isBuffer(file.data)
+      ? file.data
+      : // This will reject if data is anything other than a string or typed array
+        Buffer.from(file.data),
+  name: 'binary',
+};

package/{lib → src}/parsers/json.ts

@@ -1,6 +1,5 @@
-import { ParserError } from "../util/errors.js";
-import type { FileInfo } from "../types/index.js";
-import type { Plugin } from "../types/index.js";
+import type { FileInfo, Plugin } from '../types';
+import { ParserError } from '../util/errors';
 
 export const jsonParser: Plugin = {
   canHandle: (file: FileInfo) => file.extension === '.json',
@@ -10,7 +9,7 @@ export const jsonParser: Plugin = {
       data = data.toString();
     }
 
-    if (typeof data !== "string") {
+    if (typeof data !== 'string') {
       // data is already a JavaScript value (object, array, number, null, NaN, etc.)
       return data as object;
     }
@@ -22,11 +21,11 @@ export const jsonParser: Plugin = {
 
     try {
       return JSON.parse(data);
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
     } catch (error: any) {
       try {
         // find the first curly brace
-        const firstCurlyBrace = data.indexOf("{");
+        const firstCurlyBrace = data.indexOf('{');
         // remove any characters before the first curly brace
         data = data.slice(firstCurlyBrace);
         return JSON.parse(data);

package/src/parsers/text.ts

@@ -0,0 +1,21 @@
+import type { FileInfo, Plugin } from '../types';
+import { ParserError } from '../util/errors';
+
+const TEXT_REGEXP = /\.(txt|htm|html|md|xml|js|min|map|css|scss|less|svg)$/i;
+
+export const textParser: Plugin = {
+  canHandle: (file: FileInfo) =>
+    (typeof file.data === 'string' || Buffer.isBuffer(file.data)) && TEXT_REGEXP.test(file.url),
+  handler(file: FileInfo): string {
+    if (typeof file.data === 'string') {
+      return file.data;
+    }
+
+    if (!Buffer.isBuffer(file.data)) {
+      throw new ParserError('data is not text', file.url);
+    }
+
+    return file.data.toString('utf-8');
+  },
+  name: 'text',
+};

package/{lib → src}/parsers/yaml.ts

@@ -1,25 +1,25 @@
-import { ParserError } from "../util/errors.js";
-import yaml from "js-yaml";
-import { JSON_SCHEMA } from "js-yaml";
-import type { FileInfo, JSONSchema } from "../types/index.js";
-import type { Plugin } from "../types/index.js";
+import yaml from 'js-yaml';
+import { JSON_SCHEMA } from 'js-yaml';
+
+import type { FileInfo, JSONSchema, Plugin } from '../types';
+import { ParserError } from '../util/errors';
 
 export const yamlParser: Plugin = {
   // JSON is valid YAML
-  canHandle: (file: FileInfo) => [".yaml", ".yml", ".json"].includes(file.extension),
+  canHandle: (file: FileInfo) => ['.yaml', '.yml', '.json'].includes(file.extension),
   handler: async (file: FileInfo): Promise<JSONSchema> => {
     const data = Buffer.isBuffer(file.data) ? file.data.toString() : file.data;
 
-    if (typeof data !== "string") {
+    if (typeof data !== 'string') {
       // data is already a JavaScript value (object, array, number, null, NaN, etc.)
       return data;
     }
 
     try {
-      const yamlSchema = yaml.load(data, { schema: JSON_SCHEMA }) as JSONSchema
+      const yamlSchema = yaml.load(data, { schema: JSON_SCHEMA }) as JSONSchema;
       return yamlSchema;
     } catch (error: any) {
-      throw new ParserError(error?.message || "Parser Error", file.url);
+      throw new ParserError(error?.message || 'Parser Error', file.url);
     }
   },
   name: 'yaml',

package/{lib → src}/pointer.ts

@@ -1,9 +1,13 @@
-import type { ParserOptions } from "./options.js";
-
-import $Ref from "./ref.js";
-import * as url from "./util/url.js";
-import { JSONParserError, InvalidPointerError, MissingPointerError, isHandledError } from "./util/errors.js";
-import type { JSONSchema } from "./types";
+import type { ParserOptions } from './options';
+import $Ref from './ref';
+import type { JSONSchema } from './types';
+import {
+  InvalidPointerError,
+  isHandledError,
+  JSONParserError,
+  MissingPointerError,
+} from './util/errors';
+import * as url from './util/url';
 
 const slashes = /\//g;
 const tildes = /~/g;
@@ -100,16 +104,24 @@ class Pointer<S extends object = JSONSchema> {
         this.path = Pointer.join(this.path, tokens.slice(i));
       }
 
-      if (typeof this.value === "object" && this.value !== null && !isRootPath(pathFromRoot) && "$ref" in this.value) {
+      if (
+        typeof this.value === 'object' &&
+        this.value !== null &&
+        !isRootPath(pathFromRoot) &&
+        '$ref' in this.value
+      ) {
         return this;
       }
 
-      const token = tokens[i];
-      if (this.value[token] === undefined || (this.value[token] === null && i === tokens.length - 1)) {
+      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("/");
+          const joinedToken = tokens.slice(i, j + 1).join('/');
           if (this.value[joinedToken] !== undefined) {
             this.value = this.value[joinedToken];
             i = j;
@@ -129,11 +141,16 @@ class Pointer<S extends object = JSONSchema> {
     }
 
     if (errors.length > 0) {
-      throw errors.length === 1 ? errors[0] : new AggregateError(errors, "Multiple missing pointer errors");
+      throw errors.length === 1
+        ? errors[0]
+        : new AggregateError(errors, 'Multiple missing pointer errors');
     }
 
     // Resolve the final value
-    if (!this.value || (this.value.$ref && url.resolve(this.path, this.value.$ref) !== pathFromRoot)) {
+    if (
+      !this.value ||
+      (this.value.$ref && url.resolve(this.path, this.value.$ref) !== pathFromRoot)
+    ) {
       resolveIf$Ref(this, options, pathFromRoot);
     }
 
@@ -166,7 +183,7 @@ class Pointer<S extends object = JSONSchema> {
     for (let i = 0; i < tokens.length - 1; i++) {
       resolveIf$Ref(this, options);
 
-      token = tokens[i];
+      token = tokens[i]!;
       if (this.value && this.value[token] !== undefined) {
         // The token exists
         this.value = this.value[token];
@@ -208,14 +225,16 @@ class Pointer<S extends object = JSONSchema> {
     }
 
     // Split into an array
-    const split = pointer.split("/");
+    const split = pointer.split('/');
 
     // Decode each part, according to RFC 6901
     for (let i = 0; i < split.length; i++) {
-      split[i] = safeDecodeURIComponent(split[i].replace(escapedSlash, "/").replace(escapedTilde, "~"));
+      split[i] = safeDecodeURIComponent(
+        split[i]!.replace(escapedSlash, '/').replace(escapedTilde, '~'),
+      );
     }
 
-    if (split[0] !== "") {
+    if (split[0] !== '') {
       throw new InvalidPointerError(pointer, originalPath === undefined ? path : originalPath);
     }
 
@@ -231,16 +250,16 @@ class Pointer<S extends object = JSONSchema> {
    */
   static join(base: string, tokens: string | string[]) {
     // Ensure that the base path contains a hash
-    if (base.indexOf("#") === -1) {
-      base += "#";
+    if (base.indexOf('#') === -1) {
+      base += '#';
     }
 
     // Append each token to the base path
     tokens = Array.isArray(tokens) ? tokens : [tokens];
     for (let i = 0; i < tokens.length; i++) {
-      const token = tokens[i];
+      const token = tokens[i]!;
       // Encode the token, according to RFC 6901
-      base += "/" + encodeURIComponent(token.replace(tildes, "~0").replace(slashes, "~1"));
+      base += '/' + encodeURIComponent(token.replace(tildes, '~0').replace(slashes, '~1'));
     }
 
     return base;
@@ -306,8 +325,8 @@ export default Pointer;
  * @returns - Returns the assigned value
  */
 function setValue(pointer: any, token: any, value: any) {
-  if (pointer.value && typeof pointer.value === "object") {
-    if (token === "-" && Array.isArray(pointer.value)) {
+  if (pointer.value && typeof pointer.value === 'object') {
+    if (token === '-' && Array.isArray(pointer.value)) {
       pointer.value.push(value);
     } else {
       pointer.value[token] = value;
@@ -329,5 +348,5 @@ function unwrapOrThrow(value: any) {
 }
 
 function isRootPath(pathFromRoot: any): boolean {
-  return typeof pathFromRoot == "string" && Pointer.parse(pathFromRoot).length == 0;
+  return typeof pathFromRoot == 'string' && Pointer.parse(pathFromRoot).length == 0;
 }

package/{lib → src}/ref.ts

@@ -1,9 +1,14 @@
-import Pointer from "./pointer.js";
-import type { JSONParserError, MissingPointerError, ParserError, ResolverError } from "./util/errors.js";
-import { normalizeError } from "./util/errors.js";
-import type $Refs from "./refs.js";
-import type { ParserOptions } from "./options.js";
-import type { JSONSchema } from "./types";
+import type { ParserOptions } from './options';
+import Pointer from './pointer';
+import type $Refs from './refs';
+import type { JSONSchema } from './types';
+import type {
+  JSONParserError,
+  MissingPointerError,
+  ParserError,
+  ResolverError,
+} from './util/errors';
+import { normalizeError } from './util/errors';
 
 export type $RefError = JSONParserError | ResolverError | ParserError | MissingPointerError;
 
@@ -70,11 +75,13 @@ class $Ref<S extends object = JSONSchema> {
     // the path has been almost certainly set at this point,
     // but just in case something went wrong, normalizeError injects path if necessary
     // moreover, certain errors might point at the same spot, so filter them out to reduce noise
-    if ("errors" in err && Array.isArray(err.errors)) {
+    if ('errors' in err && Array.isArray(err.errors)) {
       this.errors.push(
-        ...err.errors.map(normalizeError).filter(({ footprint }: any) => !existingErrors.includes(footprint)),
+        ...err.errors
+          .map(normalizeError)
+          .filter(({ footprint }: any) => !existingErrors.includes(footprint)),
       );
-    } else if (!("footprint" in err) || !existingErrors.includes(err.footprint)) {
+    } else if (!('footprint' in err) || !existingErrors.includes(err.footprint)) {
       this.errors.push(normalizeError(err));
     }
   }
@@ -141,10 +148,10 @@ class $Ref<S extends object = JSONSchema> {
   static is$Ref(value: unknown): value is { $ref: string; length?: number } {
     return (
       Boolean(value) &&
-      typeof value === "object" &&
+      typeof value === 'object' &&
       value !== null &&
-      "$ref" in value &&
-      typeof value.$ref === "string" &&
+      '$ref' in value &&
+      typeof value.$ref === 'string' &&
       value.$ref.length > 0
     );
   }
@@ -156,7 +163,7 @@ class $Ref<S extends object = JSONSchema> {
    * @returns
    */
   static isExternal$Ref(value: unknown): boolean {
-    return $Ref.is$Ref(value) && value.$ref![0] !== "#";
+    return $Ref.is$Ref(value) && value.$ref![0] !== '#';
   }
 
   /**
@@ -168,10 +175,10 @@ class $Ref<S extends object = JSONSchema> {
    */
   static isAllowed$Ref(value: unknown) {
     if (this.is$Ref(value)) {
-      if (value.$ref.substring(0, 2) === "#/" || value.$ref === "#") {
+      if (value.$ref.substring(0, 2) === '#/' || value.$ref === '#') {
         // It's a JSON Pointer reference, which is always allowed
         return true;
-      } else if (value.$ref[0] !== "#") {
+      } else if (value.$ref[0] !== '#') {
         // It's an external reference, which is allowed by the options
         return true;
       }
@@ -248,14 +255,11 @@ class $Ref<S extends object = JSONSchema> {
    * @param resolvedValue - The resolved value, which can be any type
    * @returns - Returns the dereferenced value
    */
-  static dereference<S extends object = JSONSchema>(
-    $ref: $Ref<S>,
-    resolvedValue: S,
-  ): S {
-    if (resolvedValue && typeof resolvedValue === "object" && $Ref.isExtended$Ref($ref)) {
+  static dereference<S extends object = JSONSchema>($ref: $Ref<S>, resolvedValue: S): S {
+    if (resolvedValue && typeof resolvedValue === 'object' && $Ref.isExtended$Ref($ref)) {
       const merged = {};
       for (const key of Object.keys($ref)) {
-        if (key !== "$ref") {
+        if (key !== '$ref') {
           // @ts-expect-error TS(7053): Element implicitly has an 'any' type because expre... Remove this comment to see the full error message
           merged[key] = $ref[key];
         }

package/{lib → src}/refs.ts

@@ -1,10 +1,11 @@
-import { ono } from "@jsdevtools/ono";
-import $Ref from "./ref.js";
-import * as url from "./util/url.js";
-import type { JSONSchema4Type, JSONSchema6Type, JSONSchema7Type } from "json-schema";
-import type { ParserOptions } from "./options.js";
-import convertPathToPosix from "./util/convert-path-to-posix";
-import type { JSONSchema } from "./types";
+import { ono } from '@jsdevtools/ono';
+import type { JSONSchema4Type, JSONSchema6Type, JSONSchema7Type } from 'json-schema';
+
+import type { ParserOptions } from './options';
+import $Ref from './ref';
+import type { JSONSchema } from './types';
+import convertPathToPosix from './util/convert-path-to-posix';
+import * as url from './util/url';
 
 interface $RefsMap<S extends object = JSONSchema> {
   [url: string]: $Ref<S>;
@@ -33,9 +34,7 @@ export default class $Refs<S extends object = JSONSchema> {
    */
   paths(...types: (string | string[])[]): string[] {
     const paths = getPaths(this._$refs, types.flat());
-    return paths.map((path) => {
-      return convertPathToPosix(path.decoded);
-    });
+    return paths.map((path) => convertPathToPosix(path.decoded));
   }
 
   /**
@@ -49,7 +48,7 @@ export default class $Refs<S extends object = JSONSchema> {
     const $refs = this._$refs;
     const paths = getPaths($refs, types.flat());
     return paths.reduce<Record<string, any>>((obj, path) => {
-      obj[convertPathToPosix(path.decoded)] = $refs[path.encoded].value;
+      obj[convertPathToPosix(path.decoded)] = $refs[path.encoded]!.value;
       return obj;
     }, {}) as S;
   }
@@ -70,7 +69,7 @@ export default class $Refs<S extends object = JSONSchema> {
    */
   exists(path: string, options: any) {
     try {
-      this._resolve(path, "", options);
+      this._resolve(path, '', options);
       return true;
     } catch {
       return false;
@@ -85,7 +84,7 @@ export default class $Refs<S extends object = JSONSchema> {
    * @returns - Returns the resolved value
    */
   get(path: string, options?: ParserOptions): JSONSchema4Type | JSONSchema6Type | JSONSchema7Type {
-    return this._resolve(path, "", options)!.value;
+    return this._resolve(path, '', options)!.value;
   }
 
   /**
@@ -153,6 +152,11 @@ export default class $Refs<S extends object = JSONSchema> {
       throw ono(`Error resolving $ref pointer "${path}". \n"${withoutHash}" not found.`);
     }
 
+    if ($ref.value === undefined) {
+      console.warn(`$ref entry exists but value is undefined: ${withoutHash}`);
+      return null; // Treat as unresolved
+    }
+
     return $ref.resolve(absPath, options, path, pathFromRoot);
   }
 
@@ -215,25 +219,18 @@ export default class $Refs<S extends object = JSONSchema> {
  * @param [types] - Only return paths of the given types ("file", "http", etc.)
  * @returns
  */
-function getPaths<S extends object = JSONSchema>(
-  $refs: $RefsMap<S>,
-  types: string[],
-) {
+function getPaths<S extends object = JSONSchema>($refs: $RefsMap<S>, types: string[]) {
   let paths = Object.keys($refs);
 
   // Filter the paths by type
   types = Array.isArray(types[0]) ? types[0] : Array.prototype.slice.call(types);
   if (types.length > 0 && types[0]) {
-    paths = paths.filter((key) => {
-      return types.includes($refs[key].pathType as string);
-    });
+    paths = paths.filter((key) => types.includes($refs[key]!.pathType as string));
   }
 
   // Decode local filesystem paths
-  return paths.map((path) => {
-    return {
-      encoded: path,
-      decoded: $refs[path].pathType === "file" ? url.toFileSystemPath(path, true) : path,
-    };
-  });
+  return paths.map((path) => ({
+    decoded: $refs[path]!.pathType === 'file' ? url.toFileSystemPath(path, true) : path,
+    encoded: path,
+  }));
 }