cqrs

README

cqrs

Description

CQRS is a library that provides an implementation of the Command Query Responsibility Segregation (CQRS) pattern for Go. It aims to help you create clean, modular, and scalable applications by separating the read and write concerns of your domain.

Stable and Unstable Components

The library is currently considered unstable as it hasn't reached v1.0.0 yet. However, it consists of both stable and unstable components. The stable components are less likely to have their API changed, while the unstable components are still under active development and might have breaking changes in the future. The unstable components can be found under the x/ directory. Keep in mind that the whole library is under development, and it is recommended to always check the latest changes and updates before using it in your projects.

Installation

To install the library, use the following command:

go get github.com/screwyprof/cqrs

Quick Example

One of the stable components is the aggregate package, which provides a way to create event-sourced aggregates. An aggregate is a domain object that processes commands and produces events as a result. Event sourcing means that the aggregate's state is derived from its event history.

To use the aggregate package, you'll need to define your own identifier and event types. The package provides a FromAggregate function to convert your domain aggregate into an event-sourced aggregate.

A runnable example demonstrating the usage of the aggregate package can be found in the example_test.go file within the aggregate package. This example showcases how to define your own domain aggregate, commands, and events, and how to process commands and apply events using the event-sourced aggregate. More examples can be found in the the examples directory.

Documentation

Full documentation can be found on GoDoc.

Contributing

Contributions are welcome! If you have any suggestions, bug reports, or feature requests, please open a new issue or submit a pull request.

License

The Interactor Library is released under the MIT License.

Credits

This project was highly inspired by the following projects:

• https://github.com/gregoryyoung/m-r/blob/master/SimpleCQRS/Domain.cs
• https://github.com/MarkNijhof/Fohjin/tree/master/Fohjin.DDD.Example
• https://github.com/edumentab/cqrs-starter-kit/tree/master/sample-app
• https://github.com/jankronquist/rock-paper-scissors-in-java

Documentation

Index

• type Aggregate
• type AggregateFactory
• type Command
• type CommandHandler
• type CommandHandlerFunc
• type DomainEvent
• type ESAggregate
• type EventApplier
• type EventApplierFunc
• type EventMatcher
  • func MatchAnyEventOf(types ...string) EventMatcher
  • func MatchEvent(t string) EventMatcher
• type FactoryFn
• type Identifier
• type Versionable

Types

type Aggregate

type Aggregate interface {
	AggregateID() Identifier
	AggregateType() string
}

Aggregate represents a cluster of related objects that can be treated as a single unit.

This basic interface is intended for simple aggregates that may not follow CQRS or event sourcing patterns.

type AggregateFactory

type AggregateFactory interface {
	RegisterAggregate(aggregateType string, factory FactoryFn)
	CreateAggregate(aggregateType string, ID Identifier) (ESAggregate, error)
}

AggregateFactory is responsible for creating aggregates. It registers aggregate factory functions and creates aggregates based on a given aggregate type and identifier.

type Command

type Command interface {
	AggregateID() Identifier
	AggregateType() string
	CommandType() string
}

Command is sent to the domain to change the state of an aggregate.

Commands are named with a verb in the imperative mood, e.g., ConfirmOrder.

type CommandHandler

type CommandHandler interface {
	Handle(c Command) ([]DomainEvent, error)
}

CommandHandler is responsible for executing commands.

It processes a command, produces relevant domain events.

It returns a list of domain events on success It returns an error if the command cannot be executed.

type CommandHandlerFunc

type CommandHandlerFunc func(Command) ([]DomainEvent, error)

CommandHandlerFunc is a function type that can be used as a command handler.

type DomainEvent

type DomainEvent interface {
	EventType() string
}

DomainEvent represents an event that has occurred in the domain.

Events are named with a past-participle verb, e.g., OrderConfirmed.

type ESAggregate

type ESAggregate interface {
	Aggregate
	Versionable
	CommandHandler
	EventApplier
}

ESAggregate represents an aggregate that is designed with CQRS and event sourcing in mind.

It extends the basic Aggregate interface and includes additional responsibilities such as command handling, event application, and versioning.

type EventApplier

type EventApplier interface {
	Apply(e ...DomainEvent) error
}

EventApplier is responsible for applying domain events to an aggregate.

type EventApplierFunc

type EventApplierFunc func(DomainEvent)

EventApplierFunc is a function type that can be used as an event applier.

type EventMatcher

type EventMatcher func(DomainEvent) bool

EventMatcher is a func that can match event to a criteria.

func MatchAnyEventOf

func MatchAnyEventOf(types ...string) EventMatcher

MatchAnyEventOf matches if any of several matchers matches.

func MatchEvent

func MatchEvent(t string) EventMatcher

MatchEvent matches a specific event type, nil events never match.

type FactoryFn

type FactoryFn func(Identifier) ESAggregate

FactoryFn is a function type for an aggregate factory function.

type Identifier

type Identifier = fmt.Stringer

Identifier represents an aggregate identifier.

type Versionable

type Versionable interface {
	Version() int
}

Versionable indicates that an object can support different versions.