errore

What this skill does

# errore

Go-style error handling for TypeScript. Functions return errors instead of throwing them — but instead of Go's two-value tuple (`val, err`), you return a single `Error | T` union. Instead of checking `err != nil`, you check `instanceof Error`. TypeScript narrows the type automatically. No wrapper types, no Result monads, just unions and `instanceof`.

```ts
const user = await getUser(id)
if (user instanceof Error) return user // early return, like Go
console.log(user.name) // TypeScript knows: User
```

## Rules

1. Always `import * as errore from 'errore'` — namespace import, never destructure
2. Never throw for expected failures — return errors as values
3. Never return `unknown | Error` — the union collapses to `unknown`, breaks narrowing. Common trap: `res.json()` returns `unknown`, so `return await res.json()` makes the return type `MyError | unknown` → `unknown`. Fix: cast with `as` → `return (await res.json()) as User`
4. Avoid `try-catch` for control flow — use `.catch()` for async boundaries, `errore.try` for sync boundaries
5. Use `createTaggedError` for domain errors — gives you `_tag`, typed properties, `$variable` interpolation, `cause`, `findCause`, `toJSON`, and fingerprinting
6. Let TypeScript infer return types — only add explicit annotations when they improve readability (complex unions, public APIs) or when inference produces a wider type than intended
7. Use `cause` to wrap errors — `new MyError({ ..., cause: originalError })`
8. Use `| null` for optional values, not `| undefined` — three-way narrowing: `instanceof Error`, `=== null`, then value
9. Use `const` + expressions, never `let` + try-catch — ternaries, IIFEs, `instanceof Error`
10. Always handle errors inside `if` branches with early exits, keep the happy path at root — like Go's `if err != nil { return err }`, check the error, exit (return/continue/break), and continue the success path at the top indentation level. This makes the happy path readable top-to-bottom with minimal nesting
11. Always include `Error` handler in `matchError` — required fallback for plain Error instances
12. Use `.catch()` for async boundaries, `errore.try` for sync boundaries — only at the lowest call stack level where you interact with uncontrolled dependencies (third-party libs, `JSON.parse`, `fetch`, file I/O). Your own code should return errors as values, not throw.
13. Always wrap `.catch()` in a tagged domain error — `.catch((e) => new MyError({ cause: e }))`. The `.catch()` callback receives `any`, but wrapping in a typed error gives the union a concrete type. Never use `.catch((e) => e as Error)` — always wrap.
14. Always pass `cause` in `.catch()` callbacks — `.catch((e) => new MyError({ cause: e }))`, never `.catch(() => new MyError())`. Without `cause`, the original error is lost and `isAbortError` can't walk the chain to detect aborts. The `cause` preserves the full error chain for debugging and abort detection.
15. Always prefer `errore.try` over `errore.tryFn` — they are the same function, but `errore.try` is the canonical name
16. Use `errore.isAbortError` to detect abort errors — never check `error.name === 'AbortError'` manually, because tagged abort errors have their tag as `.name`
17. Custom abort errors MUST extend `errore.AbortError` — so `isAbortError` detects them in the cause chain even when wrapped by `.catch()`
18. Keep abort checks flat — check `isAbortError(result)` first as its own early return, then `result instanceof Error` as a separate early return. Never nest `isAbortError` inside `instanceof Error`:

    ```ts
    const result = await fetchData({ signal }).catch(
      (e) => new FetchError({ cause: e }),
    )
    if (errore.isAbortError(result)) return 'Request timed out'
    if (result instanceof Error) return `Failed: ${result.message}`
    ```

19. Don't reassign after error early returns — TypeScript narrows the original variable automatically after `instanceof Error` checks return. A `const narrowed = result` alias is redundant:

    ```ts
    const result = await fetch(url).catch((e) => new FetchError({ cause: e }))
    if (result instanceof Error) return `Failed: ${result.message}`
    await result.json() // TS knows result is Response here
    ```

20. Always write `instanceof Error` early returns on one line — no `{` block, no extra lines. `if (x instanceof Error) return x` keeps the happy path readable and reduces visual noise. Only use a block when the branch has more than one statement:

    ```ts
    // good — one line, no block
    if (result instanceof Error) return result
    if (user instanceof Error) return user

    // bad — block for a single return adds noise
    if (result instanceof Error) {
      return result
    }
    ```

21. Always log errors that are not propagated — when an error branch doesn't `return` or `throw` the error (i.e. the error is intentionally swallowed), add a `console.warn` or `console.error` so failures are visible during debugging. Silent error swallowing makes bugs invisible:

    ```ts
    // BAD: error silently ignored — if sync fails you'll never know
    const result = await syncToCloud(data)
    if (result instanceof Error) {
      // nothing here — silent failure
    }

    // GOOD: log before continuing — error is visible in logs
    const result = await syncToCloud(data)
    if (result instanceof Error) {
      console.warn('Cloud sync failed:', result.message)
    }
    ```

    > Propagated errors (`return error`) don't need logging — the caller handles them. But errors you choose to ignore must leave a trace. This applies to loops with `continue`, fallback branches, and any path where the error is intentionally dropped.

## TypeScript Rules

- **Object args over positional** — `({id, retries})` not `(id, retries)` for functions with 2+ params
- **Expressions over statements** — use IIFEs, ternaries, `.map`/`.filter` instead of `let` + mutation
- **Early returns** — check and return at top, don't nest. Combine conditions: `if (a && b)` not `if (a) { if (b) }`
- **No `any`** — search for proper types, use `as unknown as T` only as last resort
- **`cause` not template strings** — `new Error("msg", { cause: e })` not ``new Error(`msg ${e}`)``
- **No uninitialized `let`** — use IIFE with returns instead of `let x; if (...) { x = ... }`
- **Type empty arrays** — `const items: string[] = []` not `const items = []`
- **Module imports for node builtins** — `import fs from 'node:fs'` then `fs.readFileSync(...)`, not named imports
- **Let TypeScript infer return types** — don't annotate return types by default. TypeScript infers them from the code and the inferred type is always correct. Only add an explicit return type when it genuinely improves readability (complex unions, public API boundaries) or when inference produces a wider type than intended:

  ```ts
  // let inference do its job
  function getUser(id: string) {
    const user = await db.find(id)
    if (!user) return new NotFoundError({ id })
    return user
  }

  // explicit annotation when it adds clarity on a complex public API
  function processRequest(
    req: Request,
  ): Promise<ValidationError | AuthError | DbError | null | Response> {
    // ...
  }
  ```

- **`.filter(isTruthy)` not `.filter(Boolean)`** — `Boolean` doesn't narrow types, so `(T | null)[]` stays `(T | null)[]` after filtering. Use a type guard:

  ```ts
  function isTruthy<T>(value: T): value is NonNullable<T> {
    return Boolean(value)
  }
  const items = results.filter(isTruthy)
  ```

- **`controller.abort()` must use typed errors** — `abort(reason)` throws `reason` as-is. MUST pass a tagged error extending `errore.AbortError`, NEVER `new Error()` or a string — otherwise `isAbortError` can't detect it in the cause chain:

  ```ts
  class TimeoutError extends errore.createTaggedError({
    name: 'TimeoutError',
    message: 'Request timed out for $operation',
    extends: errore.AbortError,
  }) {}
  controller.abort(new TimeoutError({ operation: 'fetch' }))