Skip to content

Commit c3a171e

Browse files
markeriksonmarkerikson
committed
Restructure hooks page headings and descriptions
1 parent d613205 commit c3a171e

File tree

1 file changed

+152
-92
lines changed

1 file changed

+152
-92
lines changed

‎docs/rtk-query/api/created-api/hooks.mdx‎

Lines changed: 152 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -241,7 +241,9 @@ const useQueryResult = api.endpoints.getPosts.useQuery(arg, options)
241241
const useQueryResult = api.useGetPostsQuery(arg, options)
242242
```
243243

244-
#### Signature
244+
[summary](docblock://query/react/buildHooks.ts?token=UseQuery)
245+
246+
### `useQuery` Signature
245247

246248
```ts no-transpile
247249
type UseQuery = (
@@ -261,23 +263,39 @@ type UseQueryOptions = {
261263

262264
type UseQueryResult<T> = {
263265
// Base query state
264-
originalArgs?: unknown // Arguments passed to the query
265-
data?: T // The latest returned result regardless of hook arg, if present
266-
currentData?: T // The latest returned result for the current hook arg, if present
267-
error?: unknown // Error result if present
268-
requestId?: string // A string generated by RTK Query
269-
endpointName?: string // The name of the given endpoint for the query
270-
startedTimeStamp?: number // Timestamp for when the query was initiated
271-
fulfilledTimeStamp?: number // Timestamp for when the query was completed
266+
267+
// Arguments passed to the query
268+
originalArgs?: unknown
269+
// The latest returned result regardless of hook arg, if present
270+
data?: T
271+
// The latest returned result for the current hook arg, if present
272+
currentData?: T
273+
// Error result if present
274+
error?: unknown
275+
// A string generated by RTK Query
276+
requestId?: string
277+
// The name of the given endpoint for the query
278+
endpointName?: string
279+
// Timestamp for when the query was initiated
280+
startedTimeStamp?: number
281+
// Timestamp for when the query was completed
282+
fulfilledTimeStamp?: number
272283

273284
// Derived request status booleans
274-
isUninitialized: boolean // Query has not started yet.
275-
isLoading: boolean // Query is currently loading for the first time. No data yet.
276-
isFetching: boolean // Query is currently fetching, but might have data from an earlier request.
277-
isSuccess: boolean // Query has data from a successful load.
278-
isError: boolean // Query is currently in an "error" state.
279285

280-
refetch: () => QueryActionCreatorResult // A function to force refetch the query - returns a Promise with additional methods
286+
// Query has not started yet.
287+
isUninitialized: boolean
288+
// Query is currently loading for the first time. No data yet.
289+
isLoading: boolean
290+
// Query is currently fetching, but might have data from an earlier request.
291+
isFetching: boolean
292+
// Query has data from a successful load.
293+
isSuccess: boolean
294+
// Query is currently in an "error" state.
295+
isError: boolean
296+
297+
// A function to force refetch the query - returns a Promise with additional methods
298+
refetch: () => QueryActionCreatorResult
281299
}
282300
```
283301
@@ -288,11 +306,7 @@ type UseQueryResult<T> = {
288306
- **Returns**
289307
- A query result object containing the current loading state, the actual data or error returned from the API call, metadata about the request, and a function to `refetch` the data. Can be customized with `selectFromResult`
290308
291-
#### Description
292-
293-
[summary](docblock://query/react/buildHooks.ts?token=UseQuery)
294-
295-
#### `skipToken`
309+
### `skipToken`
296310
297311
[summary](docblock://query/core/buildSelectors.ts?token=skipToken)
298312
@@ -306,7 +320,9 @@ const useMutationResult = api.endpoints.updatePost.useMutation(options)
306320
const useMutationResult = api.useUpdatePostMutation(options)
307321
```
308322

309-
#### Signature
323+
[summary](docblock://query/react/buildHooks.ts?token=UseMutation)
324+
325+
### `useMutation` Signature
310326

311327
```ts no-transpile
312328
type UseMutation = (
@@ -331,20 +347,33 @@ type UseMutationTrigger<T> = (arg: any) => Promise<
331347

332348
type UseMutationResult<T> = {
333349
// Base query state
334-
originalArgs?: unknown // Arguments passed to the latest mutation call. Not available if using the `fixedCacheKey` option
335-
data?: T // Returned result if present
336-
error?: unknown // Error result if present
337-
endpointName?: string // The name of the given endpoint for the mutation
338-
fulfilledTimeStamp?: number // Timestamp for when the mutation was completed
350+
351+
// Arguments passed to the latest mutation call. Not available if using the `fixedCacheKey` option
352+
originalArgs?: unknown
353+
// Returned result if present
354+
data?: T
355+
// Error result if present
356+
error?: unknown
357+
// The name of the given endpoint for the mutation
358+
endpointName?: string
359+
// Timestamp for when the mutation was completed
360+
fulfilledTimeStamp?: number
339361

340362
// Derived request status booleans
341-
isUninitialized: boolean // Mutation has not been fired yet
342-
isLoading: boolean // Mutation has been fired and is awaiting a response
343-
isSuccess: boolean // Mutation has data from a successful call
344-
isError: boolean // Mutation is currently in an "error" state
345-
startedTimeStamp?: number // Timestamp for when the latest mutation was initiated
346363

347-
reset: () => void // A method to manually unsubscribe from the mutation call and reset the result to the uninitialized state
364+
// Mutation has not been fired yet
365+
isUninitialized: boolean
366+
// Mutation has been fired and is awaiting a response
367+
isLoading: boolean
368+
// Mutation has data from a successful call
369+
isSuccess: boolean
370+
// Mutation is currently in an "error" state
371+
isError: boolean
372+
// Timestamp for when the latest mutation was initiated
373+
startedTimeStamp?: number
374+
375+
// A method to manually unsubscribe from the mutation call and reset the result to the uninitialized state
376+
reset: () => void
348377
}
349378
```
350379
@@ -373,17 +402,15 @@ selectFromResult: () => ({})
373402
- a `reset` method to reset the hook back to its original state and remove the current result from the cache
374403
- an `originalArgs` property that contains the argument passed to the last call of the `trigger` function.
375404
376-
#### Description
377-
378-
[summary](docblock://query/react/buildHooks.ts?token=UseMutation)
379-
380405
## `useQueryState`
381406
382407
```ts title="Accessing a useQuery hook" no-transpile
383408
const useQueryStateResult = api.endpoints.getPosts.useQueryState(arg, options)
384409
```
385410

386-
#### Signature
411+
[summary](docblock://query/react/buildHooks.ts?token=UseQueryState)
412+
413+
##### `useQueryState` Signature
387414

388415
```ts no-transpile
389416
type UseQueryState = (
@@ -398,20 +425,36 @@ type UseQueryStateOptions = {
398425

399426
type UseQueryStateResult<T> = {
400427
// Base query state
401-
originalArgs?: unknown // Arguments passed to the query
402-
data?: T // The latest returned result regardless of hook arg, if present
403-
currentData?: T // The latest returned result for the current hook arg, if present
404-
error?: unknown // Error result if present
405-
requestId?: string // A string generated by RTK Query
406-
endpointName?: string // The name of the given endpoint for the query
407-
startedTimeStamp?: number // Timestamp for when the query was initiated
408-
fulfilledTimeStamp?: number // Timestamp for when the query was completed
409-
410-
isUninitialized: false // Query has not started yet.
411-
isLoading: false // Query is currently loading for the first time. No data yet.
412-
isFetching: false // Query is currently fetching, but might have data from an earlier request.
413-
isSuccess: false // Query has data from a successful load.
414-
isError: false // Query is currently in an "error" state.
428+
429+
// Arguments passed to the query
430+
originalArgs?: unknown
431+
// The latest returned result regardless of hook arg, if present
432+
data?: T
433+
// The latest returned result for the current hook arg, if present
434+
currentData?: T
435+
// Error result if present
436+
error?: unknown
437+
// A string generated by RTK Query
438+
requestId?: string
439+
// The name of the given endpoint for the query
440+
endpointName?: string
441+
// Timestamp for when the query was initiated
442+
startedTimeStamp?: number
443+
// Timestamp for when the query was completed
444+
fulfilledTimeStamp?: number
445+
446+
// Derived request status booleans
447+
448+
// Query has not started yet.
449+
isUninitialized: boolean
450+
// Query is currently loading for the first time. No data yet.
451+
isLoading: boolean
452+
// Query is currently fetching, but might have data from an earlier request.
453+
isFetching: boolean
454+
// Query has data from a successful load.
455+
isSuccess: boolean
456+
// Query is currently in an "error" state.
457+
isError: boolean
415458
}
416459
```
417460
@@ -424,17 +467,15 @@ type UseQueryStateResult<T> = {
424467
- **Returns**
425468
- A query result object containing the current loading state, the actual data or error returned from the API call and metadata about the request. Can be customized with `selectFromResult`
426469
427-
#### Description
428-
429-
[summary](docblock://query/react/buildHooks.ts?token=UseQueryState)
430-
431470
## `useQuerySubscription`
432471
433472
```ts title="Accessing a useQuerySubscription hook" no-transpile
434473
const { refetch } = api.endpoints.getPosts.useQuerySubscription(arg, options)
435474
```
436475

437-
#### Signature
476+
[summary](docblock://query/react/buildHooks.ts?token=UseQuerySubscription)
477+
478+
##### `useQuerySubscription` Signature
438479

439480
```ts no-transpile
440481
type UseQuerySubscription = (
@@ -465,10 +506,6 @@ type UseQuerySubscriptionResult = {
465506
- **Returns**
466507
- An object containing a function to `refetch` the data
467508
468-
#### Description
469-
470-
[summary](docblock://query/react/buildHooks.ts?token=UseQuerySubscription)
471-
472509
## `useLazyQuery`
473510
474511
```ts title="Accessing a useLazyQuery hook" no-transpile
@@ -478,7 +515,9 @@ const [trigger, result, lastPromiseInfo] =
478515
const [trigger, result, lastPromiseInfo] = api.useLazyGetPostsQuery(options)
479516
```
480517

481-
#### Signature
518+
[summary](docblock://query/react/buildHooks.ts?token=UseLazyQuery)
519+
520+
### `useLazyQuery` Signature
482521

483522
```ts no-transpile
484523
type UseLazyQuery = (
@@ -496,32 +535,57 @@ type UseLazyQueryOptions = {
496535
type UseLazyQueryTrigger<T> = (arg: any, preferCacheValue?: boolean) => Promise<
497536
QueryResultSelectorResult
498537
> & {
499-
arg: unknown // Whatever argument was provided to the query
500-
requestId: string // A string generated by RTK Query
501-
subscriptionOptions: SubscriptionOptions // The values used for the query subscription
502-
abort: () => void // A method to cancel the query promise
503-
unwrap: () => Promise<T> // A method to unwrap the query call and provide the raw response/error
504-
unsubscribe: () => void // A method used to manually unsubscribe from the query results
505-
refetch: () => void // A method used to re-run the query. In most cases when using a lazy query, you will never use this and should prefer to call the trigger again.
506-
updateSubscriptionOptions: (options: SubscriptionOptions) () => void // A method used to update the subscription options (eg. pollingInterval)
538+
// Whatever argument was provided to the query
539+
arg: unknown
540+
// A string generated by RTK Query
541+
requestId: string
542+
// The values used for the query subscription
543+
subscriptionOptions: SubscriptionOptions
544+
545+
// A method to cancel the query promise
546+
abort: () => void
547+
// A method to unwrap the query call and provide the raw response/error
548+
unwrap: () => Promise<T>
549+
// A method used to manually unsubscribe from the query results
550+
unsubscribe: () => void
551+
// A method used to re-run the query. In most cases when using a lazy query, you will never use this and should prefer to call the trigger again.
552+
refetch: () => void
553+
// A method used to update the subscription options (eg. pollingInterval)
554+
updateSubscriptionOptions: (options: SubscriptionOptions) () => void
507555
}
508556

509557
type UseQueryStateResult<T> = {
510558
// Base query state
511-
originalArgs?: unknown // Arguments passed to the query
512-
data?: T // The latest returned result regardless of trigger arg, if present
513-
currentData?: T // The latest returned result for the trigger arg, if present
514-
error?: unknown // Error result if present
515-
requestId?: string // A string generated by RTK Query
516-
endpointName?: string // The name of the given endpoint for the query
517-
startedTimeStamp?: number // Timestamp for when the query was initiated
518-
fulfilledTimeStamp?: number // Timestamp for when the query was completed
519-
520-
isUninitialized: false // Query has not started yet.
521-
isLoading: false // Query is currently loading for the first time. No data yet.
522-
isFetching: false // Query is currently fetching, but might have data from an earlier request.
523-
isSuccess: false // Query has data from a successful load.
524-
isError: false // Query is currently in an "error" state.
559+
560+
// Arguments passed to the query
561+
originalArgs?: unknown
562+
// The latest returned result regardless of hook arg, if present
563+
data?: T
564+
// The latest returned result for the current hook arg, if present
565+
currentData?: T
566+
// Error result if present
567+
error?: unknown
568+
// A string generated by RTK Query
569+
requestId?: string
570+
// The name of the given endpoint for the query
571+
endpointName?: string
572+
// Timestamp for when the query was initiated
573+
startedTimeStamp?: number
574+
// Timestamp for when the query was completed
575+
fulfilledTimeStamp?: number
576+
577+
// Derived request status booleans
578+
579+
// Query has not started yet.
580+
isUninitialized: boolean
581+
// Query is currently loading for the first time. No data yet.
582+
isLoading: boolean
583+
// Query is currently fetching, but might have data from an earlier request.
584+
isFetching: boolean
585+
// Query has data from a successful load.
586+
isSuccess: boolean
587+
// Query is currently in an "error" state.
588+
isError: boolean
525589
}
526590

527591
type UseLazyQueryLastPromiseInfo = {
@@ -538,18 +602,16 @@ type UseLazyQueryLastPromiseInfo = {
538602
- `result`: A query result object containing the current loading state, the actual data or error returned from the API call and metadata about the request. Can be customized with `selectFromResult`
539603
- `lastPromiseInfo`: An object containing the last argument used to call the trigger function
540604
541-
#### Description
542-
543-
[summary](docblock://query/react/buildHooks.ts?token=UseLazyQuery)
544-
545605
## `useLazyQuerySubscription`
546606
547607
```ts title="Accessing a useLazyQuerySubscription hook" no-transpile
548608
const [trigger, lastArg] =
549609
api.endpoints.getPosts.useLazyQuerySubscription(options)
550610
```
551611

552-
#### Signature
612+
[summary](docblock://query/react/buildHooks.ts?token=UseLazyQuerySubscription)
613+
614+
##### `useLazyQuerySubscription` Signature
553615

554616
```ts no-transpile
555617
type UseLazyQuerySubscription = (
@@ -577,17 +639,15 @@ type UseLazyQuerySubscriptionTrigger = (
577639
- `trigger`: A function that fetches the corresponding data for the endpoint when called
578640
- `lastArg`: The last argument used to call the trigger function
579641
580-
#### Description
581642
582-
[summary](docblock://query/react/buildHooks.ts?token=UseLazyQuerySubscription)
583643
584644
## `usePrefetch`
585645
586646
```ts title="Accessing a usePrefetch hook" no-transpile
587647
const prefetchCallback = api.usePrefetch(endpointName, options)
588648
```
589649

590-
#### Signature
650+
##### Signature
591651

592652
```ts no-transpile
593653
type UsePrefetch = (
@@ -618,7 +678,7 @@ type PrefetchCallback = (arg: any, options?: UsePrefetchOptions) => void
618678
- **Returns**
619679
- A `prefetch` callback that when called, will initiate fetching the data for the provided endpoint
620680
621-
#### Description
681+
##### Description
622682
623683
A React hook which can be used to initiate fetching data ahead of time.
624684

0 commit comments

Comments
 (0)