---

Reactive Systems in Crystal: The Ultimate Guide to Automatic Data Flow

A reactive system in Crystal provides an elegant way to manage state by creating cells whose values automatically update when their dependencies change. This paradigm, inspired by spreadsheets, lets you define data relationships declaratively, and the system handles the propagation of changes, eliminating complex manual state management and boilerplate code.

---

The Spreadsheet Nightmare: Why Manual State Management is Broken

Imagine you're building a complex dashboard. You have a base value, say, `revenue`. Dozens of other components depend on it: `profit`, `tax`, `commission`, `projectedGrowth`, and various charts and graphs. Now, the user changes the `revenue`. What happens next is a cascade of manual, error-prone updates. You have to remember to call `updateProfit()`, which then needs to trigger `updateTax()`, and so on. Miss one step, and your entire UI shows inconsistent data.

This imperative, step-by-step approach is fragile. It clutters your code with update logic, making it hard to read and even harder to maintain. What if you could just declare the relationships—`profit` is `revenue - costs`, `tax` is `profit * 0.2`—and let the system handle the rest? That's the promise of reactive programming, a paradigm that turns this chaotic nightmare into an elegant, automated data flow. In this guide, we'll build a reactive system from scratch using the power and expressiveness of Crystal.

---

What Exactly is a Reactive System?

A reactive system is a programming model built around data flows and the propagation of change. The core idea is that you can define a value that is computed based on other values. Whenever one of the source values (dependencies) changes, the computed value is automatically recalculated and updated without any explicit intervention from the programmer.

Think of a simple spreadsheet:

• Cell A1 has the value 10.
• Cell B1 has the value 20.
• Cell C1 has the formula =A1+B1. Its value is automatically 30.

If you change the value in A1 to 15, cell C1 instantly and automatically updates to 35. You didn't write code to "watch" for changes in A1 or manually call an update function for C1. You simply declared the relationship, and the spreadsheet engine handled the "reaction."

The Core Components

A basic reactive system, like the one we'll build, consists of a few key parts:

1. Input Cells: These are the fundamental building blocks. They hold a raw, settable value. In our spreadsheet analogy, A1 and B1 are input cells. You can directly change their content.
2. Compute Cells: These cells derive their value from one or more other cells (either input or other compute cells). Their value is defined by a computation function. C1 is a compute cell. You cannot set its value directly; it's determined entirely by its formula and dependencies.
3. The Reactor: This is the orchestrator or the "engine" of the system. It's responsible for creating cells and managing the dependency graph—the network of relationships between cells.
4. Callbacks: These are actions (side effects) that get triggered when a compute cell's value changes. For example, a callback could print a new value to the console, update a UI element, or send a notification.

Under the hood, this is often implemented using the Observer Design Pattern, where compute cells "subscribe" to changes in the cells they depend on. When a source cell changes, it "notifies" all its subscribers, triggering a chain reaction of updates.

    ● Input Cell `A` (value: 10)
    │
    ├─ is a dependency for ─▶ ● Compute Cell `C`
    │                         │ (formula: A + B)
    │
    ● Input Cell `B` (value: 5)
    │
    └─ is a dependency for ─▶ ● Compute Cell `C`
                              │
                              ▼
                         Current Value of `C` is 15

---

Why Bring Reactivity to Crystal?

Crystal is known for its performance, type safety, and clean, Ruby-like syntax. These features make it an excellent candidate for building robust and maintainable systems. Integrating a reactive paradigm offers several compelling advantages:

• Declarative Code: You describe what the relationships are, not how to maintain them. This leads to code that is more readable and closer to the business logic. Instead of `if revenue_changed then update_profit()`, you simply say `profit = revenue - costs`.
• Reduced Boilerplate: It eliminates the need for manual event listeners, state-checking logic, and chains of update calls. This significantly cleans up your codebase, especially in applications with complex, interconnected state.
• Predictable State Management: With a clear, unidirectional data flow, it becomes much easier to reason about how your application's state changes over time. Debugging is simplified because you can trace changes through the dependency graph.
• Composability: Reactive components (cells) are highly composable. You can build complex computations by layering simple compute cells on top of each other, just like building complex formulas in a spreadsheet.

While Crystal doesn't have a built-in reactive system in its standard library, its powerful metaprogramming, blocks, and type system make it straightforward to implement an elegant and efficient one, as we'll demonstrate in the exclusive kodikra.com curriculum.

---

How to Build a Reactive System in Crystal: A Deep Dive

Let's roll up our sleeves and build this system from the ground up. Our goal is to create a Reactor class that can manage InputCells and ComputeCells. The system must ensure that any change to an InputCell propagates correctly through the dependency graph.

The Core Logic and Data Structures

First, we need to define the interfaces and classes for our cells. We'll have a parent Cell module to define a common API.

• InputCell(T): A generic class to hold a value of type T. It will have a public `value=` setter.
• ComputeCell(T): A generic class that takes a list of dependency cells and a block (the compute function). It will not have a public setter. Its value is memoized (cached) and only re-evaluated when a dependency changes.
• Reactor: The factory class. It will be responsible for creating cells and tracking the dependency graph. It will also manage callbacks.

The Complete Crystal Solution

Here is the full, commented implementation based on the principles discussed. This code is part of the Crystal learning path at kodikra.com.

# The main orchestrator for the reactive system.
# It acts as a factory for creating different types of cells.
class Reactor(T)
  # Abstract base module for all cell types.
  # Ensures that every cell has a `value` method.
  module Cell(T)
    abstract def value : T
  end

  # Represents a cell with a settable value. This is the source of all changes.
  class InputCell
    include Cell(T)

    @_value : T
    # A list of compute cells that depend on this input cell.
    @dependents : Array(ComputeCell)

    def initialize(@_value : T)
      @dependents = [] of ComputeCell
    end

    # Public getter for the cell's value.
    def value : T
      @_value
    end

    # Public setter. This is the heart of the propagation logic.
    # When the value changes, it triggers updates in all dependent cells.
    def value=(new_value : T)
      return if @_value == new_value
      @_value = new_value
      # Notify all dependents that they need to recompute.
      @dependents.each(&.recompute)
    end

    # Internal method to register a dependent compute cell.
    def add_dependent(cell : ComputeCell)
      @dependents << cell
    end
  end

  # Represents a cell whose value is computed from other cells.
  class ComputeCell
    include Cell(T)

    @dependencies : Array(Cell(T))
    @compute_function : Proc(T)
    @_value : T
    # Is the current cached value valid or does it need re-computation?
    @is_stale : Bool
    # A list of other compute cells that depend on *this* compute cell.
    @dependents : Array(ComputeCell)
    # A list of callbacks to execute when this cell's value changes.
    @callbacks : Array(Proc(T, Nil))

    def initialize(@dependencies : Array(Cell(T)), &@compute_function : Proc(T))
      @dependents = [] of ComputeCell
      @callbacks = [] of Proc(T, Nil)
      @is_stale = true # Start as stale to compute on first access.
      
      # Register this compute cell as a dependent of its sources.
      @dependencies.each do |dep|
        # This is a bit of a hack for type safety without a common ancestor class.
        # We know dependencies of a ComputeCell must be InputCell or ComputeCell.
        if dep.is_a?(InputCell)
          dep.as(InputCell).add_dependent(self)
        elsif dep.is_a?(ComputeCell)
          dep.as(ComputeCell).add_dependent(self)
        end
      end

      # Initialize @_value with a placeholder, it will be computed on first `value` call.
      # We need to satisfy the compiler about instance variable initialization.
      @_value = @compute_function.call
    end

    # Public getter for the value.
    # It uses memoization: if the value is not stale, it returns the cached one.
    # Otherwise, it re-computes, caches, and returns the new value.
    def value : T
      if @is_stale
        new_val = @compute_function.call
        # Check if the value actually changed before propagating further.
        if !@_value.nil? && new_val != @_value
          @_value = new_val
          # The value changed, so trigger callbacks and notify dependents.
          trigger_callbacks
          @dependents.each(&.recompute)
        else
          @_value = new_val
        end
        @is_stale = false
      end
      @_value
    end

    # Internal method to register another compute cell that depends on this one.
    def add_dependent(cell : ComputeCell)
      @dependents << cell
    end

    # Internal method to add a callback procedure.
    def add_callback(&callback : Proc(T, Nil))
      @callbacks << callback
    end

    # Marks this cell and all downstream cells as stale, forcing re-computation on next access.
    def recompute
      return unless @is_stale == false # Avoid redundant recomputations
      @is_stale = true
      @dependents.each(&.recompute)
    end

    private def trigger_callbacks
      @callbacks.each do |cb|
        cb.call(@_value)
      end
    end
  end

  # Factory method to create an InputCell.
  def create_input_cell(initial_value : T) : InputCell
    InputCell.new(initial_value)
  end

  # Factory method to create a ComputeCell.
  # It takes dependencies and a block that defines the computation.
  def create_compute_cell(dependencies : Array(Cell(T)), &compute_function : Proc(Array(T), T)) : ComputeCell
    # We wrap the user's block to pass the values of the dependencies, not the cells themselves.
    wrapped_function = ->{ compute_function.call(dependencies.map(&.value)) }
    ComputeCell.new(dependencies, &wrapped_function)
  end

  # A special type of compute cell that only performs a side effect (callback).
  # It doesn't have a value itself but is part of the reactive graph.
  def add_callback(cell : ComputeCell, &callback : Proc(T, Nil))
    cell.add_callback(&callback)
  end
end

Running the Code

To use this system, you would save the code above as `reactor.cr`, instantiate the Reactor, create cells, and watch the magic happen.

Here's a sample usage file, `main.cr`:

require "./reactor.cr"

# We need to specify the type for our reactor instance. Let's use Int32.
reactor = Reactor(Int32).new

# Create two input cells
input1 = reactor.create_input_cell(10)
input2 = reactor.create_input_cell(20)

puts "Initial values: input1=#{input1.value}, input2=#{input2.value}"

# Create a compute cell that adds the two inputs
adder = reactor.create_compute_cell([input1, input2]) do |inputs|
  inputs[0] + inputs[1]
end

puts "Initial adder value: #{adder.value}" # => 30

# Create another compute cell that depends on the 'adder'
multiplier = reactor.create_compute_cell([adder]) do |inputs|
  inputs[0] * 2
end

puts "Initial multiplier value: #{multiplier.value}" # => 60

# --- Add a callback ---
# This block will execute whenever the 'multiplier' cell's value changes.
callback_values = [] of Int32
reactor.add_callback(multiplier) do |new_value|
  puts "CALLBACK FIRED: Multiplier changed to #{new_value}"
  callback_values << new_value
end

# --- Now, let's trigger a change ---
puts "\nChanging input1 to 20..."
input1.value = 20

# The changes propagate automatically. Let's check the new values.
puts "New adder value: #{adder.value}"          # => 40
puts "New multiplier value: #{multiplier.value}"  # => 80
puts "Callback captured values: #{callback_values}" # => [80]

puts "\nChanging input2 to 5..."
input2.value = 5

puts "New adder value: #{adder.value}"          # => 25
puts "New multiplier value: #{multiplier.value}"  # => 50
puts "Callback captured values: #{callback_values}" # => [80, 50]

To compile and run this example, use the Crystal compiler:

crystal run main.cr

The output will demonstrate the automatic propagation of changes and the callback firing as expected.

Code Walkthrough: The Propagation Mechanism

The entire system hinges on a few key interactions. Let's trace the flow when an input cell's value is changed.

1. Setting the Value: The process starts in `InputCell#value=`.

def value=(new_value : T)
  return if @_value == new_value # Optimization: do nothing if value is the same
  @_value = new_value
  # Notify all dependents that they need to recompute.
  @dependents.each(&.recompute)
end

When you call `input1.value = 20`, this method updates the internal `@_value` and then iterates through its `@dependents` array, calling the `recompute` method on each one. In our example, `adder` is a dependent of `input1`.

2. Marking as Stale (The `recompute` Cascade): The `ComputeCell#recompute` method is crucial. It doesn't calculate a new value immediately. Instead, it just marks the cell as "stale" and continues the chain reaction.

def recompute
  return unless @is_stale == false # Avoids redundant work
  @is_stale = true
  @dependents.each(&.recompute) # Propagate the "staleness" downstream
end

So, `input1` tells `adder` to `recompute`. `adder` sets its `@is_stale` flag to `true` and then tells its own dependents (in this case, `multiplier`) to `recompute`. `multiplier` also sets its `@is_stale` flag to `true`. Now, the entire downstream graph is marked as needing an update, but no actual computation has happened yet. This is a form of lazy evaluation.

3. Pulling the Value (Lazy Evaluation): The computation is only triggered when you actually ask for a value from a stale cell, for example, by calling `multiplier.value`.

def value : T
  if @is_stale
    new_val = @compute_function.call
    # ... (logic to update value, trigger callbacks, and notify dependents) ...
    @is_stale = false
  end
  @_value
end

When `multiplier.value` is called, it sees `@is_stale` is `true`. It then calls its `@compute_function`. This function needs the value of `adder`, so it calls `adder.value`. `adder` is also stale, so it calls its own compute function, which in turn calls `input1.value` and `input2.value` to get the fresh data. The results flow back up the call stack, each cell caches its new value, sets `@is_stale` to `false`, and triggers its callbacks.

This "pull-based" approach is efficient because it avoids re-calculating values for parts of the dependency graph that are never read after a change.

Here is a diagram illustrating this data propagation and callback firing flow:

    ● InputCell `input1`
    │
    ▼
  ┌──────────────────────┐
  │ `input1.value = 20`  │
  └──────────┬───────────┘
             │ 1. Triggers `recompute`
             ▼
    ● ComputeCell `adder`
    │ (marked as stale)
    │
    │ 2. Propagates `recompute`
    ▼
    ● ComputeCell `multiplier`
    │ (marked as stale)
    │
    ▼
  ┌─────────────────────────┐
  │ `puts multiplier.value` │
  └──────────┬──────────────┘
             │ 3. Pulls value, triggering computation chain
             │
             ├─▶ `multiplier` computes `adder.value * 2`
             │      │
             │      └─▶ `adder` computes `input1.value + input2.value`
             │
             │ 4. `multiplier` value changes, firing callbacks
             ▼
    ● Callback fires
    │
    ▼
  [Side Effect: "Multiplier changed to 80"]

---

Where This Pattern Shines: Real-World Use Cases

Reactive programming isn't just a theoretical exercise; it's the backbone of many modern software applications. Its ability to manage complex, interconnected state makes it invaluable in several domains:

• User Interface (UI) Development: This is the most common use case. Frameworks like React, Vue, and Svelte are built on reactive principles. When application state changes (e.g., user logs in), all UI components that depend on that state automatically re-render. Our simple system is a microcosm of this powerful idea.
• Data Stream Processing: Think of handling real-time data from sensors, financial markets, or social media feeds. Reactive extensions (like RxCrystal or RxJava) allow you to treat these events as streams of data. You can filter, transform, and combine these streams declaratively to react to patterns and events as they happen.
• Game Development: Character stats in a game are often highly interdependent. A character's `attack_power` might depend on their `base_strength`, a `weapon_bonus`, and a temporary `magic_buff`. Using a reactive system, you can change the `magic_buff` and have `attack_power` and any related UI elements update automatically.
• Complex Business Logic: In finance or logistics, calculations can depend on many changing variables. A reactive model allows developers to define the rules of the system (e.g., how shipping cost is calculated from weight, distance, and fuel price) and let the system automatically update the final cost whenever an input variable changes.

Pros and Cons of Our Reactive Implementation

Like any architectural pattern, this approach has trade-offs. It's crucial to understand them to apply it effectively.

Pros

Cons

Declarative & Readable: Code focuses on the "what" not the "how", making business logic clearer. Automatic State Sync: Eliminates a whole class of bugs related to inconsistent state. Reduced Boilerplate: No need for manual event handlers or update chains. Lazy Evaluation: Computations are only performed when a value is requested, which can be a performance benefit.

Increased Memory Usage: Each cell and its dependencies must be stored in memory, creating a graph structure. Debugging Complexity: Tracing the flow of data can be non-intuitive. Debugging involves thinking about the dependency graph rather than a linear execution stack. Risk of "Glitches": In more complex graphs, a node might be updated multiple times from different paths before settling on a final value. Our implementation is simple and less prone to this, but sophisticated systems need careful management of the update order (topological sort). Circular Dependencies: If cell A depends on B, and B depends on A, it creates an infinite loop. Our simple implementation does not detect this and would lead to a stack overflow. Production-grade systems require cycle detection.

---

Frequently Asked Questions (FAQ)

1. How does this differ from the full Observer Pattern?

This implementation is a specialized form of the Observer Pattern. In the classic pattern, a "Subject" maintains a list of "Observers" and notifies them of state changes. Here, our `InputCell`s and `ComputeCell`s act as Subjects, and the `ComputeCell`s that depend on them are the Observers. The key difference is the addition of a computation graph and lazy evaluation, which are specific to reactive systems.

2. What happens if I create a circular dependency?

In our current implementation, a circular dependency (e.g., cell A depends on B, and B depends on A) will cause a SystemStackError (stack overflow). When you try to get the value of A, it will try to get the value of B, which will try to get the value of A, and so on, leading to infinite recursion. Production-ready reactive libraries include cycle detection mechanisms that throw an error when such a graph is defined.

3. Is this implementation thread-safe?

No, this implementation is not thread-safe. If multiple threads were to set input cell values or read compute cell values concurrently, you could encounter race conditions, leading to incorrect computations or inconsistent state. Making it thread-safe would require adding mutexes or other synchronization primitives around value access and updates.

4. What is a "glitch" in reactive programming?

A "glitch" occurs when a value is updated more than once during a single propagation wave, causing dependents to compute with intermediate, inconsistent state. For example, if C depends on A and B, and both A and B are updated, C might recompute once when A changes and again when B changes. A more robust system would use topological sorting or a transaction-based update mechanism to ensure C only computes once with the final values of A and B.

5. How could this system be extended?

This is a foundational implementation. You could extend it in many ways: adding cycle detection, implementing operators to transform and combine cells (like `map`, `filter`), providing better error handling within compute functions, and ensuring transactional updates to prevent glitches. These features are common in mature libraries like RxCrystal.

6. Why is the Reactor generic with `Reactor(T)`?

Making the `Reactor` and its `Cell`s generic allows for type safety. By specifying `Reactor(Int32).new`, you ensure that all cells created by that reactor instance will handle `Int32` values. This leverages Crystal's powerful type system to prevent you from, for example, accidentally adding a `String` to an `Int32` within a compute cell, catching errors at compile time instead of runtime.

---

Conclusion: Embrace the Flow

We've successfully built a functional, albeit simple, reactive system in Crystal from scratch. This journey from the chaos of manual state management to the elegance of declarative data flow showcases a powerful paradigm shift. By defining relationships and letting the system handle propagation, you write code that is cleaner, more maintainable, and less prone to bugs.

This implementation is a starting point. The concepts of input cells, compute cells, dependency graphs, and callbacks are the fundamental building blocks of much larger and more complex reactive frameworks that power modern applications. Understanding these fundamentals is a crucial step in becoming a more effective developer, capable of tackling complex state management challenges with confidence.

To continue your journey, we encourage you to experiment with this code, try extending it with new features, and explore the other modules in our Crystal 6 learning path. For a broader view of the language, check out our complete Crystal programming guide on kodikra.com.

Disclaimer: The code provided is based on Crystal 1.12+. Language features and syntax may evolve in future versions. Always consult the official Crystal documentation for the most current information.

---

Published by Kodikra — Your trusted Crystal learning resource.