From a662498891111cd2ed53fdd0dfc552ab6cf547ca Mon Sep 17 00:00:00 2001 From: Virgil Date: Sat, 4 Apr 2026 08:57:06 +0000 Subject: [PATCH] docs(ax): fix misleading store usage examples Co-Authored-By: Virgil --- scope.go | 6 +++--- store.go | 11 +++++------ workspace.go | 25 +++++++++++++++---------- 3 files changed, 23 insertions(+), 19 deletions(-) diff --git a/scope.go b/scope.go index c413a7e..f0b3f22 100644 --- a/scope.go +++ b/scope.go @@ -22,7 +22,7 @@ type QuotaConfig struct { MaxGroups int } -// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }; if err := scopedStore.Set("config", "colour", "blue"); err != nil { return }` +// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }; if err := scopedStore.Set("colour", "blue"); err != nil { return }; if err := scopedStore.SetIn("config", "language", "en-GB"); err != nil { return }` type ScopedStore struct { backingStore *Store namespace string @@ -54,7 +54,7 @@ func (scopedStore *ScopedStore) resolvedStore(operation string) (*Store, error) return scopedStore.backingStore, nil } -// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a")` +// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }` func NewScoped(storeInstance *Store, namespace string) *ScopedStore { if storeInstance == nil { return nil @@ -99,7 +99,7 @@ func (scopedStore *ScopedStore) trimNamespacePrefix(groupName string) string { return core.TrimPrefix(groupName, scopedStore.namespacePrefix()) } -// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }; namespace := scopedStore.Namespace(); fmt.Println(namespace)` +// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }; fmt.Println(scopedStore.Namespace())` func (scopedStore *ScopedStore) Namespace() string { if scopedStore == nil { return "" diff --git a/store.go b/store.go index df6e663..c0c22cd 100644 --- a/store.go +++ b/store.go @@ -13,12 +13,10 @@ import ( _ "modernc.org/sqlite" ) -// NotFoundError is returned when Get cannot find a live key. -// Usage example: `if core.Is(err, store.NotFoundError) { return }` +// Usage example: `if core.Is(err, store.NotFoundError) { fmt.Println("config/colour is missing") }` var NotFoundError = core.E("store", "not found", nil) -// QuotaExceededError is returned when a scoped write would exceed quota. -// Usage example: `if core.Is(err, store.QuotaExceededError) { return }` +// Usage example: `if core.Is(err, store.QuotaExceededError) { fmt.Println("tenant-a is at quota") }` var QuotaExceededError = core.E("store", "quota exceeded", nil) const ( @@ -737,8 +735,9 @@ func (storeInstance *Store) PurgeExpired() (int64, error) { return removedRows, nil } -// New(":memory:") starts a background goroutine that calls PurgeExpired every -// 60 seconds until Close stops the store. +// New(":memory:", store.WithPurgeInterval(20*time.Millisecond)) starts a +// background goroutine that calls PurgeExpired on that interval until Close +// stops the store. func (storeInstance *Store) startBackgroundPurge() { if storeInstance == nil { return diff --git a/workspace.go b/workspace.go index f23282b..85534df 100644 --- a/workspace.go +++ b/workspace.go @@ -35,7 +35,7 @@ var defaultWorkspaceStateDirectory = ".core/state" // Workspace buffers mutable work-in-progress in `.core/state/scroll-session.duckdb` // until Commit or Discard removes the file. // -// Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30"); if err != nil { return }; defer workspace.Discard()` +// Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30"); if err != nil { return }; defer workspace.Discard(); _ = workspace.Put("like", map[string]any{"user": "@alice"})` type Workspace struct { name string backingStore *Store @@ -63,9 +63,10 @@ func (workspace *Workspace) DatabasePath() string { return workspace.databasePath } -// Usage example: `if err := workspace.Close(); err != nil { return }` -// Close releases the workspace database handle but keeps the on-disk file so a +// Close leaves `.core/state/scroll-session-2026-03-30.duckdb` on disk so a // later store instance can recover it as an orphan. +// +// Usage example: `if err := workspace.Close(); err != nil { return }; orphans := storeInstance.RecoverOrphans(".core/state"); _ = orphans` func (workspace *Workspace) Close() error { return workspace.closeWithoutRemovingFiles() } @@ -97,9 +98,10 @@ func (workspace *Workspace) ensureReady(operation string) error { return nil } -// Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30")` -// The workspace database file lives at `.core/state/scroll-session-2026-03-30.duckdb` -// and is removed when the workspace is committed or discarded. +// NewWorkspace creates `.core/state/scroll-session-2026-03-30.duckdb` and +// removes it when the workspace is committed or discarded. +// +// Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30"); if err != nil { return }; defer workspace.Discard()` func (storeInstance *Store) NewWorkspace(name string) (*Workspace, error) { if err := storeInstance.ensureReady("store.NewWorkspace"); err != nil { return nil, err @@ -206,9 +208,11 @@ func workspaceNameFromPath(stateDirectory, databasePath string) string { return core.TrimSuffix(relativePath, ".duckdb") } -// RecoverOrphans(".core/state/") returns orphaned workspaces such as -// `scroll-session.duckdb` so callers can inspect Aggregate() and then Discard(). -// Usage example: `orphans := storeInstance.RecoverOrphans(".core/state/")` +// RecoverOrphans(".core/state") returns orphaned workspaces such as +// `scroll-session-2026-03-30.duckdb` so callers can inspect Aggregate() and +// choose Commit() or Discard(). +// +// Usage example: `orphans := storeInstance.RecoverOrphans(".core/state"); for _, orphanWorkspace := range orphans { fmt.Println(orphanWorkspace.Name(), orphanWorkspace.Aggregate()) }` func (storeInstance *Store) RecoverOrphans(stateDirectory string) []*Workspace { if storeInstance == nil { return nil @@ -292,7 +296,8 @@ func (workspace *Workspace) Aggregate() map[string]any { // Commit writes one journal point for the workspace and upserts the summary // row in `workspace:NAME`. -// Usage example: `result := workspace.Commit()` +// +// Usage example: `result := workspace.Commit(); if !result.OK { return }; fmt.Println(result.Value)` func (workspace *Workspace) Commit() core.Result { if err := workspace.ensureReady("store.Workspace.Commit"); err != nil { return core.Result{Value: err, OK: false}