phlow_engine/
lib.rs

1//! # phlow - A Dynamic Rule-Based Workflow Engine
2//!
3//! `phlow` is a **flexible and extensible** rule-based workflow engine written in Rust.
4//! It allows users to define and execute **dynamic decision trees** and **conditional workflows**
5//! using JSON-based configurations and embedded scripting via [`Rhai`](https://rhai.rs).
6//!
7//! ## Features
8//! - **Dynamic workflows** with JSON-defined rules
9//! - **Embedded scripting** with Rhai for advanced expressions
10//! - **Conditional branching** with custom operators (`starts_with`, `ends_with`, `search`)
11//! - **Step-based execution** with context-aware evaluation
12//! - **Extensible engine** with pluggable functions
13//!
14//! ## Example: Decision Tree for Club Membership Approval
15//!
16//! This example demonstrates a **decision tree** to determine if a person can become a club member.
17//!
18//! ```rust
19//! use phlow_engine::{Phlow, Context};
20//! use phs::build_engine;
21//! use valu3::prelude::*;
22//! use valu3::json;
23//! use std::sync::Arc;
24//!
25//! # #[tokio::main]
26//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
27//!     let decision_tree = json!({
28//!       "steps": [
29//!         {
30//!           "condition": {
31//!             "left": "params.age",
32//!             "right": 18,
33//!             "operator": "greater_than_or_equal"
34//!           },
35//!           "then": {
36//!             "steps": [
37//!               {
38//!                 "condition": {
39//!                   "left": "params.income",
40//!                   "right": 5000.0,
41//!                   "operator": "greater_than_or_equal"
42//!                 },
43//!                 "then": {
44//!                   "return": "Approved"
45//!                 },
46//!                 "else": {
47//!                   "return": "Rejected - Insufficient income"
48//!                 }
49//!               }
50//!             ]
51//!           },
52//!           "else": {
53//!             "return": "Rejected - Underage"
54//!           }
55//!         }
56//!       ]
57//!     });
58//!
59//!     let phlow = Phlow::try_from_value(&decision_tree, None)?;
60//!     let mut context = Context::from_main(json!({ "age": 20, "income": 6000.0 }));
61//!     let result = phlow.execute(&mut context).await?;
62//!
63//!     println!("Decision: {:?}", result);
64//! # Ok(())
65//! # }
66//! ```
67//!
68//! ## Modules
69//!
70//! - [`phlow`] - Main structure containing pipelines and execution logic.
71//! - [`context`] - Manages execution state and variable storage.
72//! - [`pipeline`] - Defines sequential execution of processing steps.
73//! - [`step_worker`] - Handles conditional logic and step execution.
74//! - [`script`] - Integrates Rhai scripting for dynamic evaluation.
75//! - [`engine`] - Configures and extends the scripting engine.
76//! - [`condition`] - Defines logical operators and conditions.
77//! - [`collector`] - Logs execution steps and tracks workflow state.
78//!
79//! ## Architecture Overview
80//!
81//! The `phlow` engine processes a **workflow pipeline** composed of steps. Each step can:
82//! - Evaluate **conditions** (e.g., comparisons, regex matching)
83//! - Execute **scripts** for computations
84//! - **Branch** execution based on conditions
85//! - Store and reference **previous step outputs**
86//!
87//! ### Execution Flow
88//! 1. The engine receives an input **JSON workflow definition**.
89//! 2. The `phlow` instance **parses** and **validates** the workflow.
90//! 3. The workflow **executes step-by-step**, evaluating conditions and executing actions.
91//! 4. The **final result** is returned to the caller.
92//!
93//! ## Advanced Usage
94//!
95//! ### Adding Custom Plugins
96//!
97//! Users can **extend phlow** by adding custom functions to the execution engine.
98//! The phlow engine supports extending functionality through custom Rhai functions
99//! and repositories that can be injected into the scripting environment.
100//!
101//! For detailed examples of extending the engine, see the `phs` module documentation
102//! and the `build_engine` function.
103//!
104//! ### Handling Execution Errors
105//!
106//! Errors during workflow execution are returned as `Result<T, PhlowError>`:
107//!
108//! ```rust
109//! use phlow_engine::{Phlow, Context};
110//! use valu3::prelude::*;
111//! use valu3::json;
112//!
113//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
114//!     let workflow = json!({
115//!       "steps": [
116//!         {
117//!           "return": "Success"
118//!         }
119//!       ]
120//!     });
121//!
122//!     let phlow = Phlow::try_from_value(&workflow, None)?;
123//!     let mut context = Context::from_main(json!({"key": "value"}));
124//!
125//!     match phlow.execute(&mut context).await {
126//!         Ok(result) => println!("Execution succeeded: {:?}", result),
127//!         Err(err) => eprintln!("Execution failed: {:?}", err),
128//!     }
129//! # Ok(())
130//! # }
131//! ```
132//!
133//! ## License
134//!
135//! This project is licensed under the **MIT License**.
136pub mod collector;
137pub mod condition;
138pub mod context;
139pub mod id;
140pub mod phlow;
141pub mod pipeline;
142pub mod script;
143pub mod step_worker;
144pub mod transform;
145pub use phs;
146
147pub use context::Context;
148pub use phlow::{Phlow, PhlowError};
phlow_engine/lib.rs

phlow_engine/
lib.rs
