@askrjs/askr/data

createDataRuntimetype

createDataRuntime: (options?: DataRuntimeOptions) => DataRuntime

Create a new, isolated {@link DataRuntime} with its own query/mutation caches.

createMutationtype

createMutation: <TInput, TResult>(options: MutationOptions<TInput, TResult>) => Mutation<TInput, TResult>

Create a reactive {@link Mutation} cell bound to the current component, running options.action on execute() and optionally invalidating affected query prefixes on success.

createQuerytype

createQuery: { <T extends {}>(options: QueryOptions<T>): Query<T>; <TInput, TResult extends {}>(definition: QueryDefinition<TInput, TResult>, input: TInput, options?: Omit<QueryOptions<TResult>, "key" | "fetch">): Query<TResult>; }

Create a reactive {@link Query} cell bound to the current component, either from inline options (key + fetch) or a reusable {@link QueryDefinition} plus its input.

createQueryCollectiontype

createQueryCollection: <TInput, TResult extends {}, TKey extends QueryCollectionKey = string>(options: QueryCollectionOptions<TInput, TResult, TKey>) => QueryCollection<TInput, TResult, TKey>

Create one lifecycle-owned collection of dynamically keyed readers for a reusable query definition, with bounded collection-started fetches.

createQueryPrefetchContexttype

createQueryPrefetchContext: (options?: { runtime?: DataRuntime; registry?: ServerQueryRegistry; request?: Request; signal?: AbortSignal; mode?: "ssr" | "spa"; telemetry?: CoreTelemetry; }) => QueryPrefetchContext

Create a {@link QueryPrefetchContext} for prefetching query data ahead of render, e.g. during SSR route resolution.

DataRuntimetype

DataRuntime: any

Isolated cache/state container backing queries and mutations, e.g. one per test or request.

queryCache

readonly queryCache: Map<string, unknown>;

queryData

readonly queryData: Map<string, unknown>;

DataRuntimeOptionstype

DataRuntimeOptions: any

Options for {@link createDataRuntime}.

queryCache

queryCache?: Map<string, unknown>;

queryData

queryData?: Map<string, unknown>;

defineQuerytype

defineQuery: <TInput, TResult extends {}>(definition: QueryDefinition<TInput, TResult>) => QueryDefinition<TInput, TResult>

Freeze and return a reusable {@link QueryDefinition}.

defineServerQueriestype

defineServerQueries: (...entries: readonly ServerQueryEntry<any, any>[]) => ServerQueryRegistry

Build a {@link ServerQueryRegistry} from one or more {@link serveQuery} entries.

dehydrateDataRuntimetype

dehydrateDataRuntime: (runtime: DataRuntime) => Record<string, unknown>

Extract a runtime's cached query data into a JSON-serializable snapshot. Throws a TypeError naming the key and path of any value that would not survive JSON transport unchanged (for example a Date, Map, or bigint).

disposeDataRuntimetype

disposeDataRuntime: (runtime: DataRuntime) => void

Terminally retire an isolated runtime. The shared default cannot be disposed.

getDefaultDataRuntimetype

getDefaultDataRuntime: () => DataRuntime

Get the process-wide default {@link DataRuntime} used when none is provided explicitly.

hydrateDataRuntimetype

hydrateDataRuntime: (runtime: DataRuntime, data: unknown) => void

Load a {@link dehydrateDataRuntime} snapshot back into a runtime's query cache.

invalidatetype

invalidate: (prefix: string, options?: InvalidateOptions) => void

Mark all cached queries under prefix as stale, triggering a refresh. Matching is by :-delimited segment: a key matches when it equals prefix, when prefix ends in :, or when the key continues prefix at a : ('user:1' matches user:1:posts but not user:10). Only : is a segment boundary; the empty prefix matches every key.

invalidateOnIntervaltype

invalidateOnInterval: (prefix: string, options: InvalidateOnIntervalOptions) => void

Periodically invalidate queries matching prefix on a fixed interval, optionally gated by active route, document visibility, or window focus. prefix matches key segments the same way as {@link invalidate}.

InvalidateOnIntervalOptionstype

InvalidateOnIntervalOptions: any

Options for {@link invalidateOnInterval}.

intervalMs

intervalMs: number;

activeOn

activeOn?: string | readonly string[];

visibleOnly

visibleOnly?: boolean;

focusedOnly

focusedOnly?: boolean;

InvalidateOptionstype

InvalidateOptions: any

Options for {@link invalidate} and {@link QueryScope.invalidate}.

markPendingWrite

markPendingWrite?: boolean;

runtime

runtime?: DataRuntime;

Mutationtype

Mutation: MutationControls<TInput, TResult> &
  (MutationIdle | MutationPending | MutationSuccess<TResult> | MutationError)

Reactive state for a mutation cell: status, error/result, and execute/abort/reset controls.

MutationOptionstype

MutationOptions: {
  /** Stable identity used by runtime-scoped mutation test overrides. */
  key?: string;
  action: (
    input: TInput,
    ctx: {
      signal: AbortSignal;
    }
  ) => Promise<TResult>;
  /** Apply a synchronous optimistic change. Return a rollback for failure or abort. */
  optimistic?: (
    input: TInput,
    ctx: { signal: AbortSignal }
  ) => void | (() => void);
  /**
   * Query prefixes to invalidate after success, matched by `:`-delimited
   * segment the same way as {@link invalidate}.
   */
  affects?: (input: TInput, result: TResult) => string[];
  afterSuccess?: 'invalidate';
  runtime?: DataRuntime;
}

Options for {@link createMutation}.

prefetchQuerytype

prefetchQuery: <TInput, TResult extends {}>(context: QueryPrefetchContext, query: QueryDefinition<TInput, TResult>, input: TInput) => Promise<boolean>

Prefetch query with input into a {@link QueryPrefetchContext}'s runtime.

Querytype

Query: QueryControls &
  (
    | QueryLoading
    | QueryFresh<T>
    | QueryRefreshing<T>
    | QueryPendingWrite<T>
    | QueryStaleValue<T>
    | QueryStaleErrorWithValue<T>
    | QueryStaleError
  )

Reactive read state for a query cell: data, loading/refresh flags, and freshness.

QueryCollectiontype

QueryCollection: any

Aggregate reactive state for a lifecycle-owned dynamic query collection.

entries

readonly entries: readonly QueryCollectionEntry<TInput, TResult, TKey>[];

loading

readonly loading: boolean;

settled

readonly settled: boolean;

results

readonly results: ReadonlyMap<TKey, TResult>;

errors

readonly errors: ReadonlyMap<TKey, {}>;

get

get(key: TKey): QueryCollectionEntry<TInput, TResult, TKey> | undefined;

retry

retry(key: TKey): Promise<void>;

QueryCollectionEntrytype

QueryCollectionEntry: any

One keyed input and its underlying cache-backed query reader.

key

readonly key: TKey;

input

readonly input: TInput;

query

readonly query: Query<TResult>;

QueryCollectionKeytype

QueryCollectionKey: string | number | symbol

Stable identity for one member of a {@link QueryCollection}.

QueryCollectionOptionstype

QueryCollectionOptions: any

Options for {@link createQueryCollection}.

query

readonly query: QueryDefinition<TInput, TResult>;

inputs

readonly inputs: () => readonly TInput[];

key

readonly key: (input: TInput) => TKey;

concurrency

readonly concurrency?: number;

runtime

readonly runtime?: DataRuntime;

QueryConsistencytype

QueryConsistency: 'fresh' | 'stale' | 'refreshing' | 'pending-write'

Freshness classification for a {@link Query}'s current data.

QueryDefinitiontype

QueryDefinition: any

Reusable query definition for {@link defineQuery}: key, fetcher, and freshness checks.

key

readonly key: (input: TInput) => string;

fetch

readonly fetch: ( input: TInput, context: { signal: AbortSignal; } ) => Promise<TResult>;

isConsistent

readonly isConsistent?: (data: TResult) => boolean;

reconcile

readonly reconcile?: ( data: TResult, context: { key: string; } ) => Promise<boolean> | boolean;

QueryKeyParttype

QueryKeyPart: | string
  | number
  | boolean
  | null
  | undefined
  | readonly QueryKeyPart[]
  | {
      readonly [key: string]: QueryKeyPart;
    }

A JSON-serializable value usable as part of a query key or invalidation prefix.

QueryPrefetchContexttype

QueryPrefetchContext: any

Context passed to server prefetch callbacks, exposing a scoped prefetch helper.

runtime

readonly runtime: DataRuntime;

request

readonly request?: Request;

signal

Effective fetch signal; native runtimes compose caller cancellation and retirement.

mode

readonly mode: 'ssr' | 'spa';

prefetch

prefetch<TInput, TResult extends {}>( query: QueryDefinition<TInput, TResult>, input: TInput ): Promise<boolean>;

queryScopetype

queryScope: (namespace: string, options?: Pick<InvalidateOptions, "runtime">) => QueryScope

Create a {@link QueryScope} that namespaces keys and can bind invalidations to a runtime.

QueryScopetype

QueryScope: any

Namespaced key-building and invalidation helper returned by {@link queryScope}.

key

key(...parts: QueryKeyPart[]): string;

prefix

prefix(...parts: QueryKeyPart[]): string;

invalidate

invalidate(parts: readonly QueryKeyPart[], options?: InvalidateOptions): void;

QueryStaleReasontype

QueryStaleReason: 'aborted' | 'error' | 'inconsistent'

Why a {@link Query} is stale.

refreshOnActivitytype

refreshOnActivity: (prefix: string, options: RefreshOnActivityOptions) => void

Refresh live queries on browser activity, with an explicit freshness age.

RefreshOnActivityOptionstype

RefreshOnActivityOptions: any

Component-owned refresh policy for browser focus/visibility and reconnect.

staleTimeMs

Age since successful completion (or initial data). Zero refreshes on every event.

focus

Listen to window focus and visible document transitions. Defaults to true.

online

Listen to the window online hint. Defaults to true.

enabled

Disable listeners without changing hook order. Defaults to true.

runtime

runtime?: DataRuntime;

serveQuerytype

serveQuery: <TInput, TResult extends {}>(query: QueryDefinition<TInput, TResult>, handler: ServerQueryHandler<TInput, TResult>) => ServerQueryEntry<TInput, TResult>

Pair a {@link QueryDefinition} with the server-side handler that resolves it.

ServerQueryEntrytype

ServerQueryEntry: any

A query paired with the server handler that resolves it, produced by {@link serveQuery}.

query

readonly query: QueryDefinition<TInput, TResult>;

handler

readonly handler: ServerQueryHandler<TInput, TResult>;

ServerQueryHandlertype

ServerQueryHandler: (context: {
  input: TInput;
  request?: Request;
  signal: AbortSignal;
}) => Promise<TResult> | TResult

Server-side handler that resolves a {@link QueryDefinition}'s data for serveQuery.

ServerQueryRegistrytype

ServerQueryRegistry: any

Lookup table of server handlers keyed by their {@link QueryDefinition}, built by {@link defineServerQueries}.

entries

readonly entries: readonly ServerQueryEntry<unknown, {}>[];

get

get<TInput, TResult extends {}>( query: QueryDefinition<TInput, TResult> ): ServerQueryHandler<TInput, TResult> | undefined;