error-handling
/error-handling
Apply when handling errors or logging in components, composables, stores, server routes, tRPC routers, or Azure Functions handlers. Esposter's error handling — neverthrow Results, how each is chained and terminated, where a failure is logged or shown, and how errors are thrown and guarded on the server.
- Author
- Esposter ↗
- Repository
- Esposter ↗
- Licence
- Apache-2.0
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 15
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Apply when handling errors or logging in components, composables, stores, server routes, tRPC routers, or Azure Functions handlers. Esposter's error handling — neverthrow Results, how each is chained and terminated, where a failure is logged or shown, and how errors are thrown and guarded on the server.
Original author description
Apply when handling errors or logging in components, composables, stores, server routes, tRPC routers, or Azure Functions handlers. Esposter's error handling — neverthrow Results, how each is chained and terminated, where a failure is logged or shown, and how errors are thrown and guarded on the server.
How it works
- Settled — do not re-propose
- Deep dives
- try / catch and .then are banned
- Throwing — never new Error
- Core Utility
- Who alerts a tRPC rejection — references/alerting.md
- Finalizers — references/finalizers.md
- tRPC Backend Guards
- Client Reads/Writes — Don't Hand-Roll the Chain
SKILL.md preview
---
name: error-handling
description: Apply when handling errors or logging in components, composables, stores, server routes, tRPC routers, or Azure Functions handlers. Esposter's error handling — neverthrow Results, how each is chained and terminated, where a failure is logged or shown, and how errors are thrown and guarded on the server.
---
# Error Handling Conventions
**neverthrow** for explicit error handling. No silent swallows — every error is propagated, logged, or shown to the user.
## Settled — do not re-propose
- **A rule for an unterminated `Result`** — needs the value's type, and no type-aware rule of our own runs in either linter (the `oxlint` skill, "No type-aware rule of our own runs in either linter"); `pnpm ai:sweep:unterminated-results` reads the code after the bracket instead, so it stays a scan a sitting runs.
- **A rule for a fire-and-forget body that does not terminate** — whether the body has anything to terminate is a question about what it calls: a body whose whole work is an `executeMutation` with an `onError` is already done.
- **Reaching a template's inline alert from `error-alert/no-raw-error-alert`** — oxlint hands a JS plugin no Vue template.
- **Banning `console.warn` outright** — a notice with its own sentence is allowed; the handler slot is the swallow, and that half is the selector.
- **A base error class writing `this.name = new.target.name`** — the minifier mangles class names, so every client-side error would report a one-letter name; each class writes its name as a literal (`references/error-classes.md`).
## Deep dives
- `references/result-chains.md` — when shaping one chain: a fallback value, an alert, a mid-chain side effect, an `instanceof` branch on the error, or an abort/cancel.
- `references/alerting.md` — when wiring the error path of a tRPC call, or a background read that must not alert.
- `references/finalizers.md` — when a chain has to release something whichever way it resolves: `withFinalizer` or `withFinalizerAsync`, and when neither is the shape.
- `references/server-guards.md` — when a tRPC router or server route guards a nullable DB result, or attaches a `cause` to a `TRPCError`.
- `references/rollback-compensated-effects.md` — when a function has a fire-and-forget tail and a failure path a caller rolls back through.
- `references/ban-exceptions.md` — when a callback must become a rejection, a throw is being kept synchronous for a test, or a `.then`/`.catch`/`.finally` looks unavoidable.
- `references/azure-functions.md` — when writing or changing an Azure Functions handler, its dead-letter replay, or a handler that enumerates its own work from a query.
- `references/throwing.md` — when a code path throws, or a mock stubs a vendor method it never serves.
- `references/json-parsing.md` — when parsing JSON: user input, a stored blob, or a round trip carrying dates.
- `references/error-classes.md` — when writing or deduplicating an error class.
- `references/wrapping.md` — when deciding whether a step gets a `Result`, or whether a chain is terminated.
- `references/logging-sinks.md` — when writing an err handler or a notice: the sink per runtime, and where `console.warn` stays.
- `references/no-shared-import.md` — when handling a rejection in code that cannot import `@esposter/shared`.
- `references/unawaited-callbacks.md` — when writing a tick, a timer, a fire-and-forget hook or a gating promise executor.
## try / catch and .then are banned
`try` in any form and `.then`/`.catch`/`.finally` are `no-restricted-syntax` errors — `getResult`/`getResultAsync` and a chain, `withFinalizer`/`withFinalizerAsync` for cleanup; the two disable shapes and `Promise.try` are `references/ban-exceptions.md`.
## Throwing — never `new Error`
- **Never `new Error(...)`** — throw `InvalidOperationError(operation, name, message)` (`error-handling/no-bare-error`); the exceptions are `references/throwing.md`.
- **JSON is parsed by a schema or by `jsonDateParse`**, never a bare `JSON.parse` with a cast — which one a path takes is `references/json-parsing.md`.
## Core Utility
```ts
import { getResult, getResultAsync, noop, withFinalizer, withFinalizerAsync } from "@esposter/shared";
// getResult: sync fn → Result<T, Error>
// getResultAsync: async fn → ResultAsync<T, Error>
// noop: () => {} — the ok-handler in .match(noop, errorHandler)
// withFinalizer: sync fn + sync finalizer (e.g. restoring globals)
// withFinalizerAsync: async/sync fn + async/sync finalizer — for all async operations
```
- Always use `getResult(() => expr)` / `getResultAsync(() => asyncExpr)` — neverthrow's `fromThrowable`/`fromPromise` called directly is a `no-restricted-syntax` error, disabled only where `@esposter/shared` cannot be imported (`references/no-shared-import.md`).
- **Wrap only what can actually fail** — a pure step is called bare (`references/wrapping.md`).
- **Never leave a `Result` unterminated** — `.match` or `.unwrapOr`; no lint rule can see it, so it is a review catch and `pnpm ai:sweep:unterminated-results` a scan (`references/wrapping.md`).
- **`._unsafeUnwrap()` and `._unsafeUnwrapErr()` are banned, tests included** (`no-underscore-dangle`, which allows only Zod's `_def`). A test asserts the error with `.match(noop, (error) => error)`, and a step that must succeed, or a value it reads, takes `.match(onOk, (error) => { throw error; })`, so a failure surfaces as the error itself.
- `.isOk()` / `.isErr()` are banned (`no-restricted-syntax`) — branch with `.match(...)` instead so both branches are handled in one place. To rethrow/cleanup on failure, `throw` inside the err handler (works in sync and async handlers alike); to fall back, `.unwrapOr(fallback)`.
- **Never a silent swallow, and never `console.warn` as an err handler** — `.orTee(console.error)`, `context.error` in an Azure Function (`references/logging-sinks.md`).
- **`.match(noop, noop)` is a silent swallow** — a best-effort err handler names what was lost (`no-restricted-syntax`, `references/logging-sinks.md`).
- Never `void` a ResultAsync — always `await` (ResultAsync never rejects, so awaiting is safe).
- **Code that cannot import `@esposter/shared`** — a package a stranger installs alone, a config loaded before any package builds — handles a rejection without it (`references/no-shared-import.md`).
- Never end a fire-and-forget chain with `.orTee(handler)` alone — use `.match(noop, handler)`. Only the async form is caught: a `ResultAsync` is a thenable, so a bare one trips `typescript/no-floating-promises`, while a sync `getResult(...).orTee(...)` statement trips nothing and is a review catch.
- No-op ok handler: always `noop` — an inline `() => {}`, or a `() => undefined` whose match value is discarded, is a `no-restricted-syntax` error. Assigned, `() => undefined` is the value the ok arm produces and stays.
- **A callback nothing awaits terminates its own `Result` inside its own body**, and a promise executor's err handler also resolves its gate (`references/unawaited-callbacks.md`).
## Who alerts a tRPC rejection — `references/alerting.md`
`errorLink` alerts some rejection codes itself, so a caller that alerts them again stacks two identical toasts on one failure. **Wiring the error path of a tRPC call, or a background read that must not alert at all**, is that page.
## Finalizers — `references/finalizers.md`
`withFinalizer` and `withFinalizerAsync` run cleanup either way and then unwrap, so no terminal consumer is needed. **Releasing something a chain acquired, whichever way it resolves**, is that page.
## tRPC Backend Guards
Routers never repeat a null check: `requireEntity` and `requireMutation` from `server/trpc/guards/`, and a rejection asserted with the same family's error constructors (`references/server-guards.md`).
## Client Reads/Writes — Don't Hand-Roll the Chain
`useQuery` / `useMutation` already carry this chain for client reads/writes — see the `trpc` skill (`references/client-calls.md`) before writing your own around a `$trpc` call.
Files in this package (15)
- SKILL.md 8 KB
- references/alerting.md 3 KB
- references/azure-functions.md 4 KB
- references/ban-exceptions.md 3 KB
- references/error-classes.md 1 KB
- references/finalizers.md 3 KB
- references/json-parsing.md 1 KB
- references/logging-sinks.md 2 KB
- references/no-shared-import.md 2 KB
- references/result-chains.md 3 KB
- references/rollback-compensated-effects.md 2 KB
- references/server-guards.md 4 KB
- references/throwing.md 1 KB
- references/unawaited-callbacks.md 1 KB
- references/wrapping.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Esposter/Esposter | 100 | Apache-2.0 |
| ericrisco/rsc-harness | 100 | MIT |
| jcdendrite/claude-config | 100 | MIT |
| Sanit-mann/The-Insectoids | 100 | MIT |
| komluk/scaffolding | 100 | MIT |
| oborchers/fractional-cto | 100 | MIT |
| affaan-m/ECC | 100 | MIT |
| claude-dev-suite/claude-dev-suite | 100 | MIT |
| SHRIJANAGAIN/Nemo-Cli | 100 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 211f62e21319 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 1 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90trpc
Apply when writing tRPC routers, procedures, or router tests. Esposter's tRPC conventions — how a router, a procedure and its input are laid out, named and guarded, and how a client calls one. - 100logging-observability
Review code for correct logging and error handling patterns. Use when reviewing code that handles errors, uses logging functions, or captures exceptions. Enforces the error hierarchy where 4xx errors are never logged to Sentry and 5xx errors always are. Trigger phrases include… - 95go-error-handling
Use when Go error handling with error wrapping, sentinel errors, and custom error types. Use when handling errors in Go applications. - 95rust-error-handling
Use when Rust error handling with Result, Option, custom errors, thiserror, and anyhow. Use when handling errors in Rust applications. - 100error-contract
Standardized error response handling between frontend and backend. Covers error structure, status codes, and consistent error handling. USE WHEN: user asks about "error handling", "API errors", "error response format", "status codes", "error messages", "validation errors" DO NOT… - 90azure-table
Apply when reading or writing Azure Table Storage data (messages, moderation logs) in server code. Esposter's Azure Table Storage conventions, where the shared `@esposter/db` and `@esposter/azure` helpers own each table job and are never hand-rolled.