Package @reatom/async

@reatom/async

Interfaces

AsyncDataExt

Defined in: async/withAsyncData.ts:21

Extension interface added by withAsyncData to atoms or actions that return promises. Extends AsyncExt with data storage and abort capabilities for managing async data fetching.

Extends

• AsyncExt<Params, Payload, Error>.AbortExt

Extended by

• RouteLoader

Type Parameters

Params

Params extends any[] = any[]

The parameter types of the original atom or action

Payload

Payload = any

The resolved value type of the promise

State

State = any

The type of the stored data

InitState

InitState = State

Error

Error = any

The type of errors that can be caught

Properties

abort

abort: Action<[any]>

Defined in: extensions/withAbort.ts:11

Inherited from

AbortExt.abort

data

data: Atom<State | InitState, [State | InitState]> & object

Defined in: async/withAsyncData.ts:33

Atom that stores the fetched data Updated automatically when the async operation completes successfully

Type Declaration

reset

reset: Action<[], InitState>

error

error: Atom<Error | undefined>

Defined in: async/withAsync.ts:90

Atom containing the most recent error or undefined if no error has occurred

Inherited from

AsyncExt.error

onFulfill

onFulfill: Action<[Payload, Params], { params: Params; payload: Payload; }>

Defined in: async/withAsync.ts:54

Action that is called when the promise resolves successfully

Param

The resolved value from the promise

Param

The original parameters passed to the atom/action

Returns

An object containing the payload and parameters

Inherited from

AsyncExt.onFulfill

onReject

onReject: Action<[Error, Params], { error: Error; params: Params; }>

Defined in: async/withAsync.ts:66

Action that is called when the promise rejects with an error

Param

The error thrown by the promise

Param

The original parameters passed to the atom/action

Returns

An object containing the error and parameters

Inherited from

AsyncExt.onReject

onSettle

onSettle: Action<[{ params: Params; payload: Payload; } | { error: Error; params: Params; }], { params: Params; payload: Payload; } | { error: Error; params: Params; }>

Defined in: async/withAsync.ts:77

Action called after either successful resolution or rejection

Param

Either a payload+params object or an error+params object

Returns

The same result object that was passed in

Inherited from

AsyncExt.onSettle

pending

pending: Computed<number>

Defined in: async/withAsync.ts:87

Computed atom tracking how many async operations are currently pending

Returns

Number of pending operations (0 when none are pending)

Inherited from

AsyncExt.pending

ready

ready: Computed<boolean>

Defined in: async/withAsync.ts:45

Computed atom that indicates when no async operations are pending

Returns

Boolean indicating if all operations have completed (true) or some are still pending (false)

Inherited from

AsyncExt.ready

reset

reset: Action<[], void>

Defined in: async/withAsyncData.ts:48

Action that resets the async data atom by clearing its dependencies and resetting the data atom to its initial state. This is useful for invalidating cached data and forcing a re-fetch on next access.

Note: This action does not re-trigger the async operation automatically. Use retry if you want to reset and immediately re-fetch.

retry

retry: Action<[], Promise<Payload>>

Defined in: async/withAsyncData.ts:57

Action that retries the async operation by resetting dependencies and re-evaluating the computed function. This is useful for manually refreshing data or recovering from errors.

Returns

The promise from the re-triggered async operation

status

status: AsyncStatusAtom<State, InitState>

Defined in: async/withAsyncData.ts:38

Status atom that includes the data property

Overrides

AsyncExt.status

---

AsyncDataOptions

Defined in: async/withAsyncData.ts:70

Configuration options for the withAsyncData extension Extends AsyncOptions with options specific to data management

Extends

• AsyncOptions<Err, EmptyErr>

Type Parameters

State

State = any

The type of data to store

Params

Params extends any[] = any[]

The parameter types of the original atom or action

Payload

Payload = any

The resolved value type of the promise

Err

Err = Error

The type of errors after parsing

EmptyErr

EmptyErr = undefined

The type of the empty error state

Properties

emptyError?

optional emptyError: EmptyErr

Defined in: async/withAsync.ts:118

Initial/reset value for the error atom

Inherited from

AsyncOptions.emptyError

initState?

optional initState: State

Defined in: async/withAsyncData.ts:78

Initial value for the data atom

mapPayload()?

optional mapPayload: (payload, params, state) => State

Defined in: async/withAsyncData.ts:88

Function to transform the successful payload into the data state

Parameters

payload

Payload

The resolved value from the promise

params

Params

The original parameters passed to the atom/action

state

State

The current state of the data atom

Returns

State

The new state for the data atom

parseError()?

optional parseError: (error) => Err

Defined in: async/withAsync.ts:115

Function to transform raw errors into a specific error type

Parameters

error

unknown

The caught error of unknown type

Returns

Err

A properly typed error object

Inherited from

AsyncOptions.parseError

resetError?

optional resetError: "onFulfill" | "onCall" | null

Defined in: async/withAsync.ts:129

When to reset the error state

• ‘onCall’: Reset error when the async operation starts (default)
• ‘onFulfill’: Reset error only when the operation succeeds
• Null: Never automatically reset errors

Default

'onCall'

Inherited from

AsyncOptions.resetError

status?

optional status: boolean

Defined in: async/withAsync.ts:138

Whether to enable the status atom for detailed async operation tracking. When enabled, provides access to lifecycle state, timing information, and retry functionality through the status property.

Default

false

Inherited from

AsyncOptions.status

---

AsyncExt

Defined in: async/withAsync.ts:34

Extension interface added by withAsync to atoms or actions that return promises. Provides utilities for tracking async state, handling errors, and responding to async events.

Extended by

• AsyncDataExt

Type Parameters

Params

Params extends any[] = any[]

The parameter types of the original atom or action

Payload

Payload = any

The resolved value type of the promise

Error

Error = any

The type of errors that can be caught

Properties

error

error: Atom<Error | undefined>

Defined in: async/withAsync.ts:90

Atom containing the most recent error or undefined if no error has occurred

onFulfill

onFulfill: Action<[Payload, Params], { params: Params; payload: Payload; }>

Defined in: async/withAsync.ts:54

Action that is called when the promise resolves successfully

Param

The resolved value from the promise

Param

The original parameters passed to the atom/action

Returns

An object containing the payload and parameters

onReject

onReject: Action<[Error, Params], { error: Error; params: Params; }>

Defined in: async/withAsync.ts:66

Action that is called when the promise rejects with an error

Param

The error thrown by the promise

Param

The original parameters passed to the atom/action

Returns

An object containing the error and parameters

onSettle

onSettle: Action<[{ params: Params; payload: Payload; } | { error: Error; params: Params; }], { params: Params; payload: Payload; } | { error: Error; params: Params; }>

Defined in: async/withAsync.ts:77

Action called after either successful resolution or rejection

Param

Either a payload+params object or an error+params object

Returns

The same result object that was passed in

pending

pending: Computed<number>

Defined in: async/withAsync.ts:87

Computed atom tracking how many async operations are currently pending

Returns

Number of pending operations (0 when none are pending)

ready

ready: Computed<boolean>

Defined in: async/withAsync.ts:45

Computed atom that indicates when no async operations are pending

Returns

Boolean indicating if all operations have completed (true) or some are still pending (false)

status

status: AsyncStatusAtom<any, any>

Defined in: async/withAsync.ts:99

Atom that tracks the current status of async operations including lifecycle state, timing information, and retry functionality. Must be explicitly enabled via the status option in withAsync configuration.

Throws

When accessed without being enabled in options

Type Aliases

AsyncOptions

AsyncOptions<Err, EmptyErr> = object

Defined in: async/withAsync.ts:108

Configuration options for the withAsync extension

Extended by

• AsyncDataOptions

Type Parameters

Err

Err = Error

The type of errors after parsing

EmptyErr

EmptyErr = undefined

The type of the empty error state (default: undefined)

Properties

emptyError?

optional emptyError: EmptyErr

Defined in: async/withAsync.ts:118

Initial/reset value for the error atom

parseError()?

optional parseError: (error) => Err

Defined in: async/withAsync.ts:115

Function to transform raw errors into a specific error type

Parameters

error

unknown

The caught error of unknown type

Returns

Err

A properly typed error object

resetError?

optional resetError: null | "onCall" | "onFulfill"

Defined in: async/withAsync.ts:129

When to reset the error state

• ‘onCall’: Reset error when the async operation starts (default)
• ‘onFulfill’: Reset error only when the operation succeeds
• Null: Never automatically reset errors

Default

'onCall'

status?

optional status: boolean

Defined in: async/withAsync.ts:138

Whether to enable the status atom for detailed async operation tracking. When enabled, provides access to lifecycle state, timing information, and retry functionality through the status property.

Default

false

Variables

withAsync()

withAsync: <Err, EmptyErr>(options?) => <T>(target) => T extends AtomLike<any, Params, Promise<Payload>> ? T<T> & AsyncExt<Params, Payload, Err | EmptyErr> : never

Defined in: async/withAsync.ts:165

Extension that adds async state tracking to atoms or actions that return promises. Manages pending state, errors, and provides lifecycle actions for async operations.

This extension preserves Reatom context across async operations, ensuring that the async operation’s results properly update Reatom state.

Type Parameters

Err

Err = Error

The type of errors after parsing

EmptyErr

EmptyErr = undefined

The type of the empty error state

Parameters

options?

Configuration options for error handling

AsyncOptions<Err, EmptyErr> | null

Returns

An extension function that can be applied to atoms or actions

<T>(target): T extends AtomLike<any, Params, Promise<Payload>> ? T<T> & AsyncExt<Params, Payload, Err | EmptyErr> : never

Type Parameters

T

T extends AtomLike<any, any[], any>

Parameters

target

T

Returns

T extends AtomLike<any, Params, Promise<Payload>> ? T<T> & AsyncExt<Params, Payload, Err | EmptyErr> : never

Example

// Basic usage with an action:
  const fetchUser = action(async (userId: string) => {
    const response = await wrap(fetch(`/api/users/${userId}`))
    return await wrap(response.json())
  }, 'fetchUser').extend(withAsync())

  // Can then access:
  fetchUser.error() // → latest error if any
  fetchUser.ready() // → are all operations complete?

Functions

withAsyncData()

Implementation of the withAsyncData extension.

Example

// Basic usage with a computed for data fetching:
  const userId = atom('1', 'userId')

  // Create a computed that fetches data when userId changes
  const userData = computed(async () => {
    const id = userId()
    const response = await wrap(fetch(`/api/users/${id}`))
    if (!response.ok) throw new Error('Failed to fetch user')
    return await wrap(response.json())
  }, 'userData').extend(withAsyncData())

  // Access the fetched data and loading states:
  userData.data() // → the fetched user data
  userData.error() // → error if fetch failed
  userData.ready() // → false while loading, true when complete

Param

Configuration options for the async data handling

Call Signature

withAsyncData<Err, EmptyErr>(options?): <T>(target) => T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, Payload, undefined, Err | EmptyErr> : never

Defined in: async/withAsyncData.ts:104

Extension that adds async data management to atoms or actions that return promises.

Creates a properly typed data atom that stores the results of successful async operations. Includes all features of withAsync and withAbort for complete async handling.

Type Parameters

Err

Err = Error

The type of errors after parsing

EmptyErr

EmptyErr = undefined

The type of the empty error state

Parameters

options?

AsyncOptions<Err, EmptyErr>

Configuration options for async data handling

Returns

An extension function that can be applied to atoms or actions

<T>(target): T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, Payload, undefined, Err | EmptyErr> : never

Type Parameters

T

T extends AtomLike<any, any[], any>

Parameters

target

T

Returns

T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, Payload, undefined, Err | EmptyErr> : never

Call Signature

withAsyncData<T, Err, EmptyErr>(options): (target) => T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, Payload, Payload, Err | EmptyErr> : never

Defined in: async/withAsyncData.ts:127

Extension that adds async data management to atoms or actions that return promises.

This overload uses the payload type as the state type with a specified initial value. Useful when you know the shape of the data that will be fetched.

Type Parameters

T

T extends AtomLike<any, any[], any>

The atom or action type

Err

Err = Error

The type of errors after parsing

EmptyErr

EmptyErr = undefined

The type of the empty error state

Parameters

options

AsyncOptions<Err, EmptyErr> & T extends AtomLike<any, Params, Promise<Payload>> ? object : never

Configuration options including initial state and optional payload mapper

Returns

An extension function that can be applied to atoms or actions

(target): T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, Payload, Payload, Err | EmptyErr> : never

Parameters

target

T

Returns

T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, Payload, Payload, Err | EmptyErr> : never

Call Signature

withAsyncData<State, T, Err, EmptyErr>(options): (target) => T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, State, Payload, Err | EmptyErr> : never

Defined in: async/withAsyncData.ts:164

Extension that adds async data management to atoms or actions that return promises.

This overload allows specifying a completely custom state type with an initial value. The resolved payload will be merged with the state without custom mapping.

Type Parameters

State

State

The custom state type

T

T extends AtomLike<any, any[], any>

The atom or action type

Err

Err = Error

The type of errors after parsing

EmptyErr

EmptyErr = undefined

The type of the empty error state

Parameters

options

AsyncOptions<Err, EmptyErr> & object

Configuration options with custom initial state

Returns

An extension function that can be applied to atoms or actions

(target): T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, State, Payload, Err | EmptyErr> : never

Parameters

target

T

Returns

T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, State, Payload, Err | EmptyErr> : never

Call Signature

withAsyncData<State, T, Err, EmptyErr>(options): (target) => T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, State, State, Err | EmptyErr> : never

Defined in: async/withAsyncData.ts:196

Extension that adds async data management to atoms or actions that return promises.

This overload provides full control with a custom state type and payload mapping function. Allows complete transformation of the payload into the desired state format.

Type Parameters

State

State

The custom state type

T

T extends AtomLike<any, any[], any>

The atom or action type

Err

Err = Error

The type of errors after parsing

EmptyErr

EmptyErr = undefined

The type of the empty error state

Parameters

options

AsyncOptions<Err, EmptyErr> & object

Configuration options with custom initial state and payload mapper

Returns

An extension function that can be applied to atoms or actions

(target): T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, State, State, Err | EmptyErr> : never

Parameters

target

T

Returns

T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, State, State, Err | EmptyErr> : never