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

package/skills/asyncresult-handling/SKILL.md

@@ -4,11 +4,6 @@ description: >
   Three-state AsyncResult type (Loading, Ok, Err), isLoading/isOk/isErr type predicates, getValue/getError accessors, match() pattern matching, map/mapErr transformations, safe value extraction without undefined.
 type: core
 library: vue-core-api-utils
-library_version: "0.0.3"
-sources:
-  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/concepts/result-types.md"
-  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/usage/overview.md"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/async-result/asyncResult.ts"
 ---
 
 # @wisemen/vue-core-api-utils — Handling AsyncResult Types
@@ -101,80 +96,6 @@ const name = result.value
 // Type: string
 ```
 
-## Common Mistakes
-
-### CRITICAL: Forget to check state before calling getValue/getError
-
-```typescript
-// ❌ Wrong: getValue without isOk check
-const { result } = useQuery('contactDetail', { /* ... */ })
-const contact = result.value.getValue()
-console.log(contact.name) // contact could be null!
-```
-
-```typescript
-// ✅ Correct: check isOk first
-const { result } = useQuery('contactDetail', { /* ... */ })
-if (result.value.isOk()) {
-  const contact = result.value.getValue()
-  console.log(contact.name) // Safe!
-}
-```
-
-Calling `getValue()` without `isOk()` returns null if the result is loading or an error. You get no compile error, and the UI renders nothing or crashes at runtime.
-
-Source: `docs/packages/api-utils/pages/concepts/result-types.md`
-
-### HIGH: Not handle all three states in match()
-
-```typescript
-// ❌ Wrong: missing loading handler
-result.value.match({
-  ok: (data) => <div>{data.name}</div>,
-  err: (error) => <div>Error: {error.detail}</div>,
-  // Forgot loading!
-})
-```
-
-```typescript
-// ✅ Correct: handle all three states
-result.value.match({
-  loading: () => <div>Loading...</div>,
-  ok: (data) => <div>{data.name}</div>,
-  err: (error) => <div>Error: {error.detail}</div>,
-})
-```
-
-If you omit a handler, TypeScript errors and the UI renders nothing during the omitted state. The match is exhaustive by design.
-
-Source: `docs/packages/api-utils/pages/concepts/result-types.md` Pattern Matching Section
-
-### HIGH: Use state flags (isLoading, isError, isSuccess) instead of AsyncResult state
-
-```typescript
-// ❌ Wrong: mixing old flags with AsyncResult
-const { result, isLoading } = useQuery(...)
-if (isLoading.value) {
-  // Show spinner
-} else {
-  const data = result.value.getValue() // Could be null!
-}
-```
-
-```typescript
-// ✅ Correct: use AsyncResult state exclusively
-const { result } = useQuery(...)
-if (result.value.isLoading()) {
-  // Show spinner
-} else if (result.value.isOk()) {
-  const data = result.value.getValue() // Safe!
-}
-```
-
-Composables export both AsyncResult (exhaustive) and backward-compatible flags (`isLoading`, `isError`, `isSuccess`). Mixing them causes logic bugs where flags say the query is done but the result is still loading.
-
-Source: Maintainer interview — library provides both patterns for backward compatibility, but agents should prefer AsyncResult
-
 ## Next Steps
 
 - [Writing Queries](../writing-queries/SKILL.md) — Fetch single resources with caching

package/skills/cache-management/SKILL.md

@@ -4,16 +4,11 @@ description: >
   Type-safe QueryClient with get/set/update/invalidate methods, predicate-based updates, cascade invalidation strategy, shared cache across components, lazy refetch patterns.
 type: core
 library: vue-core-api-utils
-library_version: "0.0.3"
-sources:
-  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/usage/query-client.md"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/utils/query-client/queryClient.ts"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/factory/createApiQueryClientUtils.ts"
 ---
 
 # @wisemen/vue-core-api-utils — Cache Management
 
-Manually read, write, update, and invalidate the query cache using the type-safe `useQueryClient()` composable. This is useful for optimistic updates and strategically invalidating affected queries.
+Manually read, write, update, and invalidate the query cache using the type-safe `QueryClient` wrapper. This is useful for optimistic updates and strategically invalidating affected queries.
 
 ## Setup
 
@@ -31,16 +26,18 @@ queryClient.set(
   updatedContact
 )
 
-// Update cached data with a predicate
-queryClient.update('contactList', {
+// Update cached data with a predicate (returns { rollback } for reverting)
+const { rollback } = queryClient.update('contactList', {
   by: (contact) => contact.id === '123',
   value: (contact) => ({ ...contact, name: 'Updated' }),
 })
 
-// Invalidate queries (trigger refetch)
-queryClient.invalidate('contactList')
+// Invalidate queries (async — triggers refetch)
+await queryClient.invalidate('contactList')
 ```
 
+`useQueryClient()` is a helper you create in your `@/api` module (see [getting-started](../getting-started/SKILL.md)) that wraps `new QueryClient(getTanstackQueryClient())`.
+
 ## Core Patterns
 
 ### Get cached data
@@ -86,8 +83,8 @@ queryClient.set('contactList', [
 ```typescript
 const queryClient = useQueryClient()
 
-// Update a single item in a list
-queryClient.update('contactList', {
+// Update a single item in a list — returns { rollback } for reverting
+const { rollback } = queryClient.update('contactList', {
   by: (contact) => contact.id === '123',        // Predicate
   value: (contact) => ({                        // Transform
     ...contact,
@@ -96,13 +93,13 @@ queryClient.update('contactList', {
 })
 
 // For single entities, the predicate always matches
-queryClient.update('contactDetail', {
-  by: (contact) => true, // Always update
+const { rollback: rollbackDetail } = queryClient.update('contactDetail', {
+  by: (contact) => true,
   value: (contact) => ({ ...contact, name: 'Updated' }),
 })
 ```
 
-QueryClient knows whether the entity is an array or single item, so predicates work transparently on lists.
+`update()` returns `{ rollback }` — a function that reverts the cache to its previous state. Use this for optimistic updates. QueryClient knows whether the entity is an array or single item, so predicates work transparently on lists.
 
 ### Invalidate and refetch
 
@@ -110,78 +107,16 @@ QueryClient knows whether the entity is an array or single item, so predicates w
 const queryClient = useQueryClient()
 
 // Invalidate all queries with this key
-queryClient.invalidate('contactList')
+await queryClient.invalidate('contactList')
 
 // Invalidate specific query
-queryClient.invalidate(['contactDetail', { contactUuid: '123' }])
+await queryClient.invalidate(['contactDetail', { contactUuid: '123' }])
 
 // After invalidation, the next query interaction triggers a refetch
 ```
 
 Invalidation marks cached data as stale. The next interaction (component mount, user action) triggers a refetch.
 
-## Common Mistakes
-
-### HIGH: Call update/set without checking data structure (array vs entity)
-
-```typescript
-// ❌ Wrong: treating array like entity
-const queryClient = useQueryClient()
-queryClient.update('contactList', {
-  by: (contact) => contact.id === '123',
-  value: (contact) => ({ ...contact, name: 'Updated' }),
-})
-// If contactList is Contact[], predicate matches each item individually
-// If you expect single match, this breaks silently
-```
-
-```typescript
-// ✅ Correct: QueryClient infers type from query key
-const queryClient = useQueryClient()
-// If contactList: { entity: Contact[], ... }
-// QueryClient knows to iterate the array and apply predicate to each item
-queryClient.update('contactList', {
-  by: (contact) => contact.id === '123',
-  value: (contact) => ({ ...contact, name: 'Updated' }),
-})
-// For single entities: { entity: Contact, ... }
-// QueryClient provides the entity directly to predicate
-```
-
-QueryClient infers data structure from your query key definition, so the same `update()` call works correctly for arrays and single entities. The type system ensures you're using the right predicate signature.
-
-Source: `docs/packages/api-utils/pages/usage/query-client.md` Usage
-
-### MEDIUM: Call set() without async loading state; UI flashes stale data
-
-```typescript
-// ❌ Wrong: immediate set without loading indicator
-const queryClient = useQueryClient()
-queryClient.set(['contactDetail', { contactUuid }], updatedData)
-// Cache updated but no indicator that request is pending
-// UI looks responsive but actually has unconfirmed data
-```
-
-```typescript
-// ✅ Correct: pair optimistic update with mutation result handling
-const queryClient = useQueryClient()
-const original = queryClient.get(['contactDetail', { contactUuid }])
-
-// Update cache optimistically
-queryClient.set(['contactDetail', { contactUuid }], newData)
-
-// Execute mutation
-const result = await execute(formData)
-if (result.isErr()) {
-  // Rollback on error
-  queryClient.set(['contactDetail', { contactUuid }], original)
-}
-```
-
-If you update the cache without a mutation in flight, the UI looks responsive but the data is unconfirmed. Always pair cache updates with mutation execution and rollback on error.
-
-Source: `docs/packages/api-utils/pages/usage/query-client.md` Real-World Example
-
 ## Cache Strategy
 
 > Explicitly invalidate only the queries affected by the mutation. Let lazy refetch handle the rest when users navigate to pages needing other data.

package/skills/foundations/SKILL.md

@@ -4,12 +4,6 @@ description: >
   neverthrow Result architectural basis; three-state AsyncResult relationship to Result; @tanstack/vue-query lifecycle (staleTime, gcTime, refetch); composition of TanStack Query + neverthrow + Vue 3 reactivity.
 type: core
 library: vue-core-api-utils
-library_version: "0.0.3"
-sources:
-  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/concepts/result-types.md"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/async-result/asyncResult.ts"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/types/apiError.type.ts"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/config/config.ts"
 ---
 
 # @wisemen/vue-core-api-utils — Foundations
@@ -197,8 +191,8 @@ async function handleRefresh() {
 
 // Automatic refetch on mutation (via queryKeysToInvalidate)
 const { execute } = useMutation({
-  queryFn: (data) => ContactService.update(data),
-  queryKeysToInvalidate: { contactDetail: () => true },
+  queryFn: ({ body }: { body: ContactUpdateForm }) => ContactService.update(body),
+  queryKeysToInvalidate: { contactDetail: {} },
 })
 // After execute succeeds, contactDetail is invalidated
 // Next useQuery('contactDetail') refetches fresh data
@@ -246,8 +240,9 @@ Errors are typed and structured using `neverthrow`:
 interface ApiExpectedError {
   errors: Array<{
     code: string
-    message: string
-    details?: unknown
+    detail: string
+    status: string
+    source?: { pointer: string }
   }>
 }
 
@@ -259,10 +254,11 @@ const result = new AsyncResultErr(apiError)
 result.match({
   ok: (data) => {}, // not executed
   err: (error) => {
-    // error is ApiError
-    if (error instanceof ApiExpectedError) {
+    // error is ApiError — narrow with 'errors' in error
+    if ('errors' in error) {
       // Handle known API errors
       const codes = error.errors.map(e => e.code)
+      const detail = error.errors[0].detail
     } else {
       // Handle network/parsing errors
       console.error(error.message)
@@ -273,154 +269,6 @@ result.match({
 
 Error types are defined at library initialization via the generic `TErrorCode`. This ensures type-safe error handling across queries and mutations.
 
-## Common Mistakes
-
-### CRITICAL: Confuse Result (neverthrow) with AsyncResult; treat ok/err as boolean
-
-```typescript
-// ❌ Wrong: neverthrow Result is not AsyncResult
-const result = new Result(contact, null) // This is not how neverthrow works
-if (result.ok) { // `.ok` doesn't exist
-  console.log(result.value)
-}
-
-// Or even worse: treating AsyncResult like a boolean
-const { result } = useQuery(...)
-if (result.value) {
-  // This is always true; result is always defined (Loading | Ok | Err)
-}
-```
-
-```typescript
-// ✅ Correct: AsyncResult requires exhaustive pattern matching
-const { result } = useQuery('contactDetail', {
-  queryFn: () => ContactService.getDetail(uuid),
-})
-
-result.value.match({
-  loading: () => showSpinner(),
-  ok: (contact) => showContact(contact),
-  err: (error) => showError(error),
-})
-
-// Or use type guards
-if (result.value.isOk()) {
-  console.log(result.value.getValue())
-} else if (result.value.isErr()) {
-  console.log(result.value.getError())
-} else {
-  showSpinner()
-}
-```
-
-AsyncResult requires explicit handling of all three states. The type system won't let you skip a state.
-
-Source: `docs/packages/api-utils/pages/concepts/result-types.md`
-
-### MEDIUM: Misunderstand staleTime; think data refreshes automatically after staleTime
-
-```typescript
-// ❌ Wrong: assuming staleTime auto-refetches
-const { result } = useQuery('contactDetail', {
-  queryFn: () => ContactService.getDetail(uuid),
-  staleTime: 5 * 60 * 1000, // Not an auto-refresh interval
-})
-
-// At T=5m, data doesn't automatically refetch.
-// It's just marked stale. Refetch happens on next interaction
-// (component mount, user action, mutation invalidation)
-```
-
-```typescript
-// ✅ Correct: staleTime is a grace period, not an interval
-const { result, refetch } = useQuery('contactDetail', {
-  queryFn: () => ContactService.getDetail(uuid),
-  staleTime: 5 * 60 * 1000,
-})
-
-// Data is fresh for 5 minutes (instant returns)
-// After 5 minutes, next access triggers refetch
-// For auto-refresh, use refetch() in a watchEffect or timer
-
-watchEffect(async () => {
-  // Refetch every 10 seconds
-  const interval = setInterval(() => refetch(), 10 * 1000)
-  onCleanup(() => clearInterval(interval))
-})
-```
-
-Stale time is not an auto-refresh interval. It's the duration the cache is considered fresh without refetching. Refetch happens on next access or when explicitly triggered.
-
-### HIGH: Misunderstand gcTime and cache eviction; assume cache persists forever
-
-```typescript
-// ❌ Wrong: assuming cache is permanent
-const { result } = useQuery('contactDetail', {
-  queryFn: () => ContactService.getDetail(uuid),
-  gcTime: 5 * 60 * 1000, // Default is 5 minutes
-})
-
-// If component unmounts and user is gone for > 5 minutes,
-// Next access refetches fresh (cache is evicted)
-// This is correct behavior, but if you expected cached data...
-```
-
-```typescript
-// ✅ Correct: increase gcTime if you want longer-lived cache
-const { result } = useQuery('contactDetail', {
-  queryFn: () => ContactService.getDetail(uuid),
-  staleTime: 5 * 60 * 1000,    // Fresh for 5 minutes
-  gcTime: 60 * 60 * 1000,       // Keep in memory for 1 hour
-})
-
-// After 5 minutes (stale) but before 1 hour (gc),
-// Returning cached data (but trigger refetch automatically)
-// After 1 hour, cache is deleted; next access refetches fresh
-```
-
-gcTime controls cache eviction. Longer gcTime = cache lives longer. Longer staleTime = more queries use cache without refetching. Both are configurable defaults in the plugin config.
-
-Source: `packages/web/api-utils/src/config/config.ts`
-
-### MEDIUM: Forget that QueryClient is shared; one query invalidation affects all components
-
-```typescript
-// ❌ Wrong: not realizing cache is global
-const { execute } = useMutation({
-  queryFn: () => ContactService.update(data),
-  queryKeysToInvalidate: { contactDetail: () => true },
-})
-
-// Component A: detail view
-// Component B: list view (also uses contactDetail)
-// Even though A only updated one contact,
-// B's cache is invalidated too (because same query key)
-```
-
-```typescript
-// ✅ Correct: QueryClient is intentionally shared
-export function useContactMutation() {
-  const { execute } = useMutation({
-    queryFn: () => ContactService.update(data),
-    queryKeysToInvalidate: { 
-      // Invalidates all components using this key
-      contactDetail: () => true,
-      // Also invalidate lists that show this contact
-      contactList: () => true,
-    },
-  })
-  
-  return { execute }
-}
-
-// When A updates a contact, both A and B refetch.
-// This is the intended design: shared cache across app.
-```
-
-QueryClient is application-wide (singleton). Invalidating a query invalidates for all components using that key. This is a feature: synchronized cache across the app.
-
-Source: `packages/web/api-utils/src/utils/query-client/queryClient.ts`
-
 ## Integration pattern
 
 The full integration: