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

package/dist/index.d.mts

@@ -320,7 +320,6 @@ interface UseKeysetInfiniteQueryReturnType<TData, TErrorCode extends string = st
    */
   result: ComputedRef<AsyncResult<KeysetPaginationResponse<TData>, ApiError<TErrorCode>>>;
 }
-declare function useKeysetInfiniteQuery<TData, TErrorCode extends string = string>(options: KeysetInfiniteQueryOptions<TData, TErrorCode>): UseKeysetInfiniteQueryReturnType<TData, TErrorCode>;
 //#endregion
 //#region src/composables/query/offsetInfiniteQuery.composable.d.ts
 interface OffsetInfiniteQueryOptions<TData, TErrorCode extends string = string> {
@@ -398,7 +397,6 @@ interface UseOffsetInfiniteQueryReturnType<TData, TErrorCode extends string = st
    */
   result: ComputedRef<AsyncResult<OffsetPaginationResponse<TData>, ApiError<TErrorCode>>>;
 }
-declare function useOffsetInfiniteQuery<TData, TErrorCode extends string = string>(options: OffsetInfiniteQueryOptions<TData, TErrorCode>): UseOffsetInfiniteQueryReturnType<TData, TErrorCode>;
 //#endregion
 //#region src/composables/query/query.composable.d.ts
 interface UseQueryOptions<TResData, TErrorCode extends string = string> {
@@ -627,19 +625,19 @@ interface ApiUseMutationOptions<TQueryKeys extends object, TReqData, TResData, T
    */
   queryKeysToInvalidate?: { [TKey in keyof TQueryKeys]?: QueryKeyInvalidationConfig<TQueryKeys, TKey, TParams, TResData> };
 }
-interface CreateApiMutationUtilsReturnType<TQueryKeys extends object, TErrorCode extends string = string> {
-  useMutation: <TReqData = void, TResData = void, TParams = void>(options: ApiUseMutationOptions<TQueryKeys, TReqData, TResData, TParams, TErrorCode>) => UseMutationReturnType<TReqData, TResData, TParams>;
-}
 //#endregion
 //#region src/factory/createApiInfiniteQueryUtils.d.ts
 interface CreateApiInfiniteQueryUtilsReturnType<TQueryKeys extends object, TErrorCode extends string = string> {
-  useKeysetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseKeysetInfiniteQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => ReturnType<typeof useKeysetInfiniteQuery<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>>;
-  useOffsetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseOffsetInfiniteQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => ReturnType<typeof useOffsetInfiniteQuery<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>>;
+  useKeysetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseKeysetInfiniteQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => UseKeysetInfiniteQueryReturnType<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>;
+  useOffsetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseOffsetInfiniteQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => UseOffsetInfiniteQueryReturnType<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>;
 }
-declare function createApiInfiniteQueryUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiInfiniteQueryUtilsReturnType<TQueryKeys, TErrorCode>;
+type ApiUseKeysetInfiniteQueryReturnType<TQueryKeys extends object, TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>, TErrorCode extends string = string> = UseKeysetInfiniteQueryReturnType<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>;
+type ApiUseOffsetInfiniteQueryReturnType<TQueryKeys extends object, TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>, TErrorCode extends string = string> = UseOffsetInfiniteQueryReturnType<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>;
 //#endregion
 //#region src/factory/createApiMutationUtils.d.ts
-declare function createApiMutationUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiMutationUtilsReturnType<TQueryKeys, TErrorCode>;
+interface CreateApiMutationUtilsReturnType<TQueryKeys extends object, TErrorCode extends string = string> {
+  useMutation: <TReqData = void, TResData = void, TParams = void>(options: ApiUseMutationOptions<TQueryKeys, TReqData, TResData, TParams, TErrorCode>) => UseMutationReturnType<TReqData, TResData, TParams, TErrorCode>;
+}
 //#endregion
 //#region src/factory/createApiPrefetchInfiniteQueryUtils.d.ts
 interface CreateApiPrefetchInfiniteQueryUtilsReturnType<TQueryKeys extends object, TErrorCode extends string = string> {
@@ -650,7 +648,6 @@ interface CreateApiPrefetchInfiniteQueryUtilsReturnType<TQueryKeys extends objec
     execute: () => Promise<void>;
   };
 }
-declare function createApiPrefetchInfiniteQueryUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiPrefetchInfiniteQueryUtilsReturnType<TQueryKeys, TErrorCode>;
 //#endregion
 //#region src/factory/createApiPrefetchQueryUtils.d.ts
 interface CreateApiPrefetchQueryUtilsReturnType<TQueryKeys extends object, TErrorCode extends string = string> {
@@ -658,7 +655,6 @@ interface CreateApiPrefetchQueryUtilsReturnType<TQueryKeys extends object, TErro
     execute: () => Promise<void>;
   };
 }
-declare function createApiPrefetchQueryUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiPrefetchQueryUtilsReturnType<TQueryKeys, TErrorCode>;
 //#endregion
 //#region src/utils/query-client/queryClient.d.ts
 /**
@@ -678,6 +674,16 @@ interface QueryClientUpdateOptions<TEntity> {
    */
   value: (item: EntityItem<TEntity>) => EntityItem<TEntity>;
 }
+/**
+ * Result of an update operation, providing a rollback function
+ */
+interface QueryClientUpdateResult {
+  /**
+   * Reverts the cache entries affected by this update to their state before the update was applied.
+   * Safe to call multiple times (subsequent calls are no-ops).
+   */
+  rollback: () => void;
+}
 /**
  * QueryClient utility class for type-safe query operations
  */
@@ -775,11 +781,14 @@ declare class QueryClient<TQueryKeys extends object> {
    * @example
    * ```typescript
    * // Update a specific user by id
-   * queryClient.update('userDetail', {
+   * const { rollback } = queryClient.update('userDetail', {
    *   by: (user) => user.id === '123',
    *   value: (user) => ({ ...user, name: 'John Doe' })
    * })
    *
+   * // Revert if the mutation fails
+   * rollback()
+   *
    * // Update all electronics products to out of stock
    * queryClient.update('productList', {
    *   by: (product) => product.category === 'electronics',
@@ -787,21 +796,19 @@ declare class QueryClient<TQueryKeys extends object> {
    * })
    * ```
    */
-  update<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>, TEntity extends QueryKeyEntityFromConfig<TQueryKeys, TKey$1> = QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>(key: TKey$1, options: QueryClientUpdateOptions<TEntity>): void;
-  update<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>, TEntity extends QueryKeyEntityFromConfig<TQueryKeys, TKey$1> = QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>(keyTuple: readonly [TKey$1, Partial<QueryKeyRawParamsFromConfig<TQueryKeys, TKey$1>>], options: QueryClientUpdateOptions<TEntity>): void;
+  update<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>, TEntity extends QueryKeyEntityFromConfig<TQueryKeys, TKey$1> = QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>(key: TKey$1, options: QueryClientUpdateOptions<TEntity>): QueryClientUpdateResult;
+  update<TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>, TEntity extends QueryKeyEntityFromConfig<TQueryKeys, TKey$1> = QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>(keyTuple: readonly [TKey$1, Partial<QueryKeyRawParamsFromConfig<TQueryKeys, TKey$1>>], options: QueryClientUpdateOptions<TEntity>): QueryClientUpdateResult;
 }
 //#endregion
 //#region src/factory/createApiQueryClientUtils.d.ts
 interface CreateApiQueryClientUtilsReturnType<TQueryKeys extends object> {
   useQueryClient: () => QueryClient<TQueryKeys>;
 }
-declare function createApiQueryClientUtils<TQueryKeys extends object>(): CreateApiQueryClientUtilsReturnType<TQueryKeys>;
 //#endregion
 //#region src/factory/createApiQueryUtils.d.ts
 interface CreateApiQueryUtilsReturnType<TQueryKeys extends object, TErrorCode extends string = string> {
   useQuery: <TKey$1 extends QueryKeysWithEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => UseQueryReturnType<QueryKeyEntityFromConfig<TQueryKeys, TKey$1>>;
 }
-declare function createApiQueryUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiQueryUtilsReturnType<TQueryKeys, TErrorCode>;
 //#endregion
 //#region src/factory/createApiUtils.d.ts
 /**
@@ -820,7 +827,7 @@ declare function createApiQueryUtils<TQueryKeys extends object, TErrorCode exten
  */
 declare function createApiUtils<TQueryKeys extends object, TErrorCode extends string = string>(): {
   useQueryClient: () => QueryClient<TQueryKeys>;
-  useMutation: <TReqData = void, TResData = void, TParams = void>(options: ApiUseMutationOptions<TQueryKeys, TReqData, TResData, TParams, TErrorCode>) => UseMutationReturnType<TReqData, TResData, TParams, string>;
+  useMutation: <TReqData = void, TResData = void, TParams = void>(options: ApiUseMutationOptions<TQueryKeys, TReqData, TResData, TParams, TErrorCode>) => UseMutationReturnType<TReqData, TResData, TParams, TErrorCode>;
   useKeysetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseKeysetInfiniteQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => UseKeysetInfiniteQueryReturnType<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>;
   useOffsetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseOffsetInfiniteQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => UseOffsetInfiniteQueryReturnType<QueryKeyArrayItemFromConfig<TQueryKeys, TKey$1>, TErrorCode>;
   usePrefetchKeysetInfiniteQuery: <TKey$1 extends QueryKeysWithArrayEntityFromConfig<TQueryKeys>>(key: TKey$1, queryOptions: ApiUseKeysetInfinitePrefetchQueryOptions<TQueryKeys, TKey$1, TErrorCode>) => {
@@ -867,4 +874,4 @@ declare class SortUtil {
   }[];
 }
 //#endregion
-export { ApiError, ApiErrorObject, ApiExpectedError, ApiKnownErrorObject, ApiResult, ApiUnexpectedError, ApiUnknownErrorObject, ApiUseKeysetInfinitePrefetchQueryOptions, ApiUseKeysetInfiniteQueryOptions, ApiUseMutationOptions, ApiUseOffsetInfinitePrefetchQueryOptions, ApiUseOffsetInfiniteQueryOptions, ApiUsePrefetchQueryOptions, ApiUseQueryOptions, AsyncApiResult, AsyncResult, AsyncResultErr, AsyncResultLoading, AsyncResultOk, type CreateApiInfiniteQueryUtilsReturnType, type CreateApiMutationUtilsReturnType, type CreateApiPrefetchInfiniteQueryUtilsReturnType, type CreateApiPrefetchQueryUtilsReturnType, type CreateApiQueryClientUtilsReturnType, type CreateApiQueryUtilsReturnType, type InfiniteQueryOptions, type KeysetInfiniteQueryOptions, KeysetPagination, KeysetPaginationParams, KeysetPaginationResponse, KeysetPaginationResult, type OffsetInfiniteQueryOptions, OffsetPagination, OffsetPaginationParams, OffsetPaginationResponse, OffsetPaginationResult, PaginatedDataDto, QueryClient, QueryClientUpdateOptions, type QueryConfig, QueryKeyArrayItemFromConfig, QueryKeysWithArrayEntityFromConfig, type QueryParams, Sort, SortDirection, SortUtil, type TanstackQueryClient, type UseMutationReturnType, type UseQueryOptions, type UseQueryReturnType, type WithFilterQuery, type WithSearchQuery, type WithSortQuery, type WithStaticFilterQuery, apiUtilsPlugin, createApiInfiniteQueryUtils, createApiMutationUtils, createApiPrefetchInfiniteQueryUtils, createApiPrefetchQueryUtils, createApiQueryClientUtils, createApiQueryUtils, createApiUtils, getQueryClient as getTanstackQueryClient, initializeApiUtils, setQueryConfig };
+export { type ApiUnexpectedError, type ApiUnknownErrorObject, type ApiUseKeysetInfinitePrefetchQueryOptions, type ApiUseKeysetInfiniteQueryOptions, type ApiUseKeysetInfiniteQueryReturnType, type ApiUseMutationOptions, type ApiUseOffsetInfinitePrefetchQueryOptions, type ApiUseOffsetInfiniteQueryOptions, type ApiUseOffsetInfiniteQueryReturnType, type ApiUsePrefetchQueryOptions, type ApiUseQueryOptions, AsyncResult, AsyncResultErr, AsyncResultLoading, AsyncResultOk, type CreateApiInfiniteQueryUtilsReturnType, type CreateApiMutationUtilsReturnType, type CreateApiPrefetchInfiniteQueryUtilsReturnType, type CreateApiPrefetchQueryUtilsReturnType, type CreateApiQueryClientUtilsReturnType, type CreateApiQueryUtilsReturnType, type InfiniteQueryOptions, type KeysetInfiniteQueryOptions, type KeysetPagination, type KeysetPaginationParams, type KeysetPaginationResponse, type OffsetInfiniteQueryOptions, type OffsetPagination, type OffsetPaginationParams, type OffsetPaginationResponse, type PaginatedDataDto, QueryClient, type QueryClientUpdateOptions, type QueryClientUpdateResult, type QueryConfig, type QueryKeyArrayItemFromConfig, type QueryKeysWithArrayEntityFromConfig, type QueryParams, type Sort, SortDirection, SortUtil, type TanstackQueryClient, type UseKeysetInfiniteQueryReturnType, type UseMutationReturnType, type UseOffsetInfiniteQueryReturnType, type UseQueryOptions, type UseQueryReturnType, type WithFilterQuery, type WithSearchQuery, type WithSortQuery, type WithStaticFilterQuery, apiUtilsPlugin, createApiUtils, getQueryClient as getTanstackQueryClient, initializeApiUtils, setQueryConfig, type ApiError as "~ApiError", type ApiErrorObject as "~ApiErrorObject", type ApiExpectedError as "~ApiExpectedError", type ApiKnownErrorObject as "~ApiKnownErrorObject", type ApiResult as "~ApiResult", type AsyncApiResult as "~AsyncApiResult", type KeysetPaginationResult as "~KeysetPaginationResult", type OffsetPaginationResult as "~OffsetPaginationResult" };

package/dist/index.mjs

@@ -600,9 +600,11 @@ var QueryClient = class {
 			});
 			return !isSpecific;
 		} });
+		const snapshots = /* @__PURE__ */ new Map();
 		for (const query of queries) {
 			const currentData = query.state.data;
 			if (this.isInfiniteDataLike(currentData)) {
+				snapshots.set(query.queryKey, currentData);
 				const updatedInfiniteData = {
 					...currentData,
 					pages: currentData.pages.map((page) => {
@@ -616,10 +618,17 @@ var QueryClient = class {
 			if (!isAsyncResult(currentData)) continue;
 			const rawEntity = this.extractEntityFromAsyncResult(currentData);
 			if (rawEntity === null) continue;
+			snapshots.set(query.queryKey, currentData);
 			const updatedEntity = this.updateEntity(by, rawEntity, value);
 			const wrappedData = this.wrapEntityInAsyncResult(updatedEntity);
 			this.queryClient.setQueryData(query.queryKey, wrappedData);
 		}
+		let rolledBack = false;
+		return { rollback: () => {
+			if (rolledBack) return;
+			rolledBack = true;
+			for (const [queryKey, data] of snapshots) this.queryClient.setQueryData(queryKey, data);
+		} };
 	}
 };
 
@@ -761,4 +770,4 @@ var SortUtil = class {
 };
 
 //#endregion
-export { ApiError, ApiErrorObject, ApiExpectedError, ApiKnownErrorObject, ApiResult, ApiUnexpectedError, ApiUnknownErrorObject, AsyncApiResult, AsyncResult, AsyncResultErr, AsyncResultLoading, AsyncResultOk, KeysetPagination, KeysetPaginationParams, KeysetPaginationResponse, KeysetPaginationResult, OffsetPagination, OffsetPaginationParams, OffsetPaginationResponse, OffsetPaginationResult, PaginatedDataDto, QueryClient, QueryClientUpdateOptions, Sort, SortDirection, SortUtil, apiUtilsPlugin, createApiInfiniteQueryUtils, createApiMutationUtils, createApiPrefetchInfiniteQueryUtils, createApiPrefetchQueryUtils, createApiQueryClientUtils, createApiQueryUtils, createApiUtils, getQueryClient as getTanstackQueryClient, initializeApiUtils, setQueryConfig };
+export { AsyncResult, AsyncResultErr, AsyncResultLoading, AsyncResultOk, QueryClient, SortDirection, SortUtil, apiUtilsPlugin, createApiUtils, getQueryClient as getTanstackQueryClient, initializeApiUtils, setQueryConfig };

package/package.json

@@ -4,8 +4,8 @@
     "access": "public"
   },
   "type": "module",
-  "version": "1.0.1",
-  "license": "MIT",
+  "version": "1.2.0",
+  "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",
     "url": "https://github.com/wisemen-digital/wisemen-core",
@@ -22,8 +22,15 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "typings": "./dist/index.d.mts",
+  "keywords": [
+    "tanstack-intent",
+    "vue-query",
+    "result",
+    "error-handling"
+  ],
   "files": [
-    "./dist"
+    "dist",
+    "skills"
   ],
   "peerDependencies": {
     "@tanstack/vue-query": ">=5.90.5",
@@ -31,10 +38,12 @@
     "vue": ">=3.5.22"
   },
   "devDependencies": {
+    "@tanstack/intent": "^0.0.29",
     "@types/node": "24.8.1",
     "eslint": "9.39.4",
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
+    "vue": "3.5.27",
     "vitest": "4.1.0",
     "@wisemen/eslint-config-vue": "2.1.2"
   },

package/skills/asyncresult-handling/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: asyncresult-handling
+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
+
+All queries and mutations return `AsyncResult<T, E>` — a type-safe alternative to separate `data`, `error`, and `isLoading` states. AsyncResult is always in one of three states: Loading, Ok, or Err.
+
+## Setup
+
+```typescript
+import { useQuery } from '@/api'
+
+const { result } = useQuery('contactDetail', {
+  params: { contactUuid: computed(() => '123') },
+  queryFn: () => ContactService.getByUuid('123'),
+})
+
+// result is a ComputedRef<AsyncResult<Contact, ApiError>>
+// It's always in one of three states:
+// - AsyncResult.Loading()
+// - AsyncResult.Ok(contact: Contact)
+// - AsyncResult.Err(error: ApiError)
+```
+
+## Core Patterns
+
+### Check state and extract values safely
+
+```typescript
+const { result } = useQuery('contactDetail', { /* ... */ })
+
+if (result.value.isLoading()) {
+  console.log('Request in flight...')
+} else if (result.value.isOk()) {
+  const contact = result.value.getValue()
+  console.log('Name:', contact.name) // TypeScript knows contact is Contact
+} else if (result.value.isErr()) {
+  const error = result.value.getError()
+  console.log('Error:', error.detail)
+}
+```
+
+The type predicates `isLoading()`, `isOk()`, and `isErr()` narrow the type so `getValue()` and `getError()` are safe.
+
+### Pattern match all three states
+
+```typescript
+const { result } = useQuery('contactDetail', { /* ... */ })
+
+result.value.match({
+  loading: () => <div>Loading...</div>,
+  ok: (contact) => <div>Name: {contact.name}</div>,
+  err: (error) => <div>Error: {error.detail}</div>,
+})
+```
+
+`match()` is exhaustive — you must handle all three cases or TypeScript errors.
+
+### Transform results with map and mapErr
+
+```typescript
+const { result } = useQuery('contactDetail', { /* ... */ })
+
+// Transform the success value
+const contactName = result.value.map(contact => contact.name)
+
+// Transform the error
+const errorMessage = result.value.mapErr(error => error.detail)
+
+// Chain transformations
+const displayText = result.value
+  .map(contact => `Hello, ${contact.name}`)
+  .mapErr(error => `Failed: ${error.detail}`)
+  .unwrapOr('No data')
+```
+
+`map()` and `mapErr()` return new AsyncResult values, letting you transform without unwrapping.
+
+### Use unwrapOr for fallback values
+
+```typescript
+const { result } = useQuery('contactDetail', { /* ... */ })
+
+// Get the value if Ok, otherwise use fallback
+const contact = result.value.unwrapOr(null)
+// Type: Contact | null
+
+const name = result.value
+  .map(c => c.name)
+  .unwrapOr('Unknown')
+// 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
+- [Handling Mutations](../writing-mutations/SKILL.md) — Create/update/delete with result handling

package/skills/cache-management/SKILL.md

@@ -0,0 +1,222 @@
+---
+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: 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.
+
+## Setup
+
+```typescript
+import { useQueryClient } from '@/api'
+
+const queryClient = useQueryClient()
+
+// Get cached data
+const contact = queryClient.get(['contactDetail', { contactUuid: '123' }])
+
+// Set cached data
+queryClient.set(
+  ['contactDetail', { contactUuid: '123' }],
+  updatedContact
+)
+
+// Update cached data with a predicate
+queryClient.update('contactList', {
+  by: (contact) => contact.id === '123',
+  value: (contact) => ({ ...contact, name: 'Updated' }),
+})
+
+// Invalidate queries (trigger refetch)
+queryClient.invalidate('contactList')
+```
+
+## Core Patterns
+
+### Get cached data
+
+```typescript
+const queryClient = useQueryClient()
+
+// Get specific query
+const contact = queryClient.get(
+  ['contactDetail', { contactUuid: '123' }]
+)
+
+// Get all queries with a key
+const allContacts = queryClient.get('contactList')
+
+// Get exact query only
+const specificQuery = queryClient.get('contactList', { isExact: true })
+```
+
+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()
+
+queryClient.set(
+  ['contactDetail', { contactUuid: '123' }],
+  { id: '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 query key.
+
+### Update cached data with predicates
+
+```typescript
+const queryClient = useQueryClient()
+
+// Update a single item in a list
+queryClient.update('contactList', {
+  by: (contact) => contact.id === '123',        // Predicate
+  value: (contact) => ({                        // Transform
+    ...contact,
+    name: 'Updated John'
+  }),
+})
+
+// For single entities, the predicate always matches
+queryClient.update('contactDetail', {
+  by: (contact) => true, // Always update
+  value: (contact) => ({ ...contact, name: 'Updated' }),
+})
+```
+
+QueryClient knows whether the entity is an array or single item, so predicates work transparently on lists.
+
+### Invalidate and refetch
+
+```typescript
+const queryClient = useQueryClient()
+
+// Invalidate all queries with this key
+queryClient.invalidate('contactList')
+
+// Invalidate specific query
+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.
+>
+> — 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)
+- 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.
+
+```typescript
+// ComponentA
+const { result: resultA } = useQuery('userDetail', {
+  params: { id: computed(() => 'same-id') },
+  queryFn: () => UserService.getById('same-id'),
+})
+
+// ComponentB
+const { result: resultB } = useQuery('userDetail', {
+  params: { id: computed(() => 'same-id') },
+  queryFn: () => UserService.getById('same-id'),
+})
+
+// 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.
+
+## See Also
+
+- [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