feat: add a helper to transform any error to an xception error

source/index.ts

@@ -19,3 +19,4 @@ export * from './prototype';
 export { Xception as default } from './prototype';
 
 export * from './render';
+export * from './xceptionalize';

source/xceptionalize.ts

@@ -0,0 +1,39 @@
+/*
+ *                            *** MIT LICENSE ***
+ * -------------------------------------------------------------------------
+ * This code may be modified and distributed under the MIT license.
+ * See the LICENSE file for details.
+ * -------------------------------------------------------------------------
+ *
+ * @summary   Wrap an error as an Xception instance
+ *
+ * @author    Alvis HT Tang <alvis@hilbert.space>
+ * @license   MIT
+ * @copyright Copyright (c) 2023 - All Rights Reserved.
+ * -------------------------------------------------------------------------
+ */
+
+import { Xception } from './prototype';
+
+/**
+ * convert an error to an Xception instance with metadata merged while preserving the original error message and stack
+ * @param error the error to be converted
+ * @param options additional options for the error
+ * @param options.meta meta data to be embedded in the error
+ * @returns the transformed error
+ */
+export function xceptionalize(
+  error: Error,
+  options?: { meta?: Record<string, unknown> },
+): Xception {
+  const { meta = {} } = { ...options };
+
+  const wrappedError =
+    error instanceof Xception ? error : new Xception(error.message);
+
+  wrappedError.name = error.name;
+  wrappedError.meta = { ...wrappedError.meta, ...meta };
+  wrappedError.stack = error.stack;
+
+  return wrappedError;
+}

spec/xceptionalize.spec.ts

@@ -0,0 +1,40 @@
+/*
+ *                            *** MIT LICENSE ***
+ * -------------------------------------------------------------------------
+ * This code may be modified and distributed under the MIT license.
+ * See the LICENSE file for details.
+ * -------------------------------------------------------------------------
+ *
+ * @summary   Tests on xceptionalize
+ *
+ * @author    Alvis HT Tang <alvis@hilbert.space>
+ * @license   MIT
+ * @copyright Copyright (c) 2023 - All Rights Reserved.
+ * -------------------------------------------------------------------------
+ */
+
+import { Xception } from '#prototype';
+
+import { xceptionalize } from '#xceptionalize';
+
+describe('fn:xceptionalize', () => {
+  it('wraps an error as an Xception', () => {
+    try {
+      throw new Error('test');
+    } catch (error) {
+      const xceptionalizedError = xceptionalize(error);
+      expect(xceptionalizedError).toBeInstanceOf(Xception);
+      expect(xceptionalizedError.name).toEqual('Error');
+      expect(xceptionalizedError.message).toEqual('test');
+      expect(xceptionalizedError.meta).toEqual({});
+      expect(xceptionalizedError.stack).toEqual(error.stack);
+    }
+  });
+
+  it('ignores any xception instance', () => {
+    const xception = new Xception('test');
+    const xceptionalizedError = xceptionalize(xception);
+
+    expect(xceptionalizedError).toEqual(xception);
+  });
+});