diff --git a/packages/query-devtools/src/Explorer.tsx b/packages/query-devtools/src/Explorer.tsx index a04d9a6ad8..57cf872d60 100644 --- a/packages/query-devtools/src/Explorer.tsx +++ b/packages/query-devtools/src/Explorer.tsx @@ -36,6 +36,9 @@ import type { Query } from '@tanstack/query-core' * filled with the remaining elements * @example * chunkArray(['a','b', 'c', 'd', 'e'], 2) // returns [['a','b'], ['c', 'd'], ['e']] + * @param array - The elements to chunk. + * @param size - The number of elements per chunk. Below `1`, no chunks are returned. + * @returns The chunks. */ function chunkArray( array: Array, @@ -261,10 +264,22 @@ type ExplorerProps = { onEdit?: () => void } +/** + * Checks whether a value is iterable. + * @param x - The value to check. + * @returns `true` if `x` has a `Symbol.iterator` method. + */ function isIterable(x: any): x is Iterable { return Symbol.iterator in x } +/** + * Renders an expandable tree view of a value, used to explore a query's data in the devtools. It + * can also edit and delete entries in the query's data. + * @param props - The value to show and its label, plus the options for expanding, editing, and + * deleting entries. + * @returns The tree view. + */ export default function Explorer(props: ExplorerProps) { const theme = useTheme() const css = useQueryDevtoolsContext().shadowDOMTarget diff --git a/packages/query-devtools/src/contexts/DevtoolsOfflineContext.ts b/packages/query-devtools/src/contexts/DevtoolsOfflineContext.ts index 3447afee7c..384a73d1f9 100644 --- a/packages/query-devtools/src/contexts/DevtoolsOfflineContext.ts +++ b/packages/query-devtools/src/contexts/DevtoolsOfflineContext.ts @@ -3,6 +3,11 @@ import type { DevtoolsOfflineState } from './types' export const DevtoolsOfflineContext = createContext() +/** + * Returns the devtools offline state provided by `DevtoolsOfflineProvider`. + * @returns The offline state. + * @throws {Error} If there is no `DevtoolsOfflineProvider` above. + */ export function useDevtoolsOffline() { const state = useContext(DevtoolsOfflineContext) if (!state) throw new Error('Missing DevtoolsOfflineProvider') diff --git a/packages/query-devtools/src/contexts/DevtoolsStateContext.ts b/packages/query-devtools/src/contexts/DevtoolsStateContext.ts index 33490a27fe..ee89c2e8bc 100644 --- a/packages/query-devtools/src/contexts/DevtoolsStateContext.ts +++ b/packages/query-devtools/src/contexts/DevtoolsStateContext.ts @@ -3,6 +3,11 @@ import type { DevtoolsState } from './types' export const DevtoolsStateContext = createContext() +/** + * Returns the devtools selection and panel state provided by `DevtoolsStateProvider`. + * @returns The selection and panel state. + * @throws {Error} If there is no `DevtoolsStateProvider` above. + */ export function useDevtoolsState() { const state = useContext(DevtoolsStateContext) if (!state) throw new Error('Missing DevtoolsStateProvider') diff --git a/packages/query-devtools/src/contexts/DevtoolsSubscriptionsContext.ts b/packages/query-devtools/src/contexts/DevtoolsSubscriptionsContext.ts index 2c5308ce2a..f600530b83 100644 --- a/packages/query-devtools/src/contexts/DevtoolsSubscriptionsContext.ts +++ b/packages/query-devtools/src/contexts/DevtoolsSubscriptionsContext.ts @@ -4,6 +4,11 @@ import type { DevtoolsSubscriptions } from './types' export const DevtoolsSubscriptionsContext = createContext() +/** + * Returns the devtools cache subscription registries provided by `DevtoolsSubscriptionsProvider`. + * @returns The cache subscription registries. + * @throws {Error} If there is no `DevtoolsSubscriptionsProvider` above. + */ export function useDevtoolsSubscriptions() { const subscriptions = useContext(DevtoolsSubscriptionsContext) if (!subscriptions) throw new Error('Missing DevtoolsSubscriptionsProvider') diff --git a/packages/query-devtools/src/contexts/QueryDevtoolsContext.ts b/packages/query-devtools/src/contexts/QueryDevtoolsContext.ts index 7a9c11dfbb..8c52388a8e 100644 --- a/packages/query-devtools/src/contexts/QueryDevtoolsContext.ts +++ b/packages/query-devtools/src/contexts/QueryDevtoolsContext.ts @@ -18,6 +18,10 @@ export const QueryDevtoolsContext = createContext({ shadowDOMTarget: undefined, }) +/** + * Returns the devtools configuration from context, such as the `client` and the `onlineManager`. + * @returns The devtools configuration. + */ export function useQueryDevtoolsContext() { return useContext(QueryDevtoolsContext) } diff --git a/packages/query-devtools/src/contexts/ThemeContext.ts b/packages/query-devtools/src/contexts/ThemeContext.ts index dfb286341f..ebcfcd4923 100644 --- a/packages/query-devtools/src/contexts/ThemeContext.ts +++ b/packages/query-devtools/src/contexts/ThemeContext.ts @@ -5,6 +5,10 @@ export const ThemeContext = createContext>( () => 'dark' as const, ) +/** + * Returns the devtools theme from context. + * @returns A getter for the current theme, `'light'` or `'dark'`. Defaults to `'dark'`. + */ export function useTheme() { return useContext(ThemeContext) } diff --git a/packages/query-devtools/src/createCacheSubscriptionRegistry.ts b/packages/query-devtools/src/createCacheSubscriptionRegistry.ts index 8ad6b7b124..66029a3d37 100644 --- a/packages/query-devtools/src/createCacheSubscriptionRegistry.ts +++ b/packages/query-devtools/src/createCacheSubscriptionRegistry.ts @@ -1,6 +1,11 @@ import { onCleanup } from 'solid-js' import type { Accessor, Setter } from 'solid-js' +/** + * Creates a registry of components subscribed to a cache, so each one only updates for the cache + * events it cares about. + * @returns The `register` and `notify` functions of the registry. + */ export function createCacheSubscriptionRegistry() { const subscriptions = new Map< symbol, @@ -10,6 +15,13 @@ export function createCacheSubscriptionRegistry() { } >() + /** + * Registers a subscription that is removed when the current owner is cleaned up. + * @param callback - Computes the value from the cache. + * @param setter - Receives the computed value on every update. + * @param shouldUpdate - Decides whether an event updates this subscription. Defaults to every + * event. + */ function register( callback: (cache: Accessor) => Exclude, setter: Setter, @@ -23,6 +35,12 @@ export function createCacheSubscriptionRegistry() { onCleanup(() => subscriptions.delete(id)) } + /** + * Updates every subscription whose `shouldUpdate` accepts the event. + * @param cache - The cache to compute the values from. + * @param event - The cache event. + * @param schedule - Runs each update. Defaults to running it right away. + */ function notify( cache: Accessor, event: TEvent, diff --git a/packages/query-devtools/src/icons/index.tsx b/packages/query-devtools/src/icons/index.tsx index 7075634de8..345b4d87ba 100644 --- a/packages/query-devtools/src/icons/index.tsx +++ b/packages/query-devtools/src/icons/index.tsx @@ -1,5 +1,9 @@ import { Show, createUniqueId } from 'solid-js' +/** + * Renders the search icon. + * @returns The icon's SVG element. + */ export function Search() { return ( @@ -429,6 +511,10 @@ export function Check(props: { checked: boolean; theme: 'light' | 'dark' }) { ) } +/** + * Renders the check circle icon. + * @returns The icon's SVG element. + */ export function CheckCircle() { return ( ( null, diff --git a/packages/query-devtools/src/providers/DevtoolsSubscriptionsProvider.tsx b/packages/query-devtools/src/providers/DevtoolsSubscriptionsProvider.tsx index a31c773cef..a551fe6b44 100644 --- a/packages/query-devtools/src/providers/DevtoolsSubscriptionsProvider.tsx +++ b/packages/query-devtools/src/providers/DevtoolsSubscriptionsProvider.tsx @@ -9,6 +9,11 @@ import type { import type { DevtoolsSubscriptions } from '../contexts/types' import type { ParentProps } from 'solid-js' +/** + * Provides the query and mutation cache subscription registries to its children. + * @param props - The `children` to render. + * @returns The `children`, wrapped in the context provider. + */ export function DevtoolsSubscriptionsProvider(props: ParentProps) { const queryCacheSubscriptions = createCacheSubscriptionRegistry< QueryCache, diff --git a/packages/query-devtools/src/utils.tsx b/packages/query-devtools/src/utils.tsx index ad2ede6d65..3b0208c2dc 100644 --- a/packages/query-devtools/src/utils.tsx +++ b/packages/query-devtools/src/utils.tsx @@ -3,6 +3,12 @@ import { createSignal, onCleanup, onMount } from 'solid-js' import type { Mutation, Query } from '@tanstack/query-core' import type { DevtoolsPosition } from './contexts' +/** + * Returns the status label of a query: fetching, inactive (no observers), paused, stale, or fresh, + * checked in that order. + * @param query - The query to label. + * @returns The status label. + */ export function getQueryStatusLabel(query: Query) { return query.state.fetchStatus === 'fetching' ? 'fetching' @@ -17,6 +23,12 @@ export function getQueryStatusLabel(query: Query) { type QueryStatusLabel = 'fresh' | 'stale' | 'paused' | 'inactive' | 'fetching' +/** + * Appends a capitalized side to a CSS property name, e.g. `border` and `left` to `borderLeft`. + * @param prop - The property name. + * @param side - The side to append. + * @returns The sided property name. + */ export function getSidedProp( prop: T, side: DevtoolsPosition, @@ -26,6 +38,12 @@ export function getSidedProp( }` as `${T}${Capitalize}` } +/** + * Returns the color of a query's status: blue while fetching, gray without observers, purple while + * paused, yellow when stale, otherwise green. + * @param params - The query's `queryState`, `observerCount`, and `isStale`. + * @returns The color name. + */ export function getQueryStatusColor({ queryState, observerCount, @@ -46,6 +64,12 @@ export function getQueryStatusColor({ : 'green' } +/** + * Returns the color of a mutation's status: purple while paused, red on error, yellow while pending, + * green on success, otherwise gray. + * @param params - The mutation's `status` and `isPaused`. + * @returns The color name. + */ export function getMutationStatusColor({ status, isPaused, @@ -64,6 +88,11 @@ export function getMutationStatusColor({ : 'gray' } +/** + * Returns the color of a query status label. + * @param label - The status label. + * @returns The color name. + */ export function getQueryStatusColorByLabel(label: QueryStatusLabel) { return label === 'fresh' ? 'green' @@ -78,8 +107,9 @@ export function getQueryStatusColorByLabel(label: QueryStatusLabel) { /** * Displays a string regardless of the type of the data - * @param {unknown} value Value to be stringified - * @param {boolean} beautify Formats json to multiline + * @param value - Value to be stringified + * @param beautify - Formats json to multiline + * @returns The value serialized with `superjson`, as a JSON string. */ export const displayValue = (value: unknown, beautify: boolean = false) => { const { json } = serialize(value) @@ -169,9 +199,10 @@ export const getPreferredColorScheme = () => { /** * updates nested data by path - * @param {unknown} oldData Data to be updated - * @param {Array} updatePath Path to the data to be updated - * @param {unknown} value New value + * @param oldData - Data to be updated + * @param updatePath - Path to the data to be updated + * @param value - New value + * @returns A copy of `oldData` with the value at `updatePath` replaced. */ export const updateNestedDataByPath = ( oldData: unknown, @@ -242,8 +273,8 @@ export const updateNestedDataByPath = ( /** * Deletes nested data by path - * @param {unknown} oldData Data to be updated - * @param {Array} deletePath Path to the data to be deleted + * @param oldData - Data to be updated + * @param deletePath - Path to the data to be deleted * @returns newData without the deleted items by path */ export const deleteNestedDataByPath = (