keyvalue

Documentation

Overview

Package keyvalue provides simple in-memory key–value storage utilities with generic type parameters for keys and values.

The MemoryStorage type is a minimal, type-safe, map-backed storage implementation that satisfies both read and write semantics. It is intended for use cases such as:

• Caching
• Testing
• Lightweight in-memory data stores

Example usage:

storage := keyvalue.NewMemoryStorage[string, []byte]()

storage.Store("foo", []byte("bar"))
value, ok := storage.Get("foo")
if ok {
    fmt.Println(string(value)) // "bar"
}

storage.Remove("foo")
fmt.Println(storage.IsEmpty()) // true

Package keyvalue defines generic interfaces for key-value storage systems. It separates read-only access from full read-write access, allowing flexible abstractions and implementations.

The package provides two key interfaces:

• ReadStorage[K, V]: Defines read-only operations on a storage backend, including fetching values by key and checking if the storage is empty.

• Storage[K, V]: Extends ReadStorage by adding mutation operations such as storing, removing, and clearing entries.

These interfaces are designed to be implemented by various backends such as in-memory maps, persistent databases, or distributed caches.

Example:

type MemoryStorage[K comparable, V any] struct {
    data map[K]V
}

func (ms *MemoryStorage[K, V]) Get(key K) (V, bool)   { v, ok := ms.data[key]; return v, ok }
func (ms *MemoryStorage[K, V]) IsEmpty() bool         { return len(ms.data) == 0 }
func (ms *MemoryStorage[K, V]) Store(key K, val V)    { ms.data[key] = val }
func (ms *MemoryStorage[K, V]) Remove(key K) bool     { _, ok := ms.data[key]; delete(ms.data, key); return ok }
func (ms *MemoryStorage[K, V]) Clean() bool           { existed := len(ms.data) > 0; ms.data = map[K]V{}; return existed }

Index

• type MemoryStorage
  • func NewMemoryStorage[K comparable, V any]() *MemoryStorage[K, V]
  • func (ms *MemoryStorage[K, V]) AsReadStorage() ReadStorage[K, V]
  • func (ms *MemoryStorage[K, V]) Clean() bool
  • func (ms *MemoryStorage[K, V]) Get(key K) (V, bool)
  • func (ms *MemoryStorage[K, V]) IsEmpty() bool
  • func (ms *MemoryStorage[K, V]) List() []K
  • func (ms *MemoryStorage[K, V]) Remove(key K) bool
  • func (ms *MemoryStorage[K, V]) Store(key K, value V)
• type ReadOnlyStringToBytesStorage
• type ReadStorage
• type Storage
• type StringToBytesStorage

Types

type MemoryStorage

type MemoryStorage[K comparable, V any] struct {
	// contains filtered or unexported fields
}

MemoryStorage is a simple in-memory implementation of a generic key–value store.

It is backed by a Go map and supports storing, retrieving, removing, and cleaning up entries. The key type must be comparable (so it can be used as a map key), and the value type may be any Go type.

MemoryStorage is safe for use by a single goroutine at a time. For concurrent use, wrap it with synchronization (e.g., sync.Mutex).

func NewMemoryStorage

func NewMemoryStorage[K comparable, V any]() *MemoryStorage[K, V]

NewMemoryStorage creates and returns a new empty MemoryStorage instance.

Example:

storage := keyvalue.NewMemoryStorage[string, int]()
storage.Store("x", 42)

func (*MemoryStorage[K, V]) AsReadStorage

func (ms *MemoryStorage[K, V]) AsReadStorage() ReadStorage[K, V]

AsReadStorage exposes this MemoryStorage as a read-only storage interface.

This is useful when consumers should only read values but not modify them.

func (*MemoryStorage[K, V]) Clean

func (ms *MemoryStorage[K, V]) Clean() bool

Clean removes all entries from the storage and returns whether the storage had any data before cleanup.

Returns:

• true if the storage contained one or more items
• false if it was already empty

func (*MemoryStorage[K, V]) Get

func (ms *MemoryStorage[K, V]) Get(key K) (V, bool)

Get retrieves the value associated with the given key.

Returns:

• value: the value if found (zero value of V if not found)
• bool: true if the key exists, false otherwise

func (*MemoryStorage[K, V]) IsEmpty

func (ms *MemoryStorage[K, V]) IsEmpty() bool

IsEmpty reports whether the storage contains no entries.

Example:

storage := keyvalue.NewMemoryStorage[string, int]()
fmt.Println(storage.IsEmpty()) // true

func (*MemoryStorage[K, V]) List

func (ms *MemoryStorage[K, V]) List() []K

func (*MemoryStorage[K, V]) Remove

func (ms *MemoryStorage[K, V]) Remove(key K) bool

Remove deletes the entry for the given key if it exists.

Returns:

• true if the key was found and removed
• false if the key did not exist

func (*MemoryStorage[K, V]) Store

func (ms *MemoryStorage[K, V]) Store(key K, value V)

Store inserts or updates a key–value pair in the storage.

If the key already exists, its value is overwritten.

type ReadOnlyStringToBytesStorage

type ReadOnlyStringToBytesStorage = ReadStorage[string, []byte]

ReadOnlyStringToBytesStorage is the read-only view of StringToBytesStorage.

type ReadStorage

type ReadStorage[K comparable, V any] interface {
	List() []K
	Get(key K) (V, bool)
	IsEmpty() bool
}

ReadStorage defines a generic read-only key-value storage interface.

Type Parameters:

• K: the type of keys, must be comparable
• V: the type of values, can be any type

Methods:

• Get(key K) (V, bool): Retrieves the value associated with the given key. The second return value indicates whether the key was present in the storage.
• IsEmpty() bool: Returns true if the storage contains no entries, false otherwise.

type Storage

type Storage[K comparable, V any] interface {
	ReadStorage[K, V]

	Store(key K, value V)
	Remove(key K) bool
	Clean() bool
}

Storage defines a generic key-value storage interface that supports both read and write operations.

It embeds ReadStorage for read-only access, and extends it with mutation methods for modifying the underlying storage.

Type Parameters:

• K: the type of keys, must be comparable
• V: the type of values, can be any type

Methods:

• Store(key K, value V): Inserts or updates the value associated with the given key.
• Remove(key K) bool: Removes the value associated with the key. Returns true if the key existed and was removed, false otherwise.
• Clean() bool: Removes all key-value pairs from the storage. Returns true if any entries were present before cleanup, false otherwise.

type StringToBytesStorage

type StringToBytesStorage = Storage[string, []byte]

StringToBytesStorage is a convenience alias for a string→[]byte storage backend.