@api-client/core 0.19.16 → 0.19.17

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.19.16",
+  "version": "0.19.17",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {

package/src/exceptions/exception.ts

@@ -1,3 +1,8 @@
+/**
+ * A serialized representation of an Exception.
+ * Provides a standardized structure for pure data objects,
+ * typically used when converting errors for JSON responses.
+ */
 export interface ExceptionSchema {
   name: string
   message: string
@@ -75,39 +80,49 @@ export class Exception extends Error {
    */
   static fromRawException(init: object, defaultMessage: string): Exception {
     const typed = init as Record<string, string | number>
-    const options: ErrorOptions & { code?: string; status?: number } = {}
-    if (typed.code) {
-      options.code = typed.code as string
+    const options: ErrorOptions & { code?: string; status?: number; help?: string } = {}
+    if (typed.code !== undefined) {
+      options.code = String(typed.code)
     }
-    if (typed.status) {
-      options.status = Number(typed.status)
+    if (typed.status !== undefined) {
+      const parsedStatus = Number(typed.status)
+      if (!isNaN(parsedStatus)) {
+        options.status = parsedStatus
+      }
     }
-    const message = typed.message ?? defaultMessage
-    const result = new this(message as string, options)
-    if (typed.help) {
-      result.setHelp(typed.help as string)
+    if (typed.help !== undefined) {
+      options.help = String(typed.help)
     }
-    if (typed.name) {
-      result.name = typed.name as string
+    const message = typed.message !== undefined ? String(typed.message) : defaultMessage
+    const result = new this(message, options)
+    if (typed.name !== undefined) {
+      result.name = String(typed.name)
     }
     return result
   }
 
+  /**
+   * Initializes a new Exception instance.
+   *
+   * @param message - The primary human-readable error message.
+   * @param options - Additional properties configuration. Accepts standard `ErrorOptions`
+   * (like `cause`), plus custom `code`, `status`, and `help`.
+   */
   constructor(message?: string, options?: ErrorOptions & { code?: string; status?: number; help?: string }) {
     super(message, options)
 
     const ErrorConstructor = this.constructor as typeof Exception
 
     this.name = ErrorConstructor.name
-    this.message = message || ErrorConstructor.message || ''
-    this.status = options?.status || ErrorConstructor.status || 500
+    this.message = message ?? ErrorConstructor.message ?? ''
+    this.status = options?.status ?? ErrorConstructor.status ?? 500
 
-    const code = options?.code || ErrorConstructor.code
+    const code = options?.code ?? ErrorConstructor.code
     if (code !== undefined) {
       this.code = code
     }
 
-    const help = options?.help || ErrorConstructor.help
+    const help = options?.help ?? ErrorConstructor.help
     if (help !== undefined) {
       this.help = help
     }
@@ -115,25 +130,53 @@ export class Exception extends Error {
     Error.captureStackTrace(this, ErrorConstructor)
   }
 
+  /**
+   * Assigns a human-readable help description for troubleshooting and returns
+   * the exception instance to allow for method chaining.
+   *
+   * @param help - The detailed help informational text.
+   * @returns The current exception instance.
+   */
   setHelp(help: string): this {
     this.help = help
     return this
   }
 
+  /**
+   * Assigns a programmatic error code and returns the exception instance
+   * to allow for method chaining.
+   *
+   * @param code - The string error code (e.g., 'E_FILE_NOT_FOUND').
+   * @returns The current exception instance.
+   */
   setCode(code: string): this {
     this.code = code
     return this
   }
 
+  /**
+   * Assigns an HTTP-style status code and returns the exception instance
+   * to allow for method chaining.
+   *
+   * @param status - The numeric status code (e.g., 404, 500).
+   * @returns The current exception instance.
+   */
   setStatus(status: number): this {
     this.status = status
     return this
   }
 
+  /**
+   * Provides the string tag used by `Object.prototype.toString`.
+   */
   get [Symbol.toStringTag]() {
     return this.constructor.name
   }
 
+  /**
+   * Computes a string representation of the exception, including the
+   * programmatic code if one is defined.
+   */
   override toString(): string {
     if (this.code) {
       return `${this.name} [${this.code}]: ${this.message}`
@@ -141,6 +184,12 @@ export class Exception extends Error {
     return `${this.name}: ${this.message}`
   }
 
+  /**
+   * Serializes the exception into a plain JavaScript object.
+   * This ensures safe passing across boundaries and correct format in JSON responses.
+   *
+   * @returns The serialized exception object matching `ExceptionSchema`.
+   */
   toJSON(): ExceptionSchema {
     const result: ExceptionSchema = {
       name: this.name,
@@ -158,3 +207,58 @@ export class Exception extends Error {
     return result
   }
 }
+
+/**
+ * Converts a standard Error object (or thrown primitive) into an Exception instance.
+ * This function extracts relevant properties from the raw error
+ * and sets them on the Exception instance, allowing for a more
+ * consistent error handling experience across the application.
+ * @param error The unknown error value to convert.
+ * @param defaults Optional default properties to apply if they are missing on the Error object.
+ * @returns An Exception instance with properties set from the Error object.
+ */
+export function fromError(error: unknown, defaults: Partial<ExceptionSchema> = {}): Exception {
+  let message: string | undefined
+  let typed: Record<string, string | number> = {}
+
+  if (error instanceof Error) {
+    message = error.message
+    typed = error as unknown as Record<string, string | number>
+  } else if (typeof error === 'string') {
+    message = error
+  } else if (error !== null && typeof error === 'object') {
+    typed = error as Record<string, string | number>
+    if (typeof typed.message === 'string') {
+      message = typed.message
+    }
+  }
+
+  const e = new Exception(message || defaults.message || 'An error occurred')
+
+  if (typed.code !== undefined) {
+    e.code = String(typed.code)
+  } else if (defaults.code !== undefined) {
+    e.code = defaults.code
+  }
+
+  if (typed.status !== undefined) {
+    const status = Number(typed.status)
+    e.status = isNaN(status) ? (defaults.status ?? 500) : status
+  } else if (defaults.status !== undefined) {
+    e.status = defaults.status
+  }
+
+  if (typed.help !== undefined) {
+    e.setHelp(String(typed.help))
+  } else if (defaults.help !== undefined) {
+    e.setHelp(defaults.help)
+  }
+
+  if (typed.name !== undefined) {
+    e.name = String(typed.name)
+  } else if (defaults.name !== undefined) {
+    e.name = defaults.name
+  }
+
+  return e
+}

package/tests/unit/exceptions/exception.spec.ts

@@ -0,0 +1,261 @@
+import { test } from '@japa/runner'
+import { Exception, fromError } from '../../../src/exceptions/exception.js'
+
+test.group('Exceptions > Exception', () => {
+  test('constructor sets basic properties', ({ assert }) => {
+    const ex = new Exception('Test message', { code: 'E_TEST', status: 400, help: 'Help me' })
+    assert.equal(ex.message, 'Test message')
+    assert.equal(ex.code, 'E_TEST')
+    assert.equal(ex.status, 400)
+    assert.equal(ex.help, 'Help me')
+    assert.equal(ex.name, 'Exception')
+  })
+
+  test('constructor uses static defaults', ({ assert }) => {
+    class CustomException extends Exception {
+      static override message = 'Static message'
+      static override code = 'E_STATIC'
+      static override status = 404
+      static override help = 'Static help'
+    }
+    const ex = new CustomException()
+    assert.equal(ex.message, 'Static message')
+    assert.equal(ex.code, 'E_STATIC')
+    assert.equal(ex.status, 404)
+    assert.equal(ex.help, 'Static help')
+    assert.equal(ex.name, 'CustomException')
+  })
+
+  test('constructor defaults status to 500', ({ assert }) => {
+    const ex = new Exception('Test')
+    assert.equal(ex.status, 500)
+  })
+
+  test('constructor accepts status 0', ({ assert }) => {
+    const ex = new Exception('Test', { status: 0 })
+    assert.equal(ex.status, 0)
+  })
+
+  test('setters allow chaining and update properties', ({ assert }) => {
+    const ex = new Exception('Test')
+    const result = ex.setCode('E_CHAIN').setStatus(401).setHelp('Chained')
+
+    assert.strictEqual(result, ex)
+    assert.equal(ex.code, 'E_CHAIN')
+    assert.equal(ex.status, 401)
+    assert.equal(ex.help, 'Chained')
+  })
+
+  test('toString returns properly formatted string', ({ assert }) => {
+    const ex1 = new Exception('Error without code')
+    assert.equal(ex1.toString(), 'Exception: Error without code')
+
+    const ex2 = new Exception('Error with code', { code: 'E_CODE' })
+    assert.equal(ex2.toString(), 'Exception [E_CODE]: Error with code')
+  })
+
+  test('toStringTag returns class name', ({ assert }) => {
+    const ex = new Exception('Test')
+    assert.equal(Object.prototype.toString.call(ex), '[object Exception]')
+
+    class CustomTagError extends Exception {}
+    const ex2 = new CustomTagError('Test')
+    assert.equal(Object.prototype.toString.call(ex2), '[object CustomTagError]')
+  })
+
+  test('toJSON serializes properties', ({ assert }) => {
+    const ex = new Exception('Test message', { code: 'E_TEST', status: 400, help: 'Help me' })
+    const json = ex.toJSON()
+
+    assert.deepEqual(json, {
+      name: 'Exception',
+      message: 'Test message',
+      code: 'E_TEST',
+      status: 400,
+      help: 'Help me',
+    })
+  })
+
+  test('toJSON does not output unset optional properties', ({ assert }) => {
+    const ex = new Exception('Basic')
+    const json = ex.toJSON()
+
+    assert.deepEqual(json, {
+      name: 'Exception',
+      message: 'Basic',
+      status: 500,
+    })
+  })
+
+  test('fromRawException reconstructs exception', ({ assert }) => {
+    const raw = {
+      message: 'Raw message',
+      code: 'E_RAW',
+      status: '403',
+      help: 'Raw help',
+      name: 'RawName',
+    }
+    const ex = Exception.fromRawException(raw, 'Default')
+
+    assert.instanceOf(ex, Exception)
+    assert.equal(ex.message, 'Raw message')
+    assert.equal(ex.code, 'E_RAW')
+    assert.equal(ex.status, 403)
+    assert.equal(ex.help, 'Raw help')
+    assert.equal(ex.name, 'RawName')
+  })
+
+  test('fromRawException uses default message if missing', ({ assert }) => {
+    const ex = Exception.fromRawException({}, 'Fallback message')
+    assert.equal(ex.message, 'Fallback message')
+  })
+})
+
+test.group('Exceptions > Exception > fromError()', () => {
+  test('creates Exception from standard Error', ({ assert }) => {
+    const err = new Error('standard error message')
+    const ex = fromError(err)
+
+    assert.instanceOf(ex, Exception)
+    assert.equal(ex.message, 'standard error message')
+  })
+
+  test('creates Exception from Error with no message', ({ assert }) => {
+    const err = new Error()
+    const ex = fromError(err)
+
+    assert.instanceOf(ex, Exception)
+    assert.equal(ex.message, 'An error occurred')
+  })
+
+  test('copies code property', ({ assert }) => {
+    const err = new Error('test') as unknown as Exception
+    err.code = 'TEST_CODE'
+    const ex = fromError(err)
+
+    assert.equal(ex.code, 'TEST_CODE')
+  })
+
+  test('copies status property', ({ assert }) => {
+    const err = new Error('test') as unknown as Exception
+    err.status = 404
+    const ex = fromError(err)
+
+    assert.equal(ex.status, 404)
+  })
+
+  test('copies help property', ({ assert }) => {
+    const err = new Error('test') as unknown as Exception
+    err.help = 'Help text'
+    const ex = fromError(err)
+
+    assert.equal(ex.help, 'Help text')
+  })
+
+  test('copies name property', ({ assert }) => {
+    const err = new Error('test')
+    err.name = 'CustomErrorName'
+    const ex = fromError(err)
+
+    assert.equal(ex.name, 'CustomErrorName')
+  })
+
+  test('handles when object is already an Exception instance', ({ assert }) => {
+    const originalEx = new Exception('Original exception')
+    originalEx.code = 'ORIGINAL_CODE'
+    originalEx.status = 400
+    originalEx.setHelp('Original help')
+
+    const newEx = fromError(originalEx)
+
+    assert.instanceOf(newEx, Exception)
+    assert.equal(newEx.message, 'Original exception')
+    assert.equal(newEx.code, 'ORIGINAL_CODE')
+    assert.equal(newEx.status, 400)
+    assert.equal(newEx.help, 'Original help')
+    assert.equal(newEx.name, 'Exception')
+  })
+
+  test('uses default message when error has no message', ({ assert }) => {
+    const err = new Error()
+    err.message = ''
+    const ex = fromError(err, { message: 'Default message' })
+
+    assert.equal(ex.message, 'Default message')
+  })
+
+  test('error message takes precedence over default message', ({ assert }) => {
+    const err = new Error('Original message')
+    const ex = fromError(err, { message: 'Default message' })
+
+    assert.equal(ex.message, 'Original message')
+  })
+
+  test('uses default code when error has no code', ({ assert }) => {
+    const err = new Error('test')
+    const ex = fromError(err, { code: 'DEFAULT_CODE' })
+
+    assert.equal(ex.code, 'DEFAULT_CODE')
+  })
+
+  test('error code takes precedence over default code', ({ assert }) => {
+    const err = new Error('test') as unknown as Exception
+    err.code = 'ORIGINAL_CODE'
+    const ex = fromError(err, { code: 'DEFAULT_CODE' })
+
+    assert.equal(ex.code, 'ORIGINAL_CODE')
+  })
+
+  test('uses default status when error has no status', ({ assert }) => {
+    const err = new Error('test')
+    const ex = fromError(err, { status: 401 })
+
+    assert.equal(ex.status, 401)
+  })
+
+  test('uses default status when error status is invalid', ({ assert }) => {
+    const err = new Error('test') as unknown as Exception
+    err.status = 'invalid' as unknown as number
+    const ex = fromError(err, { status: 403 })
+
+    assert.equal(ex.status, 403)
+  })
+
+  test('error status takes precedence over default status', ({ assert }) => {
+    const err = new Error('test') as unknown as Exception
+    err.status = 404
+    const ex = fromError(err, { status: 401 })
+
+    assert.equal(ex.status, 404)
+  })
+
+  test('uses default help when error has no help', ({ assert }) => {
+    const err = new Error('test')
+    const ex = fromError(err, { help: 'Default help text' })
+
+    assert.equal(ex.help, 'Default help text')
+  })
+
+  test('error help takes precedence over default help', ({ assert }) => {
+    const err = new Error('test') as unknown as Exception
+    err.help = 'Original help text'
+    const ex = fromError(err, { help: 'Default help text' })
+
+    assert.equal(ex.help, 'Original help text')
+  })
+
+  test('uses default name when error has no name', ({ assert }) => {
+    const err = { message: 'test' } as unknown as Error
+    const ex = fromError(err, { name: 'DefaultName' })
+
+    assert.equal(ex.name, 'DefaultName')
+  })
+
+  test('error name takes precedence over default name', ({ assert }) => {
+    const err = new Error('test')
+    err.name = 'OriginalName'
+    const ex = fromError(err, { name: 'DefaultName' })
+
+    assert.equal(ex.name, 'OriginalName')
+  })
+})