QueryCollectionUtils

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