cqs-react

name	cqs-react
description	Command Query Separation (CQS) pattern for React Native with TypeScript and Clean Architecture. Use when creating, reviewing, or refactoring Commands (write operations), Queries (read operations), UseCases (complex orchestration), or ReadModels in React Native projects.

CQS for React Native (Clean Architecture)

Core Principle

CQS separates operations into two categories:

• Query: Returns data, never modifies state
• Command: Modifies state, returns minimal data (ID or void)

Quick Reference

Aspect	Query	Command
Return	Data (entity, array...)	void or { id }
State mutation	Never	Always
Side effects	Never	Allowed
Can read internally	Yes	Yes
Can call	Other Queries	Queries + Commands
File extension	.query.ts	.command.ts

Project Structure

modules/[bounded-context]/
├── core/                           # Pure domain (no external dependencies)
│   ├── entities/
│   │   └── User.entity.ts          # Entity (type/interface)
│   ├── errors/
│   │   └── UserError.error.ts      # Domain error classes
│   └── ports/
│       └── UserRepository.port.ts  # Repository Port (read + write)
│
├── application/                    # Application layer (CQS + orchestration)
│   ├── commands/                   # Write operations (mutations)
│   │   └── CreateUser.command.ts
│   ├── queries/                    # Read operations
│   │   └── GetUserById.query.ts
│   └── usecases/                   # Complex multi-step orchestration
│       └── CompleteOnboarding.usecase.ts
│
└── infrastructure/
    ├── adapters/                   # Port implementations
    │   └── UserApi.adapter.ts
    └── ui/
        ├── hooks/                  # React Query hooks
        │   ├── users.queryKeys.ts
        │   ├── useUser.query.ts
        │   └── useCreateUser.mutation.ts
        └── viewModels/
            └── useCreateUser.viewModel.tsx

Layer Dependencies

Infrastructure → Application → Core
      ↓               ↓           ↓
   Adapters       Commands     Entities
   UI/Hooks       Queries      Errors
   ViewModels     UseCases     Ports

Guides

• Commands: See references/commands.md
• Queries: See references/queries.md
• UseCases: See references/usecases.md

Key Rules

1. Ports location: Repository interfaces in core/ports/ — handle both read and write
2. Error handling: Throw typed errors from core/errors/ — React Query handles them
3. Naming: Commands use imperative verbs (Create, Update, Delete), Queries use interrogative (Get, Find, List)
4. UseCases: For multi-step workflows that orchestrate multiple commands/queries
5. File extensions: .command.ts, .query.ts, .usecase.ts