cqrs

README

Package CQRS

A robust Command Query Responsibility Segregation (CQRS) mediator for Go 1.25+.

Key Features

• Decoupled Handlers: Leverages the di package for lifecycle management.
• Auto-Coercion: Automatically handles pointer/value mismatches between dispatchers and handlers.
• Type Safe: Returns precise types using Go Generics.
• High Performance: RWMutex protected registry with optimized reflection lookups.

Usage

1. Define your Query and Result

type GetUserQuery struct { ID string }
type User struct { Name string }

2. Create the Handler

The handler must implement the IQueryHandler interface.

type UserHandler struct {}

var _ cqrs.IQueryHandler[GetUserQuery, *User] = (*UserHandler)(nil)

func (h *UserHandler) Handle(ctx context.Context, q GetUserQuery) (*User, error) {
    return &User{Name: "Leandro Luk"}, nil
}

3. Register with DI Factory

Register the handler specifying the Message, the Result, and the Handler Type.

cqrs.RegisterQueryHandler[GetUserQuery, *User, *UserHandler](func() *UserHandler {
    return &UserHandler{}
})

4. Dispatch

You can send the query as a value or a pointer; the engine will coerce it automatically.

user, err := cqrs.ExecuteQuery[*User](ctx, GetUserQuery{ID: "123"})

Technical Design

• Normalization: The registry normalizes types to ensure that T and *T resolve to the same handler.
• Coercion Engine: Before execution, the engine checks if the provided message matches the handler's input, performing pointer indirection or address-of operations if necessary.
• DI Integration: Handlers are retrieved from the di container, allowing them to have their own dependencies (repositories, clients, etc.) injected at construction time.

Installation

go get github.com/leandroluk/gox/cqrs

Documentation

Index

• func ExecuteCommand[TResult any](ctx context.Context, command any) (TResult, error)
• func ExecuteQuery[TResult any](ctx context.Context, query any) (TResult, error)
• func RegisterCommandHandler[TCommand any, TResult any, THandler ICommandHandler[TCommand, TResult]](factoryFN func() (THandler, error))
• func RegisterQueryHandler[TQuery any, TResult any, THandler IQueryHandler[TQuery, TResult]](factoryFN func() (THandler, error))
• type ICommandHandler
• type IQueryHandler

Functions

func ExecuteCommand

func ExecuteCommand[TResult any](ctx context.Context, command any) (TResult, error)

func ExecuteQuery

func ExecuteQuery[TResult any](ctx context.Context, query any) (TResult, error)

func RegisterCommandHandler

func RegisterCommandHandler[TCommand any, TResult any, THandler ICommandHandler[TCommand, TResult]](factoryFN func() (THandler, error))

func RegisterQueryHandler

func RegisterQueryHandler[TQuery any, TResult any, THandler IQueryHandler[TQuery, TResult]](factoryFN func() (THandler, error))

Types

type ICommandHandler

type ICommandHandler[TCommand any, TResult any] interface {
	Handle(ctx context.Context, command TCommand) (TResult, error)
}

type IQueryHandler

type IQueryHandler[TQuery any, TResult any] interface {
	Handle(ctx context.Context, query TQuery) (TResult, error)
}