handleMongoError

The handleMongoError function converts MongoDB errors to Nimbus exceptions based on the error code. This provides consistent error handling across your application.

An in Depth Example

This guide also has an in depth example of a working application built with Nimbus. Combining DDD, CQRS and Event Sourcing.

Check out the In Depth Example page to learn how everything is connected and works out in a real-world application.

Basic Usage

import { handleMongoError } from "@nimbus-cqrs/mongodb";

try {
    await collection.insertOne(document);
} catch (error) {
    throw handleMongoError(error);
}

Error Code Mappings

MongoDB Code	Error Type	Nimbus Exception	Details Included
121	Document validation	InvalidInputException	code, details
2	Bad value	InvalidInputException	Error message
11000	Duplicate key	InvalidInputException	keyValue
Other	Various	GenericException	Original error

Error Examples

Duplicate Key Error (Code 11000)

When inserting a document that violates a unique index:

try {
    await collection.insertOne({ email: "existing@example.com" });
} catch (error) {
    const exception = handleMongoError(error);
    // InvalidInputException with:
    // - message: "E11000 duplicate key error..."
    // - details: { keyValue: { email: "existing@example.com" } }
}

Document Validation Error (Code 121)

When a document fails schema validation:

try {
    await collection.insertOne({ name: 123 }); // name should be string
} catch (error) {
    const exception = handleMongoError(error);
    // InvalidInputException with:
    // - message: "Document failed validation"
    // - details: { code: 121, details: { ... validation errors ... } }
}

Bad Value Error (Code 2)

When a query contains invalid values:

try {
    await collection.find({ $invalid: true }).toArray();
} catch (error) {
    const exception = handleMongoError(error);
    // InvalidInputException with original error message
}

Other Errors

All other MongoDB errors are wrapped in a GenericException:

try {
    await collection.find({}).toArray();
} catch (error) {
    const exception = handleMongoError(error);
    // GenericException with original error stack trace
}

Integration with CRUD Functions

All CRUD functions use handleMongoError internally:

import { insertOne } from "@nimbus-cqrs/mongodb";

try {
    await insertOne({
        collection,
        document: { email: "duplicate@example.com" },
    });
} catch (error) {
    // Error is already a Nimbus exception
    if (error.name === "INVALID_INPUT") {
        // Handle duplicate key or validation error
    }
}

Custom Error Handling

You can use handleMongoError in your own database operations:

import { handleMongoError } from "@nimbus-cqrs/mongodb";
import { GenericException } from "@nimbus-cqrs/core";

const customDatabaseOperation = async (collection: Collection) => {
    try {
        // Custom MongoDB operation
        const result = await collection
            .aggregate([
                { $match: { status: "active" } },
                { $group: { _id: "$category", total: { $sum: "$amount" } } },
            ])
            .toArray();

        return result;
    } catch (error) {
        throw handleMongoError(error);
    }
};

Error Response in API

When combined with the Hono error handler, MongoDB errors are automatically converted to HTTP responses:

// Duplicate key error becomes:
// HTTP 400
{
    "error": "INVALID_INPUT",
    "message": "E11000 duplicate key error collection: db.users index: email_1 dup key: { email: \"existing@example.com\" }",
    "details": {
        "keyValue": {
            "email": "existing@example.com"
        }
    }
}