Overview

The QueryManager class provides comprehensive CRUD operations with advanced features like optimistic updates and automatic cache management. It internally uses two important classes: QueryKeys for managing React Query keys and cache operations, and Mutations for handling cache mutations and optimistic updates.

When QueryManager is the right fit

Use QueryManager when the feature is a real resource with identity and CRUD-style behavior.

Strong signs:

• you have list and retrieve flows for the same resource
• create, update, or delete should stay aligned with cached list and detail data
• pagination or infinite scroll matters
• optimistic CRUD behavior is useful

Avoid using QueryManager when the backend endpoint is really an action or one-off query rather than a resource lifecycle.

Those cases are usually better modeled with QueryOperations.

Relationship with QueryOperations

QueryManager and QueryOperations are complementary.

A common pattern is:

• one manager owns the resource CRUD flows
• operations define custom actions beside that resource
• the manager still helps with cache coordination through queryKeys and mutations

Architecture Overview

QueryManager
├── QueryKeys - Manages query keys and cache operations
├── Mutations - Handles cache mutations and optimistic updates
└── Hooks - Provides React hooks for CRUD operations

Core Concepts

QueryItem

All data items must extend the QueryItem interface:

interface QueryItem {
  id: string | number
}

// Example implementation
interface User extends QueryItem {
  id: string
  name: string
  email: string
  status: 'active' | 'inactive'
  createdAt: string
}

Filter Types

Define filter interfaces for list queries:

interface UserFilters {
  status?: 'active' | 'inactive'
  search?: string
  role?: string
}