feat(helpers): add toError

Author: dmltdev

__tests__/to-error.spec.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "vitest";
+import { toError } from "../src/helpers";
+import { MongoError } from "../src/types";
+
+describe("toError", () => {
+  it("converts MongoDB error with all properties to JavaScript Error", () => {
+    const mongoError: MongoError = {
+      code: 11000,
+      name: "DuplicateKey",
+      description: "Duplicate key error collection",
+      categories: ["RetriableError"]
+    };
+
+    const result = toError(mongoError);
+
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe("[11000] DuplicateKey: Duplicate key error collection | RetriableError");
+    expect(result.cause).toBe(mongoError);
+  });
+
+  it("converts MongoDB error without description", () => {
+    const mongoError: MongoError = {
+      code: 10,
+      name: "CannotMutateObject",
+      categories: ["ValidationError"]
+    };
+
+    const result = toError(mongoError);
+
+    expect(result.message).toBe("[10] CannotMutateObject | ValidationError");
+    expect(result.cause).toBe(mongoError);
+  });
+
+  it("converts MongoDB error without categories", () => {
+    const mongoError: MongoError = {
+      code: 1,
+      name: "InternalError",
+      description: "An unspecified internal error occurred."
+    };
+
+    const result = toError(mongoError);
+
+    expect(result.message).toBe("[1] InternalError: An unspecified internal error occurred.");
+    expect(result.cause).toBe(mongoError);
+  });
+
+  it("converts minimal MongoDB error with only code and name", () => {
+    const mongoError: MongoError = {
+      code: 999,
+      name: "CustomError"
+    };
+
+    const result = toError(mongoError);
+
+    expect(result.message).toBe("[999] CustomError");
+    expect(result.cause).toBe(mongoError);
+  });
+
+  it("handles multiple categories", () => {
+    const mongoError: MongoError = {
+      code: 6,
+      name: "HostUnreachable",
+      description: "The host is unreachable.",
+      categories: ["NetworkError", "RetriableError"]
+    };
+
+    const result = toError(mongoError);
+
+    expect(result.message).toBe("[6] HostUnreachable: The host is unreachable. | NetworkError, RetriableError");
+    expect(result.cause).toBe(mongoError);
+  });
+
+  it("handles empty categories array", () => {
+    const mongoError: MongoError = {
+      code: 2,
+      name: "BadValue",
+      description: "The value provided is invalid.",
+      categories: []
+    };
+
+    const result = toError(mongoError);
+
+    expect(result.message).toBe("[2] BadValue: The value provided is invalid.");
+    expect(result.cause).toBe(mongoError);
+  });
+
+  it("uses custom formatter when provided", () => {
+    const mongoError: MongoError = {
+      code: 11000,
+      name: "DuplicateKey",
+      description: "Duplicate key error collection",
+      categories: ["RetriableError"]
+    };
+
+    const customFormatter = (error: MongoError) => 
+      `MongoDB Error ${error.code}: ${error.name}`;
+
+    const result = toError(mongoError, customFormatter);
+
+    expect(result.message).toBe("MongoDB Error 11000: DuplicateKey");
+    expect(result.cause).toBe(mongoError);
+  });
+
+  it("custom formatter receives complete MongoError object", () => {
+    const mongoError: MongoError = {
+      code: 6,
+      name: "HostUnreachable",
+      description: "The host is unreachable.",
+      categories: ["NetworkError", "RetriableError"]
+    };
+
+    const customFormatter = (error: MongoError) => {
+      return `${error.name} (${error.code}): ${error.description} [${error.categories?.join(", ")}]`;
+    };
+
+    const result = toError(mongoError, customFormatter);
+
+    expect(result.message).toBe("HostUnreachable (6): The host is unreachable. [NetworkError, RetriableError]");
+    expect(result.cause).toBe(mongoError);
+  });
+
+  it("custom formatter can return simple string", () => {
+    const mongoError: MongoError = {
+      code: 1,
+      name: "InternalError"
+    };
+
+    const customFormatter = () => "Custom error message";
+
+    const result = toError(mongoError, customFormatter);
+
+    expect(result.message).toBe("Custom error message");
+    expect(result.cause).toBe(mongoError);
+  });
+});

readme.md

@@ -37,6 +37,8 @@ import {
   getErrorCode,
   getErrorDescription,
   isKnownErrorCode,
+  getErrorDetails,
+  toError,
   MongoErrorList,
 } from "mongo-error-codes";
 
@@ -45,6 +47,16 @@ console.log(getErrorCode("DuplicateKey")); // 11000
 console.log(getErrorDescription(11000)); // description or undefined
 console.log(isKnownErrorCode(11000)); // true
 
+// Get full error details
+const errorDetails = getErrorDetails(11000);
+console.log(errorDetails); // { code: 11000, name: "DuplicateKey", ... }
+
+// Convert to JavaScript Error
+if (errorDetails) {
+  const jsError = toError(errorDetails);
+  console.log(jsError.message); // "[11000] DuplicateKey: Duplicate key error collection"
+}
+
 // List all error codes
 console.log(MongoErrorList);
 ```
@@ -101,6 +113,44 @@ console.log(getErrorDetails("DuplicateKey"));
 // { code: 11000, name: "DuplicateKey", description: "Duplicate key error collection" }
 ```
 
+#### `toError(mongoError: MongoError, formatter?: (error: MongoError) => string): Error`
+
+Converts a MongoDB error object to a JavaScript Error with a formatted message. Optionally accepts a custom formatter function.
+
+```ts
+import { toError, getErrorDetails } from "mongo-error-codes";
+
+const mongoError = getErrorDetails(11000);
+if (mongoError) {
+  // Default formatting
+  const jsError = toError(mongoError);
+  console.log(jsError.message); // "[11000] DuplicateKey: Duplicate key error collection"
+  console.log(jsError.cause); // Original MongoError object
+}
+
+// With categories
+const errorWithCategories = {
+  code: 6,
+  name: "HostUnreachable",
+  description: "The host is unreachable.",
+  categories: ["NetworkError", "RetriableError"]
+};
+const jsError = toError(errorWithCategories);
+console.log(jsError.message); 
+// "[6] HostUnreachable: The host is unreachable. | NetworkError, RetriableError"
+
+// Custom formatter
+const customError = toError(errorWithCategories, (error) => 
+  `MongoDB ${error.name} (${error.code}): ${error.description}`
+);
+console.log(customError.message);
+// "MongoDB HostUnreachable (6): The host is unreachable."
+
+// Simple custom formatter
+const simpleError = toError(mongoError, (error) => `Error ${error.code}`);
+console.log(simpleError.message); // "Error 11000"
+```
+
 ### Data Structures
 
 #### `MongoErrorCodes` (enum)

src/helpers/helpers.ts

@@ -1,4 +1,5 @@
 import { MongoCodeErrorMap, MongoNameErrorMap } from "../data/map";
+import { MongoError } from "../types";
 
 /**
  * Get the name of the error code.
@@ -58,3 +59,35 @@ export function getErrorDetails(
     return MongoNameErrorMap.get(input);
   }
 }
+
+/**
+ * Convert a MongoDB error to a JavaScript error.
+ *
+ * @param mongoError - The MongoDB error.
+ * @param formatter - Optional custom formatter function that takes a MongoError and returns a string.
+ * @returns The JavaScript error.
+ */
+export function toError(
+  mongoError: MongoError,
+  formatter?: (error: MongoError) => string
+): Error {
+  let message: string;
+
+  if (formatter) {
+    message = formatter(mongoError);
+  } else {
+    message = `[${mongoError.code}] ${mongoError.name}`;
+
+    if (mongoError.description) {
+      message += `: ${mongoError.description}`;
+    }
+
+    if (mongoError.categories?.length) {
+      message += ` | ${mongoError.categories.join(", ")}`;
+    }
+  }
+
+  return new Error(message, {
+    cause: mongoError,
+  });
+}