# ts-extended-errors

> A zero-dependency error model for TypeScript applications that use native
> exceptions but need typed context, cause-chain inspection, and reliable JSON
> round trips. `ExtendedError` is a base class
> that keeps `name`, `code`, `context` and `stack` correct through subclassing;
> `defineError` declares such a class in one line and builds taxonomies through
> its `base` option; five helpers search the `cause` chain; `serializeError` and
> `deserializeError` take an error through JSON and rebuild it as the classes it
> was. Every function accepts `unknown`, because a `catch` binding is `unknown`
> and JavaScript permits throwing anything. No runtime dependencies and no
> Node.js APIs, so it runs in browsers and workers as well as on Node >= 20.19.
> Ships ESM and CommonJS with type declarations. Published to npm. MIT.

Every link below is raw markdown. The human page is the same URL without the
`.md` suffix.

Everything inlined in one fetch: https://rxova.org/packages/ts-extended-errors/llms-full.txt

## Install

    npm install ts-extended-errors

No peer dependencies. The package also ships its own `llms.txt` inside the
tarball, so after an install it can be read from
`node_modules/ts-extended-errors/llms.txt` with no network access.

## If you are writing calling code

Five facts prevent most of the mistakes:

1. The second constructor argument is an options object, so context goes in
   `{ context: { userId } }` rather than being passed directly.
2. `defineError` returns a new class on every call, so call it once at module
   scope and export the result — two calls produce two classes and
   `instanceof` between them is false.
3. `deserializeError` chooses a class by the payload's `name`, from the
   built-ins plus whatever is passed in `classes`. Without `classes` your own
   classes come back as a plain `ExtendedError` carrying the right name.
4. In a `catch`, the binding is `unknown`. Use `toError`, `isExtendedError` or
   `findCauseOf` rather than reading `.code` off it.
5. “Typed” describes an error after narrowing. TypeScript does not include
   thrown errors in a function signature; use a union or `Result` when each
   caller must see an expected failure in the return type.

## About

- [ts-extended-errors](https://rxova.org/packages/ts-extended-errors/index.md): A zero-dependency error model for TypeScript applications that use native exceptions but need typed context, cause-chain inspection, and reliable JSON round trips.

## Learn

- [Getting started](https://rxova.org/packages/ts-extended-errors/learn/getting-started.md): Install the package, declare an error class, throw it with context, and catch it — the shortest path from nothing to a typed error.
- [Why this exists](https://rxova.org/packages/ts-extended-errors/learn/why.md): Four things that go wrong when you subclass Error in TypeScript, and what each one costs when the error reaches a log or a queue.

## Guides

- [Cause chains](https://rxova.org/packages/ts-extended-errors/guides/cause-chains.md): Wrapping an error instead of replacing it, and the five helpers that search the resulting chain — causeChain, rootCause, findCause, findCauseOf and hasCauseOf.
- [Defining errors](https://rxova.org/packages/ts-extended-errors/guides/defining-errors.md): defineError and ExtendedError — codes, taxonomies built with base, messages generated from context, and which of the two to reach for.
- [Serialization](https://rxova.org/packages/ts-extended-errors/guides/serialization.md): serializeError and deserializeError — the JSON round trip that rebuilds the original classes, its options, and what to include in a log versus a response.
- [Working with unknown values](https://rxova.org/packages/ts-extended-errors/guides/unknown-values.md): A catch binding is unknown and JavaScript permits throwing anything — toError, isErrorLike, isExtendedError and describeValue are the four narrowings.

## Reference

- [API reference](https://rxova.org/packages/ts-extended-errors/reference/api.md): Every export of ts-extended-errors, with its signature and behaviour — classes, the factory, the chain helpers, and the serialization pair.
- [Types](https://rxova.org/packages/ts-extended-errors/reference/types.md): The exported TypeScript types — context, options, the serialized shape, and the constructor interfaces defineError returns.

## Under the hood

- [Limits and trust](https://rxova.org/packages/ts-extended-errors/under-the-hood/limits.md): The depth and width limits on serialization, how cycles terminate, what happens across realms, and what deserializing an untrusted payload actually does.
- [Subclassing Error](https://rxova.org/packages/ts-extended-errors/under-the-hood/subclassing.md): The four things that break when you extend Error in TypeScript, and the four lines in ExtendedError's constructor that fix each one.