@wisemen/vue-core-api-utils 1.0.0 → 1.1.0

package/skills/optimistic-uis/SKILL.md

@@ -0,0 +1,402 @@
+---
+name: optimistic-uis
+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
+
+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
+import { useMutation, useQueryClient, useQuery } from '@/api'
+import { computed } from 'vue'
+
+const queryClient = useQueryClient()
+const { result: contact } = useQuery('contactDetail', {
+  params: {
+    contactUuid: computed(() => contactUuid),
+  },
+  queryFn: () => ContactService.getDetail(contactUuid),
+})
+
+const { execute, isLoading, result: mutationResult } = useMutation({
+  queryFn: ({ body }) => 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 }], {
+    by: (c) => true,
+    value: (c) => ({ ...c, ...formData }),
+  })
+  
+  // Execute mutation
+  const result = await execute(formData)
+  
+  // On error, rollback
+  if (result.isErr()) {
+    queryClient.set(['contactDetail', { contactUuid }], originalContact)
+  }
+}
+```
+
+## Core Patterns
+
+### Immediate cache update while request pending
+
+```typescript
+const { result } = useQuery('contactDetail', {
+  params: computed(() => ({ contactUuid })),
+  queryFn: () => ContactService.getDetail(contactUuid),
+})
+
+const { execute, isLoading } = useMutation({
+  queryFn: (data) => ContactService.updateContact(contactUuid, data),
+  queryKeysToInvalidate: { /* ... */ },
+})
+
+async function handleSave(formData) {
+  // Cache update happens immediately
+  queryClient.update(['contactDetail', { contactUuid }], {
+    by: (c) => true,
+    value: (c) => ({ ...c, ...formData }),
+  })
+  
+  // Mutation executes in background
+  await execute(formData)
+  
+  // UI shows updated data from cache right away
+  // isLoading is true while request pending
+  // result.value changes when mutation completes
+}
+```
+
+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 originalContact = contact.value?.getValue()
+  
+  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
+    },
+  })
+}
+```
+
+When mutation fails, revert the optimistic change using the saved original value.
+
+### Composable combining query + mutation + optimistic UI
+
+```typescript
+export function useContactEditor(contactUuid) {
+  const queryClient = useQueryClient()
+  
+  const { result: contact } = useQuery('contactDetail', {
+    params: computed(() => ({ contactUuid })),
+    queryFn: () => ContactService.getDetail(contactUuid),
+  })
+  
+  const { execute, isLoading, result: mutationResult } = useMutation({
+    queryFn: (data) => ContactService.updateContact(contactUuid, data),
+    queryKeysToInvalidate: {
+      contactList: () => true,
+      'contact-stats': () => true,
+    },
+  })
+  
+  async function saveContact(formData) {
+    const original = contact.value?.getValue()
+    
+    // Optimistic
+    queryClient.update(['contactDetail', { contactUuid }], {
+      by: () => true,
+      value: (c) => ({ ...c, ...formData }),
+    })
+    
+    // Execute
+    const result = await execute(formData)
+    
+    // Rollback on error
+    if (result.isErr()) {
+      queryClient.set(['contactDetail', { contactUuid }], original)
+    }
+    
+    return result
+  }
+  
+  return {
+    contact,
+    saveContact,
+    isLoading,
+    mutationResult,
+  }
+}
+```
+
+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:
+
+```typescript
+const original = contact.value?.getValue()
+queryClient.update(['contactDetail', { contactUuid }], {
+  by: () => true,
+  value: (c) => ({ ...c, ...formData }),
+})
+const result = await execute(formData)
+if (result.isErr()) {
+  queryClient.set(['contactDetail', { contactUuid }], original)
+}
+```
+
+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.
+
+## See Also
+
+- [Writing Mutations](../writing-mutations/SKILL.md) — The `execute()` and result handling that pairs with optimistic updates
+- [Cache Management](../cache-management/SKILL.md) — QueryClient methods for reading and updating cache
+- [Writing Queries](../writing-queries/SKILL.md) — Understanding query results and caching behavior

package/skills/writing-infinitequeries/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: writing-infinitequeries
+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.
+
+**Choose your strategy based on what your backend API provides — not preference.**
+
+## Setup
+
+### Offset Pagination (page-based)
+
+```typescript
+import { ref, computed } from 'vue'
+import { useOffsetInfiniteQuery } from '@/api'
+import { ContactService } from '@/services'
+
+export function useContactList() {
+  const search = ref('')
+
+  return useOffsetInfiniteQuery('contactList', {
+    params: {
+      search: computed(() => search.value),
+    },
+    queryFn: (pagination) => ContactService.getAll({
+      page: pagination.pageParam,
+      limit: pagination.limit,
+      search: search.value,
+    }),
+  })
+}
+```
+
+Pagination parameter `pageParam` starts at 0 and increments. Return results with `{ data: Contact[], meta: { page, limit, total } }`.
+
+### Keyset Pagination (cursor-based)
+
+```typescript
+import { ref, computed } from 'vue'
+import { useKeysetInfiniteQuery } from '@/api'
+import { ContactService } from '@/services'
+
+export function useContactListKeyset() {
+  const search = ref('')
+
+  return useKeysetInfiniteQuery('contactListKeyset', {
+    params: {
+      search: computed(() => search.value),
+    },
+    queryFn: (pagination) => ContactService.getAllKeyset({
+      limit: pagination.limit,
+      cursor: pagination.pageParam,
+      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.
+
+## Core Patterns
+
+### Load and display paginated data
+
+```typescript
+import { computed } from 'vue'
+import { useContactList } from '@/composables'
+
+const { result, isFetching, fetchNextPage, hasNextPage } = useContactList()
+
+const contacts = computed(() => {
+  if (result.value.isOk()) {
+    return result.value.getValue().data
+  }
+  return []
+})
+```
+
+All pages are automatically concatenated into `data`. Access with `result.getValue().data`.
+
+### Load next page
+
+```vue
+<button
+  @click="fetchNextPage"
+  :disabled="isFetchingNextPage || !hasNextPage"
+>
+  {{ isFetchingNextPage ? 'Loading...' : 'Load More' }}
+</button>
+```
+
+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`.
+
+## See Also
+
+- [Writing Queries](../writing-queries/SKILL.md) — Infinite queries are queries; all query concepts apply