cago

Cago

Tiny, in‑memory, thread‑safe key/value cache for Go with TTL support.

Features

• Simple API with generics for typed Get/Set
• Per‑key TTL with background cleanup (janitor)
• Lazy expiration on read for precision
• Thread‑safe (RWMutex)

Installation

go get github.com/jasakode/cago/v2

Quick Start

package main

import (
    "fmt"
    "time"

    "github.com/jasakode/cago/v2"
)

func main() {
    // Start the cache with a 1s cleanup interval (default)
    _ = cago.New()
    defer cago.Close()

    // Set a value that expires in 5 seconds
    _ = cago.Set("name", "Cago", 5*time.Second)

    // Typed read
    if v, ok := cago.Get[string]("name"); ok {
        fmt.Println(v)
    }
}

API

type Config struct {
    CleanInterval time.Duration // how often to run cleanup; default 1s
    Timezone      cago.Timezone // reserved, not used by the engine
}

func New(cfg ...cago.Config) error
func Close()

func Set[T any](key string, value T, ttl time.Duration) error // error if key exists and not expired
func Put[T any](key string, value T, ttl time.Duration)       // upsert
func Get[T any](key string) (T, bool)                         // typed read
func Exist(key string) bool                                   // checks non‑expired presence
func Remove(key string) bool                                  // delete
func Clear()                                                  // remove all

Notes:

• ttl <= 0 means the key never expires.
• Get[T] requires T to match the concrete type stored by Set/Put.
• Expiration is enforced on read and by a periodic janitor.

Examples

Set/Put/Get with primitives:

_ = cago.Set("a", 42, 0)            // no expiry
_ = cago.Set("b", 3.14, time.Minute) // expires in 1 minute
cago.Put("a", 99, 0)                 // overwrite regardless of existence

if v, ok := cago.Get[int]("a"); ok {
    fmt.Println(v) // 99
}

Struct values:

type User struct { Name string; Age int }
u := User{"Ada", 30}
_ = cago.Set("user:1", u, 10*time.Second)
if got, ok := cago.Get[User]("user:1"); ok { fmt.Println(got.Name) }

Expiration:

_ = cago.Set("tmp", "x", 100*time.Millisecond)
time.Sleep(150 * time.Millisecond)
if _, ok := cago.Get[string]("tmp"); !ok { /* expired */ }

Cleanup and shutdown:

_ = cago.New(cago.Config{CleanInterval: 500 * time.Millisecond})
defer cago.Close()

Concurrency

All operations are safe for concurrent access. The janitor runs in a single goroutine.

License

BSD-3-Clause