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:

    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:

    // 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:

    // 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:

  // 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:

  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:

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

• Never silently suppress errors — empty catch {} and unlogged error branches hide failures. With errore you rarely need catch at all, but at any boundary where an error is not propagated, always log it (see rule 20):

  const emailResult = await sendEmail(user.email).catch(
    (e) => new EmailError({ email: user.email, cause: e }),
  )
  if (emailResult instanceof Error) {
    console.warn('Failed to send email:', emailResult.message)
  }

Flat Control Flow

Keep block nesting minimal. Every level of indentation is cognitive load. The ideal function reads top to bottom at root level — checks and early returns, no else, no nested if, no try-catch.

Core pattern — call → check error → exit if error → continue at root. This is the single most important structural rule.

Go:

user, err := getUser(id)
if err != nil {
    return fmt.Errorf("get user: %w", err)
}
// user is valid here, at root level

posts, err := getPosts(user.ID)
if err != nil {
    return fmt.Errorf("get posts: %w", err)
}
// posts is valid here, at root level

return render(user, posts)

errore (identical structure):

const user = await getUser(id)
if (user instanceof Error) return user

const posts = await getPosts(user.id)
if (posts instanceof Error) return posts

return render(user, posts)

The reader scans the left edge of the function to follow the happy path — just like reading a Go function where if err != nil blocks are speed bumps you skip over.

No else — early return eliminates it: if (x) return 'A'; return 'B'

No else if chains — sequence of early-return if blocks:

function getStatus(code: number): string {
  if (code === 200) return 'ok'
  if (code === 404) return 'not found'
  if (code >= 500) return 'server error'
  return 'unknown'
}

Flatten nested if — invert conditions and return early. if (A) { if (B) { ... } } becomes if (!A) return; if (!B) return; .... The transformation rule: take the outermost if condition, negate it, return the failure case, then continue at root level. Repeat for each nested if. The happy path falls through to the end.

Avoid try-catch for control flow — try-catch is the worst offender for nesting. It forces a two-branch structure (try + catch) and hides which line threw. Convert exceptions to values at boundaries:

async function loadConfig(): Promise<Config> {
  const raw = await fs
    .readFile('config.json', 'utf-8')
    .catch((e) => new ConfigError({ reason: 'Read failed', cause: e }))
  if (raw instanceof Error) return { port: 3000 }

  const parsed = errore.try(
    () => JSON.parse(raw) as Config,
    (e) => new ConfigError({ reason: 'Invalid JSON', cause: e }),
  )
  if (parsed instanceof Error) return { port: 3000 }

  if (!parsed.port) return { port: 3000 }

  return parsed
}

Errors in branches, happy path at root — always handle errors inside if blocks, never success logic. Error handling goes in branches with early exits. Putting success logic inside if blocks inverts the flow and buries the happy path. If you see !(x instanceof Error) in a condition, you've inverted the pattern — flip it.

Keep the happy path at minimum indentation — the reader scans down the left edge to follow the main logic:

async function handleRequest(req: Request): Promise<AppError | Response> {
  const body = await parseBody(req)
  if (body instanceof Error) return body

  const user = await authenticate(req.headers)
  if (user instanceof Error) return user

  const permission = checkPermission(user, body.resource)
  if (permission instanceof Error) return permission

  const result = await execute(body.action, body.resource)
  if (result instanceof Error) return result

  return new Response(JSON.stringify(result), { status: 200 })
}

Same in loops — error in if + continue, happy path flat:

for (const id of ids) {
  const item = await fetchItem(id)
  if (item instanceof Error) {
    console.warn('Skipping', id, item.message)
    continue
  }
  await processItem(item)
  results.push(item)
}

Patterns