RamStorage (r9e) is a small, thread-safe, generic, dependency-free Go library of in-memory key-value containers with a rich set of convenient methods to store, retrieve, transform, and iterate data.

It is focused on usability and simplicity — without giving up performance. Only the Go standard library is used; there are zero third-party dependencies.

• 🔒 Thread-safe — every operation is safe for concurrent use.
• 🧬 Generic — MapKeyValue[K comparable, T any] stores any comparable key and any value type.
• 🧱 Two containers, one API — a sync.RWMutex-backed map and a sync.Map-backed store expose the same method set, so you can switch by workload.
• 🔁 Range-over-func iterators — for k, v := range kv.All() (Go 1.23+).
• 🧰 Functional helpers — Map, Filter, Partition, Merge, Clone, GetOrSet, SortKeys, SortValues — all non-mutating where it matters.
• 🗄️ JSON-ready — implements json.Marshaler / json.Unmarshaler.
• ⚡ O(1) Size() on both containers.
• 🚫 Zero dependencies — standard library only.
• 📄 Apache-2.0 licensed.

r9e takes advantage of Go generics and the standard library's own concurrency primitives to provide a simple way to store and retrieve data from memory. Two containers share the same method set:

flowchart TD
    API["Shared API<br/>Set · Get · GetOrSet · Delete · All · Map · Filter · Partition · Merge · JSON"]
    API --> M["MapKeyValue[K, T]<br/>native map + sync.RWMutex"]
    API --> S["SMapKeyValue[K, T]<br/>sync.Map + atomic counter"]
    M --> M1["Best for read-heavy / mixed<br/>consistent bulk snapshots"]
    S --> S1["Best for disjoint-key writes<br/>write-once / read-many"]

Not sure which to use? Start with MapKeyValue. Switch to SMapKeyValue only if profiling shows the sync.Map access pattern fits your workload better. See docs/containers.md.

• Go 1.26 or newer
• No external Go modules

Add the latest release to your module:

go get github.com/slashdevops/r9e@latest

Pin a specific version:

go get github.com/slashdevops/r9e@vX.Y.Z

Update to the newest available version later:

go get -u github.com/slashdevops/r9e

Then import it:

import "github.com/slashdevops/r9e"

package main

import (
    "fmt"

    "github.com/slashdevops/r9e"
)

func main() {
    kv := r9e.NewMapKeyValue[string, int]()

    kv.Set("answer", 42)

    if v, ok := kv.GetAndCheck("answer"); ok {
        fmt.Println("answer =", v) // answer = 42
    }

    // Range-over-func iteration (Go 1.23+).
    for k, v := range kv.All() {
        fmt.Printf("%s = %d\n", k, v)
    }
}

type Constant struct {
    Name  string
    Value float64
}

kv := r9e.NewMapKeyValue[string, Constant](r9e.WithCapacity(8))

kv.Set("pi", Constant{"Archimedes' constant", 3.141592})
kv.Set("e", Constant{"Euler's number", 2.718281})
kv.Set("phi", Constant{"Golden ratio", 1.618033})

// Keep only the "large" constants (returns a NEW container).
large := kv.FilterValue(func(c Constant) bool { return c.Value > 2.0 })

// Sort the survivors by value.
sorted := large.SortValues(func(a, b Constant) bool { return a.Value > b.Value })
for _, c := range sorted {
    fmt.Printf("%s = %v\n", c.Name, c.Value)
}

Both containers implement the same methods:

Full reference: pkg.go.dev/github.com/slashdevops/r9e

Extensive guides with runnable examples and diagrams live in docs/:

Runnable examples also live in example_test.go.

v1.0.0 is the first stable release. It modernizes the library for Go 1.26 and adds several long-requested capabilities.

• 🔁 Range-over-func iterators — All() returns an iter.Seq2[K, T].
• 🧰 GetOrSet — atomic get-or-insert.
• 🔗 Merge — combine one container into another.
• 🗄️ JSON support — MarshalJSON / UnmarshalJSON on both containers.
• 🐞 Correctness fixes:
  • Fixed potential deadlocks in MapKeyValue caused by recursive read locking in Clone, Map, Filter, Partition, DeepEqual, and sorting.
  • Fixed SMapKeyValue.Size() over-counting when overwriting existing keys.
  • Fixed a non-atomic counter update race in SMapKeyValue.
• 🧹 Modern internals — uses maps, slices, the clear builtin, and sync.Map.Clear.

Migration guide with before/after snippets: docs/migration.md.

r9e keeps the common operations cheap:

• Set, Get, GetAndCheck, GetOrSet, Delete, Size are O(1).
• ContainsValue and the bulk Map / Filter / Partition / sort operations are O(n).
• WithCapacity(n) presizes MapKeyValue to avoid incremental map growth.

Run the benchmarks yourself:

git clone git@github.com:slashdevops/r9e.git
cd r9e/
make bench
# or:
go test -run '^$' -bench . -benchmem ./...

See docs/performance.md for the cost model and tuning tips.

The same checks CI runs:

make check      # fmt + vet + race tests + build
# individually:
go fmt ./...
go vet ./...
go test -race -covermode=atomic -coverprofile=coverage.txt ./...
go build ./...

Issues and pull requests are welcome at github.com/slashdevops/r9e. Please keep changes small, idiomatic, tested, documented, and dependency-free unless there is a clear reason to expand the project scope. See .github/copilot-instructions.md (also linked as AGENTS.md) for conventions.

RamStorage (r9e) is released under the Apache License 2.0:

• http://www.apache.org/licenses/LICENSE-2.0.html