core/go-store
8
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions 2

[agent/codex] API contract extraction. Read CLAUDE.md. For every exported ... #10

Closed
Virgil wants to merge 1 commit from agent/api-contract-extraction--read-claude-md into dev
pull from: agent/api-contract-extraction--read-claude-md
merge into: core:dev
Conversation 3 Commits 1 Files changed 1 +51
1 changed files with 51 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

51
docs/api-contract.md Normal file
View file

@ -0,0 +1,51 @@
---
title: API Contract
description: 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 |