feat: introduce a factory option in xception

Author: alvis

README.md

@@ -182,6 +182,44 @@ try {
 
 ---
 
+### Method: xception
+
+Convert an error to an Xception instance with metadata merged, preserving the original error message and stack.
+
+▸ **xception(exception: unknown, options?: Options): Xception**
+
+| Parameter           | Type                                                      | Description                                                                                            |
+| ------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `exception`         | unknown                                                   | a string, error, Xception, or object with a message property to be converted into an Xception instance |
+| `options.meta`      | `Record<string, unknown>`                                 | metadata to be embedded in the error                                                                   |
+| `options.namespace` | `string`                                                  | an identifier of the component where the error occurred                                                |
+| `options.tags`      | `string[]`                                                | tags for associating the error with specific contexts or categories                                    |
+| `options.factory`   | `(message: string, options: XceptionOptions) => Xception` | a custom factory function for creating `Xception` instances                                            |
+
+#### _/ Example /_
+
+```ts
+import { xception } from 'xception';
+
+try {
+  throw new Error('original error message');
+} catch (e) {
+  // convert to Xception with additional metadata
+  const customError = xception(error, {
+    meta: { key: 'value' },
+    namespace: 'namespace',
+    tags: ['critical'],
+    factory: (message, options) => new CustomXception(message, options),
+  });
+
+  throw customError;
+}
+```
+
+This method allows for the transformation of existing errors into `Xception` instances, facilitating a unified approach to error handling and logging within applications.
+
+---
+
 ## Know Issues & Limitations
 
 - This package is designed to provide server-side debugging functionality only. It has not been tested on any web browsers.

source/xception.ts

@@ -14,15 +14,16 @@
  */
 
 import { isErrorLike } from '#isErrorLike';
-import { jsonify } from '#jsonify';
 import { Xception } from '#prototype';
 import { $meta, $namespace, $tags } from '#symbols';
 
-import type { JsonObject } from 'type-fest';
-
 import type { ErrorLike } from '#isErrorLike';
 import type { XceptionOptions } from '#prototype';
 
+type Options = Omit<XceptionOptions, 'cause'> & {
+  factory?: (message: string, options: XceptionOptions) => Xception;
+};
+
 /**
  * convert an error to an Xception instance with metadata merged while preserving the original error message and stack
  * @param exception an exception to be converted
@@ -32,55 +33,71 @@ import type { XceptionOptions } from '#prototype';
  */
 export default function xception(
   exception: unknown, // string, error, Xception, { message: string, ...}
-  options?: Omit<XceptionOptions, 'cause'>,
+  options?: Options,
 ): Xception {
-  const { namespace, meta = {}, tags = [] } = { ...options };
+  // when options.factory is provided, it's used to create Xception instances; otherwise, the default constructor is used
+  const factory =
+    options?.factory ??
+    ((message: string, options?: XceptionOptions) =>
+      new Xception(message, options));
 
   if (isErrorLike(exception)) {
-    const error = createXceptionFromError(exception);
-
-    // merge the namespace
-    error[$namespace] = namespace ?? error[$namespace];
+    // fetch defaults if provided in options, or use properties of the original exception
+    const { namespace, meta, tags } = computeDefaults(exception, options);
 
-    // merge the meta data
-    error[$meta] = { ...error[$meta], ...meta };
-
-    // merge the tags
-    error[$tags] = [...new Set([...error[$tags], ...tags])];
+    // create a new Xception with the original error's message and computed options
+    const error = factory(exception.message, { namespace, meta, tags });
 
     // replace the name and stack from the original error
     error.name = exception.name ?? error.name;
     error.stack = exception.stack ?? error.stack;
 
     return error;
   } else if (typeof exception === 'string') {
-    return new Xception(exception, options);
+    // if exception is a string, we create a new Xception with the given message and options
+    const { namespace, meta, tags } = { ...options };
+
+    return factory(exception, { namespace, meta, tags });
   }
 
+  // if exception is of unexpected type, throw a new Xception indicating the problem
   throw new Xception('unexpected exception type', {
     ...options,
     cause: exception,
   });
 }
 
 /**
- * convert an error-like object to an Xception instance
- * @param exception an exception to be converted
- * @returns the transformed error
+ * compute defaults for namespace, meta, and tags by combining the ones present on the exception and the provided options
+ * @param exception the original exception-like object
+ * @param options additional options provided for generating the `Xception` instance
+ * @returns an object containing computed namespace, meta, and tags to be used for the new `Xception`
  */
-export function createXceptionFromError(exception: ErrorLike): Xception {
-  if (exception instanceof Xception) {
-    return exception;
-  } else {
-    const {
-      name: _name,
-      message: _message,
-      stack: _stack,
-      ...meta
-    } = jsonify(exception) as JsonObject;
+function computeDefaults(
+  exception: ErrorLike,
+  options?: Options,
+): {
+  namespace?: string;
+  meta: Record<string, unknown>;
+  tags: string[];
+} {
+  // if a namespace is provided in options, use it, otherwise use the original exception's namespace, if any
+  const namespace =
+    options?.namespace ?? (exception[$namespace] as string | undefined);
 
-    return new Xception(exception.message, {
-      meta,
-    });
-  }
+  // merge metadata from the original exception and options
+  const meta = {
+    ...(exception[$meta] as Record<string, unknown>),
+    ...options?.meta,
+  };
+
+  // concatenate and deduplicate tags from both the exception and the options
+  const tags = [
+    ...new Set([
+      ...((exception[$tags] as string[] | undefined) ?? []),
+      ...(options?.tags ?? []),
+    ]),
+  ];
+
+  return { namespace, meta, tags };
 }

spec/xception.spec.ts

@@ -15,8 +15,8 @@
 
 import { Xception } from '#prototype';
 
+import { $meta } from '#symbols';
 import xception from '#xception';
-import { $cause, $meta } from '#symbols';
 
 describe('fn:xceptionalize', () => {
   it('should wrap a string as an Xception', () => {