⏳ react-async-flow-z

LIVE DEMO

react-async-flow-z is a deterministic async flow & boundary engine for React and application logic.

Async is not just loading — it is state, retry, cancellation, and orchestration.

Why react-async-flow-z

• Async Boundary (pending / success / error / retry / cancel)
• AbortController built-in (no stale async)
• Deterministic retry strategy
• Event-driven async flow (via eventbus-z)
• Local state + optional global orchestration
• Framework-agnostic core
• React bindings provided, not required

Mental Model

Async Task
   ↓
AsyncBoundary (state machine)
   ↓
AsyncFlow (orchestration / signals)
   ↓
View / Sequence / Side effects

Installation

npm install react-async-flow-z eventbus-z

eventbus-z is used internally for async flow orchestration and observability.

Basic Usage

Create Async Boundary

import { createAsyncBoundary } from "react-async-flow-z";

const boundary = createAsyncBoundary({
  key: "load-user",
  retry: { max: 3 }
});

Run async task with abort support

const ctx = boundary.createContext();

boundary.pending();
try {
  const res = await fetch("/api/user", { signal: ctx.signal });
  boundary.success();
} catch (e) {
  boundary.fail(e);
}

React Integration

const boundary = useAsyncBoundary({ key: "profile" });

<AsyncView
  boundary={boundary}
  fallback={<Spinner />}
  errorFallback={(err, retry) => (
    <ErrorView onRetry={retry} />
  )}
>
  <Profile />
</AsyncView>

useAsyncBoundary is a React hook wrapper around createAsyncBoundary that handles lifecycle binding automatically.

AsyncFlow (Global Orchestration)

// Global async event orchestration
const flow = new AsyncFlow();

flow.when("profile", "success", () => {
  console.log("Profile loaded");
});

AbortController

const boundary = createAsyncBoundary()

async function loadUser() {
  const { signal } = boundary.createContext()
  boundary.pending()

  try {
    const res = await fetch("/api/user", { signal })
    boundary.success()
  } catch (e) {
    boundary.fail(e)
  }
}

AsyncSequence

createAsyncSequence([
  { name: "step1", run: fetchA, boundary: a },
  { name: "step2", run: fetchB, boundary: b }
]).run();

Each step can have its own AsyncBoundary for independent retry & cancel.

State

| State | Description | | ------- | ---------------------- | | idle | Initial state | | pending | Async task running | | success | Completed successfully | | error | Failed | | retry | Retrying | | cancel | Aborted | | reset | Reset to idle |

AsyncFlow (Global Event Bus)

AsyncFlow uses a global event bus.

Recommended usage:

• Cross-boundary observation
• Debugging & devtools
• Application-level orchestration

Avoid:

• High-frequency UI state updates
• Per-component local state

Design philosophy

• Explicit over implicit
• Async as state machine
• Abort-first mindset
• No hidden global state
• Framework adapters are optional

What this library is NOT

• ❌ Not a data-fetching cache
• ❌ Not a state manager
• ❌ Not react-query replacement
• ❌ Not Rx stream library

License

MIT