@hexadrop/command

Opinionated package to create and dispatch commands for CQRS applications.

``bash
npm install --save @hexadrop/command
`

Using bun

`bash
bun add @hexadrop/command
`

What it does

This package is an opinionated utility designed to streamline the creation and dispatching
commands in CQRS (Command Query Responsibility Segregation) applications.

It provides a set of abstractions and utilities that allow developers to handle commands in a structured and efficient
way.
Key features include:

- Command Creation: Simplifies the process of creating new commands.
- Command Dispatching: Provides mechanisms to dispatch commands to their respective handlers.
- Command Handler Decorators: Provides decorators to define command handlers.

How to use

First of all define your commands. A command is a simple class that extends the Command class and defines
the properties that will be passed to the command handler.

`typescript
// src/commands/create-user.command.ts
class CreateUserCommand extends Command {
static override COMMAND_NAME = 'user.create';

constructor(
readonly id: string,
readonly name: string,
readonly age: number
) {
super(CreateUserCommand.COMMAND_NAME);
}
}
`

`typescript
// src/commands/delete-user.command.ts
class DeleteUserCommand extends Command {
static override COMMAND_NAME = 'user.delete';

constructor(readonly id: string) {
super(CreateUserCommand.COMMAND_NAME);
}
}
`

Then define your command handlers. A command handler is a simple class that implements the CommandHandler interface

`typescript
// src/handlers/create-user.handler.ts
import Either from '@hexadrop/either';

class CreateUserHandler implements CommandHandler {
constructor(private readonly usersRepository: UsersRepository) {}

async handle(command: CreateUserCommand): Promise> {
const { age, id, name } = command;
await this.usersRepository.create({ age, id, name });

return Either.right();
}
}
`

`typescript
// src/handlers/delete-user.handler.ts
import Either from '@hexadrop/either';

class DeleteUserHandler implements CommandHandler {
constructor(private readonly usersRepository: UsersRepository) {}

async handle(command: DeleteUserCommand): Promise> {
const { id } = command;
await this.usersRepository.delete(id);

return Either.right();
}
}
`

Finally, you can dispatch your commands. To do so you need to create a CommandBus instance and register your command
handlers.

`typescript
// src/index.ts
import CommandBus from '@hexadrop/command/bus';
import SyncCommandBus from '@hexadrop/command/bus/sync';
import InMemoryCommandHandlers from '@hexadrop/command/handlers/memory';

import { CreateUserCommand, DeleteUserCommand } from './commands';
import { CreateUserHandler, DeleteUserHandler } from './handlers';

const usersRepository; // Your users repository

const createUserHandler = new CreateUserHandler(usersRepository);
const deleteUserHandler = new DeleteUserHandler(usersRepository);

const handlers = new InMemoryCommandHandlers();

handlers.register(CreateUserCommand, createUserHandler);
handlers.register(DeleteUserCommand, deleteUserHandler);

const commandBus: CommandBus = new SyncCommandBus(handlers);

commandBus.dispatch(new CreateUserCommand('1', 'John', 30));
commandBus.dispatch(new DeleteUserCommand('1'));
``

Hexadrop Code Quality Standards

Publishing this package we are committing ourselves to the following code quality standards:

- Respect Semantic Versioning: No breaking changes in patch or minor versions
- No surprises in transitive dependencies: Use the bare minimum dependencies needed to meet the purpose
- One specific purpose to meet without having to carry a bunch of unnecessary other utilities
- Tests as documentation and usage examples
- Well documented README showing how to install and use
- License favoring Open Source and collaboration