Errfy

Lightweight error constructor for Node.js and browsers. Create, customize, and log errors with ease — your errors, your rules.

Features ✨

• 🔹 Customizable error name, code, and details.
• ✅ JSON serialization for structured error output.
• 🚀 Simple create function for easy error instantiation.
• 💬 Consistent error logging with logError (via lumilog).
• 🌐 TypeScript-ready with strong typings.
• ⚡ Minimal dependencies, lightweight core.
• 🛠️ Compatible with Node.js and browsers.

Installation 💿

pnpm add errfy
# or
npm install errfy
# or
yarn add errfy

Quick Start 🚀

import { create, logError } from 'errfy';

// Create an error
const error = create('Invalid input', {
  code: 'ERR_INVALID',
  details: { field: 'email' },
  name: 'InputError',
});

// Log the error
logError('Validation failed', error);
// Output: "Validation failed: Invalid input"
// Followed by stack trace

API

Errfy

A custom error class extending Error.

class Errfy extends Error {
  constructor(
    message: string,
    code: string = 'ERR_DEFAULT',
    details: Record<string, any> = {},
    name: string = 'Errfy',
  );
  name: string;
  code: string;
  details: Record<string, any>;
  toJSON(): Record<string, any>;
}

• Parameters:
  • message: Error message.
  • code: Error code (default: 'ERR_DEFAULT').
  • details: Additional details (default: {}).
  • name: Custom error name (default: 'Errfy').
• Methods:
  • toJSON(): Returns { code, details, message, name, stack }.

create

Creates an Errfy instance with a simpler syntax.

function create(message: string, options: CreateOptions = {}): Errfy;

• Parameters:
  • message: Error message.
  • options: Configuration object.
    • code: Error code (default: 'ERR_DEFAULT').
    • details: Additional details (default: {}).
    • name: Custom error name (default: 'Errfy').
• Returns: A new Errfy instance.

CreateOptions

Interface for create function options.

interface CreateOptions {
  code?: string;
  details?: Record<string, any>;
  name?: string;
}

logError

Logs errors using lumilog.

function logError(message: string = 'Error', error: unknown): void;

• Parameters:
  • message: Context message (default: 'Error').
  • error: Error to log (Errfy, Error, or any value).
• Behavior: Logs the message and error; includes stack trace for Errfy or Error instances.

Examples 📚

Basic Error Creation

import { Errfy, create } from 'errfy';

const error1 = new Errfy('Database error', 'ERR_DB', { status: 500 });
console.log(error1.toJSON());
// Output: { code: 'ERR_DB', details: { status: 500 }, message: 'Database error', name: 'Errfy', stack: '...' }

const error2 = create('Invalid input', {
  code: 'ERR_INVALID',
  details: { field: 'email' },
});
console.log(error2.toJSON());
// Output: { code: 'ERR_INVALID', details: { field: 'email' }, message: 'Invalid input', name: 'Errfy', stack: '...' }

Logging Errors

import { create, logError } from 'errfy';

const error = create('Invalid input', {
  code: 'ERR_INVALID',
  name: 'InputError',
});
logError('Validation failed', error);
// Output: "Validation failed: Invalid input"
// Followed by stack trace

logError('Unknown issue', { code: 500 });
// Output: "Unknown issue: [object Object]"

Error Handling

import { create, logError } from 'errfy';

try {
  throw create('Failed to connect', {
    code: 'ERR_CONNECTION',
    details: { retry: false },
  });
} catch (error) {
  logError('Operation failed', error);
  console.log(error.toJSON());
}

Best Practices 📝

1. Use descriptive error codes for easy debugging.
2. Include relevant details in details for context.
3. Set custom error names to differentiate error types.
4. Wrap risky code in try/catch to handle Errfy instances.
5. Use logError for consistent logging with lumilog.
6. Keep error messages clear and concise.

License 📄

MIT License – see LICENSE. Author: Estarlin R (estarlincito.com)