README.md

sum

Wire once, run anywhere. An application framework that unifies HTTP, data, configuration, and services into a single lifecycle.

Compose and Run

// Register services by contract type
k := sum.Start()
sum.Register[UserService](k, &userImpl{})
sum.Register[OrderService](k, &orderImpl{})
sum.Freeze(k)

// Retrieve anywhere by type
userSvc := sum.MustUse[UserService](ctx)

Services, configuration, and data stores—all wired through one registry, resolved by type.

Install

go get github.com/zoobz-io/sum

Requires Go 1.24 or later.

Quick Start

package main

import (
    "context"
    "log"

    "github.com/zoobz-io/sum"
)

type Greeter interface {
    Greet(name string) string
}

type greeterImpl struct{}

func (g *greeterImpl) Greet(name string) string {
    return "Hello, " + name
}

func main() {
    // Initialize service and registry
    svc := sum.New(sum.ServiceConfig{Host: "localhost", Port: 8080})
    k := sum.Start()

    // Register services
    sum.Register[Greeter](k, &greeterImpl{})
    sum.Freeze(k)

    // Use services anywhere
    greeter := sum.MustUse[Greeter](context.Background())
    log.Println(greeter.Greet("World"))

    // Run with graceful shutdown
    if err := svc.Run(); err != nil {
        log.Fatal(err)
    }
}

Capabilities

Capability	Description	Documentation
Service Registry	Type-safe service locator with guards	Registry
Lifecycle Management	Singleton service with graceful shutdown	Service
Configuration	Load and register config via fig	Config
Typed Events	Emit and listen with type-safe payloads	Event
Data Stores	Database, KV, and object storage helpers	Database

Why sum?

• Type-safe service registry — Register and retrieve services by contract type, not strings. Compile-time safety, zero casting.
• Unified lifecycle — One Run() handles startup, signal handling, and graceful shutdown.
• Integrated data catalog — Databases, KV stores, and buckets register automatically with the data catalog for observability.
• Typed events — Define events once with Event[T], emit and listen with full type safety.
• Minimal ceremony — No annotations, no reflection magic, no code generation. Just Go.

The Ecosystem

sum builds on the zoobz-io toolkit:

Package	Purpose
rocco	HTTP engine with OpenAPI
slush	Service registry core
capitan	Event/signal system
fig	Configuration loading
grub	Database/KV/Object storage
scio	Data catalog

Documentation

• Learn: Overview · Quickstart · Concepts · Architecture
• Guides: Testing · Troubleshooting · Service Registry · Events · Data Stores
• Reference: API · Types · pkg.go.dev

Contributing

Contributions welcome—see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE