better-result Adopt

Adopt better-result incrementally in existing codebases without rewriting everything at once.

When to Use

Use this skill when the user wants to:

• migrate from try/catch to Result.try or Result.tryPromise

• replace nullable return values with typed Result<T, E>

• define domain-specific TaggedError types

• refactor nested error handling into andThen chains or Result.gen

• standardize error handling across a service or module

Reading Order

Task

Files to Read

Adopt better-result in a module

This file

Define or review error types

references/tagged-errors.md

Inspect library implementation details

opensrc/ if present

Prerequisites

Before editing code:

• Confirm better-result is already installed in the target project.

• Check for an opensrc/ directory. If present, read the package source there for current patterns.

• Identify the migration scope first: one file, one module, or one boundary layer.

Migration Strategy

1. Start at boundaries

Begin with I/O boundaries and exception-heavy code:

• HTTP clients

• database access

• file system operations

• parsing and validation

• framework adapters

Do not convert the whole codebase at once.

2. Classify existing failures

Category

Examples

Target shape

Domain errors

not found, validation, auth

TaggedError + Result.err

Infrastructure errors

network, DB, file I/O

Result.tryPromise + mapped error

Programmer defects

bad assumptions, null deref

leave throwing; defects become Panic inside Result callbacks

3. Migrate in this order

• Define error types.

• Wrap throwing boundaries with Result.try / Result.tryPromise.

• Replace null or boolean sentinel returns with Result.

• Refactor call sites to propagate Result values.

• Collapse nested branching into andThen, mapError, or Result.gen.

Core Transformations

Try/catch → Result.try

function parseConfig(json: string): Result<Config, ParseError> {

  return Result.try({

    try: () => JSON.parse(json) as Config,

    catch: (cause) => new ParseError({ cause, message: `Parse failed: ${cause}` }),

  });

}

Async throws → Result.tryPromise

async function fetchUser(id: string): Promise<Result<User, ApiError | UnhandledException>> {

  return Result.tryPromise({

    try: async () => {

      const res = await fetch(`/api/users/${id}`);

      if (!res.ok) throw new ApiError({ status: res.status, message: `API ${res.status}` });

      return res.json() as Promise<User>;

    },

    catch: (cause) => (cause instanceof ApiError ? cause : new UnhandledException({ cause })),

  });

}

Null sentinel → Result

function findUser(id: string): Result<User, NotFoundError> {

  const user = users.find((candidate) => candidate.id === id);

  return user

    ? Result.ok(user)

    : Result.err(new NotFoundError({ id, message: `User ${id} not found` }));

}

Nested flow → Result.gen

async function processOrder(orderId: string): Promise<Result<OrderResult, OrderError>> {

  return Result.gen(async function* () {

    const order = yield* Result.await(fetchOrder(orderId));

    const validated = yield* validateOrder(order);

    const result = yield* Result.await(submitOrder(validated));

    return Result.ok(result);

  });

}

Execution Workflow

• Audit the target module for try, catch, .catch(...), throw, null, undefined, and status-flag error handling.

• Define or update TaggedError classes before changing control flow.

• Convert boundary functions first and change their signatures to Result<T, E> or Promise<Result<T, E>>.

• Update immediate callers so they handle or propagate the new Result.

• Where multiple Result-returning steps compose, use Result.gen or andThen.

• Preserve error context by keeping cause, IDs, messages, and other structured fields.

• Run tests and add coverage for both success and error paths.

Completion Criteria

A migration is complete when:

• target functions no longer rely on try/catch for expected domain failures

• nullable or sentinel error returns are replaced with explicit Result values

• domain failures use typed TaggedError classes

• callers either propagate Result or explicitly unwrap/match it

• tests cover at least one success path and one representative error path

Common Pitfalls

• Over-wrapping everything instead of starting at boundaries

• Losing original failure context when mapping errors

• Mixing throw-based and Result-based APIs deep in the same flow

• Catching Panic instead of fixing the underlying defect

In This Reference

File

Purpose

references/tagged-errors.md

TaggedError patterns, matching, type guards, and examples

If opensrc/ exists, treat it as the source of truth for implementation details and current API behavior.