Documentation by stackoverfloweth · Pull Request #49 · kitbagjs/query

stackoverfloweth · 2025-07-23T03:12:54Z

added vitepress documentation, readme, as well as some release prep work
most of the actual documentation is authored heavily by Claude, so it'll need some close inspection for accuracy.

Netlify is not yet configured on this project yet, so here's the manual deploy of this branch
https://kitbag-query.netlify.app

netlify · 2025-09-02T01:54:23Z

✅ Deploy Preview for kitbag-query ready!

Name	Link
🔨 Latest commit	`ffff5b5`
🔍 Latest deploy log	https://app.netlify.com/projects/kitbag-query/deploys/68e477270200eb0008459dc9
😎 Deploy Preview	https://deploy-preview-49--kitbag-query.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

pleek91 · 2025-09-27T02:44:03Z

docs/core-concepts/queries.md

+| `errored` | `boolean` | Whether the query has encountered an error. |
+| `executed` | `boolean` | Whether the query has been executed at least once. |
+| `executing` | `boolean` | Whether the query is currently executing. |
+| `execute` | `(...args) => Promise<T>` | Function to manually trigger the query. Accepts arguments to use when calling your function, will override arguments supplied when creating the query. |


I don't think this is correct. execute doesn't accept any arguments. Its just a way to trigger the query. Specifically if immediate: false is used.

look like you're right. not sure how I got this mixed up. Not sure it's specifically for immediate: false though. Since execute is on regular query not only useQuery and immediate: boolean is only an option on useQuery

pleek91 · 2025-09-27T02:45:25Z

docs/core-concepts/queries.md

+### Execute
+
+The query includes `execute`, which can be called at any point to force the function to be called again. Execute optionally takes the arguments that match the arguments on the function. If supplied, these arguments will override whatever arguments were supplied when creating the query.
+
+```ts
+const messageFeedQuery = query(getMessages, () => null, { immediate: false })
+
+const newMessages = await messageFeedQuery.execute(Date.now())
+```


Unless I'm mistake about execute not accepting arguments, this section is incorrect.

pleek91 · 2025-09-27T02:45:59Z

docs/core-concepts/queries.md

+### Awaiting Queries
+
+When creating a query, you have the option of using `await` which changes the `data` attribute from being `T | undefined` to `T` since we can be sure that your function has executed.
+
+```ts
+const regularQuery = await query(getMessages, () => Date.now())
+//      ^? data: Message[] | undefined
+const awaitedQuery = await query(getMessages, () => Date.now())
+//      ^? data: Message[]
+```


Probably good to mention that when using async await with queries any errors will be thrown

pleek91 · 2025-09-27T02:55:08Z

docs/core-concepts/queries.md

+```ts
+const selectedUserId = ref<string | undefined>()
+
+const userQuery = useQuery(fetchUser, () => selectedUserId.value ? [selectedUserId.value] : null)


Chance to encourage more readable code with less turneries.

Suggested change

const userQuery = useQuery(fetchUser, () => selectedUserId.value ? [selectedUserId.value] : null)

const userQuery = useQuery(fetchUser, () => {

if(!selectedUserId.value) {

return null

}

return [selectedUserId.value]

})

pleek91 · 2025-09-27T02:55:45Z

docs/core-concepts/queries.md

+### Delayed execution
+
+Queries will always wait if the parameters aren't ready, but you can also setup a query to always delay execution of the function until you either call `execute()` on the query, or change the reactive parameters argument.


This needs an example, I think you're talking about immediate: false?

agreed this was unclear. Should be better with next commit

pleek91 · 2025-09-27T02:58:33Z

docs/core-concepts/queries.md

+// defineQuery - consistent configuration  
+const { useQuery: useUserQuery } = defineQuery(fetchUser, { staleTime: 60000 })
+const user1 = useUserQuery([1]) // Uses predefined staleTime
+const user2 = useUserQuery([2]) // Uses predefined staleTime


I think this is a bit misleading. You can still customize the options when you call the query. defineQuery does two things

pre defines the action

pre defines default options.

But you can override the options when you call the query.

tbh this was OG Claude code that I forgot to revisit 😅

docs/core-concepts/queries.md

pleek91 · 2025-09-28T02:28:09Z

docs/api/index.md

+
+**Parameters:**
+- `key`: Unique identifier for the query
+- `fetcher`: Async function that fetches the data


In code we call this the "action". I don't feel strongly about the name. But I'd use action for consistency.

I'll comment this out and revisit in future PR

pleek91 · 2025-09-28T02:28:45Z

docs/api/index.md

+function query<TParams extends any[], TData>(
+  key: string,
+  fetcher: (...params: TParams) => Promise<TData>,
+  options?: QueryOptions
+): QueryFunction<TParams, TData>


Incorrect example

I'll comment this out and revisit in future PR

pleek91 · 2025-09-28T02:29:29Z

docs/api/index.md

+  // Caching options
+  defaultStaleTime?: number
+  defaultCacheTime?: number
+
+  // Retry options
+  defaultRetryCount?: number
+  defaultRetryDelay?: number | ((attempt: number) => number)
+
+  // Other options...


Incorrect types

I'll comment this out and revisit in future PR

pleek91 · 2025-09-28T02:29:50Z

docs/api/index.md

+## Error Types
+
+### QueryError
+
+Base error class for query-related errors.
+
+```ts
+class QueryError extends Error {
+  readonly name = 'QueryError'
+  // ... error details
+}
+```
+
+For more detailed examples and usage patterns, see the [Core Concepts](/core-concepts/query-client) section.


Hallucination

I'll comment this out and revisit in future PR

pleek91 · 2025-09-28T02:31:22Z

docs/core-concepts/mutations.md

+  const response = await fetch('/api/users', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(userData)
+  })
+
+  if (!response.ok) throw new Error('Failed to create user')
+  return response.json()
+})


Incorrect example/syntax

it's commented out because I didn't get this far

pleek91 · 2025-09-28T02:33:01Z

docs/core-concepts/queries.md

+})
+```
+
+You can also setup a query NOT to execute immediately. These queries wait until you either call `execute()`, or change the reactive parameters argument.


Does changing the parameters execute a query that has immediate: false? Feels like it shouldn't.

good catch, I looked again and confirmed in query-preview that you MUST call execute to re-enable a query when immediate is false

stackoverfloweth requested a review from pleek91 July 23, 2025 03:12

stackoverfloweth self-assigned this Jul 23, 2025

stackoverfloweth added 4 commits September 22, 2025 22:17

defining exports, readme, testing releases

d486b50

setup vitepress docs, readme

69a42d8

export the things

85cb6e9

docs for humans by humans

069bef8

stackoverfloweth force-pushed the documentation-setup branch from 71348d1 to 069bef8 Compare September 23, 2025 03:19

stackoverfloweth and others added 2 commits September 22, 2025 22:21

add vitepress to gitignore

ff8b340

Remove VitePress cache files from tracking

73d8ea0

🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

pleek91 reviewed Sep 27, 2025

View reviewed changes

stackoverfloweth added 2 commits September 27, 2025 21:22

code review suggestions

26c7360

Merge branch 'main' into documentation-setup

f4b71eb

stackoverfloweth requested a review from pleek91 September 28, 2025 02:22

pleek91 reviewed Sep 28, 2025

View reviewed changes

code review suggestions

df5bf1b

stackoverfloweth requested a review from pleek91 September 28, 2025 18:07

pleek91 approved these changes Oct 2, 2025

View reviewed changes

stackoverfloweth added 4 commits October 5, 2025 21:07

code review suggestions

2893cc2

Merge branch 'main' into documentation-setup

8dfa098

Merge branch 'main' into documentation-setup

6c6b0d6

fixed typescript error on useQuery args type

ffff5b5

stackoverfloweth enabled auto-merge October 7, 2025 02:23

craig-pplx approved these changes Oct 7, 2025

View reviewed changes

pleek91 approved these changes Oct 7, 2025

View reviewed changes

stackoverfloweth merged commit 20cb2fb into main Oct 7, 2025
6 checks passed

stackoverfloweth deleted the documentation-setup branch October 7, 2025 02:27

-const userQuery = useQuery(fetchUser, () => selectedUserId.value ? [selectedUserId.value] : null)
+const userQuery = useQuery(fetchUser, () => {
+  if(!selectedUserId.value) {
+    return null
+  }
+   return [selectedUserId.value]
+})

		### Delayed execution

		Queries will always wait if the parameters aren't ready, but you can also setup a query to always delay execution of the function until you either call `execute()` on the query, or change the reactive parameters argument.

Uh oh!

Conversation

stackoverfloweth commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for kitbag-query ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stackoverfloweth Sep 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stackoverfloweth commented Jul 23, 2025 •

edited

Loading

netlify bot commented Sep 2, 2025 •

edited

Loading

stackoverfloweth Sep 27, 2025 •

edited

Loading