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 assert expressions
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//!           "assert": "{{ main.age >= 18 }}",
31//!           "then": {
32//!             "steps": [
33//!               {
34//!                 "assert": "{{ main.income >= 5000.0 }}",
35//!                 "then": {
36//!                   "return": "Approved"
37//!                 },
38//!                 "else": {
39//!                   "return": "Rejected - Insufficient income"
40//!                 }
41//!               }
42//!             ]
43//!           },
44//!           "else": {
45//!             "return": "Rejected - Underage"
46//!           }
47//!         }
48//!       ]
49//!     });
50//!
51//!     let phlow = Phlow::try_from_value(&decision_tree, None)?;
52//!     let mut context = Context::from_main(json!({ "age": 20, "income": 6000.0 }));
53//!     let result = phlow.execute(&mut context).await?;
54//!
55//!     println!("Decision: {:?}", result);
56//! # Ok(())
57//! # }
58//! ```
59//!
60//! ## Modules
61//!
62//! - [`phlow`] - Main structure containing pipelines and execution logic.
63//! - [`context`] - Manages execution state and variable storage.
64//! - [`pipeline`] - Defines sequential execution of processing steps.
65//! - [`step_worker`] - Handles conditional logic and step execution.
66//! - [`script`] - Integrates Rhai scripting for dynamic evaluation.
67//! - [`engine`] - Configures and extends the scripting engine.
68//! - [`condition`] - Evaluates assert expressions for branching.
69//! - [`collector`] - Logs execution steps and tracks workflow state.
70//!
71//! ## Architecture Overview
72//!
73//! The `phlow` engine processes a **workflow pipeline** composed of steps. Each step can:
74//! - Evaluate **conditions** (e.g., comparisons, regex matching)
75//! - Execute **scripts** for computations
76//! - **Branch** execution based on conditions
77//! - Store and reference **previous step outputs**
78//!
79//! ### Execution Flow
80//! 1. The engine receives an input **JSON workflow definition**.
81//! 2. The `phlow` instance **parses** and **validates** the workflow.
82//! 3. The workflow **executes step-by-step**, evaluating conditions and executing actions.
83//! 4. The **final result** is returned to the caller.
84//!
85//! ## Advanced Usage
86//!
87//! ### Adding Custom Plugins
88//!
89//! Users can **extend phlow** by adding custom functions to the execution engine.
90//! The phlow engine supports extending functionality through custom Rhai functions
91//! and repositories that can be injected into the scripting environment.
92//!
93//! For detailed examples of extending the engine, see the `phs` module documentation
94//! and the `build_engine` function.
95//!
96//! ### Handling Execution Errors
97//!
98//! Errors during workflow execution are returned as `Result<T, PhlowError>`:
99//!
100//! ```rust
101//! use phlow_engine::{Phlow, Context};
102//! use valu3::prelude::*;
103//! use valu3::json;
104//!
105//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
106//!     let workflow = json!({
107//!       "steps": [
108//!         {
109//!           "return": "Success"
110//!         }
111//!       ]
112//!     });
113//!
114//!     let phlow = Phlow::try_from_value(&workflow, None)?;
115//!     let mut context = Context::from_main(json!({"key": "value"}));
116//!
117//!     match phlow.execute(&mut context).await {
118//!         Ok(result) => println!("Execution succeeded: {:?}", result),
119//!         Err(err) => eprintln!("Execution failed: {:?}", err),
120//!     }
121//! # Ok(())
122//! # }
123//! ```
124//!
125//! ## License
126//!
127//! This project is licensed under the **MIT License**.
128pub mod collector;
129pub mod condition;
130pub mod context;
131pub mod debug;
132pub mod id;
133pub mod phlow;
134pub mod pipeline;
135pub mod script;
136pub mod step_worker;
137pub mod transform;
138pub use phs;
139
140pub use context::Context;
141pub use debug::{
142    debug_controller, set_debug_controller, DebugContext, DebugController, DebugReleaseResult,
143    DebugSnapshot,
144};
145pub use phlow::{Phlow, PhlowError};
phlow_engine/lib.rs

phlow_engine/
lib.rs
