@wisemen/vue-core-api-utils 2.0.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, register typed query keys via module augmentation, re-export composables.
+  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.2.0"
-sources:
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/plugin/apiUtilsPlugin.ts"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/register.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 available.
+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: { search?: string }
-  }
-  
-  // List query with keyset pagination
-  contactListKeyset: {
-    entity: Contact[]
-    params: { search?: 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,11 +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. Register your types and re-export composables
-
-Use module augmentation to register your query keys and error codes for library-wide type safety, then re-export composables for convenient importing across your project:
+### 4. Create your API module
 
 ```typescript
 // src/api/index.ts
@@ -90,39 +85,35 @@ import type {
   KeysetPaginationResult as ApiUtilsKeysetPaginationResult,
   OffsetPaginationResult as ApiUtilsOffsetPaginationResult,
 } from '@wisemen/vue-core-api-utils'
+import {
+  QueryClient,
+  getTanstackQueryClient,
+  useQuery,
+  useMutation,
+  useOffsetInfiniteQuery,
+  useKeysetInfiniteQuery,
+} 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'
-
-// Register query keys and error codes via module augmentation
-// This makes all composables fully typed without a factory function
-declare module '@wisemen/vue-core-api-utils' {
-  interface Register {
-    queryKeys: ProjectQueryKeys
-    errorCodes: ERROR_KEYS
-  }
-}
-
-// Re-export composables for convenient importing
+// Re-export composables for convenience
 export {
-  useKeysetInfiniteQuery,
+  useQuery,
   useMutation,
   useOffsetInfiniteQuery,
-  useQuery,
-  usePrefetchKeysetInfiniteQuery,
-  usePrefetchOffsetInfiniteQuery,
-  usePrefetchQuery,
-} from '@wisemen/vue-core-api-utils'
+  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>
 ```
 
-The `declare module` block tells the library about your project's types. After this, every composable automatically knows your query keys and error codes.
+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
 
@@ -156,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
 
@@ -185,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>
@@ -194,91 +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
-
-```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')
-```
-
-Without the plugin, composables have no QueryClient and throw 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: { search?: string }
-  }
-}
-```
-
-Query keys without proper structure cause TypeScript errors and prevent correct query key resolution.
-
-Source: `src/register.ts` — `RegisteredQueryKeyEntity` and `RegisteredQueryKeyParams` type derivation
-
-### HIGH: Skip the module augmentation; composables lose type safety
-
-```typescript
-// ❌ Wrong: no declare module block in @/api/index.ts
-// Composables fall back to `object` for query keys and `string` for error codes
-// TypeScript won't catch wrong query key names or invalid error codes
-```
-
-```typescript
-// ✅ Correct: declare module augments the Register interface
-declare module '@wisemen/vue-core-api-utils' {
-  interface Register {
-    queryKeys: ProjectQueryKeys
-    errorCodes: ERROR_KEYS
-  }
-}
-// Now useQuery('nonExistentKey', ...) is a compile error
-// And error.code is typed as ERROR_KEYS, not just string
-```
-
-Without the `declare module` block the library types fall back to generic `object` and `string`. All query key checks and error code checks become useless at compile time.
-
-Source: `src/register.ts`
-
 ## You're all set!
 
 You now have:
 - ✅ Plugin initialized with Vue Query
-- ✅ Query keys defined with types
-- ✅ Types registered via module augmentation
-- ✅ Composables re-exported from `@/api`
+- ✅ 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 [asyncresult-handling](../asyncresult-handling/SKILL.md) to understand the three-state AsyncResult type.

package/skills/optimistic-uis/SKILL.md

@@ -1,38 +1,22 @@
 ---
 name: optimistic-uis
 description: >
-  Combining mutations, QueryClient.update() with built-in rollback, and AsyncResult to create responsive UIs with instant feedback; optimistic updates with automatic error reversal.
+  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: "1.2.0"
-sources:
-  - "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
 
-Create fast, responsive UIs by updating the cache immediately while mutations execute in the background. Combine `useMutation()`, `QueryClient`, and `AsyncResult` pattern matching to provide instant feedback to users.
+Create fast, responsive UIs by updating the cache immediately while mutations execute in the background. Combine `useMutation()`, `useQueryClient()`, and `AsyncResult` pattern matching to provide instant feedback to users.
 
 ## Setup
 
 ```typescript
-// src/api/queryClient.ts
-import { QueryClient, getTanstackQueryClient } from '@wisemen/vue-core-api-utils'
-import type { ProjectQueryKeys } from '@/types/queryKey.type'
-
-export function useQueryClient() {
-  return new QueryClient<ProjectQueryKeys>(getTanstackQueryClient())
-}
-```
-
-```typescript
-import { useQuery, useMutation } from '@/api'
-import { useQueryClient } from '@/api/queryClient'
+import { useMutation, useQueryClient, useQuery } from '@/api'
 import { computed } from 'vue'
 
 const queryClient = useQueryClient()
-
 const { result: contact } = useQuery('contactDetail', {
   params: {
     contactUuid: computed(() => contactUuid),
@@ -40,22 +24,23 @@ const { result: contact } = useQuery('contactDetail', {
   queryFn: () => ContactService.getDetail(contactUuid),
 })
 
-const { execute, result: mutationResult } = useMutation({
-  queryFn: ({ body }) => ContactService.updateContact(contactUuid, body),
+const { execute, isLoading, result: mutationResult } = useMutation({
+  queryFn: ({ body }: { body: ContactUpdateForm }) =>
+    ContactService.updateContact(contactUuid, body),
   queryKeysToInvalidate: { contactList: {} },
 })
 
-async function handleSubmit(formData) {
-  // Optimistic update — returns rollback function
-  const { rollback } = queryClient.update(['contactDetail', { contactUuid }] as const, {
-    by: () => true,
+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({ body: formData })
   
-  // Revert cache on error
+  // On error, rollback
   if (result.isErr()) {
     rollback()
   }
@@ -69,59 +54,64 @@ async function handleSubmit(formData) {
 ```typescript
 const queryClient = useQueryClient()
 
-const { execute } = useMutation({
-  queryFn: (data) => ContactService.updateContact(contactUuid, data),
+const { result } = useQuery('contactDetail', {
+  params: { contactUuid: computed(() => contactUuid) },
+  queryFn: () => ContactService.getDetail(contactUuid),
+})
+
+const { execute, isLoading } = useMutation({
+  queryFn: ({ body }: { body: ContactUpdateForm }) =>
+    ContactService.updateContact(contactUuid, body),
   queryKeysToInvalidate: { contactList: {} },
 })
 
-async function handleSave(formData) {
-  // Cache update happens immediately — UI shows new data right away
-  const { rollback } = queryClient.update(['contactDetail', { contactUuid }] as const, {
-    by: () => true,
+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
   const result = await execute({ body: formData })
   
-  // On error, revert to the previous state
   if (result.isErr()) {
     rollback()
   }
 }
 ```
 
-Users see changes instantly. No perceived latency. If the server rejects the change, `rollback()` restores the previous cache state automatically.
+Users see changes instantly. `isLoading` stays true during request, giving visual feedback. No perceived latency.
 
 ### Error handling with AsyncResult
 
 ```typescript
-async function handleSave(formData) {
-  const { rollback } = queryClient.update(['contactDetail', { contactUuid }] as const, {
-    by: () => true,
+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({ body: formData })
   
-  result.match({
-    ok: () => {
-      // Server confirmed the update
-      // Cache already reflects the change from the optimistic update
-      showSuccessMessage('Contact updated')
-    },
-    err: (error) => {
-      // Revert optimistic update
-      rollback()
-      showErrorMessage(`Failed: ${'errors' in error ? error.errors[0].detail : error.message}`)
-    },
-    loading: () => {
-      // Won't happen after await, but required by match()
-    },
-  })
+  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, 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
@@ -129,28 +119,26 @@ 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, result: mutationResult } = useMutation({
-    queryFn: ({ body }) => ContactService.updateContact(contactUuid, body),
+  const { execute, isLoading, result: mutationResult } = useMutation({
+    queryFn: ({ body }: { body: ContactUpdateForm }) =>
+      ContactService.updateContact(contactUuid, body),
     queryKeysToInvalidate: {
       contactList: {},
     },
   })
   
-  async function saveContact(formData) {
-    // Optimistic update
-    const { rollback } = queryClient.update(['contactDetail', { contactUuid }] as const, {
+  async function saveContact(formData: ContactUpdateForm) {
+    const { rollback } = queryClient.update(['contactDetail', { contactUuid }], {
       by: () => true,
       value: (c) => ({ ...c, ...formData }),
     })
     
-    // Execute
     const result = await execute({ body: formData })
     
-    // Rollback on error
     if (result.isErr()) {
       rollback()
     }
@@ -161,6 +149,7 @@ export function useContactEditor(contactUuid: string) {
   return {
     contact,
     saveContact,
+    isLoading,
     mutationResult,
   }
 }
@@ -168,175 +157,22 @@ export function useContactEditor(contactUuid: string) {
 
 Encapsulate the full flow in a composable for reusability across components.
 
-## Common Mistakes
-
-### HIGH: Ignore the rollback return from update(); can't revert on error
-
-```typescript
-// ❌ Wrong: discarding rollback
-async function handleSave(formData) {
-  queryClient.update(['contactDetail', { contactUuid }] as const, {
-    by: () => true,
-    value: (c) => ({ ...c, ...formData }),
-  })
-  // rollback discarded!
-  
-  const result = await execute({ body: formData })
-  
-  if (result.isErr()) {
-    // No way to undo the optimistic change!
-    showErrorMessage('Save failed')
-    // UI now shows wrong data permanently
-  }
-}
-```
-
-```typescript
-// ✅ Correct: capture and use rollback
-async function handleSave(formData) {
-  const { rollback } = queryClient.update(['contactDetail', { contactUuid }] as const, {
-    by: () => true,
-    value: (c) => ({ ...c, ...formData }),
-  })
-  
-  const result = await execute({ body: formData })
-  
-  if (result.isErr()) {
-    rollback() // Restores previous state automatically
-    showErrorMessage('Save failed, changes reverted')
-  }
-}
-```
-
-`update()` captures the previous state internally and exposes it via `rollback()`. Always capture and use it when doing optimistic updates.
-
-Source: `src/utils/query-client/queryClient.ts` — `QueryClientUpdateResult`
-
-### CRITICAL: Stale optimistic update if component unmounts during pending mutation
-
-```typescript
-// ❌ Wrong: mutation pending, user navigates away, rollback never called
-async function handleSave(formData) {
-  const { rollback } = queryClient.update(['contactDetail', { contactUuid }] as const, {
-    by: () => true,
-    value: (c) => ({ ...c, ...formData }),
-  })
-  
-  // User navigates away while mutation is pending
-  // Cache still has optimistic data
-  const result = await execute({ body: formData })
-  if (result.isErr()) {
-    rollback() // User is gone — rollback still works but user won't see it
-  }
-}
-```
-
-```typescript
-// ✅ Correct: rollback on unmount if mutation is still in flight
-import { onUnmounted } from 'vue'
-
-let pendingRollback: (() => void) | null = null
-
-async function handleSave(formData) {
-  const { rollback } = queryClient.update(['contactDetail', { contactUuid }] as const, {
-    by: () => true,
-    value: (c) => ({ ...c, ...formData }),
-  })
-  pendingRollback = rollback
-  
-  const result = await execute({ body: formData })
-  pendingRollback = null
-  
-  if (result.isErr()) {
-    rollback()
-  }
-}
-
-onUnmounted(() => {
-  // If still saving and user leaves, rollback stale optimistic update
-  pendingRollback?.()
-})
-```
-
-If the user navigates away while a mutation is pending, rollback the optimistic change using component lifecycle hooks. Otherwise, stale unconfirmed data persists in the global cache.
-
-Source: Architectural consideration from cache invalidation patterns
+## Rollback Strategy
 
-### HIGH: Optimistic update on list query with wrong predicate; patches wrong item
+`queryClient.update()` returns a `{ rollback }` function that reverts the cache to its previous state:
 
 ```typescript
-// ❌ Wrong: update without proper predicate
-queryClient.update('contactList', {
-  by: () => true, // Matches ALL contacts in the list!
-  value: (c) => ({ ...c, name: 'Updated' }),
+const { rollback } = queryClient.update(['contactDetail', { contactUuid }], {
+  by: () => true,
+  value: (c) => ({ ...c, ...formData }),
 })
-// Every contact in the cached list gets "Updated" as name
-```
-
-```typescript
-// ✅ Correct: use a specific predicate
-queryClient.update('contactList', {
-  by: (contact) => contact.uuid === contactUuid, // Only match the specific item
-  value: (contact) => ({ ...contact, name: formData.name }),
-})
-```
-
-When updating lists, always use a predicate that uniquely identifies the item you're changing. `by: () => true` is only appropriate for single-entity queries.
-
-Source: `src/utils/query-client/queryClient.ts` — `updateEntity` iterates arrays
-
-### MEDIUM: Race condition: multiple mutations affect the same query
-
-```typescript
-// ❌ Wrong: two mutations in flight affecting the same cache
-async function handleMultipleSaves() {
-  // Mutation 1 optimistic update
-  const { rollback: rollback1 } = queryClient.update(['contactDetail', { contactUuid }] as const, {
-    by: () => true,
-    value: (c) => ({ ...c, tags: [...c.tags, 'new-tag'] }),
-  })
-  // Don't await — start Mutation 2 immediately!
-  execute1({ body: { tags: [...contact.tags, 'new-tag'] } })
-  
-  // Mutation 2 on same cache entry
-  const { rollback: rollback2 } = queryClient.update(['contactDetail', { contactUuid }] as const, {
-    by: () => true,
-    value: (c) => ({ ...c, name: 'Updated' }),
-  })
-  await execute2({ body: { name: 'Updated' } })
-  
-  // If Mutation 2 completes before Mutation 1, the tags may be lost
-}
-```
-
-```typescript
-// ✅ Correct: serialize mutations to avoid ordering issues
-async function handleMultipleSaves() {
-  const { rollback: rollback1 } = queryClient.update(['contactDetail', { contactUuid }] as const, {
-    by: () => true,
-    value: (c) => ({ ...c, tags: [...c.tags, 'new-tag'] }),
-  })
-  const result1 = await execute1({ body: { tags: [...contact.tags, 'new-tag'] } })
-  if (result1.isErr()) {
-    rollback1()
-    return
-  }
-  
-  // Only start Mutation 2 after Mutation 1 finishes
-  const { rollback: rollback2 } = queryClient.update(['contactDetail', { contactUuid }] as const, {
-    by: () => true,
-    value: (c) => ({ ...c, name: 'Updated' }),
-  })
-  const result2 = await execute2({ body: { name: 'Updated' } })
-  if (result2.isErr()) {
-    rollback2()
-  }
+const result = await execute({ body: formData })
+if (result.isErr()) {
+  rollback()
 }
 ```
 
-Serialize mutations that affect the same cache entry. Concurrent mutations on the same key can lead to lost updates or incorrect rollbacks.
-
-Source: Architectural consideration from query lifecycle patterns
+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