ima-claude 2.9.0

package/plugins/ima-claude/skills/js-fp-vue/references/reactivity-patterns.md

@@ -0,0 +1,348 @@
+# Reactivity Patterns
+
+Deep reactivity patterns, performance optimization, and memory management for Vue.js.
+
+## Table of Contents
+
+1. [Reactive vs Ref](#reactive-vs-ref)
+2. [Computed Optimization](#computed-optimization)
+3. [Watch Anti-Patterns](#watch-anti-patterns)
+4. [ShallowRef for Performance](#shallowref-for-performance)
+5. [Memory Management](#memory-management)
+6. [Common Anti-Patterns](#common-anti-patterns)
+
+---
+
+## Reactive vs Ref
+
+### When to Use ref()
+
+```typescript
+import { ref, computed } from 'vue'
+
+// Primitives - always ref
+const count = ref(0)
+const name = ref('')
+const isActive = ref(false)
+
+// Simple objects - prefer ref for consistency
+const user = ref<UserData>({ id: '1', name: 'Alice', email: 'alice@test.com' })
+
+// Access with .value in script
+console.log(user.value.name)
+
+// Template auto-unwraps
+// <p>{{ user.name }}</p>
+```
+
+### When to Use reactive()
+
+```typescript
+import { reactive } from 'vue'
+
+// Complex nested objects with many properties
+const state = reactive({
+  users: [] as UserData[],
+  filters: {
+    search: '',
+    minAge: 0,
+    status: 'active' as 'active' | 'inactive'
+  },
+  pagination: {
+    page: 1,
+    perPage: 20,
+    total: 0
+  }
+})
+
+// No .value needed
+console.log(state.filters.search)
+```
+
+### Decision Guide
+
+| Scenario | Use |
+|----------|-----|
+| Primitive values | `ref()` |
+| Single object | `ref()` |
+| Form state with many fields | `reactive()` |
+| Complex nested state | `reactive()` |
+| Needs to be replaced entirely | `ref()` |
+| Need to pass by reference | `ref()` |
+
+---
+
+## Computed Optimization
+
+### Always Computed for Derived State
+
+```typescript
+import { ref, computed } from 'vue'
+
+const users = ref<UserData[]>([])
+const searchTerm = ref('')
+
+// Good: computed automatically caches
+const filteredUsers = computed(() =>
+  users.value.filter(u =>
+    u.name.toLowerCase().includes(searchTerm.value.toLowerCase())
+  )
+)
+
+// Good: computed chain
+const activeFilteredUsers = computed(() =>
+  filteredUsers.value.filter(u => u.isActive)
+)
+
+const userCount = computed(() => activeFilteredUsers.value.length)
+```
+
+### Avoid Expensive Recomputation
+
+```typescript
+// Bad: recomputes on every access
+const getExpensiveData = () => {
+  return users.value.map(u => ({
+    ...u,
+    computed: expensiveCalculation(u)
+  }))
+}
+
+// Good: computed caches until dependencies change
+const expensiveData = computed(() =>
+  users.value.map(u => ({
+    ...u,
+    computed: expensiveCalculation(u)
+  }))
+)
+```
+
+### Computed with Getters and Setters
+
+```typescript
+const firstName = ref('John')
+const lastName = ref('Doe')
+
+const fullName = computed({
+  get: () => `${firstName.value} ${lastName.value}`,
+  set: (value: string) => {
+    const [first, ...rest] = value.split(' ')
+    firstName.value = first
+    lastName.value = rest.join(' ')
+  }
+})
+
+// Usage
+fullName.value = 'Jane Smith' // Sets firstName and lastName
+```
+
+---
+
+## Watch Anti-Patterns
+
+### Bad: Watch for Derived State
+
+```typescript
+// Bad: watch to update derived state
+const fullName = ref('')
+watch([firstName, lastName], () => {
+  fullName.value = `${firstName.value} ${lastName.value}`
+})
+
+// Good: computed for derived state
+const fullName = computed(() => `${firstName.value} ${lastName.value}`)
+```
+
+### Good: Watch for Side Effects Only
+
+```typescript
+import { watch, watchEffect } from 'vue'
+
+// Good: watch for API calls
+watch(userId, async (newId) => {
+  if (newId) {
+    user.value = await fetchUser(newId)
+  }
+})
+
+// Good: watchEffect for multiple dependencies
+watchEffect(() => {
+  if (user.value && isActive.value) {
+    analytics.track('user_active', { userId: user.value.id })
+  }
+})
+
+// Good: watch with cleanup
+watch(source, (newValue, oldValue, onCleanup) => {
+  const controller = new AbortController()
+  fetchData(newValue, { signal: controller.signal })
+
+  onCleanup(() => controller.abort())
+})
+```
+
+---
+
+## ShallowRef for Performance
+
+Use shallowRef when you have large objects that are replaced, not mutated.
+
+```typescript
+import { shallowRef, triggerRef } from 'vue'
+
+// Large dataset that gets replaced entirely
+const largeDataset = shallowRef<DataItem[]>([])
+
+// Replacing works fine
+const refreshData = async () => {
+  largeDataset.value = await fetchLargeDataset()
+}
+
+// Mutation requires manual trigger
+const updateItem = (index: number, updates: Partial<DataItem>) => {
+  largeDataset.value[index] = { ...largeDataset.value[index], ...updates }
+  triggerRef(largeDataset) // Manual trigger needed
+}
+```
+
+### When to Use shallowRef
+
+| Scenario | Use |
+|----------|-----|
+| Large arrays (1000+ items) | `shallowRef()` |
+| Data replaced, not mutated | `shallowRef()` |
+| Deeply nested objects | `shallowRef()` or `shallowReactive()` |
+| Small objects with mutations | `ref()` |
+
+---
+
+## Memory Management
+
+### Cleanup Subscriptions
+
+```typescript
+import { onUnmounted } from 'vue'
+
+export const useEventListener = (
+  target: EventTarget,
+  event: string,
+  handler: EventListener
+) => {
+  target.addEventListener(event, handler)
+
+  onUnmounted(() => {
+    target.removeEventListener(event, handler)
+  })
+}
+```
+
+### Avoid Memory Leaks with watchEffect
+
+```typescript
+import { watchEffect } from 'vue'
+
+// watchEffect auto-stops when component unmounts
+// But manual stop is available if needed
+const stop = watchEffect(() => {
+  // Side effect
+})
+
+// Manual stop if needed
+// stop()
+```
+
+### Cleanup in Async Operations
+
+```typescript
+import { ref, onUnmounted } from 'vue'
+
+export const useAsyncData = <T>(fetcher: () => Promise<T>) => {
+  const data = ref<T | null>(null)
+  const loading = ref(false)
+  let cancelled = false
+
+  const fetch = async () => {
+    cancelled = false
+    loading.value = true
+    try {
+      const result = await fetcher()
+      if (!cancelled) {
+        data.value = result
+      }
+    } finally {
+      if (!cancelled) {
+        loading.value = false
+      }
+    }
+  }
+
+  onUnmounted(() => {
+    cancelled = true
+  })
+
+  return { data, loading, fetch }
+}
+```
+
+---
+
+## Common Anti-Patterns
+
+### Reactive Over-Engineering
+
+```typescript
+// Bad: Unnecessary nesting
+const user = reactive({
+  profile: reactive({
+    settings: reactive({
+      theme: 'dark'
+    })
+  })
+})
+
+// Good: Simple structure
+const userSettings = ref({ theme: 'dark', notifications: true })
+const isDarkTheme = computed(() => userSettings.value.theme === 'dark')
+```
+
+### Ref Unwrapping Confusion
+
+```typescript
+// Bad: Inconsistent access
+const count = ref(0)
+console.log(count) // Ref object, not value
+
+// Good: Always use .value in script
+console.log(count.value)
+
+// Template auto-unwraps, no .value needed
+// <p>{{ count }}</p>
+```
+
+### Mutating Props
+
+```typescript
+// Bad: Mutating prop
+const props = defineProps<{ user: UserData }>()
+props.user.name = 'New Name' // Mutation!
+
+// Good: Emit update
+const emit = defineEmits<{ update: [user: UserData] }>()
+const updateName = (name: string) => {
+  emit('update', { ...props.user, name })
+}
+```
+
+---
+
+## Performance Checklist
+
+Before optimizing, always measure first. Then:
+
+1. Use `computed()` for derived state (caching)
+2. Avoid `watch()` for derived values
+3. Use `shallowRef()` for large datasets
+4. Clean up subscriptions in `onUnmounted()`
+5. Use `v-once` for static content in templates
+6. Use `v-memo` for expensive list renders
+7. Avoid reactive objects when plain objects suffice

package/plugins/ima-claude/skills/js-fp-vue/references/testing.md

@@ -0,0 +1,314 @@
+# Testing Vue FP Components
+
+Testing patterns for Vue.js functional programming architecture.
+
+## Table of Contents
+
+1. [Testing Pure Composables](#testing-pure-composables)
+2. [Testing Components](#testing-components)
+3. [Testing Wrapper Components](#testing-wrapper-components)
+4. [Mocking Dependencies](#mocking-dependencies)
+
+---
+
+## Testing Pure Composables
+
+Composables with pure logic are trivially testable.
+
+```typescript
+// composables/__tests__/useUserLogic.test.ts
+import { ref } from 'vue'
+import { useUserLogic } from '../useUserLogic'
+
+describe('useUserLogic', () => {
+  it('computes display data correctly', () => {
+    const userData = ref({
+      id: '1',
+      name: ' John ',
+      email: 'john@test.com'
+    })
+    const config = ref({
+      showEmail: true,
+      variant: 'compact' as const
+    })
+
+    const { displayData } = useUserLogic(userData, config)
+
+    expect(displayData.value).toEqual({
+      id: '1',
+      name: ' John ',
+      email: 'john@test.com',
+      displayName: 'John' // Trimmed
+    })
+  })
+
+  it('hides email when config.showEmail is false', () => {
+    const userData = ref({
+      id: '1',
+      name: 'John',
+      email: 'john@test.com'
+    })
+    const config = ref({
+      showEmail: false,
+      variant: 'compact' as const
+    })
+
+    const { displayData } = useUserLogic(userData, config)
+
+    expect(displayData.value.email).toBeUndefined()
+  })
+
+  it('generates correct CSS classes for variant', () => {
+    const userData = ref({ id: '1', name: 'John', email: 'john@test.com' })
+    const config = ref({ showEmail: true, variant: 'detailed' as const })
+
+    const { cssClasses } = useUserLogic(userData, config)
+
+    expect(cssClasses.value.card).toContain('detailed')
+  })
+
+  it('reacts to config changes', () => {
+    const userData = ref({ id: '1', name: 'John', email: 'john@test.com' })
+    const config = ref({ showEmail: true, variant: 'compact' as const })
+
+    const { displayData } = useUserLogic(userData, config)
+    expect(displayData.value.email).toBe('john@test.com')
+
+    config.value = { showEmail: false, variant: 'compact' }
+    expect(displayData.value.email).toBeUndefined()
+  })
+})
+```
+
+---
+
+## Testing Components
+
+Use Vue Test Utils for component testing.
+
+```typescript
+// components/__tests__/UserCard.test.ts
+import { mount } from '@vue/test-utils'
+import UserCard from '../UserCard.vue'
+
+describe('UserCard', () => {
+  const defaultProps = {
+    userData: { id: '1', name: 'John', email: 'john@test.com' },
+    config: { showEmail: true, variant: 'compact' as const }
+  }
+
+  it('renders user data correctly', () => {
+    const wrapper = mount(UserCard, { props: defaultProps })
+
+    expect(wrapper.find('.user-card__name').text()).toBe('John')
+    expect(wrapper.find('p').text()).toBe('john@test.com')
+  })
+
+  it('hides email when config.showEmail is false', () => {
+    const wrapper = mount(UserCard, {
+      props: {
+        ...defaultProps,
+        config: { showEmail: false, variant: 'compact' }
+      }
+    })
+
+    expect(wrapper.find('p').exists()).toBe(false)
+  })
+
+  it('applies correct variant class', () => {
+    const wrapper = mount(UserCard, {
+      props: {
+        ...defaultProps,
+        config: { showEmail: true, variant: 'detailed' }
+      }
+    })
+
+    expect(wrapper.find('.user-card').classes()).toContain('user-card--detailed')
+  })
+
+  it('emits update event with new data', async () => {
+    const wrapper = mount(UserCard, { props: defaultProps })
+
+    await wrapper.find('button').trigger('click')
+
+    expect(wrapper.emitted('update')).toBeTruthy()
+    expect(wrapper.emitted('update')![0]).toEqual([
+      expect.objectContaining({ id: '1' })
+    ])
+  })
+})
+```
+
+---
+
+## Testing Wrapper Components
+
+Test wrappers separately from pure components.
+
+```typescript
+// components/__tests__/UserDisplayWrapper.test.ts
+import { mount, flushPromises } from '@vue/test-utils'
+import UserDisplayWrapper from '../UserDisplayWrapper.vue'
+
+// Mock the API module
+vi.mock('@/api/userApi', () => ({
+  userApi: {
+    getUser: vi.fn(),
+    updateUser: vi.fn()
+  }
+}))
+
+import { userApi } from '@/api/userApi'
+
+describe('UserDisplayWrapper', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('shows loading state initially', () => {
+    (userApi.getUser as Mock).mockImplementation(() => new Promise(() => {}))
+
+    const wrapper = mount(UserDisplayWrapper, {
+      props: { userId: '1' }
+    })
+
+    expect(wrapper.text()).toContain('Loading')
+  })
+
+  it('renders user data after fetch', async () => {
+    (userApi.getUser as Mock).mockResolvedValue({
+      id: '1',
+      name: 'John',
+      email: 'john@test.com'
+    })
+
+    const wrapper = mount(UserDisplayWrapper, {
+      props: { userId: '1' }
+    })
+
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('John')
+  })
+
+  it('shows error state on fetch failure', async () => {
+    (userApi.getUser as Mock).mockRejectedValue(new Error('Network error'))
+
+    const wrapper = mount(UserDisplayWrapper, {
+      props: { userId: '1' }
+    })
+
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Error')
+  })
+
+  it('calls updateUser on update event', async () => {
+    const mockUser = { id: '1', name: 'John', email: 'john@test.com' }
+    ;(userApi.getUser as Mock).mockResolvedValue(mockUser)
+    ;(userApi.updateUser as Mock).mockResolvedValue(undefined)
+
+    const wrapper = mount(UserDisplayWrapper, {
+      props: { userId: '1' }
+    })
+
+    await flushPromises()
+
+    // Trigger update from child component
+    await wrapper.findComponent({ name: 'UserDisplayPure' }).vm.$emit('update', {
+      ...mockUser,
+      name: 'Updated'
+    })
+
+    expect(userApi.updateUser).toHaveBeenCalledWith(
+      expect.objectContaining({ name: 'Updated' })
+    )
+  })
+})
+```
+
+---
+
+## Mocking Dependencies
+
+### Using Provide/Inject for DI
+
+```typescript
+// Component that uses injected API
+// UserFeature.vue uses `const api = inject('api')`
+
+describe('UserFeature with injected API', () => {
+  const mockApi = {
+    getUser: vi.fn().mockResolvedValue({ id: '1', name: 'Test' }),
+    updateUser: vi.fn().mockResolvedValue(undefined)
+  }
+
+  it('uses injected API', async () => {
+    const wrapper = mount(UserFeature, {
+      global: {
+        provide: {
+          api: mockApi
+        }
+      },
+      props: { userId: '1' }
+    })
+
+    await flushPromises()
+
+    expect(mockApi.getUser).toHaveBeenCalledWith('1')
+  })
+})
+```
+
+### Testing Composables with Mocked Dependencies
+
+```typescript
+// composables/__tests__/useUserData.test.ts
+import { ref } from 'vue'
+import { useUserData } from '../useUserData'
+
+describe('useUserData', () => {
+  it('fetches user with provided API', async () => {
+    const mockApi = {
+      getUser: vi.fn().mockResolvedValue({ id: '1', name: 'Test' })
+    }
+
+    // Composable accepts API as dependency
+    const { user, loading, fetchUser } = useUserData(mockApi)
+
+    expect(loading.value).toBe(false)
+    expect(user.value).toBeNull()
+
+    await fetchUser('1')
+
+    expect(mockApi.getUser).toHaveBeenCalledWith('1')
+    expect(user.value).toEqual({ id: '1', name: 'Test' })
+  })
+
+  it('handles fetch errors', async () => {
+    const mockApi = {
+      getUser: vi.fn().mockRejectedValue(new Error('Not found'))
+    }
+
+    const { error, fetchUser } = useUserData(mockApi)
+
+    await fetchUser('1')
+
+    expect(error.value).toBeInstanceOf(Error)
+    expect(error.value?.message).toBe('Not found')
+  })
+})
+```
+
+---
+
+## Testing Best Practices
+
+| Practice | Reason |
+|----------|--------|
+| Test composables in isolation | Faster, focused tests |
+| Test components with minimal mocking | Verify integration |
+| Test wrappers with API mocks | Isolate side effects |
+| Use provide/inject for DI | Easy mock injection |
+| Test reactive updates | Verify computed reactivity |
+| Avoid snapshot tests for logic | Fragile, hard to review |