feat: add generic batching utilities for API mutations

- Add useBatchedMutation hook with TanStack-style API
- Add generic batchProcessor helpers (splitIntoBatches, processBatches)
- Hook wraps any mutation to transparently handle API batch limits
- Works by passing mutation function and calling with array
- Comprehensive test coverage (23 tests)
- Documentation with usage examples

Author: jeffredodd

src/helpers/batchProcessor.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect, vi } from 'vitest'
+import { splitIntoBatches, processBatches, DEFAULT_BATCH_SIZE } from './batchProcessor'
+
+describe('batchProcessor', () => {
+  describe('splitIntoBatches', () => {
+    it('returns empty array when given empty array', () => {
+      const result = splitIntoBatches([])
+      expect(result).toEqual([])
+    })
+
+    it('returns single batch when items length is less than batch size', () => {
+      const items = Array.from({ length: 50 }, (_, i) => i)
+      const result = splitIntoBatches(items)
+
+      expect(result).toHaveLength(1)
+      expect(result[0]).toHaveLength(50)
+    })
+
+    it('returns single batch when items length equals batch size', () => {
+      const items = Array.from({ length: 100 }, (_, i) => i)
+      const result = splitIntoBatches(items)
+
+      expect(result).toHaveLength(1)
+      expect(result[0]).toHaveLength(100)
+    })
+
+    it('splits items into multiple batches when length exceeds batch size', () => {
+      const items = Array.from({ length: 150 }, (_, i) => i)
+      const result = splitIntoBatches(items)
+
+      expect(result).toHaveLength(2)
+      expect(result[0]).toHaveLength(100)
+      expect(result[1]).toHaveLength(50)
+    })
+
+    it('splits items into exact batches when length is multiple of batch size', () => {
+      const items = Array.from({ length: 200 }, (_, i) => i)
+      const result = splitIntoBatches(items)
+
+      expect(result).toHaveLength(2)
+      expect(result[0]).toHaveLength(100)
+      expect(result[1]).toHaveLength(100)
+    })
+
+    it('handles custom batch sizes', () => {
+      const items = Array.from({ length: 75 }, (_, i) => i)
+      const result = splitIntoBatches(items, 25)
+
+      expect(result).toHaveLength(3)
+      expect(result[0]).toHaveLength(25)
+      expect(result[1]).toHaveLength(25)
+      expect(result[2]).toHaveLength(25)
+    })
+
+    it('throws error when batch size is zero', () => {
+      expect(() => splitIntoBatches([1, 2, 3], 0)).toThrow('Batch size must be greater than 0')
+    })
+
+    it('throws error when batch size is negative', () => {
+      expect(() => splitIntoBatches([1, 2, 3], -1)).toThrow('Batch size must be greater than 0')
+    })
+
+    it('preserves item order in batches', () => {
+      const items = [1, 2, 3, 4, 5]
+      const result = splitIntoBatches(items, 2)
+
+      expect(result).toEqual([[1, 2], [3, 4], [5]])
+    })
+  })
+
+  describe('processBatches', () => {
+    it('processes empty array', async () => {
+      const processFn = vi.fn().mockResolvedValue('result')
+      const result = await processBatches([], processFn)
+
+      expect(result).toEqual([])
+      expect(processFn).not.toHaveBeenCalled()
+    })
+
+    it('processes single batch when items length is less than batch size', async () => {
+      const items = Array.from({ length: 50 }, (_, i) => i)
+      const processFn = vi.fn().mockResolvedValue('result')
+
+      await processBatches(items, processFn)
+
+      expect(processFn).toHaveBeenCalledTimes(1)
+      expect(processFn).toHaveBeenCalledWith(items)
+    })
+
+    it('processes single batch when items length equals batch size', async () => {
+      const items = Array.from({ length: 100 }, (_, i) => i)
+      const processFn = vi.fn().mockResolvedValue('result')
+
+      await processBatches(items, processFn)
+
+      expect(processFn).toHaveBeenCalledTimes(1)
+      expect(processFn).toHaveBeenCalledWith(items)
+    })
+
+    it('processes multiple batches when items length exceeds batch size', async () => {
+      const items = Array.from({ length: 150 }, (_, i) => i)
+      const processFn = vi.fn().mockResolvedValue('result')
+
+      await processBatches(items, processFn)
+
+      expect(processFn).toHaveBeenCalledTimes(2)
+      expect(processFn).toHaveBeenNthCalledWith(1, items.slice(0, 100))
+      expect(processFn).toHaveBeenNthCalledWith(2, items.slice(100, 150))
+    })
+
+    it('returns results from all batch processing calls', async () => {
+      const items = Array.from({ length: 150 }, (_, i) => i)
+      const processFn = vi
+        .fn()
+        .mockResolvedValueOnce({ batch: 1 })
+        .mockResolvedValueOnce({ batch: 2 })
+
+      const result = await processBatches(items, processFn)
+
+      expect(result).toEqual([{ batch: 1 }, { batch: 2 }])
+    })
+
+    it('processes batches sequentially', async () => {
+      const items = Array.from({ length: 150 }, (_, i) => i)
+      const callOrder: number[] = []
+
+      const processFn = vi.fn().mockImplementation(async (batch: number[]) => {
+        const firstItem = batch[0]
+        if (firstItem !== undefined) {
+          callOrder.push(firstItem)
+        }
+        return `batch-${firstItem}`
+      })
+
+      await processBatches(items, processFn)
+
+      expect(callOrder).toEqual([0, 100])
+    })
+
+    it('uses custom batch size', async () => {
+      const items = Array.from({ length: 75 }, (_, i) => i)
+      const processFn = vi.fn().mockResolvedValue('result')
+
+      await processBatches(items, processFn, 25)
+
+      expect(processFn).toHaveBeenCalledTimes(3)
+    })
+
+    it('propagates errors from processing function', async () => {
+      const items = Array.from({ length: 150 }, (_, i) => i)
+      const processFn = vi.fn().mockRejectedValue(new Error('Processing failed'))
+
+      await expect(processBatches(items, processFn)).rejects.toThrow('Processing failed')
+    })
+
+    it('uses DEFAULT_BATCH_SIZE when batch size is not specified', async () => {
+      const items = Array.from({ length: 150 }, (_, i) => i)
+      const processFn = vi.fn().mockResolvedValue('result')
+
+      await processBatches(items, processFn)
+
+      expect(processFn).toHaveBeenCalledTimes(2)
+      const firstBatch = items.slice(0, DEFAULT_BATCH_SIZE)
+      expect(processFn).toHaveBeenNthCalledWith(1, expect.arrayContaining(firstBatch))
+    })
+  })
+})

src/helpers/batchProcessor.ts

@@ -0,0 +1,34 @@
+export const DEFAULT_BATCH_SIZE = 100
+
+export function splitIntoBatches<T>(items: T[], batchSize: number = DEFAULT_BATCH_SIZE): T[][] {
+  if (batchSize <= 0) {
+    throw new Error('Batch size must be greater than 0')
+  }
+
+  if (items.length === 0) {
+    return []
+  }
+
+  const batches: T[][] = []
+  for (let i = 0; i < items.length; i += batchSize) {
+    batches.push(items.slice(i, i + batchSize))
+  }
+
+  return batches
+}
+
+export async function processBatches<T, R>(
+  items: T[],
+  processFn: (batch: T[]) => Promise<R>,
+  batchSize: number = DEFAULT_BATCH_SIZE,
+): Promise<R[]> {
+  const batches = splitIntoBatches(items, batchSize)
+  const results: R[] = []
+
+  for (const batch of batches) {
+    const result = await processFn(batch)
+    results.push(result)
+  }
+
+  return results
+}

src/hooks/useBatchedMutation.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { useBatchedMutation } from './useBatchedMutation'
+
+interface TestItem {
+  id: string
+  value: number
+}
+
+describe('useBatchedMutation', () => {
+  const mockMutationFn = vi.fn()
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('integrates with processBatches to batch items correctly', async () => {
+    const items: TestItem[] = Array.from({ length: 150 }, (_, i) => ({
+      id: `item-${i}`,
+      value: i,
+    }))
+    mockMutationFn
+      .mockResolvedValueOnce({ success: true, processedCount: 100 })
+      .mockResolvedValueOnce({ success: true, processedCount: 50 })
+
+    const { result } = renderHook(() =>
+      useBatchedMutation((batch: TestItem[]) => mockMutationFn(batch)),
+    )
+
+    let response: Awaited<ReturnType<typeof result.current.mutateAsync>> | undefined
+    await act(async () => {
+      response = await result.current.mutateAsync(items)
+    })
+
+    expect(mockMutationFn).toHaveBeenCalledTimes(2)
+    expect(response).toHaveLength(2)
+    expect(response?.[0]).toEqual({ success: true, processedCount: 100 })
+    expect(response?.[1]).toEqual({ success: true, processedCount: 50 })
+  })
+
+  it('sets isPending to true during mutation and false after completion', async () => {
+    const items: TestItem[] = Array.from({ length: 50 }, (_, i) => ({
+      id: `item-${i}`,
+      value: i,
+    }))
+
+    let resolveMutation: (value: unknown) => void
+    const mutationPromise = new Promise(resolve => {
+      resolveMutation = resolve
+    })
+    mockMutationFn.mockReturnValue(mutationPromise)
+
+    const { result } = renderHook(() =>
+      useBatchedMutation((batch: TestItem[]) => mockMutationFn(batch)),
+    )
+
+    expect(result.current.isPending).toBe(false)
+
+    let mutatePromise: Promise<unknown>
+    act(() => {
+      mutatePromise = result.current.mutateAsync(items)
+    })
+
+    await waitFor(() => {
+      expect(result.current.isPending).toBe(true)
+    })
+
+    await act(async () => {
+      resolveMutation!({ success: true })
+      await mutatePromise
+    })
+
+    await waitFor(() => {
+      expect(result.current.isPending).toBe(false)
+    })
+  })
+
+  it('sets isPending to false after mutation error', async () => {
+    const items: TestItem[] = Array.from({ length: 50 }, (_, i) => ({
+      id: `item-${i}`,
+      value: i,
+    }))
+    mockMutationFn.mockRejectedValue(new Error('API error'))
+
+    const { result } = renderHook(() =>
+      useBatchedMutation((batch: TestItem[]) => mockMutationFn(batch)),
+    )
+
+    await act(async () => {
+      await expect(result.current.mutateAsync(items)).rejects.toThrow('API error')
+    })
+
+    expect(result.current.isPending).toBe(false)
+  })
+
+  it('propagates errors from mutation function', async () => {
+    const items: TestItem[] = Array.from({ length: 50 }, (_, i) => ({
+      id: `item-${i}`,
+      value: i,
+    }))
+    mockMutationFn.mockRejectedValue(new Error('Network error'))
+
+    const { result } = renderHook(() =>
+      useBatchedMutation((batch: TestItem[]) => mockMutationFn(batch)),
+    )
+
+    await act(async () => {
+      await expect(result.current.mutateAsync(items)).rejects.toThrow('Network error')
+    })
+  })
+
+  it('handles empty items array', async () => {
+    const { result } = renderHook(() =>
+      useBatchedMutation((batch: TestItem[]) => mockMutationFn(batch)),
+    )
+
+    let response: Awaited<ReturnType<typeof result.current.mutateAsync>> | undefined
+    await act(async () => {
+      response = await result.current.mutateAsync([])
+    })
+
+    expect(mockMutationFn).not.toHaveBeenCalled()
+    expect(response).toEqual([])
+  })
+})

src/hooks/useBatchedMutation.ts

@@ -0,0 +1,37 @@
+import { useState, useCallback } from 'react'
+import { processBatches, DEFAULT_BATCH_SIZE } from '@/helpers/batchProcessor'
+
+interface UseBatchedMutationOptions {
+  batchSize?: number
+}
+
+interface UseBatchedMutationResult<TItem, TResponse> {
+  mutateAsync: (items: TItem[]) => Promise<TResponse[]>
+  isPending: boolean
+}
+
+export function useBatchedMutation<TItem, TResponse>(
+  mutationFn: (batch: TItem[]) => Promise<TResponse>,
+  options?: UseBatchedMutationOptions,
+): UseBatchedMutationResult<TItem, TResponse> {
+  const batchSize = options?.batchSize ?? DEFAULT_BATCH_SIZE
+  const [isPending, setIsPending] = useState(false)
+
+  const mutateAsync = useCallback(
+    async (items: TItem[]): Promise<TResponse[]> => {
+      setIsPending(true)
+
+      try {
+        return await processBatches(items, mutationFn, batchSize)
+      } finally {
+        setIsPending(false)
+      }
+    },
+    [mutationFn, batchSize],
+  )
+
+  return {
+    mutateAsync,
+    isPending,
+  }
+}