Skip to main content

flow_runner/
lib.rs

1//! # flow-runner
2//!
3//! A small decision engine. You write rules in a `.flow` file; the host passes
4//! in data and gets back a decision. The engine never does I/O, never reads the
5//! clock, and never performs actions: it decides, and the host acts.
6//!
7//! ```
8//! use flow_runner::{Decision, Flow, Input, Limits, Value};
9//!
10//! let flow = Flow::compile(r#"
11//! edition 2026
12//! flow return-window
13//! entry evaluate
14//!
15//! param windowDays = 30
16//!
17//! node evaluate =
18//!   let age = input.data.evaluatedAt - input.data.deliveredAt
19//!   when {
20//!     age > windowDays * 86400: { "eligible": false, "reason": "WindowExpired" }
21//!     else:                     { "eligible": true }
22//!   }
23//! "#).unwrap();
24//!
25//! let data = Value::obj([
26//!     ("evaluatedAt", Value::Int(1_774_166_400)),
27//!     ("deliveredAt", Value::Int(1_772_870_400)),
28//! ]);
29//! let decision = flow.run(Input::start("evaluate", data), &Limits::default()).unwrap();
30//! let Decision::Value { value, .. } = decision else { panic!() };
31//! assert_eq!(value, Value::obj([("eligible", Value::Bool(true))]));
32//! ```
33//!
34//! Expressions inside a flow are [temple-dsl](https://docs.rs/temple-dsl).
35//!
36//! # How the pieces fit
37//!
38//! - [`Flow::compile`] parses and checks the text and produces a [`Flow`].
39//!   Problems are [`Diagnostics`], each with a span into the source.
40//! - [`Flow::run`] walks the flow for one [`Input`] and returns a
41//!   [`Decision`], with a [`Token`] to continue from later.
42//! - [`Flow::to_bytes`] and [`Flow::from_bytes`] store a flow.
43//! - [`Document`] edits a flow as text, for a visual builder.
44//!
45//! # Features
46//!
47//! - `json`: conversions to and from `serde_json`, and [`Graph::to_json`].
48//! - `cli`: the `flow` command-line tool. Implies `json`.
49
50#![forbid(unsafe_code)]
51#![warn(missing_docs)]
52
53mod blob;
54mod common;
55mod compile;
56mod document;
57mod flow;
58mod run;
59mod syntax;
60
61pub use common::diagnostic::{Diagnostic, Diagnostics, Severity};
62pub use common::error::{EditError, ExpressionError, InputError, LoadError, RebindError, RunError};
63pub use common::limits::{Limits, MAX_SOURCE_BYTES};
64pub use common::versions::BLOB_VERSION;
65pub use document::{
66    AnnotationView, BranchView, Declaration, Document, Edge, EdgeKind, Edit, Graph, LetView,
67    NodeView, OutcomeView, ParamView,
68};
69pub use flow::{Annotation, AskInfo, Flow, NodeInfo, Param};
70pub use run::{BranchKind, BranchTaken, Decision, Input, Token, TokenInfo, Trace};
71pub use temple_dsl::{Span, Value};