Go SDK

Go SDK for building EvidentSource applications and server-side WASM components.

Status: Stable

SDK Components

Component	Description
evidentsource-core	Core library: events, selectors, constraints, identifiers
evidentsource-client	Client library: gRPC connectivity to EvidentSource servers
evidentsource-functions	Server Functions library: WASM components for state changes and state views

Requirements

Client

• Go 1.22 or later

Server Functions (WASM Components)

• Go 1.22 or later
• TinyGo 0.40.1 or later - Install TinyGo
• wit-bindgen-go (optional): go install go.bytecodealliance.org/cmd/wit-bindgen-go@latest

Installation

# Core library
go get github.com/evidentsystems/evidentsource-sdks/go/packages/evidentsource-core

# Client library
go get github.com/evidentsystems/evidentsource-sdks/go/packages/evidentsource-client

# Server Functions library (for WASM components)
go get github.com/evidentsystems/evidentsource-sdks/go/packages/evidentsource-functions

Quick Start

Client Usage

package main

import (
    "context"
    "log"

    "github.com/evidentsystems/evidentsource-sdks/go/packages/evidentsource-client"
    "github.com/evidentsystems/evidentsource-sdks/go/packages/evidentsource-core/domain"
)

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

    // Connect to EvidentSource server
    es, err := client.ConnectSimple(ctx, "http://localhost:50051")
    if err != nil {
        log.Fatal(err)
    }
    defer es.Close()

    // Connect to a database
    dbName, _ := domain.NewDatabaseName("my-database")
    conn, err := es.ConnectDatabase(ctx, dbName)
    if err != nil {
        log.Fatal(err)
    }

    // Transact events
    event := domain.ProspectiveEvent{
        ID:        "evt-1",
        Stream:    "accounts",
        EventType: "com.example.account.opened",
        Subject:   ptr("acct-123"),
        Data:      domain.StringEventData{Data: `{"name": "John"}`},
    }

    summary, err := conn.Transact(ctx, []domain.ProspectiveEvent{event}, nil)
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Committed at revision %d", summary.Revision)
}

func ptr(s string) *string { return &s }

Server Functions Usage

package main

import (
    coredomain "github.com/evidentsystems/evidentsource-sdks/go/packages/evidentsource-core/domain"
    sdk "github.com/evidentsystems/evidentsource-sdks/go/packages/evidentsource-functions"
)

type CreateAccountCommand struct {
    AccountID string `json:"accountId"`
    Name      string `json:"name"`
}

func decide(db sdk.DatabaseAccess, cmd CreateAccountCommand, meta sdk.StateChangeMetadata) (sdk.DecideResult, error) {
    // Validate
    if cmd.Name == "" {
        return sdk.DecideResult{}, sdk.ValidationErr("name is required")
    }

    // Create event
    event := coredomain.ProspectiveEvent{
        ID:        "evt-1",
        Stream:    "accounts",
        EventType: "com.example.account.opened",
        Subject:   &cmd.AccountID,
        Data:      coredomain.StringEventData{Data: `{"name": "` + cmd.Name + `"}`},
    }

    return sdk.DecideResult{
        Events: []coredomain.ProspectiveEvent{event},
    }, nil
}

var Adapter = sdk.StateChangeAdapter[CreateAccountCommand]{
    ParseCommand: sdk.JSONCommandParser[CreateAccountCommand](),
    Decide:       decide,
}

func main() {}

Building WASM Components

cd examples/todomvc

# Build all components
./build_all.sh

# Install to server
./install.sh --list
./install.sh state-change create_todo
./install.sh --all

Examples

Example	Description
TodoMVC	Classic todo list with CRUD operations
Savings Account	Banking example with deposits, withdrawals, account summary

Project Structure

go/
├── go.work                    # Go workspace for multi-module development
├── interface/                 # Symlink to common WIT/proto definitions
├── packages/
│   ├── evidentsource-core/    # Foundation types
│   ├── evidentsource-client/  # gRPC client
│   └── evidentsource-functions/  # Server Functions library
├── examples/
│   ├── todomvc/               # Todo list example
│   └── savings-account/       # Banking example
└── docs/
    └── WASM_BUILDING.md       # TinyGo + WASM guide

API Reference

API documentation will be available on pkg.go.dev when packages are published.

Next Steps

• Getting Started - Build your first EvidentSource application
• State Changes - Learn about command handling
• State Views - Learn about view materialization