🦥 faultier

Extensible error handling for TypeScript

Faultier provides a structured way to create, wrap, and handle errors with type-safe tags and context. Define your error types in one place, then use them throughout your application with full TypeScript support for error classification and associated metadata.

Made with 🥐 pastry

Table of Contents

• Features
• Installation
• Usage
  • Quick Start
  • Type Safety
  • Error Chaining
  • Handling Faults
  • Extending Error Classes
• API Reference
• Contributing
• Acknowledgments
• License

Features

• Type-safe tags - Define error tags and get autocomplete and type checking
• Typed context - Associate structured metadata with each error type
• Dual messages - Separate debug messages for logs from user-facing messages
• Error chaining - Wrap and re-throw errors while preserving the full chain
• Extensible - Extend existing Error classes with Fault functionality
• Serializable - Convert faults to JSON and reconstruct them
• No dependencies - Zero runtime dependencies

Installation

# npm
npm install faultier

# yarn
yarn add faultier

# pnpm
pnpm add faultier

# bun
bun add faultier

Usage

Quick Start

import Fault from "faultier";

// Wrap an existing error and add classification
try {
  await database.query();
} catch (err) {
  throw Fault.wrap(err) // Wrap any error as a Fault
    .withTag("DATABASE_ERROR") // Classify with a tag
    .withContext({ query: "SELECT * FROM users" }); // Attach metadata
}

// Or create a fault directly when you control the error
throw Fault.create("NOT_FOUND").withContext({ resource: "user", id: "123" });

// Separate debug info from user-facing messages
throw Fault.wrap(err).withTag("PAYMENT_ERROR").withDescription(
  "Stripe API error 402: card_declined (insufficient_funds)", // Debug (for logs)
  "Payment failed. Please try a different card." // User-facing message
);

Type Safety

Define your error types using module augmentation. This tells TypeScript about your custom error tags and their expected context shapes:

declare module "faultier" {
  interface FaultRegistry {
    DATABASE_ERROR: { query: string; host?: string };
    AUTH_ERROR: { userId: string; reason: string };
    NOT_FOUND: { resource: string; id: string };
    VALIDATION_ERROR: { field: string; message: string };
    GENERIC_ERROR: never; // No context allowed - withContext will error
  }
}

Now TypeScript enforces correct tag/context combinations:

// Type-safe: context must match the tag
Fault.create("DATABASE_ERROR").withContext({ query: "SELECT *" }); // OK

Fault.create("DATABASE_ERROR").withContext({ userId: "123" }); // Type error: missing 'query'

Fault.create("NOT_FOUND").withContext({ resource: "user", id: "123" }); // OK

Fault.create("GENERIC_ERROR").withContext({ anything: "value" }); // Type error: withContext returns never

For larger applications with many error types, you can organize them into groups:

// Group related errors together
type DatabaseErrors = {
  DB_CONNECTION_ERROR: { host: string; port: number };
  DB_QUERY_ERROR: { query: string; table: string };
  DB_TIMEOUT_ERROR: { timeout: number };
};

type AuthErrors = {
  AUTH_INVALID_TOKEN: { token: string; reason: string };
  AUTH_EXPIRED_SESSION: { sessionId: string };
  AUTH_INSUFFICIENT_PERMISSIONS: { userId: string; required: string[] };
};

type ValidationErrors = {
  VALIDATION_FAILED: { field: string; message: string };
  VALIDATION_SCHEMA_ERROR: { errors: string[] };
};

// Combine all error types in your registry
declare module "faultier" {
  interface FaultRegistry extends DatabaseErrors, AuthErrors, ValidationErrors {
    // Add any standalone errors here
    GENERIC_ERROR: never;
  }
}

Error Chaining

Faults preserve the full error chain:

try {
  await fetchUser();
} catch (err) {
  throw Fault.wrap(err).withTag("SERVICE_ERROR").withDescription(
    "User service failed on primary endpoint", // Debug message
    "Unable to load user data" // User-facing message
  );
}

Extract information from the chain:

const fault = Fault.wrap(originalError)
  .withTag("API_ERROR")
  .withContext({ endpoint: "/users" });

fault.unwrap(); // [fault, ...causes, originalError] - full chain as array
fault.flatten(); // "API failed -> Service error -> Connection timeout" - messages joined
fault.getTags(); // ["API_ERROR", "SERVICE_ERROR", "DB_ERROR"] - all tags in chain
fault.getFullContext(); // { endpoint: "/users", host: "..." } - merged context from all faults

Handling Faults

Single Tag Matching

Use Fault.matchTag when you only need to handle one specific fault type:

const result = Fault.matchTag(error, "DATABASE_ERROR", (fault) => {
  logger.error("DB error", fault.context.query);
  return { status: 500 };
});

if (Fault.isUnknown(result)) {
  // Not a fault or different tag
}

Multiple Tag Matching

Use Fault.matchTags to handle several fault types:

const result = Fault.matchTags(error, {
  NOT_FOUND: (fault) => ({ status: 404 }),
  AUTH_ERROR: (fault) => ({ status: 401 }),
});

if (Fault.isUnknown(result)) {
  // Not a fault or unhandled tag
}

Global Error Handling

Use Fault.handle in global error handlers where you need to handle every possible fault type. It requires handlers for ALL registered tags:

const result = Fault.handle(error, {
  DATABASE_ERROR: (fault) => {
    logger.error("DB error", fault.context.query);
    return { status: 500 };
  },
  NOT_FOUND: (fault) => {
    return { status: 404, resource: fault.context.resource };
  },
  AUTH_ERROR: (fault) => {
    return { status: 401 };
  },
  // ... all registered tags
});

if (Fault.isUnknown(result)) {
  // Not a fault
}

Extending Error Classes

Use faultier/extend to add Fault functionality to existing Error classes:

import { extend } from "faultier/extend";

class HttpError extends Error {
  constructor(message: string, public statusCode: number) {
    super(message);
  }
}

const HttpFault = extend(HttpError);

const fault = HttpFault.create("Not found", 404)
  .withTag("HTTP_ERROR")
  .withContext({ path: "/api/users" });

console.log(fault.statusCode); // 404
console.log(fault.tag); // "HTTP_ERROR"
console.log(fault.flatten()); // Works like regular Fault

API Reference

Fault

Fault.wrap(error)

Wraps any error into a Fault instance.

Fault.wrap(new Error("Something failed"))
  .withTag("INTERNAL_ERROR")
  .withContext({ operation: "sync" });

Fault.create(tag)

Creates a new Fault with the specified tag.

Fault.create("VALIDATION_ERROR").withContext({
  field: "email",
  message: "Invalid format",
});

Instance Methods

fault.withTag(tag)

Sets the tag for a wrapped fault.

fault.withContext(context)

Sets the context for a tagged fault.

fault.withDescription(debug, message?)

Sets debug and optional user-facing messages.

fault.withDebug(debug)

Sets only the debug message (for developers/logs).

fault.withMessage(message)

Sets only the user-facing message (overrides the original error message).

fault.unwrap()

Returns the full error chain as an array.

fault.flatten(options?)

Flattens all messages into a single string.

fault.getTags()

Returns all tags from faults in the chain.

fault.getFullContext()

Returns merged context from all faults in the chain.

Static Methods

Fault.isFault(value)

Type guard to check if a value is a Fault.

try {
  await riskyOperation();
} catch (error) {
  if (Fault.isFault(error)) {
    console.log(error.tag); // Type-safe access
    console.log(error.context); // Type-safe access
  }
}

Fault.toSerializable(fault)

Converts a fault and its entire error chain to a plain object for serialization.

const fault = Fault.create("API_ERROR")
  .withContext({ endpoint: "/users" })
  .withDescription("Request failed");

const serialized = Fault.toSerializable(fault);
// {
//   name: "Fault",
//   tag: "API_ERROR",
//   message: "Request failed",
//   context: { endpoint: "/users" },
//   cause: { name: "Error", message: "Connection timeout" }
// }

// Send over network, store in database, etc.
await redis.set("last-error", JSON.stringify(serialized));

Fault.fromSerializable(data)

Reconstructs a Fault from serialized data, preserving the full error chain.

const data = await redis.get("last-error");
const fault = Fault.fromSerializable(JSON.parse(data));

console.log(fault.tag); // "API_ERROR"
console.log(fault.unwrap()); // Full chain restored

Fault.getIssue(fault, options?)

Extracts and joins user-facing messages from all faults in the chain.

const fault = Fault.wrap(dbError)
  .withTag("SERVICE_ERROR")
  .withDescription("DB failed", "Service unavailable");

Fault.getIssue(fault);
// "Service unavailable. Database connection failed."

Fault.getIssue(fault, { separator: " | " });
// "Service unavailable. | Database connection failed."

Fault.getDebug(fault, options?)

Extracts and joins debug messages from all faults in the chain.

const fault = Fault.wrap(dbError)
  .withTag("SERVICE_ERROR")
  .withDescription("Connection to postgres:5432 timed out after 30s");

Fault.getDebug(fault);
// "Connection to postgres:5432 timed out after 30s."

Fault.getDebug(fault, { separator: " -> " });
// "Connection to postgres:5432 timed out after 30s. -> Original DB error."

Fault.matchTag(error, tag, callback)

Matches a fault against a single tag. Runs the callback only if the error is a fault with the specified tag.

const result = Fault.matchTag(error, "DATABASE_ERROR", (fault) => {
  logger.error("DB error", { query: fault.context.query });
  return { status: 500 };
});

if (Fault.isUnknown(result)) {
  // Not a fault or different tag
}

Fault.matchTags(error, handlers)

Matches a fault against multiple tags. Runs the matching handler if the error is a fault with one of the specified tags. Unlike handle, only requires handlers for the tags you want to match.

const result = Fault.matchTags(error, {
  NOT_FOUND: (fault) => {
    return { status: 404, resource: fault.context.resource };
  },
  DB_ERROR: (fault) => {
    logger.error("DB error", { query: fault.context.query });
    return { status: 500 };
  },
});

if (Fault.isUnknown(result)) {
  // Not a fault or unhandled tag
}

Fault.handle(error, handlers)

Exhaustively dispatches a fault to handlers for all registered tags. Use this in global error handlers where you need to handle every possible fault type. For partial matching, use matchTag or matchTags instead.

const result = Fault.handle(error, {
  DATABASE_ERROR: (fault) => {
    logger.error("DB error", { query: fault.context.query });
    return { status: 500, message: "Database error" };
  },
  NOT_FOUND: (fault) => {
    return { status: 404, resource: fault.context.resource };
  },
  AUTH_ERROR: (fault) => {
    return { status: 401, reason: fault.context.reason };
  },
  // ... all registered tags
});

if (Fault.isUnknown(result)) {
  // Error is not a Fault
  throw error;
}

return result; // { status: 404, resource: "user" }

Fault.isUnknown(value)

Checks if a match result is UNKNOWN (not a fault or no handler matched). Use this to check the result of matchTag, matchTags, or handle.

const result = Fault.matchTags(error, {
  NOT_FOUND: (fault) => ({ status: 404 }),
});

if (Fault.isUnknown(result)) {
  // Not a fault or unhandled tag
  throw error;
}

// result is typed as { status: number } here

Fault.assert(error)

Asserts that an error is a Fault, re-throwing if it's not.

try {
  await riskyOperation();
} catch (error) {
  Fault.assert(error); // Throws if not a Fault

  // TypeScript now knows error is a Fault
  console.log(error.tag);
  console.log(error.context);
}

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Acknowledgments

This project is inspired by the Fault library.

License

MIT