Skip to content

Conversation

JosNun
Copy link

@JosNun JosNun commented Sep 25, 2025

🎯 Changes

Add a type to match tuple prefixes to match partial query keys in QueryFilters and MutationFilters

Fixes #9680

It's worth noting, there may be a case where it makes sense to turn QueryFilters (and MutationFilters into a discriminated union on the exact field, so that we only allow partial query filter types in the case where exact is false (or unspecified), but it's possible there are cases where one would want partial query key matching even in the exact: true case, and I'm not sure the added constraint adds much benefit. If you'd like me to add that, let me know.

✅ Checklist

  • I have followed the steps in the Contributing guide.
  • I have tested this code locally with pnpm test:pr.

🚀 Release Impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

  • New Features

    • Improved TypeScript support for filtering queries and mutations by allowing partial key prefixes, enhancing autocomplete and type safety with no runtime changes.
  • Tests

    • Added type-level tests to validate partial key usage and ensure invalid keys are rejected by the type system.
  • Chores

    • Prepared a patch release entry to publish the fix.

…tionFilters`

Add a type to match tuple prefixes to match partial query keys in `QueryFilters` and `MutationFilters`

Fixes TanStack#9680
Copy link
Contributor

coderabbitai bot commented Sep 25, 2025

Walkthrough

Updated TypeScript typings to allow tuple prefixes for query and mutation keys by adding DropLast and TuplePrefixes utility types; updated QueryFilters.queryKey and MutationFilters.mutationKey types; added type-level tests and a patch changeset. No runtime behavior changed.

Changes

Cohort / File(s) Summary
Type utilities & filter typings
packages/query-core/src/utils.ts
Added DropLast and TuplePrefixes utility types; changed QueryFilters.queryKey from TQueryKey to TuplePrefixes<TQueryKey> and MutationFilters.mutationKey from MutationKey to TuplePrefixes<MutationKey> (type-only).
Type tests for partial keys
packages/query-core/src/__tests__/utils.test-d.tsx
Imported assertType and added type-level tests: assert allowed partial/expanded queryKey shapes and assert rejection of invalid keys via @ts-expect-error.
Release metadata
.changeset/wise-numbers-double.md
Added changeset for a patch release noting "fix: allow partial query keys in QueryFilters".

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

A rabbit typed through tuple rows,
Nibbling tails so prefixes grow.
Partial keys hop into sight,
Types now match both left and right.
No runtime carrots moved—just light delight. 🥕✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)
Check name Status Explanation
Title Check ✅ Passed The title succinctly and accurately summarizes the main change by indicating a fix in the query-core package to allow partial query keys in QueryFilters. It uses clear, concise phrasing without extraneous information or noise. This makes it easy for reviewers to understand the purpose of the pull request at a glance.
Linked Issues Check ✅ Passed The pull request directly implements the requested behavior from issue #9680 by adding the TuplePrefixes type and updating QueryFilters.queryKey and MutationFilters.mutationKey to accept partial keys. The added type-level tests verify correct and incorrect key shapes, demonstrating compliance with the expected behavior. All coding requirements from the linked issue are satisfied.
Out of Scope Changes Check ✅ Passed All modifications are focused on adding and updating TypeScript utility types, adjusting the query-core type declarations, and adding corresponding tests and a changeset. There are no unrelated or extraneous file changes beyond the scope of supporting partial query key matching. This confirms there are no out-of-scope modifications.
Description Check ✅ Passed The pull request description follows the repository template by including the “Changes,” “Checklist,” and “Release Impact” sections with the required content and checkboxes. It clearly describes the addition of tuple prefix types and references the linked issue fix. The description is complete and well-structured according to the provided template.
Docstring Coverage ✅ Passed No functions found in the changes. Docstring coverage check skipped.
✨ Finishing touches
🧪 Generate unit tests
  • Create PR with unit tests
  • Post copyable unit tests in a comment

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6e8f075 and a348b55.

📒 Files selected for processing (1)
  • .changeset/wise-numbers-double.md (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
  • .changeset/wise-numbers-double.md

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cd29063 and 7a0f865.

📒 Files selected for processing (2)
  • packages/query-core/src/types.ts (1 hunks)
  • packages/query-core/src/utils.ts (3 hunks)
🧰 Additional context used
🧬 Code graph analysis (1)
packages/query-core/src/utils.ts (1)
packages/query-core/src/types.ts (2)
  • TuplePrefixes (46-47)
  • MutationKey (1080-1088)
🔇 Additional comments (1)
packages/query-core/src/utils.ts (1)

36-36: Blocked by TuplePrefixes recursion bug

This swap to TuplePrefixes<TQueryKey> (and the analogous mutation change below) inherits the recursion defect I pointed out on the new TuplePrefixes helper: for the default TQueryKey = QueryKey we now instantiate TuplePrefixes<ReadonlyArray<unknown>>, which never terminates. Please see my comment in types.ts—we need to add a guard there before these property types can ship.

Copy link
Collaborator

@TkDodo TkDodo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please add some type tests 🙏

Copy link

nx-cloud bot commented Sep 25, 2025

View your CI Pipeline Execution ↗ for commit a348b55


☁️ Nx Cloud last updated this comment at 2025-09-26 09:48:40 UTC

Copy link

pkg-pr-new bot commented Sep 25, 2025

More templates

@tanstack/angular-query-experimental

npm i https://pkg.pr.new/@tanstack/angular-query-experimental@9686

@tanstack/eslint-plugin-query

npm i https://pkg.pr.new/@tanstack/eslint-plugin-query@9686

@tanstack/query-async-storage-persister

npm i https://pkg.pr.new/@tanstack/query-async-storage-persister@9686

@tanstack/query-broadcast-client-experimental

npm i https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@9686

@tanstack/query-core

npm i https://pkg.pr.new/@tanstack/query-core@9686

@tanstack/query-devtools

npm i https://pkg.pr.new/@tanstack/query-devtools@9686

@tanstack/query-persist-client-core

npm i https://pkg.pr.new/@tanstack/query-persist-client-core@9686

@tanstack/query-sync-storage-persister

npm i https://pkg.pr.new/@tanstack/query-sync-storage-persister@9686

@tanstack/react-query

npm i https://pkg.pr.new/@tanstack/react-query@9686

@tanstack/react-query-devtools

npm i https://pkg.pr.new/@tanstack/react-query-devtools@9686

@tanstack/react-query-next-experimental

npm i https://pkg.pr.new/@tanstack/react-query-next-experimental@9686

@tanstack/react-query-persist-client

npm i https://pkg.pr.new/@tanstack/react-query-persist-client@9686

@tanstack/solid-query

npm i https://pkg.pr.new/@tanstack/solid-query@9686

@tanstack/solid-query-devtools

npm i https://pkg.pr.new/@tanstack/solid-query-devtools@9686

@tanstack/solid-query-persist-client

npm i https://pkg.pr.new/@tanstack/solid-query-persist-client@9686

@tanstack/svelte-query

npm i https://pkg.pr.new/@tanstack/svelte-query@9686

@tanstack/svelte-query-devtools

npm i https://pkg.pr.new/@tanstack/svelte-query-devtools@9686

@tanstack/svelte-query-persist-client

npm i https://pkg.pr.new/@tanstack/svelte-query-persist-client@9686

@tanstack/vue-query

npm i https://pkg.pr.new/@tanstack/vue-query@9686

@tanstack/vue-query-devtools

npm i https://pkg.pr.new/@tanstack/vue-query-devtools@9686

commit: a2f2b8a

Copy link

codecov bot commented Sep 25, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.65%. Comparing base (cd29063) to head (a2f2b8a).

Additional details and impacted files

Impacted file tree graph

@@             Coverage Diff             @@
##             main    #9686       +/-   ##
===========================================
+ Coverage   46.38%   60.65%   +14.27%     
===========================================
  Files         214      143       -71     
  Lines        8488     5726     -2762     
  Branches     1920     1544      -376     
===========================================
- Hits         3937     3473      -464     
+ Misses       4108     1953     -2155     
+ Partials      443      300      -143     
Components Coverage Δ
@tanstack/angular-query-experimental 93.85% <ø> (ø)
@tanstack/eslint-plugin-query ∅ <ø> (∅)
@tanstack/query-async-storage-persister 43.85% <ø> (ø)
@tanstack/query-broadcast-client-experimental 24.39% <ø> (ø)
@tanstack/query-codemods ∅ <ø> (∅)
@tanstack/query-core 97.48% <ø> (ø)
@tanstack/query-devtools 3.48% <ø> (ø)
@tanstack/query-persist-client-core 79.60% <ø> (ø)
@tanstack/query-sync-storage-persister 84.61% <ø> (ø)
@tanstack/query-test-utils ∅ <ø> (∅)
@tanstack/react-query 96.00% <ø> (ø)
@tanstack/react-query-devtools 10.00% <ø> (ø)
@tanstack/react-query-next-experimental ∅ <ø> (∅)
@tanstack/react-query-persist-client 100.00% <ø> (ø)
@tanstack/solid-query 78.06% <ø> (ø)
@tanstack/solid-query-devtools ∅ <ø> (∅)
@tanstack/solid-query-persist-client 100.00% <ø> (ø)
@tanstack/svelte-query 87.58% <ø> (ø)
@tanstack/svelte-query-devtools ∅ <ø> (∅)
@tanstack/svelte-query-persist-client 100.00% <ø> (ø)
@tanstack/vue-query 71.10% <ø> (ø)
@tanstack/vue-query-devtools ∅ <ø> (∅)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…ilters`

add tests to verify that the new partial QueryKey matching for `QueryFilters` does match partial query keys, and also doesn't allow invalid query keys.
@JosNun
Copy link
Author

JosNun commented Sep 25, 2025

@coderabbitai review

Copy link
Contributor

coderabbitai bot commented Sep 25, 2025

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Comment on lines 39 to 46
export type DropLast<T extends ReadonlyArray<unknown>> = T extends readonly [
...infer R,
unknown,
]
? R
: never

export type TuplePrefixes<T extends ReadonlyArray<unknown>> =
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

all those types become part of the public interface, I don’t think we want that so please just inline them in utils.ts

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good thought! I didn't even think of that. Updated.

JosNun and others added 2 commits September 25, 2025 19:56
Copy link

changeset-bot bot commented Sep 26, 2025

🦋 Changeset detected

Latest commit: a348b55

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages
Name Type
@tanstack/query-core Patch
@tanstack/angular-query-experimental Patch
@tanstack/query-async-storage-persister Patch
@tanstack/query-broadcast-client-experimental Patch
@tanstack/query-persist-client-core Patch
@tanstack/query-sync-storage-persister Patch
@tanstack/react-query Patch
@tanstack/solid-query Patch
@tanstack/svelte-query Patch
@tanstack/vue-query Patch
@tanstack/angular-query-persist-client Patch
@tanstack/react-query-persist-client Patch
@tanstack/solid-query-persist-client Patch
@tanstack/svelte-query-persist-client Patch
@tanstack/react-query-devtools Patch
@tanstack/react-query-next-experimental Patch
@tanstack/solid-query-devtools Patch
@tanstack/svelte-query-devtools Patch
@tanstack/vue-query-devtools Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

matchQuery types don't support partial keys
3 participants