From a2adbf7ba66c1ac4d4cb6c0ce7d376fd9dd4cec2 Mon Sep 17 00:00:00 2001 From: Virgil Date: Fri, 3 Apr 2026 06:23:51 +0000 Subject: [PATCH] refactor(store): tighten AX doc comments Co-Authored-By: Virgil --- compact.go | 2 -- events.go | 5 ----- journal.go | 3 --- scope.go | 4 ---- store.go | 2 -- workspace.go | 5 ----- 6 files changed, 21 deletions(-) diff --git a/compact.go b/compact.go index f5fd927..bcff91a 100644 --- a/compact.go +++ b/compact.go @@ -11,7 +11,6 @@ import ( var defaultArchiveOutputDirectory = ".core/archive" -// CompactOptions controls cold archive generation. // Usage example: `options := store.CompactOptions{Before: time.Now().Add(-90 * 24 * time.Hour), Output: "/tmp/archive", Format: "gzip"}` type CompactOptions struct { Before time.Time @@ -28,7 +27,6 @@ type compactArchiveEntry struct { committedAtUnixMilli int64 } -// Compact archives old journal entries as newline-delimited JSON. // Usage example: `result := storeInstance.Compact(store.CompactOptions{Before: time.Now().Add(-30 * 24 * time.Hour), Output: "/tmp/archive", Format: "gzip"})` func (storeInstance *Store) Compact(options CompactOptions) core.Result { if err := ensureJournalSchema(storeInstance.database); err != nil { diff --git a/events.go b/events.go index 5cf1b20..856bf82 100644 --- a/events.go +++ b/events.go @@ -7,7 +7,6 @@ import ( "time" ) -// EventType identifies the kind of mutation emitted by Store. // Usage example: `if event.Type == store.EventSet { return }` type EventType int @@ -34,7 +33,6 @@ func (t EventType) String() string { } } -// Event describes one mutation delivered to watchers and callbacks. // Usage example: `event := store.Event{Type: store.EventSet, Group: "config", Key: "colour", Value: "blue"}` // Usage example: `event := store.Event{Type: store.EventDeleteGroup, Group: "config"}` type Event struct { @@ -61,7 +59,6 @@ type changeCallbackRegistration struct { // dropping new ones. const watcherEventBufferCapacity = 16 -// Watch registers a buffered subscription for one group. // Usage example: `events := storeInstance.Watch("config")` // Usage example: `events := storeInstance.Watch("*")` func (storeInstance *Store) Watch(group string) <-chan Event { @@ -77,7 +74,6 @@ func (storeInstance *Store) Watch(group string) <-chan Event { return eventChannel } -// Unwatch removes a watcher for one group and closes its event stream. // Usage example: `storeInstance.Unwatch("config", events)` func (storeInstance *Store) Unwatch(group string, events <-chan Event) { if events == nil { @@ -115,7 +111,6 @@ func (storeInstance *Store) Unwatch(group string, events <-chan Event) { storeInstance.watchers[group] = nextRegisteredEvents } -// OnChange registers a synchronous mutation callback. // Usage example: `unregister := storeInstance.OnChange(func(event store.Event) { fmt.Println(event.Group, event.Key, event.Value) })` func (storeInstance *Store) OnChange(callback func(Event)) func() { if callback == nil { diff --git a/journal.go b/journal.go index 7b8f92c..cf5e912 100644 --- a/journal.go +++ b/journal.go @@ -36,7 +36,6 @@ type journalExecutor interface { Exec(query string, args ...any) (sql.Result, error) } -// CommitToJournal records one completed unit of work in the store journal. // Usage example: `result := storeInstance.CommitToJournal("scroll-session", map[string]any{"like": 4}, map[string]string{"workspace": "scroll-session"})` func (storeInstance *Store) CommitToJournal(measurement string, fields map[string]any, tags map[string]string) core.Result { if measurement == "" { @@ -85,8 +84,6 @@ func (storeInstance *Store) CommitToJournal(measurement string, fields map[strin } } -// QueryJournal reads journal rows either through a small Flux-like filter -// surface or a direct SQL SELECT against the internal journal table. // Usage example: `result := storeInstance.QueryJournal(\`from(bucket: "store") |> range(start: -24h)\`)` func (storeInstance *Store) QueryJournal(flux string) core.Result { if err := ensureJournalSchema(storeInstance.database); err != nil { diff --git a/scope.go b/scope.go index 4691e91..ab416f2 100644 --- a/scope.go +++ b/scope.go @@ -13,7 +13,6 @@ var validNamespace = regexp.MustCompile(`^[a-zA-Z0-9-]+$`) const defaultScopedGroupName = "default" -// QuotaConfig sets per-namespace key and group limits. // Usage example: `quota := store.QuotaConfig{MaxKeys: 100, MaxGroups: 10}` type QuotaConfig struct { // Usage example: `store.QuotaConfig{MaxKeys: 100, MaxGroups: 10}` limits a namespace to 100 keys. @@ -30,7 +29,6 @@ type ScopedStore struct { MaxGroups int } -// NewScoped validates a namespace and prefixes groups with namespace + ":". // Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a")` func NewScoped(storeInstance *Store, namespace string) *ScopedStore { if storeInstance == nil { @@ -43,7 +41,6 @@ func NewScoped(storeInstance *Store, namespace string) *ScopedStore { return scopedStore } -// NewScopedWithQuota adds per-namespace key and group limits. // Usage example: `scopedStore, err := store.NewScopedWithQuota(storeInstance, "tenant-a", store.QuotaConfig{MaxKeys: 100, MaxGroups: 10}); if err != nil { return }` func NewScopedWithQuota(storeInstance *Store, namespace string, quota QuotaConfig) (*ScopedStore, error) { scopedStore := NewScoped(storeInstance, namespace) @@ -77,7 +74,6 @@ func (scopedStore *ScopedStore) trimNamespacePrefix(groupName string) string { return core.TrimPrefix(groupName, scopedStore.namespacePrefix()) } -// Namespace returns the namespace string. // Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }; namespace := scopedStore.Namespace(); fmt.Println(namespace)` func (scopedStore *ScopedStore) Namespace() string { return scopedStore.namespace diff --git a/store.go b/store.go index b32ee9c..5636f77 100644 --- a/store.go +++ b/store.go @@ -38,7 +38,6 @@ type journalConfiguration struct { bucketName string } -// JournalConfiguration is the public snapshot returned by Store.JournalConfiguration(). // Usage example: `config := storeInstance.JournalConfiguration(); fmt.Println(config.EndpointURL, config.Organisation, config.BucketName)` type JournalConfiguration struct { // Usage example: `config := store.JournalConfiguration{EndpointURL: "http://127.0.0.1:8086"}` @@ -255,7 +254,6 @@ func (storeInstance *Store) DeleteGroup(group string) error { return nil } -// KeyValue is one item returned by All. // Usage example: `for entry, err := range storeInstance.All("config") { if err != nil { break }; fmt.Println(entry.Key, entry.Value) }` type KeyValue struct { // Usage example: `if entry.Key == "colour" { return }` diff --git a/workspace.go b/workspace.go index a027347..1160632 100644 --- a/workspace.go +++ b/workspace.go @@ -44,7 +44,6 @@ type Workspace struct { closed bool } -// NewWorkspace creates a workspace state file under `.core/state/`. // Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30")` func (storeInstance *Store) NewWorkspace(name string) (*Workspace, error) { validation := core.ValidateName(name) @@ -138,7 +137,6 @@ func (storeInstance *Store) cleanUpOrphanedWorkspaces(stateDirectory string) { } } -// Put appends one entry to the workspace buffer. // Usage example: `err := workspace.Put("like", map[string]any{"user": "@alice", "post": "video_123"})` func (workspace *Workspace) Put(kind string, data map[string]any) error { if kind == "" { @@ -165,7 +163,6 @@ func (workspace *Workspace) Put(kind string, data map[string]any) error { return nil } -// Aggregate returns the current per-kind entry counts in the workspace. // Usage example: `summary := workspace.Aggregate()` func (workspace *Workspace) Aggregate() map[string]any { fields, err := workspace.aggregateFields() @@ -192,13 +189,11 @@ func (workspace *Workspace) Commit() core.Result { return core.Result{Value: fields, OK: true} } -// Discard closes the workspace and removes its backing file. // Usage example: `workspace.Discard()` func (workspace *Workspace) Discard() { _ = workspace.closeAndDelete() } -// Query runs ad-hoc SQL against the workspace buffer. // Usage example: `result := workspace.Query("SELECT entry_kind, COUNT(*) AS count FROM workspace_entries GROUP BY entry_kind")` func (workspace *Workspace) Query(sqlQuery string) core.Result { rows, err := workspace.database.Query(sqlQuery)