eventually

README

Eventually

Eventually provides a flexible event handling library that enables applications to react to various types of events dynamically. The core functionality revolves around defining, publishing, and handling events.

Usage

Setup Publisher

var pub eventually.Publisher // either eventually.PubMux or eventually.Recorder
ctx = eventually.ContextWithPub(context.Background(), pub)

We put Publisher inside the context.Context so it can be Publish anywhere as long as the context pass through the caller.

Define Event

type OrderCompleted struct {
    OrderId string
}

Event was defined as struct. The struct can have any fields that represent the event data.

Publish Event

eventually.Publish(ctx, OrderCompleted{
    OrderID: "123",
})

Publish event using Publisher available in the context. If there is no Publisher in the context, it will do nothing.

Handling Events

There are 2 way to hanlding event, is by using PubMux or Recorder.

PubMux

PubMux is a multiplexer that can handle event based on it's type.

// Setup PubMux
mux := new(eventually.PubMux)
ctx = eventually.ContextWithPub(context.Background(), mux)

// Listen and handle the event
mux.React(func(e OrderCompleted) {
    fmt.Printf("Order completed: %q\n", e.OrderID)
})

// Publish event
eventually.Publish(ctx, OrderCompleted{
    OrderID: "123",
})

It will handle all events that match the OrderCompleted type.

Recorder

Recorder records the published events.

// Setup Recorder
var rec := new(eventually.Recorder)
ctx := eventually.ContextWithPub(context.Background(), rec)

// Publish event
eventually.Publish(ctx, OrderCompleted{
    OrderID: "123",
})

// Print the recorded events
fmt.Println(rec.Events)

Related Links

• A better domain events pattern
• Domain events: Design and implementation

Documentation

Overview

Package eventually provides a flexible event handling library that enables applications to react to various types of events dynamically. The core functionality revolves around defining, publishing, and handling events.

Index

• func ContextWithPub(ctx context.Context, pub Publisher) context.Context
• func Publish(ctx context.Context, event Event)
• type Event
• type EventHandler
• type PubMux
  • func (pm *PubMux) Publish(event Event)
  • func (pm *PubMux) React(fn EventHandler)
• type Publisher
• type Recorder
  • func (r *Recorder) Publish(event Event)

Examples

• PubMux
• Recorder

Functions

func ContextWithPub

func ContextWithPub(ctx context.Context, pub Publisher) context.Context

ContextWithPub wraps the pub and makes it available to the returned context.Context.

func Publish

func Publish(ctx context.Context, event Event)

Publish event using Publisher available inside the ctx.

If the Publisher is not available in the ctx, it will do nothing.

Types

type Event

type Event any

Event represents specific event. It must be a struct type.

Example:

type OrderCompleted struct {
  OrderID string
}

type EventHandler

type EventHandler any

EventHandle is a function for event handling.

The form of function is:

func(event Event)

where the Event represent the event (struct).

Event handling never fails, no error is returned.

Example:

 pubMux := &eventually.PubMux{}
 pubMux.React(func(event OrderCompleted) {
	    // handle the event
 })

type PubMux

type PubMux struct {
	// contains filtered or unexported fields
}

PubMux is a multiplexer for events. It will route events to its handlers.

Example

// Event definition
type OrderCompleted struct {
	OrderID string
}

// Setup the PubMux
mux := new(eventually.PubMux)
ctx := eventually.ContextWithPub(context.Background(), mux)

// React to the events
mux.React(func(event OrderCompleted) {
	fmt.Printf("OrderCompleted{OrderID:%s} \n", event.OrderID)
})

// Publish event through Reactor inside the context
eventually.Publish(ctx, OrderCompleted{OrderID: "123"})

Output:

OrderCompleted{OrderID:123}

func (*PubMux) Publish

func (pm *PubMux) Publish(event Event)

Publish the event.

The event needs to be a valid Event, otherwise it will panic.

func (*PubMux) React

func (pm *PubMux) React(fn EventHandler)

React will handle the published event.

It will handle only the event type defined by the fn. The fn needs to be a valid EventHandler, otherwise it will panic. Multiple handlers can be registered for the same event type.

type Publisher

type Publisher interface {
	// Publish event.
	Publish(Event)
}

Publisher publishes Event.

type Recorder

type Recorder struct {
	Events []Event
}

Recorder records the events.

The events will be recorded the the Events slice.

Example

// Event definition
type OrderCompleted struct {
	OrderID string
}

// Setup Recorder
rec := new(eventually.Recorder)
ctx := eventually.ContextWithPub(context.Background(), rec)

// Publish event through Recorder inside the context
eventually.Publish(ctx, OrderCompleted{OrderID: "123"})
eventually.Publish(ctx, OrderCompleted{OrderID: "456"})

// Print the recorded events
fmt.Printf("Record %d events\n", len(rec.Events))
for i, event := range rec.Events {
	fmt.Printf("%d. %+v\n", i+1, event)
}

Output:

Record 2 events
1. {OrderID:123}
2. {OrderID:456}

func (*Recorder) Publish

func (r *Recorder) Publish(event Event)

Publish the event to the recorder.