feat: Add ensureError utility for converting unknown values to error

src/errors.test.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 
 import {
+  ensureError,
   getErrorMessage,
   isErrorWithCode,
   isErrorWithMessage,
@@ -320,3 +321,68 @@ describe('getErrorMessage', () => {
     expect(getErrorMessage(undefined)).toBe('');
   });
 });
+
+describe('ensureError', () => {
+  it('returns Error instance unchanged', () => {
+    const originalError = new Error('original message');
+    const result = ensureError(originalError);
+
+    expect(result).toBe(originalError);
+    expect(result.message).toBe('original message');
+  });
+
+  it('returns fs.promises-style error unchanged', async () => {
+    let originalError;
+    try {
+      await fs.promises.readFile('/tmp/nonexistent', 'utf8');
+    } catch (error: unknown) {
+      originalError = error;
+    }
+
+    const result = ensureError(originalError);
+
+    expect(result).toBe(originalError);
+  });
+
+  it('converts string to Error and preserves original as cause', () => {
+    const result = ensureError('something went wrong');
+
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe('Unknown error');
+    expect(result.cause).toBe('something went wrong');
+  });
+
+  it('converts object to Error and preserves original as cause', () => {
+    const originalObject = { some: 'object' };
+    const result = ensureError(originalObject);
+
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe('Unknown error');
+    expect(result.cause).toBe(originalObject);
+  });
+
+  it('handles null with descriptive message', () => {
+    const result = ensureError(null);
+
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe('Unknown error');
+    expect(result.cause).toBeNull();
+  });
+
+  it('handles undefined with descriptive message', () => {
+    const result = ensureError(undefined);
+
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe('Unknown error');
+    expect(result.cause).toBeUndefined();
+  });
+
+  it('preserves stack trace for Error instances', () => {
+    const originalError = new Error('original message');
+    const originalStack = originalError.stack;
+
+    const result = ensureError(originalError);
+
+    expect(result.stack).toBe(originalStack);
+  });
+});

src/errors.ts

@@ -119,3 +119,22 @@ export function wrapError<Throwable>(
 
   return new Error(String(originalError));
 }
+
+/**
+ * Ensures we have a proper Error object.
+ * If the input is already an Error, returns it unchanged.
+ * Otherwise, converts to an Error with an appropriate message and preserves
+ * the original value as the cause.
+ *
+ * @param error - The caught error (could be Error, string, or unknown).
+ * @returns A proper Error instance.
+ */
+export function ensureError(error: unknown): Error {
+  if (isError(error)) {
+    return error;
+  }
+
+  const newError: Error & { cause?: unknown } = new Error('Unknown error');
+  newError.cause = error;
+  return newError;
+}

src/index.test.ts

@@ -90,6 +90,7 @@ describe('index', () => {
         "createNumber",
         "createProjectLogger",
         "definePattern",
+        "ensureError",
         "exactOptional",
         "fromWei",
         "getChecksumAddress",

src/node.test.ts

@@ -93,6 +93,7 @@ describe('node', () => {
         "definePattern",
         "directoryExists",
         "ensureDirectoryStructureExists",
+        "ensureError",
         "exactOptional",
         "fileExists",
         "forceRemove",