dmmulroy/better-result

Overview

This skill migrates better-result TaggedError usages from the v1 class-based API to the v2 factory-based API. It provides a clear, repeatable transformation for error classes, constructor logic, static helper calls, and imports so your TypeScript codebase upgrades safely and predictably. The focus is on preserving runtime behavior (messages, validation, runtime props) while switching to the new constructor shape.

How this skill works

The skill scans code for classes that extend TaggedError and extracts the tag, constructor parameters, and any constructor logic (computed messages, validation, side effects). It rewrites simple classes to the factory form and rewrites complex classes to keep a custom constructor that accepts a single args object and forwards derived fields to super. It also updates usages (new FooError(...) → new FooError({...})) and replaces v1 static helpers with their v2 equivalents and imports.

When to use it

• Upgrading better-result from v1 to v2 in a TypeScript codebase
• You have TaggedError classes defined with custom constructors, validation, or runtime properties
• You need to update calls to TaggedError.match / matchPartial / isTaggedError
• You want automated, behavior-preserving migration for error types
• During code review or refactoring to ensure consistent v2 patterns

Best practices

• Search for all occurrences of "extends TaggedError" before migrating to catch union types and type aliases
• Preserve constructor validation and runtime side effects by converting positional params into a single args object with explicit types
• Include a message field in the v2 error type so existing message usage continues to work
• Update imports to include matchError, matchErrorPartial, isTaggedError when replacing static helpers
• Run tests that exercise error construction and pattern matching after migration

Example use cases

• Simple class with only fields: convert constructorless class to TaggedError("Tag")<...>() and change new calls to pass an object
• Class that computes message: keep a custom constructor that accepts args, computes message, and calls super with combined object
• Validation in constructor: move checks to the new constructor and throw the same errors when args are invalid
• Errors with runtime properties: compute and attach runtime props (like timestamp) inside the new constructor and include them in the type
• Replace TaggedError.match / matchPartial usages with matchError / matchErrorPartial and add required imports