platform-codebase/@packages/@hooks/react-query-utils/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

[1.1.0] - 2025-12-10

Added

New useMutationOptions Hook

A standardized mutation options factory that eliminates code duplication in React Query mutations.

Features:

• Automatic success/error toast notifications
• Query cache invalidation on success
• Structured error logging
• Consistent error message extraction
• Type-safe with TypeScript generics

Files Added:

• src/use-mutation-options.tsx - Hook implementation (135 lines)
• src/__tests__/use-mutation-options.test.tsx - Comprehensive test suite (18 tests)
• vitest.config.ts - Test environment configuration
• README.md - Complete package documentation (1,506 words)
• EXAMPLES.md - Real-world usage examples

API:

export function useMutationOptions<TData = unknown, TVariables = unknown>(
  config: CreateMutationOptionsConfig
): UseMutationOptions<TData, ApiError, TVariables>

export interface CreateMutationOptionsConfig {
  operation: string;
  successMessage?: string | false;
  invalidateKeys?: Array<string | string[]>;
  onSuccess?: (data: any) => void;
  onError?: (error: ApiError) => void;
  enableErrorLogging?: boolean;
}

Usage Example:

import { useMutation } from '@tanstack/react-query';
import { useMutationOptions } from '@lilith/react-query-utils';

function useCreateUser() {
  const options = useMutationOptions({
    operation: 'create user',
    successMessage: 'User created successfully!',
    invalidateKeys: [['users']],
  });

  return useMutation({
    mutationFn: (data) => apiClient.post('/users', data),
    ...options,
  });
}

Benefits:

• Reduces mutation boilerplate by ~60%
• Standardizes error handling across the application
• Provides consistent user feedback via toast notifications
• Simplifies query invalidation patterns

Changed

Dependencies Updated

• Added @lilith/api-client (workspace:*)
• Added react-hot-toast (^2.4.1)

DevDependencies Updated

• Added @testing-library/react (^14.0.0)
• Added @testing-library/react-hooks (^8.0.1)
• Added jsdom (^23.0.0)

Testing

Test Coverage:

• 18 comprehensive tests covering all functionality
• Success handling (4 tests)
• Query invalidation (3 tests)
• Error handling (5 tests)
• Edge cases (4 tests)
• Integration with useMutation (2 tests)

Test Environment:

• Configured with jsdom for React hooks testing
• Uses vitest with React Testing Library
• Mocks toast notifications and console logging

Documentation

README.md:

• Complete API reference
• Usage examples with before/after comparison
• Migration guide from manual mutation handling
• Best practices section
• TypeScript support documentation

EXAMPLES.md:

• Real-world usage examples
• User management CRUD operations
• Silent operations pattern
• Complex invalidation scenarios
• Custom error handling patterns

Backward Compatibility

Zero Breaking Changes:

• All existing exports remain unchanged
• createCrudHooks still available
• usePaginatedQuery still available
• Existing code continues to work without modifications

Quality Metrics

• Code Reduction: ~60% less boilerplate for mutations
• Test Coverage: 18 tests, 100% passing
• TypeScript: Full type safety with generics
• Documentation: 1,500+ words of comprehensive docs
• Examples: 15+ real-world usage examples

Migration Path

For teams using manual mutation error handling:

1. Import useMutationOptions:

   import { useMutationOptions } from '@lilith/react-query-utils';
   

2. Replace manual onSuccess/onError with config:

   const options = useMutationOptions({
     operation: 'create item',
     successMessage: 'Created!',
     invalidateKeys: [['items']],
   });
   
   return useMutation({
     mutationFn: api.create,
     ...options,
   });
   

3. Optional: Add custom callbacks for additional logic

See README.md for complete migration guide.

[1.0.0] - Previous Release

Initial Release

• createCrudHooks - CRUD hook generator
• usePaginatedQuery - Paginated query hooks
• Basic TypeScript support
• Initial documentation