# effect-atom-boundary
> Typed error boundaries for Effect Atom: catch an atom's failures by tag, typed by the atom
```ts
import { AtomErrorBoundary, createErrorBoundary } from "effect-atom-boundary";
```
## Claim
The claiming step of typed error boundaries. A boundary claims errors by
`_tag`; its hook takes a read's result, throws the claimed failures to the
boundary that claims them, and returns the result typed without them.
### `TypeId`
```ts
type TypeId = "~effect-atom-boundary/ErrorBoundary";
```
```ts
const TypeId: TypeId;
```
Literal type used as the boundary components' type identifier.
Type identifier for the boundary components, which carry the tags they
claim.
### `TagsOf`
```ts
type UnclaimedResult =
R extends AsyncResult.Success
? AsyncResult.Success>
: R extends AsyncResult.Failure
? [Unclaimed] extends [never]
? never
: AsyncResult.Failure>
: R extends AsyncResult.Initial
? AsyncResult.Initial>
: never;
```
An `AsyncResult`, or a union of them, typed without the errors whose
`_tag` is in `Tags`: a failure with no error left is gone from the union,
so a read whose failures are all claimed is typed as a success.
### `UseErrorBoundary`
```ts
interface UseErrorBoundary {
>(
result: R,
): UnclaimedResult;
}
```
A boundary's hook: takes the result a component read under the boundary,
throws the failures this boundary and the boundaries above it claim, and
returns the result typed without them.
**When to use**
Wrap each read under the boundary in it, such as
`useIssueBoundary(useAtomResult(issue, handle))`, to throw the claimed
failures to their boundaries and narrow the result to the rest.
**Details**
A failure whose error has a claimed `_tag` is thrown as the error itself,
so the nearest boundary that claims it catches it. A failure with no typed
error, a defect, is thrown too, to the error boundaries above. Any other
result is returned as it is. It takes any `AsyncResult`, from a read that
returns typed failures and suspends while a failed atom refreshes:
`raf-effect-atom`'s `useAtomResult`, or `useAtomSuspense` with
`includeFailure: true` and `suspendOnWaiting: true`.
**Gotchas**
It's a hook, and it throws outside its boundary. It throws a claimed
failure whether or not the atom is refreshing, so a read that returns the
old failure while a `reset` refreshes it, such as `useAtomValue`, throws
it to the boundary again, and the handler stays after the refresh. A read
that throws every failure itself, such as `useAtomSuspense` without
`includeFailure`, throws before the hook sees the result.
## Error boundary
Error boundaries typed by an atom's error. A boundary catches failures by
`_tag`, with a handler per tag typed by the error with that tag, so UI code
never imports an error class. `AtomErrorBoundary` guards one atom;
`createErrorBoundary` makes a shared boundary whose hook narrows the atoms
read under it.
### `CatchTagProps`
```ts
interface CatchTagProps {
readonly error: E;
/**
* Refreshes what failed and renders the children again: an
* `AtomErrorBoundary`'s atom, or every atom in the registry whose failure a
* `createErrorBoundary` boundary has a handler for.
*/
readonly reset: () => void;
}
```
Props for a `catchTags` handler: the caught error, and `reset`.
### `CatchTags`
```ts
type CatchTags = TagsOf> = {
readonly [Tag in Tags]?: (
props: CatchTagProps<
Extract<
E,
{
readonly _tag: Tag;
}
>
>,
) => React.ReactNode;
};
```
One optional handler per `_tag` of `E` (or per tag in `Tags`), each typed by
the error with that tag. A handler renders as a component, so it can call
hooks.
### `ErrorsOf`
```ts
type ErrorsOf =
Source extends AtomRpc.AtomRpcClient<
infer _Self,
infer _Id,
infer _Rpcs
>
? Source["query"] extends (
...args: ReadonlyArray
) => infer Query
? Query extends Atom.Atom<
AsyncResult.AsyncResult
>
? E
: never
: never
: Source extends AtomHttpApi.AtomHttpApiClient<
infer _Self,
infer _Id,
infer Groups
>
? EndpointErrors>
: Source extends Atom.Atom<
AsyncResult.AsyncResult
>
? E
: Source extends (
...args: ReadonlyArray
) => Atom.Atom>
? E
: never;
```
The error type of what a boundary's `errors` names: an `AtomRpc` client
(the errors of every procedure), an `AtomHttpApi` client (the errors of
every endpoint and its middleware), an atom, or an atom family.
### `AtomErrorBoundaryProps`
```ts
interface AtomErrorBoundaryProps {
/** The atom whose failures this boundary catches. */
readonly atom: Atom.Atom>;
/** A handler per `_tag` of the atom's error. */
readonly catchTags: NoInfer>;
readonly children?: React.ReactNode | undefined;
}
```
Props for an error boundary that catches one atom's failures by `_tag`.
### `AtomErrorBoundary`
```ts
const AtomErrorBoundary: (
props: AtomErrorBoundaryProps,
) => React.ReactNode;
```
Provides an error boundary for one atom that renders a handler per `_tag`
of the atom's error, typed by the error with that tag.
**When to use**
Use when a subtree reads one atom and some of its failures should render
in place of the subtree, without the reading component handling them.
**Details**
The reads under it throw the atom's failures, as `useAtomSuspense` does
without `includeFailure`. A failure whose tag has a handler renders that
handler; its `reset` refreshes the atom and renders the children again. A
new `atom` clears a caught failure.
React runs no error boundaries on the server, so during server rendering
it reads `atom` before its children, from the registry or its hydrated
state, and renders the handler for a failure that has settled. The
browser keeps that HTML while it hydrates, then renders the children,
which throw the failure to it again.
**Gotchas**
A failure without a handler, or an error that isn't the one the atom fails
with in the boundary's registry, such as one a read of another atom threw,
goes to the error boundaries above. Read with `suspendOnWaiting: true`, so
a read waits for the refresh `reset` starts instead of throwing the old
failure again. `reset` refreshes the atom in the registry
the boundary renders in, not in a `RegistryContext` provided under it. A
handler renders as a component: one written inline mounts again, losing its
state, each time the parent renders.
**Example** (Catching a missing issue)
```tsx
}}
>
function IssuePage(props: { readonly id: number }) {
const result = useAtomSuspense(issue(props.id), { suspendOnWaiting: true })
return
{result.value.title}
}
```
**See also**
- [`createErrorBoundary`](https://raf-effect-atom.katt.dev/docs/api-effect-atom-boundary.md#createErrorBoundary) for a shared boundary that narrows the reads under it
### `ErrorBoundaryComponent`
```ts
interface ErrorBoundaryComponent<
Tags extends string,
> extends Variance {
(props: {
readonly children?: React.ReactNode | undefined;
}): React.ReactNode;
readonly displayName: string;
}
```
A boundary component: renders the `catchTags` handler for the errors it
claims and throws the rest to the boundaries above it.
### `ErrorBoundary`
```ts
type ErrorBoundary = readonly [
Boundary: ErrorBoundaryComponent,
useBoundary: UseErrorBoundary,
];
```
A boundary component and its hook, which narrows the results read under
it, named freely by destructuring.
### `ErrorBoundaryOptions`
```ts
interface ErrorBoundaryOptions<
Source,
Tags extends TagsOf>,
ParentTags extends string,
> {
/** A handler per `_tag` this boundary claims. */
readonly catchTags: CatchTags, Tags>;
/**
* What the handlers' errors come from, for the types: an `AtomRpc` or
* `AtomHttpApi` client, an atom, or an atom family.
*/
readonly errors: Source;
/** Names it in messages and React DevTools: `"Auth"` is ``. */
readonly name: string;
/** The boundary it sits under, which must be mounted above it. */
readonly parent?: ErrorBoundaryComponent | undefined;
}
```
Options for `createErrorBoundary`.
### `createErrorBoundary`
```ts
const createErrorBoundary: <
Source,
Tags extends TagsOf>,
ParentTags extends string = never,
>(
options: ErrorBoundaryOptions,
) => ErrorBoundary;
```
Creates a shared error boundary that claims some errors by `_tag`, returned
as `[Boundary, useBoundary]`.
**When to use**
Use for failures that belong to the app rather than to the component that
read them, such as being signed out, so the components under the boundary
only handle what's left.
**Details**
A component under it wraps its read in the hook:
`useBoundary(useAtomResult(issue, handle))` throws the failures this
boundary or one above it claims to the nearest boundary that claims them,
and returns the result typed without them. `parent` is the boundary it
sits under; the claimed tags add up along the chain. `catchTags`' keys are tags
of `errors`' error type, so a misspelled tag is a type error and each
handler's `error` is typed.
A handler's `reset` refreshes every atom in the registry the boundary
renders in whose settled failure has a tag this boundary handles, not only
the one whose read threw:
one outage fails every atom on the page, and an atom that fails after the
handler replaced the children throws to no boundary.
React runs no error boundaries on the server, so during server rendering
it looks through the registry's atoms before rendering its children, and
renders its handler for a settled failure it catches. It only sees atoms
that already ran in that registry, such as the loaders' on TanStack
Start, or under `raf-effect-atom`'s `HydrationBoundary` on React Router.
A failure it doesn't see is thrown on the server and caught in the
browser.
**Gotchas**
A boundary matches `_tag` only: a failure with a claimed tag from any atom
under it is caught. During server rendering, that's any atom in the
registry, read under it or not. The boundary throws without its `parent`
mounted above it, and the hook throws outside its boundary. The hook needs
a read that returns its failures, such as `raf-effect-atom`'s
`useAtomResult`: `useAtomSuspense` without `includeFailure` throws every
failure before the hook sees it.
**Example** (A sign-in boundary)
```tsx
const [AuthBoundary, useAuthBoundary] = createErrorBoundary({
name: "Auth",
errors: Issues,
catchTags: { Unauthorized: ({ reset }) => }
})
function IssueTitle(props: { readonly issue: Handle }) {
const result = useAuthBoundary(useAtomResult(issue, props.issue))
// AsyncResult
}
```
**See also**
- [`AtomErrorBoundary`](https://raf-effect-atom.katt.dev/docs/api-effect-atom-boundary.md#AtomErrorBoundary) for a boundary that guards one atom