@wisemen/vue-core-api-utils 2.0.0 → 2.0.2

package/skills/writing-infinitequeries/SKILL.md

@@ -4,25 +4,17 @@ description: >
   Infinite pagination with useOffsetInfiniteQuery and useKeysetInfiniteQuery, offset vs keyset strategies determined by backend API, fetchNextPage, hasNextPage, isFetchingNextPage, data/meta result structure, proper page assembly.
 type: core
 library: vue-core-api-utils
-library_version: "1.2.0"
-sources:
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/composables/query/offsetInfiniteQuery.composable.ts"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/composables/query/keysetInfiniteQuery.composable.ts"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/types/pagination.type.ts"
-subsystems:
-  - "Offset Pagination"
-  - "Keyset Pagination"
 ---
 
 # @wisemen/vue-core-api-utils — Writing Infinite Queries
 
-Paginate through large datasets with two strategies: offset-based (offset/limit) for traditional pagination, or keyset-based (cursor key) for real-time data and large datasets.
+Paginate through large datasets with two strategies: offset-based (offset/limit) for traditional pagination, or keyset-based (cursor/key) for real-time data and large datasets.
 
 **Choose your strategy based on what your backend API provides — not preference.**
 
 ## Setup
 
-### Offset Pagination (offset/limit-based)
+### Offset Pagination (page-based)
 
 ```typescript
 import { ref, computed } from 'vue'
@@ -36,16 +28,16 @@ export function useContactList() {
     params: {
       search: computed(() => search.value),
     },
-    queryFn: (pagination) => ContactService.getAll({
-      offset: pagination.offset,
-      limit: pagination.limit,
+    queryFn: ({ offset, limit }) => ContactService.getAll({
+      offset,
+      limit,
       search: search.value,
     }),
   })
 }
 ```
 
-The `queryFn` receives `{ offset: number, limit: number }`. Offset starts at 0 and advances by `limit` for each next page. Return results with `{ data: Contact[], meta: { offset, limit, total } }`.
+The `queryFn` receives `{ offset, limit }` — offset is the starting index (0 on the first page) and limit is the page size.
 
 ### Keyset Pagination (cursor-based)
 
@@ -61,16 +53,16 @@ export function useContactListKeyset() {
     params: {
       search: computed(() => search.value),
     },
-    queryFn: (pagination) => ContactService.getAllKeyset({
-      limit: pagination.limit,
-      key: pagination.key,
+    queryFn: ({ key, limit }) => ContactService.getAllKeyset({
+      limit,
+      after: key,
       search: search.value,
     }),
   })
 }
 ```
 
-The `queryFn` receives `{ key?: any, limit: number }`. The `key` is the cursor value from the previous page's `meta.next`, or `undefined` for the first page. Return results with `{ data: Contact[], meta: { next: unknown } }` — set `meta.next` to `null`/`undefined` when there are no more pages.
+The `queryFn` receives `{ key, limit }` — `key` is the cursor (`undefined` on the first page) and `limit` is the page size.
 
 ## Core Patterns
 
@@ -105,204 +97,14 @@ All pages are automatically concatenated into `data`. Access with `result.getVal
 
 Use `isFetchingNextPage` (not `isFetching`) to disable the load-more button only during pagination, not during initial load.
 
-### Custom page limit
-
-```typescript
-useOffsetInfiniteQuery('contactList', {
-  params: { search: computed(() => search.value) },
-  limit: 50, // Default is 20
-  queryFn: (pagination) => ContactService.getAll({
-    offset: pagination.offset,
-    limit: pagination.limit,
-  }),
-})
-```
-
-Pass `limit` as a top-level option to override the default page size (20).
-
-## Response Structures
-
-### Offset pagination response
-
-Your `queryFn` must return:
-```typescript
-{
-  data: Contact[],
-  meta: {
-    offset: number,  // Current offset
-    limit: number,   // Items per page
-    total: number,   // Total items across all pages
-  }
-}
-```
-
-The library uses `meta.offset + meta.limit >= meta.total` to determine if there are more pages.
-
-### Keyset pagination response
-
-Your `queryFn` must return:
-```typescript
-{
-  data: Contact[],
-  meta: {
-    next: unknown, // Cursor for the next page; null/undefined if no more pages
-  }
-}
-```
-
-The library uses `meta.next` as the `key` parameter for the subsequent page fetch.
-
-## Common Mistakes
-
-### CRITICAL: Import useInfiniteQuery from @tanstack/vue-query instead of your api module
-
-```typescript
-// ❌ Wrong: using TanStack directly
-import { useInfiniteQuery } from '@tanstack/vue-query'
-
-const { data, error } = useInfiniteQuery({
-  queryKey: ['contactList'],
-  queryFn: ({ pageParam = 0 }) => ContactService.getAll({ page: pageParam }),
-  getNextPageParam: (lastPage) => lastPage.nextPage,
-})
-// Loses AsyncResult, type safety, error codes
-```
-
-```typescript
-// ✅ Correct: use the composable from your api module
-import { useOffsetInfiniteQuery } from '@/api'
-
-const { result, fetchNextPage, hasNextPage } = useOffsetInfiniteQuery('contactList', {
-  params: { search: computed(() => '...') },
-  queryFn: (pagination) => ContactService.getAll({
-    offset: pagination.offset,
-    limit: pagination.limit,
-  }),
-})
-// Full AsyncResult wrapping, type safety, automatic error codes
-```
-
-Source: `src/composables/query/offsetInfiniteQuery.composable.ts`
-
-### CRITICAL: Return paginated data without wrapping in data/meta structure
-
-```typescript
-// ❌ Wrong: returning array directly
-queryFn: (pagination) => ContactService.getAll({
-  offset: pagination.offset,
-  limit: pagination.limit,
-})
-// Returns Contact[] directly instead of { data: Contact[], meta: { offset, limit, total } }
-// Library can't determine if there are more pages — infinite loop or stops too early
-```
-
-```typescript
-// ✅ Correct: return { data, meta } structure
-queryFn: (pagination) => ContactService.getAll({
-  offset: pagination.offset,
-  limit: pagination.limit,
-})
-// Where ContactService.getAll already returns { data: Contact[], meta: { offset, limit, total } }
-```
-
-The library requires the `{ data, meta }` shape to know how to concatenate pages and when to stop.
-
-Source: `src/types/pagination.type.ts` — `OffsetPaginationResponse`
-
-### HIGH: Use pageParam or cursor instead of offset/key
-
-```typescript
-// ❌ Wrong: using old pageParam naming
-queryFn: (pagination) => ContactService.getAll({
-  page: pagination.pageParam, // pageParam doesn't exist!
-  cursor: pagination.cursor,  // cursor doesn't exist!
-})
-```
-
-```typescript
-// ✅ Correct: use offset for offset pagination, key for keyset
-// Offset:
-queryFn: (pagination) => ContactService.getAll({
-  offset: pagination.offset, // OffsetPaginationParams.offset
-  limit: pagination.limit,
-})
-
-// Keyset:
-queryFn: (pagination) => ContactService.getAllKeyset({
-  key: pagination.key, // KeysetPaginationParams.key
-  limit: pagination.limit,
-})
-```
-
-`OffsetPaginationParams` has `{ offset: number, limit: number }`.
-`KeysetPaginationParams` has `{ key?: any, limit: number }`.
-
-Source: `src/types/pagination.type.ts`
-
-### HIGH: Mix offset and keyset pagination patterns in same query
-
-```typescript
-// ❌ Wrong: mixing pagination patterns
-const { result } = useOffsetInfiniteQuery('contactList', {
-  queryFn: (pagination) => ContactService.getAllKeyset({
-    key: pagination.key, // offset composable doesn't have key!
-    limit: pagination.limit,
-  }),
-})
-```
-
-```typescript
-// ✅ Correct: match composable to backend API
-// Use useOffsetInfiniteQuery for offset/limit APIs:
-const { result } = useOffsetInfiniteQuery('contactList', {
-  queryFn: (pagination) => ContactService.getAll({
-    offset: pagination.offset,
-    limit: pagination.limit,
-  }),
-})
-
-// Use useKeysetInfiniteQuery for cursor-based APIs:
-const { result } = useKeysetInfiniteQuery('contactListKeyset', {
-  queryFn: (pagination) => ContactService.getAllKeyset({
-    key: pagination.key,
-    limit: pagination.limit,
-  }),
-})
-```
-
-Each composable expects a specific pagination parameter type. Choose the right composable for your backend API.
-
-Source: `src/composables/query/offsetInfiniteQuery.composable.ts` and `keysetInfiniteQuery.composable.ts`
-
-### MEDIUM: Forget isFetchingNextPage flag; show loading on first page load
-
-```typescript
-// ❌ Wrong: using isFetching on load-more button
-const { result, isFetching, fetchNextPage } = useOffsetInfiniteQuery(...)
-<button @click="fetchNextPage" :disabled="isFetching">
-  {{ isFetching ? 'Loading...' : 'Load More' }}
-</button>
-// Button disabled on initial load too!
-```
-
-```typescript
-// ✅ Correct: use isFetchingNextPage for pagination button
-const { result, isFetchingNextPage, fetchNextPage } = useOffsetInfiniteQuery(...)
-<button @click="fetchNextPage" :disabled="isFetchingNextPage">
-  {{ isFetchingNextPage ? 'Loading...' : 'Load More' }}
-</button>
-```
-
-`isFetching` is true during initial load and when fetching next pages. `isFetchingNextPage` is true only when loading additional pages.
-
-Source: `src/composables/query/offsetInfiniteQuery.composable.ts` — `UseOffsetInfiniteQueryReturnType`
-
 ## Backend API Strategy
 
 > Offset vs keyset pagination depends entirely on your backend endpoint. Use the strategy your API provides.
+>
+> — Maintainer guidance
 
-If your API accepts `offset` and `limit` parameters, use `useOffsetInfiniteQuery`.
-If your API accepts a cursor `key` parameter, use `useKeysetInfiniteQuery`.
+If your API provides `offset` and `limit` parameters, use `useOffsetInfiniteQuery`.
+If your API provides a cursor/key parameter, use `useKeysetInfiniteQuery`.
 
 ## See Also
 

package/skills/writing-mutations/SKILL.md

@@ -1,12 +1,9 @@
 ---
 name: writing-mutations
 description: >
-  Create, update, delete resources using useMutation, typed queryKeysToInvalidate with optional param extractors, AsyncResult error handling, execute function, request shape with body/params separation.
+  Create, update, delete resources using useMutation, typed queryKeysToInvalidate, AsyncResult error handling, execute function, request shape with body/params separation.
 type: core
 library: vue-core-api-utils
-library_version: "1.2.0"
-sources:
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/composables/mutation/mutation.composable.ts"
 ---
 
 # @wisemen/vue-core-api-utils — Writing Mutations
@@ -21,8 +18,8 @@ import { ContactService } from '@/services'
 
 export function useCreateContact() {
   return useMutation({
-    queryFn: async (options: { body: ContactCreateForm }) => {
-      return await ContactService.create(options.body)
+    queryFn: async ({ body }: { body: ContactCreateForm }) => {
+      return await ContactService.create(body)
     },
     queryKeysToInvalidate: {
       contactList: {}, // Invalidate all contactList queries
@@ -31,7 +28,7 @@ export function useCreateContact() {
 }
 ```
 
-Every mutation should list which queries to invalidate via `queryKeysToInvalidate`.
+Every mutation must list which queries to invalidate via `queryKeysToInvalidate`.
 
 ## Core Patterns
 
@@ -61,54 +58,31 @@ async function handleSubmit(formData: ContactCreateForm) {
 
 Always `await execute()` and check the result state before continuing.
 
-### Update mutation with specific query invalidation using param extractors
-
-When you need to invalidate a specific query (rather than all queries with a key), pass param extractor functions:
+### Update mutation with specific query invalidation
 
 ```typescript
-export function useUpdateContact() {
-  return useMutation<ContactUpdateForm, Contact, { contactUuid: string }>({
-    queryFn: async (options) => {
-      return await ContactService.update(options.params.contactUuid, options.body)
+export function useUpdateContact(contactUuid: string) {
+  return useMutation({
+    queryFn: async ({ body }: { body: ContactUpdateForm }) => {
+      return await ContactService.update(contactUuid, body)
     },
     queryKeysToInvalidate: {
-      // Invalidate only the specific contact that was updated
       contactDetail: {
-        contactUuid: (params) => params.contactUuid,
+        contactUuid: (_params, _result) => contactUuid, // Invalidate only this contact's detail query
       },
-      // Invalidate all contact lists
-      contactList: {},
-    },
-  })
-}
-```
-
-Param extractors receive `(mutationParams, responseData)` and return the value for that query param. Empty object `{}` invalidates all queries with that key.
-
-### Mutation with URL params only (no body)
-
-```typescript
-export function useDeleteContact() {
-  return useMutation<void, void, { contactUuid: string }>({
-    queryFn: async (options) => {
-      return await ContactService.delete(options.params.contactUuid)
-    },
-    queryKeysToInvalidate: {
-      contactList: {},
+      contactList: {}, // Invalidate all contactList queries
     },
   })
 }
-
-// execute({ params: { contactUuid: '123' } })
 ```
 
-When `TReqData` is `void`, the `execute` call takes `{ params: TParams }` instead of `{ body, params }`.
+You can invalidate multiple queries. Include queries that depend on the data you're changing.
 
 ### Form integration
 
 ```vue
 <script setup lang="ts">
-import { reactive } from 'vue'
+import { ref } from 'vue'
 import { useCreateContact } from '@/composables'
 
 const form = reactive({ name: '', email: '' })
@@ -131,8 +105,8 @@ async function handleSubmit() {
     <button :disabled="result.isLoading()">
       {{ result.isLoading() ? 'Creating...' : 'Create' }}
     </button>
-    <div v-if="result.isErr()">
-      Error: {{ result.getError().errors?.[0]?.detail }}
+    <div v-if="result.isErr() && 'errors' in result.getError()">
+      Error: {{ result.getError().errors[0].detail }}
     </div>
   </form>
 </template>
@@ -140,125 +114,6 @@ async function handleSubmit() {
 
 Use `result.isLoading()` to disable the button during mutation.
 
-## Common Mistakes
-
-### CRITICAL: Import useMutation from @tanstack/vue-query instead of your api module
-
-```typescript
-// ❌ Wrong: using TanStack directly
-import { useMutation } from '@tanstack/vue-query'
-
-const mutation = useMutation({
-  mutationFn: async (data) => ContactService.create(data),
-  onSuccess: () => {
-    queryClient.invalidateQueries({ queryKey: ['contactList'] })
-  },
-})
-// Loses AsyncResult, type safety, error codes
-```
-
-```typescript
-// ✅ Correct: use the composable from your api module
-import { useMutation } from '@/api'
-
-const { execute, result } = useMutation({
-  queryFn: async (options: { body: ContactCreateForm }) => {
-    return await ContactService.create(options.body)
-  },
-  queryKeysToInvalidate: {
-    contactList: {}, // Typed, type-safe
-  },
-})
-// Full AsyncResult, type-safe queryKeysToInvalidate, error codes
-```
-
-Direct TanStack import loses type safety and AsyncResult wrapping.
-
-Source: `src/composables/mutation/mutation.composable.ts`
-
-### CRITICAL: Forget to list queryKeysToInvalidate; cache becomes stale
-
-```typescript
-// ❌ Wrong: no queryKeysToInvalidate
-const { execute } = useMutation({
-  queryFn: async (options: { body: ContactCreateForm }) => {
-    return await ContactService.create(options.body)
-  },
-  // Forgot queryKeysToInvalidate!
-})
-// Mutation succeeds but list query still shows old data
-```
-
-```typescript
-// ✅ Correct: invalidate affected queries
-const { execute } = useMutation({
-  queryFn: async (options: { body: ContactCreateForm }) => {
-    return await ContactService.create(options.body)
-  },
-  queryKeysToInvalidate: {
-    contactList: {}, // Invalidate all contactList queries
-  },
-})
-// After success, contactList queries refetch
-```
-
-If you don't list which queries to invalidate, the cache stays stale and the UI shows outdated data.
-
-Source: `src/composables/mutation/mutation.composable.ts` — `onSuccess` invalidation logic
-
-### HIGH: Not await execute(); code runs before mutation completes
-
-```typescript
-// ❌ Wrong: fire and forget
-async function handleSubmit() {
-  execute({ body: formData })
-  router.push('/contacts') // Redirects before mutation finishes!
-}
-```
-
-```typescript
-// ✅ Correct: await the result
-async function handleSubmit() {
-  const result = await execute({ body: formData })
-  if (result.isOk()) {
-    router.push('/contacts')
-  }
-  // If isErr, form stays visible for retry
-}
-```
-
-Not awaiting `execute()` means the mutation is still in flight when you navigate away or access the result.
-
-Source: `src/composables/mutation/mutation.composable.ts` — `execute` returns `Promise<ApiResult>`
-
-### HIGH: Use body instead of params for URL parameters
-
-```typescript
-// ❌ Wrong: URL params passed as body
-const { execute } = useMutation<SearchForm, Results, void>({
-  queryFn: async (options) => {
-    return await SearchService.search(options.body) // URL params shouldn't be in body
-  },
-})
-```
-
-```typescript
-// ✅ Correct: separate body (payload) from params (URL query string)
-const { execute } = useMutation<SearchForm, Results, { category: string }>({
-  queryFn: async (options) => {
-    const { body, params } = options
-    return await SearchService.search(body, params.category)
-  },
-})
-
-// Call with both:
-execute({ body: searchForm, params: { category: 'contacts' } })
-```
-
-`body` is for the request payload (POST/PUT body); `params` is for URL query string parameters. The `RequestParams` type enforces this shape automatically based on your generics.
-
-Source: `src/composables/mutation/mutation.composable.ts` — `RequestParams` type
-
 ## See Also
 
 - [Cache Management](../cache-management/SKILL.md) — Understanding which queries to invalidate

package/skills/writing-queries/SKILL.md

@@ -4,9 +4,6 @@ description: >
   Single resource queries using useQuery, computed ref params, staleTime configuration, queryFn, refetch, isFetching vs isLoading distinctions, automatic cache management.
 type: core
 library: vue-core-api-utils
-library_version: "1.2.0"
-sources:
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/composables/query/query.composable.ts"
 ---
 
 # @wisemen/vue-core-api-utils — Writing Queries
@@ -71,20 +68,6 @@ const { result } = useQuery('contactDetail', {
 
 `staleTime` determines how long cached data is considered fresh. After this time, the next query interaction triggers a background refetch.
 
-### Conditionally enable a query
-
-```typescript
-const isEnabled = computed(() => contactUuid.value !== null)
-
-const { result } = useQuery('contactDetail', {
-  params: { contactUuid: computed(() => contactUuid.value!) },
-  queryFn: () => ContactService.getByUuid(contactUuid.value!),
-  isEnabled,
-})
-```
-
-Use `isEnabled` to prevent the query from running until required data is available.
-
 ### Manually refetch on demand
 
 ```typescript
@@ -102,115 +85,6 @@ if (result.value.isOk()) {
 }
 ```
 
-## Common Mistakes
-
-### CRITICAL: Import useQuery from @tanstack/vue-query instead of your api module
-
-```typescript
-// ❌ Wrong: using TanStack directly
-import { useQuery } from '@tanstack/vue-query'
-
-const { data, error, isLoading } = useQuery({
-  queryKey: ['contactDetail', '123'],
-  queryFn: () => ContactService.getByUuid('123'),
-})
-// Loses AsyncResult wrapping, type safety, error code typing
-```
-
-```typescript
-// ✅ Correct: use the composable from your api module (or directly from the library)
-import { useQuery } from '@/api'
-import { computed } from 'vue'
-
-const { result, isLoading } = useQuery('contactDetail', {
-  params: { contactUuid: computed(() => '123') },
-  queryFn: () => ContactService.getByUuid('123'),
-  staleTime: 1000 * 60 * 5,
-})
-// Full type safety, AsyncResult wrapping, automatic error codes
-```
-
-Importing directly from @tanstack/vue-query bypasses the typed composable, losing AsyncResult wrapping, type-safe query keys, and error code typing.
-
-Source: `src/composables/query/query.composable.ts`
-
-### HIGH: Use plain ref for params instead of computed
-
-```typescript
-// ❌ Wrong: plain ref doesn't trigger refetch
-const userId = ref('123')
-const { result } = useQuery('userDetail', {
-  params: { userId }, // plain ref, not computed
-  queryFn: () => UserService.getById(userId.value),
-})
-// Later: userId.value = '456'
-// Query does NOT refetch — cache stays stale!
-```
-
-```typescript
-// ✅ Correct: use computed so query watches changes
-const userId = computed(() => props.userId)
-const { result } = useQuery('userDetail', {
-  params: { userId },
-  queryFn: () => UserService.getById(userId.value),
-})
-// userId changes → computed updates → query watches → refetch happens
-```
-
-When params are plain refs, the query doesn't watch them and the cache isn't invalidated when the param changes.
-
-Source: `src/composables/query/query.composable.ts` — `NestedMaybeRefOrGetter` type
-
-### HIGH: Not set staleTime; background refetch on every interaction
-
-```typescript
-// ❌ Wrong: no staleTime; background refetch constantly
-const { result } = useQuery('userDetail', {
-  params: { userId: computed(() => '123') },
-  queryFn: () => UserService.getById('123'),
-  // staleTime defaults to 0 — cache is immediately stale!
-})
-// Every component interaction triggers a refetch
-```
-
-```typescript
-// ✅ Correct: set staleTime to a reasonable value
-const { result } = useQuery('userDetail', {
-  params: { userId: computed(() => '123') },
-  queryFn: () => UserService.getById('123'),
-  staleTime: 1000 * 60 * 5, // 5 minutes
-})
-// Cache remains fresh for 5 minutes — background refetch only after expiry
-```
-
-Default `staleTime` is 0, meaning the cache is immediately considered stale. Every interaction triggers a background refetch. Set `staleTime` based on how frequently the data changes.
-
-### MEDIUM: Confuse isFetching with isLoading
-
-```typescript
-// ❌ Wrong: checking isLoading for conditional render
-const { result, isLoading } = useQuery(...)
-if (isLoading.value) {
-  return // Exits only on initial load!
-}
-// Code here runs while background refetch happens
-```
-
-```typescript
-// ✅ Correct: use result.isLoading() for state checks
-const { result } = useQuery(...)
-if (result.value.isLoading()) {
-  return // True only on initial load
-}
-// Use isFetching separately for background fetch indicator
-```
-
-`isLoading` is true only during the initial fetch. `isFetching` is true whenever any fetch is in progress (including background refetches). Use `result.isLoading()` for conditional rendering; use `isFetching` for loading indicators.
-
-Note: `isLoading`, `isError`, and `isSuccess` on the return type are deprecated — prefer `result.value.isLoading()`, `result.value.isErr()`, and `result.value.isOk()`.
-
-Source: `src/composables/query/query.composable.ts` — `UseQueryReturnType`
-
 ## See Also
 
 - [Cache Management](../cache-management/SKILL.md) — Understanding caching strategy informs staleTime choices