Errors

All Mongster errors inherit from MongsterError. The specialized classes let you handle failures at the right level without pattern-matching raw strings.

import { MongsterError, ValidationError } from "mongster";

try {
  throw new ValidationError("Email is required");
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(error.message);
  }

  if (error instanceof MongsterError) {
    console.error(error.code, error.message);
  }
}

Error classes

When to catch what

• Catch ValidationError when you want to return a user-facing input error.
• Catch ConnectionError during startup and fail fast.
• Catch MongsterError when you want one fallback for every library-specific failure.

MongsterError shape

Every MongsterError carries:

• name — the class name ("SchemaError", "ValidationError", etc.).
• message — the human-readable message.
• code: MongsterErrorCode — one of the codes in the table above.
• issues: MongsterIssue[] — a normalized list of structured problems.

MongsterError extends the standard Error, so cause, stack, and the standard constructor options work as expected.

MongsterIssue

The shape of each item in error.issues:

interface MongsterIssue {
  path?: (string | number)[];
  message: string;
}

path is present when the issue is tied to a specific field or array index. Use it to map errors back to form fields or to surface a structured response.

MongsterErrorCode

The full set of codes that can appear on error.code:

type MongsterErrorCode =
  | "schema_error"
  | "validation_error"
  | "query_error"
  | "connection_error"
  | "transaction_error"
  | "index_sync_error";

Switch on code if you want one centralized handler rather than instanceof chains.

Stack trace toggle

MongsterError.stackTraces is a static toggle that controls whether instances capture a stack trace. Disabling it on hot paths or in production can shave a small but non-trivial amount of overhead off schema validation.

import { MongsterError } from "mongster";

// Disable (e.g., in production hot paths).
MongsterError.stackTraces = false;

// Re-enable (default).
MongsterError.stackTraces = true;

Errors still carry their name, message, code, and issues; only the stack string is omitted.