QueryCollectionUtils

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

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.

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

Properties#

clearError()#

clearError: () => Promise<void>;

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

Refetch, retaining errors until a successful result applies. While a user mutation is persisting or its handler is active, this retains the Query fetch boundary so it cannot wait on publication blocked by that transaction.

Returns#

Promise<void>

Promise that resolves when the applicable refetch boundary completes

Throws#

Error if the refetch fails

dataUpdatedAt#

dataUpdatedAt: number;

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

Get timestamp of last successful data update (in milliseconds)

errorCount#

errorCount: number;

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

Get the number of consecutive sync failures. Incremented only when query fails completely (not per retry attempt); reset after a successful result applies.

fetchStatus#

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

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

Get the aggregate observer fetch status. Returns fetching if any observer is fetching, otherwise paused if any observer is paused, and idle when every observer is idle or no observers exist.

isError#

isError: boolean;

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

Check if the collection is in an error state

isFetching#

isFetching: boolean;

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

Check if query is currently fetching (initial or background)

isLoading#

isLoading: boolean;

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

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

isRefetching#

isRefetching: boolean;

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

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

lastError#

lastError: TError | undefined;

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

Get the last error encountered by the query (if any); reset after a successful result applies

refetch#

refetch: RefetchFn;

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

Manually refetch and await the applicable fetch or application boundary.

writeBatch()#

writeBatch: (callback) => Promise<void>;

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

Execute direct writes as one atomic batch. Resolves when the sync commit applies.

Parameters#

callback#

() => void

Returns#

Promise<void>

writeDelete()#

writeDelete: (keys) => Promise<void>;

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

Delete items without an optimistic update. Resolves when the sync commit applies.

Parameters#

keys#

TKey | TKey[]

Returns#

Promise<void>

writeInsert()#

writeInsert: (data) => Promise<void>;

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

Insert items without an optimistic update. Resolves when the sync commit applies.

Parameters#

data#

TInsertInput | TInsertInput[]

Returns#

Promise<void>

writeUpdate()#

writeUpdate: (updates) => Promise<void>;

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

Update items without an optimistic update. Resolves when the sync commit applies.

Parameters#

updates#

Partial<TItem> | Partial<TItem>[]

Returns#

Promise<void>

writeUpsert()#

writeUpsert: (data) => Promise<void>;

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

Insert or update items without an optimistic update. Resolves when the sync commit applies.

Parameters#

data#

Partial<TItem> | Partial<TItem>[]

Returns#

Promise<void>