Interface ListQueryOptions<TRaw, TEntity>

Declarative instruction for a collection query: stable queryKey, fetcher, and per-row normalization into the graph. mode controls whether a fetch replaces ids or appends (infinite scroll) when used with load-more.

interface ListQueryOptions<TRaw, TEntity extends object> {
    enabled?: boolean;
    fetch?: (params: ListFetchParams) => Promise<ListResponse<TRaw>>;
    mode?: "replace" | "append";
    normalize?: (raw: TRaw) => { data: TEntity; id: string };
    onError?: (error: Error) => void;
    onSuccess?: (result: ListResponse<TRaw>) => void;
    queryKey: unknown[];
    sideEffects?: (
        items: TRaw[],
        store: Omit<
            Omit<StoreApi<GraphState>, "subscribe"> & {
                subscribe: {
                    (
                        listener: (
                            selectedState: GraphState,
                            previousSelectedState: GraphState,
                        ) => void,
                    ): () => void;
                    <U>(
                        selector: (state: GraphState) => U,
                        listener: (selectedState: U, previousSelectedState: U) => void,
                        options?: {
                            equalityFn?: (a: ..., b: ...) => ...;
                            fireImmediately?: boolean;
                        },
                    ): () => void;
                };
            },
            "setState",
        > & {
            setState(
                nextStateOrUpdater:
                    | GraphState
                    | Partial<GraphState>
                    | (
                        (
                            state: {
                                appendListResult: (
                                    key: string,
                                    ids: string[],
                                    meta: Partial<
                                        Omit<ListState, (...) | (...) | (...) | (...) | (...)>,
                                    >,
                                ) => void;
                                clearEntitySyncMetadata: (type: string, id: string) => void;
                                clearPatch: (type: string, id: string) => void;
                                entities: { [x: string]: { [x: string]: { [x: string]: unknown } } };
                                entityStates: {
                                    [x: string]: {
                                        error: string | null;
                                        isFetching: boolean;
                                        lastFetched: number | null;
                                        stale: boolean;
                                    };
                                };
                                ingestFetchedList: (
                                    type: string,
                                    entries: { data: Record<(...), (...)>; id: string }[],
                                    options?: IngestFetchedListOptions,
                                ) => void;
                                insertIdInList: (
                                    key: string,
                                    id: string,
                                    position: number | "end" | "start",
                                ) => void;
                                invalidateEntity: (type: string, id?: string) => void;
                                invalidateLists: (
                                    matcher: string | ((key: string) => boolean),
                                ) => void;
                                invalidateType: (type: string) => void;
                                lists: {
                                    [x: string]: {
                                        currentPage: number | null;
                                        error: string | null;
                                        hasNextPage: boolean;
                                        hasPrevPage: boolean;
                                        ids: string[];
                                        isFetching: boolean;
                                        isFetchingMore: boolean;
                                        lastError:
                                            | {
                                                cause?: ...;
                                                kind: ...;
                                                message: ...;
                                                name: ...;
                                                stack?: ...;
                                                status?: ...;
                                            }
                                            | {
                                                cause?: ...;
                                                kind: ...;
                                                message: ...;
                                                name: ...;
                                                stack?: ...;
                                                status?: ...;
                                            }
                                            | null;
                                        lastFetched: number
                                        | null;
                                        nextCursor: string | null;
                                        pageSize: number | null;
                                        prevCursor: string | null;
                                        stale: boolean;
                                        total: number | null;
                                    };
                                };
                                patchEntity: (
                                    type: string,
                                    id: string,
                                    patch: Record<string, unknown>,
                                ) => void;
                                patches: { [x: string]: { [x: string]: { [x: string]: unknown } } };
                                prependListResult: (
                                    key: string,
                                    ids: string[],
                                    meta?: Partial<ListState>,
                                ) => void;
                                readEntity: <T = Record<string, unknown>>(
                                    type: string,
                                    id: string,
                                ) => T | null;
                                readEntitySnapshot: <T = Record<string, unknown>>(
                                    type: string,
                                    id: string,
                                ) => EntitySnapshot<(...) & (...)> | null;
                                removeEntity: (type: string, id: string) => void;
                                removeIdFromAllLists: (type: string, id: string) => void;
                                replaceEntity: (
                                    type: string,
                                    id: string,
                                    data: Record<string, unknown>,
                                ) => void;
                                setEntityError: (
                                    type: string,
                                    id: string,
                                    error: string | null,
                                ) => void;
                                setEntityFetched: (type: string, id: string) => void;
                                setEntityFetching: (
                                    type: string,
                                    id: string,
                                    fetching: boolean,
                                ) => void;
                                setEntityStale: (type: string, id: string, stale: boolean) => void;
                                setEntitySyncMetadata: (
                                    type: string,
                                    id: string,
                                    metadata: Partial<EntitySyncMetadata>,
                                ) => void;
                                setListError: (
                                    key: string,
                                    error: string | null,
                                    typed?: EntityError | null,
                                ) => void;
                                setListFetching: (key: string, fetching: boolean) => void;
                                setListFetchingMore: (key: string, fetchingMore: boolean) => void;
                                setListResult: (
                                    key: string,
                                    ids: string[],
                                    meta: Partial<
                                        Omit<ListState, (...) | (...) | (...) | (...) | (...)>,
                                    >,
                                ) => void;
                                setListStale: (key: string, stale: boolean) => void;
                                syncMetadata: {
                                    [x: string]: {
                                        origin: SyncOrigin;
                                        synced: boolean;
                                        updatedAt: number | null;
                                    };
                                };
                                unpatchEntity: (type: string, id: string, keys: string[]) => void;
                                upsertEntities: (
                                    type: string,
                                    entries: { data: Record<(...), (...)>; id: string }[],
                                ) => void;
                                upsertEntity: (
                                    type: string,
                                    id: string,
                                    data: Record<string, unknown>,
                                ) => void;
                            },
                        ) => void
                    ),
                shouldReplace?: false,
            ): void;
            setState(
                nextStateOrUpdater:
                    | GraphState
                    | (
                        (
                            state: {
                                appendListResult: (
                                    key: string,
                                    ids: string[],
                                    meta: Partial<
                                        Omit<ListState, (...) | (...) | (...) | (...) | (...)>,
                                    >,
                                ) => void;
                                clearEntitySyncMetadata: (type: string, id: string) => void;
                                clearPatch: (type: string, id: string) => void;
                                entities: { [x: string]: { [x: string]: { [x: string]: unknown } } };
                                entityStates: {
                                    [x: string]: {
                                        error: string | null;
                                        isFetching: boolean;
                                        lastFetched: number | null;
                                        stale: boolean;
                                    };
                                };
                                ingestFetchedList: (
                                    type: string,
                                    entries: { data: Record<(...), (...)>; id: string }[],
                                    options?: IngestFetchedListOptions,
                                ) => void;
                                insertIdInList: (
                                    key: string,
                                    id: string,
                                    position: number | "end" | "start",
                                ) => void;
                                invalidateEntity: (type: string, id?: string) => void;
                                invalidateLists: (
                                    matcher: string | ((key: string) => boolean),
                                ) => void;
                                invalidateType: (type: string) => void;
                                lists: {
                                    [x: string]: {
                                        currentPage: number | null;
                                        error: string | null;
                                        hasNextPage: boolean;
                                        hasPrevPage: boolean;
                                        ids: string[];
                                        isFetching: boolean;
                                        isFetchingMore: boolean;
                                        lastError:
                                            | {
                                                cause?: ...;
                                                kind: ...;
                                                message: ...;
                                                name: ...;
                                                stack?: ...;
                                                status?: ...;
                                            }
                                            | {
                                                cause?: ...;
                                                kind: ...;
                                                message: ...;
                                                name: ...;
                                                stack?: ...;
                                                status?: ...;
                                            }
                                            | null;
                                        lastFetched: number
                                        | null;
                                        nextCursor: string | null;
                                        pageSize: number | null;
                                        prevCursor: string | null;
                                        stale: boolean;
                                        total: number | null;
                                    };
                                };
                                patchEntity: (
                                    type: string,
                                    id: string,
                                    patch: Record<string, unknown>,
                                ) => void;
                                patches: { [x: string]: { [x: string]: { [x: string]: unknown } } };
                                prependListResult: (
                                    key: string,
                                    ids: string[],
                                    meta?: Partial<ListState>,
                                ) => void;
                                readEntity: <T = Record<string, unknown>>(
                                    type: string,
                                    id: string,
                                ) => T | null;
                                readEntitySnapshot: <T = Record<string, unknown>>(
                                    type: string,
                                    id: string,
                                ) => EntitySnapshot<(...) & (...)> | null;
                                removeEntity: (type: string, id: string) => void;
                                removeIdFromAllLists: (type: string, id: string) => void;
                                replaceEntity: (
                                    type: string,
                                    id: string,
                                    data: Record<string, unknown>,
                                ) => void;
                                setEntityError: (
                                    type: string,
                                    id: string,
                                    error: string | null,
                                ) => void;
                                setEntityFetched: (type: string, id: string) => void;
                                setEntityFetching: (
                                    type: string,
                                    id: string,
                                    fetching: boolean,
                                ) => void;
                                setEntityStale: (type: string, id: string, stale: boolean) => void;
                                setEntitySyncMetadata: (
                                    type: string,
                                    id: string,
                                    metadata: Partial<EntitySyncMetadata>,
                                ) => void;
                                setListError: (
                                    key: string,
                                    error: string | null,
                                    typed?: EntityError | null,
                                ) => void;
                                setListFetching: (key: string, fetching: boolean) => void;
                                setListFetchingMore: (key: string, fetchingMore: boolean) => void;
                                setListResult: (
                                    key: string,
                                    ids: string[],
                                    meta: Partial<
                                        Omit<ListState, (...) | (...) | (...) | (...) | (...)>,
                                    >,
                                ) => void;
                                setListStale: (key: string, stale: boolean) => void;
                                syncMetadata: {
                                    [x: string]: {
                                        origin: SyncOrigin;
                                        synced: boolean;
                                        updatedAt: number | null;
                                    };
                                };
                                unpatchEntity: (type: string, id: string, keys: string[]) => void;
                                upsertEntities: (
                                    type: string,
                                    entries: { data: Record<(...), (...)>; id: string }[],
                                ) => void;
                                upsertEntity: (
                                    type: string,
                                    id: string,
                                    data: Record<string, unknown>,
                                ) => void;
                            },
                        ) => void
                    ),
                shouldReplace: true,
            ): void;
        },
    ) => void;
    staleTime?: number;
    type: string;
}

Type Parameters

TRaw
TEntity extends object

Index

Properties

enabled? fetch? mode? normalize? onError? onSuccess? queryKey sideEffects? staleTime? type

Properties

`Optional`enabled

enabled?: boolean

`Optional`fetch

fetch?: (params: ListFetchParams) => Promise<ListResponse<TRaw>>

Inline fetcher (deprecated 1.x REST form). Optional in 2.0: pure graph subscriptions for Tier-A PGlite/Electric entities pass no fetcher — the graph is hydrated out-of-band and the hook only joins ids → entities. When omitted, fetchList is a no-op and the hook is read-only.

`Optional`mode

mode?: "replace" | "append"

`Optional`normalize

normalize?: (raw: TRaw) => { data: TEntity; id: string }

Row normalizer. Optional alongside fetch (graph-only callers omit both).

`Optional`onError

onError?: (error: Error) => void

`Optional`onSuccess

onSuccess?: (result: ListResponse<TRaw>) => void

queryKey

queryKey: unknown[]

`Optional`sideEffects

sideEffects?: (
    items: TRaw[],
    store: Omit<
        Omit<StoreApi<GraphState>, "subscribe"> & {
            subscribe: {
                (
                    listener: (
                        selectedState: GraphState,
                        previousSelectedState: GraphState,
                    ) => void,
                ): () => void;
                <U>(
                    selector: (state: GraphState) => U,
                    listener: (selectedState: U, previousSelectedState: U) => void,
                    options?: {
                        equalityFn?: (a: ..., b: ...) => ...;
                        fireImmediately?: boolean;
                    },
                ): () => void;
            };
        },
        "setState",
    > & {
        setState(
            nextStateOrUpdater:
                | GraphState
                | Partial<GraphState>
                | (
                    (
                        state: {
                            appendListResult: (
                                key: string,
                                ids: string[],
                                meta: Partial<
                                    Omit<ListState, (...) | (...) | (...) | (...) | (...)>,
                                >,
                            ) => void;
                            clearEntitySyncMetadata: (type: string, id: string) => void;
                            clearPatch: (type: string, id: string) => void;
                            entities: { [x: string]: { [x: string]: { [x: string]: unknown } } };
                            entityStates: {
                                [x: string]: {
                                    error: string | null;
                                    isFetching: boolean;
                                    lastFetched: number | null;
                                    stale: boolean;
                                };
                            };
                            ingestFetchedList: (
                                type: string,
                                entries: { data: Record<(...), (...)>; id: string }[],
                                options?: IngestFetchedListOptions,
                            ) => void;
                            insertIdInList: (
                                key: string,
                                id: string,
                                position: number | "end" | "start",
                            ) => void;
                            invalidateEntity: (type: string, id?: string) => void;
                            invalidateLists: (
                                matcher: string | ((key: string) => boolean),
                            ) => void;
                            invalidateType: (type: string) => void;
                            lists: {
                                [x: string]: {
                                    currentPage: number | null;
                                    error: string | null;
                                    hasNextPage: boolean;
                                    hasPrevPage: boolean;
                                    ids: string[];
                                    isFetching: boolean;
                                    isFetchingMore: boolean;
                                    lastError:
                                        | {
                                            cause?: ...;
                                            kind: ...;
                                            message: ...;
                                            name: ...;
                                            stack?: ...;
                                            status?: ...;
                                        }
                                        | {
                                            cause?: ...;
                                            kind: ...;
                                            message: ...;
                                            name: ...;
                                            stack?: ...;
                                            status?: ...;
                                        }
                                        | null;
                                    lastFetched: number
                                    | null;
                                    nextCursor: string | null;
                                    pageSize: number | null;
                                    prevCursor: string | null;
                                    stale: boolean;
                                    total: number | null;
                                };
                            };
                            patchEntity: (
                                type: string,
                                id: string,
                                patch: Record<string, unknown>,
                            ) => void;
                            patches: { [x: string]: { [x: string]: { [x: string]: unknown } } };
                            prependListResult: (
                                key: string,
                                ids: string[],
                                meta?: Partial<ListState>,
                            ) => void;
                            readEntity: <T = Record<string, unknown>>(
                                type: string,
                                id: string,
                            ) => T | null;
                            readEntitySnapshot: <T = Record<string, unknown>>(
                                type: string,
                                id: string,
                            ) => EntitySnapshot<(...) & (...)> | null;
                            removeEntity: (type: string, id: string) => void;
                            removeIdFromAllLists: (type: string, id: string) => void;
                            replaceEntity: (
                                type: string,
                                id: string,
                                data: Record<string, unknown>,
                            ) => void;
                            setEntityError: (
                                type: string,
                                id: string,
                                error: string | null,
                            ) => void;
                            setEntityFetched: (type: string, id: string) => void;
                            setEntityFetching: (
                                type: string,
                                id: string,
                                fetching: boolean,
                            ) => void;
                            setEntityStale: (type: string, id: string, stale: boolean) => void;
                            setEntitySyncMetadata: (
                                type: string,
                                id: string,
                                metadata: Partial<EntitySyncMetadata>,
                            ) => void;
                            setListError: (
                                key: string,
                                error: string | null,
                                typed?: EntityError | null,
                            ) => void;
                            setListFetching: (key: string, fetching: boolean) => void;
                            setListFetchingMore: (key: string, fetchingMore: boolean) => void;
                            setListResult: (
                                key: string,
                                ids: string[],
                                meta: Partial<
                                    Omit<ListState, (...) | (...) | (...) | (...) | (...)>,
                                >,
                            ) => void;
                            setListStale: (key: string, stale: boolean) => void;
                            syncMetadata: {
                                [x: string]: {
                                    origin: SyncOrigin;
                                    synced: boolean;
                                    updatedAt: number | null;
                                };
                            };
                            unpatchEntity: (type: string, id: string, keys: string[]) => void;
                            upsertEntities: (
                                type: string,
                                entries: { data: Record<(...), (...)>; id: string }[],
                            ) => void;
                            upsertEntity: (
                                type: string,
                                id: string,
                                data: Record<string, unknown>,
                            ) => void;
                        },
                    ) => void
                ),
            shouldReplace?: false,
        ): void;
        setState(
            nextStateOrUpdater:
                | GraphState
                | (
                    (
                        state: {
                            appendListResult: (
                                key: string,
                                ids: string[],
                                meta: Partial<
                                    Omit<ListState, (...) | (...) | (...) | (...) | (...)>,
                                >,
                            ) => void;
                            clearEntitySyncMetadata: (type: string, id: string) => void;
                            clearPatch: (type: string, id: string) => void;
                            entities: { [x: string]: { [x: string]: { [x: string]: unknown } } };
                            entityStates: {
                                [x: string]: {
                                    error: string | null;
                                    isFetching: boolean;
                                    lastFetched: number | null;
                                    stale: boolean;
                                };
                            };
                            ingestFetchedList: (
                                type: string,
                                entries: { data: Record<(...), (...)>; id: string }[],
                                options?: IngestFetchedListOptions,
                            ) => void;
                            insertIdInList: (
                                key: string,
                                id: string,
                                position: number | "end" | "start",
                            ) => void;
                            invalidateEntity: (type: string, id?: string) => void;
                            invalidateLists: (
                                matcher: string | ((key: string) => boolean),
                            ) => void;
                            invalidateType: (type: string) => void;
                            lists: {
                                [x: string]: {
                                    currentPage: number | null;
                                    error: string | null;
                                    hasNextPage: boolean;
                                    hasPrevPage: boolean;
                                    ids: string[];
                                    isFetching: boolean;
                                    isFetchingMore: boolean;
                                    lastError:
                                        | {
                                            cause?: ...;
                                            kind: ...;
                                            message: ...;
                                            name: ...;
                                            stack?: ...;
                                            status?: ...;
                                        }
                                        | {
                                            cause?: ...;
                                            kind: ...;
                                            message: ...;
                                            name: ...;
                                            stack?: ...;
                                            status?: ...;
                                        }
                                        | null;
                                    lastFetched: number
                                    | null;
                                    nextCursor: string | null;
                                    pageSize: number | null;
                                    prevCursor: string | null;
                                    stale: boolean;
                                    total: number | null;
                                };
                            };
                            patchEntity: (
                                type: string,
                                id: string,
                                patch: Record<string, unknown>,
                            ) => void;
                            patches: { [x: string]: { [x: string]: { [x: string]: unknown } } };
                            prependListResult: (
                                key: string,
                                ids: string[],
                                meta?: Partial<ListState>,
                            ) => void;
                            readEntity: <T = Record<string, unknown>>(
                                type: string,
                                id: string,
                            ) => T | null;
                            readEntitySnapshot: <T = Record<string, unknown>>(
                                type: string,
                                id: string,
                            ) => EntitySnapshot<(...) & (...)> | null;
                            removeEntity: (type: string, id: string) => void;
                            removeIdFromAllLists: (type: string, id: string) => void;
                            replaceEntity: (
                                type: string,
                                id: string,
                                data: Record<string, unknown>,
                            ) => void;
                            setEntityError: (
                                type: string,
                                id: string,
                                error: string | null,
                            ) => void;
                            setEntityFetched: (type: string, id: string) => void;
                            setEntityFetching: (
                                type: string,
                                id: string,
                                fetching: boolean,
                            ) => void;
                            setEntityStale: (type: string, id: string, stale: boolean) => void;
                            setEntitySyncMetadata: (
                                type: string,
                                id: string,
                                metadata: Partial<EntitySyncMetadata>,
                            ) => void;
                            setListError: (
                                key: string,
                                error: string | null,
                                typed?: EntityError | null,
                            ) => void;
                            setListFetching: (key: string, fetching: boolean) => void;
                            setListFetchingMore: (key: string, fetchingMore: boolean) => void;
                            setListResult: (
                                key: string,
                                ids: string[],
                                meta: Partial<
                                    Omit<ListState, (...) | (...) | (...) | (...) | (...)>,
                                >,
                            ) => void;
                            setListStale: (key: string, stale: boolean) => void;
                            syncMetadata: {
                                [x: string]: {
                                    origin: SyncOrigin;
                                    synced: boolean;
                                    updatedAt: number | null;
                                };
                            };
                            unpatchEntity: (type: string, id: string, keys: string[]) => void;
                            upsertEntities: (
                                type: string,
                                entries: { data: Record<(...), (...)>; id: string }[],
                            ) => void;
                            upsertEntity: (
                                type: string,
                                id: string,
                                data: Record<string, unknown>,
                            ) => void;
                        },
                    ) => void
                ),
            shouldReplace: true,
        ): void;
    },
) => void

`Optional`staleTime

staleTime?: number

type

type: string

Interface ListQueryOptions<TRaw, TEntity>

Type Parameters

Index

Properties

Properties

`Optional`enabled

`Optional`fetch

`Optional`mode

`Optional`normalize

`Optional`onError

`Optional`onSuccess

queryKey

`Optional`sideEffects

`Optional`staleTime

type

Settings

On This Page

Interface ListQueryOptions<TRaw, TEntity>

Type Parameters

Index

Properties

Properties

Optionalenabled

Optionalfetch

Optionalmode

Optionalnormalize

OptionalonError

OptionalonSuccess

queryKey

OptionalsideEffects

OptionalstaleTime

type

Settings

On This Page

`Optional`enabled

`Optional`fetch

`Optional`mode

`Optional`normalize

`Optional`onError

`Optional`onSuccess

`Optional`sideEffects

`Optional`staleTime