docs: mention second parameter for cancelQueries
#9597
Conversation
WalkthroughDocumentation updates add a second optional parameter Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant U as Caller
participant QC as QueryClient
participant Q as Matching Queries
U->>QC: cancelQueries(filters, cancelOptions?)
Note right of QC: cancelOptions: { silent?, revert? }
QC->>Q: Locate queries matching filters
alt revert = true
QC->>Q: Revert to previous state\n(restore data, set fetchStatus=idle)
else revert = false
QC->>Q: Leave current state unchanged
end
alt silent = true
Note over QC,U: Suppress CancelledError propagation
QC-->>U: Return retry promise (no throw)
else silent = false
QC-->>U: Propagate CancelledError on cancellation
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
docs/reference/QueryClient.md (1)
405-416: AddcancelOptionsparameter in example and specify return type forcancelQueriesTo align the docs with the core API signature and other async methods, include the second
cancelOptionsargument in the usage example and update the Returns section to reflect that it returns aPromise<void>.• File: docs/reference/QueryClient.md
• Lines: 405–416```tsx -await queryClient.cancelQueries({ queryKey: ['posts'], exact: true }) +await queryClient.cancelQueries( + { queryKey: ['posts'], exact: true }, + { silent: true } +)Options
filters?: QueryFilters: Query FilterscancelOptions?: CancelOptions: Cancel OptionsReturns
Promise<void>
- Resolves once cancellation has been attempted for all matching queries.
</blockquote></details> <details> <summary>docs/framework/react/guides/filters.md (4)</summary><blockquote> `74-76`: **Section placement reads well; consider surfacing “Cancel Options” more broadly.** This topic applies to query cancellation (and potentially mutation cancellation in other areas), not just filters. Optional: Promote “Cancel Options” to its own top-level guide (or a shared “Options”/“Cancellations” page) and link to it from both this page and the QueryClient reference, improving discoverability from the sidebar. --- `79-84`: **Enrich the example to demonstrate both options and the practical effect.** Showing only `silent: true` is correct but minimal. Add `revert: false` to illustrate behavior differences during an in-flight refetch. Apply this diff to extend the snippet: ```diff ```tsx -// Cancel specific queries silently -await queryClient.cancelQueries( - { queryKey: ['posts'] }, - { silent: true } -) +// Cancel specific queries: +// - silent: don't propagate a CancelledError to observers +// - revert: keep the current state instead of reverting to the previous one +await queryClient.cancelQueries( + { queryKey: ['posts'] }, + { silent: true, revert: false } +)--- `86-94`: **Consider adding a TypeScript shape alongside the prose.** A compact TS snippet improves scanability and aligns with other sections. Add this block just above the options list: ```ts type CancelOptions = { silent?: boolean // default: false revert?: boolean // default: true }
88-94: Refinesilentandrevertdocumentation to match actual behaviorReplace the existing snippet with the following for greater accuracy:
- `silent?: boolean` - - When set to `true`, prevents `CancelledError` from being thrown during query cancellation. - - Defaults to `false` + `silent?: boolean` + - When set to `true`, suppresses propagation of `CancelledError` to observers (e.g., `onError` callbacks) and related notifications, and returns the retry promise instead of rejecting. + - Defaults to `false` - `revert?: boolean` - - When set to `true`, reverts the query to its previous state before cancellation. - - Defaults to `true` + `revert?: boolean` + - When set to `true`, restores the query’s state (data and status) from immediately before the in-flight fetch, sets `fetchStatus` back to `idle`, and only throws if there was no prior data. + - Defaults to `true`
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
docs/framework/react/guides/filters.md(1 hunks)docs/reference/QueryClient.md(1 hunks)
|
View your CI Pipeline Execution ↗ for commit b913dbe
☁️ Nx Cloud last updated this comment at |
docs/reference/QueryClient.md
Outdated
| **Options** | ||
|
|
||
| - `filters?: QueryFilters`: [Query Filters](../../framework/react/guides/filters.md#query-filters) | ||
| - `cancelOptions?: CancelOptions`: [Cancel Options](../../framework/react/guides/filters.md#cancel-options) |
There was a problem hiding this comment.
| - `cancelOptions?: CancelOptions`: [Cancel Options](../../framework/react/guides/filters.md#cancel-options) | |
| - `cancelOptions?: CancelOptions`: [Cancel Options](../../framework/react/guides/query-cancellation#XXX) |
I think this would be a better place for CancelOptions. because CancelOptions is not about filters
There was a problem hiding this comment.
Thanks, moved it to query-cancellation guide.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/framework/react/guides/query-cancellation.md (1)
191-208: Clarify CancelOptions semantics and avoid implementation-leaky phrasing.
- “returns the retry promise instead of rejecting” is internal-detail-y and may confuse readers. Prefer describing outward effects (no observer error notifications) over return mechanics.
- Defaults for
silent/revertappear to vary by call site (e.g., internal cancels often usesilent: true; unmount cancels userevert: true). Please avoid stating global defaults unless guaranteed by the public API; otherwise, add a short note that defaults are contextual. Evidence from maintainers/issues showsCancelledErrorcarries{ silent, revert }flags and is often silent, not noisy. (github.com)Apply:
- - When set to `true`, suppresses propagation of `CancelledError` to observers (e.g., `onError` callbacks) and related notifications, and returns the retry promise instead of rejecting. - - Defaults to `false` + - When set to `true`, suppresses propagation of `CancelledError` to observers (e.g., `onError` callbacks) and related notifications. + - Note: In practice, many internal cancellations are silent by default; behavior can be contextual. @@ - - When set to `true`, restores the query’s state (data and status) from immediately before the in-flight fetch, sets `fetchStatus` back to `idle`, and only throws if there was no prior data. - - Defaults to `true` + - When set to `true`, restores the query’s state (data and status) from immediately before the in-flight fetch and sets `fetchStatus` back to `idle`. + - Note: Revert is commonly used for unmount/abort flows. + +```ts +// Type shape for reference +type CancelOptions = { + silent?: boolean + revert?: boolean +} +```Please confirm with maintainers whether global defaults should be documented. If yes, I’ll update the copy accordingly.
docs/reference/QueryClient.md (1)
414-416: Tiny formatting/grammar tweak for Options list.Insert a blank line between bullets to silence some linters and improve readability; keep consistent with other sections.
**Options** -- `filters?: QueryFilters`: [Query Filters](../../framework/react/guides/filters.md#query-filters) -`cancelOptions?: CancelOptions`: [Cancel Options](../../framework/react/guides/query-cancellation.md#cancel-options) +- `filters?: QueryFilters`: [Query Filters](../../framework/react/guides/filters.md#query-filters) + +- `cancelOptions?: CancelOptions`: [Cancel Options](../../framework/react/guides/query-cancellation.md#cancel-options)Also verify the anchor slug resolves correctly given the header is written as “##
Cancel Options” (Docusaurus usually slugifies this to#cancel-options). Build preview to be safe.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
docs/framework/react/guides/query-cancellation.md(1 hunks)docs/reference/QueryClient.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/reference/QueryClient.md
[grammar] ~414-~414: There might be a mistake here.
Context: ...filters?: QueryFilters: Query Filters - cancelOptions?: CancelOptions: [Cancel Options](../../framework/react...
(QB_NEW_EN)
🪛 markdownlint-cli2 (0.17.2)
docs/reference/QueryClient.md
412-412: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🔇 Additional comments (1)
docs/reference/QueryClient.md (1)
406-409: Sample update looks good.Two-argument example for
cancelQueriesis clear and consistent with the intended signature. ✔️
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/reference/QueryClient.md (1)
406-409: Example looks good; align the Returns section with async usageYou’re using
awaithere, so please document thatcancelQueriesreturnsPromise<void>instead of “does not return anything.”Apply this diff to the Returns subsection below:
-**Returns** - -This method does not return anything +**Returns** + +- `Promise<void>` + - Resolves when matching queries have been cancelled.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/reference/QueryClient.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/reference/QueryClient.md
[grammar] ~414-~414: There might be a mistake here.
Context: ...filters?: QueryFilters: Query Filters - cancelOptions?: CancelOptions: [Cancel Options](../../framework/react...
(QB_NEW_EN)
🪛 markdownlint-cli2 (0.17.2)
docs/reference/QueryClient.md
412-412: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🔇 Additional comments (2)
docs/reference/QueryClient.md (2)
412-412: Ignore MD036 here (repo-wide pattern)“Options” is consistently styled as bold text across this page; keep as-is despite markdownlint’s MD036 warning.
415-415: The requested script is running; I’ll revisit once we have its output.
The API page for
cancelQueriesdoes not mention that it accepts second optional parameter ofCancelOptions(docs page), which is indicated by the TypeScript signature.Cancel Optionssection to the Filters guide. Not sure if this is the optimal location for them though, please advise if there's more fitting place.cancelOptionsforcancelQueriescall.Summary by CodeRabbit
New Features
Documentation