Zestor

In-Memory Store (gomap)

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

import "github.com/zestor-dev/zestor/store/gomap"

The gomap package provides a high-performance in-memory implementation of the store.Store interface using Go maps with sync.RWMutex for thread safety.

Features

Zero Dependencies: Pure Go, no external packages
Maximum Speed: Direct memory access, no serialization
Thread-Safe: RWMutex for concurrent access
Full Watch Support: Real-time event notifications
Validation Hooks: Per-kind validation functions
Custom Comparison: Control when updates trigger events

Quick Start

import (
 "github.com/zestor-dev/zestor/store"
 "github.com/zestor-dev/zestor/store/gomap"
)

type User struct {
 Name string
 Email string
}

func main() {
 s := gomap.NewMemStore[User](store.StoreOptions[User]{})
 defer s.Close()

 // CRUD operations
 s.Set("users", "alice", User{Name: "Alice", Email: "alice@example.com"})
 
 user, ok, _ := s.Get("users", "alice")
 if ok {
 fmt.Println(user.Name) // Alice
 }
}

Configuration Options

Basic Store

s := gomap.NewMemStore[User](store.StoreOptions[User]{})

With Validation

Validate data before writes:

Installation

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

Requirements

Go 1.25 or later

Install via Go Modules

Add Zestor to your project:

go get github.com/zestor-dev/zestor

Import

Import the packages you need:

import (
 "github.com/zestor-dev/zestor/store"
 "github.com/zestor-dev/zestor/store/gomap" // In-memory store
)

For persistent storage with SQLite:

import (
 "github.com/zestor-dev/zestor/store"
 "github.com/zestor-dev/zestor/store/sqlite" // SQLite store
 "github.com/zestor-dev/zestor/codec" // Serialization codecs
)

For PostgreSQL (server-backed persistence and cross-process watch):

import (
 "github.com/zestor-dev/zestor/store"
 "github.com/zestor-dev/zestor/store/postgres"
 "github.com/zestor-dev/zestor/codec"
)

Package Overview

Package	Description
`store`	Core interfaces, types, and options
`store/gomap`	In-memory implementation
`store/sqlite`	SQLite-backed persistent implementation
`store/postgres`	PostgreSQL-backed implementation
`codec`	Serialization codecs (JSON, Protobuf, YAML)

Verify Installation

Create a simple test file:

store package

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

import "github.com/zestor-dev/zestor/store"

The store package defines interfaces, types, and options for Zestor stores.

Interfaces

Reader[T any]

Read-only access to the store.

type Reader[T any] interface {
 Get(kind, key string) (val T, ok bool, err error)
 List(kind string, filter ...FilterFunc[T]) (map[string]T, error)
 Count(kind string) (int, error)
 Keys(kind string) ([]string, error)
 Values(kind string) ([]KeyValue[T], error)
 GetAll() (map[string]map[string]T, error)
}

Writer[T any]

Write access to the store.

type Writer[T any] interface {
 Set(kind, key string, value T) (created bool, err error)
 SetFn(kind, key string, fn func(v T) (T, error)) (changed bool, err error)
 SetAll(kind string, values map[string]T) error
 Delete(kind, key string) (existed bool, prev T, err error)
}

Watcher[T any]

Watch access to the store.

type Watcher[T any] interface {
 Watch(kind string, opts ...WatchOption[T]) (r <-chan *Event[T], cancel func(), err error)
}

ReadWriter[T any]

Combined read and write access.

Store & Kinds

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

The Store Interface

Zestor’s core is the Store interface, which provides a complete set of operations for managing in-memory data:

type Store[T any] interface {
 Reader[T]
 Writer[T]
 Watcher[T]
 Close() error
 Dump() string
}

The interface is generic — you specify your data type T when creating the store, and all operations are type-safe.

Kinds: Organizing Your Data

Data in Zestor is organized by kinds. Think of kinds like tables in a database or collections in MongoDB.

Quick Start

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

This guide walks you through building a simple application using Zestor.

Create a Store

First, define your data type and create a store. Zestor ships several implementations; three common ones are below.

In-Memory Store (gomap)

Best for: caching, testing, ephemeral data.

package main

import (
 "fmt"
 "github.com/zestor-dev/zestor/store"
 "github.com/zestor-dev/zestor/store/gomap"
)

type User struct {
 Name string
 Email string
 Role string
}

func main() {
 // Create a new in-memory store
 s := gomap.NewMemStore[User](store.StoreOptions[User]{})
 defer s.Close()
}

SQLite Store (sqlite)

Best for: persistence, desktop apps, CLI tools.

SQLite Store

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

import "github.com/zestor-dev/zestor/store/sqlite"

The sqlite package provides a persistent SQLite-backed implementation of store.Store using modernc.org/sqlite — a pure Go SQLite driver (no CGo required).

Features

Persistent Storage: Data survives application restarts
ACID Transactions: Full transactional support
Single File: All data in one .db file
WAL Mode: Write-Ahead Logging for better concurrency
Version Tracking: Automatic version incrementing
No-op Detection: Byte-level comparison prevents unnecessary updates
Pure Go: No CGo, cross-platform compatible

Quick Start

import (
 "github.com/zestor-dev/zestor/codec"
 "github.com/zestor-dev/zestor/store/sqlite"
)

type User struct {
 Name string `json:"name"`
 Email string `json:"email"`
}

func main() {
 s, err := sqlite.New[User](sqlite.Options{
 DSN: "file:app.db?cache=shared",
 Codec: &codec.JSON{},
 })
 if err != nil {
 log.Fatal(err)
 }
 defer s.Close()

 // Same API as gomap
 s.Set("users", "alice", User{Name: "Alice", Email: "alice@example.com"})
 
 user, ok, _ := s.Get("users", "alice")
 if ok {
 fmt.Println(user.Name) // Alice
 }
}

Configuration

Options

type Options struct {
 DSN string // SQLite connection string (required)
 Codec codec.Codec // Serialization codec (required)
 BusyTimeout time.Duration // Lock wait timeout (optional)
 DisableWAL bool // Disable WAL mode (optional)
}

DSN Examples

DSN	Description
`file:app.db`	Simple file database
`file:app.db?cache=shared`	Shared cache (recommended)
`file:app.db?mode=rwc`	Read-write-create
`file::memory:?cache=shared`	In-memory (testing)

Full Configuration

s, _ := sqlite.New[Config](sqlite.Options{
 DSN: "file:config.db?cache=shared",
 Codec: &codec.JSON{},
 BusyTimeout: 5 * time.Second, // Wait up to 5s for locks
 DisableWAL: false, // Keep WAL enabled (default)
})

Database Schema

The store automatically creates this schema on first use:

Watching & Events

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

Overview

Zestor’s watch system lets you subscribe to changes in real-time. When data is created, updated, or deleted, watchers receive events through a channel.

Basic Watching

// Start watching the "users" kind
ch, cancel, err := s.Watch("users")
if err != nil {
 log.Fatal(err)
}
defer cancel() // Always cancel when done

// Process events
for event := range ch {
 fmt.Printf("%s: %s\n", event.EventType, event.Name)
}

Event Types

Three event types are emitted:

Event	When	`event.Object` contains
`EventTypeCreate`	New key is set	The new value
`EventTypeUpdate`	Existing key is modified	The new value
`EventTypeDelete`	Key is deleted	The previous value

for event := range ch {
 switch event.EventType {
 case store.EventTypeCreate:
 fmt.Printf("Created %s: %+v\n", event.Name, event.Object)
 case store.EventTypeUpdate:
 fmt.Printf("Updated %s: %+v\n", event.Name, event.Object)
 case store.EventTypeDelete:
 fmt.Printf("Deleted %s (was: %+v)\n", event.Name, event.Object)
 }
}

Event Structure

type Event[T any] struct {
 Kind string // The kind (e.g., "users")
 Name string // The key (e.g., "alice")
 EventType EventType // create, update, or delete
 Object T // The value (or previous value for delete)
}

Watch Options

Filter by Event Type

Only receive specific event types:

Interface Segregation

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

Overview

Zestor follows the Interface Segregation Principle by splitting its functionality into focused interfaces. This allows you to pass only the access level your code needs.

Available Interfaces

// Reader provides read-only access
type Reader[T any] interface {
 Get(kind, key string) (val T, ok bool, err error)
 List(kind string, filter ...FilterFunc[T]) (map[string]T, error)
 Count(kind string) (int, error)
 Keys(kind string) ([]string, error)
 Values(kind string) ([]KeyValue[T], error)
 GetAll() (map[string]map[string]T, error)
}

// Writer provides write access
type Writer[T any] interface {
 Set(kind, key string, value T) (created bool, err error)
 SetFn(kind, key string, fn func(v T) (T, error)) (changed bool, err error)
 SetAll(kind string, values map[string]T) error
 Delete(kind, key string) (existed bool, prev T, err error)
}

// Watcher provides watch access
type Watcher[T any] interface {
 Watch(kind string, opts ...WatchOption[T]) (r <-chan *Event[T], cancel func(), err error)
}

// ReadWriter combines Reader and Writer
type ReadWriter[T any] interface {
 Reader[T]
 Writer[T]
}

// Store is the full interface
type Store[T any] interface {
 Reader[T]
 Writer[T]
 Watcher[T]
 Close() error
 Dump() string
}

Why Interface Segregation?

1. Principle of Least Privilege

Pass only the access your code needs:

PostgreSQL Store

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

import "github.com/zestor-dev/zestor/store/postgres"

The postgres package provides a PostgreSQL-backed implementation of store.Store using jackc/pgx/v5 with connection pooling. Writes go to a KV table and an outbox; a trigger sends NOTIFY so a background listener can drain the outbox and fan out Watch events—so watchers on different application instances can observe the same kinds.

Features

Persistent storage with ACID transactions
Cross-process watch via LISTEN / NOTIFY and an outbox (ordered by outbox id)
Namespace / tenant id (Namespace option maps to ns_id)
Version and updated_at maintained on the KV row
No-op Set: skipped when serialized bytes are unchanged (no outbox row)

Quick start

import (
 "log"
 "time"

 "github.com/zestor-dev/zestor/codec"
 "github.com/zestor-dev/zestor/store"
 "github.com/zestor-dev/zestor/store/postgres"
)

type User struct {
 Name string `json:"name"`
 Email string `json:"email"`
}

func main() {
 s, err := postgres.New[User](postgres.Options{
 ConnString: "postgresql://user:pass@localhost:5432/mydb?sslmode=disable",
 Codec: &codec.JSON{},
 Timeout: 10 * time.Second,
 })
 if err != nil {
 log.Fatal(err)
 }
 defer s.Close()

 ch, cancel, err := s.Watch("users", store.WithInitialReplay[User]())
 if err != nil {
 log.Fatal(err)
 }
 defer cancel()

 go func() {
 for ev := range ch {
 log.Printf("%s %s\n", ev.EventType, ev.Name)
 }
 }()

 _, _ = s.Set("users", "alice", User{Name: "Alice", Email: "alice@example.com"})
}

Configuration

Options

type Options struct {
 ConnString string // PostgreSQL URL (required), e.g. postgres://...
 Codec codec.Codec // Required
 Namespace int64 // Optional; default 0 — isolates rows per tenant
 Timeout time.Duration // Per-operation timeout; default 10s
}

Connection strings

Use any DSN accepted by pgx, for example:

Codecs

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

What is a Codec?

A codec (coder/decoder) handles serialization and deserialization of your data types. Persistent stores like SQLite need codecs to convert Go structs to bytes for storage and back again when reading.

type Codec interface {
 Marshal(v any) ([]byte, error)
 Unmarshal(data []byte, v any) error
}

Why Codecs Matter

In-memory stores like gomap store your Go values directly — no serialization needed. But persistent stores must convert values to bytes:

┌──────────────┐ Marshal ┌──────────────┐
│ Go Struct │ ───────────────► │ []byte │ ───► Storage
│ {Name:"X"} │ │ [123,34...] │
└──────────────┘ └──────────────┘

┌──────────────┐ Unmarshal ┌──────────────┐
│ Go Struct │ ◄─────────────── │ []byte │ ◄─── Storage
│ {Name:"X"} │ │ [123,34...] │
└──────────────┘ └──────────────┘

Available Codecs

JSON

The most common choice. Human-readable, widely supported.