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 (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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type MemoryStorage ¶ added in v1.4.2
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 ¶ added in v1.4.2
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 ¶ added in v1.4.2
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 ¶ added in v1.4.2
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 ¶ added in v1.4.2
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 ¶ added in v1.4.2
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 ¶ added in v1.4.4
func (ms *MemoryStorage[K, V]) List() []K
func (*MemoryStorage[K, V]) Remove ¶ added in v1.4.2
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 ¶ added in v1.4.2
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 ¶ added in v1.4.3
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 ¶ added in v1.4.3
StringToBytesStorage is a convenience alias for a string→[]byte storage backend.
Source Files