@tempots/ui/utils/query-resource.d.ts

Provides a higher level of renderables to help fast development with Tempo.

import { Signal, Value } from '@tempots/dom';
import { AsyncResult, NonLoading } from '@tempots/std';
/**
 * Represents an asynchronous query with its current status, value, error, and loading state.
 * Provides methods to reload the query and dispose of it.
 *
 * @template Res - The type of the value when the query is successfully loaded.
 * @template E - The type of the error when the query fails to load.
 * @public
 */
export interface QueryResource<Res, E> {
    /** The current status of the query as an AsyncResult. */
    readonly status: Signal<AsyncResult<Res, E>>;
    /** Abort the current in-flight request (if any) and clean up. */
    readonly cancel: (newState?: NonLoading<Res, E>) => void;
    /** Disposes of the query, aborting any ongoing requests and cleaning up. */
    readonly dispose: () => void;
    /** The current value of the query, or undefined if not loaded or failed. */
    readonly value: Signal<Res | undefined>;
    /** The current error of the query, or undefined if not failed. */
    readonly error: Signal<E | undefined>;
    /** Whether the query is currently loading. */
    readonly loading: Signal<boolean>;
    /** Reloads the query using the current request. */
    readonly reload: () => void;
}
/**
 * Options for loading a query, including the request, abort signal, and previous result.
 *
 * @template Req - The type of the request.
 * @template Res - The type of the value when the query is successfully loaded.
 * @template E - The type of the error when the query fails to load.
 * @public
 */
export interface QueryResourceLoadOptions<Req, Res, E> {
    /** The request to load the query. */
    readonly request: Req;
    /** The signal to abort the loading process if needed. */
    readonly abortSignal: AbortSignal;
    /** The previous result of the query loading, if any. */
    readonly previous: AsyncResult<Res, E>;
    /** Side-effects */
    readonly onSuccess?: (value: Res, req: Req) => void;
    readonly onError?: (error: E, req: Req) => void;
    readonly onSettled?: (result: AsyncResult<Res, E>, req: Req) => void;
}
/**
 * Creates an asynchronous query that can be loaded, reloaded, and disposed of.
 *
 * @template R - The type of the request.
 * @template V - The type of the value when the query is successfully loaded.
 * @template E - The type of the error when the query fails to load.
 *
 * @param request - The request to load the query.
 * @param load - The function to load the query.
 * @param convertError - The function to convert an unknown error into a specific error type.
 * @returns The created asynchronous query.
 * @public
 */
export declare const makeQueryResource: <Req, Res, E>({ request, load, convertError, onSuccess, onError, onSettled, }: {
    request: Value<Req>;
    load: (options: QueryResourceLoadOptions<Req, Res, E>) => Promise<Res>;
    convertError: (error: unknown) => E;
    onSuccess?: (value: Res, req: Req) => void;
    onError?: (error: E, req: Req) => void;
    onSettled?: (result: AsyncResult<Res, E>, req: Req) => void;
}) => QueryResource<Res, E>;