Errors

Monch provides typed error classes for handling failures.

Import

import {
  MonchError,
  MonchConnectionError,
  MonchValidationError,
} from '@codician-team/monch';

Error Classes

MonchError

Base class for all Monch errors:

class MonchError extends Error {
  name: 'MonchError';
  message: string;
}

MonchConnectionError

Thrown when connection fails or is misconfigured:

class MonchConnectionError extends MonchError {
  name: 'MonchConnectionError';
}

Common causes:

• No MONGODB_URI environment variable
• Invalid connection string
• Network unreachable
• Authentication failed
• Database not found

MonchValidationError

Thrown when Zod validation fails:

class MonchValidationError extends MonchError {
  name: 'MonchValidationError';
  issues: ZodIssue[];

  formatIssues(): string;
  toFormErrors(): Record<string, string>;
  get firstError(): string;
  get firstField(): string;
}

MonchValidationError Methods

issues

Raw Zod validation issues array:

error.issues
// [
//   { path: ['name'], message: 'Required', code: 'invalid_type' },
//   { path: ['email'], message: 'Invalid email', code: 'invalid_string' }
// ]

formatIssues()

Human-readable multi-line string:

error.formatIssues()
// '- name: Required\n- email: Invalid email'

toFormErrors()

Field-to-error mapping for form UIs:

error.toFormErrors()
// { name: 'Required', email: 'Invalid email' }

Only includes the first error for each field.

firstError

The first error message:

error.firstError
// 'Required'

firstField

Path to the first error field:

error.firstField
// 'name'

// For nested fields:
// 'address.city'

The _root Key

When validation errors have an empty path (top-level errors), toFormErrors() and firstField use _root as the key:

// Schema with refinement
const schema = z.object({
  password: z.string(),
  confirmPassword: z.string(),
}).refine(
  (data) => data.password === data.confirmPassword,
  { message: 'Passwords must match' }
);

// If refinement fails:
error.toFormErrors()  // { _root: 'Passwords must match' }
error.firstField      // '_root'

Usage Examples

Basic Error Handling

import { MonchValidationError, MonchConnectionError } from '@codician-team/monch';

try {
  await Users.insertOne({ name: '', email: 'invalid' });
} catch (error) {
  if (error instanceof MonchValidationError) {
    console.log('Validation failed:', error.formatIssues());
  } else if (error instanceof MonchConnectionError) {
    console.log('Connection failed:', error.message);
  } else {
    throw error;
  }
}

Form Error Display

// Server Action
export async function createUser(formData: FormData) {
  try {
    const user = await Users.insertOne({
      name: formData.get('name') as string,
      email: formData.get('email') as string,
    });
    return { success: true, user: user.serialize() };
  } catch (error) {
    if (error instanceof MonchValidationError) {
      return { success: false, errors: error.toFormErrors() };
    }
    throw error;
  }
}

// Client Component
function UserForm() {
  const [errors, setErrors] = useState<Record<string, string>>({});

  async function handleSubmit(formData: FormData) {
    const result = await createUser(formData);
    if (!result.success) {
      setErrors(result.errors);
    }
  }

  return (
    <form action={handleSubmit}>
      <input name="name" />
      {errors.name && <span className="error">{errors.name}</span>}

      <input name="email" />
      {errors.email && <span className="error">{errors.email}</span>}

      {errors._root && <span className="error">{errors._root}</span>}

      <button type="submit">Create</button>
    </form>
  );
}

Quick Validation Check

try {
  await Users.insertOne(data);
} catch (error) {
  if (error instanceof MonchValidationError) {
    // Quick access to first error
    console.log(`Error in ${error.firstField}: ${error.firstError}`);
  }
}

Type Guard

function isValidationError(error: unknown): error is MonchValidationError {
  return error instanceof MonchValidationError;
}

try {
  await Users.insertOne(data);
} catch (error) {
  if (isValidationError(error)) {
    // TypeScript knows error.issues exists
    console.log(error.issues);
  }
}

When Errors Are Thrown

Error	Operations	Cause
MonchConnectionError	Any	Connection failure, missing config
MonchValidationError	insertOne, insertMany	Full document validation fails
MonchValidationError	updateOne, updateMany, findOneAndUpdate	$set/$setOnInsert validation fails (partial)
MonchValidationError	replaceOne, findOneAndReplace	Replacement validation fails (full)
MonchValidationError	bulkWrite	Any operation validation fails