diff --git a/API-Reference.-.md b/API-Reference.-.md deleted file mode 100644 index 01518b9..0000000 --- a/API-Reference.-.md +++ /dev/null @@ -1,185 +0,0 @@ -# API Reference - -All methods are on the `*Store` type. Errors are wrapped with context (e.g. `store.Get: config/theme: store: not found`). - -## Constructor - -### New - -```go -func New(dbPath string) (*Store, error) -``` - -Creates a new Store backed by a SQLite database at `dbPath`. Enables WAL journal mode for concurrent read access and creates the `kv` table if it does not exist. - -Use `":memory:"` for an ephemeral in-memory database (ideal for tests). - -```go -// File-backed store -s, err := store.New("/var/lib/myapp/data.db") - -// In-memory store for tests -s, err := store.New(":memory:") -``` - -**Errors:** Returns an error if the database cannot be opened, WAL mode cannot be enabled, or the schema cannot be created. - ---- - -## Close - -```go -func (s *Store) Close() error -``` - -Closes the underlying SQLite database connection. Always defer this after creating a store. - -```go -s, err := store.New("app.db") -if err != nil { - log.Fatal(err) -} -defer s.Close() -``` - ---- - -## Get - -```go -func (s *Store) Get(group, key string) (string, error) -``` - -Retrieves a single value by group and key. - -```go -val, err := s.Get("config", "theme") -if errors.Is(err, store.ErrNotFound) { - // Key does not exist -} -``` - -**Returns:** The value string, or an error wrapping `ErrNotFound` if the key does not exist in the given group. - ---- - -## Set - -```go -func (s *Store) Set(group, key, value string) error -``` - -Stores a value under the given group and key. Uses upsert semantics: if the key already exists in the group, its value is overwritten. - -```go -err := s.Set("config", "theme", "dark") -err = s.Set("config", "theme", "light") // Overwrites "dark" -``` - -**Errors:** Returns an error only on database failure. - ---- - -## Delete - -```go -func (s *Store) Delete(group, key string) error -``` - -Removes a single key from a group. No error is returned if the key does not exist (the DELETE is a no-op). - -```go -err := s.Delete("config", "theme") -``` - ---- - -## DeleteGroup - -```go -func (s *Store) DeleteGroup(group string) error -``` - -Removes all keys belonging to a group. Useful for clearing an entire namespace. - -```go -err := s.DeleteGroup("cache") -``` - ---- - -## GetAll - -```go -func (s *Store) GetAll(group string) (map[string]string, error) -``` - -Returns all key-value pairs in a group as a map. Returns an empty (non-nil) map if the group has no keys. - -```go -all, err := s.GetAll("config") -// all = map[string]string{"theme": "dark", "lang": "en-GB"} - -empty, err := s.GetAll("nonexistent") -// empty = map[string]string{} -``` - ---- - -## Count - -```go -func (s *Store) Count(group string) (int, error) -``` - -Returns the number of keys in a group. Returns 0 for groups that do not exist or have no keys. - -```go -n, err := s.Count("config") -fmt.Printf("%d keys -", n) -``` - ---- - -## Render - -```go -func (s *Store) Render(tmplStr, group string) (string, error) -``` - -Loads all key-value pairs from a group and executes a Go `text/template` against them. The template receives a `map[string]string` where keys are the store keys and values are the store values. - -See [[Template-Rendering]] for detailed examples and template syntax. - -```go -tmpl := `{"pool":"{{ .pool }}","wallet":"{{ .wallet }}"}` -out, err := s.Render(tmpl, "user") -// out = `{"pool":"pool.lthn.io:3333","wallet":"iz..."}` -``` - -**Errors:** Returns an error if the database query fails, the template cannot be parsed, or template execution fails (e.g. referencing a key that does not exist without using `index`). - ---- - -## ErrNotFound - -```go -var ErrNotFound = errors.New("store: not found") -``` - -Sentinel error returned (wrapped) by `Get` when the requested group/key combination does not exist. Use `errors.Is` to check: - -```go -val, err := s.Get("config", "missing") -if errors.Is(err, store.ErrNotFound) { - // Handle missing key -} -``` - -The full error message includes the group and key: `store.Get: config/missing: store: not found`. - -## Related - -- [[Home]] — Package overview, installation, schema diagram -- [[Template-Rendering]] — Go template syntax and Render examples