Documentation - Tags & Invalidation by stackoverfloweth · Pull Request #61 · kitbagjs/query

stackoverfloweth · 2025-10-17T03:35:37Z

Continue working through missing documentation pages

side quest:

include everything in main export off the default client
update queries docs to reflect recent changes to params syntax

craig-pplx · 2025-10-17T03:39:21Z

docs/compare-to-tanstack.md

 # Migrating from Tanstack

- no keys, caches function + arguments by default
+- no keys (tags don't require user to adopt naming scheme), caches function + arguments by default


I know both these libraries and this is confusing to me. I'd keep it as no keys. Because in tanstack keys are required to even make a query. You don't need to use tags at all. In fact some simple apps I'd expect to not need tags.

this file is not done, just taking notes along the way

nit: maybe don't commit unfinished pages or mark things that don't need reviewed. Just so I can skip them

craig-pplx · 2025-10-17T03:40:04Z

docs/core-concepts/queries.md

 }

-const catsQuery = query(searchCats, ['Maine Coon'])
+const catsQuery = query(searchCats, () => ['Maine Coon'])


Did we update the query function to accept a getter? I thought last we left it query accepted an array and use query accepted a getter.

oh duh, yeah I misremembered our change was only for useQuery. Good catch

craig-pplx · 2025-10-17T03:42:43Z

docs/core-concepts/tags-invalidation.md

 # Tags & Invalidation

-<!-- Tags provide a powerful way to organize and invalidate cached queries in Kitbag query. They allow you to group related queries and efficiently update your cache when data changes.
+When it comes time to refresh your query, there are a few options. First, each query has an `execute()` function, which will force the query to refetch and update the reactive `data` for your query but also any other query that shares the same function and arguments.


This second sentence is pretty long. Maybe break it up a bit.

Also I'd avoid "fetch" terminology. Actions are just functions. They don't necessarily fetch

craig-pplx · 2025-10-17T03:44:01Z

docs/core-concepts/tags-invalidation.md

+## Tags

-const { queryClient } = createQueryClient()
+Often we have multiple queries to different functions that are related to each other. For example, any queries that use the current user token in API headers would probably want to be called again if the token changes. Ideally these queries that are otherwise unrelated could be grouped together.


I think this could be simpler to understand if it was user id rather than token.

I chose token and API headers specifically because I thought it was a good example of a thing that could change and is NOT gonna be an argument for the query functions. I feel like userId could be an argument for fetchMe or maybe more so getNotifications in the readers mind

craig-pplx · 2025-10-17T03:47:07Z

docs/core-concepts/tags-invalidation.md

-    invalidateTags: [userTag, profileTag]
-  }
-)
+export const requiresUserContext = tag()


Yeah this example feels to complex to me. Let's make a cute cat example. We just need to show creating a tag, adding the tag to two queries, and then refreshing by the tag.

I tried something simpler and cat themed. Let's see what you think of this version

craig-pplx · 2025-10-17T03:49:04Z

docs/core-concepts/tags-invalidation.md

+## Tag Type

-Invalidate queries based on conditions:
+Kitbag Query also tracks a generic on each tag, which By default is `unknown`. This satisfies any query, but assigning your actual type not only validates the query type but also provides improved type safety later when accessing cached data, like in `setQueryData`


"Kitbag Query also supports typed tags. Where a generic type can be added to a tag for extra type safety"

Or something along those lines. We don't tract generics. We support typed tags. (That's like a concept, typed tags)

docs/core-concepts/tags-invalidation.md

pleek91 · 2025-10-21T02:12:48Z

docs/core-concepts/tags-invalidation.md

-const dashboardTag = tag('dashboard')
-const analyticsTag = tag('analytics')
-const settingsTag = tag('settings')
+As an example, let's group some queries that all use the same external API. That way when the API version changes, we can update all the queries at once because they share the same tag.


You're going to have to walk me through the thought behind this sort of example. Tags are really intended to be a grouping of related data. So I don't really understand this use case.

I'd just make the tags catsTag and refresh all cats data. The api version stuff is distracting IMO.

pleek91 · 2025-10-21T02:12:58Z

docs/core-concepts/tags-invalidation.md

-## Advanced Invalidation Patterns
+const catNamesQuery = useQuery(randomCatNames, () => [...], { tags: [usesCatsApi] })
+const catYearsQuery = useQuery(convertToCatYears, () => [...], { tags: [usesCatsApi] })
+const catYearsQuery = useQuery(checkCatIsNapping, () => [...], { tags: [usesCatsApi] })


catNappingQuery

pleek91 · 2025-10-21T02:14:53Z

docs/core-concepts/tags-invalidation.md

-### Background Invalidation
-
-Invalidate without showing loading states:
+Kitbag Query also supports typed tags. Where a generic type can be added to a tag for extra type safety. By default the tag type is `unknown`. This satisfies any query, but assigning your actual type not only validates the query type but also provides improved type safety later when accessing cached data, like in `setQueryData`.


This is how its suppose to work, but be aware its more of a concept then actually working code at this point.

It works for basic cases, but once you start having multiple types it kinda falls apart.

pleek91 · 2025-10-21T02:17:32Z

docs/core-concepts/tags-invalidation.md

+::: code-group

-const userQuery = query('user', fetchUser, { 
-  tags: [userTag] 
-})
+```vue [components/CatViewer.vue]
+<script lang="ts" setup>
+import { useQuery } from '@kitbag/query'

-const userFriendsQuery = query('user-friends', fetchUserFriends, { 
-  tags: [userTag, userRelationsTag] 
-})
+const { catId } = defineProps<{
+  catId: string
+}>()

-const userGroupsQuery = query('user-groups', fetchUserGroups, { 
-  tags: [userTag, userRelationsTag] 
-})
-
-// Update user profile - only invalidate direct user data
-userMutation.mutate(userData, {
-  invalidateTags: [userTag]
-})
-
-// Update friend relationship - invalidate user relations
-addFriendMutation.mutate(friendData, {
-  invalidateTags: [userRelationsTag]
-})
+const query = useQuery(fetchCat, () => [catId])
+</script>
 ```

-### By Access Patterns
-
-Group by how data is accessed:
-
-```ts
-const listTag = tag('list')       // List views
-const detailTag = tag('detail')   // Detail views
-const searchTag = tag('search')   // Search results
-
-const usersListQuery = query('users-list', fetchUsers, {
-  tags: [userTag, listTag]
-})
-
-const userDetailQuery = query('user-detail', fetchUserDetail, {
-  tags: [userTag, detailTag]
-})
-
-const userSearchQuery = query('user-search', searchUsers, {
-  tags: [userTag, searchTag]
-})
-```
+:::


I'd skip this example, we already went over how to create queries. Just show a typed tag example.

pleek91 · 2025-10-21T02:19:05Z

docs/core-concepts/tags-invalidation.md

 ```

-### 2. Don't Over-Tag
+```vue [components/CatViewer.vue]


The two parts example isn't necessary IMO. We can just create a typed tag, create a tagged query with that tag, then call refreshData with the tag with a specific value. And show that it'll refresh the query only if the id matches.

pleek91 · 2025-10-21T02:20:42Z

docs/compare-to-tanstack.md

 # Migrating from Tanstack

- no keys, caches function + arguments by default
+- no keys (tags don't require user to adopt naming scheme), caches function + arguments by default


nit: maybe don't commit unfinished pages or mark things that don't need reviewed. Just so I can skip them

Co-authored-by: Craig Harshbarger <pleek91@gmail.com>

craig-pplx

Couple last suggestions. Otherwise very clean and concise. Love it

craig-pplx · 2025-10-23T03:40:53Z

docs/core-concepts/tags-invalidation.md

-  }
-)
+  // invalidates only queries that call searchCats with ['Himalayan']
+  refreshQueryData(searchCats, () => ['Himalayan'])


I don't think this uses a getter. It's not reactive.

docs/core-concepts/tags-invalidation.md

craig-pplx · 2025-10-23T03:44:37Z

docs/core-concepts/tags-invalidation.md

-  search: tag('search')
+function save(catId: string): Promise<void> {
+  ...
+  refreshQueryData(catIdTag(catId))


Along with this we should show how on a query the tags can be a getter. So the list of cats and be tagged based on each cat in the list. That way if cat 1 is refreshed, the list of cats (which contains cat 1) is refreshed as well.

Co-authored-by: Craig Harshbarger <craig.harshbarger@perplexity.ai>

stackoverfloweth added 3 commits October 16, 2025 22:31

export everything on default client

0b31991

update queries to reflect recent changes to params syntax

8f5eb6f

updated page for tags & invalidation

798051e

stackoverfloweth requested a review from pleek91 October 17, 2025 03:35

stackoverfloweth self-assigned this Oct 17, 2025

craig-pplx reviewed Oct 17, 2025

View reviewed changes

code review suggestions

65a4cba

stackoverfloweth requested a review from craig-pplx October 21, 2025 01:01

pleek91 reviewed Oct 21, 2025

View reviewed changes

stackoverfloweth and others added 3 commits October 22, 2025 20:18

Merge branch 'main' into docs-tags

f620943

Update docs/core-concepts/tags-invalidation.md

6162085

Co-authored-by: Craig Harshbarger <pleek91@gmail.com>

code review suggestions

a26edef

stackoverfloweth requested a review from pleek91 October 23, 2025 02:05

craig-pplx approved these changes Oct 23, 2025

View reviewed changes

stackoverfloweth and others added 2 commits October 24, 2025 13:47

Update docs/core-concepts/tags-invalidation.md

2750e58

Co-authored-by: Craig Harshbarger <craig.harshbarger@perplexity.ai>

code review suggestions

98dce67

pleek91 approved these changes Oct 25, 2025

View reviewed changes

stackoverfloweth merged commit 488a52a into main Oct 25, 2025
2 checks passed

stackoverfloweth deleted the docs-tags branch October 25, 2025 01:29

Uh oh!

Conversation

stackoverfloweth commented Oct 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

craig-pplx left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants