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

package/skills/writing-infinitequeries/SKILL.md

@@ -4,11 +4,11 @@ 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: "0.0.3"
+library_version: "1.2.0"
 sources:
-  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/usage/paginated-query.md"
   - "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"
@@ -16,13 +16,13 @@ subsystems:
 
 # @wisemen/vue-core-api-utils — Writing Infinite Queries
 
-Paginate through large datasets with two strategies: offset-based (page/limit) for traditional pagination, or keyset-based (cursor) 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 (page-based)
+### Offset Pagination (offset/limit-based)
 
 ```typescript
 import { ref, computed } from 'vue'
@@ -37,7 +37,7 @@ export function useContactList() {
       search: computed(() => search.value),
     },
     queryFn: (pagination) => ContactService.getAll({
-      page: pagination.pageParam,
+      offset: pagination.offset,
       limit: pagination.limit,
       search: search.value,
     }),
@@ -45,7 +45,7 @@ export function useContactList() {
 }
 ```
 
-Pagination parameter `pageParam` starts at 0 and increments. Return results with `{ data: Contact[], meta: { page, limit, total } }`.
+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 } }`.
 
 ### Keyset Pagination (cursor-based)
 
@@ -63,14 +63,14 @@ export function useContactListKeyset() {
     },
     queryFn: (pagination) => ContactService.getAllKeyset({
       limit: pagination.limit,
-      cursor: pagination.pageParam,
+      key: pagination.key,
       search: search.value,
     }),
   })
 }
 ```
 
-Pagination parameter `pageParam` is a cursor (string). Return results with `{ data: Contact[], meta: { next?: string } }` — the next cursor or undefined if no more pages.
+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.
 
 ## Core Patterns
 
@@ -105,9 +105,56 @@ 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 factory
+### CRITICAL: Import useInfiniteQuery from @tanstack/vue-query instead of your api module
 
 ```typescript
 // ❌ Wrong: using TanStack directly
@@ -122,54 +169,75 @@ const { data, error } = useInfiniteQuery({
 ```
 
 ```typescript
-// ✅ Correct: use factory composable
+// ✅ 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({
-    page: pagination.pageParam,
+    offset: pagination.offset,
     limit: pagination.limit,
   }),
 })
 // Full AsyncResult wrapping, type safety, automatic error codes
 ```
 
-Direct TanStack import loses the factory's type safety, AsyncResult wrapping, and error code typing.
-
-Source: Library architecture — always use composables from `createApiUtils()` factory
+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({
-  page: pagination.pageParam,
+  offset: pagination.offset,
   limit: pagination.limit,
 })
-// Returns Contact[] directly instead of { data: Contact[], meta: {...} }
-// QueryClient doesn't know how to append pages; pages overwrite instead of concat
+// 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({
-  page: pagination.pageParam,
+  offset: pagination.offset,
   limit: pagination.limit,
-}).then(data => ({
-  data,
-  meta: {
-    page: pagination.pageParam,
-    limit: pagination.limit,
-    total: 100, // Total count if available
-  }
-}))
-// QueryClient knows how to append pages
+})
+// 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,
+})
 ```
 
-Pagination requires the library to know which part of the response is the data array and which part is pagination metadata. Return an object with `data` (array) and `meta` (metadata).
+`OffsetPaginationParams` has `{ offset: number, limit: number }`.
+`KeysetPaginationParams` has `{ key?: any, limit: number }`.
 
-Source: `docs/packages/api-utils/pages/usage/paginated-query.md` Handling Pagination Results
+Source: `src/types/pagination.type.ts`
 
 ### HIGH: Mix offset and keyset pagination patterns in same query
 
@@ -177,7 +245,7 @@ Source: `docs/packages/api-utils/pages/usage/paginated-query.md` Handling Pagina
 // ❌ Wrong: mixing pagination patterns
 const { result } = useOffsetInfiniteQuery('contactList', {
   queryFn: (pagination) => ContactService.getAllKeyset({
-    cursor: pagination.pageParam, // offset expects page number!
+    key: pagination.key, // offset composable doesn't have key!
     limit: pagination.limit,
   }),
 })
@@ -185,26 +253,26 @@ const { result } = useOffsetInfiniteQuery('contactList', {
 
 ```typescript
 // ✅ Correct: match composable to backend API
-// Use useOffsetInfiniteQuery for page/limit APIs:
+// Use useOffsetInfiniteQuery for offset/limit APIs:
 const { result } = useOffsetInfiniteQuery('contactList', {
   queryFn: (pagination) => ContactService.getAll({
-    page: pagination.pageParam,
+    offset: pagination.offset,
     limit: pagination.limit,
   }),
 })
 
 // Use useKeysetInfiniteQuery for cursor-based APIs:
-const { result } = useKeysetInfiniteQuery('contactList', {
+const { result } = useKeysetInfiniteQuery('contactListKeyset', {
   queryFn: (pagination) => ContactService.getAllKeyset({
-    cursor: pagination.pageParam,
+    key: pagination.key,
     limit: pagination.limit,
   }),
 })
 ```
 
-Each composable expects a specific pagination parameter type. Offset expects a number; keyset expects a cursor string. Choose the right composable for your backend API.
+Each composable expects a specific pagination parameter type. Choose the right composable for your backend API.
 
-Source: `docs/packages/api-utils/pages/usage/paginated-query.md` Offset vs Keyset comparison
+Source: `src/composables/query/offsetInfiniteQuery.composable.ts` and `keysetInfiniteQuery.composable.ts`
 
 ### MEDIUM: Forget isFetchingNextPage flag; show loading on first page load
 
@@ -225,18 +293,16 @@ const { result, isFetchingNextPage, fetchNextPage } = useOffsetInfiniteQuery(...
 </button>
 ```
 
-`isFetching` is true during initial load and when fetching next pages. `isFetchingNextPage` is true only when loading additional pages. Use `isFetchingNextPage` for the load-more button.
+`isFetching` is true during initial load and when fetching next pages. `isFetchingNextPage` is true only when loading additional pages.
 
-Source: `docs/packages/api-utils/pages/usage/paginated-query.md` Return Values
+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 provides `page` and `limit` parameters, use `useOffsetInfiniteQuery`.
-If your API provides a `cursor` parameter, use `useKeysetInfiniteQuery`.
+If your API accepts `offset` and `limit` parameters, use `useOffsetInfiniteQuery`.
+If your API accepts a cursor `key` parameter, use `useKeysetInfiniteQuery`.
 
 ## See Also
 

package/skills/writing-mutations/SKILL.md

@@ -1,14 +1,12 @@
 ---
 name: writing-mutations
 description: >
-  Create, update, delete resources using factory-provided useMutation, typed queryKeysToInvalidate, AsyncResult error handling, execute function, request shape with body/params separation.
+  Create, update, delete resources using useMutation, typed queryKeysToInvalidate with optional param extractors, AsyncResult error handling, execute function, request shape with body/params separation.
 type: core
 library: vue-core-api-utils
-library_version: "0.0.3"
+library_version: "1.2.0"
 sources:
-  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/usage/mutation.md"
   - "wisemen-digital/wisemen-core:packages/web/api-utils/src/composables/mutation/mutation.composable.ts"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/factory/createApiMutationUtils.ts"
 ---
 
 # @wisemen/vue-core-api-utils — Writing Mutations
@@ -33,7 +31,7 @@ export function useCreateContact() {
 }
 ```
 
-Every mutation must list which queries to invalidate via `queryKeysToInvalidate`.
+Every mutation should list which queries to invalidate via `queryKeysToInvalidate`.
 
 ## Core Patterns
 
@@ -52,8 +50,7 @@ async function handleSubmit(formData: ContactCreateForm) {
     // Invalidated queries will refetch automatically
   } else if (response.isErr()) {
     const error = response.getError()
-    // Handle error based on code
-    if (error.errors[0].code === 'EMAIL_EXISTS') {
+    if ('errors' in error && error.errors[0].code === 'EMAIL_EXISTS') {
       toast.error('That email is already registered')
     } else {
       toast.error('Creation failed')
@@ -64,29 +61,54 @@ async function handleSubmit(formData: ContactCreateForm) {
 
 Always `await execute()` and check the result state before continuing.
 
-### Update mutation with specific query invalidation
+### 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:
 
 ```typescript
-export function useUpdateContact(contactUuid: string) {
-  return useMutation({
-    queryFn: async (options: { body: ContactUpdateForm }) => {
-      return await ContactService.update(contactUuid, options.body)
+export function useUpdateContact() {
+  return useMutation<ContactUpdateForm, Contact, { contactUuid: string }>({
+    queryFn: async (options) => {
+      return await ContactService.update(options.params.contactUuid, options.body)
+    },
+    queryKeysToInvalidate: {
+      // Invalidate only the specific contact that was updated
+      contactDetail: {
+        contactUuid: (params) => params.contactUuid,
+      },
+      // 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: {
-      contactDetail: {}, // Invalidate the specific contact
-      contactList: {},   // And the list
+      contactList: {},
     },
   })
 }
+
+// execute({ params: { contactUuid: '123' } })
 ```
 
-You can invalidate multiple queries. Include queries that depend on the data you're changing.
+When `TReqData` is `void`, the `execute` call takes `{ params: TParams }` instead of `{ body, params }`.
 
 ### Form integration
 
 ```vue
 <script setup lang="ts">
-import { ref } from 'vue'
+import { reactive } from 'vue'
 import { useCreateContact } from '@/composables'
 
 const form = reactive({ name: '', email: '' })
@@ -110,7 +132,7 @@ async function handleSubmit() {
       {{ result.isLoading() ? 'Creating...' : 'Create' }}
     </button>
     <div v-if="result.isErr()">
-      Error: {{ result.getError().errors[0].detail }}
+      Error: {{ result.getError().errors?.[0]?.detail }}
     </div>
   </form>
 </template>
@@ -120,7 +142,7 @@ Use `result.isLoading()` to disable the button during mutation.
 
 ## Common Mistakes
 
-### CRITICAL: Import useMutation from @tanstack/vue-query instead of factory
+### CRITICAL: Import useMutation from @tanstack/vue-query instead of your api module
 
 ```typescript
 // ❌ Wrong: using TanStack directly
@@ -136,7 +158,7 @@ const mutation = useMutation({
 ```
 
 ```typescript
-// ✅ Correct: use factory composable
+// ✅ Correct: use the composable from your api module
 import { useMutation } from '@/api'
 
 const { execute, result } = useMutation({
@@ -150,9 +172,9 @@ const { execute, result } = useMutation({
 // Full AsyncResult, type-safe queryKeysToInvalidate, error codes
 ```
 
-Direct TanStack import loses the factory's type safety and AsyncResult wrapping.
+Direct TanStack import loses type safety and AsyncResult wrapping.
 
-Source: Library architecture — always use composables from `createApiUtils()` factory
+Source: `src/composables/mutation/mutation.composable.ts`
 
 ### CRITICAL: Forget to list queryKeysToInvalidate; cache becomes stale
 
@@ -180,9 +202,9 @@ const { execute } = useMutation({
 // After success, contactList queries refetch
 ```
 
-If you don't list which queries to invalidate, the cache stays stale and the UI shows outdated data. Update returns success but list still shows old items.
+If you don't list which queries to invalidate, the cache stays stale and the UI shows outdated data.
 
-Source: `docs/packages/api-utils/pages/usage/mutation.md` Create Mutation Example
+Source: `src/composables/mutation/mutation.composable.ts` — `onSuccess` invalidation logic
 
 ### HIGH: Not await execute(); code runs before mutation completes
 
@@ -205,34 +227,37 @@ async function handleSubmit() {
 }
 ```
 
-Not awaiting `execute()` means the mutation is still in flight when you navigate away or access the result. Always await and check the result before continuing.
+Not awaiting `execute()` means the mutation is still in flight when you navigate away or access the result.
 
-Source: `docs/packages/api-utils/pages/usage/mutation.md` Usage in Component
+Source: `src/composables/mutation/mutation.composable.ts` — `execute` returns `Promise<ApiResult>`
 
-### HIGH: Use body instead of params for query parameters
+### HIGH: Use body instead of params for URL parameters
 
 ```typescript
-// ❌ Wrong: filter/search as body
-const { execute } = useMutation({
+// ❌ Wrong: URL params passed as body
+const { execute } = useMutation<SearchForm, Results, void>({
   queryFn: async (options) => {
-    return await SearchService.search(options.body) // params should go in URL!
+    return await SearchService.search(options.body) // URL params shouldn't be in body
   },
 })
 ```
 
 ```typescript
-// ✅ Correct: separate body and params
-const { execute } = useMutation({
+// ✅ 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(params) // URL params
+    return await SearchService.search(body, params.category)
   },
 })
+
+// Call with both:
+execute({ body: searchForm, params: { category: 'contacts' } })
 ```
 
-When mutations accept query parameters (filters, search), pass them in the `params` field of the options, not `body`. `body` is for request payload; `params` is for URL query string.
+`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: Source code `mutation.composable.ts` — request shape documentation
+Source: `src/composables/mutation/mutation.composable.ts` — `RequestParams` type
 
 ## See Also
 

package/skills/writing-queries/SKILL.md

@@ -1,13 +1,11 @@
 ---
 name: writing-queries
 description: >
-  Single resource queries using factory-provided useQuery, computed ref params, staleTime configuration, queryFn, refetch, isFetching vs isLoading distinctions, automatic cache management.
+  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: "0.0.3"
+library_version: "1.2.0"
 sources:
-  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/usage/query.md"
-  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/usage/overview.md"
   - "wisemen-digital/wisemen-core:packages/web/api-utils/src/composables/query/query.composable.ts"
 ---
 
@@ -73,6 +71,20 @@ 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
@@ -92,7 +104,7 @@ if (result.value.isOk()) {
 
 ## Common Mistakes
 
-### CRITICAL: Import useQuery from @tanstack/vue-query instead of factory
+### CRITICAL: Import useQuery from @tanstack/vue-query instead of your api module
 
 ```typescript
 // ❌ Wrong: using TanStack directly
@@ -106,7 +118,7 @@ const { data, error, isLoading } = useQuery({
 ```
 
 ```typescript
-// ✅ Correct: use factory-provided composable
+// ✅ Correct: use the composable from your api module (or directly from the library)
 import { useQuery } from '@/api'
 import { computed } from 'vue'
 
@@ -118,9 +130,9 @@ const { result, isLoading } = useQuery('contactDetail', {
 // Full type safety, AsyncResult wrapping, automatic error codes
 ```
 
-Importing directly from @tanstack/vue-query bypasses the typed factory, losing AsyncResult wrapping, type-safe query keys, and error code typing.
+Importing directly from @tanstack/vue-query bypasses the typed composable, losing AsyncResult wrapping, type-safe query keys, and error code typing.
 
-Source: Library architecture — always use composables from `createApiUtils()` factory
+Source: `src/composables/query/query.composable.ts`
 
 ### HIGH: Use plain ref for params instead of computed
 
@@ -147,9 +159,9 @@ const { result } = useQuery('userDetail', {
 
 When params are plain refs, the query doesn't watch them and the cache isn't invalidated when the param changes.
 
-Source: `docs/packages/api-utils/pages/usage/query.md` Usage in Vue Component section
+Source: `src/composables/query/query.composable.ts` — `NestedMaybeRefOrGetter` type
 
-### HIGH: Not set staleTime; serve stale cache indefinitely
+### HIGH: Not set staleTime; background refetch on every interaction
 
 ```typescript
 // ❌ Wrong: no staleTime; background refetch constantly
@@ -173,8 +185,6 @@ const { result } = useQuery('userDetail', {
 
 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.
 
-Source: `docs/packages/api-utils/pages/getting-started/installation.md` Setup section
-
 ### MEDIUM: Confuse isFetching with isLoading
 
 ```typescript
@@ -195,9 +205,11 @@ if (result.value.isLoading()) {
 // 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 on load-more buttons.
+`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: `docs/packages/api-utils/pages/usage/query.md` Return Values section
+Source: `src/composables/query/query.composable.ts` — `UseQueryReturnType`
 
 ## See Also