titan library

Titan — Total Integrated Transfer Architecture Network

A uniquely powerful reactive state management architecture for Dart & Flutter.

The Titan Lexicon

Concept Titan Name Why
Store / Bloc Pillar Titans held up the sky; Pillars hold up your app
Dispatch / Add Strike Fast, decisive, powerful
State Core The indestructible center of the Pillar
Consumer Vestige The UI — a visible trace of underlying power
Provider Beacon Shines state down to all children

Quick Start

import 'package:titan_bastion/titan_bastion.dart';

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

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

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

Primary API

  • Pillar — Structured state module with lifecycle
  • Core / core — Reactive mutable state
  • Derived / derived — Reactive computed values
  • strike — Batched state mutations
  • Titan — Global Pillar registry & DI
  • Herald — Cross-Pillar event bus
  • Vigil — Centralized error tracking

Advanced API

Classes

Aegis
Resilient async operations with configurable retry logic.
AegisConfig
Configuration for an Aegis retry operation.
AegisResult<T>
Result of an Aegis retry operation.
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.
A breadcrumb records a notable event that occurred before an error.
Chronicle
Chronicle — Titan's structured logging system.
ClampConduit<T extends num>
A Conduit that clamps numeric values to a min–max range.
Conduit<T>
A pipeline stage that intercepts individual Core state changes.
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<P extends Pillar>
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.
Ledger
Ledger — Reactive state transaction manager.
LedgerRecord
Record of a completed transaction for history/audit.
LedgerTransaction
A single atomic transaction scope.
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.
Mandate
Reactive policy evaluation engine.
MandateDenial
One or more required writs failed — access is denied.
MandateGrant
All required writs passed — access is granted.
MandateVerdict
Result of evaluating a Mandate's policies.
NexusBatch<T>
Multiple changes occurred (e.g., addAll, removeWhere).
NexusChange<T>
Describes a change to a NexusList, NexusMap, or NexusSet.
NexusClear<T>
The collection was cleared.
NexusInsert<T>
An element was inserted into a list.
NexusList<T>
NexusList — A reactive, observable list with granular change tracking.
NexusMap<K, V>
NexusMap — A reactive, observable map with granular change tracking.
NexusMapRemove<K, V>
A key-value pair was removed from a map.
NexusMapSet<K, V>
A key-value pair was set in a map.
NexusRemove<T>
An element was removed from a list.
NexusSet<T>
NexusSet — A reactive, observable set with granular change tracking.
NexusSetAdd<T>
An element was added to a set.
NexusSetRemove<T>
An element was removed from a set.
NexusUpdate<T>
An element was updated in a list at a specific index.
Omen<T>
Reactive async computed value with automatic dependency tracking.
Pillar
The fundamental organizing unit of Titan's state management.
PillarSnapshot
An immutable snapshot of a Pillar's named Core values.
Prism<T>
Prism — A fine-grained, memoized state projection.
PrismEquals
Structural equality comparators for use with Prism.
ReactiveNode
Base class for all reactive primitives in Titan.
ReactiveScope
Global reactive tracking scope.
ReadCore<T>
A read-only view of a TitanState (Core).
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).
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.
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.
TitanAsyncState<T>
A reactive state container for asynchronous operations.
TitanComputed<T>
A derived reactive value that automatically tracks its dependencies.
TitanConfig
Global configuration for Titan.
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.
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.
Vigil
Vigil — The eternal watch over errors.
Writ
A single policy rule evaluated by a Mandate.
WritViolation
Details of a Writ that failed evaluation.

Enums

BackoffStrategy
Strategy for calculating retry delays.
ErrorSeverity
The severity level of a tracked error.
LedgerStatus
Status of a LedgerTransaction.
LogLevel
Log severity levels, ordered from least to most severe.
MandateStrategy
Combination strategy for evaluating multiple Writ rules.

Extensions

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).
PrismCoreExtension on TitanState<T>
Extension on TitanState providing the prism method for ergonomic sub-value selection.

Functions

titanBatch(void updates()) → void
Groups multiple state changes into a single notification cycle.
titanBatchAsync(Future<void> updates()) → Future<void>
Async version of titanBatch.

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

ConduitRejectedException
Thrown by a Conduit.pipe to reject a state change.