# @askrjs/askr/data

> Published API exports for @askrjs/askr/data.

Source: [https://askrjs.com/docs/reference/api/askr/data](https://askrjs.com/docs/reference/api/askr/data)

Status: stable. Packages: @askrjs/askr/data.

**Published packages are authoritative.** Examples may lag behind a published contract. When guidance differs, verify the exports and TypeScript declarations in your installed package, then file an issue.

## Exports

This entrypoint publishes 35 exports from the declarations shipped by @askrjs/askr.

### `createDataRuntime`

```ts
createDataRuntime: (options?: DataRuntimeOptions) => DataRuntime
```

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

### `createMutation`

```ts
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.

### `createQuery`

```ts
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.

### `createQueryCollection`

```ts
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.

### `createQueryPrefetchContext`

```ts
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.

### `DataRuntime`

```ts
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>;

- `queryTestOverrides`: Test-only query overrides keyed by the canonical query key.

- `mutationTestOverrides`: Test-only mutation overrides keyed by the canonical mutation key.

### `DataRuntimeOptions`

```ts
DataRuntimeOptions: any
```

Options for {@link createDataRuntime}.

- `queryCache`: queryCache?: Map<string, unknown>;

- `queryData`: queryData?: Map<string, unknown>;

- `queryTestOverrides`: queryTestOverrides?: Map<string, unknown>;

- `mutationTestOverrides`: mutationTestOverrides?: Map<string, unknown>;

### `defineQuery`

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

Freeze and return a reusable {@link QueryDefinition}.

### `defineServerQueries`

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

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

### `dehydrateDataRuntime`

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

Extract a runtime's cached query data into a JSON-serializable snapshot, dropping non-serializable values.

### `getDefaultDataRuntime`

```ts
getDefaultDataRuntime: () => DataRuntime
```

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

### `hydrateDataRuntime`

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

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

### `invalidate`

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

Mark all cached queries whose key starts with `prefix` as stale, triggering a refresh.

### `invalidateOnInterval`

```ts
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.

### `InvalidateOnIntervalOptions`

```ts
InvalidateOnIntervalOptions: any
```

Options for {@link invalidateOnInterval}.

- `intervalMs`: intervalMs: number;

- `activeOn`: activeOn?: string | readonly string[];

- `visibleOnly`: visibleOnly?: boolean;

- `focusedOnly`: focusedOnly?: boolean;

### `InvalidateOptions`

```ts
InvalidateOptions: any
```

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

- `markPendingWrite`: markPendingWrite?: boolean;

- `runtime`: runtime?: DataRuntime;

### `Mutation`

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

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

### `MutationOptions`

```ts
MutationOptions: {
  /** Stable identity used by runtime-scoped mutation test overrides. */
  key?: string;
  action: (input: TInput, ctx: {
    signal: AbortSignal;
  }) => Promise<TResult>;
  affects?: (input: TInput, result: TResult) => string[];
  afterSuccess?: 'invalidate';
  runtime?: DataRuntime;
}
```

Options for {@link createMutation}.

### `prefetchQuery`

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

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

### `Query`

```ts
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.

### `QueryCollection`

```ts
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>;

### `QueryCollectionEntry`

```ts
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>;

### `QueryCollectionKey`

```ts
QueryCollectionKey: string | number | symbol
```

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

### `QueryCollectionOptions`

```ts
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;

### `QueryConsistency`

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

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

### `QueryDefinition`

```ts
QueryDefinition: any
```

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

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

- `fetch`: readonly fetch: (context: TInput & {
    signal: AbortSignal;
  }) => Promise<TResult>;

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

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

### `QueryKeyPart`

```ts
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.

### `QueryPrefetchContext`

```ts
QueryPrefetchContext: any
```

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

- `runtime`: readonly runtime: DataRuntime;

- `request`: readonly request?: Request;

- `signal`: readonly signal: AbortSignal;

- `mode`: readonly mode: 'ssr' | 'spa';

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

### `queryScope`

```ts
queryScope: (namespace: string) => QueryScope
```

Create a {@link QueryScope} that namespaces keys and invalidations under `namespace`.

### `QueryScope`

```ts
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;

### `QueryStaleReason`

```ts
QueryStaleReason: 'aborted' | 'error' | 'inconsistent'
```

Why a {@link Query} is stale.

### `serveQuery`

```ts
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.

### `ServerQueryEntry`

```ts
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>;

### `ServerQueryHandler`

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

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

### `ServerQueryRegistry`

```ts
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;

## Documentation navigation

[Previous](https://askrjs.com/docs/reference/api/askr/resources/index.md) | [Next](https://askrjs.com/docs/reference/api/askr/testing/index.md)