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

package/skills/getting-started/SKILL.md

@@ -1,19 +1,14 @@
 ---
 name: getting-started
 description: >
-  Install @wisemen/vue-core-api-utils, initialize apiUtilsPlugin with QueryClient config, define typed query keys interface, create API composables with error codes.
+  Install @wisemen/vue-core-api-utils, initialize apiUtilsPlugin with QueryClient config, register typed query keys via module augmentation, set up a typed QueryClient wrapper.
 type: lifecycle
 library: vue-core-api-utils
-library_version: "1.0.1"
-sources:
-  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/getting-started/installation.md"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/plugin/apiUtilsPlugin.ts"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/config/config.ts"
 ---
 
 # @wisemen/vue-core-api-utils — Getting Started
 
-Get `@wisemen/vue-core-api-utils` installed, your Vue Query plugin initialized, query keys defined, and typed composables created.
+Get `@wisemen/vue-core-api-utils` installed, your Vue Query plugin initialized, query keys registered, and a typed QueryClient created.
 
 ## Setup
 
@@ -23,35 +18,37 @@ Get `@wisemen/vue-core-api-utils` installed, your Vue Query plugin initialized,
 pnpm install @wisemen/vue-core-api-utils @tanstack/vue-query neverthrow vue
 ```
 
-### 2. Define your query keys
+### 2. Register your query keys via module augmentation
 
-Create a TypeScript interface that maps query keys to their response types and parameters:
+Augment the `Register` interface to define your query keys and error codes:
 
 ```typescript
 // src/types/queryKey.type.ts
 
-export interface ProjectQueryKeys {
-  // Single entity query
-  contactDetail: {
-    entity: Contact
-    params: { contactUuid: string }
-  }
-  
-  // List query with offset pagination
-  contactList: {
-    entity: Contact[]
-    params: { page: number; limit: number; search?: string }
-  }
-  
-  // List query with keyset pagination
-  contactListKeyset: {
-    entity: Contact[]
-    params: { limit: number; key?: string }
+import type { Contact } from '@/models'
+
+declare module '@wisemen/vue-core-api-utils' {
+  interface Register {
+    queryKeys: {
+      contactDetail: {
+        entity: Contact
+        params: { contactUuid: string }
+      }
+      contactList: {
+        entity: Contact[]
+        params: { search?: string }
+      }
+      contactListKeyset: {
+        entity: Contact[]
+        params: { search?: string }
+      }
+    }
+    errorCodes: 'NOT_FOUND' | 'UNAUTHORIZED' | 'VALIDATION_ERROR'
   }
 }
 ```
 
-Every key must have both `entity` (response type) and `params` (required parameters).
+Every key must have `entity` (response type) and `params` (filter/identifier parameters). Do not include pagination fields in params — those are handled by the infinite query composables.
 
 ### 3. Initialize the plugin in your main.ts
 
@@ -76,9 +73,9 @@ app.use(apiUtilsPlugin({
 app.mount('#app')
 ```
 
-The `apiUtilsPlugin` function creates a QueryClient with your config and handles @tanstack/vue-query setup internally.
+The `apiUtilsPlugin` creates a QueryClient with your config and handles @tanstack/vue-query setup internally.
 
-### 4. Create your API composables
+### 4. Create your API module
 
 ```typescript
 // src/api/index.ts
@@ -88,31 +85,36 @@ import type {
   KeysetPaginationResult as ApiUtilsKeysetPaginationResult,
   OffsetPaginationResult as ApiUtilsOffsetPaginationResult,
 } from '@wisemen/vue-core-api-utils'
-import { createApiUtils } from '@wisemen/vue-core-api-utils'
-
-import type { ProjectQueryKeys } from '@/types/queryKey.type'
-
-// Define your error codes
-export type ERROR_KEYS = 'NOT_FOUND' | 'UNAUTHORIZED' | 'NETWORK_ERROR' | 'VALIDATION_ERROR'
-
-// Create factory with your types
-export const {
-  useKeysetInfiniteQuery,
+import {
+  QueryClient,
+  getTanstackQueryClient,
+  useQuery,
   useMutation,
   useOffsetInfiniteQuery,
+  useKeysetInfiniteQuery,
+} from '@wisemen/vue-core-api-utils'
+
+// Re-export composables for convenience
+export {
   useQuery,
-  usePrefetchKeysetInfiniteQuery,
-  usePrefetchOffsetInfiniteQuery,
-  usePrefetchQuery,
-  useQueryClient,
-} = createApiUtils<ProjectQueryKeys, ERROR_KEYS>()
+  useMutation,
+  useOffsetInfiniteQuery,
+  useKeysetInfiniteQuery,
+}
+
+// Create a typed QueryClient helper
+export function useQueryClient() {
+  return new QueryClient(getTanstackQueryClient())
+}
 
 // Export typed result types
-export type ApiResult<T> = ApiUtilsApiResult<T, ERROR_KEYS>
-export type OffsetPaginationResult<T> = ApiUtilsOffsetPaginationResult<T, ERROR_KEYS>
-export type KeysetPaginationResult<T> = ApiUtilsKeysetPaginationResult<T, ERROR_KEYS>
+export type ApiResult<T> = ApiUtilsApiResult<T>
+export type OffsetPaginationResult<T> = ApiUtilsOffsetPaginationResult<T>
+export type KeysetPaginationResult<T> = ApiUtilsKeysetPaginationResult<T>
 ```
 
+Composables are imported directly from the package. The `QueryClient` is a type-safe wrapper around the Tanstack QueryClient — its types are inferred from your `Register` augmentation.
+
 ## Core Patterns
 
 ### Create a detail query composable
@@ -145,17 +147,17 @@ 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 after success
+      contactList: {},
     },
   })
 }
 ```
 
-Every mutation should list which queries to invalidate via `queryKeysToInvalidate`.
+Every mutation should list which queries to invalidate via `queryKeysToInvalidate`. An empty object `{}` invalidates all queries with that key.
 
 ### Use composables in components
 
@@ -174,7 +176,7 @@ const { result, refetch } = useContactDetail(props.contactUuid)
       Name: {{ result.getValue().name }}
     </div>
     <div v-else-if="result.isErr()">
-      Error: {{ result.getError().detail }}
+      Error occurred
     </div>
     <button @click="refetch">Retry</button>
   </div>
@@ -183,66 +185,12 @@ const { result, refetch } = useContactDetail(props.contactUuid)
 
 All queries and mutations return `AsyncResult` with three states: loading, ok, and err.
 
-## Common Mistakes
-
-### CRITICAL: Forget to initialize apiUtilsPlugin with QueryClient config
-
-```typescript
-// ❌ Wrong: plugin not initialized
-const app = createApp(App)
-app.mount('#app')
-// Throws: "[api-utils] QueryClient not available..."
-```
-
-```typescript
-// ✅ Correct: plugin initialized with config
-const app = createApp(App)
-app.use(apiUtilsPlugin({
-  defaultOptions: {
-    queries: { staleTime: 1000 * 60 * 5 },
-  },
-}))
-app.mount('#app')
-```
-
-If you skip the plugin, `createApiUtils()` has no QueryClient and throws immediately.
-
-Source: `src/config/config.ts` — `getQueryClient()` assertion
-
-### HIGH: Define query keys interface without strict entity/params structure
-
-```typescript
-// ❌ Wrong: inconsistent structure
-export interface ProjectQueryKeys {
-  contactDetail: { entity: Contact } // Missing params!
-  contactList: Contact[] // Should wrap in { entity, params }
-}
-```
-
-```typescript
-// ✅ Correct: every key has entity and params
-export interface ProjectQueryKeys {
-  contactDetail: {
-    entity: Contact
-    params: { contactUuid: string }
-  }
-  contactList: {
-    entity: Contact[]
-    params: { page: number; limit: number }
-  }
-}
-```
-
-Query keys without proper structure prevent the factory from typing composables correctly and cause runtime errors during query key resolution.
-
-Source: `docs/packages/api-utils/pages/getting-started/installation.md` Section 3
-
 ## You're all set!
 
 You now have:
 - ✅ Plugin initialized with Vue Query
-- ✅ Query keys defined with types
-- ✅ API composables created
+- ✅ Query keys registered via module augmentation
+- ✅ Typed QueryClient wrapper created
 - ✅ Error codes enumerated
 
-Head to [writing-queries](../writing-queries/SKILL.md) to fetch your first resource, or [handling-asyncresult-types](../asyncresult-handling/SKILL.md) to understand the three-state AsyncResult type.
+Head to [writing-queries](../writing-queries/SKILL.md) to fetch your first resource, or [asyncresult-handling](../asyncresult-handling/SKILL.md) to understand the three-state AsyncResult type.

package/skills/optimistic-uis/SKILL.md

@@ -4,12 +4,6 @@ description: >
   Combining mutations, cache updates, and AsyncResult to create responsive UIs with instant feedback; optimistic updates with error handling, async transitions, immediate user feedback without request latency.
 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:docs/packages/api-utils/pages/usage/query-client.md"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/composables/mutation/mutation.composable.ts"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/utils/query-client/queryClient.ts"
 ---
 
 # @wisemen/vue-core-api-utils — Optimistic UIs
@@ -31,26 +25,24 @@ const { result: contact } = useQuery('contactDetail', {
 })
 
 const { execute, isLoading, result: mutationResult } = useMutation({
-  queryFn: ({ body }) => ContactService.updateContact(contactUuid, body),
+  queryFn: ({ body }: { body: ContactUpdateForm }) =>
+    ContactService.updateContact(contactUuid, body),
   queryKeysToInvalidate: { contactList: {} },
 })
 
-async function handleSubmit(formData) {
-  // Save original (for rollback)
-  const originalContact = contact.value.isOk() ? contact.value.getValue() : null
-  
-  // Optimistic update: immediate cache change
-  queryClient.update(['contactDetail', { contactUuid }], {
+async function handleSubmit(formData: ContactUpdateForm) {
+  // Optimistic update — returns { rollback } for reverting on error
+  const { rollback } = queryClient.update(['contactDetail', { contactUuid }], {
     by: (c) => true,
     value: (c) => ({ ...c, ...formData }),
   })
   
   // Execute mutation
-  const result = await execute(formData)
+  const result = await execute({ body: formData })
   
   // On error, rollback
   if (result.isErr()) {
-    queryClient.set(['contactDetail', { contactUuid }], originalContact)
+    rollback()
   }
 }
 ```
@@ -60,29 +52,32 @@ async function handleSubmit(formData) {
 ### Immediate cache update while request pending
 
 ```typescript
+const queryClient = useQueryClient()
+
 const { result } = useQuery('contactDetail', {
-  params: computed(() => ({ contactUuid })),
+  params: { contactUuid: computed(() => contactUuid) },
   queryFn: () => ContactService.getDetail(contactUuid),
 })
 
 const { execute, isLoading } = useMutation({
-  queryFn: (data) => ContactService.updateContact(contactUuid, data),
-  queryKeysToInvalidate: { /* ... */ },
+  queryFn: ({ body }: { body: ContactUpdateForm }) =>
+    ContactService.updateContact(contactUuid, body),
+  queryKeysToInvalidate: { contactList: {} },
 })
 
-async function handleSave(formData) {
-  // Cache update happens immediately
-  queryClient.update(['contactDetail', { contactUuid }], {
+async function handleSave(formData: ContactUpdateForm) {
+  // Cache update happens immediately, rollback returned for error case
+  const { rollback } = queryClient.update(['contactDetail', { contactUuid }], {
     by: (c) => true,
     value: (c) => ({ ...c, ...formData }),
   })
   
   // Mutation executes in background
-  await execute(formData)
+  const result = await execute({ body: formData })
   
-  // UI shows updated data from cache right away
-  // isLoading is true while request pending
-  // result.value changes when mutation completes
+  if (result.isErr()) {
+    rollback()
+  }
 }
 ```
 
@@ -91,71 +86,61 @@ Users see changes instantly. `isLoading` stays true during request, giving visua
 ### Error handling with AsyncResult
 
 ```typescript
-async function handleSave(formData) {
-  const originalContact = contact.value?.getValue()
-  
-  queryClient.update(['contactDetail', { contactUuid }], {
+async function handleSave(formData: ContactUpdateForm) {
+  const queryClient = useQueryClient()
+
+  const { rollback } = queryClient.update(['contactDetail', { contactUuid }], {
     by: (c) => true,
     value: (c) => ({ ...c, ...formData }),
   })
   
-  const result = await execute(formData)
-  
-  // Match on mutation result
-  result.match({
-    ok: () => {
-      // Server confirmed the update
-      // Cache already reflects the change
-      showSuccessMessage('Contact updated')
-    },
-    err: (error) => {
-      // Revert optimistic update
-      queryClient.set(['contactDetail', { contactUuid }], originalContact)
-      showErrorMessage(`Failed: ${error.message}`)
-    },
-    loading: () => {
-      // Should not happen after await, but handle just in case
-    },
-  })
+  const result = await execute({ body: formData })
+  
+  if (result.isOk()) {
+    showSuccessMessage('Contact updated')
+  } else if (result.isErr()) {
+    rollback()
+    const error = result.getError()
+    if ('errors' in error) {
+      showErrorMessage(`Failed: ${error.errors[0].detail}`)
+    } else {
+      showErrorMessage('An unexpected error occurred')
+    }
+  }
 }
 ```
 
-When mutation fails, revert the optimistic change using the saved original value.
+When mutation fails, call `rollback()` to revert the optimistic cache change. Narrow the error type with `'errors' in error` to distinguish expected API errors from unexpected ones.
 
 ### Composable combining query + mutation + optimistic UI
 
 ```typescript
-export function useContactEditor(contactUuid) {
+export function useContactEditor(contactUuid: string) {
   const queryClient = useQueryClient()
   
   const { result: contact } = useQuery('contactDetail', {
-    params: computed(() => ({ contactUuid })),
+    params: { contactUuid: computed(() => contactUuid) },
     queryFn: () => ContactService.getDetail(contactUuid),
   })
   
   const { execute, isLoading, result: mutationResult } = useMutation({
-    queryFn: (data) => ContactService.updateContact(contactUuid, data),
+    queryFn: ({ body }: { body: ContactUpdateForm }) =>
+      ContactService.updateContact(contactUuid, body),
     queryKeysToInvalidate: {
-      contactList: () => true,
-      'contact-stats': () => true,
+      contactList: {},
     },
   })
   
-  async function saveContact(formData) {
-    const original = contact.value?.getValue()
-    
-    // Optimistic
-    queryClient.update(['contactDetail', { contactUuid }], {
+  async function saveContact(formData: ContactUpdateForm) {
+    const { rollback } = queryClient.update(['contactDetail', { contactUuid }], {
       by: () => true,
       value: (c) => ({ ...c, ...formData }),
     })
     
-    // Execute
-    const result = await execute(formData)
+    const result = await execute({ body: formData })
     
-    // Rollback on error
     if (result.isErr()) {
-      queryClient.set(['contactDetail', { contactUuid }], original)
+      rollback()
     }
     
     return result
@@ -172,228 +157,22 @@ export function useContactEditor(contactUuid) {
 
 Encapsulate the full flow in a composable for reusability across components.
 
-## Common Mistakes
-
-### HIGH: Forget to save original data before optimistic update; can't rollback on error
-
-```typescript
-// ❌ Wrong: no original saved, rollback impossible
-const { execute, result } = useMutation({
-  queryFn: (data) => ContactService.updateContact(data),
-  queryKeysToInvalidate: { contactList: () => true },
-})
-
-async function handleSave(formData) {
-  // Update cache immediately
-  queryClient.update(['contactDetail', { contactUuid }], {
-    by: () => true,
-    value: (c) => ({ ...c, ...formData }),
-  })
-  
-  const result = await execute(formData)
-  
-  if (result.isErr()) {
-    // No way to undo the optimistic change!
-    showErrorMessage('Save failed')
-  }
-}
-```
-
-```typescript
-// ✅ Correct: save original before update
-async function handleSave(formData) {
-  // Save original FIRST
-  const originalContact = contact.value?.getValue()
-  
-  // Update cache
-  queryClient.update(['contactDetail', { contactUuid }], {
-    by: () => true,
-    value: (c) => ({ ...c, ...formData }),
-  })
-  
-  const result = await execute(formData)
-  
-  if (result.isErr()) {
-    // Restore original
-    queryClient.set(['contactDetail', { contactUuid }], originalContact)
-    showErrorMessage('Save failed, changes reverted')
-  }
-}
-```
-
-Always save the current value before modifying the cache. Use it to rollback if the mutation fails.
-
-Source: `docs/packages/api-utils/pages/usage/query-client.md` Real-World Example
-
-### CRITICAL: Handle stale optimistic updates; if component unmounts, optimistic change remains in cache
-
-```typescript
-// ❌ Wrong: optimistic update lives in cache even if user navigates away
-async function handleSave(formData) {
-  const originalContact = contact.value?.getValue()
-  
-  queryClient.update(['contactDetail', { contactUuid }], {
-    by: () => true,
-    value: (c) => ({ ...c, ...formData }),
-  })
-  
-  // User navigates away while mutation pending
-  // Cache still has optimistic data
-  // When user returns, data is stale
-  const result = await execute(formData)
-  if (result.isErr()) {
-    // Rollback happens but user is gone
-    queryClient.set(['contactDetail', { contactUuid }], originalContact)
-  }
-}
-```
-
-```typescript
-// ✅ Correct: clear optimistic flag or track mutation completion
-import { onUnmounted } from 'vue'
-
-let originalContact = null
-let isSaving = false
-
-async function handleSave(formData) {
-  originalContact = contact.value?.getValue()
-  isSaving = true
-  
-  queryClient.update(['contactDetail', { contactUuid }], {
-    by: () => true,
-    value: (c) => ({ ...c, ...formData }),
-  })
-  
-  const result = await execute(formData)
-  isSaving = false
-  
-  if (result.isErr() && originalContact) {
-    queryClient.set(['contactDetail', { contactUuid }], originalContact)
-  }
-}
-
-onUnmounted(() => {
-  // If still saving and user leaves, rollback
-  if (isSaving && originalContact) {
-    queryClient.set(['contactDetail', { contactUuid }], originalContact)
-  }
-})
-```
-
-If user navigates away while a mutation is pending, rollback the optimistic change using component lifecycle hooks. Otherwise, stale data persists in the cache.
-
-Source: Architectural consideration from cache invalidation patterns
-
-### HIGH: Miss querying the correct data structure; optimistic update patches wrong field
-
-```typescript
-// ❌ Wrong: update assuming flat entity, but query returns paginated structure
-const { result: paginatedContacts } = useQuery('contactList', {
-  params: computed(() => ({ limit: 20, offset: 0 })),
-  queryFn: () => ContactService.list({ limit: 20, offset: 0 }),
-})
-
-queryClient.update('contactList', {
-  by: (contact) => contact.id === '123',
-  value: (contact) => ({ ...contact, name: 'Updated' }),
-})
-// This fails because contactList is not Contact[] but { data: Contact[], meta: {...} }
-```
-
-```typescript
-// ✅ Correct: QueryClient handles nested structures automatically
-const { result: paginatedContacts } = useQuery('contactList', {
-  params: computed(() => ({ limit: 20, offset: 0 })),
-  queryFn: () => ContactService.list({ limit: 20, offset: 0 }),
-})
-
-// QueryClient infers the data structure from query keys
-// If contactList query returns { data: Contact[], meta: {...} }
-// QueryClient knows to iterate contact.data and apply the predicate
-queryClient.update('contactList', {
-  by: (contact) => contact.id === '123',
-  value: (contact) => ({ ...contact, name: 'Updated' }),
-})
-```
-
-QueryClient automatically extracts the entity from nested query results (`{ data: [...], meta: {...} }`). You work with the flattened entity, QueryClient handles the nesting. This is why checking your query key definition matters.
-
-Source: `packages/web/api-utils/src/utils/query-client/queryClient.ts`
-
-### MEDIUM: Race condition: multiple mutations affect the same query, order matters
-
-```typescript
-// ❌ Wrong: two mutations in flight affecting the same cache
-async function handleMultipleSaves() {
-  // Mutation 1: add tag
-  queryClient.update(['contactDetail', { contactUuid }], {
-    by: () => true,
-    value: (c) => ({ ...c, tags: [...c.tags, 'new-tag'] }),
-  })
-  const result1 = await execute({ tags: [...contact.value.tags, 'new-tag'] })
-  
-  // Mutation 2: change name
-  // But Mutation 1 is still in flight!
-  queryClient.update(['contactDetail', { contactUuid }], {
-    by: () => true,
-    value: (c) => ({ ...c, name: 'Updated' }),
-  })
-  const result2 = await execute({ name: 'Updated' })
-  
-  // If Mutation 2 completes before Mutation 1, the tags are lost
-}
-```
-
-```typescript
-// ✅ Correct: serialize mutations or track multiple originals
-async function handleMultipleSaves() {
-  const original = contact.value?.getValue()
-  
-  // Either: await each mutation before starting the next
-  queryClient.update(['contactDetail', { contactUuid }], {
-    by: () => true,
-    value: (c) => ({ ...c, tags: [...c.tags, 'new-tag'] }),
-  })
-  const result1 = await execute({ tags: [...contact.value.tags, 'new-tag'] })
-  if (result1.isErr()) {
-    queryClient.set(['contactDetail', { contactUuid }], original)
-    return
-  }
-  
-  // Now safe to do second mutation
-  const updatedOriginal = queryClient.get(['contactDetail', { contactUuid }])
-  queryClient.update(['contactDetail', { contactUuid }], {
-    by: () => true,
-    value: (c) => ({ ...c, name: 'Updated' }),
-  })
-  const result2 = await execute({ name: 'Updated' })
-  if (result2.isErr()) {
-    queryClient.set(['contactDetail', { contactUuid }], updatedOriginal)
-  }
-}
-```
-
-Mutations should be serialized (one at a time) or you need to track the state after each optimistic update. Concurrent mutations on the same cache lead to lost updates.
-
-Source: Architectural consideration from query lifecycle patterns
-
 ## Rollback Strategy
 
-Rollback is enabled by saving the original data before the optimistic update:
+`queryClient.update()` returns a `{ rollback }` function that reverts the cache to its previous state:
 
 ```typescript
-const original = contact.value?.getValue()
-queryClient.update(['contactDetail', { contactUuid }], {
+const { rollback } = queryClient.update(['contactDetail', { contactUuid }], {
   by: () => true,
   value: (c) => ({ ...c, ...formData }),
 })
-const result = await execute(formData)
+const result = await execute({ body: formData })
 if (result.isErr()) {
-  queryClient.set(['contactDetail', { contactUuid }], original)
+  rollback()
 }
 ```
 
-However, rollback patterns for complex scenarios (partial field updates, nested objects) are being refined in the library. For now, save and restore the entire entity.
+Always use the built-in `rollback()` rather than manually saving and restoring the original data — it handles all edge cases including list updates and concurrent modifications.
 
 ## See Also