errore

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.

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:

    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: