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

package/skills/foundations/SKILL.md

@@ -0,0 +1,461 @@
+---
+name: foundations
+description: >
+  neverthrow Result architectural basis; three-state AsyncResult relationship to Result; @tanstack/vue-query lifecycle (staleTime, gcTime, refetch); composition of TanStack Query + neverthrow + Vue 3 reactivity.
+type: core
+library: vue-core-api-utils
+library_version: "0.0.3"
+sources:
+  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/concepts/result-types.md"
+  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/async-result/asyncResult.ts"
+  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/types/apiError.type.ts"
+  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/config/config.ts"
+---
+
+# @wisemen/vue-core-api-utils — Foundations
+
+Understand how `AsyncResult` from `neverthrow` and `@tanstack/vue-query` combine to provide structured error handling and reactive query management. This knowledge informs all other skills.
+
+## Core Concepts
+
+### AsyncResult: The three-state type system
+
+`AsyncResult<T, E>` is a Result type from the `neverthrow` library that explicitly models three states:
+
+```typescript
+type AsyncResult<T, E> = AsyncResultLoading 
+  | AsyncResultOk<T>
+  | AsyncResultErr<E>
+```
+
+The three states replace traditional Vue composition with separate flags:
+
+```typescript
+// ❌ Old pattern: multiple flags
+const isLoading = ref(false)
+const isError = ref(false)
+const data = ref(null)
+const error = ref(null)
+
+// Which combinations are valid? isLoading + isError? isLoading + data?
+// The state machine is implicit, error-prone
+```
+
+```typescript
+// ✅ AsyncResult: single discriminated union
+const result = ref<AsyncResult<Contact, ApiError>>(new AsyncResultLoading())
+
+// Only three valid states; type system enforces them
+// Pattern matching makes every state explicit
+result.value.match({
+  loading: () => 'Loading...',
+  ok: (contact) => contact.name,
+  err: (error) => error.message,
+})
+```
+
+### Three-state representation
+
+AsyncResult wraps any promise-based operation:
+
+| State | Setup | Usage | Next |
+|-------|-------|-------|------|
+| **Loading** | Initial state when query starts | Show spinner/skeleton | → Ok or Err |
+| **Ok(T)** | Server returned success with data | Show data with `getValue()` | Stays Ok until refetch |
+| **Err(E)** | Server returned error or network failed | Show error with `getError()` | Query can be retried |
+
+```typescript
+import { useQuery } from '@/api'
+
+const { result } = useQuery('contactDetail', {
+  queryFn: () => ContactService.getDetail(uuid),
+})
+
+// result is computed ref to AsyncResult<Contact, ApiError>
+result.value.match({
+  loading: () => <div>Loading</div>,
+  ok: (contact) => <div>{contact.name}</div>,
+  err: (error) => <div>Error: {error.message}</div>,
+})
+```
+
+### neverthrow Result vs AsyncResult
+
+neverthrow provides `Result<T, E>` for synchronous operations. `AsyncResult` extends it for async:
+
+```typescript
+// neverthrow Result: already resolved
+const result: Result<Contact, ApiError> = await contactService.getDetail()
+
+result.match({
+  ok: (contact) => console.log(contact.name),
+  err: (error) => console.error(error.message),
+})
+```
+
+```typescript
+// AsyncResult: waiting for promise
+const result: AsyncResult<Contact, ApiError> = new AsyncResultLoading()
+
+result.match({
+  loading: () => console.log('Waiting...'),
+  ok: (contact) => console.log(contact.name),
+  err: (error) => console.error(error.message),
+})
+```
+
+AsyncResult is Result + loading state. Every composable that fetches data returns AsyncResult.
+
+### Type guards from neverthrow
+
+Safely extract values using type guards:
+
+```typescript
+const result = new AsyncResultOk(contact)
+
+// Type predicate
+if (result.isOk()) {
+  const contact = result.getValue() // No type error; TypeScript knows it's Contact
+}
+
+const errResult = new AsyncResultErr(error)
+if (errResult.isErr()) {
+  const error = errResult.getError() // No type error; TypeScript knows it's ApiError
+}
+
+if (!result.isLoading()) {
+  // Could be Ok or Err
+}
+```
+
+## TanStack Query Lifecycle
+
+`@tanstack/vue-query` manages the async lifecycle beneath AsyncResult.
+
+### Query state machine
+
+```
+[Initial]
+   ↓
+[Fetching] (isLoading)
+   ↓
+[Stale] (cached data exists but flagged for refresh)
+   ↓
+[Inactive] (unused queries auto-cleanup after gcTime)
+```
+
+### Stale time: How long is cached data fresh?
+
+```typescript
+const { result } = useQuery('contactDetail', {
+  queryFn: () => ContactService.getDetail(uuid),
+  staleTime: 5 * 60 * 1000, // 5 minutes
+})
+
+// Timeline:
+// T=0:    First fetch. Result is Ok(contact). freshInterval starts.
+// T=4m59s: Data is still fresh. Returning cached contact instantly.
+// T=5m01s: Data is now stale. Still showing cached contact, but next interaction refetches.
+// T=next-page-view: Fresh fetch triggered automatically.
+```
+
+Stale time is the **grace period** before the cache is considered outdated. While fresh, subsequent requests return cache instantly without refetching.
+
+### Garbage collection time: When does cache disappear?
+
+```typescript
+const gcTime = 5 * 60 * 1000 // 5 minutes
+
+// Query runs, then becomes unused (component unmounts, user navigates away).
+// For gcTime duration, data is kept in memory (but marked as stale).
+// After gcTime, if query hasn't been accessed, it's deleted from cache.
+```
+
+gcTime is cleanup. If you navigate back before gcTime expires, you get the cached (stale) data. After gcTime, next access refetches fresh.
+
+### Refetch triggers
+
+Queries refetch when:
+
+1. **Manual trigger** — `refetch()` function
+2. **Mutation invalidation** — `queryKeysToInvalidate` in mutation definition
+3. **Stale time expired** — Next component interaction after staleTime passes
+4. **Focus refetch** — Window regains focus (configurable)
+5. **Component mount** — If cache is beyond gcTime
+
+```typescript
+const { result, refetch } = useQuery('contactDetail', {
+  queryFn: () => ContactService.getDetail(uuid),
+  staleTime: 5 * 60 * 1000,
+})
+
+// Manual refetch
+async function handleRefresh() {
+  await refetch()
+  // result updates to new Ok or Err
+}
+
+// Automatic refetch on mutation (via queryKeysToInvalidate)
+const { execute } = useMutation({
+  queryFn: (data) => ContactService.update(data),
+  queryKeysToInvalidate: { contactDetail: () => true },
+})
+// After execute succeeds, contactDetail is invalidated
+// Next useQuery('contactDetail') refetches fresh data
+```
+
+## Composable architecture
+
+Each composable in vue-core-api-utils is built from:
+
+1. **TanStack Query composable** — `useQuery`, `useInfiniteQuery`, `useMutation` from @tanstack/vue-query
+2. **AsyncResult wrapper** — Result from neverthrow with loading state
+3. **Type-safe parameters** — ProjectQueryKeys and error codes from your domain
+
+```typescript
+// High-level (what you use)
+const { result, isLoading, refetch } = useQuery('contactDetail', {
+  params: computed(() => ({ uuid })),
+  queryFn: () => ContactService.getDetail(uuid),
+  staleTime: 5 * 60 * 1000,
+})
+
+// Under the hood:
+// 1. TanStack Query manages the fetch lifecycle
+const query = useQueryRaw(queryKey, queryFn, { staleTime })
+
+// 2. Wrap query state in AsyncResult
+const result = computed(() => {
+  if (query.isLoading.value) return new AsyncResultLoading()
+  if (query.isError.value) return new AsyncResultErr(query.error.value)
+  return new AsyncResultOk(query.data.value)
+})
+
+// 3. Expose typed composable
+return { result, isLoading: query.isLoading, refetch: query.refetch }
+```
+
+The composables handle this composition. You just use `result.value.match()`.
+
+## Error handling strategy
+
+Errors are typed and structured using `neverthrow`:
+
+```typescript
+// Error type definition
+interface ApiExpectedError {
+  errors: Array<{
+    code: string
+    message: string
+    details?: unknown
+  }>
+}
+
+type ApiError = ApiExpectedError | ApiUnexpectedError
+
+// In AsyncResult
+const result = new AsyncResultErr(apiError)
+
+result.match({
+  ok: (data) => {}, // not executed
+  err: (error) => {
+    // error is ApiError
+    if (error instanceof ApiExpectedError) {
+      // Handle known API errors
+      const codes = error.errors.map(e => e.code)
+    } else {
+      // Handle network/parsing errors
+      console.error(error.message)
+    }
+  },
+})
+```
+
+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:
+
+```
+User interaction
+    ↓
+useQuery/useMutation composable
+    ↓
+@tanstack/vue-query (fetch + cache mgmt)
+    ↓
+Promise from queryFn
+    ↓
+neverthrow Result handling
+    ↓
+AsyncResult (Loading | Ok | Err)
+    ↓
+Vue computed ref (reactive)
+    ↓
+Template pattern matching with result.value.match()
+```
+
+Each layer adds value:
+- **User interaction** triggers the flow
+- **Composable** provides type safety (ProjectQueryKeys)
+- **TanStack Query** handles caching, refetching, lifecycle
+- **neverthrow** enforces error handling at compile time
+- **AsyncResult** makes state explicit in templates
+- **Vue reactivity** keeps UI synchronized
+
+Understanding this stack helps you use each piece correctly.
+
+## See Also
+
+- [AsyncResult Handling](../asyncresult-handling/SKILL.md) — Deep dive into pattern matching and type guards
+- [Writing Queries](../writing-queries/SKILL.md) — Applying staleTime and refetch in real queries
+- [Writing Mutations](../writing-mutations/SKILL.md) — How mutations invalidate cache
+- [Cache Management](../cache-management/SKILL.md) — Manual cache operations behind the scenes

package/skills/getting-started/SKILL.md

@@ -0,0 +1,248 @@
+---
+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.
+type: lifecycle
+library: vue-core-api-utils
+library_version: "1.0.1"
+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/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.
+
+## Setup
+
+### 1. Install the package
+
+```bash
+pnpm install @wisemen/vue-core-api-utils @tanstack/vue-query neverthrow vue
+```
+
+### 2. Define your query keys
+
+Create a TypeScript interface that maps query keys to their response types and parameters:
+
+```typescript
+// src/types/queryKey.type.ts
+
+export interface ProjectQueryKeys {
+  // Single entity query
+  contactDetail: {
+    entity: Contact
+    params: { contactUuid: string }
+  }
+  
+  // List query with offset pagination
+  contactList: {
+    entity: Contact[]
+    params: { page: number; limit: number; search?: string }
+  }
+  
+  // List query with keyset pagination
+  contactListKeyset: {
+    entity: Contact[]
+    params: { limit: number; key?: string }
+  }
+}
+```
+
+Every key must have both `entity` (response type) and `params` (required parameters).
+
+### 3. Initialize the plugin in your main.ts
+
+```typescript
+// main.ts
+
+import { createApp } from 'vue'
+import { apiUtilsPlugin } from '@wisemen/vue-core-api-utils'
+import App from './App.vue'
+
+const app = createApp(App)
+
+app.use(apiUtilsPlugin({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5, // 5 minutes
+      retry: 1,
+    },
+  },
+}))
+
+app.mount('#app')
+```
+
+The `apiUtilsPlugin` function creates a QueryClient with your config and handles @tanstack/vue-query setup internally.
+
+### 4. Create your API composables
+
+```typescript
+// src/api/index.ts
+
+import type {
+  ApiResult as ApiUtilsApiResult,
+  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 {
+  useKeysetInfiniteQuery,
+  useMutation,
+  useOffsetInfiniteQuery,
+  useQuery,
+  usePrefetchKeysetInfiniteQuery,
+  usePrefetchOffsetInfiniteQuery,
+  usePrefetchQuery,
+  useQueryClient,
+} = createApiUtils<ProjectQueryKeys, ERROR_KEYS>()
+
+// Export typed result types
+export type ApiResult<T> = ApiUtilsApiResult<T, ERROR_KEYS>
+export type OffsetPaginationResult<T> = ApiUtilsOffsetPaginationResult<T, ERROR_KEYS>
+export type KeysetPaginationResult<T> = ApiUtilsKeysetPaginationResult<T, ERROR_KEYS>
+```
+
+## Core Patterns
+
+### Create a detail query composable
+
+```typescript
+// src/composables/useContactDetail.ts
+
+import { computed } from 'vue'
+import { useQuery } from '@/api'
+import { ContactService } from '@/services'
+
+export function useContactDetail(contactUuid: string) {
+  return useQuery('contactDetail', {
+    params: { contactUuid: computed(() => contactUuid) },
+    queryFn: () => ContactService.getByUuid(contactUuid),
+    staleTime: 1000 * 60 * 5,
+  })
+}
+```
+
+Parameters must be computed refs so the query watches changes and refetches automatically.
+
+### Create a mutation composable
+
+```typescript
+// src/composables/useCreateContact.ts
+
+import { useMutation } from '@/api'
+import { ContactService } from '@/services'
+
+export function useCreateContact() {
+  return useMutation({
+    queryFn: async (options: { body: ContactCreateForm }) => {
+      return await ContactService.create(options.body)
+    },
+    queryKeysToInvalidate: {
+      contactList: {}, // Invalidate all contactList queries after success
+    },
+  })
+}
+```
+
+Every mutation should list which queries to invalidate via `queryKeysToInvalidate`.
+
+### Use composables in components
+
+```vue
+<script setup lang="ts">
+import { useContactDetail } from '@/composables'
+
+const props = defineProps<{ contactUuid: string }>()
+const { result, refetch } = useContactDetail(props.contactUuid)
+</script>
+
+<template>
+  <div>
+    <div v-if="result.isLoading()">Loading...</div>
+    <div v-else-if="result.isOk()">
+      Name: {{ result.getValue().name }}
+    </div>
+    <div v-else-if="result.isErr()">
+      Error: {{ result.getError().detail }}
+    </div>
+    <button @click="refetch">Retry</button>
+  </div>
+</template>
+```
+
+All queries and mutations return `AsyncResult` with three states: loading, ok, and err.
+
+## Common Mistakes
+
+### CRITICAL: Forget to initialize apiUtilsPlugin with QueryClient config
+
+```typescript
+// ❌ Wrong: plugin not initialized
+const app = createApp(App)
+app.mount('#app')
+// Throws: "[api-utils] QueryClient not available..."
+```
+
+```typescript
+// ✅ Correct: plugin initialized with config
+const app = createApp(App)
+app.use(apiUtilsPlugin({
+  defaultOptions: {
+    queries: { staleTime: 1000 * 60 * 5 },
+  },
+}))
+app.mount('#app')
+```
+
+If you skip the plugin, `createApiUtils()` has no QueryClient and throws immediately.
+
+Source: `src/config/config.ts` — `getQueryClient()` assertion
+
+### HIGH: Define query keys interface without strict entity/params structure
+
+```typescript
+// ❌ Wrong: inconsistent structure
+export interface ProjectQueryKeys {
+  contactDetail: { entity: Contact } // Missing params!
+  contactList: Contact[] // Should wrap in { entity, params }
+}
+```
+
+```typescript
+// ✅ Correct: every key has entity and params
+export interface ProjectQueryKeys {
+  contactDetail: {
+    entity: Contact
+    params: { contactUuid: string }
+  }
+  contactList: {
+    entity: Contact[]
+    params: { page: number; limit: number }
+  }
+}
+```
+
+Query keys without proper structure prevent the factory from typing composables correctly and cause runtime errors during query key resolution.
+
+Source: `docs/packages/api-utils/pages/getting-started/installation.md` Section 3
+
+## You're all set!
+
+You now have:
+- ✅ Plugin initialized with Vue Query
+- ✅ Query keys defined with types
+- ✅ API composables created
+- ✅ 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.