sc30gsw/better-result-adopt

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:

1. Confirm better-result is already installed in the target project.
2. Check for an opensrc/ directory. If present, read the package source there for current patterns.
3. 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. Follow official Best Practices

Use the official better-result Best Practices as the source of truth:

• Use Result for expected failures that are part of normal flow.
• Wrap throwing third-party and generated-client calls with Result.try / Result.tryPromise.
• Use TaggedError for discriminated domain and infrastructure error unions.
• Preserve context on errors with fields such as message, cause, ids, status, operation, and reason.
• Compose multi-step flows with Result.gen; in async generators, use yield* Result.await(...).
• Avoid premature unwrapping. Keep values in the Result context until a framework or serialization boundary.
• Use Result.isError / Result.isOk type guards or .match(...); both are valid. Choose the clearer option for the call site.
• Use matchError when handling a tagged error union exhaustively.
• Never use Result<T, any>.
• Do not ignore Result errors. Handle, propagate, or log them intentionally.
• Do not call .unwrap() without a preceding type guard or an intentional, documented throw.
• Test both success and error paths.

3. 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 |

4. Migrate in this order

1. Define error types.
2. Wrap throwing boundaries with Result.try / Result.tryPromise.
3. Replace null or boolean sentinel returns with Result.
4. Refactor call sites to propagate Result values.
5. Collapse nested branching into andThen, mapError, or Result.gen.

Serialization Boundaries

When a function is called through RPC, server functions, route loaders, or any serialization boundary:

• Use Result internally to model and compose failures.
• Do not return Ok, Err, TaggedError, Error, Response, or other class instances directly.
• Convert the final outcome to a plain serializable object at the boundary.
• Prefer inferred return types unless the framework produces unknown/any or the function is an explicit public API boundary.

const result = await Result.gen(async function* () {
  const user = yield* Result.await(fetchUser(input));
  const session = yield* createSession(user);
  return Result.ok(session);
});

if (Result.isError(result)) {
  return { error: true as const, message: result.error.message };
}

return { error: false as const, session: result.value };

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

1. Audit the target module for try, catch, .catch(...), throw, null, undefined, and status-flag error handling.
2. Define or update TaggedError classes before changing control flow.
3. Convert boundary functions first and change their signatures to Result<T, E> or Promise<Result<T, E>>.
4. Update immediate callers so they handle or propagate the new Result.
5. Where multiple Result-returning steps compose, use Result.gen or andThen.
6. Preserve error context by keeping cause, IDs, messages, and other structured fields.
7. 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
• serialization boundaries return plain objects, not Result or Error instances
• 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
• Returning Result or TaggedError instances from server functions or RPC handlers that require serialization
• Treating .match(...) as mandatory when a Result.isError / Result.isOk type guard is clearer

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.