result = abs(s.val) (reactive)

result = abs2(s.val) (squared magnitude)

Removes all key-value pairs in one step.

Effect on reactivity

• Pushes a single structural history entry (or joins the active transaction).
• Resets len(rt) to 0 and bumps rev(rt).
• Triggers any effects that depend on length or structure.

• Structural edit: sets length to 0 and increments rev(rs).
• Pushes one history entry (or merges into an active transaction).
• Effects that depend on length or structure rerun after the flush.

Raises no error when the sequence is already empty.

Purpose

Erases both the undo and redo stacks of the given context without altering current state.

When to call

• Before loading a fresh document or scene where old history should not apply.
• In tests that want to assert depth from a clean slate.

Pitfalls

• Users can no longer undo the edits made earlier in the session.
• Does not stop reactions; only history is cleared.

Creates a derived signal whose value is calculated by getter. The result is cached and recomputed only when any signal read inside getter has changed. If setter is supplied the computed signal becomes writable; calling set or pct.set(x) forwards the write to setter.

How it fits in

• Use computed for values that can be expressed entirely in terms of other signals.
• Effects depending on the computed signal see a single dependency instead of all the sources used inside getter.
• Writable computed signals let you expose a convenient virtual field (for example percent health) that writes back to one or more base signals.

Example

let pct = computed(ctx,
  getter = () => hp.val.float / maxHp.val.float,
  setter = (p: float) => hp.set int(p * maxHp.val.float))

echo pct.val   # read
pct.set 0.8    # write through setter

Pitfalls

• getter runs immediately when computed is created; avoid heavy work or side effects inside it.
• Do not call set on the computed signal from inside its own getter; that would cause infinite recursion.
• If setter writes the same value back into the sources the engine detects no change and pushes no history entry.

Removes key from the reactive table if it exists.

Reactive effects

• Structural operation; bumps rev(rt) and updates len(rt).
• Pushes a history entry (or merges into an open transaction).
• Effects that depend on length or on rev(rt) rerun.

Keys that are not present are ignored and no history entry is added.

Turns off automatic persistence for the context. No further snapshots are written to the JSON node that was previously passed to enableAutosave.

Effect

• Clears the autosave flag and the stored node reference.
• Does not perform a final save; call flushQueued(ctx) first if you need the latest state persisted.

Pitfalls

• After disabling, edits to store signals will not reach the old JSON node unless autosave is enabled again or saveState is called manually.

Stops all reactive activity owned by ctx and frees its resources.

What happens

• If autosave is active a final snapshot is written before shutdown.
• Pending reaction queues and history stacks are cleared.
• Scheduler is replaced with a no-op and currentObserver is set to nil, so no further reactions run.
• ctx.isDisposed becomes true; helper procs treat the context as dead.

Typical usage

let ctx = newReactiveCtx()
...
dispose ctx      # when the data set or UI panel is closed

Pitfalls

• Writing to a signal after disposal mutates its raw value but triggers no reactions or autosave.
• A disposed context cannot be revived. Create a new context instead.
• Transactions open at the moment of disposal are silently cancelled.

Registers body as a reactive side effect. The procedure runs once immediately, collects every signal it reads, and is scheduled to run again whenever any of those signals changes.

Purpose

Effects are the bridge from reactive data to the outside world. Use them for printing, updating the UI, sending network messages, or any work whose result is not itself a signal.

How it works

• During the first call ctx.currentObserver is set to the callback so every signal read registers the dependency automatically.
• Later writes to any of those signals schedule the effect.
• If the active scheduler is queued or frame based, the run happens on the next flushQueued(ctx) or frame tick.
• Dependencies are re-collected on every run; if body stops reading a signal it will be unsubscribed.

Example

effect(ctx, proc () =
  echo "HP:", hp.val, "/", maxHp.val
)

Pitfalls

• Do not mutate signals inside the same effect that reads them unless you are certain it will not cause infinite loops.
• An effect runs even if the computed result is identical; add manual checks if you need extra deduplication.
• Heavy work should be batched or throttled to avoid frame drops under rapid updates.

Registers a reactive side effect that can schedule cleanup callbacks. body receives an onCleanup function; every Cleanup registered with it runs right before the effect re executes or when the context is disposed.

Purpose

Same as the simple effect, plus deterministic setup and teardown of resources such as timers, event listeners, or file handles.

Usage pattern

effect(ctx, proc (onCleanup: AddCleanup) =
  let id = setTimer(1000, tick)
  onCleanup(() => clearTimer(id))
)

• First run: acquire resources, register cleanups, establish dependencies.
• On every re run: all cleanups fire, then the body executes again.
• On dispose(ctx): any remaining cleanups run once.

Pitfalls

• Register each resource exactly once; adding inside loops can leak callbacks.
• Cleanups run even when signal values did not change if the effect still re evaluates. Keep them lightweight and idempotent.
• Avoid calling onCleanup conditionally based on signal values that may differ between runs; otherwise the number of callbacks can grow unbounded.

Executes body immediately and never schedules it again, even if the procedure reads signals that later change. Dependency tracking is disabled during the call.

Purpose

Use effectOnce for one time side effects such as logging, initialising third party libraries, or writing a first snapshot after startup.

Example

effectOnce(ctx, proc () =
  echo "Initial HP:", hp.val
)

Pitfalls

• Because no dependencies are collected, later updates do not trigger the procedure. Choose a normal effect if you need ongoing reactivity.
• Cleanups cannot be registered; allocate resources only if they live for the full lifetime of the context.

Activates automatic persistence for all store-registered signals in ctx. The current values are written into target immediately and once per flush whenever any store signal changes.

How it works

• If target is nil a new empty JSON object is created.
• Every call to flushQueued(ctx) (or an automatic flush by the scheduler) serialises the latest store snapshot into the same JSON node. Existing keys are overwritten, other keys in target remain.
• On dispose(ctx) a final snapshot is written.

Typical usage

var doc: JsonNode
enableAutosave(ctx, doc)      # initial snapshot
gold += 10                    # mutate a store signal
flushQueued ctx               # doc updated

Pitfalls

• Keep target alive as long as autosave is enabled; if you reassign the variable the library keeps the old reference.
• Call disableAutosave(ctx) before switching to a new node to avoid unintentionally writing into both.
• Immediate scheduler writes right away; queued or frame schedulers require an explicit flush or a frame tick.

Runs all reactions currently waiting in ctx.queue and then, if autosave is enabled and the context is marked dirty, writes one snapshot to the autosave JSON node.

Purpose

Use flushQueued when working with the queued or frame schedulers if you need to force updates immediately, or in automated tests where you want deterministic timing without depending on the scheduler loop.

What it does

• Copies the current queue, clears it, and executes each reaction once.
• Clears queueHashes so the same reaction can be queued again later.
• If autosave is active and any write happened since the last snapshot, serialises the store signals into the target JSON node.

Typical usage

useQueuedScheduler(ctx)
value.set 42       # effect is queued
flushQueued ctx    # run it right now

Pitfalls

• Do not call inside a transaction; the batch is not finished until the outer transaction flushes.
• Immediate scheduler users never need this call because reactions run at once.
• Flushing very often defeats the coalescing benefit of queued schedulers.

Replaces the values of all store-registered signals in ctx with the contents of src. Keys that are missing in src leave their signals unchanged. Signals not registered with store or registerStore are unaffected.

Typical workflow

var snapshot: JsonNode
saveState(ctx, snapshot)   # later...
loadState(ctx, snapshot)   # restore previous snapshot

Effects on history and reactions

• Each setter call triggered by loadState pushes its own undo record unless the context is inside isUndoing, isRedoing, or isDisposed.
• Reactions fire normally after the load; wrap the call in transaction(ctx) if you want one coalesced update.

Pitfalls

• src must not be nil; pass an empty object to clear all stored keys.
• Data types are not validated beyond basic conversion; loading a float into an int signal raises a value error.
• The redo stack is cleared after the first new write; if you load a snapshot and then set a signal manually the forward history is lost.

Creates a memoised selector. The returned closure reads its cached value without tracking dependencies, while an internal effect keeps that cache up to date by running selector again only when any of the signals it reads change.

Purpose

Use memo to avoid expensive recalculation or to expose a selector that can be read many times without causing additional reactivity churn.

How it works

• On creation selector runs once, collects its dependencies, and stores the result.
• An internal effect reruns selector when any dependency changes and updates the cache.
• The returned closure just returns the current cache, adding itself as a dependency of callers.

Example

let sum = memo(ctx, () => a.val + b.val)
echo sum()   # fast cached read

Pitfalls

• Do not call memo inside another effect if the selector performs heavy work; create it once at module or context setup time.
• Values are compared with !=; if T has complex equality rules make sure that still detects real changes.
• The memo itself never pushes undo history; only the underlying signal writes do.

Constructs and returns a fresh ReactiveCtx with the default immediate scheduler and empty history, queues, and store list.

When to call

• At application startup to create the primary reactive graph.
• Inside tests or short-lived components to obtain an isolated context that can be disposed without affecting the rest of the program.

The new context is clean: undoDepth, redoDepth, and queue.len are all zero, isDisposed is false, and autosave is disabled.

result = phase(s.val) (argument / angle)

Appends x to the end of the reactive sequence.

Reactive effects

• Structural edit: length grows by 1 and rev(rs) increments.
• Pushes one history entry or merges into an open transaction.
• Effects that depend on length or structure rerun.

always equals abs(z.val) (== z.val.polar.r)

Removes the element at idx from a ReactiveSeq.

Effects

• Structural edit: len(rs) and rev(rs) update.
• Pushes one history entry (or merges into an open transaction).
• Triggers effects that depend on length or structure.

Raises IndexDefect if idx is out of range.

Writes a snapshot of all store-registered signals in ctx into dest.

Rules

• Allocates a new JSON object when dest is nil.
• Overwrites existing keys that match store entries; leaves others untouched.
• Does not clear history or fire reactions.

Use before closing a document or for manual export; for continuous persistence prefer enableAutosave.