Application

Introduction

The Application module provides the tools you need to define and execute application use cases with CQRS and pipeline behaviors.

Use this section when you need to:

• create a command;
• create a query;
• create a handler;
• validate commands or queries;
• add logging around application requests;
• monitor execution performance;
• add idempotency to commands;
• configure concurrency retries;
• enable query processing features such as caching;
• handle exceptions consistently.

Before you start

Application features are configured through AppBuilder.

Enable the application pipeline with:

const app = new AppBuilder()
  .addPipeline()

You can provide additional configuration when a feature requires it:

const app = new AppBuilder()
  .addPipeline((config) => {
    // Configure CQRS and pipeline features here.
  })

Build the application after configuring the required modules:

const container = await app.build()

The exact configuration depends on the feature you want to use. Each feature page documents its required configuration and prerequisites.

Create a command

To create a command, see:

Create a Command

The guide covers:

• defining the command;
• defining its input;
• adding validation;
• sending the command;
• connecting it to a handler.

Create a query

To create a query, see:

Create a Query

The guide covers:

• defining the query;
• defining its parameters;
• adding validation;
• executing the query;
• connecting it to a handler.

Create a handler

To implement the application logic for a command or query, see:

Create a Handler

The guide covers:

• extending BaseHandler;
• implementing the handler method;
• receiving dependencies;
• accessing the current user context when required;
• registering the handler;
• connecting the handler to its command or query.

Pipelines

Pipeline behaviors let you add cross-cutting behavior to commands and queries without putting that behavior directly into every handler.

Choose the feature you need:

Task	Documentation
Handle application exceptions	Exception Pipeline
Add request logging	Logging Pipeline
Monitor execution time	Performance Pipeline
Validate commands and queries	Validation Pipeline
Prevent duplicate command processing	Idempotency Pipeline
Retry concurrency conflicts	Concurrency Pipeline
Enable query caching	Caching Pipeline

Validation

If you need to validate a command or query before its handler runs:

Enable Validation

The validation guide explains:

• how to configure validation in AppBuilder;
• how to use Zod schemas;
• where to define schemas;
• how to configure custom validation;
• what happens when validation fails.

For the command and query definitions used by the examples, see:

• Create a Command
• Create a Query

Logging

To configure logging around command and query execution:

Configure Logging

Performance

To monitor command and query execution time:

Configure Performance Tracking

Idempotency

To prevent duplicate processing of commands:

Configure Idempotency

Concurrency

To configure concurrency retries for commands:

Configure Concurrency

Caching

To enable query caching:

Enable Caching

Exception handling

To configure or troubleshoot exception handling for application requests:

Configure Exception Handling

CQRS

Use the CQRS section when you are creating application requests and their handlers.

Task	Documentation
Understand the CQRS workflow	CQRS Overview
Create a command	Create a Command
Create a query	Create a Query
Create a handler	Create a Handler

Typical workflow

A typical application use case follows this path:

Create Command or Query
        │
        ▼
Add input validation if required
        │
        ▼
Create the Handler
        │
        ▼
Register the Handler
        │
        ▼
Configure required pipelines
        │
        ▼
Execute the Command or Query

For example, when creating a new command:

Create Command
      │
      ├── Add validation
      │      └── Validation Pipeline
      │
      └── Create Handler
             └── Register Handler

The individual guides contain the implementation details required for each step.

Where should I start?

Use the task that matches what you are trying to do:

• I need a command → Create a Command
• I need a query → Create a Query
• I need a handler → Create a Handler
• I need validation → Validation Pipeline
• I need logging → Logging Pipeline
• I need performance tracking → Performance Pipeline
• I need idempotency → Idempotency Pipeline
• I need concurrency retries → Concurrency Pipeline
• I need caching → Caching Pipeline
• I need exception handling → Exception Pipeline

Troubleshooting

If a command or query does not execute as expected, check:

1. addPipeline() has been configured on the AppBuilder;
2. the required pipeline configuration is enabled;
3. the command or query is connected to a handler;
4. the handler is registered in the application;
5. the request is executed through the configured mediator;
6. any feature-specific prerequisites documented in the relevant pipeline guide are satisfied.

If the problem is specific to a feature, start from its dedicated guide rather than troubleshooting the entire Application module.

Related documentation

• Create a Command
• Create a Query
• Create a Handler
• CQRS Overview
• Exception Pipeline
• Performance Pipeline
• Logging Pipeline
• Validation Pipeline
• Idempotency Pipeline
• Concurrency Pipeline
• Caching Pipeline

---

Support Us

Xeno.JS is an MIT-licensed open source project. It can grow thanks to the support of these awesome people. If you’d like to join them, please read more at support section