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::phlow;
20//! use phlow::Engine;
21//! use valu3::json;
22//! use phlow::context::Context;
23//!
24//! fn main() {
25//!     let decision_tree = json!({
26//!       "steps": [
27//!         {
28//!           "condition": {
29//!             "left": "params.age",
30//!             "right": 18,
31//!             "operator": "greater_than_or_equal"
32//!           },
33//!           "then": {
34//!             "steps": [
35//!               {
36//!                 "condition": {
37//!                   "left": "params.income",
38//!                   "right": 5000.0,
39//!                   "operator": "greater_than_or_equal"
40//!                 },
41//!                 "then": {
42//!                   "return": "Approved"
43//!                 },
44//!                 "else": {
45//!                   "return": "Rejected - Insufficient income"
46//!                 }
47//!               }
48//!             ]
49//!           },
50//!           "else": {
51//!             "return": "Rejected - Underage"
52//!           }
53//!         }
54//!       ]
55//!     });
56//!
57//!     let engine = build_engine(None);
58//!     let phlow = phlow::try_from_value(&engine, &decision_tree, None, None).unwrap();
59//!
60//!     let mut context = Context::new(Some(json!({ "age": 20, "income": 6000.0 })));
61//!     let result = phlow.execute_with_context(&mut context).unwrap();
62//!
63//!     println!("Decision: {:?}", result);
64//! }
65//! ```
66//!
67//! ## Modules
68//!
69//! - [`phlow`] - Main structure containing pipelines and execution logic.
70//! - [`context`] - Manages execution state and variable storage.
71//! - [`pipeline`] - Defines sequential execution of processing steps.
72//! - [`step_worker`] - Handles conditional logic and step execution.
73//! - [`script`] - Integrates Rhai scripting for dynamic evaluation.
74//! - [`engine`] - Configures and extends the scripting engine.
75//! - [`condition`] - Defines logical operators and conditions.
76//! - [`collector`] - Logs execution steps and tracks workflow state.
77//!
78//! ## Architecture Overview
79//!
80//! The `phlow` engine processes a **workflow pipeline** composed of steps. Each step can:
81//! - Evaluate **conditions** (e.g., comparisons, regex matching)
82//! - Execute **scripts** for computations
83//! - **Branch** execution based on conditions
84//! - Store and reference **previous step outputs**
85//!
86//! ### Execution Flow
87//! 1. The engine receives an input **JSON workflow definition**.
88//! 2. The `phlow` instance **parses** and **validates** the workflow.
89//! 3. The workflow **executes step-by-step**, evaluating conditions and executing actions.
90//! 4. The **final result** is returned to the caller.
91//!
92//! ## Advanced Usage
93//!
94//! ### Adding Custom Plugins
95//!
96//! Users can **extend phlow** by adding custom functions to the execution engine:
97//!
98//! ```rust
99//! use phlow::engine::{build_engine, Plugins, PluginFunction};
100//! use valu3::value::Value;
101//! use std::collections::HashMap;
102//! use std::sync::Arc;
103//!
104//! fn main() {
105//!     let mut plugins = HashMap::new();
106//!
107//!     let custom_function = plugin!(|value| {
108//!         Value::from(format!("Processed: {}", value.to_string()))
109//!     });
110//!     
111//!     plugins.insert("custom_process".to_string(), custom_function);
112//!     let engine = build_engine(Some(Plugins { plugins }));
113//!
114//!     let result: Value = engine.eval("custom_process(\"Hello\")").unwrap();
115//!     println!("Result: {:?}", result);
116//! }
117//! ```
118//!
119//! ### Handling Execution Errors
120//!
121//! Errors during workflow execution are returned as `Result<T, PhlowError>`:
122//!
123//! ```rust
124//! match phlow.execute_with_context(&mut context) {
125//!     Ok(result) => println!("Execution succeeded: {:?}", result),
126//!     Err(err) => eprintln!("Execution failed: {:?}", err),
127//! }
128//! ```
129//!
130//! ## License
131//!
132//! This project is licensed under the **MIT License**.
133pub mod collector;
134pub mod condition;
135pub mod context;
136pub mod id;
137pub mod phlow;
138pub mod pipeline;
139pub mod script;
140pub mod step_worker;
141pub mod transform;
142pub use phs;
143
144pub use context::Context;
145pub use phlow::Phlow;
phlow_engine/lib.rs

phlow_engine/
lib.rs
