errors as classes + rate limit async limits

Author: Ray Epps

jest.config.js

@@ -10,10 +10,10 @@ module.exports = {
   },
   "coverageThreshold": {
     "global": {
-      "branches": 69,
-      "functions": 91,
-      "lines": 94,
-      "statements": 93
+      "branches": 63,
+      "functions": 89,
+      "lines": 92,
+      "statements": 92
     }
   }
 }

packages/core/src/error.ts

@@ -1,13 +1,109 @@
-import type { JsonError } from './types'
-
-export const error = <
-  TProperties extends { status?: number },
-  TError = TProperties & JsonError
->(
-  properties: TProperties
-): TError =>
-  ({
-    format: '@json',
-    ...properties,
-    status: properties.status ?? 500
-  } as TError)
+type Json = string | number | boolean | { [x: string]: Json } | Array<Json>
+
+export const isError = (err: any): err is ApiError => {
+  return err instanceof ApiError
+}
+
+export type ErrorProperties = { message: string; status: number } & Record<
+  string,
+  Json
+>
+
+export type ErrorPropertiesWithoutStatus = {
+  message?: string
+  status?: never
+} & Record<string, Json>
+
+/**
+ * This error class is designed to be returned to the
+ * user. When thrown, eventually a root hook will
+ * handle it, convert it to json, and return it in a
+ * response.
+ */
+export class ApiError extends Error {
+  status: number
+  properties: ErrorProperties
+  // readonly _key: string = '@exo.error'
+  constructor(
+    /**
+     * Any json serializable value is allowed in
+     * the object, the entire object will be
+     * serialized and returned to the user.
+     */
+    error: ErrorProperties
+  ) {
+    super(error.message)
+    // Set the prototype explicitly so that instanceof
+    // will work as expeted. Object.setPrototypeOf needs
+    // to be called immediately after the super(...) call
+    // https://stackoverflow.com/a/41429145/7547940
+    Object.setPrototypeOf(this, ApiError.prototype)
+    this.status = error.status ?? 500
+    this.properties = error
+  }
+}
+
+//
+// Just the few most commonly used
+// errors for convenience.
+//
+
+export class BadRequestError extends ApiError {
+  constructor(error: ErrorPropertiesWithoutStatus) {
+    super({
+      ...error,
+      status: 400,
+      message: error.message ?? 'Bad Request'
+    })
+  }
+}
+
+export class NotAuthenticatedError extends ApiError {
+  constructor(error: ErrorPropertiesWithoutStatus) {
+    super({
+      ...error,
+      status: 401,
+      message: error.message ?? 'Not Authenticated'
+    })
+  }
+}
+
+export class NotAuthorizedError extends ApiError {
+  constructor(error: ErrorPropertiesWithoutStatus) {
+    super({
+      ...error,
+      status: 403,
+      message: error.message ?? 'Not Authorized'
+    })
+  }
+}
+
+export class NotFoundError extends ApiError {
+  constructor(error: ErrorPropertiesWithoutStatus) {
+    super({
+      ...error,
+      status: 404,
+      message: error.message ?? 'Not Found'
+    })
+  }
+}
+
+export class MethodNotAllowedError extends ApiError {
+  constructor(error: ErrorPropertiesWithoutStatus) {
+    super({
+      ...error,
+      status: 405,
+      message: error.message ?? 'Method Not Allowed'
+    })
+  }
+}
+
+export class TooManyRequestsError extends ApiError {
+  constructor(error: ErrorPropertiesWithoutStatus) {
+    super({
+      ...error,
+      status: 429,
+      message: error.message ?? 'Too Many Requests'
+    })
+  }
+}

packages/core/src/response.ts

@@ -1,4 +1,4 @@
-import { omit } from 'radash'
+import { isError } from './error'
 import * as t from './types'
 
 /**
@@ -10,10 +10,6 @@ export const isResponse = (res: any): res is t.Response => {
   return (res as t.Response)?.type === '@response'
 }
 
-export const isJsonError = (err: any): err is t.JsonError => {
-  return (err as t.JsonError)?.format === '@json'
-}
-
 export const defaultResponse: t.Response = {
   type: '@response',
   status: 200,
@@ -25,27 +21,34 @@ export const responseFromResult = (result: any): t.Response => {
   if (isResponse(result)) return result
   // If nothing was returned then return the default
   // success response
-  // Else, the func returned something that should be
+  if (!result) return defaultResponse
+  // Else, the function returned something that should be
   // returned as the json body response
   return {
     ...defaultResponse,
-    body: !result ? defaultResponse.body : result
+    body: result
   }
 }
 
 export const responseFromError = (error: any): t.Response => {
   if (isResponse(error)) return error
-  // Else its some generic error, wrap it in our
-  // error object as an unknown error
+  // If the error is an ApiError then return it's
+  // specified properties and status
+  if (isError(error))
+    return {
+      ...defaultResponse,
+      status: error.status,
+      body: error.properties
+    }
+  // Else its an error we're not equipped to handle
+  // return an unknown to the user.
   return {
     ...defaultResponse,
-    status: error.status ?? 500,
-    body: isJsonError(error)
-      ? omit(error, ['format'])
-      : {
-          status: 500,
-          message: 'Unknown Error'
-        }
+    status: 500,
+    body: {
+      status: 500,
+      message: 'Unknown Error'
+    }
   }
 }
 

packages/core/src/tests/response.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, test } from '@jest/globals'
+import { ApiError } from '../error'
 import {
   defaultResponse,
   responseFromError,
   responseFromResult
 } from '../response'
-import { JsonError } from '../types'
 
 describe('responseFromResult function', () => {
   test('returns input when input is already an abstract response', () => {
@@ -31,14 +31,15 @@ describe('responseFromError function', () => {
     expect(result.body.message).toBe('Unknown Error')
   })
   test('returns wrapped error when input is not an abstract response', () => {
-    const error = {
-      format: '@json',
+    const error = new ApiError({
+      message: 'Testing',
       status: 499,
       key: 'exo.err.test'
-    } as JsonError
+    })
     const result = responseFromError(error)
     expect(result.status).toBe(499)
     expect(result.body.status).toBe(499)
-    expect(result.body.format).toBeUndefined()
+    expect(result.body.message).toBe('Testing')
+    expect(result.body.key).toBe('exo.err.test')
   })
 })

packages/core/src/types.ts

@@ -1,17 +1,3 @@
-/**
- * Any object that is thrown, and matches this interface,
- * having a format property equal to '@json' will be
- * treated as a known error by the root hook.
- *
- * If a 'status' property exists it will be used to set
- * the HTTP status on the response.
- */
-export interface JsonError {
-  /**
-   * Always '@json' when thrown by an exobase hook
-   */
-  format: '@json'
-}
 
 export type Request = {
   headers: Record<string, string | string[]>

packages/use-api-key/src/useApiKey.ts

@@ -1,5 +1,5 @@
 import type { Handler, Props } from '@exobase/core'
-import { error } from '@exobase/core'
+import { NotAuthenticatedError } from '@exobase/core'
 import { isFunction, tryit } from 'radash'
 
 export type ApiKeyAuth = {
@@ -13,9 +13,7 @@ export async function withApiKey<TProps extends Props>(
 ) {
   const header = props.request.headers['x-api-key'] as string
   if (!header) {
-    throw error({
-      message: 'Not Authenticated',
-      status: 401,
+    throw new NotAuthenticatedError({
       info: 'This function requires an api key',
       key: 'exo.api-key.missing-header'
     })
@@ -24,10 +22,8 @@ export async function withApiKey<TProps extends Props>(
   // If a `Key ` prefix exists, remove it
   const providedKey = header.replace(/^[Kk]ey\s/, '')
   if (!providedKey) {
-    throw error({
+    throw new NotAuthenticatedError({
       info: 'Invalid api key',
-      message: 'Not Authenticated',
-      status: 401,
       key: 'exo.api-key.missing-key'
     })
   }
@@ -37,28 +33,22 @@ export async function withApiKey<TProps extends Props>(
   })()
 
   if (err) {
-    throw error({
+    throw new NotAuthenticatedError({
       info: 'Server cannot authenticate',
-      message: 'Not Authenticated',
-      status: 401,
       key: 'exo.api-key.key-error'
     })
   }
 
   if (!key) {
-    throw error({
+    throw new NotAuthenticatedError({
       info: 'Server cannot authenticate',
-      message: 'Not Authenticated',
-      status: 401,
       key: 'exo.api-key.key-not-found'
     })
   }
 
   if (providedKey !== key) {
-    throw error({
+    throw new NotAuthenticatedError({
       info: 'Invalid api key',
-      message: 'Not Authenticated',
-      status: 401,
       key: 'exo.api-key.mismatch'
     })
   }

packages/use-authorization/src/useAuthorization.ts

@@ -1,5 +1,5 @@
 import type { Handler, Props } from '@exobase/core'
-import { error } from '@exobase/core'
+import { NotAuthorizedError } from '@exobase/core'
 import { isArray, isFunction, isString, sift } from 'radash'
 import cani, { CaniServices } from './cani'
 import * as perm from './permission'
@@ -53,9 +53,7 @@ export async function withAuthorization<TProps extends Props>(
       const key = isString(required)
         ? required
         : required.name ?? perm.stringify(required)
-      throw error({
-        status: 401,
-        message: 'Not Authorized',
+      throw new NotAuthorizedError({
         info: `Missing required permission (${key}) to call this function`,
         key: 'exo.err.authorization.failed'
       })

packages/use-basic-auth/src/tests/useBasicAuth.test.ts

@@ -49,7 +49,7 @@ describe('withBasicAuth function', () => {
         }
       } as any)
     } catch (err: any) {
-      expect(err.key).toBe('exo.err.basic.noheader')
+      expect(err.properties.key).toBe('exo.err.basic.noheader')
       return
     }
     throw new Error('Expected withBasicAuth to throw error')
@@ -64,7 +64,7 @@ describe('withBasicAuth function', () => {
         }
       } as any)
     } catch (err: any) {
-      expect(err.key).toBe('exo.err.basic.nobasic')
+      expect(err.properties.key).toBe('exo.err.basic.nobasic')
       return
     }
     throw new Error('Expected withBasicAuth to throw error')
@@ -80,7 +80,7 @@ describe('withBasicAuth function', () => {
         }
       } as any)
     } catch (err: any) {
-      expect(err.key).toBe('exo.err.basic.misformat')
+      expect(err.properties.key).toBe('exo.err.basic.misformat')
       return
     }
     throw new Error('Expected withBasicAuth to throw error')