@pinia/colada-plugin-retry 0.1.3 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,1571 +1,46 @@
1
- import * as vue0 from "vue";
2
- import { ComponentInternalInstance, ComputedRef, EffectScope, MaybeRefOrGetter, Plugin, ShallowRef } from "vue";
3
- import * as pinia0 from "pinia";
4
- import { Pinia } from "pinia";
1
+ import { PiniaColadaPluginContext } from "@pinia/colada";
2
+
3
+ //#region src/retry.d.ts
5
4
 
6
- //#region ../../src/data-state.d.ts
7
- /**
8
- * The status of data.
9
- * - `pending`: initial state
10
- * - `error`: has an error
11
- * - `success`: has data
12
- */
13
- type DataStateStatus = 'pending' | 'error' | 'success';
14
- /**
15
- * Internal base type for data state.
16
- * @internal
17
- */
18
- interface _DataState_Base<TData, TError> {
19
- /**
20
- * The last successfully resolved data.
21
- */
22
- data: TData;
23
- /**
24
- * The last rejected error.
25
- */
26
- error: TError;
27
- /**
28
- * The status of the data.
29
- * @see {@link DataStateStatus}
30
- */
31
- status: DataStateStatus;
32
- }
33
- interface DataState_Success<TData, TDataInitial> extends _DataState_Base<TData | Exclude<TDataInitial, undefined>, null> {
34
- status: 'success';
35
- }
36
- interface DataState_Error<TData, TError, TDataInitial> extends _DataState_Base<TData | TDataInitial, TError> {
37
- status: 'error';
38
- }
39
- interface DataState_Pending<TDataInitial> extends _DataState_Base<TDataInitial, null> {
40
- status: 'pending';
41
- }
42
- /**
43
- * Possible states for data based on its status.
44
- */
45
- type DataState<TData, TError, TDataInitial = undefined> = DataState_Success<TData, TDataInitial> | DataState_Error<TData, TError, TDataInitial> | DataState_Pending<TDataInitial>;
46
- /**
47
- * The status of an async operation tied to pinia colada e.g. queries and mutations.
48
- * - `idle`: not loading
49
- * - `loading`: currently loading
50
- */
51
- type AsyncStatus = 'idle' | 'loading';
52
- //#endregion
53
- //#region ../../src/types-extension.d.ts
54
- /**
55
- * Allows you to extend the default types of the library.
56
- *
57
- * @example
58
- * ```ts
59
- * // types-extension.d.ts
60
- * import '@pinia/colada'
61
- * export {}
62
- * declare module '@pinia/colada' {
63
- * interface TypesConfig {
64
- * defaultError: MyCustomError
65
- * queryMeta: {
66
- * onErrorMessage?: string
67
- * }
68
- * }
69
- * }
70
- * ```
71
- */
72
- interface TypesConfig {}
73
- /**
74
- * The default error type used.
75
- * @internal
76
- */
77
- type ErrorDefault = TypesConfig extends Record<'defaultError', infer E> ? E : Error;
78
- /**
79
- * The meta information stored alongside each query inferred from the {@link TypesConfig}.
80
- * @internal
81
- */
82
- type QueryMeta = TypesConfig extends Record<'queryMeta', infer M> ? M : Record<string, unknown>;
83
- //#endregion
84
- //#region ../../src/entry-keys.d.ts
85
- declare function toCacheKey(key: undefined): undefined;
86
- declare function toCacheKey(key: EntryKey): string;
87
- declare function toCacheKey(key: EntryKey | undefined): string | undefined;
88
- /**
89
- * Used for keys
90
- *
91
- * @internal
92
- */
93
- type JSONPrimitive = string | number | boolean | null;
94
- /**
95
- * Used for keys
96
- *
97
- * @internal
98
- */
99
- type JSONValue = JSONPrimitive | JSONObject | JSONArray;
100
- /**
101
- * Used for keys. Interface to avoid deep recursion.
102
- *
103
- * @internal
104
- */
105
- type JSONObject = object;
106
- /**
107
- * Used for keys. Interface to avoid deep recursion.
108
- *
109
- * @internal
110
- */
111
- interface JSONArray extends Array<JSONValue> {}
112
- /**
113
- * Key used to identify a query or a mutation. Must be a JSON serializable
114
- * value. Type is unknwon to avoid annoying type errors like recursive types
115
- * and not being able to assign an interface to it due to its index signature.
116
- */
117
- type EntryKey = readonly JSONValue[];
118
- /**
119
- * Internal symbol used to tag the data type of the entry key.
120
- *
121
- * @internal
122
- */
123
- declare const ENTRY_DATA_TAG: unique symbol;
124
- /**
125
- * Internal symbol used to tag the error type of the entry key.
126
- *
127
- * @internal
128
- */
129
- declare const ENTRY_ERROR_TAG: unique symbol;
130
- /**
131
- * Internal symbol used to tag the data initial type of the entry key.
132
- *
133
- * @internal
134
- */
135
- declare const ENTRY_DATA_INITIAL_TAG: unique symbol;
136
- /**
137
- * Same as {@link EntryKey} but with a data tag that allows inference of the data type.
138
- * Used by `defineQueryOptions()`.
139
- */
140
- type EntryKeyTagged<TData, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined> = EntryKey & {
141
- [ENTRY_DATA_TAG]: TData;
142
- [ENTRY_ERROR_TAG]: TError;
143
- [ENTRY_DATA_INITIAL_TAG]: TDataInitial;
144
- };
145
- //#endregion
146
- //#region ../../src/query-options.d.ts
147
- /**
148
- * Possible values for `refetchOnMount`, `refetchOnWindowFocus`, and `refetchOnReconnect`.
149
- * `true` refetches if data is stale (calles `refresh()`), `false` never refetches, `'always'` always refetches.
150
- */
151
- type RefetchOnControl = boolean | 'always';
152
- /**
153
- * Options for queries that can be globally overridden.
154
- */
155
- interface UseQueryOptionsGlobal {
156
- /**
157
- * Whether the query should be enabled or not. If `false`, the query will not
158
- * be executed until `refetch()` or `refresh()` is called. If it becomes
159
- * `true`, the query will be refreshed.
160
- */
161
- enabled?: MaybeRefOrGetter<boolean>;
162
- /**
163
- * Time in ms after which the data is considered stale and will be refreshed
164
- * on next read.
165
- *
166
- * @default 5000 (5 seconds)
167
- */
168
- staleTime?: number;
169
- /**
170
- * Time in ms after which, once the data is no longer being used, it will be
171
- * garbage collected to free resources. Set to `false` to disable garbage
172
- * collection.
173
- *
174
- * @default 300_000 (5 minutes)
175
- */
176
- gcTime?: number | false;
177
- /**
178
- * Whether to refetch the query when the component is mounted.
179
- * @default true
180
- */
181
- refetchOnMount?: MaybeRefOrGetter<RefetchOnControl>;
182
- /**
183
- * Whether to refetch the query when the window regains focus.
184
- * @default true
185
- */
186
- refetchOnWindowFocus?: MaybeRefOrGetter<RefetchOnControl>;
187
- /**
188
- * Whether to refetch the query when the network reconnects.
189
- * @default true
190
- */
191
- refetchOnReconnect?: MaybeRefOrGetter<RefetchOnControl>;
192
- /**
193
- * A placeholder data that is initially shown while the query is loading for
194
- * the first time. This will also show the `status` as `success` until the
195
- * query finishes loading (no matter the outcome of the query). Note: unlike
196
- * with `initialData`, the placeholder does not change the cache state.
197
- */
198
- placeholderData?: (previousData: unknown) => any;
199
- /**
200
- * Whether to catch errors during SSR (onServerPrefetch) when the query fails.
201
- * @default false
202
- */
203
- ssrCatchError?: boolean;
204
- }
205
- /**
206
- * Context object passed to the `query` function of `useQuery()`.
207
- * @see {@link UseQueryOptions}
208
- */
209
- interface UseQueryFnContext {
210
- /**
211
- * `AbortSignal` instance attached to the query call. If the call becomes
212
- * outdated (e.g. due to a new call with the same key), the signal will be
213
- * aborted.
214
- */
215
- signal: AbortSignal;
216
- }
217
- /**
218
- * Type-only symbol to keep the type
219
- *
220
- * @internal
221
- */
222
- declare const tErrorSymbol: unique symbol;
223
- /**
224
- * Options for `useQuery()`. Can be extended by plugins.
225
- *
226
- * @example
227
- * ```ts
228
- * // use-query-plugin.d.ts
229
- * export {} // needed
230
- * declare module '@pinia/colada' {
231
- * interface UseQueryOptions {
232
- * // Whether to refresh the data when the component is mounted.
233
- * refreshOnMount?: boolean
234
- * }
235
- * }
236
- * ```
237
- */
238
- interface UseQueryOptions<TData = unknown, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined> extends Pick<UseQueryOptionsGlobal, 'gcTime' | 'enabled' | 'refetchOnMount' | 'refetchOnReconnect' | 'refetchOnWindowFocus' | 'staleTime' | 'ssrCatchError'> {
239
- /**
240
- * The key used to identify the query. Array of primitives **without**
241
- * reactive values or a reactive array or getter. It should be treaded as an
242
- * array of dependencies of your queries, e.g. if you use the
243
- * `route.params.id` property, it should also be part of the key:
244
- *
245
- * ```ts
246
- * import { useRoute } from 'vue-router'
247
- * import { useQuery } from '@pinia/colada'
248
- *
249
- * const route = useRoute()
250
- * const { data } = useQuery({
251
- * // pass a getter function (or computed, ref, etc.) to ensure reactivity
252
- * key: () => ['user', route.params.id],
253
- * query: () => fetchUser(route.params.id),
254
- * })
255
- * ```
256
- */
257
- key: MaybeRefOrGetter<EntryKey>;
258
- /**
259
- * The function that will be called to fetch the data. It **must** be async.
260
- */
261
- query: (context: UseQueryFnContext) => Promise<TData>;
262
- /**
263
- * The data which is initially set to the query while the query is loading
264
- * for the first time. Note: unlike with {@link placeholderData}, setting the
265
- * initial data changes the state of the query (it will be set to `success`).
266
- *
267
- * @see {@link placeholderData}
268
- */
269
- initialData?: () => TDataInitial;
270
- /**
271
- * A placeholder data that is initially shown while the query is loading for
272
- * the first time. This will also show the `status` as `success` until the
273
- * query finishes loading (no matter the outcome of the query). Note: unlike
274
- * with {@link initialData}, the placeholder does not change the cache state.
275
- *
276
- * @see {@link initialData}
277
- */
278
- placeholderData?: NoInfer<TDataInitial> | NoInfer<TData> | (<T extends TData>(previousData: T | undefined) => NoInfer<TDataInitial> | NoInfer<TData> | undefined);
279
- /**
280
- * Meta information associated with the query. Can be a raw object, a function
281
- * returning the meta object, or a ref containing the meta object.
282
- * The meta is resolved when the entry is **created** and stored in
283
- * `entry.meta`.
284
- *
285
- * **Note**: Meta is serialized during SSR, so it must be serializable (no functions,
286
- * class instances, or circular references). You can also completely ignore
287
- * it during SSR with a ternary: `meta: import.meta.ev.SSR ? {} : actualMeta`
288
- *
289
- * @example
290
- * ```ts
291
- * // SSR-safe: simple serializable data
292
- * useQuery({
293
- * key: ['user', id],
294
- * query: () => fetchUser(id),
295
- * meta: { errorMessage: true }
296
- * })
297
- *
298
- * // Using a function to compute meta
299
- * useQuery({
300
- * key: ['user', id],
301
- * query: () => fetchUser(id),
302
- * meta: () => ({ timestamp: Date.now() })
303
- * })
304
- *
305
- * // Skipping meta during SSR
306
- * useQuery({
307
- * key: ['user', id],
308
- * query: () => fetchUser(id),
309
- * meta: {
310
- * onError: import.meta.env.SSR ? undefined : ((err) => console.log('error'))
311
- * }
312
- * })
313
- * ```
314
- */
315
- meta?: MaybeRefOrGetter<QueryMeta>;
316
- /**
317
- * Ghost property to ensure TError generic parameter is included in the
318
- * interface structure. This property should never be used directly and is
319
- * only for type system correctness. it could be removed in the future if the
320
- * type can be inferred in any other way.
321
- *
322
- * @internal
323
- */
324
- readonly [tErrorSymbol]?: TError;
325
- }
326
- /**
327
- * Default options for `useQuery()`. Modifying this object will affect all the queries that don't override these
328
- */
329
- declare const USE_QUERY_DEFAULTS: {
330
- staleTime: number;
331
- gcTime: NonNullable<UseQueryOptions["gcTime"]>;
332
- refetchOnWindowFocus: NonNullable<UseQueryOptions["refetchOnWindowFocus"]>;
333
- refetchOnReconnect: NonNullable<UseQueryOptions["refetchOnReconnect"]>;
334
- refetchOnMount: NonNullable<UseQueryOptions["refetchOnMount"]>;
335
- enabled: MaybeRefOrGetter<boolean>;
336
- };
337
- type UseQueryOptionsWithDefaults<TData = unknown, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined> = UseQueryOptions<TData, TError, TDataInitial> & typeof USE_QUERY_DEFAULTS;
338
- //#endregion
339
- //#region ../../src/entry-filter.d.ts
340
5
  /**
341
- * Base interface for {@link EntryFilter}.
342
- *
343
- * @internal
6
+ * Options for the Pinia Colada Retry plugin.
344
7
  */
345
- interface EntryFilter_Base<TEntry> {
346
- /**
347
- * A key to filter the entries.
348
- */
349
- key?: EntryKey;
8
+ interface RetryOptions {
350
9
  /**
351
- * If `true`, it will only match the entry of the given `key`, skipping any children entries.
352
- * It also makes `key` required.
10
+ * The delay between retries. Can be a duration in ms or a function that
11
+ * receives the attempt number (starts at 0) and returns a duration in ms. By
12
+ * default, it will wait 2^attempt * 1000 ms, but never more than 30 seconds.
353
13
  *
354
- * @example
355
- * ```ts
356
- * { key: ['a'], exact: true }
357
- * // will match ['a'] but not ['a', 'b'], while
358
- * { key: ['a'] }
359
- * // will match both
360
- * ```
361
- */
362
- exact?: boolean;
363
- /**
364
- * If `true` or `false`, it will only return entries that match the stale status. If set to `null` or `undefined`, it matches both.
365
- * Requires `entry.options` to be set.
366
- */
367
- stale?: boolean | null;
368
- /**
369
- * If `true` or `false`, it will only return entries that match the active status. If set to `null` or `undefined`, it matches both.
14
+ * @param attempt -
15
+ * @returns
370
16
  */
371
- active?: boolean | null;
17
+ delay?: number | ((attempt: number) => number);
372
18
  /**
373
- * If it has a non _nullish_ value, it only returns the entries with the given status.
19
+ * The maximum number of times to retry the operation. Set to 0 to disable or
20
+ * to Infinity to retry forever. It can also be a function that receives the
21
+ * failure count and the error and returns if it should retry. Defaults to 3.
22
+ * **Must be a positive number**.
374
23
  */
375
- status?: DataStateStatus | null;
376
- /**
377
- * Pass a predicate to filter the entries. This will be executed for each entry matching the other filters.
378
- * @param entry - entry to filter
379
- */
380
- predicate?: (entry: TEntry) => boolean;
381
- }
382
- /**
383
- * Filter to get exactly one entry from the cache. Requires the `key` to be set.
384
- *
385
- * @internal
386
- */
387
- interface EntryFilter_Key<TEntry> extends EntryFilter_Base<TEntry> {
388
- key: EntryKey;
389
- exact: true;
24
+ retry?: number | ((failureCount: number, error: unknown) => boolean);
390
25
  }
391
- /**
392
- * Filter to get multiple matching entries from the cache.
393
- *
394
- * @internal
395
- */
396
- interface EntryFilter_NoKey<TEntry> extends EntryFilter_Base<TEntry> {
397
- exact?: false;
26
+ interface RetryEntry {
27
+ retryCount: number;
28
+ timeoutId?: ReturnType<typeof setTimeout>;
398
29
  }
399
30
  /**
400
- * Base interface to filter entries from a cache.
31
+ * Plugin that adds the ability to retry failed queries.
401
32
  *
402
- * @internal
403
- */
404
- type EntryFilter<TEntry> = EntryFilter_NoKey<TEntry> | EntryFilter_Key<TEntry>;
405
- //#endregion
406
- //#region ../../src/query-store.d.ts
407
- /**
408
- * Allows defining extensions to the query entry that are returned by `useQuery()`.
409
- */
410
- interface UseQueryEntryExtensions<TData, TError, TDataInitial extends TData | undefined = undefined> {}
411
- /**
412
- * NOTE: Entries could be classes but the point of having all functions within the store is to allow plugins to hook
413
- * into actions.
414
- */
415
- /**
416
- * A query entry in the cache.
33
+ * @param globalOptions - global options for the retries
417
34
  */
418
- interface UseQueryEntry<TData = unknown, TError = unknown, TDataInitial extends TData | undefined = (unknown extends TData ? unknown : undefined)> {
419
- /**
420
- * The state of the query. Contains the data, error and status.
421
- */
422
- state: ShallowRef<DataState<TData, TError, TDataInitial>>;
423
- /**
424
- * A placeholder `data` that is initially shown while the query is loading for the first time. This will also show the
425
- * `status` as `success` until the query finishes loading (no matter the outcome).
426
- */
427
- placeholderData: TDataInitial | TData | null | undefined;
428
- /**
429
- * The status of the query.
430
- */
431
- asyncStatus: ShallowRef<AsyncStatus>;
432
- /**
433
- * When was this data set in the entry for the last time in ms. It can also
434
- * be 0 if the entry has been invalidated.
435
- */
436
- when: number;
437
- /**
438
- * The serialized key associated with this query entry.
439
- */
440
- key: EntryKey;
441
- /**
442
- * Seriaized version of the key. Used to retrieve the entry from the cache.
443
- */
444
- keyHash: string;
445
- /**
446
- * Components and effects scopes that use this query entry.
447
- */
448
- deps: Set<EffectScope | ComponentInternalInstance>;
449
- /**
450
- * Timeout id that scheduled a garbage collection. It is set here to clear it when the entry is used by a different component
451
- */
452
- gcTimeout: ReturnType<typeof setTimeout> | undefined;
453
- /**
454
- * The current pending request.
455
- */
456
- pending: null | {
457
- /**
458
- * The abort controller used to cancel the request and which `signal` is passed to the query function.
459
- */
460
- abortController: AbortController;
461
- /**
462
- * The promise created by `queryCache.fetch` that is currently pending.
463
- */
464
- refreshCall: Promise<DataState<TData, TError, TDataInitial>>;
465
- /**
466
- * When was this `pending` object created.
467
- */
468
- when: number;
469
- };
470
- /**
471
- * Options used to create the query. They can be `null` during hydration but are needed for fetching. This is why
472
- * `store.ensure()` sets this property. Note these options might be shared by multiple query entries when the key is
473
- * dynamic and that's why some methods like {@link fetch} receive the options as an argument.
474
- */
475
- options: UseQueryOptionsWithDefaults<TData, TError, TDataInitial> | null;
476
- /**
477
- * Whether the data is stale or not, requires `options.staleTime` to be set.
478
- */
479
- readonly stale: boolean;
480
- /**
481
- * Whether the query is currently being used by a Component or EffectScope (e.g. a store).
482
- */
483
- readonly active: boolean;
484
- /**
485
- * Resolved meta information for this query. This is the computed value
486
- * from options.meta (function/ref resolved to raw object).
487
- */
488
- meta: QueryMeta;
489
- /**
490
- * Extensions to the query entry added by plugins.
491
- */
492
- ext: UseQueryEntryExtensions<TData, TError, TDataInitial>;
493
- /**
494
- * Internal property to store the HMR ids of the components that are using
495
- * this query and force refetching.
496
- *
497
- * @internal
498
- */
499
- __hmr?: {
35
+ declare function PiniaColadaRetry(globalOptions?: RetryOptions): (context: PiniaColadaPluginContext) => void;
36
+ declare module '@pinia/colada' {
37
+ interface UseQueryOptions<TData, TError, TDataInitial> {
500
38
  /**
501
- * Reference count of the components using this query.
39
+ * Options for the retries of this query added by `@pinia/colada-plugin-retry`.
502
40
  */
503
- ids: Map<string, number>;
504
- };
505
- }
506
- /**
507
- * Filter object to get entries from the query cache.
508
- *
509
- * @see {@link QueryCache.getEntries}
510
- * @see {@link QueryCache.cancelQueries}
511
- * @see {@link QueryCache#invalidateQueries}
512
- */
513
- type UseQueryEntryFilter = EntryFilter<UseQueryEntry>;
514
- /**
515
- * A query entry that is defined with {@link defineQuery}.
516
- * @internal
517
- */
518
- type DefineQueryEntry = [lastEnsuredEntries: UseQueryEntry[], returnValue: unknown, effect: EffectScope, paused: ShallowRef<boolean>];
519
- /**
520
- * Composable to get the cache of the queries. As any other composable, it can
521
- * be used inside the `setup` function of a component, within another
522
- * composable, or in injectable contexts like stores and navigation guards.
523
- */
524
- declare const useQueryCache: pinia0.StoreDefinition<"_pc_query", Pick<{
525
- caches: ShallowRef<Map<string, UseQueryEntry<unknown, unknown, unknown>>, Map<string, UseQueryEntry<unknown, unknown, unknown>>>;
526
- ensureDefinedQuery: <T>(fn: () => T) => DefineQueryEntry;
527
- /**
528
- * Scope to track effects and components that use the query cache.
529
- * @internal
530
- */
531
- _s: vue0.Raw<EffectScope>;
532
- setQueryData: <TData = unknown, TError = {
533
- custom: Error;
534
- }, TDataInitial extends TData | undefined = undefined>(key: EntryKeyTagged<TData, TError, TDataInitial> | EntryKey, data: NoInfer<TData> | Exclude<NoInfer<TDataInitial>, undefined> | ((oldData: TData | TDataInitial | undefined) => TData | Exclude<TDataInitial, undefined>)) => void;
535
- setQueriesData: <TData = unknown>(filters: UseQueryEntryFilter, updater: (previous: TData | undefined) => TData) => void;
536
- getQueryData: <TData = unknown, TError = {
537
- custom: Error;
538
- }, TDataInitial extends TData | undefined = undefined>(key: EntryKeyTagged<TData, TError, TDataInitial> | EntryKey) => TData | TDataInitial | undefined;
539
- invalidateQueries: (filters?: UseQueryEntryFilter, refetchActive?: boolean | "all") => Promise<unknown>;
540
- cancelQueries: (filters?: UseQueryEntryFilter, reason?: unknown) => void;
541
- invalidate: (entry: UseQueryEntry) => void;
542
- fetch: <TData, TError, TDataInitial extends TData | undefined>(entry: UseQueryEntry<TData, TError, TDataInitial>, options?: UseQueryOptionsWithDefaults<TData, TError, TDataInitial> | null) => Promise<DataState<TData, TError, TDataInitial>>;
543
- refresh: <TData, TError, TDataInitial extends TData | undefined>(entry: UseQueryEntry<TData, TError, TDataInitial>, options?: UseQueryOptionsWithDefaults<TData, TError, TDataInitial> | null) => Promise<DataState<TData, TError, TDataInitial>>;
544
- ensure: <TData = unknown, TError = {
545
- custom: Error;
546
- }, TDataInitial extends TData | undefined = undefined>(opts: UseQueryOptions<TData, TError, TDataInitial>, previousEntry?: UseQueryEntry<TData, TError, TDataInitial>) => UseQueryEntry<TData, TError, TDataInitial>;
547
- extend: <TData = unknown, TError = {
548
- custom: Error;
549
- }, TDataInitial extends TData | undefined = undefined>(_entry: UseQueryEntry<TData, TError, TDataInitial>) => void;
550
- track: (entry: UseQueryEntry, effect: EffectScope | ComponentInternalInstance | null | undefined) => void;
551
- untrack: (entry: UseQueryEntry, effect: EffectScope | ComponentInternalInstance | undefined | null) => void;
552
- cancel: (entry: UseQueryEntry, reason?: unknown) => void;
553
- create: <TData, TError, TDataInitial extends TData | undefined>(key: EntryKey, options?: UseQueryOptionsWithDefaults<TData, TError, TDataInitial> | null, initialData?: TDataInitial, error?: TError | null, when?: number, meta?: QueryMeta) => UseQueryEntry<TData, TError, TDataInitial>;
554
- remove: (entry: UseQueryEntry) => void;
555
- get: <TData = unknown, TError = {
556
- custom: Error;
557
- }, TDataInitial extends TData | undefined = undefined>(key: EntryKeyTagged<TData, TError, TDataInitial> | EntryKey) => UseQueryEntry<TData, TError, TDataInitial> | undefined;
558
- setEntryState: <TData, TError, TDataInitial extends TData | undefined = TData | undefined>(entry: UseQueryEntry<TData, TError, TDataInitial>, state: DataState<NoInfer<TData>, NoInfer<TError>, NoInfer<TDataInitial>>) => void;
559
- getEntries: (filters?: UseQueryEntryFilter) => UseQueryEntry[];
560
- }, "caches" | "_s">, Pick<{
561
- caches: ShallowRef<Map<string, UseQueryEntry<unknown, unknown, unknown>>, Map<string, UseQueryEntry<unknown, unknown, unknown>>>;
562
- ensureDefinedQuery: <T>(fn: () => T) => DefineQueryEntry;
563
- /**
564
- * Scope to track effects and components that use the query cache.
565
- * @internal
566
- */
567
- _s: vue0.Raw<EffectScope>;
568
- setQueryData: <TData = unknown, TError = {
569
- custom: Error;
570
- }, TDataInitial extends TData | undefined = undefined>(key: EntryKeyTagged<TData, TError, TDataInitial> | EntryKey, data: NoInfer<TData> | Exclude<NoInfer<TDataInitial>, undefined> | ((oldData: TData | TDataInitial | undefined) => TData | Exclude<TDataInitial, undefined>)) => void;
571
- setQueriesData: <TData = unknown>(filters: UseQueryEntryFilter, updater: (previous: TData | undefined) => TData) => void;
572
- getQueryData: <TData = unknown, TError = {
573
- custom: Error;
574
- }, TDataInitial extends TData | undefined = undefined>(key: EntryKeyTagged<TData, TError, TDataInitial> | EntryKey) => TData | TDataInitial | undefined;
575
- invalidateQueries: (filters?: UseQueryEntryFilter, refetchActive?: boolean | "all") => Promise<unknown>;
576
- cancelQueries: (filters?: UseQueryEntryFilter, reason?: unknown) => void;
577
- invalidate: (entry: UseQueryEntry) => void;
578
- fetch: <TData, TError, TDataInitial extends TData | undefined>(entry: UseQueryEntry<TData, TError, TDataInitial>, options?: UseQueryOptionsWithDefaults<TData, TError, TDataInitial> | null) => Promise<DataState<TData, TError, TDataInitial>>;
579
- refresh: <TData, TError, TDataInitial extends TData | undefined>(entry: UseQueryEntry<TData, TError, TDataInitial>, options?: UseQueryOptionsWithDefaults<TData, TError, TDataInitial> | null) => Promise<DataState<TData, TError, TDataInitial>>;
580
- ensure: <TData = unknown, TError = {
581
- custom: Error;
582
- }, TDataInitial extends TData | undefined = undefined>(opts: UseQueryOptions<TData, TError, TDataInitial>, previousEntry?: UseQueryEntry<TData, TError, TDataInitial>) => UseQueryEntry<TData, TError, TDataInitial>;
583
- extend: <TData = unknown, TError = {
584
- custom: Error;
585
- }, TDataInitial extends TData | undefined = undefined>(_entry: UseQueryEntry<TData, TError, TDataInitial>) => void;
586
- track: (entry: UseQueryEntry, effect: EffectScope | ComponentInternalInstance | null | undefined) => void;
587
- untrack: (entry: UseQueryEntry, effect: EffectScope | ComponentInternalInstance | undefined | null) => void;
588
- cancel: (entry: UseQueryEntry, reason?: unknown) => void;
589
- create: <TData, TError, TDataInitial extends TData | undefined>(key: EntryKey, options?: UseQueryOptionsWithDefaults<TData, TError, TDataInitial> | null, initialData?: TDataInitial, error?: TError | null, when?: number, meta?: QueryMeta) => UseQueryEntry<TData, TError, TDataInitial>;
590
- remove: (entry: UseQueryEntry) => void;
591
- get: <TData = unknown, TError = {
592
- custom: Error;
593
- }, TDataInitial extends TData | undefined = undefined>(key: EntryKeyTagged<TData, TError, TDataInitial> | EntryKey) => UseQueryEntry<TData, TError, TDataInitial> | undefined;
594
- setEntryState: <TData, TError, TDataInitial extends TData | undefined = TData | undefined>(entry: UseQueryEntry<TData, TError, TDataInitial>, state: DataState<NoInfer<TData>, NoInfer<TError>, NoInfer<TDataInitial>>) => void;
595
- getEntries: (filters?: UseQueryEntryFilter) => UseQueryEntry[];
596
- }, never>, Pick<{
597
- caches: ShallowRef<Map<string, UseQueryEntry<unknown, unknown, unknown>>, Map<string, UseQueryEntry<unknown, unknown, unknown>>>;
598
- ensureDefinedQuery: <T>(fn: () => T) => DefineQueryEntry;
599
- /**
600
- * Scope to track effects and components that use the query cache.
601
- * @internal
602
- */
603
- _s: vue0.Raw<EffectScope>;
604
- setQueryData: <TData = unknown, TError = {
605
- custom: Error;
606
- }, TDataInitial extends TData | undefined = undefined>(key: EntryKeyTagged<TData, TError, TDataInitial> | EntryKey, data: NoInfer<TData> | Exclude<NoInfer<TDataInitial>, undefined> | ((oldData: TData | TDataInitial | undefined) => TData | Exclude<TDataInitial, undefined>)) => void;
607
- setQueriesData: <TData = unknown>(filters: UseQueryEntryFilter, updater: (previous: TData | undefined) => TData) => void;
608
- getQueryData: <TData = unknown, TError = {
609
- custom: Error;
610
- }, TDataInitial extends TData | undefined = undefined>(key: EntryKeyTagged<TData, TError, TDataInitial> | EntryKey) => TData | TDataInitial | undefined;
611
- invalidateQueries: (filters?: UseQueryEntryFilter, refetchActive?: boolean | "all") => Promise<unknown>;
612
- cancelQueries: (filters?: UseQueryEntryFilter, reason?: unknown) => void;
613
- invalidate: (entry: UseQueryEntry) => void;
614
- fetch: <TData, TError, TDataInitial extends TData | undefined>(entry: UseQueryEntry<TData, TError, TDataInitial>, options?: UseQueryOptionsWithDefaults<TData, TError, TDataInitial> | null) => Promise<DataState<TData, TError, TDataInitial>>;
615
- refresh: <TData, TError, TDataInitial extends TData | undefined>(entry: UseQueryEntry<TData, TError, TDataInitial>, options?: UseQueryOptionsWithDefaults<TData, TError, TDataInitial> | null) => Promise<DataState<TData, TError, TDataInitial>>;
616
- ensure: <TData = unknown, TError = {
617
- custom: Error;
618
- }, TDataInitial extends TData | undefined = undefined>(opts: UseQueryOptions<TData, TError, TDataInitial>, previousEntry?: UseQueryEntry<TData, TError, TDataInitial>) => UseQueryEntry<TData, TError, TDataInitial>;
619
- extend: <TData = unknown, TError = {
620
- custom: Error;
621
- }, TDataInitial extends TData | undefined = undefined>(_entry: UseQueryEntry<TData, TError, TDataInitial>) => void;
622
- track: (entry: UseQueryEntry, effect: EffectScope | ComponentInternalInstance | null | undefined) => void;
623
- untrack: (entry: UseQueryEntry, effect: EffectScope | ComponentInternalInstance | undefined | null) => void;
624
- cancel: (entry: UseQueryEntry, reason?: unknown) => void;
625
- create: <TData, TError, TDataInitial extends TData | undefined>(key: EntryKey, options?: UseQueryOptionsWithDefaults<TData, TError, TDataInitial> | null, initialData?: TDataInitial, error?: TError | null, when?: number, meta?: QueryMeta) => UseQueryEntry<TData, TError, TDataInitial>;
626
- remove: (entry: UseQueryEntry) => void;
627
- get: <TData = unknown, TError = {
628
- custom: Error;
629
- }, TDataInitial extends TData | undefined = undefined>(key: EntryKeyTagged<TData, TError, TDataInitial> | EntryKey) => UseQueryEntry<TData, TError, TDataInitial> | undefined;
630
- setEntryState: <TData, TError, TDataInitial extends TData | undefined = TData | undefined>(entry: UseQueryEntry<TData, TError, TDataInitial>, state: DataState<NoInfer<TData>, NoInfer<TError>, NoInfer<TDataInitial>>) => void;
631
- getEntries: (filters?: UseQueryEntryFilter) => UseQueryEntry[];
632
- }, "cancel" | "get" | "create" | "ensure" | "remove" | "extend" | "setEntryState" | "getEntries" | "untrack" | "ensureDefinedQuery" | "setQueryData" | "setQueriesData" | "getQueryData" | "invalidateQueries" | "cancelQueries" | "invalidate" | "fetch" | "refresh" | "track">>;
633
- /**
634
- * The cache of the queries. It's the store returned by {@link useQueryCache}.
635
- */
636
- type QueryCache = ReturnType<typeof useQueryCache>;
637
- /**
638
- * Checks if the given object is a query cache. Used in SSR to apply custom serialization.
639
- *
640
- * @param cache - the object to check
641
- *
642
- * @see {@link QueryCache}
643
- * @see {@link serializeQueryCache}
644
- */
645
- declare function isQueryCache(cache: unknown): cache is QueryCache;
646
- /**
647
- * Raw data of a query entry. Can be serialized from the server and used to
648
- * hydrate the store.
649
- *
650
- * @internal
651
- */
652
- type _UseQueryEntryNodeValueSerialized<TData = unknown, TError = unknown> = [
653
- /**
654
- * The data returned by the query.
655
- */
656
- data: TData | undefined,
657
- /**
658
- * The error thrown by the query.
659
- */
660
- error: TError | null,
661
- /**
662
- * When was this data fetched the last time in ms
663
- */
664
- when?: number,
665
- /**
666
- * Meta information associated with the query
667
- */
668
- meta?: QueryMeta];
669
- /**
670
- * Hydrates the query cache with the serialized cache. Used during SSR.
671
- * @param queryCache - query cache
672
- * @param serializedCache - serialized cache
673
- */
674
- declare function hydrateQueryCache(queryCache: QueryCache, serializedCache: Record<string, _UseQueryEntryNodeValueSerialized>): void;
675
- /**
676
- * Serializes the query cache to a compressed version. Used during SSR.
677
- *
678
- * @param queryCache - query cache
679
- */
680
- declare function serializeQueryCache(queryCache: QueryCache): Record<string, _UseQueryEntryNodeValueSerialized>;
681
- //#endregion
682
- //#region ../../src/use-query.d.ts
683
- /**
684
- * Return type of `useQuery()`.
685
- */
686
- interface UseQueryReturn<TData = unknown, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined> extends UseQueryEntryExtensions<TData, TError, TDataInitial> {
687
- /**
688
- * The state of the query. Contains its data, error, and status.
689
- */
690
- state: ComputedRef<DataState<TData, TError, TDataInitial>>;
691
- /**
692
- * Status of the query. Becomes `'loading'` while the query is being fetched, is `'idle'` otherwise.
693
- */
694
- asyncStatus: ComputedRef<AsyncStatus>;
695
- /**
696
- * The last successful data resolved by the query. Alias for `state.value.data`.
697
- *
698
- * @see {@link state}
699
- */
700
- data: ShallowRef<TData | TDataInitial>;
701
- /**
702
- * The error rejected by the query. Alias for `state.value.error`.
703
- *
704
- * @see {@link state}
705
- */
706
- error: ShallowRef<TError | null>;
707
- /**
708
- * The status of the query. Alias for `state.value.status`.
709
- *
710
- * @see {@link state}
711
- * @see {@link DataStateStatus}
712
- */
713
- status: ShallowRef<DataStateStatus>;
714
- /**
715
- * Returns whether the request is still pending its first call. Alias for `status.value === 'pending'`
716
- */
717
- isPending: ComputedRef<boolean>;
718
- /**
719
- * Returns whether the `data` is the `placeholderData`.
720
- */
721
- isPlaceholderData: ComputedRef<boolean>;
722
- /**
723
- * Returns whether the request is currently fetching data. Alias for `asyncStatus.value === 'loading'`
724
- */
725
- isLoading: ShallowRef<boolean>;
726
- /**
727
- * Ensures the current data is fresh. If the data is stale, refetch, if not return as is.
728
- * @param throwOnError - whether to throw an error if the refresh fails. Defaults to `false`
729
- * @returns a promise that resolves when the refresh is done
730
- */
731
- refresh: (throwOnError?: boolean) => Promise<DataState<TData, TError, TDataInitial>>;
732
- /**
733
- * Ignores fresh data and triggers a new fetch
734
- * @param throwOnError - whether to throw an error if the fetch fails. Defaults to `false`
735
- * @returns a promise that resolves when the fetch is done
736
- */
737
- refetch: (throwOnError?: boolean) => Promise<DataState<TData, TError, TDataInitial>>;
41
+ retry?: RetryOptions | Exclude<RetryOptions['retry'], undefined>;
42
+ }
738
43
  }
739
- /**
740
- * Ensures and return a shared query state based on the `key` option.
741
- *
742
- * @param options - The options of the query
743
- *
744
- * @example
745
- * ```ts
746
- * const { state } = useQuery({
747
- * key: ['documents'],
748
- * query: () => getDocuments(),
749
- * })
750
- * ```
751
- */
752
- declare function useQuery<TData, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined>(options: UseQueryOptions<TData, TError, TDataInitial> | (() => DefineQueryOptions<TData, TError, TDataInitial>)): UseQueryReturn<TData, TError, TDataInitial>;
753
- /**
754
- * `useQuery` for dynamic typed query keys. Requires options defined with
755
- * {@link defineQueryOptions}.
756
- *
757
- * @param setupOptions - options defined with {@link defineQueryOptions}
758
- * @param paramsGetter - a getter or ref that returns the parameters for the `setupOptions`
759
- *
760
- * @example
761
- * ```ts
762
- * import { defineQueryOptions, useQuery } from '@pinia/colada'
763
- *
764
- * const documentDetailsQuery = defineQueryOptions((id: number ) => ({
765
- * key: ['documents', id],
766
- * query: () => fetchDocument(id),
767
- * }))
768
- *
769
- * useQuery(documentDetailsQuery, 4)
770
- * useQuery(documentDetailsQuery, () => route.params.id)
771
- * useQuery(documentDetailsQuery, () => props.id)
772
- * ```
773
- */
774
- declare function useQuery<Params, TData, TError, TDataInitial extends TData | undefined>(setupOptions: (params: Params) => DefineQueryOptions<TData, TError, TDataInitial>, paramsGetter: MaybeRefOrGetter<NoInfer<Params>>): UseQueryReturn<TData, TError, TDataInitial>;
775
- //#endregion
776
- //#region ../../src/utils.d.ts
777
- /**
778
- * Type that represents a value that can be an array or a single value.
779
- *
780
- * @internal
781
- */
782
- type _MaybeArray<T> = T | T[];
783
- /**
784
- * Checks if a type is exactly `any`.
785
- *
786
- * @internal
787
- */
788
- type IsAny<T> = 0 extends 1 & T ? true : false;
789
- /**
790
- * Checks if a type is exactly `unknown`. This is useful to determine if a type is
791
- *
792
- * @internal
793
- */
794
- type IsUnknown<T> = IsAny<T> extends true ? false : unknown extends T ? true : false;
795
- /**
796
- * Transforms a value or a function that returns a value to a value.
797
- *
798
- * @param valFn either a value or a function that returns a value
799
- * @param args arguments to pass to the function if `valFn` is a function
800
- *
801
- * @internal
802
- */
803
- declare function toValueWithArgs<T, Args extends any[]>(valFn: T | ((...args: Args) => T), ...args: Args): T;
804
- /**
805
- * Type that represents a value that can be a promise or a single value.
806
- *
807
- * @internal
808
- */
809
- type _Awaitable<T> = T | Promise<T>;
810
- /**
811
- * To avoid using `{}`
812
- * @internal
813
- */
814
- interface _EmptyObject {}
815
- /**
816
- * @internal
817
- */
818
- type _IsMaybeRefOrGetter<T> = [T] extends [MaybeRefOrGetter<infer U>] ? MaybeRefOrGetter<U> extends T ? true : false : false;
819
- /**
820
- * @internal
821
- */
822
- type _UnwrapMaybeRefOrGetter<T> = T extends MaybeRefOrGetter<infer U> ? U : T;
823
- /**
824
- * Removes the `MaybeRefOrGetter` wrapper from all fields of an object,
825
- * except for fields specified in the `Ignore` type.
826
- * @internal
827
- */
828
- type _RemoveMaybeRef<T, Ignore extends keyof T = never> = { [K in keyof T]: K extends Ignore ? T[K] : _IsMaybeRefOrGetter<NonNullable<T[K]>> extends true ? _UnwrapMaybeRefOrGetter<T[K]> : T[K] };
829
- //#endregion
830
- //#region ../../src/define-query.d.ts
831
- /**
832
- * Options to define a query with `defineQuery()`. Similar to
833
- * {@link UseQueryOptions} but disallows reactive values as `defineQuery()` is
834
- * used outside of an effect scope.
835
- */
836
- type DefineQueryOptions<TData = unknown, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined> = _RemoveMaybeRef<UseQueryOptions<TData, TError, TDataInitial>, typeof tErrorSymbol | 'initialData' | 'placeholderData'>;
837
- /**
838
- * Define a query with the given options. Similar to `useQuery(options)` but
839
- * allows you to reuse **all** of the query state in multiple places. It only
840
- * allow static values in options. If you need dynamic values, use the function
841
- * version.
842
- *
843
- * @param options - the options to define the query
844
- *
845
- * @example
846
- * ```ts
847
- * const useTodoList = defineQuery({
848
- * key: ['todos'],
849
- * query: () => fetch('/api/todos', { method: 'GET' }),
850
- * })
851
- * ```
852
- */
853
- declare function defineQuery<TData, TError = ErrorDefault>(options: DefineQueryOptions<TData, TError>): () => UseQueryReturn<TData, TError>;
854
- /**
855
- * Define a query with a setup function. Allows to return arbitrary values from
856
- * the query function, create contextual refs, rename the returned values, etc.
857
- * The setup function will be called only once, like stores, and **must be
858
- * synchronous**.
859
- *
860
- * @param setup - a function to setup the query
861
- *
862
- * @example
863
- * ```ts
864
- * const useFilteredTodos = defineQuery(() => {
865
- * const todoFilter = ref<'all' | 'finished' | 'unfinished'>('all')
866
- * const { data, ...rest } = useQuery({
867
- * key: ['todos', { filter: todoFilter.value }],
868
- * query: () =>
869
- * fetch(`/api/todos?filter=${todoFilter.value}`, { method: 'GET' }),
870
- * })
871
- * // expose the todoFilter ref and rename data for convenience
872
- * return { ...rest, todoList: data, todoFilter }
873
- * })
874
- * ```
875
- */
876
- declare function defineQuery<T>(setup: () => T): () => T;
877
- //#endregion
878
- //#region ../../src/define-query-options.d.ts
879
- /**
880
- * Tagged version of {@link DefineQueryOptions} that includes a key with
881
- * data type information.
882
- */
883
- interface DefineQueryOptionsTagged<TData = unknown, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined> extends DefineQueryOptions<TData, TError, TDataInitial> {
884
- key: EntryKeyTagged<TData, TError, TDataInitial>;
885
- }
886
- /**
887
- * Define dynamic query options by passing a function that accepts an optional
888
- * arbitrary parameter and returns the query options. Enables type-safe query
889
- * keys. Must be passed to {@link useQuery} with or without a getter to
890
- * retrieve the params.
891
- *
892
- * @param setupOptions - A function that returns the query options.
893
- */
894
- declare function defineQueryOptions<Params, TData, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined>(setupOptions: (params?: Params) => DefineQueryOptions<TData, TError, TDataInitial>): (params?: Params) => DefineQueryOptionsTagged<TData, TError, TDataInitial>;
895
- /**
896
- * Define dynamic query options by passing a function that accepts an arbitrary
897
- * parameter and returns the query options. Enables type-safe query keys.
898
- * Must be passed to {@link useQuery} alongside a getter for the params.
899
- *
900
- * @param setupOptions - A function that returns the query options.
901
- */
902
- declare function defineQueryOptions<Params, TData, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined>(setupOptions: (params: Params) => DefineQueryOptions<TData, TError, TDataInitial>): (params: Params) => DefineQueryOptionsTagged<TData, TError, TDataInitial>;
903
- /**
904
- * Define static query options that are type safe with
905
- * `queryCache.getQueryData()`. Can be passed directly to {@link useQuery}.
906
- *
907
- * @param options - The query options.
908
- */
909
- declare function defineQueryOptions<TData, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined>(options: DefineQueryOptions<TData, TError, TDataInitial>): DefineQueryOptionsTagged<TData, TError, TDataInitial>;
910
- //#endregion
911
- //#region ../../src/use-query-state.d.ts
912
- /**
913
- * Return type for the {@link useQueryState} composable.
914
- *
915
- * @see {@link useQueryState}
916
- */
917
- interface UseQueryStateReturn<TData = unknown, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined> {
918
- /**
919
- * `state` of the query entry.
920
- *
921
- * @see {@link UseQueryReturn#state}
922
- */
923
- state: ComputedRef<DataState<TData, TError, TDataInitial> | undefined>;
924
- /**
925
- * `data` of the query entry.
926
- *
927
- * @see {@link UseQueryReturn#data}
928
- */
929
- data: ComputedRef<TData | TDataInitial | undefined>;
930
- /**
931
- * `error` of the query entry.
932
- *
933
- * @see {@link UseQueryReturn#error}
934
- */
935
- error: ComputedRef<TError | null | undefined>;
936
- /**
937
- * `status` of the query entry.
938
- *
939
- * @see {@link DataStateStatus}
940
- * @see {@link UseQueryReturn#status}
941
- */
942
- status: ComputedRef<DataStateStatus | undefined>;
943
- /**
944
- * `asyncStatus` of the query entry.
945
- *
946
- * @see {@link AsyncStatus}
947
- * @see {@link UseQueryReturn#asyncStatus}
948
- */
949
- asyncStatus: ComputedRef<AsyncStatus | undefined>;
950
- /**
951
- * Is the query entry currently pending or non existent.
952
- */
953
- isPending: ComputedRef<boolean>;
954
- }
955
- /**
956
- * Reactive access to the state of a query entry without fetching it.
957
- *
958
- * @param key - tagged key of the query entry to access
959
- */
960
- declare function useQueryState<TData, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined>(key: MaybeRefOrGetter<EntryKeyTagged<TData, TError, TDataInitial>>): UseQueryStateReturn<TData, TError, TDataInitial>;
961
- /**
962
- * Reactive access to the state of a query entry without fetching it.
963
- *
964
- * @param setupOptions - function that returns the query options based on the provided params
965
- * @param paramsGetter - getter for the parameters used to generate the query key
966
- *
967
- * @see {@link DefineQueryOptions}
968
- * @see {@link defineQueryOptions}
969
- */
970
- declare function useQueryState<Params, TData, TError, TDataInitial extends TData | undefined>(setupOptions: (params: Params) => DefineQueryOptions<TData, TError, TDataInitial>, paramsGetter: MaybeRefOrGetter<NoInfer<Params>>): UseQueryStateReturn<TData, TError, TDataInitial>;
971
- /**
972
- * Reactive access to the state of a query entry without fetching it.
973
- *
974
- * @param key - key of the query entry to access
975
- */
976
- declare function useQueryState<TData, TError = ErrorDefault, TDataInitial extends TData | undefined = undefined>(key: MaybeRefOrGetter<EntryKey>): UseQueryStateReturn<TData, TError, TDataInitial>;
977
- //#endregion
978
- //#region ../../src/infinite-query.d.ts
979
- /**
980
- * Options for {@link useInfiniteQuery}.
981
- *
982
- * @experimental See https://github.com/posva/pinia-colada/issues/178
983
- */
984
- interface UseInfiniteQueryOptions<TData, TError, TDataInitial extends TData | undefined = TData | undefined, TPages = unknown> extends Omit<UseQueryOptions<TData, TError, TDataInitial>, 'query' | 'initialData' | 'placeholderData' | 'key'> {
985
- key: UseQueryOptions<TPages, TError, TPages>['key'];
986
- /**
987
- * The function that will be called to fetch the data. It **must** be async.
988
- */
989
- query: (pages: NoInfer<TPages>, context: UseQueryFnContext) => Promise<TData>;
990
- initialPage: TPages | (() => TPages);
991
- merge: (result: NoInfer<TPages>, current: NoInfer<TData>) => NoInfer<TPages>;
992
- }
993
- interface UseInfiniteQueryReturn<TPage = unknown, TError = ErrorDefault> extends Omit<UseQueryReturn<TPage, TError, TPage>, 'refetch' | 'refresh'> {
994
- loadMore: () => Promise<unknown>;
995
- }
996
- /**
997
- * Store and merge paginated data into a single cache entry. Allows to handle
998
- * infinite scrolling. This is an **experimental** API and is subject to
999
- * change.
1000
- *
1001
- * @param options - Options to configure the infinite query.
1002
- *
1003
- * @experimental See https://github.com/posva/pinia-colada/issues/178
1004
- */
1005
- declare function useInfiniteQuery<TData, TError = ErrorDefault, TPage = unknown>(options: UseInfiniteQueryOptions<TData, TError, TData | undefined, TPage>): UseInfiniteQueryReturn<TPage, TError>;
1006
- //#endregion
1007
- //#region ../../src/use-mutation.d.ts
1008
- /**
1009
- * Valid keys for a mutation. Similar to query keys.
1010
- *
1011
- * @see {@link EntryKey}
1012
- *
1013
- * @internal
1014
- */
1015
- type _MutationKey<TVars> = EntryKey | ((vars: TVars) => EntryKey);
1016
- /**
1017
- * Removes the nullish types from the context type to make `A & TContext` work instead of yield `never`.
1018
- *
1019
- * @internal
1020
- */
1021
- type _ReduceContext<TContext> = TContext extends void | null | undefined ? _EmptyObject : Record<any, any> extends TContext ? _EmptyObject : TContext;
1022
- /**
1023
- * Context object returned by a global `onMutate` function that is merged with the context returned by a local
1024
- * `onMutate`.
1025
- * @example
1026
- * ```ts
1027
- * declare module '@pinia/colada' {
1028
- * export interface UseMutationGlobalContext {
1029
- * router: Router // from vue-router
1030
- * }
1031
- * }
1032
- *
1033
- * // add the `router` to the context
1034
- * app.use(MutationPlugin, {
1035
- * onMutate() {
1036
- * return { router }
1037
- * },
1038
- * })
1039
- * ```
1040
- */
1041
- interface UseMutationGlobalContext {}
1042
- interface UseMutationReturn<TData, TVars, TError> {
1043
- key?: EntryKey | ((vars: NoInfer<TVars>) => EntryKey);
1044
- /**
1045
- * The combined state of the mutation. Contains its data, error, and status.
1046
- * It enables type narrowing based on the {@link UseMutationReturn['status']}.
1047
- */
1048
- state: ComputedRef<DataState<TData, TError>>;
1049
- /**
1050
- * The status of the mutation.
1051
- *
1052
- * @see {@link DataStateStatus}
1053
- */
1054
- status: ShallowRef<DataStateStatus>;
1055
- /**
1056
- * Status of the mutation. Becomes `'loading'` while the mutation is being fetched, is `'idle'` otherwise.
1057
- */
1058
- asyncStatus: ShallowRef<AsyncStatus>;
1059
- /**
1060
- * The result of the mutation. `undefined` if the mutation has not been called yet.
1061
- */
1062
- data: ShallowRef<TData | undefined>;
1063
- /**
1064
- * The error of the mutation. `null` if the mutation has not been called yet or if it was successful.
1065
- */
1066
- error: ShallowRef<TError | null>;
1067
- /**
1068
- * Whether the mutation is currently executing.
1069
- */
1070
- isLoading: ComputedRef<boolean>;
1071
- /**
1072
- * The variables passed to the mutation. They are initially `undefined` and change every time the mutation is called.
1073
- */
1074
- variables: ShallowRef<TVars | undefined>;
1075
- /**
1076
- * Calls the mutation and returns a promise with the result.
1077
- *
1078
- * @param vars - parameters to pass to the mutation
1079
- */
1080
- mutateAsync: unknown | void extends TVars ? () => Promise<TData> : (vars: TVars) => Promise<TData>;
1081
- /**
1082
- * Calls the mutation without returning a promise to avoid unhandled promise rejections.
1083
- *
1084
- * @param args - parameters to pass to the mutation
1085
- */
1086
- mutate: (...args: unknown | void extends TVars ? [] : [vars: TVars]) => void;
1087
- /**
1088
- * Resets the state of the mutation to its initial state.
1089
- */
1090
- reset: () => void;
1091
- }
1092
- /**
1093
- * Setups a mutation.
1094
- *
1095
- * @param options - Options to create the mutation
1096
- *
1097
- * @example
1098
- * ```ts
1099
- * const queryCache = useQueryCache()
1100
- * const { mutate, status, error } = useMutation({
1101
- * mutation: (id: number) => fetch(`/api/todos/${id}`),
1102
- * onSuccess() {
1103
- * queryCache.invalidateQueries('todos')
1104
- * },
1105
- * })
1106
- * ```
1107
- */
1108
- declare function useMutation<TData, TVars = void, TError = ErrorDefault, TContext extends Record<any, any> = _EmptyObject>(options: UseMutationOptions<TData, TVars, TError, TContext>): UseMutationReturn<TData, TVars, TError>;
1109
- //#endregion
1110
- //#region ../../src/mutation-options.d.ts
1111
- /**
1112
- * Options for mutations that can be globally overridden.
1113
- */
1114
- interface UseMutationOptionsGlobal {
1115
- /**
1116
- * Runs before a mutation is executed. It can return a value that will be
1117
- * passed to `mutation`, `onSuccess`, `onError` and `onSettled`. If it
1118
- * returns a promise, it will be awaited before running `mutation`.
1119
- */
1120
- onMutate?: (
1121
- /**
1122
- * The variables passed to the mutation.
1123
- */
1124
- vars: unknown) => _Awaitable<UseMutationGlobalContext | undefined | void | null>;
1125
- /**
1126
- * Runs when a mutation is successful.
1127
- */
1128
- onSuccess?: (
1129
- /**
1130
- * The result of the mutation.
1131
- */
1132
- data: unknown,
1133
- /**
1134
- * The variables passed to the mutation.
1135
- */
1136
- vars: unknown,
1137
- /**
1138
- * The merged context from `onMutate` and the global context.
1139
- */
1140
- context: UseMutationGlobalContext) => unknown;
1141
- /**
1142
- * Runs when a mutation encounters an error.
1143
- */
1144
- onError?: (
1145
- /**
1146
- * The error thrown by the mutation.
1147
- */
1148
- error: unknown,
1149
- /**
1150
- * The variables passed to the mutation.
1151
- */
1152
- vars: unknown,
1153
- /**
1154
- * The merged context from `onMutate` and the global context. Properties returned by `onMutate` can be `undefined`
1155
- * if `onMutate` throws.
1156
- */
1157
- context: Partial<Record<keyof UseMutationGlobalContext, never>> | UseMutationGlobalContext) => unknown;
1158
- /**
1159
- * Runs after the mutation is settled, regardless of the result.
1160
- */
1161
- onSettled?: (
1162
- /**
1163
- * The result of the mutation. `undefined` when a mutation failed.
1164
- */
1165
- data: unknown | undefined,
1166
- /**
1167
- * The error thrown by the mutation. `undefined` if the mutation was successful.
1168
- */
1169
- error: unknown | undefined,
1170
- /**
1171
- * The variables passed to the mutation.
1172
- */
1173
- vars: unknown,
1174
- /**
1175
- * The merged context from `onMutate` and the global context. Properties returned by `onMutate` can be `undefined`
1176
- * if `onMutate` throws.
1177
- */
1178
- context: Partial<Record<keyof UseMutationGlobalContext, never>> | UseMutationGlobalContext) => unknown;
1179
- /**
1180
- * Time in ms after which, once the mutation is no longer being used, it will be
1181
- * garbage collected to free resources. Set to `false` to disable garbage
1182
- * collection (not recommended).
1183
- *
1184
- * @default 60_000 (1 minute)
1185
- */
1186
- gcTime?: number | false;
1187
- }
1188
- /**
1189
- * Default options for `useMutation()`. Modifying this object will affect all mutations.
1190
- */
1191
- declare const USE_MUTATION_DEFAULTS: {
1192
- gcTime: NonNullable<UseMutationOptions["gcTime"]>;
1193
- };
1194
- type UseMutationOptionsWithDefaults<TData = unknown, TVars = void, TError = ErrorDefault, TContext extends Record<any, any> = _EmptyObject> = UseMutationOptions<TData, TVars, TError, TContext> & typeof USE_MUTATION_DEFAULTS;
1195
- /**
1196
- * Options to create a mutation.
1197
- */
1198
- interface UseMutationOptions<TData = unknown, TVars = void, TError = ErrorDefault, TContext extends Record<any, any> = _EmptyObject> extends Pick<UseMutationOptionsGlobal, 'gcTime'> {
1199
- /**
1200
- * The key of the mutation. If the mutation is successful, it will invalidate the mutation with the same key and refetch it
1201
- */
1202
- mutation: (vars: TVars, context: _ReduceContext<NoInfer<TContext>>) => Promise<TData>;
1203
- /**
1204
- * Optional key to identify the mutation globally and access it through other
1205
- * helpers like `useMutationState()`. If you don't need to reference the
1206
- * mutation elsewhere, you should ignore this option.
1207
- */
1208
- key?: _MutationKey<NoInfer<TVars>>;
1209
- /**
1210
- * Runs before the mutation is executed. **It should be placed before `mutation()` for `context` to be inferred**. It
1211
- * can return a value that will be passed to `mutation`, `onSuccess`, `onError` and `onSettled`. If it returns a
1212
- * promise, it will be awaited before running `mutation`.
1213
- *
1214
- * @example
1215
- * ```ts
1216
- * useMutation({
1217
- * // must appear before `mutation` for `{ foo: string }` to be inferred
1218
- * // within `mutation`
1219
- * onMutate() {
1220
- * return { foo: 'bar' }
1221
- * },
1222
- * mutation: (id: number, { foo }) => {
1223
- * console.log(foo) // bar
1224
- * return fetch(`/api/todos/${id}`)
1225
- * },
1226
- * onSuccess(data, vars, context) {
1227
- * console.log(context.foo) // bar
1228
- * },
1229
- * })
1230
- * ```
1231
- */
1232
- onMutate?: (
1233
- /**
1234
- * The variables passed to the mutation.
1235
- */
1236
- vars: NoInfer<TVars>, context: UseMutationGlobalContext) => _Awaitable<TContext | undefined | void | null>;
1237
- /**
1238
- * Runs if the mutation is successful.
1239
- */
1240
- onSuccess?: (
1241
- /**
1242
- * The result of the mutation.
1243
- */
1244
- data: NoInfer<TData>,
1245
- /**
1246
- * The variables passed to the mutation.
1247
- */
1248
- vars: NoInfer<TVars>,
1249
- /**
1250
- * The merged context from `onMutate` and the global context.
1251
- */
1252
- context: UseMutationGlobalContext & _ReduceContext<NoInfer<TContext>>) => unknown;
1253
- /**
1254
- * Runs if the mutation encounters an error.
1255
- */
1256
- onError?: (
1257
- /**
1258
- * The error thrown by the mutation.
1259
- */
1260
- error: TError,
1261
- /**
1262
- * The variables passed to the mutation.
1263
- */
1264
- vars: NoInfer<TVars>,
1265
- /**
1266
- * The merged context from `onMutate` and the global context. Properties returned by `onMutate` can be `undefined`
1267
- * if `onMutate` throws.
1268
- */
1269
- context: (Partial<Record<keyof UseMutationGlobalContext, never>> & Partial<Record<keyof _ReduceContext<NoInfer<TContext>>, never>>) | (UseMutationGlobalContext & _ReduceContext<NoInfer<TContext>>)) => unknown;
1270
- /**
1271
- * Runs after the mutation is settled, regardless of the result.
1272
- */
1273
- onSettled?: (
1274
- /**
1275
- * The result of the mutation. `undefined` if the mutation failed.
1276
- */
1277
- data: NoInfer<TData> | undefined,
1278
- /**
1279
- * The error thrown by the mutation. `undefined` if the mutation was successful.
1280
- */
1281
- error: TError | undefined,
1282
- /**
1283
- * The variables passed to the mutation.
1284
- */
1285
- vars: NoInfer<TVars>,
1286
- /**
1287
- * The merged context from `onMutate` and the global context. Properties returned by `onMutate` can be `undefined`
1288
- * if `onMutate` throws.
1289
- */
1290
- context: (Partial<Record<keyof UseMutationGlobalContext, never>> & Partial<Record<keyof _ReduceContext<NoInfer<TContext>>, never>>) | (UseMutationGlobalContext & _ReduceContext<NoInfer<TContext>>)) => unknown;
1291
- }
1292
- /**
1293
- * Global default options for `useMutations()`.
1294
- * @internal
1295
- */
1296
- type UseMutationOptionsGlobalDefaults = UseMutationOptionsGlobal & typeof USE_MUTATION_DEFAULTS;
1297
- //#endregion
1298
- //#region ../../src/mutation-store.d.ts
1299
- /**
1300
- * Allows defining extensions to the mutation entry that are returned by `useMutation()`.
1301
- */
1302
- interface UseMutationEntryExtensions<TData, TVars, TError, TContext extends Record<any, any> = _EmptyObject> {}
1303
- /**
1304
- * A mutation entry in the cache.
1305
- */
1306
- interface UseMutationEntry<TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject> {
1307
- /**
1308
- * Unique id of the mutation entry. 0 if the entry is not yet in the cache.
1309
- */
1310
- id: number;
1311
- /**
1312
- * The state of the mutation. Contains the data, error and status.
1313
- */
1314
- state: ShallowRef<DataState<TData, TError>>;
1315
- /**
1316
- * The async status of the mutation.
1317
- */
1318
- asyncStatus: ShallowRef<AsyncStatus>;
1319
- /**
1320
- * When was this data fetched the last time in ms
1321
- */
1322
- when: number;
1323
- /**
1324
- * The key associated with this mutation entry.
1325
- * Can be `undefined` if the entry has no key.
1326
- */
1327
- key: EntryKey | undefined;
1328
- /**
1329
- * The variables used to call the mutation.
1330
- */
1331
- vars: TVars | undefined;
1332
- /**
1333
- * Options used to create the mutation.
1334
- */
1335
- options: UseMutationOptionsWithDefaults<TData, TVars, TError, TContext>;
1336
- /**
1337
- * Timeout id that scheduled a garbage collection. It is set here to clear it when the entry is used by a different component.
1338
- */
1339
- gcTimeout: ReturnType<typeof setTimeout> | undefined;
1340
- /**
1341
- * Extensions to the mutation entry added by plugins.
1342
- */
1343
- ext: UseMutationEntryExtensions<TData, TVars, TError, TContext>;
1344
- }
1345
- /**
1346
- * Filter to get entries from the mutation cache.
1347
- */
1348
- type UseMutationEntryFilter = EntryFilter<UseMutationEntry>;
1349
- /**
1350
- * Composable to get the cache of the mutations. As any other composable, it
1351
- * can be used inside the `setup` function of a component, within another
1352
- * composable, or in injectable contexts like stores and navigation guards.
1353
- */
1354
- declare const useMutationCache: pinia0.StoreDefinition<"_pc_mutation", Pick<{
1355
- caches: vue0.Ref<Map<number, UseMutationEntry<unknown, any, unknown, any>>, Map<number, UseMutationEntry<unknown, any, unknown, any>>>;
1356
- create: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(options: UseMutationOptionsWithDefaults<TData, TVars, TError, TContext>, key?: EntryKey | undefined, vars?: TVars) => UseMutationEntry<TData, TVars, TError, TContext>;
1357
- ensure: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>, vars: NoInfer<TVars>) => UseMutationEntry<TData, TVars, TError, TContext>;
1358
- ensureDefinedMutation: <T>(fn: () => T) => unknown;
1359
- mutate: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>) => Promise<TData>;
1360
- remove: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>) => void;
1361
- extend: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(_entry: UseMutationEntry<TData, TVars, TError, TContext>) => void;
1362
- get: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(id: number) => UseMutationEntry<TData, TVars, TError, TContext> | undefined;
1363
- setEntryState: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>, state: DataState<NoInfer<TData>, NoInfer<TError>>) => void;
1364
- getEntries: (filters?: UseMutationEntryFilter) => UseMutationEntry[];
1365
- untrack: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>) => void;
1366
- /**
1367
- * Scope to track effects and components that use the mutation cache.
1368
- * @internal
1369
- */
1370
- _s: vue0.EffectScope;
1371
- }, "caches" | "_s">, Pick<{
1372
- caches: vue0.Ref<Map<number, UseMutationEntry<unknown, any, unknown, any>>, Map<number, UseMutationEntry<unknown, any, unknown, any>>>;
1373
- create: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(options: UseMutationOptionsWithDefaults<TData, TVars, TError, TContext>, key?: EntryKey | undefined, vars?: TVars) => UseMutationEntry<TData, TVars, TError, TContext>;
1374
- ensure: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>, vars: NoInfer<TVars>) => UseMutationEntry<TData, TVars, TError, TContext>;
1375
- ensureDefinedMutation: <T>(fn: () => T) => unknown;
1376
- mutate: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>) => Promise<TData>;
1377
- remove: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>) => void;
1378
- extend: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(_entry: UseMutationEntry<TData, TVars, TError, TContext>) => void;
1379
- get: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(id: number) => UseMutationEntry<TData, TVars, TError, TContext> | undefined;
1380
- setEntryState: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>, state: DataState<NoInfer<TData>, NoInfer<TError>>) => void;
1381
- getEntries: (filters?: UseMutationEntryFilter) => UseMutationEntry[];
1382
- untrack: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>) => void;
1383
- /**
1384
- * Scope to track effects and components that use the mutation cache.
1385
- * @internal
1386
- */
1387
- _s: vue0.EffectScope;
1388
- }, never>, Pick<{
1389
- caches: vue0.Ref<Map<number, UseMutationEntry<unknown, any, unknown, any>>, Map<number, UseMutationEntry<unknown, any, unknown, any>>>;
1390
- create: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(options: UseMutationOptionsWithDefaults<TData, TVars, TError, TContext>, key?: EntryKey | undefined, vars?: TVars) => UseMutationEntry<TData, TVars, TError, TContext>;
1391
- ensure: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>, vars: NoInfer<TVars>) => UseMutationEntry<TData, TVars, TError, TContext>;
1392
- ensureDefinedMutation: <T>(fn: () => T) => unknown;
1393
- mutate: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>) => Promise<TData>;
1394
- remove: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>) => void;
1395
- extend: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(_entry: UseMutationEntry<TData, TVars, TError, TContext>) => void;
1396
- get: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(id: number) => UseMutationEntry<TData, TVars, TError, TContext> | undefined;
1397
- setEntryState: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>, state: DataState<NoInfer<TData>, NoInfer<TError>>) => void;
1398
- getEntries: (filters?: UseMutationEntryFilter) => UseMutationEntry[];
1399
- untrack: <TData = unknown, TVars = unknown, TError = unknown, TContext extends Record<any, any> = _EmptyObject>(entry: UseMutationEntry<TData, TVars, TError, TContext>) => void;
1400
- /**
1401
- * Scope to track effects and components that use the mutation cache.
1402
- * @internal
1403
- */
1404
- _s: vue0.EffectScope;
1405
- }, "get" | "create" | "ensure" | "ensureDefinedMutation" | "mutate" | "remove" | "extend" | "setEntryState" | "getEntries" | "untrack">>;
1406
- /**
1407
- * The cache of the mutations. It's the store returned by {@link useMutationCache}.
1408
- */
1409
- type MutationCache = ReturnType<typeof useMutationCache>;
1410
- /**
1411
- * Checks if the given object is a mutation cache. Used in SSR to apply custom serialization.
1412
- *
1413
- * @param cache - the object to check
1414
- *
1415
- * @see {@link MutationCache}
1416
- */
1417
- declare function isMutationCache(cache: unknown): cache is MutationCache;
1418
- //#endregion
1419
- //#region ../../src/define-mutation.d.ts
1420
- /**
1421
- * Define a mutation with the given options. Similar to `useMutation(options)` but allows you to reuse the mutation in
1422
- * multiple places.
1423
- *
1424
- * @param options - the options to define the mutation
1425
- * @example
1426
- * ```ts
1427
- * const useCreateTodo = defineMutation({
1428
- * mutation: (todoText: string) =>
1429
- * fetch('/api/todos', {
1430
- * method: 'POST',
1431
- * body: JSON.stringify({ text: todoText }),
1432
- * }),
1433
- * })
1434
- * ```
1435
- */
1436
- declare function defineMutation<TData, TVars = void, TError = ErrorDefault, TContext extends Record<any, any> = _EmptyObject>(options: UseMutationOptions<TData, TVars, TError, TContext>): () => UseMutationReturn<TData, TVars, TError>;
1437
- /**
1438
- * Define a mutation with a function setup. Allows to return arbitrary values from the mutation function, create
1439
- * contextual refs, rename the returned values, etc.
1440
- *
1441
- * @param setup - a function to setup the mutation
1442
- * @example
1443
- * ```ts
1444
- * const useCreateTodo = defineMutation(() => {
1445
- * const todoText = ref('')
1446
- * const { data, mutate, ...rest } = useMutation({
1447
- * mutation: () =>
1448
- * fetch('/api/todos', {
1449
- * method: 'POST',
1450
- * body: JSON.stringify({ text: todoText.value }),
1451
- * }),
1452
- * })
1453
- * // expose the todoText ref and rename other methods for convenience
1454
- * return { ...rest, createTodo: mutate, todo: data, todoText }
1455
- * })
1456
- * ```
1457
- */
1458
- declare function defineMutation<T>(setup: () => T): () => T;
1459
- //#endregion
1460
- //#region ../../src/plugins/index.d.ts
1461
- /**
1462
- * Context passed to a Pinia Colada plugin.
1463
- */
1464
- interface PiniaColadaPluginContext {
1465
- /**
1466
- * The query cache used by the application.
1467
- */
1468
- queryCache: QueryCache;
1469
- /**
1470
- * The Pinia instance used by the application.
1471
- */
1472
- pinia: Pinia;
1473
- /**
1474
- * An effect scope to collect effects. It should be used if you use any reactivity API like `ref()`, `watch()`, `computed()`, etc.
1475
- * @see {@link https://vuejs.org/api/reactivity-advanced.html#effectscope}
1476
- */
1477
- scope: EffectScope;
1478
- }
1479
- /**
1480
- * A Pinia Colada plugin.
1481
- */
1482
- interface PiniaColadaPlugin {
1483
- (context: PiniaColadaPluginContext): void;
1484
- }
1485
- //#endregion
1486
- //#region ../../src/pinia-colada.d.ts
1487
- /**
1488
- * Options for the Pinia Colada plugin.
1489
- */
1490
- interface PiniaColadaOptions {
1491
- /**
1492
- * Pinia instance to use. This is only needed if installing before the Pinia plugin.
1493
- */
1494
- pinia?: Pinia;
1495
- /**
1496
- * Pinia Colada plugins to install.
1497
- */
1498
- plugins?: PiniaColadaPlugin[];
1499
- /**
1500
- * Global options for queries. These will apply to all `useQuery()`, `defineQuery()`, etc.
1501
- */
1502
- queryOptions?: UseQueryOptionsGlobal;
1503
- /**
1504
- * Global options for mutations. These will apply to all `useMutation()`, `defineMutation()`, etc.
1505
- */
1506
- mutationOptions?: UseMutationOptionsGlobal;
1507
- }
1508
- /**
1509
- * Plugin that installs the Query and Mutation plugins alongside some extra plugins.
1510
- *
1511
- * @see {@link QueryPlugin} to only install the Query plugin.
1512
- *
1513
- * @param app - Vue App
1514
- * @param options - Pinia Colada options
1515
- */
1516
- declare const PiniaColada: Plugin<[options?: PiniaColadaOptions]>;
1517
- //#endregion
1518
- //#region ../../src/plugins/query-hooks.d.ts
1519
- /**
1520
- * Options for {@link PiniaColadaQueryHooksPlugin}.
1521
- */
1522
- interface PiniaColadaQueryHooksPluginOptions {
1523
- /**
1524
- * Global handler for when a query is successful.
1525
- *
1526
- * @param data - data returned by the query
1527
- */
1528
- onSuccess?: <TData = unknown>(data: TData, entry: UseQueryEntry<TData, unknown>) => unknown;
1529
- /**
1530
- * Global handler for when a query is settled (either successfully or with an error). Will await for the `onSuccess`
1531
- * or `onError` handlers to resolve if they return a promise.
1532
- *
1533
- * @param data - data returned by the query if any
1534
- * @param error - error thrown if any
1535
- */
1536
- onSettled?: <TData = unknown, TError = unknown>(data: TData | undefined, error: TError | null, entry: UseQueryEntry<TData, TError>) => unknown;
1537
- /**
1538
- * Global error handler for all queries.
1539
- *
1540
- * @param error - error thrown
1541
- */
1542
- onError?: <TError = unknown>(error: TError, entry: UseQueryEntry<unknown, TError>) => unknown;
1543
- }
1544
- /**
1545
- * Allows to add global hooks to all queries:
1546
- * - `onSuccess`: called when a query is successful
1547
- * - `onError`: called when a query throws an error
1548
- * - `onSettled`: called when a query is settled (either successfully or with an error)
1549
- * @param options - Pinia Colada Query Hooks plugin options
1550
- *
1551
- * @example
1552
- * ```ts
1553
- * import { PiniaColada, PiniaColadaQueryHooksPlugin } from '@pinia/colada'
1554
- *
1555
- * const app = createApp(App)
1556
- * // app setup with other plugins
1557
- * app.use(PiniaColada, {
1558
- * plugins: [
1559
- * PiniaColadaQueryHooksPlugin({
1560
- * onError(error, entry) {
1561
- * // ...
1562
- * },
1563
- * }),
1564
- * ],
1565
- * })
1566
- * ```
1567
- */
1568
- declare function PiniaColadaQueryHooksPlugin(options: PiniaColadaQueryHooksPluginOptions): PiniaColadaPlugin;
1569
44
  //#endregion
1570
- export { type AsyncStatus, type DataState, type DataStateStatus, type DataState_Error, type DataState_Pending, type DataState_Success, type DefineQueryOptions, type DefineQueryOptionsTagged, type EntryKey, type EntryKeyTagged, type MutationCache, PiniaColada, type PiniaColadaOptions, type PiniaColadaPlugin, type PiniaColadaPluginContext, PiniaColadaQueryHooksPlugin, type PiniaColadaQueryHooksPluginOptions, type QueryCache, type RefetchOnControl, type TypesConfig, type UseInfiniteQueryOptions, type UseInfiniteQueryReturn, type UseMutationEntry, type UseMutationEntryExtensions, type UseMutationEntryFilter, type UseMutationOptions, type UseMutationOptionsGlobal, type UseMutationOptionsGlobalDefaults, type UseMutationOptionsWithDefaults, type UseMutationReturn, type UseQueryEntry, type UseQueryEntryExtensions, type UseQueryEntryFilter, type UseQueryOptions, type UseQueryOptionsGlobal, type UseQueryOptionsWithDefaults, type UseQueryReturn, type UseQueryStateReturn, type _Awaitable, type _DataState_Base, type ENTRY_DATA_INITIAL_TAG as _ENTRY_DATA_INITIAL_TAG, type ENTRY_DATA_TAG as _ENTRY_DATA_TAG, type ENTRY_ERROR_TAG as _ENTRY_ERROR_TAG, type _EmptyObject, type EntryFilter as _EntryFilter, type EntryFilter_Base as _EntryFilter_Base, type EntryFilter_Key as _EntryFilter_Key, type EntryFilter_NoKey as _EntryFilter_NoKey, type IsAny as _IsAny, type IsUnknown as _IsUnknown, type JSONArray as _JSONArray, type JSONObject as _JSONObject, type JSONPrimitive as _JSONPrimitive, type JSONValue as _JSONValue, type _MaybeArray, type _ReduceContext, type _UseQueryEntryNodeValueSerialized, toValueWithArgs as _toValueWithArgs, defineMutation, defineQuery, defineQueryOptions, hydrateQueryCache, isMutationCache, isQueryCache, serializeQueryCache, toCacheKey, useInfiniteQuery, useMutation, useMutationCache, useQuery, useQueryCache, useQueryState };
45
+ export { PiniaColadaRetry, RetryEntry, RetryOptions };
1571
46
  //# sourceMappingURL=index.d.mts.map