We should settle on a general direction for package structure and naming. This issue is not for discussing package details, but to discuss where to cut them up or merge them. Refer to packages/react-async/src for an overview of what's currently there. The goal is to offer a way to later add new features without affecting the existing functionality, by using separate packages.

Current idea:

• @async-library/core Core features, library agnostic: reducer, status, globalScope
• @async-library/devtools Chrome DevTools extension, supports all libraries
• @async-library/react-async-component React Component with Render Props API (<Async>) and its helper subcomponents (aka classic React Async)
• @async-library/react-async-hook React Hook (useAsync) and standalone helpers
• @async-library/react-fetch-hook React Hook (useFetch), depends on react-async-hook
• @async-library/vue-async-composition Vue.js Composition, following the Vue Composition API

Questions:

• How do we deal with propTypes? Do they go in core somehow? Can we generate them from TypeScript?

Let's collect and decide on the uses cases and features we want to support with Async Library, either directly or through a separate package. They are grouped, but in no particular order. Core would be @async-library/core, Integrations would be e.g. @async-library/react-hook. User provided would be through passing a prop/option. Plugins would be separate packages.

⚙️ Core

• Handle race conditions in subsequent requests.
• Metadata to show started time / last fetched time / request duration and keep track of number of runs.
• Manual (re)start.
• Optimistic updates (set data to expected value before the promise settles).
• AbortController integration (create one on every start and pass it along).
• Run a function when the promise resolves or rejects (and the ability to define it just-in-time).
• Ability to append new data to the old data (e.g. infinite scroll).
• Global access to all instances, including their state and actions, and the option to (temporarily) override them from DevTools.
• Gracefully handle infinite loops.
• Support subscriptions (e.g. GraphQL, websockets, messagechannels, generators).
• Pass arguments when invoking the async function manually (i.e. run(arg1, arg2), to support dynamic requests).
• Allow polling for updates, alongside performing actions (i.e. enable reload of promiseFn while also using deferFn).
• Support resolving data synchronously, e.g. from a cache, to avoid rerendering.
• Allow custom concurrency strategies (e.g. ignore new fetches, cancel old fetches, queue new fetches, fetch all in parallel, fetch once and never again)
• Allow things like circuit breakers and retry with exponential backoff

🧩 Integration

• Await any promise / thenable or async function and render the various UI states accordingly.
• Cancellation on unmount / destroy.
• Optional automatic start on mount.
• Automatic restart on certain prop changes.
• Support both automatic start and manual start at the same time, e.g. to populate a form with existing data and submit it later.
• Control over when a certain state is rendered (e.g. persist old data while new data is loading).
• Server-side rendering and rehydration.
• Allow async functions to depend on eachother (e.g. one's result is used to construct/start another).
• Support stale-while-revalidate, like SWR.

🔌 User provided / plugin

• Allow debouncing / throttling / caching / retries.
• Automatic JSON (de)serialization.

@async-library/core will contain all the core functionality that Async Library provides. It will generally not be used directly, but be a dependency of @async-library/react-async-hook for example. It should have feature parity with react-async and react-async-hook (outside of React specifics).

This description is updated as the discussion unfolds.

Features

• Standardized API (both in and out)
• Full state management for a single instance in local state
• No global store (otherwise you might as well use Redux Saga)
• Cancellation (with AbortController)
• DevTools integration (e.g. allow replaying a promiseFn)

To discuss:

• Should we use generators instead of promises?
• Should we use an internal state machine?
• Should we allow users to create their own async state machine?

Core API

States:

• initial nothing happened yet (or reinitialize was invoked)
• pending promise is loading or paused
• fulfilled promise was fulfilled with data
• rejected promise was rejected with error

Config options:

• fn async function that will be invoked on run
• runOnInit flag to enable running on init (mount) [do we really need this?]
• initialValue initialize value to a predefined value or error [should this be separate values for data and error?]

Callback options:

• onInit when first initialized (i.e. mount)
• onData when promise has fulfilled with data
• onError when promise has rejected with error
• onAbort when promise has aborted
• onDestroy when destroying the instance (i.e. unmount)

Actions:

• run invoke fn
• abort cancel a pending promise and invoke AbortController::abort
• reinitialize abort and reset state to initial

Metadata:

• runCount number of times run was invoked (automatically or manually)
• startedAt when the last run was invoked
• finishedAt when the last promise was fulfilled or rejected

This API deviates quite a bit from React Async. Notably:

• promiseFn and deferFn are combined into fn
• promise is dropped as an option. You can just pass () => promise instead.