esja

README

esja

EventSourcing library in Go.

Warning: Unstable API!

This project is work in progress and the public API can change until the v1.0.0 is released.

Documentation

Index

• func NewEntity[T Entity[T]](id string, eventsSlice []VersionedEvent[T]) (*T, error)
• type Entity
• type Event
• type Stream
  • func NewStream[T any](id string) (*Stream[T], error)
  • func NewStreamWithType[T any](id string, streamType string) (*Stream[T], error)
  • func (s *Stream[T]) HasEvents() bool
  • func (s *Stream[T]) ID() string
  • func (s *Stream[T]) PopEvents() []VersionedEvent[T]
  • func (s *Stream[T]) Record(entity *T, event Event[T]) error
  • func (s *Stream[T]) Type() string
• type VersionedEvent

Functions

func NewEntity

func NewEntity[T Entity[T]](id string, eventsSlice []VersionedEvent[T]) (*T, error)

NewEntity instantiates a new T with the given events applied to it. At the same time the entity's internal Stream is initialised, so it can record new upcoming stream.

Types

type Entity

type Entity[T any] interface {
	// Stream exposes a pointer to the internal entity's Stream.
	Stream() *Stream[T]

	// NewWithStream returns a new instance of T
	// with the provided Stream queue injected.
	NewWithStream(*Stream[T]) *T
}

Entity represents the event-sourced type saved and loaded by the event store. In DDD terms, it is the "aggregate root".

In order for your domain type to implement Entity:

• Keep *Stream in a field.
• Implement the interface methods in accordance with its description.

Then an EventStore will be able to store and load it.

Example:

type User struct {
    stream *esja.Stream[User]
    id     string
}

func (u User) Stream() *esja.Stream[User] {
    return u.stream
}

func (u User) NewWithStream(stream *esja.Stream[User]) *User {
	return &User{stream: stream}
}

type Event

type Event[T any] interface {
	// EventName should identify the event and the version of its schema.
	//
	// Example:
	//
	// 	func (e FooCreated) EventName() string {
	// 		return "FooCreated_v1"
	// 	}
	EventName() string

	// ApplyTo applies the event to the entity.
	ApplyTo(*T) error
}

type Stream

type Stream[T any] struct {
	// contains filtered or unexported fields
}

Stream represents a queue of events and basic stream properties.

func NewStream

func NewStream[T any](id string) (*Stream[T], error)

NewStream creates a new instance of a Stream with provided ID.

func NewStreamWithType

func NewStreamWithType[T any](id string, streamType string) (*Stream[T], error)

NewStreamWithType creates a new instance of a Stream with provided ID and custom type.

func (*Stream[T]) HasEvents

func (s *Stream[T]) HasEvents() bool

HasEvents returns true if there are any queued stream.

func (*Stream[T]) ID

func (s *Stream[T]) ID() string

func (*Stream[T]) PopEvents

func (s *Stream[T]) PopEvents() []VersionedEvent[T]

PopEvents returns the slice of queued VersionedEvents and clears it.

func (*Stream[T]) Record

func (s *Stream[T]) Record(entity *T, event Event[T]) error

Record applies the provided Event to the entity and puts it into the stream's event queue as a next VersionedEvent.

func (*Stream[T]) Type

func (s *Stream[T]) Type() string

type VersionedEvent

type VersionedEvent[T any] struct {
	Event[T]
	StreamVersion int
}

VersionedEvent is an event with a corresponding stream version.