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

package/skills/writing-infinitequeries/SKILL.md

@@ -4,19 +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"
-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"
-subsystems:
-  - "Offset Pagination"
-  - "Keyset Pagination"
 ---
 
 # @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.**
 
@@ -36,16 +28,16 @@ export function useContactList() {
     params: {
       search: computed(() => search.value),
     },
-    queryFn: (pagination) => ContactService.getAll({
-      page: pagination.pageParam,
-      limit: pagination.limit,
+    queryFn: ({ offset, limit }) => ContactService.getAll({
+      offset,
+      limit,
       search: search.value,
     }),
   })
 }
 ```
 
-Pagination parameter `pageParam` starts at 0 and increments. Return results with `{ data: Contact[], meta: { page, 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,
-      cursor: pagination.pageParam,
+    queryFn: ({ key, limit }) => ContactService.getAllKeyset({
+      limit,
+      after: 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, limit }` — `key` is the cursor (`undefined` on the first page) and `limit` is the page size.
 
 ## Core Patterns
 
@@ -105,138 +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.
 
-## Common Mistakes
-
-### CRITICAL: Import useInfiniteQuery from @tanstack/vue-query instead of factory
-
-```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 factory composable
-import { useOffsetInfiniteQuery } from '@/api'
-
-const { result, fetchNextPage, hasNextPage } = useOffsetInfiniteQuery('contactList', {
-  params: { search: computed(() => '...') },
-  queryFn: (pagination) => ContactService.getAll({
-    page: pagination.pageParam,
-    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
-
-### CRITICAL: Return paginated data without wrapping in data/meta structure
-
-```typescript
-// ❌ Wrong: returning array directly
-queryFn: (pagination) => ContactService.getAll({
-  page: pagination.pageParam,
-  limit: pagination.limit,
-})
-// Returns Contact[] directly instead of { data: Contact[], meta: {...} }
-// QueryClient doesn't know how to append pages; pages overwrite instead of concat
-```
-
-```typescript
-// ✅ Correct: return { data, meta } structure
-queryFn: (pagination) => ContactService.getAll({
-  page: pagination.pageParam,
-  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
-```
-
-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).
-
-Source: `docs/packages/api-utils/pages/usage/paginated-query.md` Handling Pagination Results
-
-### HIGH: Mix offset and keyset pagination patterns in same query
-
-```typescript
-// ❌ Wrong: mixing pagination patterns
-const { result } = useOffsetInfiniteQuery('contactList', {
-  queryFn: (pagination) => ContactService.getAllKeyset({
-    cursor: pagination.pageParam, // offset expects page number!
-    limit: pagination.limit,
-  }),
-})
-```
-
-```typescript
-// ✅ Correct: match composable to backend API
-// Use useOffsetInfiniteQuery for page/limit APIs:
-const { result } = useOffsetInfiniteQuery('contactList', {
-  queryFn: (pagination) => ContactService.getAll({
-    page: pagination.pageParam,
-    limit: pagination.limit,
-  }),
-})
-
-// Use useKeysetInfiniteQuery for cursor-based APIs:
-const { result } = useKeysetInfiniteQuery('contactList', {
-  queryFn: (pagination) => ContactService.getAllKeyset({
-    cursor: pagination.pageParam,
-    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.
-
-Source: `docs/packages/api-utils/pages/usage/paginated-query.md` Offset vs Keyset comparison
-
-### 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. Use `isFetchingNextPage` for the load-more button.
-
-Source: `docs/packages/api-utils/pages/usage/paginated-query.md` Return Values
-
 ## 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 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,14 +1,9 @@
 ---
 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, AsyncResult error handling, execute function, request shape with body/params separation.
 type: core
 library: vue-core-api-utils
-library_version: "0.0.3"
-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
@@ -23,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
@@ -52,8 +47,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')
@@ -69,12 +63,14 @@ Always `await execute()` and check the result state before continuing.
 ```typescript
 export function useUpdateContact(contactUuid: string) {
   return useMutation({
-    queryFn: async (options: { body: ContactUpdateForm }) => {
-      return await ContactService.update(contactUuid, options.body)
+    queryFn: async ({ body }: { body: ContactUpdateForm }) => {
+      return await ContactService.update(contactUuid, body)
     },
     queryKeysToInvalidate: {
-      contactDetail: {}, // Invalidate the specific contact
-      contactList: {},   // And the list
+      contactDetail: {
+        contactUuid: (_params, _result) => contactUuid, // Invalidate only this contact's detail query
+      },
+      contactList: {}, // Invalidate all contactList queries
     },
   })
 }
@@ -109,7 +105,7 @@ async function handleSubmit() {
     <button :disabled="result.isLoading()">
       {{ result.isLoading() ? 'Creating...' : 'Create' }}
     </button>
-    <div v-if="result.isErr()">
+    <div v-if="result.isErr() && 'errors' in result.getError()">
       Error: {{ result.getError().errors[0].detail }}
     </div>
   </form>
@@ -118,122 +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 factory
-
-```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 factory composable
-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 the factory's type safety and AsyncResult wrapping.
-
-Source: Library architecture — always use composables from `createApiUtils()` factory
-
-### 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. Update returns success but list still shows old items.
-
-Source: `docs/packages/api-utils/pages/usage/mutation.md` Create Mutation Example
-
-### 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. Always await and check the result before continuing.
-
-Source: `docs/packages/api-utils/pages/usage/mutation.md` Usage in Component
-
-### HIGH: Use body instead of params for query parameters
-
-```typescript
-// ❌ Wrong: filter/search as body
-const { execute } = useMutation({
-  queryFn: async (options) => {
-    return await SearchService.search(options.body) // params should go in URL!
-  },
-})
-```
-
-```typescript
-// ✅ Correct: separate body and params
-const { execute } = useMutation({
-  queryFn: async (options) => {
-    const { body, params } = options
-    return await SearchService.search(params) // URL params
-  },
-})
-```
-
-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.
-
-Source: Source code `mutation.composable.ts` — request shape documentation
-
 ## See Also
 
 - [Cache Management](../cache-management/SKILL.md) — Understanding which queries to invalidate

package/skills/writing-queries/SKILL.md

@@ -1,14 +1,9 @@
 ---
 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"
-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"
 ---
 
 # @wisemen/vue-core-api-utils — Writing Queries
@@ -90,115 +85,6 @@ if (result.value.isOk()) {
 }
 ```
 
-## Common Mistakes
-
-### CRITICAL: Import useQuery from @tanstack/vue-query instead of factory
-
-```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 factory-provided composable
-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 factory, losing AsyncResult wrapping, type-safe query keys, and error code typing.
-
-Source: Library architecture — always use composables from `createApiUtils()` factory
-
-### 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: `docs/packages/api-utils/pages/usage/query.md` Usage in Vue Component section
-
-### HIGH: Not set staleTime; serve stale cache indefinitely
-
-```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.
-
-Source: `docs/packages/api-utils/pages/getting-started/installation.md` Setup section
-
-### 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 on load-more buttons.
-
-Source: `docs/packages/api-utils/pages/usage/query.md` Return Values section
-
 ## See Also
 
 - [Cache Management](../cache-management/SKILL.md) — Understanding caching strategy informs staleTime choices