Expand server targets and adopt better-result

Author: devalade

.claude/skills/better-result-adopt/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: better-result-adopt
+description: Adopt better-result in an existing TypeScript codebase. Use when replacing try/catch, Promise rejection handling, null sentinels, or thrown domain exceptions with typed Result workflows.
+references:
+  - references/tagged-errors.md
+---
+
+# 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. 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
+
+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`.
+
+## Core Transformations
+
+### Try/catch → `Result.try`
+
+```ts
+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`
+
+```ts
+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`
+
+```ts
+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`
+
+```ts
+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
+- 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.

.claude/skills/better-result-adopt/references/tagged-errors.md

@@ -0,0 +1,188 @@
+# TaggedError Patterns
+
+## Defining Errors
+
+### Simple Error (no computed message)
+
+```typescript
+import { TaggedError } from "better-result";
+
+class NotFoundError extends TaggedError("NotFoundError")<{
+  resource: string;
+  id: string;
+  message: string;
+}>() {}
+
+// Usage
+new NotFoundError({ resource: "User", id: "123", message: "User 123 not found" });
+```
+
+### Error with Computed Message
+
+Keep constructor for derived message:
+
+```typescript
+class NotFoundError extends TaggedError("NotFoundError")<{
+  resource: string;
+  id: string;
+  message: string;
+}>() {
+  constructor(args: { resource: string; id: string }) {
+    super({ ...args, message: `${args.resource} not found: ${args.id}` });
+  }
+}
+
+// Usage: new NotFoundError({ resource: "User", id: "123" })
+```
+
+### Error with Cause
+
+Wrap underlying exceptions:
+
+```typescript
+class DatabaseError extends TaggedError("DatabaseError")<{
+  operation: string;
+  message: string;
+  cause: unknown;
+}>() {
+  constructor(args: { operation: string; cause: unknown }) {
+    const msg = args.cause instanceof Error ? args.cause.message : String(args.cause);
+    super({ ...args, message: `DB ${args.operation} failed: ${msg}` });
+  }
+}
+
+// Usage in Result.tryPromise
+Result.tryPromise({
+  try: () => db.query(sql),
+  catch: (e) => new DatabaseError({ operation: "query", cause: e }),
+});
+```
+
+### Error with Validation/Runtime Props
+
+```typescript
+class RateLimitError extends TaggedError("RateLimitError")<{
+  retryAfter: number;
+  message: string;
+}>() {
+  constructor(args: { retryAfterMs: number }) {
+    super({
+      retryAfter: args.retryAfterMs,
+      message: `Rate limited, retry after ${args.retryAfterMs}ms`,
+    });
+  }
+}
+```
+
+## Error Unions
+
+Group related errors for function signatures:
+
+```typescript
+// Domain errors
+class NotFoundError extends TaggedError("NotFoundError")<{ id: string; message: string }>() {}
+class ValidationError extends TaggedError("ValidationError")<{ field: string; message: string }>() {}
+class AuthError extends TaggedError("AuthError")<{ reason: string; message: string }>() {}
+
+// Union type
+type AppError = NotFoundError | ValidationError | AuthError;
+
+// Function signature
+function processRequest(req: Request): Result<Response, AppError> { ... }
+```
+
+## Matching Errors
+
+### Exhaustive Match
+
+Compiler ensures all error types handled:
+
+```typescript
+import { matchError } from "better-result";
+
+const message = matchError(error, {
+  NotFoundError: (e) => `Missing: ${e.id}`,
+  ValidationError: (e) => `Invalid: ${e.field}`,
+  AuthError: (e) => `Unauthorized: ${e.reason}`,
+});
+```
+
+### Partial Match with Fallback
+
+Handle subset, catch-all for rest:
+
+```typescript
+import { matchErrorPartial } from "better-result";
+
+const message = matchErrorPartial(
+  error,
+  { NotFoundError: (e) => `Missing: ${e.id}` },
+  (e) => `Error: ${e.message}`, // fallback for ValidationError, AuthError
+);
+```
+
+### Type Guards
+
+```typescript
+import { isTaggedError, TaggedError } from "better-result";
+
+// Check any tagged error
+if (isTaggedError(value)) {
+  console.log(value._tag);
+}
+
+// Check specific error class
+if (NotFoundError.is(value)) {
+  console.log(value.id); // narrowed to NotFoundError
+}
+
+// Also available
+TaggedError.is(value); // same as isTaggedError
+```
+
+### In Result.match
+
+```typescript
+result.match({
+  ok: (value) => handleSuccess(value),
+  err: (e) =>
+    matchError(e, {
+      NotFoundError: (e) => handleNotFound(e),
+      ValidationError: (e) => handleValidation(e),
+    }),
+});
+```
+
+## Pipeable Style
+
+matchError/matchErrorPartial support data-last for pipelines:
+
+```typescript
+const handler = matchError({
+  NotFoundError: (e) => `Missing: ${e.id}`,
+  ValidationError: (e) => `Invalid: ${e.field}`,
+});
+pipe(error, handler);
+```
+
+## Converting Existing Errors
+
+```typescript
+// FROM: class hierarchy
+class NotFoundError extends AppError {
+  constructor(public id: string) {
+    super(`Not found: ${id}`);
+  }
+}
+// TO: TaggedError
+class NotFoundError extends TaggedError("NotFoundError")<{ id: string; message: string }>() {
+  constructor(args: { id: string }) {
+    super({ ...args, message: `Not found: ${args.id}` });
+  }
+}
+
+// FROM: string/generic errors
+throw "User not found";
+// TO: typed Result
+return Result.err(new NotFoundError({ id, message: "User not found" }));
+```