synapse

README

synapse

A small Go event sourcing and CQRS toolkit. Composable primitives — aggregates, events, repositories, projections — with zero third-party deps in the core and pluggable backends for events, snapshots, and projection checkpoints.

Status

Pre-1.0. The public surface is still moving; expect minor breaking changes between tagged versions. The persistent stack (SQLite events + snapshots + checkpoints, one file) is shaping up production-ready but has not yet seen production traffic.

Install

go get github.com/ianunruh/synapse

Requires Go 1.26 or newer.

Quick look

package main

import (
    "context"

    jsoncodec "github.com/ianunruh/synapse/codec/json"
    "github.com/ianunruh/synapse/es"
    "github.com/ianunruh/synapse/eventstore/memory"
)

// Define an aggregate by embedding *es.AggregateBase.

type Counter struct {
    *es.AggregateBase
    Value int
}

func NewCounter(id es.StreamID) *Counter {
    return &Counter{AggregateBase: es.NewAggregateBase(id)}
}

type CounterIncremented struct {
    By int `json:"by"`
}

func (c *Counter) Apply(env es.Envelope) {
    if inc, ok := env.Payload.(CounterIncremented); ok {
        c.Value += inc.By
    }
}

func (c *Counter) Increment(by int) {
    c.Record("counter.incremented", CounterIncremented{By: by}, c.Apply)
}

func main() {
    ctx := context.Background()

    reg := es.NewRegistry()
    es.Register(reg, "counter.incremented", jsoncodec.For[CounterIncremented]())

    repo := es.NewRepository(memory.New(), reg, NewCounter)

    c := NewCounter("counter/hits")
    c.Increment(2)
    c.Increment(3)
    _ = repo.Save(ctx, c)

    loaded, _ := repo.Load(ctx, "counter/hits")
    _ = loaded.Value // == 5
}

A full walkthrough is in docs/getting-started.md. Runnable examples live under examples/.

Documentation

• Getting started — a 20-minute walkthrough that builds the Counter aggregate above into a service with commands, a projection, snapshots, and a SQLite backend.
• Architecture Decision Records — 30 records explaining why the library is shaped the way it is.
• Benchmarks — baseline numbers for the core hot paths and the included store backends.
• Package docs: pkg.go.dev/github.com/ianunruh/synapse/es.

Packages

The repo is a Go workspace. Core interfaces live in es; backends and contract suites are sibling packages — or sibling modules when they pull in third-party deps.

Package	Module	What it is
es	root	Aggregate, Repository, Event, Envelope, Snapshotter, Projection, etc.
es/middleware	root	Built-in repository middleware: PerAggregateLocking, Retry
es/projection	root	Runner for read-model projections (type filters, batched checkpoints)
es/commandbus	root	Transport-facing CommandBus + middleware (Logging, Recover, Timeout)
codec/json	root	JSON event/snapshot codec
codec/proto	sibling	Protobuf event/snapshot codec
codec/codectest	root	Codec contract test suite
idgen	root	UUIDv7 identifier generator
eventstore/memory	root	In-memory event store
eventstore/postgres	sibling	Postgres event store (pgxpool, shared LISTEN/NOTIFY)
eventstore/sqlite	sibling	SQLite event store
eventstore/eventstoretest	root	Backend contract test suite
snapshotstore/memory	root	In-memory snapshot store
snapshotstore/postgres	sibling	Postgres snapshot store
snapshotstore/sqlite	sibling	SQLite snapshot store
snapshotstore/snapshotstoretest	root	Backend contract test suite
checkpointstore/memory	root	In-memory checkpoint store
checkpointstore/postgres	sibling	Postgres checkpoint store
checkpointstore/sqlite	sibling	SQLite checkpoint store
checkpointstore/checkpointstoretest	root	Backend contract test suite
pgtest	sibling	Postgres testing harness (testcontainers-go)
examples/counter	root	In-memory event sourcing walkthrough
examples/order	root	Multi-stage aggregate with command validation
examples/projection	root	Projection runner walkthrough
examples/persistent	sibling	SQLite-backed end-to-end demo
examples/http-service	root	CommandBus driven by net/http, live projection

Sibling modules each have their own go.mod. A go.work file at the repo root ties them together for local development. The root module has zero third-party deps; the SQLite backends transitively pull in modernc.org/sqlite (pure Go, no CGo).

Design principles

Recorded as Architecture Decision Records (starting at ADR-0001):

• Go 1.26 toolchain, language features and stdlib used to current capability.
• Zero third-party deps in the root module. Backends that need them live as sibling Go modules.
• Modernization-clean. gopls modernize ./... exits 0 in every module.
• Serialization-agnostic core. Codecs are registered per event type; the es package never imports a specific codec.
• Type safety and performance are co-equal goals. Where they point the same direction (most cases), take both. Where they conflict, prefer the perf-friendly option in hot paths and document the trade-off.
• Admin RPCs and a web UI, when they exist, will be optional sibling subpackages users opt into.

License

Apache 2.0. See LICENSE.

Documentation

Overview

Package synapse is a toolkit for building event-sourced systems in Go.

The library is organized as a set of small subpackages so applications import only what they need. This package itself is doc-only — there is nothing to import from it.

Core (root module, no third-party deps):

• github.com/ianunruh/synapse/es — aggregates, envelopes, the EventStore interface, the [es.Repository] (with snapshots and middleware), the codec [es.Registry], typed command handlers, [es.Execute].
• github.com/ianunruh/synapse/es/middleware — concrete repository middleware: per-aggregate locking, retry-on-conflict.
• github.com/ianunruh/synapse/es/projection — a single-process [projection.Runner] that subscribes, decodes, projects, and checkpoints. Supports type filters and batched checkpoint saves.
• github.com/ianunruh/synapse/es/commandbus — a transport-facing [commandbus.Bus] that routes named, byte-encoded commands to a typed [es.Handler], with its own middleware (Logging, Recover, Timeout).

Codecs (per-event-type, opt-in):

• github.com/ianunruh/synapse/codec/json — encoding/json adapter, root module, stdlib only.
• github.com/ianunruh/synapse/codec/proto — google.golang.org/protobuf adapter, sibling module so the protobuf dep stays out of the core.

Event, snapshot, and checkpoint store backends:

• in-memory: github.com/ianunruh/synapse/eventstore/memory, github.com/ianunruh/synapse/snapshotstore/memory, github.com/ianunruh/synapse/checkpointstore/memory — root module, suitable for tests and development.
• SQLite: github.com/ianunruh/synapse/eventstore/sqlite (and the matching snapshotstore/sqlite, checkpointstore/sqlite) — sibling modules, pure-Go via modernc.org/sqlite.
• Postgres: github.com/ianunruh/synapse/eventstore/postgres (and the matching snapshot/checkpoint variants) — sibling modules via jackc/pgx/v5.

Shared infrastructure:

• github.com/ianunruh/synapse/idgen — UUIDv7 generator.
• github.com/ianunruh/synapse/pgtest — Postgres testing harness (testcontainers-go).
• github.com/ianunruh/synapse/codec/codectest, github.com/ianunruh/synapse/eventstore/eventstoretest, github.com/ianunruh/synapse/snapshotstore/snapshotstoretest, github.com/ianunruh/synapse/checkpointstore/checkpointstoretest — shared contract test suites for the corresponding interfaces.

Architectural decisions are recorded under docs/adr/. Read the relevant ADR before relitigating a decision.