Add docs for kit-operations by streusselhirni · Pull Request #17 · teamnovu/kit

streusselhirni · 2026-09-04T09:58:56Z

Adding documentation for @teamnovu/kit-operations.

The docs focus on how to use the package. They don't explain the internal workings of the package.

Disclaimer: Claude assistet in making sure all relevant features are mentioned in the documentation and helped with code examples and some formulations. The full text and all code examples has been proof-read and checked by myself.

Note

Add docs for `@teamnovu/kit-operations` and export `appendQueryParams`

Adds setup and API documentation for @teamnovu/kit-operations in packages/operations/docs/.
Introduces appendQueryParams and toQueryParamEntries in packages/operations/src/queryParams.ts to serialize query parameters into API Platform bracket notation.
The serializers omit nullish values, use empty bracket suffixes for arrays, and drop cyclic back-references.
Risk: Adds appendQueryParams as a new top-level export in packages/operations/src/index.ts.

Changes since #17 opened

Clarified mutation body handling and parameter reactivity behavior in kit-operations [b43a9d1]
Clarified query and mutation configuration behavior including queryKey, queryFn, and enabled properties [b43a9d1]
Clarified resource tracking behavior for endpoints in kit-operations [b43a9d1]
Refined documentation of SSR transport context, error behavior, and query parameter handling [b43a9d1]
Clarified headers override behavior and composition patterns [b43a9d1]
Documented guidance for calling endpoints outside setup() and using sentinel values for header omission [b43a9d1]
Clarified type-only declaration behavior in kit-operations [b43a9d1]

^{Macroscope summarized 8646a4d.}

alpoxo · 2026-09-07T06:28:33Z

I think it would be good to describe in separate sections:

How to set it up (piece by piece)
All the different invalidation mechanisms / variants, maybe as one single code-block. E.g. now invalidateQueries and invalidateResources are spread through multiple sections and the invalidateQueries variant with an $invalidateKey used as a function is not yet documented

alpoxo · 2026-09-07T06:16:44Z

+bracket notation API Platform filters expect is a backend-specific concern:
+
+```ts
+function appendQueryParams(url: string, queryParams?: Record<string, unknown>): string {


I don't think this has to be part of the documentation, as it is not part of the library itself.

On one hand, I agree. On the other, it's a helper function I expect nearly everybody to use and it's kind of important for the code example above. I didn't like just using it and then writing "Please provide the appendQueryParams function yourself" without giving an example.

If it is this important, we should either integrate it in the library or put it elsewhere where we can refer to it.

As discussed, included the appendQueryParam function as it's own export in the package.

alpoxo · 2026-09-07T06:26:09Z

+))
+```
+
+For `useQueries`, run each entry through `toLossyQueryOptions`. It does nothing at runtime and only


toLossyQueryOptions should be used in any case where covariance is needed as useQuery in general has type definitions enforcing invariance in many cases where it shouldn't be necessary.

Made docs clearer on this

alpoxo · 2026-09-07T06:30:51Z

+    update: mutation<Project, ProjectInput>()
+      .url('/api/projects/:id')
+      .build(() => ({
+        options: { method: 'PATCH' },


Invalidation can be put here through onSuccess.

It would be better to only invalidate the specific resource with its id and not all projects - unless the intent is to also refetch the list - in which case it may make more sense to in addition invalidate the specific list endpoint.

Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>

Gather every invalidation variant into one code block: the `$invalidateKey` levels for tree, branch, endpoint and single call, and the `invalidateResources` forms for a type, an instance and several at once. The endpoint- and call-level keys were undocumented so far. Carry the invalidation in the quick start's update endpoint, so the example shows an operation that owns its own invalidation rules. Also adds the setup walkthrough and the note on loosening the option types.

…docs-operations

alpoxo · 2026-09-14T11:54:13Z

+    update: mutation<Project, ProjectInput>()
+      .url('/api/projects/:id')
+      .build(() => ({
+        options: { method: 'PATCH' },


It would be better to only invalidate the specific resource with its id and not all projects - unless the intent is to also refetch the list - in which case it may make more sense to in addition invalidate the specific list endpoint.

alpoxo · 2026-09-14T11:57:21Z

@@ -0,0 +1,382 @@
+# Setup
+
+This page wires the package into an existing Vue app, end to end. The package has no configuration


This page wires the Vue app? Nice, nothing more to do then :D

Add docs for kit-operations

218f554

streusselhirni requested a review from alpoxo September 4, 2026 09:58

macroscopeapp Bot reviewed Sep 4, 2026

View reviewed changes

Comment thread packages/operations/docs/index.md

Comment thread packages/operations/docs/index.md Outdated

Comment thread packages/operations/docs/index.md Outdated

alpoxo reviewed Sep 7, 2026

View reviewed changes

docs(operations): Correctly expand headers in makeQueryFn

bd1ceb8

Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>

macroscopeapp Bot reviewed Sep 7, 2026

View reviewed changes

Comment thread packages/operations/docs/index.md Outdated

Comment thread packages/operations/docs/index.md Outdated

streusselhirni added 3 commits September 7, 2026 10:25

feat(operations): included appendQueryParams in package and adapted docs

6b7ca0b

docs(operation): clearer wording

fed5890

macroscopeapp Bot reviewed Sep 7, 2026

View reviewed changes

streusselhirni added 5 commits September 7, 2026 11:12

feat(operations): correctly handle url fragments in appendQueryParams

f4a520b

docs(operations): wording

fdcf84b

fix(operations): prevent endless loop in appendQueryParams

06dee59

docs(operations): fix various wordings

f086b23

fix(operations):properly prevent endless loops in appendQueryParams

0232736

macroscopeapp Bot reviewed Sep 7, 2026

View reviewed changes

Comment thread packages/operations/docs/index.md

docs(operations):more wording

7625c9c

macroscopeapp Bot reviewed Sep 7, 2026

View reviewed changes

Comment thread packages/operations/docs/index.md

streusselhirni added 2 commits September 7, 2026 14:21

docs(operations):more wording

bac49b9

Merge branch 'nh-docs-operations' of github.com:teamnovu/kit into nh-…

8646a4d

…docs-operations

macroscopeapp Bot reviewed Sep 7, 2026

View reviewed changes

Comment thread packages/operations/docs/index.md

docs(operations):more wording

b43a9d1

alpoxo approved these changes Sep 16, 2026

View reviewed changes

		@@ -0,0 +1,382 @@
		# Setup

		This page wires the package into an existing Vue app, end to end. The package has no configuration

Uh oh!

Conversation

streusselhirni commented Sep 4, 2026 • edited by macroscopeapp Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add docs for @teamnovu/kit-operations and export appendQueryParams

Changes since #17 opened

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alpoxo commented Sep 7, 2026

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

streusselhirni commented Sep 4, 2026 •

edited by macroscopeapp Bot

Loading

Add docs for `@teamnovu/kit-operations` and export `appendQueryParams`