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

package/package.json

@@ -4,7 +4,7 @@
     "access": "public"
   },
   "type": "module",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",
@@ -45,7 +45,7 @@
     "typescript": "5.9.3",
     "vue": "3.5.27",
     "vitest": "4.1.0",
-    "@wisemen/eslint-config-vue": "2.1.2"
+    "@wisemen/eslint-config-vue": "2.1.3"
   },
   "scripts": {
     "build": "tsdown",

package/skills/asyncresult-handling/SKILL.md

@@ -4,10 +4,8 @@ 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"
+library_version: "1.2.0"
 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"
 ---
 
@@ -149,15 +147,15 @@ If you omit a handler, TypeScript errors and the UI renders nothing during the o
 
 Source: `docs/packages/api-utils/pages/concepts/result-types.md` Pattern Matching Section
 
-### HIGH: Use state flags (isLoading, isError, isSuccess) instead of AsyncResult state
+### HIGH: Use deprecated state flags (isLoading, isError, isSuccess) instead of AsyncResult state
 
 ```typescript
-// ❌ Wrong: mixing old flags with AsyncResult
+// ❌ Wrong: using deprecated flags
 const { result, isLoading } = useQuery(...)
 if (isLoading.value) {
   // Show spinner
 } else {
-  const data = result.value.getValue() // Could be null!
+  const data = result.value.getValue() // Could be null if isErr!
 }
 ```
 
@@ -171,9 +169,9 @@ if (result.value.isLoading()) {
 }
 ```
 
-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.
+`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: Maintainer interview — library provides both patterns for backward compatibility, but agents should prefer AsyncResult
+Source: `src/composables/query/query.composable.ts` — `UseQueryReturnType` deprecated annotations
 
 ## Next Steps
 

package/skills/cache-management/SKILL.md

@@ -1,29 +1,43 @@
 ---
 name: cache-management
 description: >
-  Type-safe QueryClient with get/set/update/invalidate methods, predicate-based updates, cascade invalidation strategy, shared cache across components, lazy refetch patterns.
+  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: core
 library: vue-core-api-utils
-library_version: "0.0.3"
+library_version: "1.2.0"
 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-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 `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` class. 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'
+import { useQueryClient } from '@/api/queryClient'
 
 const queryClient = useQueryClient()
 
 // Get cached data
-const contact = queryClient.get(['contactDetail', { contactUuid: '123' }])
+const contacts = queryClient.get('contactDetail')
 
 // Set cached data
 queryClient.set(
@@ -31,14 +45,14 @@ queryClient.set(
   updatedContact
 )
 
-// Update cached data with a predicate
-queryClient.update('contactList', {
+// Update cached data with a predicate (returns rollback function)
+const { rollback } = queryClient.update('contactList', {
   by: (contact) => contact.id === '123',
   value: (contact) => ({ ...contact, name: 'Updated' }),
 })
 
 // Invalidate queries (trigger refetch)
-queryClient.invalidate('contactList')
+await queryClient.invalidate('contactList')
 ```
 
 ## Core Patterns
@@ -48,46 +62,42 @@ queryClient.invalidate('contactList')
 ```typescript
 const queryClient = useQueryClient()
 
-// Get specific query
-const contact = queryClient.get(
-  ['contactDetail', { contactUuid: '123' }]
-)
+// Get all queries with a key (returns array)
+const allContacts = queryClient.get('contactDetail')
 
-// Get all queries with a key
-const allContacts = queryClient.get('contactList')
+// Get exact query stored as ['contactDetail']
+const exactContact = queryClient.get('contactDetail', { isExact: true })
 
-// Get exact query only
-const specificQuery = queryClient.get('contactList', { isExact: true })
+// Get specific query with params (returns single item or null)
+const contact = queryClient.get(['contactDetail', { contactUuid: '123' }] as const)
 ```
 
-Returns the cached data or null if not cached. The QueryClient infers entity type from your query key definition.
+Returns the cached entity or null if not cached. The QueryClient infers the entity type from your query key definition.
 
 ### Set cached data
 
 ```typescript
 const queryClient = useQueryClient()
 
+// Set query with key + params
 queryClient.set(
   ['contactDetail', { contactUuid: '123' }],
-  { id: '123', name: 'John', email: 'john@email.com' }
+  { 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 query with just the key (stores as ['contactDetail'])
+queryClient.set('contactDetail', { uuid: '123', name: 'John', email: 'john@email.com' })
 ```
 
-`set()` replaces all cached data for that query key.
+`set()` replaces all cached data for that specific query key.
 
 ### Update cached data with predicates
 
 ```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,
@@ -95,14 +105,25 @@ queryClient.update('contactList', {
   }),
 })
 
-// For single entities, the predicate always matches
-queryClient.update('contactDetail', {
-  by: (contact) => true, // Always update
+// 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
   value: (contact) => ({ ...contact, name: 'Updated' }),
 })
 ```
 
-QueryClient knows whether the entity is an array or single item, so predicates work transparently on lists.
+Using a key+params tuple updates only the specific query, not all queries with that key.
 
 ### Invalidate and refetch
 
@@ -110,10 +131,10 @@ 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' }])
+// Invalidate specific query with params
+await queryClient.invalidate(['contactDetail', { contactUuid: '123' }] as const)
 
 // After invalidation, the next query interaction triggers a refetch
 ```
@@ -122,80 +143,95 @@ Invalidation marks cached data as stale. The next interaction (component mount,
 
 ## Common Mistakes
 
-### HIGH: Call update/set without checking data structure (array vs entity)
+### HIGH: Create QueryClient without typed query keys; lose type safety
 
 ```typescript
-// ❌ Wrong: treating array like entity
-const queryClient = useQueryClient()
+// ❌ 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: (contact) => contact.id === '123',
-  value: (contact) => ({ ...contact, name: 'Updated' }),
+  by: (c) => c.id === '123',
+  value: (c) => ({ ...c, name: 'Updated' }),
 })
-// If contactList is Contact[], predicate matches each item individually
-// If you expect single match, this breaks silently
+// No way to undo if the mutation fails
 ```
 
 ```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' }),
+// ✅ Correct: capture rollback for error recovery
+const { rollback } = queryClient.update('contactList', {
+  by: (c) => c.id === '123',
+  value: (c) => ({ ...c, name: 'Updated' }),
 })
-// For single entities: { entity: Contact, ... }
-// QueryClient provides the entity directly to predicate
+
+const result = await execute(formData)
+if (result.isErr()) {
+  rollback() // Reverts the cache to its pre-update state
+}
 ```
 
-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.
+`update()` returns `{ rollback }` — always capture it when doing optimistic updates so you can revert on error.
 
-Source: `docs/packages/api-utils/pages/usage/query-client.md` Usage
+Source: `src/utils/query-client/queryClient.ts` — `QueryClientUpdateResult`
 
-### MEDIUM: Call set() without async loading state; UI flashes stale data
+### MEDIUM: Call set() without rollback plan; UI flashes stale data on error
 
 ```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
+// ❌ 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: pair optimistic update with mutation result handling
-const queryClient = useQueryClient()
-const original = queryClient.get(['contactDetail', { contactUuid }])
-
-// Update cache optimistically
-queryClient.set(['contactDetail', { contactUuid }], newData)
+// ✅ Correct: prefer update() which has built-in rollback
+const { rollback } = queryClient.update(['contactDetail', { contactUuid }] as const, {
+  by: () => true,
+  value: () => newData,
+})
 
-// Execute mutation
 const result = await execute(formData)
 if (result.isErr()) {
-  // Rollback on error
-  queryClient.set(['contactDetail', { contactUuid }], original)
+  rollback()
 }
 ```
 
-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.
+Prefer `update()` over `set()` for optimistic changes because `update()` automatically captures the previous state for rollback.
 
-Source: `docs/packages/api-utils/pages/usage/query-client.md` Real-World Example
+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 showing the one you archived)
+- If you archived a conversation, invalidate `conversationList` (but maybe not `conversationDetail` unless it's the one you archived)
 - Don't invalidate unrelated queries — let them refetch lazily when needed
 
 ## Shared Cache Across Components
 
-Important: Multiple components using the same query key share the same cached data. This is a feature, not a bug.
+Multiple components using the same query key share the same cached data. This is a feature, not a bug.
 
 ```typescript
 // ComponentA
@@ -210,8 +246,8 @@ const { result: resultB } = useQuery('userDetail', {
   queryFn: () => UserService.getById('same-id'),
 })
 
-// resultA and resultB are the SAME cached value
-// Mutation in B invalidates A's cache
+// resultA and resultB share the SAME cached value
+// Mutation in B that invalidates userDetail also triggers a refetch in A
 ```
 
 Use this to your advantage: invalidate a query and all components using it refetch automatically.
@@ -220,3 +256,4 @@ 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,9 +4,8 @@ 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"
+library_version: "1.2.0"
 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"

package/skills/getting-started/SKILL.md

@@ -1,19 +1,19 @@
 ---
 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, re-export composables.
 type: lifecycle
 library: vue-core-api-utils
-library_version: "1.0.1"
+library_version: "1.2.0"
 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/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 created.
+Get `@wisemen/vue-core-api-utils` installed, your Vue Query plugin initialized, query keys defined, and typed composables available.
 
 ## Setup
 
@@ -40,13 +40,13 @@ export interface ProjectQueryKeys {
   // List query with offset pagination
   contactList: {
     entity: Contact[]
-    params: { page: number; limit: number; search?: string }
+    params: { search?: string }
   }
   
   // List query with keyset pagination
   contactListKeyset: {
     entity: Contact[]
-    params: { limit: number; key?: string }
+    params: { search?: string }
   }
 }
 ```
@@ -78,7 +78,9 @@ app.mount('#app')
 
 The `apiUtilsPlugin` function creates a QueryClient with your config and handles @tanstack/vue-query setup internally.
 
-### 4. Create your API composables
+### 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:
 
 ```typescript
 // src/api/index.ts
@@ -88,15 +90,23 @@ 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 {
+// 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
+export {
   useKeysetInfiniteQuery,
   useMutation,
   useOffsetInfiniteQuery,
@@ -104,8 +114,7 @@ export const {
   usePrefetchKeysetInfiniteQuery,
   usePrefetchOffsetInfiniteQuery,
   usePrefetchQuery,
-  useQueryClient,
-} = createApiUtils<ProjectQueryKeys, ERROR_KEYS>()
+} from '@wisemen/vue-core-api-utils'
 
 // Export typed result types
 export type ApiResult<T> = ApiUtilsApiResult<T, ERROR_KEYS>
@@ -113,6 +122,8 @@ export type OffsetPaginationResult<T> = ApiUtilsOffsetPaginationResult<T, ERROR_
 export type KeysetPaginationResult<T> = ApiUtilsKeysetPaginationResult<T, ERROR_KEYS>
 ```
 
+The `declare module` block tells the library about your project's types. After this, every composable automatically knows your query keys and error codes.
+
 ## Core Patterns
 
 ### Create a detail query composable
@@ -185,7 +196,7 @@ All queries and mutations return `AsyncResult` with three states: loading, ok, a
 
 ## Common Mistakes
 
-### CRITICAL: Forget to initialize apiUtilsPlugin with QueryClient config
+### CRITICAL: Forget to initialize apiUtilsPlugin
 
 ```typescript
 // ❌ Wrong: plugin not initialized
@@ -205,7 +216,7 @@ app.use(apiUtilsPlugin({
 app.mount('#app')
 ```
 
-If you skip the plugin, `createApiUtils()` has no QueryClient and throws immediately.
+Without the plugin, composables have no QueryClient and throw immediately.
 
 Source: `src/config/config.ts` — `getQueryClient()` assertion
 
@@ -228,21 +239,46 @@ export interface ProjectQueryKeys {
   }
   contactList: {
     entity: Contact[]
-    params: { page: number; limit: number }
+    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
 ```
 
-Query keys without proper structure prevent the factory from typing composables correctly and cause runtime errors during query key resolution.
+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: `docs/packages/api-utils/pages/getting-started/installation.md` Section 3
+Source: `src/register.ts`
 
 ## You're all set!
 
 You now have:
 - ✅ Plugin initialized with Vue Query
 - ✅ Query keys defined with types
-- ✅ API composables created
+- ✅ Types registered via module augmentation
+- ✅ Composables re-exported from `@/api`
 - ✅ 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.