Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

QueryCollectionUtils.md

287 lines5.7 KB

Defined in: packages/query-db-collection/src/query.ts:262

Utility methods available on Query Collections for direct writes and manual operations. Direct writes bypass optimistic mutations and write to the synced data store. Eager collections patch Query cache; on-demand collections revalidate scoped entries.

Extends

  • UtilsRecord

Type Parameters

TItem

TItem extends object = Record<string, unknown>

The type of items stored in the collection

TKey

TKey extends string | number = string | number

The type of the item keys

TInsertInput

TInsertInput extends object = TItem

The type accepted for insert operations

TError

TError = unknown

The type of errors that can occur during queries

Indexable

[key: string]: any

Properties

clearError()

clearError: () => Promise<void>;

Defined in: packages/query-db-collection/src/query.ts:306

Clear the error state and trigger a refetch of the query

Returns

Promise<void>

Promise that resolves when the refetch completes successfully

Throws

Error if the refetch fails


dataUpdatedAt

dataUpdatedAt: number;

Defined in: packages/query-db-collection/src/query.ts:297

Get timestamp of last successful data update (in milliseconds)


errorCount

errorCount: number;

Defined in: packages/query-db-collection/src/query.ts:289

Get the number of consecutive sync failures. Incremented only when query fails completely (not per retry attempt); reset on success.


fetchStatus

fetchStatus: "idle" | "fetching" | "paused";

Defined in: packages/query-db-collection/src/query.ts:299

Get current fetch status


isError

isError: boolean;

Defined in: packages/query-db-collection/src/query.ts:284

Check if the collection is in an error state


isFetching

isFetching: boolean;

Defined in: packages/query-db-collection/src/query.ts:291

Check if query is currently fetching (initial or background)


isLoading

isLoading: boolean;

Defined in: packages/query-db-collection/src/query.ts:295

Check if query is loading for the first time (no data yet)


isRefetching

isRefetching: boolean;

Defined in: packages/query-db-collection/src/query.ts:293

Check if query is refetching in background (not initial fetch)


lastError

lastError: TError | undefined;

Defined in: packages/query-db-collection/src/query.ts:282

Get the last error encountered by the query (if any); reset on success


refetch

refetch: RefetchFn;

Defined in: packages/query-db-collection/src/query.ts:268

Manually trigger a refetch of the query


writeBatch()

writeBatch: (callback) => void;

Defined in: packages/query-db-collection/src/query.ts:278

Execute direct writes as one atomic batch, then update or revalidate the Query cache

Parameters

callback

() => void

Returns

void


writeDelete()

writeDelete: (keys) => void;

Defined in: packages/query-db-collection/src/query.ts:274

Delete items without an optimistic update. On-demand queries revalidate their scoped cache entries.

Parameters

keys

TKey | TKey[]

Returns

void


writeInsert()

writeInsert: (data) => void;

Defined in: packages/query-db-collection/src/query.ts:270

Insert items without an optimistic update. On-demand queries revalidate their scoped cache entries.

Parameters

data

TInsertInput | TInsertInput[]

Returns

void


writeUpdate()

writeUpdate: (updates) => void;

Defined in: packages/query-db-collection/src/query.ts:272

Update items without an optimistic update. On-demand queries revalidate their scoped cache entries.

Parameters

updates

Partial<TItem> | Partial<TItem>[]

Returns

void


writeUpsert()

writeUpsert: (data) => void;

Defined in: packages/query-db-collection/src/query.ts:276

Insert or update items without an optimistic update. On-demand queries revalidate their scoped cache entries.

Parameters

data

Partial<TItem> | Partial<TItem>[]

Returns

void