go-store/docs/api-contract.md

title	description
API Contract	Exported public API for go-store with signatures, descriptions, and current test coverage status.

API Contract

Coverage is marked yes only when the current test suite explicitly exercises the exported item's public contract. Indirect internal use inside another exported method is not counted.

Kind	Name	Signature	Description	Test Coverage
Type	Store	type Store struct	Group-namespaced key-value store backed by SQLite.	yes
Function	New	func New(dbPath string) (*Store, error)	Creates a Store at the given SQLite path; ":memory:" is intended for tests.	yes
Method	(*Store).Close	func (s *Store) Close() error	Stops the background purge goroutine and closes the underlying database.	yes
Method	(*Store).Get	func (s *Store) Get(group, key string) (string, error)	Retrieves a value by group and key; expired keys are lazily deleted and treated as not found.	yes
Method	(*Store).Set	func (s *Store) Set(group, key, value string) error	Stores a value by group and key, overwriting any existing value and clearing any expiry.	yes
Method	(*Store).SetWithTTL	func (s *Store) SetWithTTL(group, key, value string, ttl time.Duration) error	Stores a value with a time-to-live; expired keys are later removed lazily and by background purge.	yes
Method	(*Store).Delete	func (s *Store) Delete(group, key string) error	Removes a single key from a group.	yes
Method	(*Store).Count	func (s *Store) Count(group string) (int, error)	Returns the number of non-expired keys in a group.	yes
Method	(*Store).DeleteGroup	func (s *Store) DeleteGroup(group string) error	Removes all keys in a group.	yes
Type	KV	type KV struct	Represents a key-value pair.	no
Method	(*Store).GetAll	func (s *Store) GetAll(group string) (map[string]string, error)	Returns all non-expired key-value pairs in a group.	yes
Method	(*Store).All	func (s *Store) All(group string) iter.Seq2[KV, error]	Returns an iterator over all non-expired key-value pairs in a group.	no
Method	(*Store).GetSplit	func (s *Store) GetSplit(group, key, sep string) (iter.Seq[string], error)	Retrieves a value and returns an iterator over parts split by the supplied separator.	no
Method	(*Store).GetFields	func (s *Store) GetFields(group, key string) (iter.Seq[string], error)	Retrieves a value and returns an iterator over whitespace-separated parts.	no
Method	(*Store).Render	func (s *Store) Render(tmplStr, group string) (string, error)	Loads all non-expired key-value pairs from a group and renders a Go template.	yes
Method	(*Store).CountAll	func (s *Store) CountAll(prefix string) (int, error)	Returns the total number of non-expired keys across groups whose names start with the given prefix.	yes
Method	(*Store).Groups	func (s *Store) Groups(prefix string) ([]string, error)	Returns the distinct group names of all non-expired keys, optionally filtered by prefix.	yes
Method	(*Store).GroupsSeq	func (s *Store) GroupsSeq(prefix string) iter.Seq2[string, error]	Returns an iterator over the distinct group names of all non-expired keys.	no
Method	(*Store).PurgeExpired	func (s *Store) PurgeExpired() (int64, error)	Deletes all expired keys across all groups and returns the number of rows removed.	yes
Type	QuotaConfig	type QuotaConfig struct	Defines optional namespace limits for a ScopedStore; zero values mean unlimited.	yes
Type	ScopedStore	type ScopedStore struct	Wraps a *Store and auto-prefixes group names with a namespace.	yes
Function	NewScoped	func NewScoped(store *Store, namespace string) (*ScopedStore, error)	Creates a ScopedStore with a validated namespace prefix.	yes
Function	NewScopedWithQuota	func NewScopedWithQuota(store *Store, namespace string, quota QuotaConfig) (*ScopedStore, error)	Creates a ScopedStore with quota enforcement for new keys and groups.	yes
Method	(*ScopedStore).Namespace	func (s *ScopedStore) Namespace() string	Returns the namespace string for the scoped store.	yes
Method	(*ScopedStore).Get	func (s *ScopedStore) Get(group, key string) (string, error)	Retrieves a value by group and key within the namespace.	yes
Method	(*ScopedStore).Set	func (s *ScopedStore) Set(group, key, value string) error	Stores a value by group and key within the namespace, enforcing quotas for new keys and groups.	yes
Method	(*ScopedStore).SetWithTTL	func (s *ScopedStore) SetWithTTL(group, key, value string, ttl time.Duration) error	Stores a value with a time-to-live within the namespace, enforcing quotas for new keys and groups.	yes
Method	(*ScopedStore).Delete	func (s *ScopedStore) Delete(group, key string) error	Removes a single key from a group within the namespace.	yes
Method	(*ScopedStore).DeleteGroup	func (s *ScopedStore) DeleteGroup(group string) error	Removes all keys in a group within the namespace.	yes
Method	(*ScopedStore).GetAll	func (s *ScopedStore) GetAll(group string) (map[string]string, error)	Returns all non-expired key-value pairs in a group within the namespace.	yes
Method	(*ScopedStore).All	func (s *ScopedStore) All(group string) iter.Seq2[KV, error]	Returns an iterator over all non-expired key-value pairs in a group within the namespace.	no
Method	(*ScopedStore).Count	func (s *ScopedStore) Count(group string) (int, error)	Returns the number of non-expired keys in a group within the namespace.	yes
Method	(*ScopedStore).Render	func (s *ScopedStore) Render(tmplStr, group string) (string, error)	Loads all non-expired key-value pairs from a namespaced group and renders a Go template.	yes
Type	EventType	type EventType int	Describes the kind of store mutation that occurred.	yes
Method	EventType.String	func (t EventType) String() string	Returns a human-readable label for the event type.	yes
Type	Event	type Event struct	Describes a single store mutation; Key is empty for group deletes and Value is only set for writes.	yes
Type	Watcher	type Watcher struct	Receives events matching a group/key filter.	yes
Method	(*Store).Watch	func (s *Store) Watch(group, key string) *Watcher	Creates a watcher for matching mutations; "*" wildcards are supported and events are dropped if the buffer fills.	yes
Method	(*Store).Unwatch	func (s *Store) Unwatch(w *Watcher)	Removes a watcher, closes its channel, and tolerates repeated calls.	yes
Method	(*Store).OnChange	func (s *Store) OnChange(fn func(Event)) func()	Registers a synchronous callback for every mutation and returns an unregister function.	yes