@pinia/colada-plugin-delay 0.1.3 → 0.1.5

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