advanced library

Advanced / framework-adjacent surface of package:armature.

Import this barrel when you need:

• handler / callback typedefs for explicit field annotations (BehaviorHandler, PipeHandler, TaskFn, VoidTask, StateChangeListener, StateListenerDisposer, StateUpdateCallback);
• the individual TaskStrategy* classes (usually you reach for factories on TaskStrategy — .queue, .once, .debounce(...) — and never touch these directly);
• debug-overlay mirrors of the live container (ContainerDebug, FeatureDebugInfo, FeatureDependency, PortDebugInfo);
• LoggerDebugInfo for implementing a custom Logger.

Everything here is deliberately kept out of the main package:armature/armature.dart barrel to keep discovery sharp — typical feature / store / task code should not need this import.

Classes

ContainerDebug

Structured, read-only snapshot of an AppContainer for debug tooling.

FeatureDebugInfo

Debug info for a single feature.

FeatureDependency

A parent-of link from one feature to another with required/optional distinction.

LoggerDebugInfo

Provides structured debug metadata for logging.

PortDebugInfo

Debug info for a single port registered by a feature.

TaskStrategyDebounce

Coalesce-burst strategy: each call restarts a quiet timer; the function fires once after duration passes with no further calls. See TaskStrategy.debounce.

TaskStrategyLatest

Supersede-and-share strategy: a new call cancels the in-flight one; all pending callers share the latest run's outcome. See TaskStrategy.latest.

TaskStrategyOnce

Cache-and-share strategy: the function runs once; later calls share the cached result (or in-flight future). See TaskStrategy.once.

TaskStrategyQueue

FIFO serialise strategy: each call awaits the previous one to settle before its own work begins. See TaskStrategy.queue.

TaskStrategyThrottle

Rate-limit strategy: at most one run per duration window. The edge selects which call within the window actually drives the run. See TaskStrategy.throttle.

VoidTask<TResult, TError>

A Task that takes no parameter. Call it with task() — no null required. Created via createVoid or Store.createVoidTask.

Extensions

ContainerDebugExtensions on AppContainer

Builds a fresh ContainerDebug snapshot. Re-invoke to refresh — nothing is cached; each call walks the live graph.

Typedefs

BehaviorHandler<TBranch extends Enum, TPayload extends Object?> = BehaviorDescriptor<TBranch, TPayload>? Function(FeatureHandlerContext ctx)

Handler that produces a BehaviorDescriptor from feature context.

PipeHandler<TValue> = TValue Function(TValue value, FeatureHandlerContext ctx)

Handler that transforms a pipe value with access to feature context.

StateChangeListener<TState> = void Function(TState prevState, TState state)

Invoked by State.subscribe on every state transition.

StateListenerDisposer = void Function()

Disposer returned by State.subscribe. Call to remove the listener; idempotent — repeated calls are safe no-ops.

StateUpdateCallback<TState> = TState Function(TState state)

Produces the next state from the current state. Passed to State.update (and re-exported via Store.update) for functional updates that don't need a temp variable.

TaskFn<TParams, TResult, TError> = Future<TResult> Function(TParams params)

Async function executed by a Task.