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

package/package.json

@@ -4,7 +4,7 @@
     "access": "public"
   },
   "type": "module",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",
@@ -35,6 +35,7 @@
   "peerDependencies": {
     "@tanstack/vue-query": ">=5.90.5",
     "neverthrow": ">=8.2.0",
+    "zod": ">=4.3.5",
     "vue": ">=3.5.22"
   },
   "devDependencies": {

package/skills/asyncresult-handling/SKILL.md

@@ -4,9 +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: "1.2.0"
-sources:
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/async-result/asyncResult.ts"
 ---
 
 # @wisemen/vue-core-api-utils — Handling AsyncResult Types
@@ -99,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 deprecated state flags (isLoading, isError, isSuccess) instead of AsyncResult state
-
-```typescript
-// ❌ Wrong: using deprecated flags
-const { result, isLoading } = useQuery(...)
-if (isLoading.value) {
-  // Show spinner
-} else {
-  const data = result.value.getValue() // Could be null if isErr!
-}
-```
-
-```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!
-}
-```
-
-`isLoading`, `isError`, and `isSuccess` on `UseQueryReturnType` are deprecated — they exist for backward compatibility but are less type-safe than AsyncResult. Always prefer `result.value.isLoading()`, `result.value.isErr()`, and `result.value.isOk()`.
-
-Source: `src/composables/query/query.composable.ts` — `UseQueryReturnType` deprecated annotations
-
 ## Next Steps
 
 - [Writing Queries](../writing-queries/SKILL.md) — Fetch single resources with caching

package/skills/cache-management/SKILL.md

@@ -1,43 +1,24 @@
 ---
 name: cache-management
 description: >
-  Type-safe QueryClient class with get/set/update/invalidate methods, rollback support from update(), predicate-based updates, cascade invalidation strategy, shared cache across components.
+  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: "1.2.0"
-sources:
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/utils/query-client/queryClient.ts"
-  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/config/config.ts"
 ---
 
 # @wisemen/vue-core-api-utils — Cache Management
 
-Manually read, write, update, and invalidate the query cache using the type-safe `QueryClient` class. 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
 
-The library exports a `QueryClient` class that wraps the underlying TanStack QueryClient with type-safe methods. Create a helper function in your project to get a typed instance:
-
-```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())
-}
-```
-
-Then use it anywhere in your composables or components:
-
 ```typescript
-import { useQueryClient } from '@/api/queryClient'
+import { useQueryClient } from '@/api'
 
 const queryClient = useQueryClient()
 
 // Get cached data
-const contacts = queryClient.get('contactDetail')
+const contact = queryClient.get(['contactDetail', { contactUuid: '123' }])
 
 // Set cached data
 queryClient.set(
@@ -45,16 +26,18 @@ queryClient.set(
   updatedContact
 )
 
-// Update cached data with a predicate (returns rollback function)
+// 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)
+// 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
@@ -62,34 +45,38 @@ await queryClient.invalidate('contactList')
 ```typescript
 const queryClient = useQueryClient()
 
-// Get all queries with a key (returns array)
-const allContacts = queryClient.get('contactDetail')
+// Get specific query
+const contact = queryClient.get(
+  ['contactDetail', { contactUuid: '123' }]
+)
 
-// Get exact query stored as ['contactDetail']
-const exactContact = queryClient.get('contactDetail', { isExact: true })
+// Get all queries with a key
+const allContacts = queryClient.get('contactList')
 
-// Get specific query with params (returns single item or null)
-const contact = queryClient.get(['contactDetail', { contactUuid: '123' }] as const)
+// Get exact query only
+const specificQuery = queryClient.get('contactList', { isExact: true })
 ```
 
-Returns the cached entity or null if not cached. The QueryClient infers the entity type from your query key definition.
+Returns the cached data or null if not cached. The QueryClient infers entity type from your query key definition.
 
 ### Set cached data
 
 ```typescript
 const queryClient = useQueryClient()
 
-// Set query with key + params
 queryClient.set(
   ['contactDetail', { contactUuid: '123' }],
-  { uuid: '123', name: 'John', email: 'john@email.com' }
+  { id: '123', name: 'John', email: 'john@email.com' }
 )
 
-// Set query with just the key (stores as ['contactDetail'])
-queryClient.set('contactDetail', { uuid: '123', name: 'John', email: 'john@email.com' })
+// For lists, set works with arrays too
+queryClient.set('contactList', [
+  { id: '123', name: 'John' },
+  { id: '456', name: 'Jane' },
+])
 ```
 
-`set()` replaces all cached data for that specific query key.
+`set()` replaces all cached data for that query key.
 
 ### Update cached data with predicates
 
@@ -105,25 +92,14 @@ const { rollback } = queryClient.update('contactList', {
   }),
 })
 
-// If the operation should be reverted (e.g. mutation failed):
-rollback()
-```
-
-`update()` returns a `{ rollback }` function that reverts the cache to its state before the update. Safe to call multiple times (subsequent calls are no-ops).
-
-### Update specific query with params tuple
-
-```typescript
-const queryClient = useQueryClient()
-
-// Update only the specific cached query for this contact
-queryClient.update(['contactDetail', { contactUuid: '123' }] as const, {
-  by: () => true, // Single entity — always matches
+// For single entities, the predicate always matches
+const { rollback: rollbackDetail } = queryClient.update('contactDetail', {
+  by: (contact) => true,
   value: (contact) => ({ ...contact, name: 'Updated' }),
 })
 ```
 
-Using a key+params tuple updates only the specific query, not all queries with that key.
+`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
 
@@ -133,105 +109,28 @@ const queryClient = useQueryClient()
 // Invalidate all queries with this key
 await queryClient.invalidate('contactList')
 
-// Invalidate specific query with params
-await queryClient.invalidate(['contactDetail', { contactUuid: '123' }] as const)
+// Invalidate specific query
+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: Create QueryClient without typed query keys; lose type safety
-
-```typescript
-// ❌ Wrong: untyped QueryClient
-import { QueryClient, getTanstackQueryClient } from '@wisemen/vue-core-api-utils'
-
-const queryClient = new QueryClient(getTanstackQueryClient())
-// All methods fall back to `object` for query keys — no autocomplete, no type checking
-```
-
-```typescript
-// ✅ Correct: typed QueryClient
-import { QueryClient, getTanstackQueryClient } from '@wisemen/vue-core-api-utils'
-import type { ProjectQueryKeys } from '@/types/queryKey.type'
-
-const queryClient = new QueryClient<ProjectQueryKeys>(getTanstackQueryClient())
-// queryClient.get('nonExistentKey') → TypeScript error
-// queryClient.update('contactList', { by: (c) => c.nonExistentField }) → TypeScript error
-```
-
-Always provide your `ProjectQueryKeys` type generic when instantiating QueryClient.
-
-Source: `src/utils/query-client/queryClient.ts` — `QueryClient<TQueryKeys>` class
-
-### HIGH: Discard the rollback return from update(); can't revert optimistic changes
-
-```typescript
-// ❌ Wrong: ignoring rollback
-queryClient.update('contactList', {
-  by: (c) => c.id === '123',
-  value: (c) => ({ ...c, name: 'Updated' }),
-})
-// No way to undo if the mutation fails
-```
-
-```typescript
-// ✅ Correct: capture rollback for error recovery
-const { rollback } = queryClient.update('contactList', {
-  by: (c) => c.id === '123',
-  value: (c) => ({ ...c, name: 'Updated' }),
-})
-
-const result = await execute(formData)
-if (result.isErr()) {
-  rollback() // Reverts the cache to its pre-update state
-}
-```
-
-`update()` returns `{ rollback }` — always capture it when doing optimistic updates so you can revert on error.
-
-Source: `src/utils/query-client/queryClient.ts` — `QueryClientUpdateResult`
-
-### MEDIUM: Call set() without rollback plan; UI flashes stale data on error
-
-```typescript
-// ❌ Wrong: immediate set without error recovery
-queryClient.set(['contactDetail', { contactUuid }], newData)
-// Cache updated but if the mutation fails, data is wrong with no way to revert
-```
-
-```typescript
-// ✅ Correct: prefer update() which has built-in rollback
-const { rollback } = queryClient.update(['contactDetail', { contactUuid }] as const, {
-  by: () => true,
-  value: () => newData,
-})
-
-const result = await execute(formData)
-if (result.isErr()) {
-  rollback()
-}
-```
-
-Prefer `update()` over `set()` for optimistic changes because `update()` automatically captures the previous state for rollback.
-
-Source: `src/utils/query-client/queryClient.ts`
-
 ## 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.
+>
+> — Maintainer guidance
 
 When a mutation succeeds, look at what changed:
 - If you updated a contact, invalidate `contactDetail` and `contactList` (they both show that contact)
-- If you archived a conversation, invalidate `conversationList` (but maybe not `conversationDetail` unless it's the one you archived)
+- If you archived a conversation, invalidate `conversationList` (but maybe not `conversationDetail` unless showing the one you archived)
 - Don't invalidate unrelated queries — let them refetch lazily when needed
 
 ## Shared Cache Across Components
 
-Multiple components using the same query key share the same cached data. This is a feature, not a bug.
+Important: Multiple components using the same query key share the same cached data. This is a feature, not a bug.
 
 ```typescript
 // ComponentA
@@ -246,8 +145,8 @@ const { result: resultB } = useQuery('userDetail', {
   queryFn: () => UserService.getById('same-id'),
 })
 
-// resultA and resultB share the SAME cached value
-// Mutation in B that invalidates userDetail also triggers a refetch in A
+// resultA and resultB are the SAME cached value
+// Mutation in B invalidates A's cache
 ```
 
 Use this to your advantage: invalidate a query and all components using it refetch automatically.
@@ -256,4 +155,3 @@ Use this to your advantage: invalidate a query and all components using it refet
 
 - [Writing Mutations](../writing-mutations/SKILL.md) — Every mutation needs to know which queries to invalidate
 - [Writing Queries](../writing-queries/SKILL.md) — Understanding caching strategy informs cache management choices
-- [Optimistic UIs](../optimistic-uis/SKILL.md) — Full optimistic update pattern using update() and rollback

package/skills/foundations/SKILL.md

@@ -4,11 +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: "1.2.0"
-sources:
-  - "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
@@ -196,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
@@ -245,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 }
   }>
 }
 
@@ -258,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)
@@ -272,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: