CipherBoundary

Make React async predictable. End of chaos.

A deterministic execution layer for handling async logic and errors in React applications.

---

Why this exists

React applications today have fragmented async behavior:

• scattered try/catch
• inconsistent error handling
• no unified async state model
• race conditions and stale updates
• different patterns across fetch, actions, effects

react-async-boundary solves this by introducing a single execution layer for all async logic in React.

---

Core Idea

Instead of handling async logic everywhere differently, you run everything through one deterministic system:

run(asyncFunction)

That’s it.

---

Features (v1)

• Unified async execution layer
• Standardized error model
• Predictable async state machine
• Cancellation support (AbortController)
• Simple retry mechanism
• React hook-based API

---

Installation

npm install react-async-boundary

or

pnpm add react-async-boundary

---

Quick Start

import { useAsync } from "react-async-boundary"

function App() {
  const { run, state, error, data } = useAsync()

  const handleClick = async () => {
    await run(() => fetch("/api/user").then(r => r.json()))
  }

  return (
    <div>
      <button onClick={handleClick}>Load</button>

      {state.status === "running" && <p>Loading...</p>}
      {state.status === "error" && <p>{error.message}</p>}
      {state.status === "success" && <pre>{JSON.stringify(data)}</pre>}
    </div>
  )
}

---

Async State Model

type AsyncState =
  | { status: "idle" }
  | { status: "running" }
  | { status: "success"; data: any }
  | { status: "error"; error: any }
  | { status: "retrying"; attempt: number }
  | { status: "cancelled" }

---

Error Model

type AsyncError = {
  type: "network" | "validation" | "auth" | "runtime" | "unknown"
  message: string
  retryable: boolean
  raw?: unknown
}

---

API

useAsync

const { run, state, error, data, reset } = useAsync()

run

await run(() => apiCall(), {
  retry: 2
})

---

AsyncBoundary

<AsyncBoundary fallback={ErrorFallback}>
  <App />
</AsyncBoundary>

---

Philosophy

• Deterministic async execution
• Unified error handling
• Minimal API surface

---

What this is NOT

• Not React Query replacement
• Not caching library
• Not data layer

---

License

MIT