What is AsyncFlowState?

TL;DR

AsyncFlowState is a behavior orchestrator for async UI actions. It manages the idle → loading → success → error → retry lifecycle so you don't have to.

The Problem

Every modern application has async user actions: clicking buttons, submitting forms, saving data, deleting items, uploading files, or making payments.

Each of these actions follows the same lifecycle:

idle → loading → success → error → retry

But in real projects, this logic is re-written thousands of times. This leads to:

• Double submission bugs — user clicks twice before the first request completes
• Inconsistent loading UX — spinners everywhere, or nowhere
• Error handling chaos — forgotten catch blocks, messy state transitions
• Boilerplate fatigue — writing setIsLoading(true) on every function

The Solution

AsyncFlowState provides a standard, reusable engine to control async UI behavior correctly and consistently.

Feature	Manual	AsyncFlowState
Double submission prevention	Custom logic	Built-in
Retry with backoff	Tedious	One config
Optimistic UI	Complex	One line
Loading flash prevention	setTimeout hacks	minDuration
Error focus management	Manual	Automatic
Accessibility (ARIA)	Usually forgotten	Built-in

What AsyncFlowState is NOT

It's important to understand what AsyncFlowState does not replace:

• Not a data-fetching library — It doesn't replace React Query or SWR. Those manage cache, backgrounds, and stale data.
• Not a state manager — It doesn't replace Redux, Zustand, or Pinia. Those manage global application state.
• It's a behavior orchestrator — It manages how async actions behave in the UI.

Works alongside your stack

AsyncFlowState complements your existing tools. Use React Query for data fetching, Zustand for state, and AsyncFlowState for action behavior.

Package Ecosystem

AsyncFlowState is built as a modular monorepo:

Package	Description
@asyncflowstate/core	Framework-agnostic logic engine
@asyncflowstate/react	React hooks & accessibility helpers
@asyncflowstate/next	Next.js Server Actions & SSR integration
@asyncflowstate/vue	Vue 3 composables & provide/inject config
@asyncflowstate/svelte	Svelte stores with $ auto-subscription
@asyncflowstate/angular	Angular Observable/BehaviorSubject bindings
@asyncflowstate/solid	SolidJS fine-grained reactive signals

Key Features

• Global Config — Set default options app-wide with FlowProvider
• Declarative Chaining — Orchestrate workflows with triggerOn and signals
• Streaming Support — Native AsyncIterable / ReadableStream support
• Parallel & Sequential — Aggregate state across multiple flows
• Declarative Polling — Auto-refresh with conditional stop logic
• Smart Persistence — Resume interrupted operations across page refreshes
• Circuit Breaker — Prevent cascading failures with cross-session persistence
• Visual Debugger — Real-time Timeline/Gantt view of async activity
• Global Notifications — Centralized success/error handling for all flows