Agent Skills: better-result Migrate v2

better-result Migrate v2

Upgrade better-result error definitions from the v1 TaggedError API to the v2 factory-based API.

When to Use

Use this skill when the user:

• is upgrading better-result from v1 to v2
• has classes that extend TaggedError directly
• still uses TaggedError.match, TaggedError.matchPartial, or TaggedError.isTaggedError
• needs help rewriting constructor calls to the new object-based form

Reading Order

| Task | Files to Read | | --- | --- | | Plan and execute the migration | This file | | See concrete before/after transforms | references/migration-patterns.md | | Verify current library behavior | opensrc/ if present |

Quick API Diff

| v1 | v2 | | --- | --- | | class FooError extends TaggedError | class FooError extends TaggedError("FooError")<Props>() {} | | readonly _tag = "FooError" as const | _tag generated by the factory | | new FooError("123") | new FooError({ id: "123", message: "..." }) | | TaggedError.match(...) | matchError(...) | | TaggedError.matchPartial(...) | matchErrorPartial(...) | | TaggedError.isTaggedError(...) | isTaggedError(...) or TaggedError.is(...) |

Migration Workflow

1. Search for extends TaggedError across the codebase.
2. For each class, extract:
   • the _tag literal
   • constructor parameters and runtime properties
   • any computed message or validation logic
3. Rewrite the class to TaggedError("Tag")<Props>().
4. If constructor logic exists, keep a custom constructor that accepts an object and calls super({...}).
5. Update call sites from positional arguments to object arguments.
6. Replace static helper usage with the new standalone helpers.
7. Update imports.
8. Run tests and search again for old API remnants.

Transformation Rules

• Simple class: remove _tag, replace base class, move fields into the generic props object.
• Computed message: keep a custom constructor and derive message before super(...).
• Validation logic: preserve validation inside the custom constructor.
• Extra runtime fields: include them in the props object passed to super(...).
• Usages: migrate new FooError(a, b) to new FooError({ a, b, message }) or an equivalent derived-message constructor.

Read references/migration-patterns.md before editing if the target classes are non-trivial.

Search Checklist

Search for all of these before and after the migration:

• extends TaggedError
• readonly _tag =
• TaggedError.match
• TaggedError.matchPartial
• TaggedError.isTaggedError
• new call sites for migrated error classes

Completion Criteria

A migration is complete when:

• no classes directly extend the old v1 TaggedError base class
• migrated classes use TaggedError("...")<...>()
• call sites use the new constructor shape
• static helper calls are replaced with matchError, matchErrorPartial, or isTaggedError
• imports reflect the new helper functions
• tests pass with the upgraded package version

Common Pitfalls

• Dropping custom validation logic during the rewrite
• Forgetting to include message in the props shape
• Updating class declarations but not constructor call sites
• Replacing TaggedError.match but missing matchPartial or isTaggedError
• Migrating the type but not preserving extra runtime fields like timestamps or codes

In This Reference

| File | Purpose | | --- | --- | | references/migration-patterns.md | Detailed v1 → v2 before/after examples and import helper changes |

If opensrc/ exists, use it to confirm the exact v2 API exposed by the installed package.