Depends

A library for ergonomic, performant, incremental computation between arbitrary types.

Why would I want that

Most applications rely on some core logic which must respond to external events. Often, the logic to transform each event in to an action is straightforward, but as the application scales, many hard to reason-with situations emerge from the combinatorial explosion of states.

Dependency graphs are an excellent code architecture to tame complexity in such scenarios.

use std::{collections::HashSet, rc::Rc};

use depends::{
    core::{Depends, LeafNodeRc, Resolve, UpdateDependeeMut, UpdateLeafMut},
    derives::{Dependee, Dependencies, Leaf},
};

// A `Leaf` is a node which takes new values from outside the graph.
#[derive(Leaf, Default)]
pub struct NumberInput {
    value: i32,
}

// `Leaf` types must provide a way for code outside to update their internal state.
// This is just a simple replace for now.
impl UpdateLeafMut for NumberInput {
    type Input = i32;

    fn update_mut(&mut self, input: Self::Input) {
        self.value = input;
    }
}

// `Dependencies` are derived to state what references `Dependee` nodes need to
// calculate their state on-demand. These could be any number of other `Dependee`s
// or `Leaf`s.
#[derive(Dependencies)]
pub struct Components {
    left: LeafNodeRc<NumberInput>,
    right: LeafNodeRc<NumberInput>,
}

// A `Dependee` i.e. its state is a pure transformation of other nodes
#[derive(Dependee, Default)]
#[depends(dependencies = Components)]
pub struct Sum {
    value: i32,
}

// This trait specifies how a `Dependee` updates its internal state given its dependencies.
impl UpdateDependeeMut for Sum {
    fn update_mut(&mut self, input: <Self as Depends>::Input<'_>) {
        // `ComponentsRef` is auto-generated by `Dependencies`. It's a read-reference
        // to each field of `Components`
        let ComponentsRef { left, right } = input;
        self.value = left.data().value + right.data().value;
    }
}

struct MyGraph {
    left: LeafNodeRc<NumberInput>,
    right: LeafNodeRc<NumberInput>,
    // `SumNode` is auto-generated by `Dependee`.
    sum: Rc<SumNode>,
}

// Compose a graph!
let left = NumberInput::default().into_leaf();
let right = NumberInput::default().into_leaf();
let sum = Sum::default().into_node(Components::new(Rc::clone(&left), Rc::clone(&right)));

let graph = MyGraph { left, right, sum };

// A `Visitor` is a collection which tracks which nodes have been visited each run.
let mut visitor = HashSet::<usize>::new();

// Resolving the graph from any node will traverse via Depth First Search, prompting
// recalculation for an node which has `State::Dirty`.
assert_eq!(graph.sum.resolve(&mut visitor).data().value, 0);

// `Forgets` which nodes have been visited.
visitor.clear();

// Recursively marks nodes as `State::Clean`.
graph.sum.clean(&mut visitor);

// `Forgets` which nodes have been visited (whilst cleaning).
visitor.clear();


// Update the leaves. Their state is now `State::Dirty`.
graph.left.update(2);
graph.right.update(2);

// We've successfully implemented simple addition! Only nodes which have dirty parents
// will be recalculated.
assert_eq!(graph.sum.resolve(&mut visitor).data().value, 4);

Clearly, to implement a simple addition problem, a dependency graph is overkill. However, for more complex problems, where many inputs can change and the output is a combination of many transformations on that input (and derivations of it), depends can help you produce scalable, performant, testable code out of the box.

Graphviz

Any graph built using depends can be converted to a Graphviz representation by passing a GraphvizVisitor (this requires the feature graphviz).

let graph = my_graph();
let mut visitor = GraphvizVisitor::new();
graph.answer.resolve(&mut visitor);
assert_eq!(
    graph.render().unwrap(),
    r#"
digraph G {
  2[label="Sum"];
  0[label="NumberInput"];
  1[label="NumberInput"];
  0 -> 2;
  1 -> 2;
}
"#);

The graph in the above example is rendered below.