feat: throw on error

.changeset/thick-pumpkins-battle.md

@@ -0,0 +1,5 @@
+---
+'@scalar/openapi-parser': patch
+---
+
+feat: validate and dereference, throwOnError option

README.md

@@ -128,6 +128,26 @@ const result = openapi()
   .get()
 ```
 
+### Then/Catch syntax
+
+If you’re more the then/catch type of guy, that’s fine:
+
+```ts
+import { validate } from '@scalar/openapi-parser'
+
+const specification = …
+
+validate(specification, {
+  throwOnError: true,
+})
+.then(result => {
+  // Success
+})
+.catch(error => {
+  // Failure
+})
+```
+
 ### Advanced: URL and file references
 
 You can reference other files, too. To do that, the parser needs to know what files are available.

packages/openapi-parser/src/configuration.ts

@@ -21,10 +21,10 @@ export const OpenApiVersions = Object.keys(
  * List of error messages used in the Validator
  */
 export const ERRORS = {
-  EMPTY_OR_INVALID: 'Cannot find JSON, YAML or filename in data',
+  EMPTY_OR_INVALID: 'Can’t find JSON, YAML or filename in data',
   // URI_MUST_BE_STRING: 'uri parameter or $id attribute must be a string',
   OPENAPI_VERSION_NOT_SUPPORTED:
-    'Cannot find supported Swagger/OpenAPI version in specification, version must be a string.',
+    'Can’t find supported Swagger/OpenAPI version in specification, version must be a string.',
   INVALID_REFERENCE: 'Can’t resolve reference: %s',
   EXTERNAL_REFERENCE_NOT_FOUND: 'Can’t resolve external reference: %s',
   FILE_DOES_NOT_EXIST: 'File does not exist: %s',

packages/openapi-parser/src/lib/Validator/Validator.ts

@@ -8,7 +8,12 @@ import {
   type OpenApiVersion,
   OpenApiVersions,
 } from '../../configuration'
-import type { AnyObject, Filesystem, ValidateResult } from '../../types'
+import type {
+  AnyObject,
+  Filesystem,
+  ThrowOnErrorOption,
+  ValidateResult,
+} from '../../types'
 import { details as getOpenApiVersion } from '../../utils/details'
 import { resolveReferences } from '../../utils/resolveReferences'
 import { transformErrors } from '../../utils/transformErrors'
@@ -45,7 +50,10 @@ export class Validator {
   /**
    * Checks whether a specification is valid and all references can be resolved.
    */
-  async validate(filesystem: Filesystem): Promise<ValidateResult> {
+  async validate(
+    filesystem: Filesystem,
+    options?: ThrowOnErrorOption,
+  ): Promise<ValidateResult> {
     const entrypoint = filesystem.find((file) => file.isEntrypoint)
     const specification = entrypoint?.specification
 
@@ -61,6 +69,10 @@ export class Validator {
     try {
       // AnyObject is empty or invalid
       if (specification === undefined || specification === null) {
+        if (options?.throwOnError) {
+          throw new Error(ERRORS.EMPTY_OR_INVALID)
+        }
+
         return {
           valid: false,
           errors: transformErrors(entrypoint, ERRORS.EMPTY_OR_INVALID),
@@ -101,7 +113,7 @@ export class Validator {
       }
 
       // Check if the references are valid
-      const resolvedReferences = resolveReferences(filesystem)
+      const resolvedReferences = resolveReferences(filesystem, options)
 
       return {
         valid: schemaResult && resolvedReferences.valid,
@@ -110,6 +122,10 @@ export class Validator {
       }
     } catch (error) {
       // Something went horribly wrong!
+      if (options?.throwOnError) {
+        throw error
+      }
+
       return {
         valid: false,
         errors: transformErrors(entrypoint, error.message ?? error),

packages/openapi-parser/src/pipeline.test.ts

@@ -257,4 +257,143 @@ describe('pipeline', () => {
     expect(result.errors).toStrictEqual([])
     expect(result.schema.info.title).toBe('Hello World')
   })
+
+  it('throws an error when dereference fails (global)', async () => {
+    expect(async () => {
+      await openapi({
+        throwOnError: true,
+      })
+        .load({
+          openapi: '3.1.0',
+          info: {},
+          paths: {
+            '/foobar': {
+              post: {
+                requestBody: {
+                  $ref: '#/components/requestBodies/DoesNotExist',
+                },
+              },
+            },
+          },
+        })
+        .dereference()
+        .get()
+    }).rejects.toThrowError(
+      'Can’t resolve reference: #/components/requestBodies/DoesNotExist',
+    )
+  })
+
+  it('throws an error when dereference fails (only dereference)', async () => {
+    expect(async () => {
+      await openapi()
+        .load({
+          openapi: '3.1.0',
+          info: {},
+          paths: {
+            '/foobar': {
+              post: {
+                requestBody: {
+                  $ref: '#/components/requestBodies/DoesNotExist',
+                },
+              },
+            },
+          },
+        })
+        .dereference({
+          throwOnError: true,
+        })
+        .get()
+    }).rejects.toThrowError(
+      'Can’t resolve reference: #/components/requestBodies/DoesNotExist',
+    )
+  })
+
+  it('throws an error when validate fails (global)', async () => {
+    expect(async () => {
+      await openapi({
+        throwOnError: true,
+      })
+        .load({
+          openapi: '3.1.0',
+          info: {
+            title: 'Hello World',
+          },
+          paths: {
+            '/foobar': {
+              post: {
+                requestBody: {
+                  $ref: '#/components/requestBodies/DoesNotExist',
+                },
+              },
+            },
+          },
+        })
+        .validate()
+        .get()
+    }).rejects.toThrowError(
+      'Can’t resolve reference: #/components/requestBodies/DoesNotExist',
+    )
+  })
+
+  it('throws an error when validate fails (only validate)', async () => {
+    expect(async () => {
+      await openapi()
+        .load({
+          openapi: '3.1.0',
+          info: {
+            title: 'Hello World',
+          },
+          paths: {
+            '/foobar': {
+              post: {
+                requestBody: {
+                  $ref: '#/components/requestBodies/DoesNotExist',
+                },
+              },
+            },
+          },
+        })
+        .validate({
+          throwOnError: true,
+        })
+        .get()
+    }).rejects.toThrowError(
+      'Can’t resolve reference: #/components/requestBodies/DoesNotExist',
+    )
+  })
+
+  it('works with then & catch', async () => {
+    return new Promise((resolve, reject) => {
+      openapi()
+        .load({
+          openapi: '3.1.0',
+          info: {
+            title: 'Hello World',
+          },
+          paths: {
+            '/foobar': {
+              post: {
+                requestBody: {
+                  $ref: '#/components/requestBodies/DoesNotExist',
+                },
+              },
+            },
+          },
+        })
+        .validate({
+          throwOnError: true,
+        })
+        .get()
+        .then(() => {
+          reject()
+        })
+        .catch((error) => {
+          expect(error.message).toBe(
+            'Can’t resolve reference: #/components/requestBodies/DoesNotExist',
+          )
+
+          resolve(null)
+        })
+    })
+  })
 })