shelving/store/FetchStore.d.ts

Toolkit for using data in JavaScript.

import { type NONE } from "../util/constants.js";
import { BusyStore } from "./BusyStore.js";
import type { AsyncStoreInput, StoreInput } from "./Store.js";
/** Zero passed to `refresh()` means "always refresh this value" (this is the default). */
export declare const ALWAYS_REFRESH = 0;
/** Infinity passed to `refresh()` means "only refresh if this value is not loaded or invalid". */
export declare const AVOID_REFRESH: number;
/** Callback for a callback fetch store. */
export type FetchCallback<T> = (signal: AbortSignal) => StoreInput<T> | PromiseLike<StoreInput<T>>;
/**
 * Store that fetches its values from a remote source.
 *
 * @param value The initial value for the store, or `NONE` if it does not have one yet.
 * @param callback An optional callback that, if set, will be called when the `refresh()` method is invoked to fetch the next value.
 * - Override `this._fetch()` in subclasses to define custom fetching behaviour for a subclass.
 */
export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
    get loading(): boolean;
    write(input: StoreInput<TT>): void;
    read(): import("./Store.js").StoreInternal<T>;
    get age(): number;
    constructor(value: T | typeof NONE, callback?: FetchCallback<TT>);
    /**
     * Fetch the result for this store now.
     * - Triggered automatically when someone reads `value` or `loading`.
     * - Refreshes are de-duplicated. Concurrent calls while a fetch is in-flight return the same promise.
     * - Never throws — errors are stored as `reason`.
     *
     * @param maxAge The maximum age for whether we refresh or not.
     * - `0` zero means "always refresh" (this is the default).
     * - `Infinity` means "refresh only if store is still in a loading state.
     * - Any other value may or may not be stale based on `this.age`
     */
    refresh(maxAge?: number): Promise<boolean> | boolean;
    private _pendingRefresh;
    /**
     * Current `AbortSignal` for this store's in-flight fetch.
     * - Created lazily; a new signal is issued each time `refresh()` starts a new fetch or `abort()` is called.
     * - Triggers `abort()` so any current awaits are cancelled.
     */
    get signal(): AbortSignal;
    private _aborter;
    /**
     * Call the fetch callback to get the next value.
     * @param signal `AbortSignal` for the current fetch — passed through to the callback so it can cancel HTTP requests etc.
     */
    protected _fetch(signal: AbortSignal): AsyncStoreInput<TT>;
    private _callback;
    /** Whether this store is has currently been invalidated and needs a refresh. */
    get invalidated(): boolean;
    /**
     * Invalidate this store so a new fetch is triggered on the next read of `loading` or `value`.
     * - Triggers `abort()` so any current awaits are cancelled.
     */
    invalidate(): void;
    private _invalidation;
    abort(): void;
}