better-result

v2 introduces Panic to handle unrecoverable errors (bugs) that occur inside Result operations, such as when a user-provided callback throws or a generator cleanup fails. This distinguishes between recoverable domain errors (Err) and developer bugs (Panic).

• Automatic Panics: Occur when a callback inside .map() or similar operations throws, or when a Result.gen cleanup block throws.
• Manual Panics: Use the panic(message, cause) function.
• Type Guarding: Use isPanic(error) to identify a panic.

import { Panic, panic, isPanic } from "better-result";

// Manual panic
panic("something went wrong", cause);

// Type guard
if (isPanic(error)) {
  console.log(error.message, error.cause);
}

import { Panic, panic, isPanic } from "better-result";

// Callbacks that throw now cause Panic instead of corrupting state
Result.ok(1).map(() => {
  throw new Error("bug");
}); // throws Panic

// Generator cleanup throws → Panic
Result.gen(function* () {
  try {
    yield* Result.err("expected");
  } finally {
    throw new Error("cleanup bug"); // throws Panic
  }
});

// Manual panic
panic("something went wrong", cause);

// Type guard
if (isPanic(error)) {
  console.log(error.message, error.cause);
}

Panic is thrown (not returned) when a user-provided callback (like in .map(), Result.gen, or Result.try) throws an exception. This represents a code defect rather than a recoverable domain error.

To catch a Panic for error reporting, use isPanic(error), Panic.is(error), or error instanceof Panic.

Panic Properties:

• message: string describing the panic.
• cause: unknown, the original exception.

Why Panic? Using Err for bugs would compromise type safety by forcing Result<T, E | unknown>. Panic preserves the integrity of the Result type.

import { Panic, isPanic } from "better-result";

// Callback throws → Panic
Result.ok(1).map(() => {
  throw new Error("bug");
}); // throws Panic

// Catching Panic (for error reporting)
try {
  result.map(() => {
    throw new Error("bug");
  });
} catch (error) {
  if (isPanic(error)) {
    console.error("Defect:", error.message, error.cause);
  }

  if (Panic.is(error)) {
    // same behavior
  }

  if (error instanceof Panic) {
    // works too
  }
}

In better-result v2, TaggedError is used as a factory function to define error classes. Instead of manually defining a _tag property and calling super(message), you pass the tag name to TaggedError() and provide a generic type for the error's properties (which must include message).

Pattern 1: Simple class

For simple errors, pass the tag and the property types to the factory, then extend the resulting class.

Pattern 2: Computed messages

If the message depends on other properties, implement a constructor that accepts an arguments object and calls super() with the computed message included in the object.

Pattern 3: Validation logic

Validation logic should be placed inside the constructor before calling super().

Pattern 4: Extra runtime properties

Properties not passed in the constructor (like timestamps) should be included in the generic type definition and added via the super() call.

When upgrading better-result from v1 to v2, you must migrate error definitions from the class-based TaggedError API to the new factory-based API.

Key Changes

• Class Declaration: Instead of class FooError extends TaggedError, use the factory pattern: class FooError extends TaggedError("FooError")<Props>() {}.
• Tag Generation: You no longer need to manually define readonly _tag = "FooError" as const; the factory generates this for you.
• Constructor Arguments: Positional arguments are replaced by a single object argument. For example, new FooError("123") becomes new FooError({ id: "123", message: "..." }).
• Static Helpers: Static methods on TaggedError have been replaced by standalone helper functions:
  • TaggedError.match(...) $\rightarrow$ matchError(...)
  • TaggedError.matchPartial(...) $\rightarrow$ matchErrorPartial(...)
  • TaggedError.isTaggedError(...) $\rightarrow$ isTaggedError(...) or TaggedError.is(...)

Follow these steps to ensure a complete migration from better-result v1 to v2:

1. Identify Targets: Search the codebase for extends TaggedError and readonly _tag =.
2. Extract Metadata: For each class, identify the _tag literal, constructor parameters, runtime properties, and any validation or computed message logic.
3. Rewrite Class: Use the TaggedError("Tag")<Props>() factory pattern.
4. Handle Custom Logic: If the error requires custom logic (like validation or computing a message), implement a custom constructor that accepts an object and calls super({...}).
5. Update Call Sites: Change all new ErrorClass(arg1, arg2) calls to the new object-based shape new ErrorClass({ arg1, arg2, message }).
6. Replace Helpers: Swap TaggedError.match, TaggedError.matchPartial, and TaggedError.isTaggedError with their standalone v2 counterparts.
7. Update Imports: Ensure all new standalone helpers are correctly imported.
8. Verify: Run tests and perform a final search for old API patterns.

The project provides portable SKILL.md skills to help AI agents adopt or migrate to better-result.

Available Skills

• better-result-adopt: Guides an agent through converting try/catch to Result methods, defining TaggedError classes, and refactoring to Result.gen.
• better-result-migrate-v2: Guides an agent through migrating TaggedError from v1 to the v2 factory syntax.

Installation via skills.sh

Use npx skills to add these to your agent's environment:

npx skills add dmmulroy/better-result@better-result-adopt
npx skills add dmmulroy/better-result@better-result-migrate-v2

To install globally without prompts:

npx skills add dmmulroy/better-result@better-result-adopt -g -y

Manual Installation

If your agent does not support skills.sh, manually copy the following directories into the agent's skills folder:

• skills/better-result-adopt/
• skills/better-result-migrate-v2/