cell_flow library

A high-performance reactive orchestration layer for the Cell framework (codename Mitosis).

cell_flow extends the core atomicity of package:cell by providing a sophisticated suite of operators designed for complex data-flow transformations, temporal logic, and asynchronous coordination.

The Mitosis Architecture

While the core Cell library handles state and synchronous pulse propagation, Mitosis (cell_flow) provides the machinery for:

• Transformation: Reshaping data as it traverses the graph via operators like Flow.map, Flow.scan, and Flow.bufferCount.
• Temporal Control: Managing the dimension of time using Flow.debounce, Flow.throttle, Flow.delay, and Flow.interval.
• Asynchronous Bridging: Safely integrating Future and Stream workloads into the synchronous graph via Flow.asyncMap and Flow.switchMap.
• Topological Routing: Multiplexing and demultiplexing pulses through Flow.groupBy, Flow.partition, and Flow.windowCount.

Core Mechanics

1. Unified Graph: Unlike traditional Rx wrappers, cell_flow instructions are compiled directly into the underlying Cell graph. There is no "translation" overhead; a FlowHandle is a first-class citizen of the reactive topography.
2. Instruction-Based Composition: At its heart, the library uses FlowInstruction objects. These can be chained using the + operator to create reusable "Gate" definitions or "Receptors" independent of specific source cells.
3. Fluent API: For rapid development, the library provides comprehensive extensions on Cell and FlowHandle, allowing for a declarative, chainable syntax similar to RxDart.

Usage Paradigms

The Fluent Path (Quick Orchestration):

final results = searchInput.cell
    .filter((q) => q.length > 2)
    .debounce(duration: const Duration(milliseconds: 300))
    .asyncMap((q) => api.fetch(q))
    .share();

The Instruction Path (Reusable Gates):

// Define a reusable logic gate
final validationGate = MapValue<String, String>((s) => s.trim()) +
    Filter<String>((s) => s.isNotEmpty) +
    Distinct<String>();

// Apply the gate to any source
final handle = validationGate.toHandle(source: myCell);

Resource Management

Operators in cell_flow automatically manage their internal state and subscriptions. When a FlowHandle is disposed, the underlying orchestration graph is pruned to prevent memory leaks and unnecessary computations.

Further Reading

• ARCHITECTURE-Flow.md: Theoretical foundations of the Mitosis layer.
• FEATURES-Flow.md: Detailed catalog of every available operator.
• HowTo-Fluent_Operator.md: Best practices for method-chaining.
• HowTo-FlowInstruction-Receptor.md: Advanced custom gate composition.