@scalar/openapi-parser 0.8.10 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalar/openapi-parser
 
+## 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,CAoGzB"}

package/dist/utils/resolveReferences.js

@@ -26,10 +26,10 @@ errors) {
     // Get the main file
     const entrypoint = getEntrypoint(filesystem);
     // Recursively resolve all references
-    resolve(file?.specification ?? entrypoint.specification, filesystem, file ?? entrypoint);
+    resolve(file?.specification ?? entrypoint.specification, filesystem, file ?? entrypoint, options?.onDereference);
     // 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);
+    resolve(file?.specification ?? entrypoint.specification, filesystem, file ?? entrypoint, options?.onDereference);
     // 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,7 +43,7 @@ errors) {
     /**
      * Resolves the circular reference to an object and deletes the $ref properties.
      */
-    function resolve(schema, resolveFilesystem, resolveFile) {
+    function resolve(schema, resolveFilesystem, resolveFile, onResolve) {
         let result;
         // Iterate over the whole objecct
         Object.entries(schema ?? {}).forEach(([_, value]) => {
@@ -54,6 +54,7 @@ errors) {
                 if (target === undefined) {
                     return undefined;
                 }
+                onResolve?.({ schema, ref: schema.$ref });
                 // Get rid of the reference
                 delete schema.$ref;
                 if (typeof target === 'object') {
@@ -65,7 +66,7 @@ errors) {
                 }
             }
             if (typeof value === 'object' && !isCircular(value)) {
-                result = resolve(value, resolveFilesystem, resolveFile);
+                result = resolve(value, resolveFilesystem, resolveFile, onResolve);
             }
         });
         return {

package/package.json

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