Documentation navigation

Published API · 0.1.0-rc.1

foldkit · asyncData

Published foldkit API declarations for asyncData.

./asyncData

@wsagency/wseffect-foldkit · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-foldkit@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-foldkit/asyncData'

Exported declarations

all

Combines an iterable or record of values under the `zipWith` lattice. An iterable collapses to an in-order array of data (empty input yields `Success({ data: [] })`); a record builds a struct (empty input yields `Success({ data: {} })`). The highest-ranked no-data state blocks, the leftmost `Failure` error wins, and any `Stale` in an all-data set makes the result `Stale` with the leftmost `Stale` error. All inputs must share one error type; unify with `mapError` first. The record form is the multi-resource screen: `all({ user, orders, prefs })` combines into one value whose data is the struct of all datas.

all: <const Inputs extends Iterable<AsyncData<any, any>> | Record<string, AsyncData<any, any>>>(inputs: Inputs) => [Inputs] extends [ReadonlyArray<AsyncData<any, any>>] ? AsyncData<{
    -readonly [K in keyof Inputs]: [Inputs[K]] extends [
        AsyncData<infer A, any>
    ] ? A : never;
}, Inputs[number] extends never ? never : [Inputs[number]] extends [AsyncData<any, infer E>] ? E : never> : [Inputs] extends [Iterable<AsyncData<infer A, infer E>>] ? AsyncData<Array<A>, E> : AsyncData<{
    -readonly [K in keyof Inputs]: [Inputs[K]] extends [
        AsyncData<infer A, any>
    ] ? A : never;
}, Inputs[keyof Inputs] extends never ? never : [Inputs[keyof Inputs]] extends [AsyncData<any, infer E>] ? E : never>

AsyncData

The six-state union for an asynchronously loaded value: `Idle | Loading | Refreshing(data) | Failure(error) | Stale(error, data) | Success(data)`. Value-first type parameters, matching `Result<A, E>` and `Exit<A, E>`. `Refreshing` and `Stale` make stale-while-revalidate and stale-on-failure first-class states: both hold the previous good `data`, `Refreshing` while a reload is in flight, `Stale` after a reload failed. Data-presence classification, used throughout the module: - "has data" states: `Success`, `Refreshing`, `Stale`. - "no data" states: `Idle`, `Loading`, `Failure`. - "pending" states (a request in flight): `Loading`, `Refreshing` only. `Stale` is not pending; its fetch already failed. Naming rule: predicates are tag-named (`isSuccess`, `isFailure`) but getters are payload-named (`getData`, `getError`) because `getData` spans three tags (`Success`, `Refreshing`, `Stale`) and `getError` spans two (`Failure`, `Stale`). Handler keys are tag-named where dispatch is per tag (`match`) and channel-named where one handler covers multiple tags (`matchData`, `mapBoth`).

export type AsyncData<A, E> = Idle | Loading | Refreshing<A> | Failure<E> | Stale<A, E> | Success<A>;

AsyncDataEncoded

The encoded (wire) form of a `AsyncData<A, E>` whose data encodes to `AI` and whose error encodes to `EI`.

export type AsyncDataEncoded<AI, EI> = Readonly<{
    _tag: 'Idle';
}> | Readonly<{
    _tag: 'Loading';
}> | Readonly<{
    _tag: 'Refreshing';
    data: AI;
}> | Readonly<{
    _tag: 'Failure';
    error: EI;
}> | Readonly<{
    _tag: 'Stale';
    error: EI;
    data: AI;
}> | Readonly<{
    _tag: 'Success';
    data: AI;
}>;

AsyncDataSchema

What the `Schema` factory returns: the six-state Union codec to embed in a Model plus the Schema-bound constructors for the four parameterized states. Combinators are not part of this bag; they are module-level free functions over any `AsyncData<A, E>` value.

export type AsyncDataSchema<A, AI, E, EI> = Readonly<{
    /** The six-state Union codec. Embed this in your Model, or in
     *  `Schema.HashMap(key, this)` for a keyed cache. */
    schema: EffectSchema.Codec<AsyncData<A, E>, AsyncDataEncoded<AI, EI>>;
    Idle: typeof Idle;
    Loading: typeof Loading;
    Refreshing: (payload: Readonly<{
        data: A;
    }>) => AsyncData<A, E>;
    Failure: (payload: Readonly<{
        error: E;
    }>) => AsyncData<A, E>;
    Stale: (payload: Readonly<{
        error: E;
        data: A;
    }>) => AsyncData<A, E>;
    Success: (payload: Readonly<{
        data: A;
    }>) => AsyncData<A, E>;
}>;

fail

Bare-value alias for `Failure({ error })`, mirroring `Result.fail`.

fail: <E, A = never>(error: E) => AsyncData<A, E>

Failure

The `Failure` state: request failed, showing the failure.

export type Failure<E> = Readonly<{
    _tag: 'Failure';
    error: E;
}>;

Failure

Constructs a `Failure` state carrying the error only. Plain value builder, generic in `E`; use the `Schema` factory's `Failure` for a Schema-bound constructor.

Failure: <E>(payload: Readonly<{
    error: E;
}>) => AsyncData<never, E>

flatMap

Treats every data-bearing state (`Success`, `Refreshing`, `Stale`) exactly like `Success(data)`: returns `f(data)` unchanged, dropping the tag and any `Stale` error, so a caller can settle in-flight or stale data into `Success`. The no-data states pass through. Widens the error channel to `E | E2`, matching `Result.flatMap`.

flatMap: {
    <A, B, E2>(f: (data: A) => AsyncData<B, E2>): <E>(self: AsyncData<A, E>) => AsyncData<B, E | E2>;
    <A, E, B, E2>(self: AsyncData<A, E>, f: (data: A) => AsyncData<B, E2>): AsyncData<B, E | E2>;
}

fromOptionOrIdle

Collapses a possibly-missing cache entry to an AsyncData: `Some(entry)` is the entry, `None` is `Idle`. The keyed-cache read idiom, where a key that was never fetched is simply absent and absence means nothing was requested yet: ```ts const notes = AsyncData.fromOptionOrIdle(HashMap.get(model.notesByNotebook, notebookId)) ```

fromOptionOrIdle: <A, E>(maybeEntry: Option.Option<AsyncData<A, E>>) => AsyncData<A, E>

getData

Returns the data as an `Option`, spanning all three data-bearing states: `Some` for `Success`, `Refreshing`, and `Stale`, `None` otherwise. Payload-named because it deliberately spans three tags.

getData: <A, E>(self: AsyncData<A, E>) => Option.Option<A>

getError

Returns the error as an `Option`, spanning both error-bearing states: `Some` for `Failure` and `Stale`, `None` otherwise. Symmetric with `getData`.

getError: <A, E>(self: AsyncData<A, E>) => Option.Option<E>

getOrElse

Returns the data of any data-bearing state, or `onEmpty()` for the three no-data states. The fallback is a nullary thunk, mirroring `Option.getOrElse`, because the no-data states collapse to empty with no single payload.

getOrElse: {
    <B>(onEmpty: Function.LazyArg<B>): <A, E>(self: AsyncData<A, E>) => A | B;
    <A, E, B>(self: AsyncData<A, E>, onEmpty: Function.LazyArg<B>): A | B;
}

hasData

Returns `true` when the state holds data: `Success`, `Refreshing`, or `Stale`.

hasData: <A, E>(self: AsyncData<A, E>) => boolean

hasError

Returns `true` when the state carries an error: `Failure` or `Stale`. The error-channel twin of `hasData`.

hasError: <A, E>(self: AsyncData<A, E>) => boolean

Idle

The `Idle` state: nothing requested yet.

export type Idle = Readonly<{
    _tag: 'Idle';
}>;

Idle

Constructs the `Idle` state. A parameter-free callable Schema, so it can also serve as a Union member.

Idle: import("../schema/index.js").CallableTaggedStruct<"Idle", {}>

isAsyncData

Type guard on `unknown`: checks that the value has a `_tag` belonging to the six `AsyncData` states.

isAsyncData: (input: unknown) => input is AsyncData<unknown, unknown>

isFailure

Returns `true` only for the `Failure` state, not `Stale`. Refinement.

isFailure: <A, E>(self: AsyncData<A, E>) => self is Failure<E>

isIdle

Returns `true` only for the `Idle` state. Refinement.

isIdle: <A, E>(self: AsyncData<A, E>) => self is Idle

isLoading

Returns `true` only for the empty `Loading` state, not `Refreshing`. Refinement.

isLoading: <A, E>(self: AsyncData<A, E>) => self is Loading

isPending

Returns `true` when a request is in flight: `Loading` or `Refreshing` only. `Stale` is not pending because its fetch already failed. Use for a spinner regardless of held data.

isPending: <A, E>(self: AsyncData<A, E>) => boolean

isRefreshing

Returns `true` only for the `Refreshing` state. Refinement.

isRefreshing: <A, E>(self: AsyncData<A, E>) => self is Refreshing<A>

isStale

Returns `true` only for the `Stale` state: a failed refresh holding the last good data. Refinement.

isStale: <A, E>(self: AsyncData<A, E>) => self is Stale<A, E>

isSuccess

Returns `true` only for the `Success` state, not `Refreshing` or `Stale`. Refinement.

isSuccess: <A, E>(self: AsyncData<A, E>) => self is Success<A>

loadIfMissing

The first-visit load transition: the cold no-data states (`Idle`, `Failure`) start a fresh `Loading`; every other state yields `None`, so loaded data is kept without revalidation and a request in flight is not restarted. The load-only sibling of `revalidateOrLoad` and `revalidate`, and the state-machine form of TanStack Query's `staleTime: Infinity`: fetch on first visit, keep the cache afterwards.

loadIfMissing: <A, E>(self: AsyncData<A, E>) => Option.Option<AsyncData<A, E>>

Loading

The `Loading` state: first request in flight, no prior data.

export type Loading = Readonly<{
    _tag: 'Loading';
}>;

Loading

Constructs the `Loading` state. A parameter-free callable Schema, so it can also serve as a Union member.

Loading: import("../schema/index.js").CallableTaggedStruct<"Loading", {}>

map

Maps the data of all three data-bearing states, preserving each tag so the `Refreshing` and `Stale` signals survive a pure transform. `Stale` maps only its `data`, keeping its `error`. The no-data states pass through unchanged.

map: {
    <A, B>(f: (data: A) => B): <E>(self: AsyncData<A, E>) => AsyncData<B, E>;
    <A, E, B>(self: AsyncData<A, E>, f: (data: A) => B): AsyncData<B, E>;
}

mapBoth

Maps both channels with channel-named handlers: `onData` spans `Success`, `Refreshing`, and `Stale`; `onError` spans `Failure` and `Stale`. For `Stale`, both handlers apply. Tags are preserved.

mapBoth: {
    <A, E, B, E2>(handlers: {
        readonly onData: (data: A) => B;
        readonly onError: (error: E) => E2;
    }): (self: AsyncData<A, E>) => AsyncData<B, E2>;
    <A, E, B, E2>(self: AsyncData<A, E>, handlers: {
        readonly onData: (data: A) => B;
        readonly onError: (error: E) => E2;
    }): AsyncData<B, E2>;
}

mapError

Maps the error of the two error-bearing states: `Failure` and `Stale` transform (`Stale` keeps its `data`), everything else passes through. Use it to unify heterogeneous error types before a combine.

mapError: {
    <E, E2>(f: (error: E) => E2): <A>(self: AsyncData<A, E>) => AsyncData<A, E2>;
    <A, E, E2>(self: AsyncData<A, E>, f: (error: E) => E2): AsyncData<A, E2>;
}

match

Handles all six states exhaustively, passing each handler its unwrapped payload. `onStale` alone receives the whole `{ error, data }` payload object because `Stale` carries two fields. Use `matchData` when the view does not care which of the data-bearing states it is rendering.

match: {
    <A, E, B, C = B, D = B, F = B, G = B, H = B>(handlers: Readonly<{
        onIdle: Function.LazyArg<B>;
        onLoading: Function.LazyArg<C>;
        onRefreshing: (data: A) => D;
        onFailure: (error: E) => F;
        onStale: (payload: Readonly<{
            error: E;
            data: A;
        }>) => G;
        onSuccess: (data: A) => H;
    }>): (self: AsyncData<A, E>) => B | C | D | F | G | H;
    <A, E, B, C = B, D = B, F = B, G = B, H = B>(self: AsyncData<A, E>, handlers: Readonly<{
        onIdle: Function.LazyArg<B>;
        onLoading: Function.LazyArg<C>;
        onRefreshing: (data: A) => D;
        onFailure: (error: E) => F;
        onStale: (payload: Readonly<{
            error: E;
            data: A;
        }>) => G;
        onSuccess: (data: A) => H;
    }>): B | C | D | F | G | H;
}

matchData

Collapses the six states to the three channels a view usually renders: `onData` spans the data-bearing states (`Success`, `Refreshing`, `Stale`), `onFailure` receives the `Failure` error, and `onEmpty` covers `Idle` and `Loading` together. A `Stale` renders through `onData` so its data stays on screen. Use `matchDataSplitEmpty` when `Idle` and `Loading` render differently, and `match` when the stale error or the `Refreshing` signal matters.

matchData: {
    <A, E, B, C = B, D = B>(handlers: {
        readonly onEmpty: Function.LazyArg<B>;
        readonly onFailure: (error: E) => C;
        readonly onData: (data: A) => D;
    }): (self: AsyncData<A, E>) => B | C | D;
    <A, E, B, C = B, D = B>(self: AsyncData<A, E>, handlers: {
        readonly onEmpty: Function.LazyArg<B>;
        readonly onFailure: (error: E) => C;
        readonly onData: (data: A) => D;
    }): B | C | D;
}

matchDataSplitEmpty

Like `matchData`, but the collapsed `onEmpty` channel is split in two: `onIdle` handles `Idle` and `onLoading` handles `Loading`, for views that render nothing requested yet differently from a request in flight. `onData` and `onFailure` behave exactly as in `matchData`.

matchDataSplitEmpty: {
    <A, E, B, C = B, D = B, F = B>(handlers: {
        readonly onIdle: Function.LazyArg<B>;
        readonly onLoading: Function.LazyArg<C>;
        readonly onFailure: (error: E) => D;
        readonly onData: (data: A) => F;
    }): (self: AsyncData<A, E>) => B | C | D | F;
    <A, E, B, C = B, D = B, F = B>(self: AsyncData<A, E>, handlers: {
        readonly onIdle: Function.LazyArg<B>;
        readonly onLoading: Function.LazyArg<C>;
        readonly onFailure: (error: E) => D;
        readonly onData: (data: A) => F;
    }): B | C | D | F;
}

orElse

Returns `self` when it holds data (`Success`, `Refreshing`, or `Stale`), otherwise `that()`. The recovery and cache-fallback combinator: recover an `Idle`, `Loading`, or `Failure` into a secondary source without `match`.

orElse: {
    <A, E>(that: Function.LazyArg<AsyncData<A, E>>): (self: AsyncData<A, E>) => AsyncData<A, E>;
    <A, E>(self: AsyncData<A, E>, that: Function.LazyArg<AsyncData<A, E>>): AsyncData<A, E>;
}

Refreshing

The `Refreshing` state: reloading while holding the previous good data.

export type Refreshing<A> = Readonly<{
    _tag: 'Refreshing';
    data: A;
}>;

Refreshing

Constructs a `Refreshing` state holding the previous good data. Plain value builder, generic in `A`; use the `Schema` factory's `Refreshing` for a Schema-bound constructor.

Refreshing: <A>(payload: Readonly<{
    data: A;
}>) => AsyncData<A, never>

revalidate

The loaded-only revalidation transition: `Success` and `Stale` move to `Refreshing`, every other state yields `None`. Unlike `revalidateOrLoad` there is no cold-start `Loading`, so only caches that actually hold data revalidate; this is the generic refresher path after a mutation.

revalidate: <A, E>(self: AsyncData<A, E>) => Option.Option<AsyncData<A, E>>

revalidateOrLoad

The revalidate-on-entry transition: revalidates loaded data and loads cold data. The data-bearing loaded states (`Success`, `Stale`) move to `Refreshing`; the cold no-data states (`Idle`, `Failure`) start a fresh `Loading`; the already-pending states (`Loading`, `Refreshing`) yield `None` so the request in flight is not restarted. `None` means no transition, and no load Command, is needed.

revalidateOrLoad: <A, E>(self: AsyncData<A, E>) => Option.Option<AsyncData<A, E>>

Schema

Builds the six-state `AsyncData` Schema for the given data and error Schemas (value-first). Put `schema` in your Model; use the returned constructors when you want ones typed to this instance's `A` and `E`.

Schema: <A, AI, E, EI>(dataSchema: EffectSchema.Codec<A, AI>, errorSchema: EffectSchema.Codec<E, EI>) => AsyncDataSchema<A, AI, E, EI>

settle

Folds a settled `Result` into the previous state, keeping the last good data: a `Result` success becomes `Success`, and a `Result` failure becomes `Stale({ error, data })` when `self` holds data, else a bare `Failure`. The primary way to fold a fetch back into the Model, and the reason a failed refresh keeps data on screen: without `settle`, every fetch needs a success arm and a failure arm that hand-assemble `Success`, `Stale`, and `Failure` from the previous state. When a failure should deliberately drop the previous data, match on the `Result` directly and build the `Failure` explicitly.

settle: {
    <A, E>(result: Result.Result<A, E>): (self: AsyncData<A, E>) => AsyncData<A, E>;
    <A, E>(self: AsyncData<A, E>, result: Result.Result<A, E>): AsyncData<A, E>;
}

Stale

The `Stale` state: the last refresh failed, still holding the previous good data. The failed-refresh mirror of `Refreshing`.

export type Stale<A, E> = Readonly<{
    _tag: 'Stale';
    error: E;
    data: A;
}>;

Stale

Constructs a `Stale` state carrying both the refresh error and the last good data. Plain value builder, generic in `A` and `E`; use the `Schema` factory's `Stale` for a Schema-bound constructor.

Stale: <A, E>(payload: Readonly<{
    error: E;
    data: A;
}>) => AsyncData<A, E>

succeed

Bare-value alias for `Success({ data })`, mirroring `Result.succeed`.

succeed: <A, E = never>(data: A) => AsyncData<A, E>

Success

The `Success` state: request succeeded, data present.

export type Success<A> = Readonly<{
    _tag: 'Success';
    data: A;
}>;

Success

Constructs a `Success` state holding the data. Plain value builder, generic in `A`; use the `Schema` factory's `Success` for a Schema-bound constructor.

Success: <A>(payload: Readonly<{
    data: A;
}>) => AsyncData<A, never>

zipWith

Combines two values under the two-tier lattice `Failure > Loading > Idle > Stale > Refreshing > Success`. If either input is a no-data state, the highest-ranked such state wins with no combination (`self`'s error wins when both are `Failure`). Otherwise both hold data: combine with `f` and tag the result with the highest-ranked data state present (`self`'s error wins when both are `Stale`). Because the combined value needs both inputs' data, a single no-data input collapses the whole combine to that state: `zipWith(Idle(), Success({ data }), f)` yields `Idle`.

zipWith: {
    <A, E, B, C>(that: AsyncData<B, E>, f: (selfData: A, thatData: B) => C): (self: AsyncData<A, E>) => AsyncData<C, E>;
    <A, E, B, C>(self: AsyncData<A, E>, that: AsyncData<B, E>, f: (selfData: A, thatData: B) => C): AsyncData<C, E>;
}