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

package/skills/writing-mutations/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: writing-mutations
+description: >
+  Create, update, delete resources using factory-provided useMutation, typed queryKeysToInvalidate, AsyncResult error handling, execute function, request shape with body/params separation.
+type: core
+library: vue-core-api-utils
+library_version: "0.0.3"
+sources:
+  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/usage/mutation.md"
+  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/composables/mutation/mutation.composable.ts"
+  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/factory/createApiMutationUtils.ts"
+---
+
+# @wisemen/vue-core-api-utils — Writing Mutations
+
+Create, update, and delete resources. Mutations automatically invalidate affected queries and return AsyncResult for explicit error handling.
+
+## Setup
+
+```typescript
+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
+    },
+  })
+}
+```
+
+Every mutation must list which queries to invalidate via `queryKeysToInvalidate`.
+
+## Core Patterns
+
+### Execute a mutation and handle the result
+
+```typescript
+import { useCreateContact } from '@/composables'
+
+const { execute, result } = useCreateContact()
+
+async function handleSubmit(formData: ContactCreateForm) {
+  const response = await execute({ body: formData })
+  
+  if (response.isOk()) {
+    console.log('Created contact:', response.getValue())
+    // Invalidated queries will refetch automatically
+  } else if (response.isErr()) {
+    const error = response.getError()
+    // Handle error based on code
+    if (error.errors[0].code === 'EMAIL_EXISTS') {
+      toast.error('That email is already registered')
+    } else {
+      toast.error('Creation failed')
+    }
+  }
+}
+```
+
+Always `await execute()` and check the result state before continuing.
+
+### Update mutation with specific query invalidation
+
+```typescript
+export function useUpdateContact(contactUuid: string) {
+  return useMutation({
+    queryFn: async (options: { body: ContactUpdateForm }) => {
+      return await ContactService.update(contactUuid, options.body)
+    },
+    queryKeysToInvalidate: {
+      contactDetail: {}, // Invalidate the specific contact
+      contactList: {},   // And the list
+    },
+  })
+}
+```
+
+You can invalidate multiple queries. Include queries that depend on the data you're changing.
+
+### Form integration
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useCreateContact } from '@/composables'
+
+const form = reactive({ name: '', email: '' })
+const { execute, result } = useCreateContact()
+
+async function handleSubmit() {
+  const response = await execute({ body: form })
+  
+  if (response.isOk()) {
+    router.push('/contacts')
+  }
+  // If isErr, form stays visible for user to retry
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <input v-model="form.name" />
+    <input v-model="form.email" />
+    <button :disabled="result.isLoading()">
+      {{ result.isLoading() ? 'Creating...' : 'Create' }}
+    </button>
+    <div v-if="result.isErr()">
+      Error: {{ result.getError().errors[0].detail }}
+    </div>
+  </form>
+</template>
+```
+
+Use `result.isLoading()` to disable the button during mutation.
+
+## Common Mistakes
+
+### CRITICAL: Import useMutation from @tanstack/vue-query instead of factory
+
+```typescript
+// ❌ Wrong: using TanStack directly
+import { useMutation } from '@tanstack/vue-query'
+
+const mutation = useMutation({
+  mutationFn: async (data) => ContactService.create(data),
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: ['contactList'] })
+  },
+})
+// Loses AsyncResult, type safety, error codes
+```
+
+```typescript
+// ✅ Correct: use factory composable
+import { useMutation } from '@/api'
+
+const { execute, result } = useMutation({
+  queryFn: async (options: { body: ContactCreateForm }) => {
+    return await ContactService.create(options.body)
+  },
+  queryKeysToInvalidate: {
+    contactList: {}, // Typed, type-safe
+  },
+})
+// Full AsyncResult, type-safe queryKeysToInvalidate, error codes
+```
+
+Direct TanStack import loses the factory's type safety and AsyncResult wrapping.
+
+Source: Library architecture — always use composables from `createApiUtils()` factory
+
+### CRITICAL: Forget to list queryKeysToInvalidate; cache becomes stale
+
+```typescript
+// ❌ Wrong: no queryKeysToInvalidate
+const { execute } = useMutation({
+  queryFn: async (options: { body: ContactCreateForm }) => {
+    return await ContactService.create(options.body)
+  },
+  // Forgot queryKeysToInvalidate!
+})
+// Mutation succeeds but list query still shows old data
+```
+
+```typescript
+// ✅ Correct: invalidate affected queries
+const { execute } = useMutation({
+  queryFn: async (options: { body: ContactCreateForm }) => {
+    return await ContactService.create(options.body)
+  },
+  queryKeysToInvalidate: {
+    contactList: {}, // Invalidate all contactList queries
+  },
+})
+// After success, contactList queries refetch
+```
+
+If you don't list which queries to invalidate, the cache stays stale and the UI shows outdated data. Update returns success but list still shows old items.
+
+Source: `docs/packages/api-utils/pages/usage/mutation.md` Create Mutation Example
+
+### HIGH: Not await execute(); code runs before mutation completes
+
+```typescript
+// ❌ Wrong: fire and forget
+async function handleSubmit() {
+  execute({ body: formData })
+  router.push('/contacts') // Redirects before mutation finishes!
+}
+```
+
+```typescript
+// ✅ Correct: await the result
+async function handleSubmit() {
+  const result = await execute({ body: formData })
+  if (result.isOk()) {
+    router.push('/contacts')
+  }
+  // If isErr, form stays visible for retry
+}
+```
+
+Not awaiting `execute()` means the mutation is still in flight when you navigate away or access the result. Always await and check the result before continuing.
+
+Source: `docs/packages/api-utils/pages/usage/mutation.md` Usage in Component
+
+### HIGH: Use body instead of params for query parameters
+
+```typescript
+// ❌ Wrong: filter/search as body
+const { execute } = useMutation({
+  queryFn: async (options) => {
+    return await SearchService.search(options.body) // params should go in URL!
+  },
+})
+```
+
+```typescript
+// ✅ Correct: separate body and params
+const { execute } = useMutation({
+  queryFn: async (options) => {
+    const { body, params } = options
+    return await SearchService.search(params) // URL params
+  },
+})
+```
+
+When mutations accept query parameters (filters, search), pass them in the `params` field of the options, not `body`. `body` is for request payload; `params` is for URL query string.
+
+Source: Source code `mutation.composable.ts` — request shape documentation
+
+## See Also
+
+- [Cache Management](../cache-management/SKILL.md) — Understanding which queries to invalidate
+- [Writing Queries](../writing-queries/SKILL.md) — Mutations invalidate queries; understand queries first

package/skills/writing-queries/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: writing-queries
+description: >
+  Single resource queries using factory-provided useQuery, computed ref params, staleTime configuration, queryFn, refetch, isFetching vs isLoading distinctions, automatic cache management.
+type: core
+library: vue-core-api-utils
+library_version: "0.0.3"
+sources:
+  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/usage/query.md"
+  - "wisemen-digital/wisemen-core:docs/packages/api-utils/pages/usage/overview.md"
+  - "wisemen-digital/wisemen-core:packages/web/api-utils/src/composables/query/query.composable.ts"
+---
+
+# @wisemen/vue-core-api-utils — Writing Queries
+
+Fetch single resources with automatic caching, parameter reactivity, and configurable staleness.
+
+## Setup
+
+```typescript
+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, // 5 minutes
+  })
+}
+```
+
+The `params` object must contain computed refs so the query automatically refetches when params change.
+
+## Core Patterns
+
+### Query with reactive parameters
+
+```typescript
+import { computed, ref } from 'vue'
+import { useQuery } from '@/api'
+
+const contactUuid = ref('123')
+
+const { result, refetch } = useQuery('contactDetail', {
+  params: {
+    contactUuid: computed(() => contactUuid.value), // Computed so query watches it
+  },
+  queryFn: () => ContactService.getByUuid(contactUuid.value),
+  staleTime: 1000 * 60 * 5,
+})
+
+// When contactUuid.value changes, the query automatically refetches
+contactUuid.value = '456'
+```
+
+Parameters must be computed refs. If you pass a plain ref, the query doesn't watch changes.
+
+### Set cache expiry with staleTime
+
+```typescript
+// Cache is fresh for 5 minutes — no background refetch
+const { result } = useQuery('contactDetail', {
+  params: { contactUuid: computed(() => '123') },
+  queryFn: () => ContactService.getByUuid('123'),
+  staleTime: 1000 * 60 * 5, // 5 minutes = 300 seconds
+})
+
+// Default staleTime is 0 — cache immediately becomes stale
+// Combine with global defaults in apiUtilsPlugin config
+```
+
+`staleTime` determines how long cached data is considered fresh. After this time, the next query interaction triggers a background refetch.
+
+### Manually refetch on demand
+
+```typescript
+const { result, refetch } = useQuery('contactDetail', {
+  params: { contactUuid: computed(() => '123') },
+  queryFn: () => ContactService.getByUuid('123'),
+})
+
+// Manually trigger a new fetch
+await refetch()
+
+// After refetch completes, result contains new data
+if (result.value.isOk()) {
+  console.log(result.value.getValue())
+}
+```
+
+## Common Mistakes
+
+### CRITICAL: Import useQuery from @tanstack/vue-query instead of factory
+
+```typescript
+// ❌ Wrong: using TanStack directly
+import { useQuery } from '@tanstack/vue-query'
+
+const { data, error, isLoading } = useQuery({
+  queryKey: ['contactDetail', '123'],
+  queryFn: () => ContactService.getByUuid('123'),
+})
+// Loses AsyncResult wrapping, type safety, error code typing
+```
+
+```typescript
+// ✅ Correct: use factory-provided composable
+import { useQuery } from '@/api'
+import { computed } from 'vue'
+
+const { result, isLoading } = useQuery('contactDetail', {
+  params: { contactUuid: computed(() => '123') },
+  queryFn: () => ContactService.getByUuid('123'),
+  staleTime: 1000 * 60 * 5,
+})
+// Full type safety, AsyncResult wrapping, automatic error codes
+```
+
+Importing directly from @tanstack/vue-query bypasses the typed factory, losing AsyncResult wrapping, type-safe query keys, and error code typing.
+
+Source: Library architecture — always use composables from `createApiUtils()` factory
+
+### HIGH: Use plain ref for params instead of computed
+
+```typescript
+// ❌ Wrong: plain ref doesn't trigger refetch
+const userId = ref('123')
+const { result } = useQuery('userDetail', {
+  params: { userId }, // plain ref, not computed
+  queryFn: () => UserService.getById(userId.value),
+})
+// Later: userId.value = '456'
+// Query does NOT refetch — cache stays stale!
+```
+
+```typescript
+// ✅ Correct: use computed so query watches changes
+const userId = computed(() => props.userId)
+const { result } = useQuery('userDetail', {
+  params: { userId },
+  queryFn: () => UserService.getById(userId.value),
+})
+// userId changes → computed updates → query watches → refetch happens
+```
+
+When params are plain refs, the query doesn't watch them and the cache isn't invalidated when the param changes.
+
+Source: `docs/packages/api-utils/pages/usage/query.md` Usage in Vue Component section
+
+### HIGH: Not set staleTime; serve stale cache indefinitely
+
+```typescript
+// ❌ Wrong: no staleTime; background refetch constantly
+const { result } = useQuery('userDetail', {
+  params: { userId: computed(() => '123') },
+  queryFn: () => UserService.getById('123'),
+  // staleTime defaults to 0 — cache is immediately stale!
+})
+// Every component interaction triggers a refetch
+```
+
+```typescript
+// ✅ Correct: set staleTime to a reasonable value
+const { result } = useQuery('userDetail', {
+  params: { userId: computed(() => '123') },
+  queryFn: () => UserService.getById('123'),
+  staleTime: 1000 * 60 * 5, // 5 minutes
+})
+// Cache remains fresh for 5 minutes — background refetch only after expiry
+```
+
+Default `staleTime` is 0, meaning the cache is immediately considered stale. Every interaction triggers a background refetch. Set `staleTime` based on how frequently the data changes.
+
+Source: `docs/packages/api-utils/pages/getting-started/installation.md` Setup section
+
+### MEDIUM: Confuse isFetching with isLoading
+
+```typescript
+// ❌ Wrong: checking isLoading for conditional render
+const { result, isLoading } = useQuery(...)
+if (isLoading.value) {
+  return // Exits only on initial load!
+}
+// Code here runs while background refetch happens
+```
+
+```typescript
+// ✅ Correct: use result.isLoading() for state checks
+const { result } = useQuery(...)
+if (result.value.isLoading()) {
+  return // True only on initial load
+}
+// Use isFetching separately for background fetch indicator
+```
+
+`isLoading` is true only during the initial fetch. `isFetching` is true whenever any fetch is in progress (including background refetches). Use `result.isLoading()` for conditional rendering; use `isFetching` for loading indicators on load-more buttons.
+
+Source: `docs/packages/api-utils/pages/usage/query.md` Return Values section
+
+## See Also
+
+- [Cache Management](../cache-management/SKILL.md) — Understanding caching strategy informs staleTime choices
+- [Writing Infinite Queries](../writing-infinitequeries/SKILL.md) — Pagination uses the same patterns