Help us shape the future of Go! Take the 2026 Go Developer Survey

nodra

package module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 24, 2026 License: MIT Imports: 11 Imported by: 0

README

nodra

Nodra is a production-oriented reactive state store for Go desktop applications. It is a state library for MyGo apps with Zustand-like ergonomics, and does not tie your state to a renderer or a persistence backend.

Install

go get github.com/yldm-tech/nodra@latest

The core API is in github.com/yldm-tech/nodra. The optional local inspector is in github.com/yldm-tech/nodra/devtools, so applications can omit its server and UI.

MyGo usage

The MyGo integration targets v0.6.3, pinned in go.mod and shared by the native example.

Redraw a native MyGo window whenever its store publishes:

stop := nodra.Invalidate(store, window)

The subscription stops automatically when the window closes. Call stop() to detach it earlier; repeated calls are safe. A hidden window stays subscribed so it can be shown again. Each window has its own subscription, and closing one does not close the shared Store.

For a window that only displays part of the state, select that part so unrelated updates do not request a frame:

stop := nodra.InvalidateSelector(store, window, func(s AppState) int {
    return s.Count
})

InvalidateSelectorWith accepts SelectorOptions[V], including Equals for collections and Immediate to request a frame on attachment. It uses the same equality and ownership rules as SubscribeSelectorWith. Select every value the view displays; multiple windows can select different values from the same Store. This filters redraw requests, not individual UI elements, and does not track field reads automatically.

Keep local UI state, such as a draft or an open popover, in the view's Go owner or MyGo's ui.Local. For a widget that edits shared business state, bind a local snapshot field and commit only the changed field:

enabled := store.Get().Enabled
if ui.Checkbox(c, &enabled, "Enable sync").Changed() {
    if err := store.Update(func(s *AppState) { s.Enabled = enabled }); err != nil {
        log.Print(err)
    }
}

Replacing the whole snapshot with Set here could overwrite another field changed by a background task. Subscribers and selectors run on writer goroutines, so update other UI-owned fields through window.Update; the invalidation helpers only request a goroutine-safe redraw. Stopping does not wait for an already running callback, and a selector panic during attachment releases the window listener before propagating.

go run ./examples/mygo demonstrates a counter and a preferences window with independent selectors, field-level widget commits, and a background action.

Read-only state and lifecycle ownership

Pass store.ReadOnly() to UI code that should observe shared state without changing or closing it. The concrete wrapper hides its backing Store; returning an interface whose dynamic value is the writable Store would not provide that boundary. Reader[T] is the observation surface accepted by selectors, projections, derived getters, MyGo invalidation and DevTools attachment. A read-only DevTools source remains non-restorable even when inspector restoration is enabled. Read-only values retain the source's cloning/immutability policy; referenced data is not automatically frozen.

view := store.ReadOnly()
nodra.Invalidate(view, window)
count := nodra.Select(view, func(s AppState) int { return len(s.Items) }).Value

AsyncAction.Status() now returns ReadOnly[AsyncState] instead of *Store[AsyncState]. Ordinary read/subscription calls continue to work. Change explicit status variable/parameter types to ReadOnly[AsyncState] or Reader[AsyncState]; remove writes or closes on status and close its owning action instead. Helpers that previously accepted *Store[T] now accept Reader[T], so explicitly typed helper function variables may need the same parameter change.

Use a Scope for one window/module owner. Register stores first, persistence writers next, then actions; drains execute in reverse order. Observe owns unsubscribe functions separately so subscriptions stop before drains. A registration racing with shutdown is cleaned immediately and returns ErrClosed.

scope := nodra.NewScope()
_ = scope.Defer(func(context.Context) error { return store.Close() })
_ = scope.Defer(writer.Close)
_ = scope.Defer(action.Close)
_ = scope.Observe(nodra.Invalidate(store.ReadOnly(), window))
task, err := action.Run(scope.Context(), input)
// Handle err. At owner shutdown, use a fresh deadline:
shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
err = scope.Close(shutdownCtx)

Close cancels scope.Context(), stops observations, drains registered resources and preserves all cleanup errors. Concurrent callers share the shutdown result with independent wait deadlines; the first Close supplies the cleanup context. Callbacks must respect that context. Use an independent worker context for write-behind persistence so it can drain after the Scope context is canceled. Do not synchronously close a Scope from one of its own cleanup callbacks, or from a task it must drain. Shared stores can outlive a Scope by leaving their Close unregistered. The workbench demonstrates Scope ownership and window-bound observations.

Async actions

Action and Do are synchronous mutations: their callbacks run under the Store write lock. Use NewAsyncAction for file/network work, then commit a short state mutation:

search, err := nodra.NewAsyncAction(store, "search", func(ctx context.Context, query string, progress func(float64)) ([]Item, error) {
    return fetchItems(ctx, query)
}, func(s *AppState, items []Item) error {
    s.Items = items
    return nil
})
// Handle err before using search.
task, err := search.Run(ctx, query)
// Handle err; task.Cancel() requests cancellation, task.Wait(waitCtx) observes completion.

Each run cancels its predecessor and only the latest uncanceled result can commit, including when old work ignores cancellation. Status() is an observable ReadOnly[AsyncState] with a run ID, running flag, monotonic progress from zero to one, and error text. It exposes no mutation or close methods. Attach it to MyGo invalidation or DevTools like any Store. Work runs outside the state lock; the apply callback follows normal UpdateErr ownership and rollback rules. Copy mutable inputs before Run, or otherwise keep them immutable for the entire run.

Action hooks and events cover the work and commit, with a per-store action ID and duration. Panics at the asynchronous user-code boundary become PanicError; a notification/hook panic can happen after a successful commit. Cancellation prevents result commits, but cannot undo network/file side effects already performed. Work must honor its context. Closing the source Store cancels active runs. At owner shutdown, call search.Close(shutdownCtx) before closing stores; it cancels and waits, and closes the status Store after terminal status is published. A timed-out Close can be called again. Do not wait or close synchronously from that task's own work, hooks or subscribers.

Scheduling and per-task status

NewAsyncActionWithOptions adds explicit scheduling without changing the default constructor's latest-result policy:

action, err := nodra.NewAsyncActionWithOptions(store, "load item", work, apply,
    nodra.ActionOptions[Request]{
        Policy: nodra.LatestWins,
        Key: func(request Request) string { return request.ItemID },
        MaxConcurrent: 4,
        QueueLimit: 32,
    })

LatestWins replaces work only for the same key; different keys are independent. Use QueueAll for work that must retain every accepted input. QueueAll defaults to one worker for FIFO starts/commits; with more workers, starts are FIFO and commits follow completion order. LatestWins with zero MaxConcurrent preserves unbounded legacy behavior. Bounded actions default to 64 pending entries, and a full queue returns ErrQueueFull without canceling existing work. A superseded queued entry can be replaced even when that queue is full. Canceled work that has not returned still occupies its concurrency slot. Run accepts input without waiting for a work slot; canceled queued tasks finish without executing work.

Task.Status() exposes that task's key, queued/running/terminal phase, progress and diagnostic error. The status Store closes after terminal status. The action-level Status describes the most recently accepted run, which is not a count of all active work. Use ActiveTasks() or TaskSnapshot() on the source for current work. Do not wait for another queued task synchronously from work, hooks or subscribers of the same bounded action; that can exhaust its own work slots. Progress may be reported concurrently during work; stop reporting when work returns.

SubscribeActionTrace observes async acceptance, start, progress and terminal outcome. Action ID links traces to mutation and completion events; RunID is local to one action. TaskVersion orders one task's status while Revision orders source trace publication; callbacks can still overlap. Committed/Version identify the accepted publication even if notifications later fail. A Store Batch coalesces publication across writers, so its final mutation has no single ActionID and individual batched actions do not claim a published commit version. Durations include queue waiting time. Terminal task entries are released from the source's active map.

Owned projections for large state

Get and ordinary selector subscriptions preserve the Store's full-state cloning policy. For hot reads, Select borrows read-only state and copies only the projection you return:

count := nodra.Select(store, func(s AppState) int { return len(s.Items) }).Value
items := nodra.Select(store, func(s AppState) []Item { return slices.Clone(s.Items) }).Value

The callback runs under the read lock: do not mutate state, retain source references, reenter the Store or block. Copy nested mutable references too. The returned snapshot includes the source version. SubscribeProjection / SubscribeProjectionWith offer the same explicit ownership boundary for subscriptions without a whole-state copy per listener. Their projector runs on immutable source snapshots and must return independently owned projections; callbacks must treat current/previous projections as immutable. Default stores still require immutable referenced data. Existing SubscribeSelector remains the convenient isolated choice. Only opt in to projections where the smaller copy matters. InvalidateProjection / InvalidateProjectionWith apply the same policy to window-bound redraws; DeriveProjection memoizes an owned projection. These accept read-only views and preserve the projector contract throughout the binding/derived pipeline. Derived reference values and listener arguments are read-only.

Grouped and filtered undo

history := nodra.TrackWith(store, nodra.HistoryOptions[AppState]{
    Limit: 50,
    Equals: func(a, b AppState) bool { return a.Title == b.Title },
    Restore: func(current, recorded AppState) AppState {
        current.Title = recorded.Title
        return current
    },
})
end, err := history.BeginGroup() // keep end until the drag/edit interaction finishes
// Handle err. Updates still publish for each frame.
end()

Equals ignores changes outside the edited fields. Restore preserves their current values during undo/redo; filtering alone does not preserve fields when restoring whole snapshots. These callbacks must be pure, must not mutate arguments, and must not reenter the Store or History because they can run under locks. Nested groups merge into one undo step; repeated end calls are safe. Concurrent writers join an open group. Travel is rejected with ErrHistoryGroup until every group ends. An empty/filtered group adds no step. Track(store, limit) retains its existing behavior.

Desktop workflow example

go run ./examples/workbench opens a local file-name search and a settings form. It uses real directory traversal, cooperative search cancellation, bounded results, UI-local drafts, asynchronous validation and atomic settings-file writes. Invalid directories and failed writes leave the draft available and the committed preferences unchanged. Cancel edits reloads the committed preferences. The settings path defaults to the user configuration directory; override it with -settings /path/to/settings.json. Saves also maintain a .bak copy. Add -devtools to print a local read-only inspection URL for real search/save task lifecycles.

Core usage

import nodra "github.com/yldm-tech/nodra"

tasks := nodra.New([]Task{})
stop := tasks.SubscribeWith(nodra.SubscribeOptions[[]Task]{Immediate: true}, func(snapshot nodra.Snapshot[[]Task]) {
	log.Printf("%d tasks", len(snapshot.Value))
})
defer stop()

tasks.Update(func(value *[]Task) {
	*value = append(*value, task)
})

What is included

  • Generic, concurrency-safe Store[T] with versioned snapshots
  • Opt-in NewWithClone / DefineWithClone for isolated mutable state and deep rollback
  • Set, Update, and UpdateErr with value rollback on returned errors and panics
  • Subscribe and SubscribeWith with immediate delivery and per-subscriber equality
  • SubscribeSelector and SubscribeSelectorWith for focused updates with previous values
  • Derive for memoized computed/getter values
  • Action / Do with action timing and error events
  • Latest-result asynchronous actions with cancellation, progress, observable status and explicit shutdown
  • Opt-in owned projections that avoid whole-state copies for hot reads and subscriptions
  • SubscribeMutations with direct, patch, reset and action metadata
  • Create, Define, State, Patch, and Reset aliases for familiar Pinia/Zustand workflows
  • Store IDs and independent named store instances
  • Action lifecycle hooks: before, after, and error
  • Nested Batch notification groups that publish one final snapshot
  • Transaction for one serialized, fallible mutation
  • Track / TrackWith history with bounded undo/redo, recording filters and cross-frame edit groups
  • Persistence[T] with pluggable storage and codec interfaces
  • Ready-to-use FileStorage and JSONCodec[T] with atomic file replacement
  • VersionedJSONCodec[T] with sequential schema migrations and explicit legacy JSON support
  • AutoSaveWithErrors for observable persistence failures
  • AutoSaveAsync for debounced, coalesced writes with Flush, Close and an error stream
  • Context-bound, bounded Watch streams that close with the store
  • Invalidate and InvalidateSelector for window-bound redraw subscriptions with automatic cleanup
  • Optional DevTools with a local browser inspector, mutation/action timeline, lazy state trees, key/value search, bounded state diffs, snapshot export, JSON editing and opt-in state restoration

Design guarantees

  • Store locks are released before user listeners run, so listeners can safely read or update the same store.
  • Versions increment once per published update, not once per mutation inside a batch.
  • Closing a store is permanent; updates return nodra.ErrClosed and active watches terminate.
  • By default, values are not deep copied. Copy reference types before changing them, or use NewWithClone with a complete clone function. Cloned stores isolate constructor and Set inputs, update candidates, reads, each subscriber, mutation metadata and reset state.
  • Selectors and derived getters catch up with changes during initialization and ignore computations from older versions once a newer version has been processed. Callbacks still run on writer goroutines and may run concurrently.
  • Concurrent Save calls on one Persistence instance are serialized from state capture through storage write, so a delayed save cannot overwrite a newer save. Keep one persistence instance per destination; Load is intended for startup before concurrent writes.
  • Subscriptions discard obsolete snapshots once they have accepted a newer source version. Callbacks that already started may still overlap or finish out of order. Watch channels are bounded and retain the newest accepted version; slow consumers may skip intermediate snapshots.
  • History keeps source versions monotonic and commits stack changes with successful undo/redo writes. Failed writes leave stacks intact. Travel inside an open batch returns ErrHistoryBatch; finish the batch before undoing or redoing.

Isolated mutable state

When state contains maps, slices or pointers, opt in to cloning instead of maintaining copy-on-write manually:

store := nodra.NewWithClone(map[string]int{"count": 0}, func(v map[string]int) map[string]int {
    return maps.Clone(v)
})
err := store.Transaction(func(state *map[string]int) error {
    (*state)["count"]++
    return validate(*state) // an error discards the candidate, including map changes
})

Clone all mutable nested references too. The function must support concurrent calls and must not reenter the store. Each isolation boundary costs a copy; keep using New for immutable state or large data already managed with copy-on-write. Named factories support the same policy through DefineWithClone.

Collection selectors

Selectors accept slices, maps and values containing interfaces. By default dynamically comparable values use == (including pointer identity); other values use reflect.DeepEqual. Nil and empty collections differ with the default comparison. Supply Equals for domain-specific equality or faster comparisons of large collections:

stop := nodra.SubscribeSelectorWith(store,
    func(s State) []string { return s.Tags },
    func(current, previous []string) { window.Invalidate() },
    nodra.SelectorOptions[[]string]{Equals: slices.Equal[[]string]},
)
defer stop()

For maps use maps.Equal[map[string]int, map[string]int] or a custom comparator. Comparators must be pure and concurrency-safe; a supplied comparator replaces the default entirely. Selected reference values follow the source store's ownership policy: treat them as read-only and copy before changing them. SubscribeSelector offers the same default equality without previous values or options.

Versioned persistence

VersionedJSONCodec[T] wraps state in {"schemaVersion": N, "state": ...}. Migrations[n] transforms state JSON from version n to n+1. With AllowUnversioned: true, existing raw JSON enters the chain at version zero:

codec := nodra.VersionedJSONCodec[Settings]{
    Version: 2,
    AllowUnversioned: true,
    Migrations: map[int]nodra.JSONMigration{
        0: migrateLegacyToV1,
        1: migrateV1ToV2,
    },
}
persistence := nodra.NewPersistence(store, nodra.FileStorage{Path: path}, codec)
err := persistence.Load(ctx) // completes migrations before changing the store

Missing migrations, invalid migration output and future schemas return errors. A failed load leaves the store and file untouched. Load before starting autosave; successful migration is written by a subsequent Save or autosave.

Validated persistence and backup recovery

NewPersistenceWithOptions accepts PersistenceOptions[T]{Validate: ...}. Validation runs after decoding/migration and before Store replacement, and before encoding/saving. It must be pure and concurrency-safe. A failed load or validation leaves memory and files unchanged. LoadError identifies read, decode or validate, distinguishes backup loads, and preserves the underlying error for errors.Is/errors.As.

Enable FileStorage{Path: path, Backup: true} to write an independently replaced path + ".bak" copy after successful primary replacement. Backup I/O errors are returned; the primary may already have been saved when a backup fails. The two files are not one transaction. Keep one Persistence writer per destination, and reserve its .bak path for this backup. Applications must surface save errors rather than assume both files were updated.

After a failed startup Load, stop and present that error before starting autosave. persistence.LoadBackup(ctx) explicitly validates and loads the backup into memory without rewriting either file. A later Save intentionally persists the recovered/current state. No silent fallback discards a corrupt original. Stores without a backup-capable backend return ErrNoBackup. Try go run ./examples/persistent -file /path/to/state.json -recover-backup to inspect recovery without modifying the files.

Write-behind persistence

Move encoding and disk I/O off the goroutine updating the store:

writer, err := persistence.AutoSaveAsync(ctx, nodra.AsyncOptions{
    Debounce: 100 * time.Millisecond,
})
// Handle err before using writer.
// Updates now coalesce on one worker; Flush bypasses the debounce delay.
err = writer.Flush(flushCtx)
// At application exit, stop updates and drain before canceling ctx or closing store.
err = writer.Close(shutdownCtx)

The writer schedules the current state once at startup. Flush waits for the version visible at the call; canceling one flush wait leaves the worker running. Failed writes stay pending and retry on the next update or flush. Errors() is a bounded stream for background failures; Flush and Close return errors directly. Close stops observing, attempts the final flush, and stops even on failure. Retry a failed shutdown write with persistence.Save and a fresh context. Parent cancellation and store closure stop the worker without a guaranteed drain.

examples/persistent combines cloning, legacy migration, error handling and graceful shutdown:

go run ./examples/persistent -file /path/to/state.json

Repository layout

*.go                           store, history, persistence, MyGo invalidation, and tests (package nodra)
devtools/                      optional inspector, local HTTP API and embedded browser UI
examples/                      standalone and native MyGo examples
docs/architecture.md           lifecycle and threading details

The repository is one Go module, github.com/yldm-tech/nodra, with a single go.mod at the root.

DevTools

import "github.com/yldm-tech/nodra/devtools"

inspector := devtools.New(devtools.Options{}) // read-only by default
defer inspector.Close()
stop, err := devtools.Attach(inspector, "preferences", prefsStore)
// Handle err before using stop; call stop when this store is no longer in scope.
url, err := inspector.Listen() // random loopback port; open the full session URL

The browser shows multiple stores, live state, bounded mutation/action history, action durations and errors, before/after diffs, filtering and JSON export. Set AllowRestore: true explicitly to enable typed JSON editing and restoring a retained snapshot. Restoration calls Set and emits new events; it does not reverse external action effects. Redact filters state before capture and disables restoration. No external assets, services or frontend build step are required.

Try the interactive example and see the DevTools guide for lifecycle, redaction and browser tests:

go run ./examples/devtools -restore

Nodra DevTools inspecting a state change

Verification

go test -race ./...
go vet ./...

Run the native MyGo example with go run ./examples/mygo.

CI runs race tests and vet on Linux, macOS and Windows. It also runs golangci-lint, two 10-second fuzz targets, benchmark smoke tests, cross builds for Linux and Windows, and checks that the module path is github.com/yldm-tech/nodra, that there is no other go.mod, go.work or replace directive, and that go mod tidy leaves no diff.

Fuzzing and benchmarks
go test -run '^$' -fuzz=FuzzVersionedJSONDecode -fuzztime=30s -parallel=2 .
go test -run '^$' -fuzz=FuzzHistoryStateMachine -fuzztime=30s -parallel=2 .
go test -run '^$' -bench=. -benchmem -count=5 .

Fuzzing checks accepted versioned/legacy JSON round trips and compares bounded undo/redo/batch operations with an independent state-machine model. Benchmarks report store updates with 0/1/100 listeners, full cloning of a 1,000-entry map, and selection of 1,000-element slices with default versus custom equality. Run repeated measurements on the same Go version, hardware and load before comparing changes. The CI -benchtime=1x run only checks execution, with no performance thresholds.

An illustrative local run on Apple M4 Pro, darwin/arm64 measured approximately 73 ns per update without listeners, 101 ns with one listener and 1.51 µs with 100 listeners; cloning the map cost 6.81 µs. Slice selection including the projection clone took 6.57 µs with default equality and 1.13 µs with slices.Equal. These are machine-specific measurements, not API guarantees.

Releases

The module is released by release-please with plain vX.Y.Z tags and one root CHANGELOG.md.

  1. Every push to main updates the release PR when there are releasable commits since the last tag. Merging that PR tags the release and publishes a GitHub release.
  2. After a release, post-release.yml checks that the tag resolves through proxy.golang.org.

Commit messages follow Conventional Commits:

  • feat: ... adds a feature (minor bump)
  • fix: ... fixes a bug (patch bump)
  • feat!: ... or a BREAKING CHANGE: footer marks a breaking change (minor bump while the version is below 1.0.0)
  • docs, test, refactor, ci, build and chore do not trigger a release

Use a scope where it helps, e.g. fix(persist): ....

Release PRs are pushed with the workflow's GITHUB_TOKEN. GitHub holds their test runs at "approval required", so the release workflow approves those runs itself (.github/scripts/start-pr-ci.sh). Setting a RELEASE_PLEASE_TOKEN repository secret (a fine-grained PAT or GitHub App token with contents and pull request write access) makes them trigger CI directly instead.

Pinia/Zustand-style example

store := nodra.Create(Counter{Count: 0})
increment := store.Action("increment", func(state *Counter) error {
    state.Count++
    return nil
})
double := nodra.Derive(store, func(state Counter) int {
    return state.Count * 2
}, func(a, b int) bool { return a == b })

_ = increment()
fmt.Println(store.State().Count, double.Get())

See docs/architecture.md for the full concept mapping.

Named stores

counter := nodra.Define("counter", func() Counter {
    return Counter{Count: 0}
})
store := counter.New()

Each call to New creates an independent instance with the same initial-state factory. The ID is available to mutation and action observers for logging and devtools integrations.

Documentation

Overview

Package nodra is a state library for MyGo apps: concurrency-safe reactive stores whose snapshots drive native MyGo views. Invalidate redraws a window when its store publishes; the Store itself does not depend on a running MyGo app, so services and tests can use it as well.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrNoUndo = errors.New("nodra: nothing to undo")
	ErrNoRedo = errors.New("nodra: nothing to redo")
)

ErrNoUndo and ErrNoRedo report an empty history stack.

View Source 
var (
	ErrSuperseded    = errors.New("nodra: async action superseded")
	ErrInvalidAction = errors.New("nodra: invalid async action")
	ErrQueueFull     = errors.New("nodra: async action queue full")
)
View Source 
var (
	ErrUnsupportedVersion = errors.New("nodra: unsupported schema version")
	ErrMissingMigration   = errors.New("nodra: missing schema migration")
)
View Source 
var ErrClosed = errors.New("nodra: store is closed")
View Source 
var ErrHistoryBatch = errors.New("nodra: cannot undo or redo inside an open batch")

ErrHistoryBatch reports travel without an independent publication boundary.

View Source 
var ErrHistoryGroup = errors.New("nodra: cannot undo or redo inside an open history group")
View Source 
var ErrInvalidPersistence = errors.New("nodra: invalid persistence configuration")
View Source 
var ErrNoBackup = errors.New("nodra: backup storage unavailable")

Functions

func Invalidate added in v0.2.0 

func Invalidate[T any](source Reader[T], window *mygo.Window) (stop func())

Invalidate requests a new frame of window's native Content whenever store publishes a snapshot. The subscription stops when the window closes; the returned function stops it earlier and is safe to call repeatedly. Nil inputs and destroyed windows subscribe to nothing. A callback already running when stopped may still request a frame.

func InvalidateProjection added in v0.6.0 

func InvalidateProjection[T, V any](source Reader[T], window *mygo.Window, project func(T) V) func()

InvalidateProjection requests frames only when an owned projection changes, without cloning the entire source. The projector and callbacks follow SubscribeProjection's ownership rules. The window owns the subscription lifetime.

func InvalidateProjectionWith added in v0.6.0 

func InvalidateProjectionWith[T, V any](source Reader[T], window *mygo.Window, project func(T) V, options SelectorOptions[V]) func()

func InvalidateSelector added in v0.5.0 

func InvalidateSelector[T any, V any](source Reader[T], window *mygo.Window, selector func(T) V) (stop func())

InvalidateSelector requests a frame only when the selected value changes, using SubscribeSelector's equality rules. The subscription stops when the window closes or the returned function is called. Selectors run on writer goroutines and must be concurrency-safe; selected reference values follow the store's ownership policy.

func InvalidateSelectorWith added in v0.5.0 

func InvalidateSelectorWith[T any, V any](source Reader[T], window *mygo.Window, selector func(T) V, options SelectorOptions[V]) (stop func())

InvalidateSelectorWith is InvalidateSelector with custom equality and optional immediate invalidation. Nil inputs and destroyed windows subscribe to nothing. As with Invalidate, stopping does not wait for callbacks already running.

func SubscribeProjection added in v0.6.0 

func SubscribeProjection[T, V any](source Reader[T], project func(T) V, fn func(V)) func()

func SubscribeProjectionWith added in v0.6.0 

func SubscribeProjectionWith[T, V any](source Reader[T], project func(T) V, fn func(current, previous V), options SelectorOptions[V]) func()

SubscribeProjectionWith is an opt-in selector that borrows immutable source snapshots instead of cloning the entire Store per notification. project must be pure and concurrency-safe, must not retain or mutate source references, and must return independently owned projections. Callbacks must treat the current/previous projections as immutable. Equality, initialization and callback ordering match SubscribeSelectorWith. On default stores, source reference values must remain immutable as with any retained snapshot.

func SubscribeSelector 

func SubscribeSelector[T any, S any](store Reader[T], selector func(T) S, fn func(S)) func()

func SubscribeSelectorWith 

func SubscribeSelectorWith[T any, V any](source Reader[T], selector func(T) V, fn func(current, previous V), options SelectorOptions[V]) func()

SubscribeSelectorWith calls fn with current and previous selected values. It catches up after registration and ignores obsolete computations. Callbacks run on writer goroutines and may overlap, as with Store.Subscribe.

Types

type ActionEvent 

type ActionEvent struct {
	ID        uint64
	RunID     uint64
	Key       string
	Version   uint64
	Committed bool
	StoreID   string
	Name      string
	Started   time.Time
	Finished  time.Time
	Duration  time.Duration
	Err       error
}

ActionEvent describes one completed action.

type ActionHooks 

type ActionHooks struct {
	Before func(ActionEvent)
	After  func(ActionEvent)
	Error  func(ActionEvent)
}

ActionHooks observes action lifecycle events. Before runs before the mutation; After runs only on success; Error runs only on failure.

type ActionOptions added in v0.6.0 

type ActionOptions[I any] struct {
	Policy        ActionPolicy
	Key           func(I) string
	MaxConcurrent int
	QueueLimit    int
}

ActionOptions configures cooperative work scheduling. LatestWins (default) replaces only the preceding task with the same Key; nil Key uses one shared key. QueueAll keeps every accepted task. MaxConcurrent bounds work including canceled work that has not returned; zero is unbounded for LatestWins and defaults to one for QueueAll. QueueLimit bounds waiting tasks (default 64 when bounded). Starts are FIFO; with concurrency above one commits follow completion order. Key must be pure and concurrency-safe.

type ActionPolicy added in v0.6.0 

type ActionPolicy uint8
const (
	LatestWins ActionPolicy = iota
	QueueAll
)

type ActionTrace added in v0.6.0 

type ActionTrace struct {
	ID          uint64
	RunID       uint64
	StoreID     string
	Name        string
	Key         string
	Phase       TaskPhase
	Progress    float64
	Revision    uint64
	TaskVersion uint64
	Version     uint64
	Committed   bool
	At          time.Time
	Duration    time.Duration
	Err         error
}

ActionTrace observes asynchronous task lifecycles. ID is the source Store action ID; RunID is local to its AsyncAction. Revision orders trace notifications even when callbacks overlap. Version identifies a published commit when Committed is true. Progress is monotonic for one task. Completion ActionEvents remain a separate, backward-compatible stream.

type AsyncAction added in v0.6.0 

type AsyncAction[T, I, R any] struct {
	// contains filtered or unexported fields
}

AsyncAction runs work outside the Store lock with an explicit commit policy. The default accepts only the latest uncanceled run per key. Input and result ownership follows Store's policy; copy mutable inputs before Run. Work must honor its context. Progress, status subscribers and action hooks can run on background goroutines.

func NewAsyncAction added in v0.6.0 

func NewAsyncAction[T, I, R any](store *Store[T], name string, work func(context.Context, I, func(float64)) (R, error), apply func(*T, R) error) (*AsyncAction[T, I, R], error)

func NewAsyncActionWithOptions added in v0.6.0 

func NewAsyncActionWithOptions[T, I, R any](store *Store[T], name string, work func(context.Context, I, func(float64)) (R, error), apply func(*T, R) error, options ActionOptions[I]) (*AsyncAction[T, I, R], error)

func (*AsyncAction[T, I, R]) Close added in v0.6.0 

func (a *AsyncAction[T, I, R]) Close(ctx context.Context) error

Close prevents new runs, cancels every active run and waits for cooperative work within ctx. The status store closes after the final run's terminal status. A timed-out Close can be called again to wait for remaining work. Do not Close synchronously from work, hooks or subscribers of this action; cancel there and close from the owner instead.

func (*AsyncAction[T, I, R]) Run added in v0.6.0 

func (a *AsyncAction[T, I, R]) Run(ctx context.Context, input I) (*Task, error)

Run accepts work according to ActionOptions. LatestWins supersedes the preceding task with the same key; QueueAll retains every accepted task. Canceled and superseded results never commit. ErrQueueFull rejects work without canceling existing tasks.

func (*AsyncAction[T, I, R]) Status added in v0.6.0 

func (a *AsyncAction[T, I, R]) Status() ReadOnly[AsyncState]

Status returns the observable status of the latest run, suitable for MyGo invalidation or DevTools attachment. Callers must not write to this store.

type AsyncOptions added in v0.3.0 

type AsyncOptions struct {
	Debounce time.Duration
}

AsyncOptions configures write-behind persistence. Debounce is a trailing-edge delay for bursts of updates; zero starts immediately. Flush bypasses the delay.

type AsyncPersistence added in v0.3.0 

type AsyncPersistence[T any] struct {
	// contains filtered or unexported fields
}

AsyncPersistence owns one worker and a bounded error stream. It coalesces updates without blocking writer goroutines on encoding or storage. Failed writes remain pending; the next update or Flush retries them without spinning. Values must be immutable or the store must use NewWithClone.

func (*AsyncPersistence[T]) Close added in v0.3.0 

func (a *AsyncPersistence[T]) Close(ctx context.Context) error

Close stops observing updates, flushes the final observed state, then stops the worker even if the flush fails. It is idempotent; concurrent callers wait on the same result with their own context. Do not mutate the store concurrently with Close if those changes must be included. Retry failed shutdown writes with Persistence.Save; a closed async writer cannot be restarted.

func (*AsyncPersistence[T]) Errors added in v0.3.0 

func (a *AsyncPersistence[T]) Errors() <-chan error

Errors reports failed write attempts. The bounded stream may drop errors if unread; Flush and Close return their write error directly. It closes on exit.

func (*AsyncPersistence[T]) Flush added in v0.3.0 

func (a *AsyncPersistence[T]) Flush(ctx context.Context) error

Flush waits until the version visible when called has been saved, bypassing debounce and retrying a previous failure. Canceling this wait does not cancel the shared worker. Later updates may be included in the same write.

type AsyncState added in v0.6.0 

type AsyncState struct {
	ID       uint64
	Name     string
	Running  bool
	Progress float64
	Error    string
	Phase    TaskPhase
	Key      string
	Revision uint64
}

AsyncState describes the latest run. Progress is between zero and one; Error is diagnostic text. Treat the action's status store as read-only.

type Codec 

type Codec[T any] interface {
	Encode(T) ([]byte, error)
	Decode([]byte) (T, error)
}

Codec serializes and restores one state value.

type Definition 

type Definition[T any] struct {
	// contains filtered or unexported fields
}

Definition is a reusable named store factory, analogous to Pinia's defineStore and Zustand's reusable vanilla store creator.

func Define 

func Define[T any](id string, initial func() T) *Definition[T]

Define creates a store definition. Each New call gets independent state.

func DefineWithClone added in v0.3.0 

func DefineWithClone[T any](id string, initial func() T, clone func(T) T) *Definition[T]

DefineWithClone creates a named factory with NewWithClone's isolation policy.

func (*Definition[T]) ID 

func (d *Definition[T]) ID() string

func (*Definition[T]) New 

func (d *Definition[T]) New() *Store[T]

type Derived 

type Derived[T any, V any] struct {
	// contains filtered or unexported fields
}

Derived is a memoized getter derived from a store. It recomputes when the source publishes and only notifies listeners when the selected value changes.

func Derive 

func Derive[T any, V any](source Reader[T], selector func(T) V, equals func(V, V) bool) *Derived[T, V]

func DeriveProjection added in v0.6.0 

func DeriveProjection[T any, V any](source Reader[T], project func(T) V, equals func(V, V) bool) *Derived[T, V]

DeriveProjection memoizes an owned projection without whole-source clones. It follows SubscribeProjection's ownership contract; returned reference values and listener arguments are read-only.

func (*Derived[T, V]) Close 

func (d *Derived[T, V]) Close() error

func (*Derived[T, V]) Get 

func (d *Derived[T, V]) Get() V

func (*Derived[T, V]) Subscribe 

func (d *Derived[T, V]) Subscribe(fn func(V)) func()

type FileStorage 

type FileStorage struct {
	Path string
	Perm os.FileMode
	// Backup writes an independent Path+".bak" copy after each successful primary replacement. A backup failure is returned even though the primary may already contain the new state. Use one Persistence writer per destination.
	Backup bool
}

FileStorage stores encoded state at Path. Save writes a temporary file in the same directory and renames it into place, so readers see a complete file.

func (FileStorage) Load 

func (f FileStorage) Load(ctx context.Context) ([]byte, error)

func (FileStorage) LoadBackup added in v0.6.0 

func (f FileStorage) LoadBackup(ctx context.Context) ([]byte, error)

func (FileStorage) Save 

func (f FileStorage) Save(ctx context.Context, data []byte) (err error)

type History 

type History[T any] struct {
	// contains filtered or unexported fields
}

History records successful store snapshots and provides bounded undo/redo.

func Track 

func Track[T any](store *Store[T], limit int) *History[T]

Track starts recording changes to store. limit is the maximum number of undo entries; values below one disable history recording.

func TrackWith added in v0.6.0 

func TrackWith[T any](store *Store[T], options HistoryOptions[T]) *History[T]

func (*History[T]) BeginGroup added in v0.6.0 

func (h *History[T]) BeginGroup() (func(), error)

BeginGroup merges edits across frames into one undo step while still publishing every update. Groups nest; the returned end function is idempotent. Concurrent writers join the group. Undo and Redo are rejected until all groups end. Filtering still applies, so a group containing only ignored changes adds no step.

func (*History[T]) CanRedo 

func (h *History[T]) CanRedo() bool

func (*History[T]) CanUndo 

func (h *History[T]) CanUndo() bool

func (*History[T]) Close 

func (h *History[T]) Close() error

Close stops recording future changes. It does not close the underlying store.

func (*History[T]) Redo 

func (h *History[T]) Redo() error

Redo restores the next state.

func (*History[T]) Undo 

func (h *History[T]) Undo() error

Undo restores the previous state.

type HistoryOptions added in v0.6.0 

type HistoryOptions[T any] struct {
	Limit   int
	Equals  func(previous, next T) bool
	Restore func(current, recorded T) T
}

HistoryOptions configures recording. Equals excludes changes to irrelevant fields. Restore merges recorded fields into current state so ignored fields survive travel. Both functions must be pure, must not mutate arguments, and must not reenter the Store or History; they can run while those locks are held. With nil callbacks, every publication records and travel replaces the whole value.

type JSONCodec 

type JSONCodec[T any] struct{}

JSONCodec encodes a store value using encoding/json.

func (JSONCodec[T]) Decode 

func (JSONCodec[T]) Decode(data []byte) (T, error)

func (JSONCodec[T]) Encode 

func (JSONCodec[T]) Encode(value T) ([]byte, error)

type JSONMigration added in v0.3.0 

type JSONMigration func(json.RawMessage) (json.RawMessage, error)

JSONMigration converts one schema version to the next. Inputs and outputs are state JSON, without the version envelope. Return an error to abort Load.

type LoadError added in v0.6.0 

type LoadError struct {
	Stage  string
	Backup bool
	Err    error
}

LoadError identifies the failing load stage without changing state or files. Backup distinguishes explicit backup loads. Unwrap preserves codec, validation and filesystem errors.

func (*LoadError) Error added in v0.6.0 

func (e *LoadError) Error() string

func (*LoadError) Unwrap added in v0.6.0 

func (e *LoadError) Unwrap() error

type Mutation 

type Mutation[T any] struct {
	ActionID uint64
	Type     MutationType
	Name     string
	Previous T
	Value    T
	Version  uint64
	At       time.Time
}

Mutation contains Pinia-like subscription metadata.

type MutationType 

type MutationType string

MutationType describes why a store published a snapshot. 

const (
	MutationDirect MutationType = "direct"
	MutationPatch  MutationType = "patch"
	MutationAction MutationType = "action"
	MutationReset  MutationType = "reset"
)

type PanicError added in v0.6.0 

type PanicError struct{ Value any }

PanicError reports a panic at the asynchronous user-code boundary. The Store may already have committed if a notification or completion hook panicked.

func (*PanicError) Error added in v0.6.0 

func (e *PanicError) Error() string

type Persistence 

type Persistence[T any] struct {
	// contains filtered or unexported fields
}

Persistence connects a store to a Storage and Codec. It is explicit by default: call Load at startup and Save after successful application actions. Save calls on the same instance are serialized, including state capture and encoding. Separate instances sharing a storage destination are not coordinated.

func NewPersistence 

func NewPersistence[T any](store *Store[T], storage Storage, codec Codec[T]) *Persistence[T]

func NewPersistenceWithOptions added in v0.6.0 

func NewPersistenceWithOptions[T any](store *Store[T], storage Storage, codec Codec[T], options PersistenceOptions[T]) *Persistence[T]

func (*Persistence[T]) AutoSave 

func (p *Persistence[T]) AutoSave(ctx context.Context) func()

AutoSave subscribes to updates and saves synchronously after each update. The returned function stops autosaving. Use Batch to coalesce writes.

func (*Persistence[T]) AutoSaveAsync added in v0.3.0 

func (p *Persistence[T]) AutoSaveAsync(ctx context.Context, options AsyncOptions) (*AsyncPersistence[T], error)

AutoSaveAsync subscribes and schedules the current state once, then all subsequent versions. Use Close before closing the store to drain writes. Parent cancellation and store closure stop the worker without a guaranteed drain. Storage.Save must respect context cancellation to bound shutdown time.

func (*Persistence[T]) AutoSaveWithErrors 

func (p *Persistence[T]) AutoSaveWithErrors(ctx context.Context) (<-chan error, func())

AutoSaveWithErrors subscribes to updates and reports persistence failures on a buffered channel. The channel closes when ctx is canceled or stop is called. Stop releases the background watcher but does not wait for in-flight saves.

func (*Persistence[T]) Load 

func (p *Persistence[T]) Load(ctx context.Context) error

func (*Persistence[T]) LoadBackup added in v0.6.0 

func (p *Persistence[T]) LoadBackup(ctx context.Context) error

LoadBackup explicitly restores validated backup state to memory. It never rewrites the primary file, so a corrupt original remains available for diagnosis. Call before starting autosave; a later Save intentionally writes the current state to disk.

func (*Persistence[T]) Save 

func (p *Persistence[T]) Save(ctx context.Context) error

type PersistenceOptions added in v0.6.0 

type PersistenceOptions[T any] struct{ Validate func(T) error }

PersistenceOptions validates decoded and saved state before it reaches the Store or storage. Validate must be pure and concurrency-safe, and must not mutate its input.

type ReadOnly added in v0.6.0 

type ReadOnly[T any] struct {
	// contains filtered or unexported fields
}

ReadOnly grants observation without Set, Update, Reset, action hooks or Close. Values still follow the source's cloning/immutability policy; this is a capability boundary, not a deep-freeze operation. Its zero value is an empty, invalid source (Done returns nil).

func (ReadOnly[T]) ActiveTasks added in v0.6.0 

func (r ReadOnly[T]) ActiveTasks() []ActionTrace

func (ReadOnly[T]) Done added in v0.6.0 

func (r ReadOnly[T]) Done() <-chan struct{}

func (ReadOnly[T]) Get added in v0.6.0 

func (r ReadOnly[T]) Get() T

func (ReadOnly[T]) ID added in v0.6.0 

func (r ReadOnly[T]) ID() string

func (ReadOnly[T]) Snapshot added in v0.6.0 

func (r ReadOnly[T]) Snapshot() Snapshot[T]

func (ReadOnly[T]) State added in v0.6.0 

func (r ReadOnly[T]) State() T

func (ReadOnly[T]) Subscribe added in v0.6.0 

func (r ReadOnly[T]) Subscribe(fn func(Snapshot[T])) func()

func (ReadOnly[T]) SubscribeActionTrace added in v0.6.0 

func (r ReadOnly[T]) SubscribeActionTrace(fn func(ActionTrace)) func()

func (ReadOnly[T]) SubscribeActions added in v0.6.0 

func (r ReadOnly[T]) SubscribeActions(fn func(ActionEvent)) func()

func (ReadOnly[T]) SubscribeMutations added in v0.6.0 

func (r ReadOnly[T]) SubscribeMutations(fn func(Mutation[T])) func()

func (ReadOnly[T]) SubscribeWith added in v0.6.0 

func (r ReadOnly[T]) SubscribeWith(options SubscribeOptions[T], fn func(Snapshot[T])) func()

func (ReadOnly[T]) TaskSnapshot added in v0.6.0 

func (r ReadOnly[T]) TaskSnapshot() TaskSnapshot

func (ReadOnly[T]) Version added in v0.6.0 

func (r ReadOnly[T]) Version() uint64

func (ReadOnly[T]) Watch added in v0.6.0 

func (r ReadOnly[T]) Watch(ctx context.Context, buffer int) <-chan Snapshot[T]

type Reader added in v0.6.0 

type Reader[T any] interface {
	Get() T
	State() T
	Snapshot() Snapshot[T]
	Version() uint64
	ID() string
	Done() <-chan struct{}
	Subscribe(func(Snapshot[T])) func()
	SubscribeWith(SubscribeOptions[T], func(Snapshot[T])) func()
	SubscribeMutations(func(Mutation[T])) func()
	SubscribeActions(func(ActionEvent)) func()
	SubscribeActionTrace(func(ActionTrace)) func()
	ActiveTasks() []ActionTrace
	TaskSnapshot() TaskSnapshot
	Watch(context.Context, int) <-chan Snapshot[T]
	// contains filtered or unexported methods
}

Reader is the observation surface shared by Store and ReadOnly. Only Nodra sources implement it; a read-only wrapper never exposes its backing Store. Snapshot ownership and callback concurrency are unchanged.

type Scope added in v0.6.0 

type Scope struct {
	// contains filtered or unexported fields
}

Scope owns a module's lifetime. Close cancels Context, stops observations, then runs deferred drains in reverse registration order. Register stores first, persistence second, and actions last so work finishes before persistence drains and stores close. Shared stores need not belong to a Scope.

func NewScope added in v0.6.0 

func NewScope() *Scope

func (*Scope) Close added in v0.6.0 

func (s *Scope) Close(ctx context.Context) error

Close starts shutdown once. Concurrent callers share its result but can stop waiting with their own context. The first caller supplies the drain context; resources receive that deadline even if the caller stops waiting. Persistence that must drain should use an independent worker context, not Scope.Context, which is canceled first.

func (*Scope) Context added in v0.6.0 

func (s *Scope) Context() context.Context

func (*Scope) Defer added in v0.6.0 

func (s *Scope) Defer(cleanup func(context.Context) error) error

Defer registers a context-aware drain. Late registrations run immediately with the original shutdown context and return ErrClosed plus any cleanup error. Drains must respect context cancellation and must not synchronously Close their own Scope.

func (*Scope) Done added in v0.6.0 

func (s *Scope) Done() <-chan struct{}

func (*Scope) Observe added in v0.6.0 

func (s *Scope) Observe(stop func()) error

Observe owns an unsubscribe function. A registration racing with Close is stopped immediately instead of leaking. Already executing source callbacks are not awaited.

type SelectorOptions 

type SelectorOptions[V any] struct {
	Immediate bool
	Equals    func(previous, next V) bool
}

SelectorOptions configures a selector subscription. With no Equals function, comparable values use == (including pointer identity); other values use reflect.DeepEqual. A custom comparator can use slices.Equal or maps.Equal.

type Snapshot 

type Snapshot[T any] struct {
	Value   T
	Version uint64
}

func Select added in v0.6.0 

func Select[T, V any](source Reader[T], project func(T) V) Snapshot[V]

Select reads an owned projection and source version without cloning the whole Store. project borrows read-only state under the read lock: it must not mutate or retain source references, reenter the Store, or block. Return scalars or copy all mutable references in the projection (for example with slices.Clone). Existing Get and SubscribeSelector keep their full-state isolation policy.

type Storage 

type Storage interface {
	Load(context.Context) ([]byte, error)
	Save(context.Context, []byte) error
}

Storage is the minimal persistence backend used by Persistence. Files, key-value databases and encrypted stores can implement it.

type Store 

type Store[T any] struct {
	// contains filtered or unexported fields
}

func Create 

func Create[T any](initial T) *Store[T]

Create is the Pinia/Zustand-style constructor name for a typed store.

func New 

func New[T any](initial T) *Store[T]

func NewWithClone added in v0.3.0 

func NewWithClone[T any](initial T, clone func(T) T) *Store[T]

NewWithClone isolates owned state, snapshots, subscriber values and rollback with clone. Clone must copy all mutable references, be safe for concurrent calls, and must not reenter the store. A nil clone preserves New's behavior.

func (*Store[T]) Action 

func (s *Store[T]) Action(name string, fn func(*T) error) func() error

Action returns a reusable named action function, matching Pinia action definitions while keeping Go's explicit function types.

func (*Store[T]) ActiveTasks added in v0.6.0 

func (s *Store[T]) ActiveTasks() []ActionTrace

ActiveTasks returns queued/running tasks independently of diagnostic sampling. The slice is owned by the caller.

func (*Store[T]) Batch 

func (s *Store[T]) Batch(fn func()) error

func (*Store[T]) Close 

func (s *Store[T]) Close() error

func (*Store[T]) Do 

func (s *Store[T]) Do(name string, fn func(*T) error) error

Do runs a named mutation and emits an action event after it completes.

func (*Store[T]) Done added in v0.6.0 

func (s *Store[T]) Done() <-chan struct{}

func (*Store[T]) Get 

func (s *Store[T]) Get() T

func (*Store[T]) ID 

func (s *Store[T]) ID() string

func (*Store[T]) Patch 

func (s *Store[T]) Patch(fn func(*T)) error

func (*Store[T]) ReadOnly added in v0.6.0 

func (s *Store[T]) ReadOnly() ReadOnly[T]

func (*Store[T]) Reset 

func (s *Store[T]) Reset() error

func (*Store[T]) Set 

func (s *Store[T]) Set(value T) error

func (*Store[T]) Snapshot 

func (s *Store[T]) Snapshot() Snapshot[T]

func (*Store[T]) State 

func (s *Store[T]) State() T

func (*Store[T]) Subscribe 

func (s *Store[T]) Subscribe(fn func(Snapshot[T])) func()

func (*Store[T]) SubscribeActionHooks 

func (s *Store[T]) SubscribeActionHooks(hooks ActionHooks) func()

SubscribeActionHooks registers lifecycle hooks and returns an unsubscribe function.

func (*Store[T]) SubscribeActionTrace added in v0.6.0 

func (s *Store[T]) SubscribeActionTrace(fn func(ActionTrace)) func()

func (*Store[T]) SubscribeActions 

func (s *Store[T]) SubscribeActions(fn func(ActionEvent)) func()

func (*Store[T]) SubscribeMutations 

func (s *Store[T]) SubscribeMutations(fn func(Mutation[T])) func()

func (*Store[T]) SubscribeWith 

func (s *Store[T]) SubscribeWith(options SubscribeOptions[T], fn func(Snapshot[T])) func()

func (*Store[T]) TaskSnapshot added in v0.6.0 

func (s *Store[T]) TaskSnapshot() TaskSnapshot

func (*Store[T]) Transaction 

func (s *Store[T]) Transaction(fn func(*T) error) error

func (*Store[T]) Update 

func (s *Store[T]) Update(fn func(*T)) error
Example 
package main

import (
	"fmt"

	"github.com/yldm-tech/nodra"
)

func main() {
	store := nodra.New(0)
	store.Subscribe(func(snapshot nodra.Snapshot[int]) {
		fmt.Println(snapshot.Value, snapshot.Version)
	})
	if err := store.Update(func(value *int) { *value = 42 }); err != nil {
		fmt.Println(err)
	}
}

Output:
42 1

func (*Store[T]) UpdateErr 

func (s *Store[T]) UpdateErr(fn func(*T) error) error

func (*Store[T]) Version 

func (s *Store[T]) Version() uint64

func (*Store[T]) Watch 

func (s *Store[T]) Watch(ctx context.Context, buffer int) <-chan Snapshot[T]

type SubscribeOptions 

type SubscribeOptions[T any] struct {
	Immediate bool
	Equals    func(previous, next T) bool
}

type Task added in v0.6.0 

type Task struct {
	ID uint64
	// contains filtered or unexported fields
}

Task is one run of an AsyncAction. Cancel requests cooperative cancellation; Wait waits for work and its completion notifications, independently of the waiter's context. Do not Wait from the task's own work, hooks or synchronous subscribers.

func (*Task) Cancel added in v0.6.0 

func (t *Task) Cancel()

func (*Task) Done added in v0.6.0 

func (t *Task) Done() <-chan struct{}

func (*Task) Status added in v0.6.0 

func (t *Task) Status() ReadOnly[AsyncState]

func (*Task) Wait added in v0.6.0 

func (t *Task) Wait(ctx context.Context) error

type TaskPhase added in v0.6.0 

type TaskPhase string
const (
	TaskQueued     TaskPhase = "queued"
	TaskRunning    TaskPhase = "running"
	TaskSucceeded  TaskPhase = "succeeded"
	TaskCanceled   TaskPhase = "canceled"
	TaskSuperseded TaskPhase = "superseded"
	TaskFailed     TaskPhase = "failed"
)

type TaskSnapshot added in v0.6.0 

type TaskSnapshot struct {
	Revision uint64
	Tasks    []ActionTrace
}

TaskSnapshot identifies current queued/running tasks and the source trace revision at capture time. Terminal tasks are released by the source; Task.Status retains their final state.

type VersionedJSONCodec added in v0.3.0 

type VersionedJSONCodec[T any] struct {
	Version          int
	Migrations       map[int]JSONMigration
	AllowUnversioned bool
}

VersionedJSONCodec stores {"schemaVersion": N, "state": ...}. Migrations[n] upgrades version n to n+1, sequentially. AllowUnversioned accepts legacy raw JSON as version zero. Version must be positive; future versions are rejected. Decode never writes storage: persist a successful upgrade explicitly with Save.

func (VersionedJSONCodec[T]) Decode added in v0.3.0 

func (c VersionedJSONCodec[T]) Decode(data []byte) (T, error)

func (VersionedJSONCodec[T]) Encode added in v0.3.0 

func (c VersionedJSONCodec[T]) Encode(value T) ([]byte, error)

Source Files

View all Source files

Directories

Path Synopsis
Package devtools provides an opt-in local inspector for Nodra stores.
 Package devtools provides an opt-in local inspector for Nodra stores.
examples
basic command
devtools command
Command devtools runs a counter with a live local inspector.
 Command devtools runs a counter with a live local inspector.
mygo command
Example mygo demonstrates two native windows sharing business state with independent redraw subscriptions.
 Example mygo demonstrates two native windows sharing business state with independent redraw subscriptions.
persistent command
Command persistent demonstrates cloned state, schema migration and write-behind persistence.
 Command persistent demonstrates cloned state, schema migration and write-behind persistence.
workbench command
Command workbench searches real local file names and edits persisted settings.
 Command workbench searches real local file names and edits persisted settings.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.