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

package/LICENSE.md

@@ -0,0 +1,59 @@
+# PolyForm Strict License 1.0.0
+
+<https://polyformproject.org/licenses/strict/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose, other than distributing the software or making changes or new works based on the software.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

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,18 +625,20 @@ 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>;
 }
+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>;
 declare function createApiInfiniteQueryUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiInfiniteQueryUtilsReturnType<TQueryKeys, TErrorCode>;
 //#endregion
 //#region src/factory/createApiMutationUtils.d.ts
+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>;
+}
 declare function createApiMutationUtils<TQueryKeys extends object, TErrorCode extends string = string>(): CreateApiMutationUtilsReturnType<TQueryKeys, TErrorCode>;
 //#endregion
 //#region src/factory/createApiPrefetchInfiniteQueryUtils.d.ts
@@ -678,6 +678,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 +785,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,8 +800,8 @@ 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
@@ -867,4 +880,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 ApiError, type ApiErrorObject, type ApiExpectedError, type ApiKnownErrorObject, type ApiResult, type ApiUnexpectedError, type ApiUnknownErrorObject, type ApiUseKeysetInfinitePrefetchQueryOptions, type ApiUseKeysetInfiniteQueryOptions, type ApiUseKeysetInfiniteQueryReturnType, type ApiUseMutationOptions, type ApiUseOffsetInfinitePrefetchQueryOptions, type ApiUseOffsetInfiniteQueryOptions, type ApiUseOffsetInfiniteQueryReturnType, type ApiUsePrefetchQueryOptions, type ApiUseQueryOptions, type AsyncApiResult, 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 KeysetPaginationResult, type OffsetInfiniteQueryOptions, type OffsetPagination, type OffsetPaginationParams, type OffsetPaginationResponse, type OffsetPaginationResult, type PaginatedDataDto, QueryClient, type QueryClientUpdateOptions, type QueryClientUpdateResult, type QueryConfig, type QueryKeyArrayItemFromConfig, type QueryKeysWithArrayEntityFromConfig, type QueryParams, type Sort, type SortDirection, SortUtil, type TanstackQueryClient, type UseKeysetInfiniteQueryReturnType, type UseMutationReturnType, type UseOffsetInfiniteQueryReturnType, 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 };

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, SortUtil, apiUtilsPlugin, createApiInfiniteQueryUtils, createApiMutationUtils, createApiPrefetchInfiniteQueryUtils, createApiPrefetchQueryUtils, createApiQueryClientUtils, createApiQueryUtils, createApiUtils, getQueryClient as getTanstackQueryClient, initializeApiUtils, setQueryConfig };

package/package.json

@@ -4,8 +4,8 @@
     "access": "public"
   },
   "type": "module",
-  "version": "1.0.0",
-  "license": "MIT",
+  "version": "1.1.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,12 +38,14 @@
     "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.1"
+    "@wisemen/eslint-config-vue": "2.1.2"
   },
   "scripts": {
     "build": "tsdown",

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