@scalar/openapi-parser 0.8.10 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @scalar/openapi-parser
 
+## 0.10.0
+
+### Minor Changes
+
+- fbef0c3: fix(openapi-parser): improve performance
+
+### Patch Changes
+
+- fbef0c3: fix: doesn’t validate files with external references
+
+## 0.9.0
+
+### Minor Changes
+
+- 6fef2f3: feat(openapi-parser): support `onDereference` option on `dereference`
+
 ## 0.8.10
 
 ### Patch Changes

package/README.md

@@ -63,6 +63,20 @@ const specification = `{
 const { schema, errors } = await dereference(specification)
 ```
 
+### Track references
+
+The `dereference` function accepts an `onDereference` callback option that gets called whenever a reference is resolved. This can be useful for tracking which schemas are being dereferenced:
+
+```ts
+import { dereference } from '@scalar/openapi-parser'
+
+const { schema, errors } = await dereference(specification, {
+  onDereference: ({ schema, ref }) => {
+    //
+  },
+})
+```
+
 ### Modify an OpenAPI document
 
 ```ts

package/dist/utils/dereference.d.ts

@@ -1,5 +1,6 @@
-import type { AnyApiDefinitionFormat, DereferenceResult, Filesystem, ThrowOnErrorOption } from '../types';
-export type DereferenceOptions = ThrowOnErrorOption;
+import type { AnyApiDefinitionFormat, DereferenceResult, Filesystem } from '../types';
+import { type ResolveReferencesOptions } from './resolveReferences.js';
+export type DereferenceOptions = ResolveReferencesOptions;
 /**
  * Resolves all references in an OpenAPI document
  */

package/dist/utils/dereference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dereference.d.ts","sourceRoot":"","sources":["../../src/utils/dereference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EACnB,MAAM,UAAU,CAAA;AAMjB,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,CAAA;AAEnD;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,sBAAsB,GAAG,UAAU,EAC1C,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAY5B"}
+{"version":3,"file":"dereference.d.ts","sourceRoot":"","sources":["../../src/utils/dereference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,iBAAiB,EACjB,UAAU,EACX,MAAM,UAAU,CAAA;AAIjB,OAAO,EACL,KAAK,wBAAwB,EAE9B,MAAM,qBAAqB,CAAA;AAE5B,MAAM,MAAM,kBAAkB,GAAG,wBAAwB,CAAA;AAEzD;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,sBAAsB,GAAG,UAAU,EAC1C,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAY5B"}

package/dist/utils/resolveReferences.d.ts

@@ -5,8 +5,14 @@ export type ResolveReferencesResult = {
     errors: ErrorObject[];
     schema: OpenAPI.Document;
 };
+export type ResolveReferencesOptions = ThrowOnErrorOption & {
+    onDereference?: (data: {
+        schema: AnyObject;
+        ref: string;
+    }) => void;
+};
 /**
  * Takes a specification and resolves all references.
  */
-export declare function resolveReferences(input: AnyObject | Filesystem, options?: ThrowOnErrorOption, file?: FilesystemEntry, errors?: ErrorObject[]): ResolveReferencesResult;
+export declare function resolveReferences(input: AnyObject | Filesystem, options?: ResolveReferencesOptions, file?: FilesystemEntry, errors?: ErrorObject[]): ResolveReferencesResult;
 //# sourceMappingURL=resolveReferences.d.ts.map

package/dist/utils/resolveReferences.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveReferences.d.ts","sourceRoot":"","sources":["../../src/utils/resolveReferences.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAGpD,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,eAAe,EACf,kBAAkB,EACnB,MAAM,UAAU,CAAA;AAejB,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAA;CACzB,CAAA;AAOD;;GAEG;AACH,wBAAgB,iBAAiB,CAE/B,KAAK,EAAE,SAAS,GAAG,UAAU,EAE7B,OAAO,CAAC,EAAE,kBAAkB,EAE5B,IAAI,CAAC,EAAE,eAAe,EAEtB,MAAM,CAAC,EAAE,WAAW,EAAE,GACrB,uBAAuB,CA+FzB"}
+{"version":3,"file":"resolveReferences.d.ts","sourceRoot":"","sources":["../../src/utils/resolveReferences.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAGpD,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,eAAe,EACf,kBAAkB,EACnB,MAAM,UAAU,CAAA;AAejB,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,GAAG;IAC1D,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACnE,CAAA;AAOD;;GAEG;AACH,wBAAgB,iBAAiB,CAE/B,KAAK,EAAE,SAAS,GAAG,UAAU,EAE7B,OAAO,CAAC,EAAE,wBAAwB,EAElC,IAAI,CAAC,EAAE,eAAe,EAEtB,MAAM,CAAC,EAAE,WAAW,EAAE,GACrB,uBAAuB,CAqGzB"}

package/dist/utils/resolveReferences.js

@@ -27,9 +27,6 @@ errors) {
     const entrypoint = getEntrypoint(filesystem);
     // Recursively resolve all references
     resolve(file?.specification ?? entrypoint.specification, filesystem, file ?? entrypoint);
-    // If we replace references with content, that includes a reference, we can’t deal with that right-away.
-    // That’s why we need a second run.
-    resolve(file?.specification ?? entrypoint.specification, filesystem, file ?? entrypoint);
     // Remove duplicats (according to message) from errors
     errors = errors.filter((error, index, self) => index ===
         self.findIndex((t) => t.message === error.message && t.code === error.code));
@@ -43,48 +40,46 @@ errors) {
     /**
      * Resolves the circular reference to an object and deletes the $ref properties.
      */
-    function resolve(schema, resolveFilesystem, resolveFile) {
-        let result;
-        // Iterate over the whole objecct
-        Object.entries(schema ?? {}).forEach(([_, value]) => {
-            // Ignore parts without a reference
-            if (schema.$ref !== undefined) {
-                // Find the referenced content
-                const target = resolveUri(schema.$ref, options, resolveFile, resolveFilesystem, errors);
-                if (target === undefined) {
-                    return undefined;
-                }
-                // Get rid of the reference
-                delete schema.$ref;
-                if (typeof target === 'object') {
-                    Object.keys(target).forEach((key) => {
-                        if (schema[key] === undefined) {
-                            schema[key] = target[key];
-                        }
-                    });
+    function resolve(schema, resolveFilesystem, resolveFile, 
+    // references to resolved object
+    resolved = new WeakSet()) {
+        let result = { errors: [] };
+        if (schema === null || resolved.has(schema))
+            return result;
+        resolved.add(schema);
+        function resolveExternal(externalFile) {
+            resolve(externalFile.specification, resolveFilesystem, externalFile, resolved);
+            return externalFile;
+        }
+        // Ignore parts without a reference
+        while (schema.$ref !== undefined) {
+            // Find the referenced content
+            const target = resolveUri(schema.$ref, options, resolveFile, resolveFilesystem, resolveExternal, errors);
+            // invalid
+            if (typeof target !== 'object' || target === null)
+                break;
+            options?.onDereference?.({ schema, ref: schema.$ref });
+            // Get rid of the reference
+            delete schema.$ref;
+            for (const key of Object.keys(target)) {
+                if (schema[key] === undefined) {
+                    schema[key] = target[key];
                 }
             }
-            if (typeof value === 'object' && !isCircular(value)) {
-                result = resolve(value, resolveFilesystem, resolveFile);
+        }
+        // Iterate over the whole object
+        for (const value of Object.values(schema)) {
+            if (typeof value === 'object' && value !== null) {
+                result = resolve(value, resolveFilesystem, resolveFile, resolved);
             }
-        });
-        return {
-            errors: result?.errors ?? [],
-        };
-    }
-}
-// TODO: Is there a better way? :D
-function isCircular(schema) {
-    try {
-        JSON.stringify(schema);
-        return false;
-    }
-    catch (error) {
-        return true;
+        }
+        return result;
     }
 }
 /**
  * Resolves a URI to a part of the specification
+ *
+ * The output is not necessarily dereferenced
  */
 function resolveUri(
 // 'foobar.json#/foo/bar'
@@ -92,7 +87,9 @@ uri, options,
 // { filename: './foobar.json '}
 file, 
 // [ { filename: './foobar.json '} ]
-filesystem, errors) {
+filesystem, 
+// a function to resolve references in external file
+resolve, errors) {
     // Ignore invalid URIs
     if (typeof uri !== 'string') {
         if (options?.throwOnError) {
@@ -123,13 +120,13 @@ filesystem, errors) {
             });
             return;
         }
-        const result = resolveReferences(filesystem, options, externalReference, errors);
         // $ref: 'other-file.yaml'
         if (path === undefined) {
-            return result.schema;
+            return externalReference.specification;
         }
         // $ref: 'other-file.yaml#/foo/bar'
-        return resolveUri(`#${path}`, options, externalReference, filesystem, errors);
+        // resolve refs first before accessing properties directly
+        return resolveUri(`#${path}`, options, resolve(externalReference), filesystem, resolve, errors);
     }
     // Pointers
     const segments = getSegmentsFromPath(path);

package/package.json

@@ -17,7 +17,7 @@
     "parser",
     "typescript"
   ],
-  "version": "0.8.10",
+  "version": "0.10.0",
   "engines": {
     "node": ">=18"
   },