Align Command, Query, Operation, and Action naming

[patroza]

Context

We currently have two concepts named Command:

• API/application commands: the write side of the API, paired with Query, broadly following CQRS.
• Frontend/UI command pattern: user-triggered capabilities such as buttons, menu entries, command palette items, keyboard-triggered flows, loading state, confirmation, toasts, follow-up side effects, etc.

The duplicate name makes the architecture harder to talk about. Command can mean either a resource/API write request or a user-facing UI capability depending on layer.

We also used Action as an umbrella word inside resource files for things that can be either queries or commands. That now collides with the better frontend name for user-triggered capabilities.

Decision direction

Keep Command for the API/application boundary:

• Query = read-side request.
• Command = write-side/application intent.
• This remains valid CQRS language even though we do not require event sourcing or eventual consistency.
• Other ecosystems often call write operations Mutation (TanStack Query, Apollo, GraphQL), but that is not our resource vocabulary.

Rename the frontend command-pattern concept to Action:

• Action = something the user can do from the UI.
• An action may orchestrate one or more resource operations, read queries, perform navigation, analytics, local UI state updates, optimistic UI, confirmation, toast handling, cache invalidation, etc.
• This avoids implying a 1:1 mapping between UI affordances and backend commands.

Use Operation as the resource/API umbrella:

• Operation = something exposed by a resource.
• A resource operation is either a Query or a Command.
• This replaces resource-level Action naming.

Working mental model:

User runs an Action.
An Action may orchestrate one or more resource Operations.
A resource Operation is either a Query or a Command.
Views read via Queries.
Writes/application intents go through Commands.

Short version:

Actions invoke operations.
Operations are queries or commands.

Naming guidelines

Use these terms by layer:

• UI/frontend capability: Action.
• Resource/API umbrella: Operation, or ResourceOperation in exported/shared APIs when extra scope helps.
• API/application write request: Command.
• API/application read request: Query.

Avoid these terms:

• UiAction as the default frontend name. Use plain Action inside frontend/UI packages.
• ResourceAction for resource query/command definitions. Use Operation / ResourceOperation instead.
• Action as a resource umbrella.
• Mutation as our resource write-operation name. Mention it only when comparing to external ecosystems.

Example derived frontend names:

• Action
• ActionGroup
• ActionId
• ActionContext
• ActionHandler
• ActionResult
• ActionState
• ActionRegistry
• useActions

Example derived resource/API names:

• Operation
• ResourceOperation
• OperationKind
• operationName
• operations
• queries
• commands

Possible resource shape:

const operations = {
  queries: {
    Get,
    List
  },
  commands: {
    Create,
    Update,
    Delete
  }
}

Plan

1. Audit current frontend Command types, helpers, docs, tests, and examples.
2. Audit resource-level Action naming used as an umbrella for queries and commands.
3. Separate UI command-pattern names from API/resource command names.
4. Rename UI concepts from Command* to Action* where they model user capabilities/workflows.
5. Rename resource umbrella concepts from Action* to Operation* where they model query/command definitions.
6. Keep API/resource Command and Query terminology intact.
7. Update docs to explain the layer split and the orchestration relationship.
8. Add compatibility aliases only if needed for migration, with a clear removal path.
9. Include changesets for public package/API changes.

Acceptance criteria

• No layer has two competing meanings for Command.
• API/resource docs consistently use Query / Command for operation kinds.
• Resource docs consistently use Operation / ResourceOperation as the query-or-command umbrella.
• Frontend/UI docs consistently use Action for user-triggered capabilities.
• Examples show that an Action may compose multiple operations, queries, commands, and side effects.
• Public exports either use the new names or provide explicitly documented deprecated aliases.