Timebox

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started#

Requirements#

Go 1.27 or later
A supported persistence service when using PostgreSQL or Redis/Valkey

Install#

go get github.com/kode4food/timebox@v0.1.0

Backend packages are part of the same module:

import (
 "github.com/kode4food/timebox"
 "github.com/kode4food/timebox/memory"
)

Define an Aggregate#

An aggregate needs a state type, an empty-state constructor, event types, event payloads, and appliers. Appliers rebuild state from stored events and must be deterministic.

type Account struct {
 Balance int
}

type Deposited struct {
 Amount int `json:"amount"`
}

const AccountDeposited timebox.EventType = "account.deposited"

func newAccount() Account {
 return Account{}
}

var accountAppliers = timebox.Appliers[Account]{
 AccountDeposited: timebox.MakeApplier(
 func(account Account, _ *timebox.Event, data Deposited) Account {
 account.Balance += data.Amount
 return account
 },
 ),
}

MakeApplier decodes the payload and passes both the event metadata and typed data to the function.

Tutorial: Place an Order

Mon, 01 Jan 0001 00:00:00 +0000

Tutorial: Place an Order#

This tutorial builds a small order service from an empty Go module. It receives inventory, atomically reserves stock while placing an order, confirms and ships the order, and queries the resulting event history, status index, and customer tags.

The finished program uses the in-memory backend so it runs without infrastructure. The final step shows how to replace memory with durable storage without changing the domain code.

Aggregates and Events

Mon, 01 Jan 0001 00:00:00 +0000

Aggregates and Events#

Aggregate IDs#

Every aggregate ID contains a type and key:

orderID := timebox.NewAggregateID("order", "ORD-123")

Both components are always populated. For a concept with exactly one aggregate, use NewAggregateType; it fills the key with timebox.SingletonKey:

catalogID := timebox.NewAggregateType("catalog")

Use this pattern for singleton concepts such as a catalog or cluster. Use NewAggregateID when a type has many instances, such as ("workflow", workflowID).

Event Types and Payloads#

Event type names are durable identifiers. Payloads are JSON encoded by Aggregator.Raise:

Transactions

Mon, 01 Jan 0001 00:00:00 +0000

Transactions#

Executor.Exec is a single-aggregate transaction. Use Store.Transact when one operation must update several aggregates atomically:

err := store.Transact(func(tx *timebox.Transaction) error {
 if _, err := tx.Exec(accounts, sourceID,
 func(source Account, ag *timebox.Aggregator[Account]) error {
 if source.Balance < amount {
 return ErrInsufficientFunds
 }
 return ag.Raise(MoneyWithdrawn, Money{Amount: amount})
 },
 ); err != nil {
 return err
 }

 _, err := tx.Exec(accounts, destinationID,
 func(_ Account, ag *timebox.Aggregator[Account]) error {
 return ag.Raise(MoneyDeposited, Money{Amount: amount})
 },
 )
 return err
})

Every backend appends all enlisted aggregate batches or none of them. Each aggregate has its own optimistic sequence check. On a conflict, Timebox refreshes state and reruns the entire transaction function.

Backends

Mon, 01 Jan 0001 00:00:00 +0000

Backends#

All backends implement the same append, snapshot, query, and optimistic-concurrency contract. Choose one backend for storage and create one or more stores over it.

Memory#

backend := memory.Open()
store, err := backend.NewStore()

Use memory for tests and single-process ephemeral state. It supports indexing and archiving.

PostgreSQL#

backend, err := postgres.Open(postgres.Config{
 URL: "postgres://localhost:5432/app?sslmode=disable",
 Prefix: "timebox",
 MaxConns: 32,
})
if err != nil {
 return err
}
defer backend.Close()

store, err := backend.NewStore()

The backend creates and owns its schema. Prefix is the PostgreSQL schema name. PostgreSQL supports events, snapshots, status, tags, and multi-aggregate transactions; it does not support archiving.

Snapshots, Indexing, and Archiving

Mon, 01 Jan 0001 00:00:00 +0000

Snapshots, Indexing, and Archiving#

Snapshots#

Snapshots accelerate state loading; events remain authoritative. Executors save snapshots opportunistically when there is no snapshot or when trailing event data exceeds SnapshotRatio relative to the stored snapshot.

Set TrimEvents when retained events before a snapshot are unnecessary:

store, err := backend.NewStore(timebox.Config{
 TrimEvents: true,
 SnapshotRatio: 1.0,
})

Trimming happens with snapshot persistence. Do not enable it when the complete live event history must remain queryable.

Status and Tag Indexing#

An indexer derives metadata from the same event batch being appended:

Production Patterns

Mon, 01 Jan 0001 00:00:00 +0000

Production Patterns#

These patterns show how the core pieces fit into a long-running replicated service.

One Backend, Several Stores#

Open one backend, then create several stores over it when aggregate families need different policies:

A metadata store for singleton aggregates, with event trimming enabled
A workflow store with a status/tag indexer and a different snapshot ratio

Stores share persistence while keeping their caching, snapshotting, trimming, and indexing policies separate.

One Executor per State Model#

Create separate executors for each state model. Singleton models use NewAggregateType; models with many instances use NewAggregateID.