@hey-api/json-schema-ref-parser 1.3.1 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hey-api/json-schema-ref-parser",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
   "keywords": [
     "$ref",
@@ -45,19 +45,17 @@
   "dependencies": {
     "@jsdevtools/ono": "7.1.3",
     "@types/json-schema": "7.0.15",
-    "js-yaml": "4.1.1"
+    "yaml": "2.8.3"
   },
   "devDependencies": {
-    "@types/js-yaml": "4.0.9",
-    "typescript": "5.9.3"
+    "typescript": "6.0.2"
   },
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.13.0"
   },
   "scripts": {
-    "build": "tsdown && pnpm check-exports",
-    "check-exports": "attw --pack . --profile esm-only --ignore-rules cjs-resolves-to-esm",
+    "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsgo --noEmit"
   }
 }

package/src/__tests__/bundle.test.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -11,6 +12,10 @@ const __dirname = path.dirname(__filename);
 const getSnapshotsPath = () => path.join(__dirname, '__snapshots__');
 const getTempSnapshotsPath = () => path.join(__dirname, '.gen', 'snapshots');
 
+const writeJsonFile = (filePath: string, value: unknown) => {
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
+};
+
 /**
  * Helper function to compare a bundled schema with a snapshot file.
  * Handles writing the schema to a temp file and comparing with the snapshot.
@@ -46,6 +51,176 @@ describe('bundle', () => {
     await expectBundledSchemaToMatchSnapshot(schema, 'circular-ref-with-description.json');
   });
 
+  it('emits decoded internal refs for generic component names', async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'json-schema-ref-parser-'));
+
+    try {
+      const rootPath = path.join(tempDir, 'root.json');
+
+      writeJsonFile(rootPath, {
+        components: {
+          schemas: {
+            ClientResponse: {
+              properties: {
+                id: {
+                  type: 'string',
+                },
+              },
+              type: 'object',
+            },
+            'PaginatedListItems<ClientResponse>': {
+              properties: {
+                items: {
+                  items: {
+                    $ref: '#/components/schemas/ClientResponse',
+                  },
+                  type: 'array',
+                },
+              },
+              type: 'object',
+            },
+          },
+        },
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        openapi: '3.0.0',
+        paths: {
+          '/clients': {
+            get: {
+              responses: {
+                '200': {
+                  content: {
+                    'application/json': {
+                      schema: {
+                        $ref: '#/components/schemas/PaginatedListItems<ClientResponse>',
+                      },
+                    },
+                  },
+                  description: 'ok',
+                },
+              },
+            },
+          },
+        },
+      });
+
+      const refParser = new $RefParser();
+      const schema = (await refParser.bundle({ pathOrUrlOrSchema: rootPath })) as any;
+
+      expect(
+        schema.paths['/clients'].get.responses['200'].content['application/json'].schema.$ref,
+      ).toBe('#/components/schemas/PaginatedListItems<ClientResponse>');
+
+      const bundledJson = JSON.stringify(schema);
+      expect(bundledJson).not.toContain('PaginatedListItems%3CClientResponse%3E');
+    } finally {
+      fs.rmSync(tempDir, { force: true, recursive: true });
+    }
+  });
+
+  it('emits decoded refs for external schemas with generic and unicode names', async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'json-schema-ref-parser-'));
+
+    try {
+      const externalPath = path.join(tempDir, 'external.json');
+      const rootPath = path.join(tempDir, 'root.json');
+
+      writeJsonFile(externalPath, {
+        components: {
+          schemas: {
+            'PaginatedList<ClientItem>': {
+              description: 'generic schema',
+              properties: {
+                next: {
+                  $ref: '#/components/schemas/PaginatedList<ClientItem>',
+                },
+              },
+              type: 'object',
+            },
+            Überschrift: {
+              description: 'unicode schema',
+              properties: {
+                next: {
+                  $ref: '#/components/schemas/Überschrift',
+                },
+              },
+              type: 'object',
+            },
+          },
+        },
+      });
+
+      writeJsonFile(rootPath, {
+        info: {
+          title: 'Test API',
+          version: '1.0.0',
+        },
+        openapi: '3.0.0',
+        paths: {
+          '/generic': {
+            get: {
+              responses: {
+                '200': {
+                  content: {
+                    'application/json': {
+                      schema: {
+                        $ref: 'external.json#/components/schemas/PaginatedList<ClientItem>',
+                      },
+                    },
+                  },
+                  description: 'ok',
+                },
+              },
+            },
+          },
+          '/unicode': {
+            get: {
+              responses: {
+                '200': {
+                  content: {
+                    'application/json': {
+                      schema: {
+                        $ref: 'external.json#/components/schemas/Überschrift',
+                      },
+                    },
+                  },
+                  description: 'ok',
+                },
+              },
+            },
+          },
+        },
+      });
+
+      const refParser = new $RefParser();
+      const schema = (await refParser.bundle({ pathOrUrlOrSchema: rootPath })) as any;
+      const schemas = schema.components.schemas as Record<string, any>;
+
+      const findSchemaByDescription = (description: string) =>
+        Object.entries(schemas).find(([, value]) => value.description === description);
+
+      const genericSchema = findSchemaByDescription('generic schema');
+      const unicodeSchema = findSchemaByDescription('unicode schema');
+
+      expect(genericSchema).toBeDefined();
+      expect(unicodeSchema).toBeDefined();
+
+      const [genericName, genericValue] = genericSchema!;
+      const [unicodeName, unicodeValue] = unicodeSchema!;
+
+      expect(genericValue.properties.next.$ref).toBe(`#/components/schemas/${genericName}`);
+      expect(unicodeValue.properties.next.$ref).toBe(`#/components/schemas/${unicodeName}`);
+
+      const bundledJson = JSON.stringify(schema);
+      expect(bundledJson).not.toContain('PaginatedList%3CClientItem%3E');
+      expect(bundledJson).not.toContain('%C3%9Cberschrift');
+    } finally {
+      fs.rmSync(tempDir, { force: true, recursive: true });
+    }
+  });
+
   it('bundles multiple references to the same file correctly', async () => {
     const refParser = new $RefParser();
     const pathOrUrlOrSchema = path.join(

package/src/__tests__/pointer.test.ts

@@ -1,9 +1,32 @@
 import path from 'node:path';
 
 import { $RefParser } from '..';
+import Pointer from '../pointer';
 import { getSpecsPath } from './utils';
 
 describe('pointer', () => {
+  it('round-trips generic and unicode component names through join and parse', () => {
+    const genericRef = Pointer.join('#/components/schemas', 'PaginatedListItems<ClientResponse>');
+    const unicodeRef = Pointer.join('#/components/schemas', 'Überschrift');
+
+    expect(genericRef).toBe('#/components/schemas/PaginatedListItems%3CClientResponse%3E');
+    expect(unicodeRef).toBe('#/components/schemas/%C3%9Cberschrift');
+
+    expect(Pointer.parse(genericRef)).toEqual([
+      'components',
+      'schemas',
+      'PaginatedListItems<ClientResponse>',
+    ]);
+    expect(Pointer.parse(unicodeRef)).toEqual(['components', 'schemas', 'Überschrift']);
+  });
+
+  it('preserves JSON Pointer escaping for path-like tokens while decoding them on parse', () => {
+    const joined = Pointer.join('#/paths', '/foo');
+
+    expect(joined).toBe('#/paths/~1foo');
+    expect(Pointer.parse(joined)).toEqual(['paths', '/foo']);
+  });
+
   it('inlines internal JSON Pointer refs under #/paths/ for OpenAPI bundling', async () => {
     const refParser = new $RefParser();
     const pathOrUrlOrSchema = path.join(

package/src/bundle.ts

@@ -92,7 +92,7 @@ const getContainerTypeFromPath = (
 };
 
 /**
- * Inventories the given JSON Reference (i.e. records detailed information about it so we can
+ * Inventories the given JSON Reference (i.e., records detailed information about it so we can
  * optimize all $refs in the schema), and then crawls the resolved value.
  */
 const inventory$Ref = <S extends object = JSONSchema>({
@@ -213,10 +213,10 @@ const inventory$Ref = <S extends object = JSONSchema>({
   }
 
   const newEntry: InventoryEntry = {
-    $ref, // The JSON Reference (e.g. {$ref: string})
-    circular: pointer.circular, // Is this $ref pointer DIRECTLY circular? (i.e. it references itself)
+    $ref, // The JSON Reference (e.g., {$ref: string})
+    circular: pointer.circular, // Is this $ref pointer DIRECTLY circular? (i.e., it references itself)
     depth, // How far from the JSON Schema root is this $ref pointer?
-    extended, // Does this $ref extend its resolved value? (i.e. it has extra properties, in addition to "$ref")
+    extended, // Does this $ref extend its resolved value? (i.e., it has extra properties, in addition to "$ref")
     external, // Does this $ref pointer point to a file other than the main JSON Schema file?
     file, // The file that the $ref pointer resolves to
     hash, // The hash within `file` that the $ref pointer resolves to
@@ -240,7 +240,7 @@ const inventory$Ref = <S extends object = JSONSchema>({
   // Recursively crawl the resolved value.
   // When the resolution followed a $ref chain to a different file,
   // use the resolved file as the base path so that local $ref values
-  // (e.g. #/components/schemas/SiblingSchema) inside the resolved
+  // (e.g., #/components/schemas/SiblingSchema) inside the resolved
   // value resolve against the correct file.
   if (!existingEntry || external) {
     let crawlPath = pointer.path;
@@ -445,8 +445,8 @@ function remap(parser: $RefParser, inventory: Array<InventoryEntry>) {
   const ensureContainer = (
     type: 'schemas' | 'parameters' | 'requestBodies' | 'responses' | 'headers',
   ) => {
-    const isOas3 = !!(root && typeof root === 'object' && typeof root.openapi === 'string');
-    const isOas2 = !!(root && typeof root === 'object' && typeof root.swagger === 'string');
+    const isOas3 = Boolean(root && typeof root === 'object' && typeof root.openapi === 'string');
+    const isOas2 = Boolean(root && typeof root === 'object' && typeof root.swagger === 'string');
 
     if (isOas3) {
       if (!root.components || typeof root.components !== 'object') {
@@ -570,11 +570,11 @@ function remap(parser: $RefParser, inventory: Array<InventoryEntry>) {
     }
 
     // Keep internal refs internal. However, if the $ref extends the resolved value
-    // (i.e. it has additional properties in addition to "$ref"), then we must
+    // (i.e., it has additional properties in addition to "$ref"), then we must
     // preserve the original $ref rather than rewriting it to the resolved hash.
     if (!entry.external) {
       if (!entry.extended && entry.$ref && typeof entry.$ref === 'object') {
-        entry.$ref.$ref = entry.hash;
+        entry.$ref.$ref = decodeURI(entry.hash);
       }
       continue;
     }
@@ -582,7 +582,7 @@ function remap(parser: $RefParser, inventory: Array<InventoryEntry>) {
     // Avoid changing direct self-references; keep them internal
     if (entry.circular) {
       if (entry.$ref && typeof entry.$ref === 'object') {
-        entry.$ref.$ref = entry.pathFromRoot;
+        entry.$ref.$ref = decodeURI(entry.pathFromRoot);
       }
       continue;
     }

package/src/dereference.ts

@@ -226,9 +226,9 @@ function dereference$Ref<S extends object = JSONSchema>(
   }
 
   if (directCircular) {
-    // The pointer is a DIRECT circular reference (i.e. it references itself).
+    // The pointer is a DIRECT circular reference (i.e., it references itself).
     // So replace the $ref path with the absolute path from the JSON Schema root
-    dereferencedValue.$ref = pathFromRoot;
+    dereferencedValue.$ref = decodeURI(pathFromRoot);
   }
 
   const dereferencedObject = {

package/src/index.ts

@@ -117,12 +117,12 @@ export class $RefParser {
 
     await resolveExternal(this, this.options);
     const errors = JSONParserErrorGroup.getParserErrors(this);
-    if (errors.length > 0) {
+    if (errors.length) {
       throw new JSONParserErrorGroup(this);
     }
     _bundle(this, this.options);
     const errors2 = JSONParserErrorGroup.getParserErrors(this);
-    if (errors2.length > 0) {
+    if (errors2.length) {
       throw new JSONParserErrorGroup(this);
     }
     return this.schema!;
@@ -148,14 +148,14 @@ export class $RefParser {
 
     await resolveExternal(this, this.options);
     const errors = JSONParserErrorGroup.getParserErrors(this);
-    if (errors.length > 0) {
+    if (errors.length) {
       throw new JSONParserErrorGroup(this);
     }
     _bundle(this, this.options);
     // Merged root is ready for bundling
 
     const errors2 = JSONParserErrorGroup.getParserErrors(this);
-    if (errors2.length > 0) {
+    if (errors2.length) {
       throw new JSONParserErrorGroup(this);
     }
     return this.schema!;
@@ -297,7 +297,7 @@ export class $RefParser {
 
   public mergeMany(): JSONSchema {
     const schemas = this.schemaMany || [];
-    if (schemas.length === 0) {
+    if (!schemas.length) {
       throw ono('mergeMany called with no schemas. Did you run parseMany?');
     }
 
@@ -335,7 +335,7 @@ export class $RefParser {
         }
       }
     }
-    if (Object.keys(infoAccumulator).length > 0) {
+    if (Object.keys(infoAccumulator).length) {
       merged.info = infoAccumulator;
     }
 
@@ -356,7 +356,7 @@ export class $RefParser {
         }
       }
     }
-    if (servers.length > 0) {
+    if (servers.length) {
       merged.servers = servers;
     }
 
@@ -568,7 +568,7 @@ export class $RefParser {
       }
     }
 
-    if (tags.length > 0) {
+    if (tags.length) {
       merged.tags = tags;
     }
 
@@ -585,3 +585,17 @@ export class $RefParser {
 
 export { sendRequest } from './resolvers/url';
 export type { JSONSchema } from './types';
+export type { JSONParserErrorType } from './util/errors';
+export {
+  InvalidPointerError,
+  isHandledError,
+  JSONParserError,
+  JSONParserErrorGroup,
+  MissingPointerError,
+  normalizeError,
+  ParserError,
+  ResolverError,
+  TimeoutError,
+  UnmatchedParserError,
+  UnmatchedResolverError,
+} from './util/errors';

package/src/parsers/yaml.ts

@@ -1,5 +1,4 @@
-import yaml from 'js-yaml';
-import { JSON_SCHEMA } from 'js-yaml';
+import { parse } from 'yaml';
 
 import type { FileInfo, JSONSchema, Plugin } from '../types';
 import { ParserError } from '../util/errors';
@@ -16,8 +15,7 @@ export const yamlParser: Plugin = {
     }
 
     try {
-      const yamlSchema = yaml.load(data, { schema: JSON_SCHEMA }) as JSONSchema;
-      return yamlSchema;
+      return parse(data) as JSONSchema;
     } catch (error: any) {
       throw new ParserError(error?.message || 'Parser Error', file.url);
     }

package/src/pointer.ts

@@ -140,7 +140,7 @@ class Pointer<S extends object = JSONSchema> {
       }
     }
 
-    if (errors.length > 0) {
+    if (errors.length) {
       throw errors.length === 1
         ? errors[0]
         : new AggregateError(errors, 'Multiple missing pointer errors');
@@ -171,7 +171,7 @@ class Pointer<S extends object = JSONSchema> {
     const tokens = Pointer.parse(this.path);
     let token;
 
-    if (tokens.length === 0) {
+    if (!tokens.length) {
       // There are no tokens, replace the entire object with the new value
       this.value = value;
       return value;
@@ -205,7 +205,7 @@ class Pointer<S extends object = JSONSchema> {
   /**
    * Parses a JSON pointer (or a path containing a JSON pointer in the hash)
    * and returns an array of the pointer's tokens.
-   * (e.g. "schema.json#/definitions/person/name" => ["definitions", "person", "name"])
+   * (e.g., "schema.json#/definitions/person/name" => ["definitions", "person", "name"])
    *
    * The pointer is parsed according to RFC 6901
    * {@link https://tools.ietf.org/html/rfc6901#section-3}
@@ -244,8 +244,8 @@ class Pointer<S extends object = JSONSchema> {
   /**
    * Creates a JSON pointer path, by joining one or more tokens to a base path.
    *
-   * @param base - The base path (e.g. "schema.json#/definitions/person")
-   * @param tokens - The token(s) to append (e.g. ["name", "first"])
+   * @param base - The base path (e.g., "schema.json#/definitions/person")
+   * @param tokens - The token(s) to append (e.g., ["name", "first"])
    * @returns
    */
   static join(base: string, tokens: string | string[]) {

package/src/ref.ts

@@ -46,7 +46,7 @@ class $Ref<S extends object = JSONSchema> {
   $refs: $Refs<S>;
 
   /**
-   * Indicates the type of {@link $Ref#path} (e.g. "file", "http", etc.)
+   * Indicates the type of {@link $Ref#path} (e.g., "file", "http", etc.)
    */
   pathType: string | unknown;
 
@@ -152,7 +152,7 @@ class $Ref<S extends object = JSONSchema> {
       value !== null &&
       '$ref' in value &&
       typeof value.$ref === 'string' &&
-      value.$ref.length > 0
+      Boolean(value.$ref.length)
     );
   }
 

package/src/refs.ts

@@ -224,7 +224,7 @@ function getPaths<S extends object = JSONSchema>($refs: $RefsMap<S>, types: stri
 
   // Filter the paths by type
   types = Array.isArray(types[0]) ? types[0] : Array.prototype.slice.call(types);
-  if (types.length > 0 && types[0]) {
+  if (types.length && types[0]) {
     paths = paths.filter((key) => types.includes($refs[key]!.pathType as string));
   }