@tanstack/query-devtools 5.104.1 → 5.104.2

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.
Files changed (35) hide show
  1. package/build/Devtools-BTIH1dw_.js.map +1 -1
  2. package/build/{Devtools-DDPb_OXS.cjs → Devtools-CJHY2Wx-.cjs} +212 -5
  3. package/build/{Devtools-BR7-Ww0_.js → Devtools-DBqcRO2f.js} +212 -5
  4. package/build/{DevtoolsComponent-PDsMk_-d.js → DevtoolsComponent-BdsgosNO.js} +2 -2
  5. package/build/{DevtoolsComponent-DdJdz_3E.cjs → DevtoolsComponent-BjB9B9oL.cjs} +2 -2
  6. package/build/{DevtoolsPanelComponent-D7InkRel.cjs → DevtoolsPanelComponent-Co1Z91vW.cjs} +2 -2
  7. package/build/{DevtoolsPanelComponent-DWMNAgBe.js → DevtoolsPanelComponent-Jyh8juKn.js} +2 -2
  8. package/build/dev.cjs +3 -3
  9. package/build/dev.js +3 -3
  10. package/build/index.d.cts +81 -0
  11. package/build/index.d.cts.map +1 -1
  12. package/build/index.d.ts +81 -0
  13. package/build/index.d.ts.map +1 -1
  14. package/build/index.js.map +1 -1
  15. package/build/{utils-BSq_mRvI.cjs → utils-C0KLuaCQ.cjs} +57 -12
  16. package/build/{utils-Fz9uQv9N.js → utils-DPVWL709.js} +57 -12
  17. package/build/utils-po3vZo_N.js.map +1 -1
  18. package/package.json +4 -4
  19. package/src/Devtools.tsx +25 -0
  20. package/src/Explorer.tsx +18 -4
  21. package/src/TanstackQueryDevtools.tsx +11 -0
  22. package/src/TanstackQueryDevtoolsPanel.tsx +14 -0
  23. package/src/contexts/DevtoolsOfflineContext.ts +5 -0
  24. package/src/contexts/DevtoolsStateContext.ts +5 -0
  25. package/src/contexts/DevtoolsSubscriptionsContext.ts +5 -0
  26. package/src/contexts/PiPContext.tsx +13 -0
  27. package/src/contexts/QueryDevtoolsContext.ts +4 -0
  28. package/src/contexts/ThemeContext.ts +4 -0
  29. package/src/contexts/types.ts +96 -0
  30. package/src/createCacheSubscriptionRegistry.ts +18 -0
  31. package/src/icons/index.tsx +102 -0
  32. package/src/providers/DevtoolsOfflineProvider.tsx +6 -0
  33. package/src/providers/DevtoolsStateProvider.tsx +5 -0
  34. package/src/providers/DevtoolsSubscriptionsProvider.tsx +5 -0
  35. package/src/utils.tsx +59 -15
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tanstack/query-devtools",
3
- "version": "5.104.1",
3
+ "version": "5.104.2",
4
4
  "description": "Developer tools to interact with and visualize the TanStack Query cache",
5
5
  "author": "tannerlinsley",
6
6
  "license": "MIT",
@@ -49,7 +49,7 @@
49
49
  "@solid-primitives/resize-observer": "^2.2.0",
50
50
  "@solid-primitives/storage": "^1.3.11",
51
51
  "@tanstack/match-sorter-utils": "^9.1.2",
52
- "@tanstack/query-core": "5.104.1",
52
+ "@tanstack/query-core": "5.104.2",
53
53
  "clsx": "^2.1.1",
54
54
  "goober": "^2.1.19",
55
55
  "solid-js": "^1.9.15",
@@ -65,14 +65,14 @@
65
65
  "scripts": {
66
66
  "clean": "premove ./build ./coverage ./dist-ts ./.cache/test-types",
67
67
  "compile": "tsc --project tsconfig.json",
68
- "test:eslint": "eslint --concurrency=auto ./src",
68
+ "test:oxlint": "oxlint ./src",
69
69
  "test:types": "npm-run-all --serial test:types:*",
70
- "test:types:ts56": "node ../../node_modules/typescript56/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts56 --tsBuildInfoFile .cache/test-types/ts56.tsbuildinfo",
71
70
  "test:types:ts57": "node ../../node_modules/typescript57/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts57 --tsBuildInfoFile .cache/test-types/ts57.tsbuildinfo",
72
71
  "test:types:ts58": "node ../../node_modules/typescript58/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts58 --tsBuildInfoFile .cache/test-types/ts58.tsbuildinfo",
73
72
  "test:types:ts59": "node ../../node_modules/typescript59/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts59 --tsBuildInfoFile .cache/test-types/ts59.tsbuildinfo",
74
73
  "test:types:tscurrent": "tsc --project tsconfig.json --outDir .cache/test-types/tscurrent --tsBuildInfoFile .cache/test-types/tscurrent.tsbuildinfo",
75
74
  "test:types:ts70": "node ../../node_modules/typescript70/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts70 --tsBuildInfoFile .cache/test-types/ts70.tsbuildinfo",
75
+ "test:types:ts71": "node ../../node_modules/typescript71/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts71 --tsBuildInfoFile .cache/test-types/ts71.tsbuildinfo",
76
76
  "test:lib": "vitest",
77
77
  "test:lib:dev": "pnpm run test:lib --watch",
78
78
  "test:build": "publint --strict && attw --pack",
package/src/Devtools.tsx CHANGED
@@ -101,10 +101,21 @@ interface QueryStatusProps {
101
101
  count: number
102
102
  }
103
103
 
104
+ /**
105
+ * The devtools component that `TanstackQueryDevtools` and `TanstackQueryDevtoolsPanel` lazily load
106
+ * and render.
107
+ */
104
108
  export type DevtoolsComponentType = Component<QueryDevtoolsProps> & {
105
109
  shadowDOMTarget?: ShadowRoot
106
110
  }
107
111
 
112
+ /**
113
+ * The floating devtools: a toggle button that opens a resizable panel, or the
114
+ * panel in a picture-in-picture window when one is open.
115
+ * @param props - The `localStore` that persists the devtools settings, and its
116
+ * `setLocalStore` setter.
117
+ * @returns The toggle button and the panel.
118
+ */
108
119
  export const Devtools: Component<DevtoolsPanelProps> = (props) => {
109
120
  const theme = useTheme()
110
121
  const css = useQueryDevtoolsContext().shadowDOMTarget
@@ -335,6 +346,12 @@ const PiPPanel: Component<{
335
346
  )
336
347
  }
337
348
 
349
+ /**
350
+ * The container of the embedded devtools panel, which tracks its width for
351
+ * the responsive layout.
352
+ * @param props - The `children` to render inside the panel.
353
+ * @returns The panel container.
354
+ */
338
355
  export const ParentPanel: Component<{
339
356
  children: JSX.Element
340
357
  }> = (props) => {
@@ -662,6 +679,14 @@ const DraggablePanel: Component<DevtoolsPanelProps> = (props) => {
662
679
  )
663
680
  }
664
681
 
682
+ /**
683
+ * The content of the devtools panel: the query and mutation lists with their
684
+ * filters and actions, and the details of the selected query or mutation.
685
+ * @param props - The `localStore` and `setLocalStore` that persist the devtools
686
+ * settings, `showPanelViewOnly` to hide the controls that only apply to the
687
+ * floating devtools, and `onClose` to close an embedded panel.
688
+ * @returns The panel content.
689
+ */
665
690
  export const ContentView: Component<ContentViewProps> = (props) => {
666
691
  const {
667
692
  selectedQueryHash,
package/src/Explorer.tsx CHANGED
@@ -30,11 +30,13 @@ import { useQueryDevtoolsContext, useTheme } from './contexts'
30
30
  import type { Query } from '@tanstack/query-core'
31
31
 
32
32
  /**
33
- * Chunk elements in the array by size
34
- *
35
- * when the array cannot be chunked evenly by size, the last chunk will be
36
- * filled with the remaining elements
33
+ * Chunk elements in the array by size.
37
34
  *
35
+ * When the array cannot be chunked evenly by size, the last chunk will be
36
+ * filled with the remaining elements.
37
+ * @param array - The elements to chunk.
38
+ * @param size - The number of elements per chunk. Below `1`, no chunks are returned.
39
+ * @returns The chunks.
38
40
  * @example
39
41
  * chunkArray(['a','b', 'c', 'd', 'e'], 2) // returns [['a','b'], ['c', 'd'], ['e']]
40
42
  */
@@ -262,10 +264,22 @@ type ExplorerProps = {
262
264
  onEdit?: () => void
263
265
  }
264
266
 
267
+ /**
268
+ * Checks whether a value is iterable.
269
+ * @param x - The value to check.
270
+ * @returns `true` if `x` has a `Symbol.iterator` method.
271
+ */
265
272
  function isIterable(x: any): x is Iterable<unknown> {
266
273
  return Symbol.iterator in x
267
274
  }
268
275
 
276
+ /**
277
+ * Renders an expandable tree view of a value, used to explore a query's data in the devtools. It
278
+ * can also edit and delete entries in the query's data.
279
+ * @param props - The value to show and its label, plus the options for expanding, editing, and
280
+ * deleting entries.
281
+ * @returns The tree view.
282
+ */
269
283
  export default function Explorer(props: ExplorerProps) {
270
284
  const theme = useTheme()
271
285
  const css = useQueryDevtoolsContext().shadowDOMTarget
@@ -15,8 +15,19 @@ import type {
15
15
  } from './contexts/types'
16
16
  import type { Signal } from 'solid-js'
17
17
 
18
+ /**
19
+ * The options for `TanstackQueryDevtools`, which mounts the floating devtools.
20
+ */
18
21
  export interface TanstackQueryDevtoolsConfig extends QueryDevtoolsProps {
22
+ /**
23
+ * Use this to pass a nonce to the style tag that is added to the document head. This is useful if
24
+ * you are using a Content Security Policy (CSP) nonce to allow inline styles.
25
+ */
19
26
  styleNonce?: string
27
+ /**
28
+ * Use this to pass a shadow DOM target to the devtools so that the styles will be applied
29
+ * within the shadow DOM instead of within the head tag in the light DOM.
30
+ */
20
31
  shadowDOMTarget?: ShadowRoot
21
32
  }
22
33
 
@@ -15,9 +15,23 @@ import type {
15
15
  } from './contexts/types'
16
16
  import type { Signal } from 'solid-js'
17
17
 
18
+ /**
19
+ * The options for `TanstackQueryDevtoolsPanel`, which mounts the devtools as an embedded panel.
20
+ */
18
21
  export interface TanstackQueryDevtoolsPanelConfig extends QueryDevtoolsProps {
22
+ /**
23
+ * Use this to pass a nonce to the style tag that is added to the document head. This is useful if
24
+ * you are using a Content Security Policy (CSP) nonce to allow inline styles.
25
+ */
19
26
  styleNonce?: string
27
+ /**
28
+ * Use this to pass a shadow DOM target to the devtools so that the styles will be applied
29
+ * within the shadow DOM instead of within the head tag in the light DOM.
30
+ */
20
31
  shadowDOMTarget?: ShadowRoot
32
+ /**
33
+ * Callback function that is called when the devtools panel is closed.
34
+ */
21
35
  onClose?: () => void
22
36
  }
23
37
 
@@ -3,6 +3,11 @@ import type { DevtoolsOfflineState } from './types'
3
3
 
4
4
  export const DevtoolsOfflineContext = createContext<DevtoolsOfflineState>()
5
5
 
6
+ /**
7
+ * Returns the devtools offline state provided by `DevtoolsOfflineProvider`.
8
+ * @returns The offline state.
9
+ * @throws {Error} If there is no `DevtoolsOfflineProvider` above.
10
+ */
6
11
  export function useDevtoolsOffline() {
7
12
  const state = useContext(DevtoolsOfflineContext)
8
13
  if (!state) throw new Error('Missing DevtoolsOfflineProvider')
@@ -3,6 +3,11 @@ import type { DevtoolsState } from './types'
3
3
 
4
4
  export const DevtoolsStateContext = createContext<DevtoolsState>()
5
5
 
6
+ /**
7
+ * Returns the devtools selection and panel state provided by `DevtoolsStateProvider`.
8
+ * @returns The selection and panel state.
9
+ * @throws {Error} If there is no `DevtoolsStateProvider` above.
10
+ */
6
11
  export function useDevtoolsState() {
7
12
  const state = useContext(DevtoolsStateContext)
8
13
  if (!state) throw new Error('Missing DevtoolsStateProvider')
@@ -4,6 +4,11 @@ import type { DevtoolsSubscriptions } from './types'
4
4
  export const DevtoolsSubscriptionsContext =
5
5
  createContext<DevtoolsSubscriptions>()
6
6
 
7
+ /**
8
+ * Returns the devtools cache subscription registries provided by `DevtoolsSubscriptionsProvider`.
9
+ * @returns The cache subscription registries.
10
+ * @throws {Error} If there is no `DevtoolsSubscriptionsProvider` above.
11
+ */
7
12
  export function useDevtoolsSubscriptions() {
8
13
  const subscriptions = useContext(DevtoolsSubscriptionsContext)
9
14
  if (!subscriptions) throw new Error('Missing DevtoolsSubscriptionsProvider')
@@ -32,6 +32,14 @@ const PiPContext = createContext<Accessor<PiPContextType> | undefined>(
32
32
  undefined,
33
33
  )
34
34
 
35
+ /**
36
+ * Provides the picture-in-picture window of the devtools, and functions to
37
+ * open and close it.
38
+ * @param props - The `children` to render, the `localStore` and
39
+ * `setLocalStore` that persist whether the window is open, and `disabled` to
40
+ * turn picture-in-picture off.
41
+ * @returns The context provider.
42
+ */
35
43
  export const PiPProvider = (props: PiPProviderProps) => {
36
44
  // Expose pipWindow that is currently active
37
45
  const [pipWindow, setPipWindow] = createSignal<Window | null>(null)
@@ -192,6 +200,11 @@ export const PiPProvider = (props: PiPProviderProps) => {
192
200
  )
193
201
  }
194
202
 
203
+ /**
204
+ * Reads the picture-in-picture context provided by {@link PiPProvider}.
205
+ * @returns An accessor of the picture-in-picture window and the functions to
206
+ * open and close it.
207
+ */
195
208
  export const usePiPWindow = () => {
196
209
  const context = createMemo(() => {
197
210
  const ctx = useContext(PiPContext)
@@ -18,6 +18,10 @@ export const QueryDevtoolsContext = createContext<QueryDevtoolsProps>({
18
18
  shadowDOMTarget: undefined,
19
19
  })
20
20
 
21
+ /**
22
+ * Returns the devtools configuration from context, such as the `client` and the `onlineManager`.
23
+ * @returns The devtools configuration.
24
+ */
21
25
  export function useQueryDevtoolsContext() {
22
26
  return useContext(QueryDevtoolsContext)
23
27
  }
@@ -5,6 +5,10 @@ export const ThemeContext = createContext<Accessor<'light' | 'dark'>>(
5
5
  () => 'dark' as const,
6
6
  )
7
7
 
8
+ /**
9
+ * Returns the devtools theme from context.
10
+ * @returns A getter for the current theme, `'light'` or `'dark'`. Defaults to `'dark'`.
11
+ */
8
12
  export function useTheme() {
9
13
  return useContext(ThemeContext)
10
14
  }
@@ -13,10 +13,23 @@ import type { createCacheSubscriptionRegistry } from '../createCacheSubscription
13
13
  type XPosition = 'left' | 'right'
14
14
  type YPosition = 'top' | 'bottom'
15
15
 
16
+ /**
17
+ * The side of the screen the devtools panel opens on.
18
+ */
16
19
  export type DevtoolsPosition = XPosition | YPosition
20
+ /**
21
+ * The corner of the screen the toggle button is placed in, or `'relative'` to place it in the
22
+ * normal document flow.
23
+ */
17
24
  export type DevtoolsButtonPosition = `${YPosition}-${XPosition}` | 'relative'
25
+ /**
26
+ * The color theme of the devtools. `'system'` follows the user's color scheme preference.
27
+ */
18
28
  export type Theme = 'dark' | 'light' | 'system'
19
29
 
30
+ /**
31
+ * A custom error that can be triggered on a query from the devtools.
32
+ */
20
33
  export interface DevtoolsErrorType {
21
34
  /**
22
35
  * The name of the error.
@@ -28,35 +41,109 @@ export interface DevtoolsErrorType {
28
41
  initializer: (query: Query) => Error
29
42
  }
30
43
 
44
+ /**
45
+ * The options shared by every devtools entry point: the `client` to inspect, the adapter's
46
+ * `queryFlavor` and `version` shown in the header, and the display options.
47
+ * `onClose` is only used by the panel entry point.
48
+ */
31
49
  export interface QueryDevtoolsProps {
50
+ /**
51
+ * The `QueryClient` whose caches the devtools inspect.
52
+ */
32
53
  readonly client: QueryClient
54
+ /**
55
+ * The adapter name shown next to the logo in the header, e.g. `'React Query'`.
56
+ */
33
57
  queryFlavor: string
58
+ /**
59
+ * The adapter version shown next to `queryFlavor` in the header.
60
+ */
34
61
  version: string
62
+ /**
63
+ * The `onlineManager` the devtools read and toggle to simulate going offline.
64
+ */
35
65
  onlineManager: typeof onlineManager
36
66
 
67
+ /**
68
+ * The position of the TanStack logo to open and close the devtools panel.
69
+ */
37
70
  buttonPosition?: DevtoolsButtonPosition
71
+ /**
72
+ * The position of the devtools panel.
73
+ */
38
74
  position?: DevtoolsPosition
75
+ /**
76
+ * Set this to `true` if you want the devtools to default to being open.
77
+ */
39
78
  initialIsOpen?: boolean
79
+ /**
80
+ * Use this so you can define custom errors that can be shown in the devtools.
81
+ */
40
82
  errorTypes?: Array<DevtoolsErrorType>
83
+ /**
84
+ * Use this to pass a shadow DOM target to the devtools so that the styles will be applied
85
+ * within the shadow DOM instead of within the head tag in the light DOM.
86
+ */
41
87
  shadowDOMTarget?: ShadowRoot
88
+ /**
89
+ * Callback function that is called when the devtools panel is closed. Only used by the panel
90
+ * entry point.
91
+ */
42
92
  onClose?: () => void
93
+ /**
94
+ * Set this to `true` to hide disabled queries from the devtools panel.
95
+ */
43
96
  hideDisabledQueries?: boolean
97
+ /**
98
+ * Set this to `'light'`, `'dark'`, or `'system'` to change the theme of the devtools panel.
99
+ */
44
100
  theme?: Theme
45
101
  }
46
102
 
103
+ /**
104
+ * The devtools UI state: the selected query and mutation, and the panel width.
105
+ */
47
106
  export interface DevtoolsState {
107
+ /**
108
+ * The hash of the query whose details are shown, or `null` if none is selected.
109
+ */
48
110
  selectedQueryHash: Accessor<string | null>
111
+ /**
112
+ * Selects a query by its hash, or clears the selection with `null`.
113
+ */
49
114
  setSelectedQueryHash: Setter<string | null>
115
+ /**
116
+ * The `mutationId` of the mutation whose details are shown, or `null` if none is selected.
117
+ */
50
118
  selectedMutationId: Accessor<number | null>
119
+ /**
120
+ * Selects a mutation by its `mutationId`, or clears the selection with `null`.
121
+ */
51
122
  setSelectedMutationId: Setter<number | null>
123
+ /**
124
+ * The current width of the devtools panel in pixels, used for the responsive layout.
125
+ */
52
126
  panelWidth: Accessor<number>
127
+ /**
128
+ * Updates the stored panel width, e.g. when the panel is resized.
129
+ */
53
130
  setPanelWidth: Setter<number>
54
131
  }
55
132
 
133
+ /**
134
+ * The registries through which devtools components subscribe to the query cache and the mutation
135
+ * cache, each one only updating for the cache events it cares about.
136
+ */
56
137
  export interface DevtoolsSubscriptions {
138
+ /**
139
+ * The registry through which devtools components subscribe to query cache events.
140
+ */
57
141
  queryCacheSubscriptions: ReturnType<
58
142
  typeof createCacheSubscriptionRegistry<QueryCache, QueryCacheNotifyEvent>
59
143
  >
144
+ /**
145
+ * The registry through which devtools components subscribe to mutation cache events.
146
+ */
60
147
  mutationCacheSubscriptions: ReturnType<
61
148
  typeof createCacheSubscriptionRegistry<
62
149
  MutationCache,
@@ -65,7 +152,16 @@ export interface DevtoolsSubscriptions {
65
152
  >
66
153
  }
67
154
 
155
+ /**
156
+ * Whether the devtools' `onlineManager` is offline, and a function that toggles it.
157
+ */
68
158
  export interface DevtoolsOfflineState {
159
+ /**
160
+ * Whether the devtools' `onlineManager` is currently offline.
161
+ */
69
162
  offline: Accessor<boolean>
163
+ /**
164
+ * Switches the devtools' `onlineManager` between online and offline.
165
+ */
70
166
  toggleOffline: () => void
71
167
  }
@@ -1,6 +1,11 @@
1
1
  import { onCleanup } from 'solid-js'
2
2
  import type { Accessor, Setter } from 'solid-js'
3
3
 
4
+ /**
5
+ * Creates a registry of components subscribed to a cache, so each one only updates for the cache
6
+ * events it cares about.
7
+ * @returns The `register` and `notify` functions of the registry.
8
+ */
4
9
  export function createCacheSubscriptionRegistry<TCache, TEvent>() {
5
10
  const subscriptions = new Map<
6
11
  symbol,
@@ -10,6 +15,13 @@ export function createCacheSubscriptionRegistry<TCache, TEvent>() {
10
15
  }
11
16
  >()
12
17
 
18
+ /**
19
+ * Registers a subscription that is removed when the current owner is cleaned up.
20
+ * @param callback - Computes the value from the cache.
21
+ * @param setter - Receives the computed value on every update.
22
+ * @param shouldUpdate - Decides whether an event updates this subscription. Defaults to every
23
+ * event.
24
+ */
13
25
  function register<T>(
14
26
  callback: (cache: Accessor<TCache>) => Exclude<T, Function>,
15
27
  setter: Setter<T>,
@@ -23,6 +35,12 @@ export function createCacheSubscriptionRegistry<TCache, TEvent>() {
23
35
  onCleanup(() => subscriptions.delete(id))
24
36
  }
25
37
 
38
+ /**
39
+ * Updates every subscription whose `shouldUpdate` accepts the event.
40
+ * @param cache - The cache to compute the values from.
41
+ * @param event - The cache event.
42
+ * @param schedule - Runs each update. Defaults to running it right away.
43
+ */
26
44
  function notify(
27
45
  cache: Accessor<TCache>,
28
46
  event: TEvent,