Package @reatom/async

@reatom/async

Interfaces

AsyncDataExt<Params, Payload, State, Error>

Defined in: async/withAsyncData.ts:20

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

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>

Defined in: async/withAsyncData.ts:31

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

error

error: Atom<undefined | Error>

Defined in: async/withAsync.ts:81

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:45

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:57

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:68

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:78

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:36

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

AsyncDataOptions<State, Params, Payload, Err, EmptyErr>

Defined in: async/withAsyncData.ts:44

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:100

Initial/reset value for the error atom

Inherited from

AsyncOptions.emptyError

initState?

optional initState: State

Defined in: async/withAsyncData.ts:52

Initial value for the data atom

mapPayload()?

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

Defined in: async/withAsyncData.ts:62

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:97

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: null | "onCall" | "onFulfill"

Defined in: async/withAsync.ts:109

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

Inherited from

AsyncOptions.resetError

AsyncExt<Params, Payload, Error>

Defined in: async/withAsync.ts:25

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<undefined | Error>

Defined in: async/withAsync.ts:81

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:45

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:57

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:68

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:78

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:36

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)

Type Aliases

AsyncOptions<Err, EmptyErr>

AsyncOptions<Err, EmptyErr> = object

Defined in: async/withAsync.ts:90

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:100

Initial/reset value for the error atom

parseError()?

optional parseError: (error) => Err

Defined in: async/withAsync.ts:97

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:109

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

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:136

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

null | AsyncOptions<Err, EmptyErr>

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, undefined | Payload, Err | EmptyErr> : never

Defined in: async/withAsyncData.ts:78

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, undefined | Payload, 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, undefined | Payload, Err | EmptyErr> : never

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<T, Err, EmptyErr>(options): (target) => T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, Payload, Err | EmptyErr> : never

Defined in: async/withAsyncData.ts:101

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, Err | EmptyErr> : never

Parameters

target

T

Returns

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

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<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:138

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

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<State, T, Err, EmptyErr>(options): (target) => T extends AtomLike<any, Params, Promise<Payload>> ? AsyncDataExt<Params, Payload, State, Err | EmptyErr> : never

Defined in: async/withAsyncData.ts:170

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, Err | EmptyErr> : never

Parameters

target

T

Returns

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

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