@dxos/errors 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@dxos/errors",
-  "version": "0.8.4-main.84f28bd",
+  "version": "0.8.4-main.937b3ca",
   "description": "Error definitions",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"

package/src/base.ts

@@ -2,12 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-export type BaseErrorOptions = {
+/**
+ * Options for creating a BaseError.
+ */
+export type BaseErrorOptions = ErrorOptions & {
   /**
-   * The cause of the error.
-   * An instance of Error.
+   * Override base message.
    */
-  cause?: unknown;
+  message?: string;
 
   /**
    * Structured details about the error.
@@ -15,41 +17,63 @@ export type BaseErrorOptions = {
   context?: Record<string, unknown>;
 };
 
-export class BaseError extends Error {
-  static extend(code: string) {
-    return class extends BaseError {
-      static code = code;
+/**
+ * Base class for all DXOS errors.
+ */
+export class BaseError<Name extends string = string> extends Error {
+  /**
+   * Primary way of defining new error classes.
+   * Extended class may specialize constructor for required context params.
+   * @param name - Error name.
+   * @param message - Default error message.
+   */
+  static extend<Name extends string = string>(name: Name, message?: string) {
+    return class ExtendedError extends BaseError<Name> {
+      static override name: Name = name;
 
       static is(error: unknown): error is BaseError {
-        return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+        return typeof error === 'object' && error !== null && 'name' in error && error.name === name;
+      }
+
+      static wrap(
+        options?: Omit<BaseErrorOptions, 'cause'> & { ifTypeDiffers?: boolean },
+      ): (error: unknown) => ExtendedError {
+        const wrapFn = (error: unknown) => {
+          if (options?.ifTypeDiffers === true && this.is(error)) {
+            return error as ExtendedError;
+          }
+          const newError: ExtendedError = new this({ message, ...options, cause: error });
+          Error.captureStackTrace(newError, wrapFn); // Position stack-trace to start from the caller of `wrap`.
+          return newError;
+        };
+        return wrapFn;
       }
 
-      constructor(message: string, options?: BaseErrorOptions) {
-        super(code, message, options);
+      constructor(options?: BaseErrorOptions) {
+        super(name, { message: options?.message ?? message, ...options });
       }
     };
   }
 
-  #code: string;
-  #context: Record<string, unknown>;
+  // NOTE: Errors go through odd transformations and the private fields seem to break.
+  override name: Name;
+  context: Record<string, unknown>;
 
-  constructor(code: string, message: string, options?: BaseErrorOptions) {
-    super(message, options);
+  constructor(name: Name, options?: BaseErrorOptions) {
+    super(options?.message, { cause: options?.cause });
 
-    this.#code = code;
-    this.#context = options?.context ?? {};
+    this.name = name;
+    this.context = options?.context ?? {};
     Object.setPrototypeOf(this, new.target.prototype);
   }
 
-  override get name() {
-    return this.#code;
-  }
-
-  get code() {
-    return this.#code;
+  /** Fallback message. */
+  override get message() {
+    return this.constructor.name;
   }
 
-  get context() {
-    return this.#context;
+  // For effect error matching.
+  get _tag(): Name {
+    return this.name;
   }
 }

package/src/errors.test.ts

@@ -4,14 +4,16 @@
 
 import { describe, expect, test } from 'vitest';
 
+import { BaseError, type BaseErrorOptions } from './base';
 import { SystemError } from './errors';
 
 describe('errors', () => {
   test('error code and message, cause', () => {
-    const error = new SystemError('Test message', { cause: new Error('Test cause'), context: { a: 1, b: 2 } });
+    const error = new SystemError({ message: 'Test message', cause: new Error('Test cause'), context: { a: 1, b: 2 } });
     expect(error).toBeInstanceOf(SystemError);
     expect(error).toBeInstanceOf(SystemError);
-    expect(error.code).toBe(SystemError.code);
+    expect(error.name).toBe(SystemError.name);
+    expect(error._tag).toBe(SystemError.name);
     expect(error.message).toBe('Test message');
     expect(error.cause).toBeInstanceOf(Error);
     expect((error.cause as Error).message).toBe('Test cause');
@@ -24,19 +26,37 @@ describe('errors', () => {
       expect.fail('Expected error to be thrown');
     } catch (error: any) {
       expect(error).toBeInstanceOf(SystemError);
-      expect(String(error)).toEqual('SYSTEM_ERROR: Test message');
+      expect(String(error)).toEqual('SystemError: Test message');
       const stackLines = error.stack!.split('\n');
-      expect(stackLines?.[0]).toEqual('SYSTEM_ERROR: Test message');
+      expect(stackLines?.[0]).toEqual('SystemError: Test message');
       expect(stackLines?.[1]).toMatch(/^ {4}at two \(.*$/);
       expect(stackLines?.[2]).toMatch(/^ {4}at one \(.*$/);
     }
   });
+
+  test('custom message', () => {
+    class CustomError extends BaseError.extend('CustomError', 'Custom message') {
+      constructor(value: number, options?: Omit<BaseErrorOptions, 'context'>) {
+        super({ context: { value }, ...options });
+      }
+    }
+
+    const error = new CustomError(1);
+    expect(error).toBeInstanceOf(CustomError);
+    expect(error.message).toBe('Custom message');
+    expect(error.context).toEqual({ value: 1 });
+  });
+
+  test('is', () => {
+    const error = new SystemError({ message: 'Test message' });
+    expect(SystemError.is(error)).toBe(true);
+  });
 });
 
 const throwError = () => {
   const one = () => {
     const two = () => {
-      throw new SystemError('Test message');
+      throw new SystemError({ message: 'Test message' });
     };
     two();
   };

package/src/errors.ts

@@ -4,14 +4,16 @@
 
 import { BaseError } from './base';
 
-export class TimeoutError extends BaseError.extend('TIMEOUT') {}
+export class ApiError extends BaseError.extend('ApiError', 'API error') {}
 
-export class AbortedError extends BaseError.extend('ABORTED') {}
+export class SystemError extends BaseError.extend('SystemError', 'System error') {}
 
-export class UnimplementedError extends BaseError.extend('UNIMPLEMENTED') {}
+export class InternalError extends BaseError.extend('InternalError', 'Internal error') {}
 
-export class ApiError extends BaseError.extend('API_ERROR') {}
+export class TimeoutError extends BaseError.extend('TimeoutError', 'Timeout') {}
 
-export class SystemError extends BaseError.extend('SYSTEM_ERROR') {}
+export class AbortedError extends BaseError.extend('AbortedError', 'Aborted') {}
 
-export class InternalError extends BaseError.extend('INTERNAL_ERROR') {}
+export class NotImplementedError extends BaseError.extend('NotImplementedError', 'Not implemented') {}
+
+export class RuntimeServiceError extends BaseError.extend('RuntimeServiceError', 'Runtime service error') {}