titan_bastion library

Titan Flutter — Reactive state management for Flutter.

The Titan Architecture

Concept	Titan Name	Purpose
Store / Bloc	Pillar	Structured state with lifecycle
State	Core	Reactive mutable value
Consumer	Vestige	Auto-tracking UI builder
Provider	Beacon	Scoped Pillar delivery
Dispatch	Strike	Batched state mutation

Quick Start

import 'package:titan_bastion/titan_bastion.dart';

// 1. Define a Pillar
class CounterPillar extends Pillar {
  late final count = core(0);
  late final doubled = derived(() => count.value * 2);
  void increment() => strike(() => count.value++);
}

// 2. Register
Titan.put(CounterPillar());

// 3. Consume
Vestige<CounterPillar>(
  builder: (context, counter) => Text('${counter.count.value}'),
)

Organized App

Beacon(
  pillars: [CounterPillar.new, AuthPillar.new],
  child: MaterialApp(
    home: Vestige<CounterPillar>(
      builder: (context, counter) => Scaffold(
        body: Center(child: Text('${counter.count.value}')),
        floatingActionButton: FloatingActionButton(
          onPressed: counter.increment,
          child: Icon(Icons.add),
        ),
      ),
    ),
  ),
)

Classes

Aegis: Resilient async operations with configurable retry logic.
AegisConfig: Configuration for an Aegis retry operation.
AegisResult<T>: Result of an Aegis retry operation.
AnimatedVestige: AnimatedVestige — A Pillar consumer with implicit animation support.
AnnalEntry: A single entry in the audit trail.
Annals: Centralized, immutable audit trail manager.
AsyncData<T>: Successful async state with data.
AsyncError<T>: Error async state.
AsyncLoading<T>: Loading async state (no previous data available).
AsyncRefreshing<T>: Refreshing async state — loading with previous data preserved.
AsyncValue<T>: Represents the state of an asynchronous operation.
Beacon: Beacon — Shines Pillar state down to all children.
BeaconScope: Provides static helpers for finding Pillars in the widget tree.
Breadcrumb: A breadcrumb records a notable event that occurred before an error.
Bulwark<T>: A reactive circuit breaker.
Chronicle: Chronicle — Titan's structured logging system.
ClampConduit<T extends num>: A Conduit that clamps numeric values to a min–max range.
Codex<T>: Codex — Paginated data management with reactive state.
CodexPage<T>: A page of data returned by a paginated fetch.
CodexRequest: A request for a page of data.
Conduit<T>: A pipeline stage that intercepts individual Core state changes.
Confluence2<A extends Pillar, B extends Pillar>: Confluence — Where multiple Pillars converge in a single builder.
Confluence3<A extends Pillar, B extends Pillar, C extends Pillar>: Confluence3 — Where three Pillars converge in a single builder.
Confluence4<A extends Pillar, B extends Pillar, C extends Pillar, D extends Pillar>: Confluence4 — Where four Pillars converge in a single builder.
ConsoleErrorHandler: A simple ErrorHandler that logs errors to the console.
ConsoleLogSink: A console LogSink with formatted, colorized output.
CoreChange<T>: A recorded change on a Core.
Crucible: A testing harness for Pillars.
DebouncedState<T>: A TitanState that debounces updates from a source.
Epoch<T>: A TitanState with undo/redo history.
ErrorContext: Contextual information about where and why an error occurred.
ErrorHandler: A pluggable error handler (sink) for Vigil.
FilteredErrorHandler: A filtering ErrorHandler that only forwards errors matching a condition.
FreezeConduit<T>: A Conduit that prevents state changes once a condition is met.
Herald: Herald — The Titan Event Bus.
HeraldEvent: A wrapper for globally-captured Herald events.
InMemoryRelicAdapter: An in-memory RelicAdapter for testing.
Lens: Lens — Titan's in-app debug overlay.
LensLogSink: A LogSink that captures LogEntry records into a bounded buffer.
LogEntry: A structured log entry with level, message, and optional context.
LogSink: A pluggable output destination for log entries.
Loom<S, E>: A reactive finite state machine.
LoomTransition<S, E>: A record of a state machine transition.
Obs: Ultra-simple auto-tracking reactive widget builder.
Pillar: The fundamental organizing unit of Titan's state management.
PillarScope: PillarScope — Override multiple Pillar instances for a subtree.
PillarSnapshot: An immutable snapshot of a Pillar's named Core values.
Quarry<T>: Quarry — Reactive data fetching with caching and stale-while-revalidate.
QuarryRetry: Configuration for retry behavior.
Rampart: A responsive layout builder that adapts to screen width.
RampartBreakpoints: Breakpoint thresholds for responsive layout tiers.
RampartValue<T>: A responsive adaptive value that varies by layout tier.
RampartVisibility: Selectively show or hide a child based on the layout tier.
ReactiveNode: Base class for all reactive primitives in Titan.
ReactiveScope: Global reactive tracking scope.
Relic: Relic — Preserves state across sessions.
RelicAdapter: A pluggable storage backend for Relic.
RelicEntry<T>: Describes how to persist and restore a single TitanState (Core).
Saga<T>: A multi-step async workflow orchestrator with compensating actions.
SagaStep<T>: A single step in a Saga workflow.
Scroll<T>: Scroll — A form field with validation, dirty tracking, and reset.
ScrollGroup: ScrollGroup — Manages a collection of Scroll fields as a form.
Sigil: A centralized, reactive feature flag registry.
Snapshot: Snapshot utilities for capturing and restoring Pillar state.
StateChangeRecord: A record of a single state change.
StrikeMiddleware: Middleware that intercepts Pillar.strike and Pillar.strikeAsync calls.
Tether: Typed request-response channel registry for Pillar inter-communication.
ThrottleConduit<T>: A Conduit that debounces rapid value changes, keeping only the last.
ThrottledState<T>: A TitanState that throttles updates from a source.
Titan: Titan — The global registry for your app's Pillars and services.
TitanAsyncBuilder<T>: A widget for rendering async state with loading, error, and data states.
TitanAsyncState<T>: A reactive state container for asynchronous operations.
TitanBuilder: A widget that automatically rebuilds when reactive values change.
TitanComputed<T>: A derived reactive value that automatically tracks its dependencies.
TitanConfig: Global configuration for Titan.
TitanConsumer<T extends TitanStore>: A widget that provides access to a TitanStore and rebuilds reactively.
TitanContainer: A lightweight dependency injection container for Titan stores.
TitanEffect: A reactive side effect that automatically tracks dependencies and re-runs when they change.
TitanError: A captured error with full context, severity, and timestamp.
TitanHistoryObserver: An observer that records state change history for time-travel debugging.
TitanLoggingObserver: A simple logging observer that prints state changes.
TitanModule: A module for organizing related store registrations.
TitanObserver: Global observer for all Titan state changes and lifecycle events.
TitanScope: Provides a TitanContainer to the widget subtree.
TitanSelector<T>: A widget that selects and watches a specific value from reactive state.
TitanSimpleModule: A convenience module created from a list of store factories.
TitanState<T>: A mutable reactive state container.
TitanStore: Base class for organized state containers.
TransformConduit<T>: A Conduit that applies a transformation function to new values.
ValidateConduit<T>: A Conduit that validates new values and rejects invalid ones.
Vestige: Vestige — The visible trace of a Pillar's power in the UI.
VestigeConsumer: VestigeConsumer — Combines building and listening in one widget.
VestigeListener: VestigeListener — Reacts to Pillar state changes without rebuilding.
VestigeRaw: VestigeRaw — A raw reactive builder without Pillar typing.
VestigeSelector: VestigeSelector — Select a sub-value from a Pillar for fine-grained rebuilds.
VestigeWhen: VestigeWhen — Conditional widget rendering based on Pillar state.
Vigil: Vigil — The eternal watch over errors.
Volley<T>: A batch async executor with concurrency control and progress tracking.
VolleyFailure<T>: A failed task result.
VolleyResult<T>: The result of a single VolleyTask.
VolleySuccess<T>: A successful task result.
VolleyTask<T>: A single task in a Volley batch.
WhenCase: A condition-builder pair for VestigeWhen.

Enums

BackoffStrategy: Strategy for calculating retry delays.
BulwarkState: The three states of a circuit breaker.
ErrorSeverity: The severity level of a tracked error.
LogLevel: Log severity levels, ordered from least to most severe.
RampartLayout: The current responsive layout tier.
SagaStatus: The status of a Saga execution.
VolleyStatus: The status of a Volley execution.

Mixins

TitanStateMixin<T extends StatefulWidget>: A mixin that adds reactive capabilities to a StatefulWidget's State.

Extensions

BeaconContext on BuildContext: Extension methods on BuildContext for accessing Pillars.
CoreBoolExtensions on TitanState<bool>: Convenience methods for Core<bool>.
CoreDoubleExtensions on TitanState<double>: Convenience methods for Core<double>.
CoreIntExtensions on TitanState<int>: Convenience methods for Core<int>.
CoreListExtensions on TitanState<List<T>>: Convenience methods for Core<List<T>>.
CoreMapExtensions on TitanState<Map<K, V>>: Convenience methods for Core<Map<K, V>>.
FluxComputedExtensions on TitanComputed<T>: Stream-like operators for TitanComputed (Derived).
FluxNodeExtensions on ReactiveNode: Stream conversion for any ReactiveNode.
FluxStateExtensions on TitanState<T>: Stream-like operators for TitanState (Core).
RampartContext on BuildContext: Extension on BuildContext for responsive helpers.
TitanContextExtensions on BuildContext: Extension methods on BuildContext for Titan state management.

Functions

titanBatch(void updates()) → void: Groups multiple state changes into a single notification cycle.
titanBatchAsync(Future<void> updates()) → Future<void>: Async version of titanBatch.
titanContainerOf(BuildContext context) → TitanContainer: Provides access to the nearest TitanContainer from the widget tree.

Typedefs

Core<T> = TitanState<T>: Core — The indestructible center of a Pillar.
Derived<T> = TitanComputed<T>: Derived — A reactive value forged from Cores.
ReactiveListener = void Function(): Callback signature for listening to reactive node changes.

Exceptions / Errors

BulwarkOpenException: Exception thrown when a call is attempted on an open circuit breaker.
ConduitRejectedException: Thrown by a Conduit.pipe to reject a state change.

titan_bastion library

The Titan Architecture

Quick Start

Organized App

Classes

Enums

Mixins

Extensions

Functions

Typedefs

Exceptions / Errors

titan_bastion package

titan_bastion library