@uniflowed/query

type

QueryFilters

export type QueryFilters = {|
  /** A key prefix, or an exact key with `exact`. */
  readonly queryKey?: QueryKey,
  readonly exact?: boolean,
  /** `active` is "somebody is watching"; see the module docs. */
  readonly type?: "all" | "active" | "inactive",
  readonly predicate?: (query: Query<mixed>) => boolean,
|};

Which entries an operation applies to.

Everything is optional and everything narrows: no filter at all means every entry, which is what invalidateQueries() with no argument means and why that call is worth writing.

type

QueryDefaults

export type QueryDefaults = {|
  readonly staleTime?: number,
  readonly gcTime?: number,
  readonly retry?: RetryPolicy,
  readonly retryDelay?: RetryDelay,
  readonly refetchInterval?: number | null,
  readonly refetchOnWindowFocus?: boolean,
  readonly refetchOnReconnect?: boolean,
|};

What a whole application decides once.

type

FetchQueryOptions

export type FetchQueryOptions<TData> = {|
  readonly queryKey: QueryKey,
  readonly queryFn: (context: FetchContext<TData>) => Promise<TData>,
  readonly staleTime?: number,
  readonly gcTime?: number,
  readonly retry?: RetryPolicy,
  readonly retryDelay?: RetryDelay,
|};

What fetchQuery needs, which is a query without anything React-shaped.

type

InfiniteData

export type InfiniteData<TPage, TParam> = {|
  readonly pages: $ReadOnlyArray<TPage>,
  readonly pageParams: $ReadOnlyArray<TParam>,
|};

The value a paged entry holds.

type

InfinitePageContext

export type InfinitePageContext<TParam> = {|
  readonly queryKey: QueryKey,
  readonly signal: AbortSignal,
  readonly pageParam: TParam,
  readonly direction: FetchDirection,
|};

What the query function is called with, once per page.

type

PageParamFn

export type PageParamFn<TPage, TParam> = (
  lastPage: TPage,
  allPages: $ReadOnlyArray<TPage>,
  lastPageParam: TParam,
  allPageParams: $ReadOnlyArray<TParam>,
) => TParam | null | void;

Where the next page starts, or null when there is no next page.

Returning null is how the list ends, and it is why hasNextPage can be answered without an extra request: the server already said so in the answer it gave for the last page.

type

InfiniteQueryResult

export type InfiniteQueryResult<TSelected> = {|
  ...QueryResult<TSelected>,
  readonly hasNextPage: boolean,
  readonly hasPreviousPage: boolean,
  readonly isFetchingNextPage: boolean,
  readonly isFetchingPreviousPage: boolean,
  readonly fetchNextPage: () => Promise<void>,
  readonly fetchPreviousPage: () => Promise<void>,
|};

An ordinary result, plus the two ends of the list.

function

infinitePages

export function infinitePages<TPage, TParam>(
  options: InfiniteQueryOptions<TPage, TParam, mixed>,
  direction: FetchDirection | null,
): Fetcher<InfiniteData<TPage, TParam>> { ... }

The function the cache calls to fill a paged entry.

direction decides which of the three things it means: extend the list forward, extend it backward, or — when there is no direction — refetch every page the entry already holds. A first fetch has nothing to extend, so it asks for initialPageParam whatever the direction says.

function

hasMore

export function hasMore<TPage, TParam>(
  options: InfiniteQueryOptions<TPage, TParam, mixed>,
  data: InfiniteData<TPage, TParam> | void,
  towards: FetchDirection,
): boolean { ... }

Whether the server said there is another page after the ones held.

class

InfiniteQueryObserver

export class InfiniteQueryObserver<TPage, TParam, TSelected> extends QueryObserver<
  InfiniteData<TPage, TParam>,
  TSelected,
> { ... }

The observer for a paged query.

Everything about watching, fetching, retrying and snapshotting is inherited; the two differences are that the entry is filled a page at a time and that the snapshot carries the controls for the two ends of the list.

type

QueryKey

export type QueryKey = $ReadOnlyArray<mixed>;

A key, as a caller writes it: ["user", id].

function

hashKey

export function hashKey(key: QueryKey): string { ... }

A key as a string, stable across member order inside object members.

Two keys with the same hash are the same request by definition. That is the contract every other module in this package relies on, including the one that decides a component does not need to resubscribe.

function

matchesKey

export function matchesKey(key: QueryKey, pattern: QueryKey, exact: boolean = false): boolean { ... }

Whether key is described by pattern.

By default pattern is a prefix: ["users"] matches ["users", 1], and ["users", {done: true}] matches ["users", {done: true, page: 2}] — object members match partially, so a filter can name the parts of a parameter record it cares about and ignore the rest.

With exact, the two must hash identically. That is the option for "this one entry and not the list it belongs to", which is the difference between refreshing a row and refetching a table.

type

MutationCallbacks

export type MutationCallbacks<TVariables, TData, TContext> = {|
  readonly onSuccess?: (data: TData, variables: TVariables, context: TContext | void) => mixed,
  readonly onError?: (error: Error, variables: TVariables, context: TContext | void) => mixed,
  readonly onSettled?: (
    data: TData | void,
    error: Error | null,
    variables: TVariables,
    context: TContext | void,
  ) => mixed,
|};

The callbacks a single call may add.

Both sets run — the ones on the hook and the ones on the call — with the hook's first. The hook's are the ones that keep the cache correct and must not be skippable by a caller who only wanted a toast.

type

ResolvedMutationOptions

export type ResolvedMutationOptions<TVariables, TData, TContext> = {|
  ...MutationOptions<TVariables, TData, TContext>,
  readonly retry: RetryPolicy,
  readonly retryDelay: RetryDelay,
|};

The same options with the client's defaults filled in.

type

MutationResult

export type MutationResult<TVariables, TData, TContext> = {|
  readonly data: TData | void,
  readonly error: Error | null,
  readonly status: MutationStatus,
  readonly variables: TVariables | void,
  readonly failureCount: number,
  readonly isIdle: boolean,
  readonly isPending: boolean,
  readonly isSuccess: boolean,
  readonly isError: boolean,
  /** Fire and forget. The failure is in `error`, not in a rejected promise. */
  readonly mutate: (
    variables: TVariables,
    callbacks?: MutationCallbacks<TVariables, TData, TContext>,
  ) => void,
  /** The same call, awaited. Rejects, so a caller can branch on the failure. */
  readonly mutateAsync: (
    variables: TVariables,
    callbacks?: MutationCallbacks<TVariables, TData, TContext>,
  ) => Promise<TData>,
  readonly reset: () => void,
|};

What a mutation looks like to a component.

type

QueryOptions

export type QueryOptions<TData, TSelected = TData> = {|
  readonly queryKey: QueryKey,
  readonly queryFn: (context: FetchContext<TData>) => Promise<TData>,
  /** `false` means "do not fetch this yet"; a manual refetch still works. */
  readonly enabled?: boolean,
  /** How long an answer counts as fresh. `Infinity` means "until I say so". */
  readonly staleTime?: number,
  /** How long an unwatched entry is kept before it is collected. */
  readonly gcTime?: number,
  readonly retry?: RetryPolicy,
  readonly retryDelay?: RetryDelay,
  /** Narrow the data. See the module docs for what it buys. */
  readonly select?: (data: TData) => TSelected,
  /** Shown while there is nothing yet; never written to the cache. */
  readonly placeholderData?: mixed | ((previous: TData | void) => mixed),
  readonly refetchInterval?: number | null,
  readonly refetchOnWindowFocus?: boolean,
  readonly refetchOnReconnect?: boolean,
|};

How a component asks for a key.

Everything except the key and the function has a default on the client, so an application sets staleTime once instead of at every call site.

type

ResolvedQueryOptions

export type ResolvedQueryOptions<TData, TSelected = TData> = {|
  readonly queryKey: QueryKey,
  readonly queryFn: (context: FetchContext<TData>) => Promise<TData>,
  readonly enabled: boolean,
  readonly staleTime: number,
  readonly gcTime: number,
  readonly retry: RetryPolicy,
  readonly retryDelay: RetryDelay,
  readonly select?: (data: TData) => TSelected,
  readonly placeholderData?: mixed | ((previous: TData | void) => mixed),
  readonly refetchInterval: number | null,
  readonly refetchOnWindowFocus: boolean,
  readonly refetchOnReconnect: boolean,
|};

The same options with the client's defaults filled in.

type

QueryResult

export type QueryResult<T> = {|
  readonly data: T | void,
  readonly error: Error | null,
  readonly status: QueryStatus,
  readonly fetchStatus: FetchStatus,
  /** There is no answer yet, not even a failed one. */
  readonly isPending: boolean,
  /** The first load: pending *and* a request is in flight. */
  readonly isLoading: boolean,
  readonly isSuccess: boolean,
  readonly isError: boolean,
  /** A request is in flight, first load or refresh. */
  readonly isFetching: boolean,
  /** A request is in flight over data that is already on screen. */
  readonly isRefetching: boolean,
  readonly isStale: boolean,
  readonly isPlaceholderData: boolean,
  /** Failed attempts in the request in flight, for "retrying (2 of 3)". */
  readonly failureCount: number,
  /** Refetch now, superseding anything in flight. Never rejects. */
  readonly refetch: () => Promise<void>,
|};

What a component sees.

Deliberately without timestamps. A clock reading in a render-visible snapshot re-renders every observer on every successful refresh, even when the answer is identical — which is exactly what structural sharing exists to prevent, and it also defeats select: narrowing to user.name is only worth having if the snapshot is insensitive to the fields it discarded, and a dataUpdatedAt beside it moves whenever *any* field does.

So the snapshot carries decisions rather than readings. isStale is the one the clock reaches, because it is the one a component can act on. client.getQueryState(key) has dataUpdatedAt, checkedAt and the rest for a devtool or a "last updated" label that wants them.

type

PresenceEvent

export type PresenceEvent = "focus" | "online";

Which of the two ambient facts changed.

type

QueryStatus

export type QueryStatus = "pending" | "success" | "error";

Whether the entry has an answer yet, and whether that answer is a failure.

type

FetchStatus

export type FetchStatus = "idle" | "fetching";

Whether a request is in flight, independent of whether there is data.

type

FetchDirection

export type FetchDirection = "forward" | "backward";

Which end of a paged query is being extended.

type

QueryState

export type QueryState<T> = {|
  readonly status: QueryStatus,
  readonly fetchStatus: FetchStatus,
  readonly data: T | void,
  readonly dataUpdatedAt: number,
  readonly checkedAt: number,
  readonly error: Error | null,
  readonly errorUpdatedAt: number,
  /** Failed attempts in the current request, reset when one is started. */
  readonly failureCount: number,
  readonly failureReason: Error | null,
  /** Set by invalidation: stale regardless of the clock. */
  readonly invalidated: boolean,
  readonly direction: FetchDirection | null,
|};

Everything known about one key.

dataUpdatedAt and checkedAt are two different facts and conflating them is a mistake with a visible cost. checkedAt is when the server was last asked and answered; it is what staleness is measured from. dataUpdatedAt is when the answer last *changed*. A poll that confirms the same rows moves checkedAt and leaves dataUpdatedAt alone — which is exactly what lets a component that displays "updated 2 minutes ago" stay still while the cache quietly keeps itself fresh underneath.

type

FetchContext

export type FetchContext<T> = {|
  readonly queryKey: QueryKey,
  readonly signal: AbortSignal,
  readonly previousData: T | void,
  readonly failureCount: number,
|};

What a query function is called with.

signal is a getter; see the module docs for what reading it means. previousData is what the cache holds right now, which a paged query needs and an ordinary one can use for a conditional request.

type

Fetcher

export type Fetcher<T> = (context: FetchContext<T>) => Promise<T>;

How an entry is refilled. One attempt; retrying is [runWithRetry]'s job.

interface

QueryWatcher

export interface QueryWatcher {
  /** The state changed. Whether that is worth a render is the watcher's call. */
  onQueryUpdate(): void;
  /** Whether this watcher currently wants the key fetched at all. */
  isEnabled(): boolean;
  /** Refetch now, superseding anything in flight. Never rejects. */
  refetchNow(): Promise<void>;
}

What a query needs from the thing watching it.

An interface rather than a concrete observer type, so this module does not depend on the React-facing one. A query has to be able to say "somebody refresh me" during invalidation, and it must not have to know what a React hook is to say it.

variable

DEFAULT_GC_TIME

export const DEFAULT_GC_TIME: number = 5 * 60_000;

How long an unobserved entry is kept, so a quick navigation back is free.

variable

EMPTY_STATE

export const EMPTY_STATE: QueryState<empty> = Object.freeze({
  status: "pending",
  fetchStatus: "idle",
  data: undefined,
  dataUpdatedAt: 0,
  checkedAt: 0,
  error: null,
  errorUpdatedAt: 0,
  failureCount: 0,
  failureReason: null,
  invalidated: false,
  direction: null,
});

What is known about a key nobody has fetched.

One shared object rather than one per entry, and safe to share precisely because state is replaced rather than edited. It is also what a component reads on its first render, before the effect that builds the entry has run — reading a key that does not exist yet must not create it.

component

QueryClientProvider

export component QueryClientProvider(client: QueryClient, children: React.Node) { ... }

Make a client available to the tree.

Required rather than falling back to a module-level default. A default is shared with every other tree in the process, which on a server means one reader's data is in the cache the next request renders from, and in a test means the previous test's answer decides this one's result.

function

useQueryClient

export function useQueryClient(): QueryClient { ... }

The client this subtree uses.

function

useQuery

export function useQuery<TData, TSelected = TData>(
  options: QueryOptions<TData, TSelected>,
): QueryResult<TSelected> { ... }

Read a key, fetching it when it is missing or stale.

A cached answer is returned immediately and refreshed behind it, so navigating back to a page shows it at once. isFetching says a request is in flight; isPending says there is nothing to show yet — conflating those is why applications flash a spinner over data they already have.

function

useInfiniteQuery

export function useInfiniteQuery<TPage, TParam, TSelected = InfiniteData<TPage, TParam>>(
  options: InfiniteQueryOptions<TPage, TParam, TSelected>,
): InfiniteQueryResult<TSelected> { ... }

Read a key that arrives a page at a time.

One cache entry holding every page, so the list is invalidated, refetched and collected as the single thing the reader sees. See infinite.js for why the alternative — a query per page — cannot stay coherent.

function

useMutation

export function useMutation<TVariables, TData, TContext = mixed>(
  options: MutationOptions<TVariables, TData, TContext>,
): MutationResult<TVariables, TData, TContext> { ... }

Run something that changes state, with the callbacks a rollback needs.

mutate is called from an event, so the closure it captures is the one from the render the reader was looking at, and there is nothing to go stale. mutateAsync is the same call for a caller who needs to await it — the difference is only whether a failure arrives as a rejected promise or as error on the next render.

type

RetryPolicy

export type RetryPolicy = boolean | number | ((failureCount: number, error: Error) => boolean);

Whether a failed attempt should be tried again.

false never retries, true retries forever, a number is a count of *retries* — 2 means three attempts in total — and a predicate is given the number of failures so far and the last error, which is the only form that can tell a 500 from a 404.

type

RetryDelay

export type RetryDelay = number | ((failureCount: number, error: Error) => number);

How long to wait before the next attempt, in milliseconds.

class

CancelledError

export class CancelledError extends Error { ... }

What a cancelled request rejects with.

A real class rather than a string, because the code that swallows a cancellation must not also swallow a genuine failure — telling them apart by message would break the first time someone's API said "aborted".

function

backoffDelay

export function backoffDelay(failureCount: number): number { ... }

Doubling backoff from one second, capped at thirty.

function

runWithRetry

export function runWithRetry<T>(options: {|
  readonly attempt: (failureCount: number) => Promise<T>,
  readonly retry: RetryPolicy,
  readonly retryDelay: RetryDelay,
  readonly signal: AbortSignal,
  readonly onFailure?: (failureCount: number, error: Error) => void,
|}): Promise<T> { ... }

Run attempt until it succeeds, the policy gives up, or the signal fires.

onFailure is called after every failed attempt with the running count, so the caller can put "retrying, attempt 2" on screen. It is not called for a cancellation: nobody is waiting for that answer, so there is nothing to report.

The error a caller finally sees is the *last* one. An early failure that was retried past is not the reason the request failed; the one that exhausted the policy is.

function

asError

export function asError(thrown: mixed): Error { ... }

Whatever was thrown, as an Error, because state has to hold one shape.

function

isPlainObject

export function isPlainObject(value: mixed): boolean { ... }

Whether value is an object literal rather than a class instance.

Object.prototype or a null prototype, and nothing else: the walk may only rebuild things it can rebuild faithfully, and a class instance rebuilt as an object literal has silently lost its methods.

function

structuralShare

export function structuralShare<T>(previous: mixed, next: T): T { ... }

next, with every deeply-equal subtree replaced by previous's reference.

Returns previous itself when the two are deeply equal, which is the whole point: an unchanged response must not produce a new identity, or nothing downstream can tell that it was unchanged.

The shape of the *result* is always next's shape. Sharing never resurrects a key that next dropped or a row it removed; it only reuses references for the parts that are still there and still equal.

function

shallowEqual

export function shallowEqual(left: { +[string]: mixed }, right: { +[string]: mixed }): boolean { ... }

Whether two records have the same keys and Object.is-identical values.

This is how an observer decides whether the snapshot it just built is the one it already returned. It is a *shallow* comparison on purpose: every field it compares is either a primitive or a value that already went through [structuralShare], so identity is the correct question and a deep walk here would be paying twice for an answer we already have.