zen_engine/
lib.rs

1//! # ZEN Engine
2//!
3//! ZEN Engine is business friendly Open-Source Business Rules Engine (BRE) which executes decision
4//! models according to the GoRules JSON Decision Model (JDM) standard. It's written in Rust and
5//! provides native bindings for NodeJS and Python.
6//!
7//! # Usage
8//!
9//! To execute a simple decision using a Noop (default) loader you can use the code below.
10//!
11//! ```rust
12//! use serde_json::json;
13//! use zen_engine::DecisionEngine;
14//! use zen_engine::model::DecisionContent;
15//!
16//! async fn evaluate() {
17//!     let decision_content: DecisionContent = serde_json::from_str(include_str!("jdm_graph.json")).unwrap();
18//!     let engine = DecisionEngine::default();
19//!     let decision = engine.create_decision(decision_content.into());
20//!
21//!     let result = decision.evaluate(&json!({ "input": 12 })).await;
22//! }
23//! ```
24//!
25//! Alternatively, you may create decision indirectly without constructing the engine utilising
26//! `Decision::from` function.
27//!
28//! # Loaders
29//!
30//! For more advanced use cases where you want to load multiple decisions and utilise graphs you
31//! may use one of the following pre-made loaders:
32//! - FilesystemLoader - with a given path as a root it tries to load a decision based on relative path
33//! - MemoryLoader - works as a HashMap (key-value store)
34//! - ClosureLoader - allows for definition of simple async callback function which takes key as a parameter
35//! and returns an `Arc<DecisionContent>` instance
36//! - NoopLoader - (default) fails to load decision, allows for usage of create_decision
37//! (mostly existing for streamlining API across languages)
38//!
39//! ## Filesystem loader
40//!
41//! Assuming that you have a folder with decision models (.json files) which is located under /app/decisions,
42//! you may use FilesystemLoader in the following way:
43//!
44//! ```rust
45//! use serde_json::json;
46//! use zen_engine::DecisionEngine;
47//! use zen_engine::loader::{FilesystemLoader, FilesystemLoaderOptions};
48//!
49//! async fn evaluate() {
50//!     let engine = DecisionEngine::new(FilesystemLoader::new(FilesystemLoaderOptions {
51//!         keep_in_memory: true, // optionally, keep in memory for increase performance
52//!         root: "/app/decisions"
53//!     }));
54//!     
55//!     let context = json!({ "customer": { "joinedAt": "2022-01-01" } });
56//!     // If you plan on using it multiple times, you may cache JDM for minor performance gains
57//!     // In case of bindings (in other languages, this increase is much greater)
58//!     {
59//!         let promotion_decision = engine.get_decision("commercial/promotion.json").await.unwrap();
60//!         let result = promotion_decision.evaluate(&context).await.unwrap();
61//!     }
62//!     
63//!     // Or on demand
64//!     {
65//!         let result = engine.evaluate("commercial/promotion.json", &context).await.unwrap();
66//!     }
67//! }
68//!
69//!
70//! ```
71//!
72//! ## Custom loader
73//! You may create a custom loader for zen engine by implementing `DecisionLoader` trait.
74//! Here's an example of how MemoryLoader has been implemented.
75//! ```rust
76//! use std::collections::HashMap;
77//! use std::sync::{Arc, RwLock};
78//! use zen_engine::loader::{DecisionLoader, LoaderError, LoaderResponse};
79//! use zen_engine::model::DecisionContent;
80//!
81//! #[derive(Debug, Default)]
82//! pub struct MemoryLoader {
83//!     memory_refs: RwLock<HashMap<String, Arc<DecisionContent>>>,
84//! }
85//!
86//! impl MemoryLoader {
87//!     pub fn add<K, D>(&self, key: K, content: D)
88//!         where
89//!             K: Into<String>,
90//!             D: Into<DecisionContent>,
91//!     {
92//!         let mut mref = self.memory_refs.write().unwrap();
93//!         mref.insert(key.into(), Arc::new(content.into()));
94//!     }
95//!
96//!     pub fn get<K>(&self, key: K) -> Option<Arc<DecisionContent>>
97//!         where
98//!             K: AsRef<str>,
99//!     {
100//!         let mref = self.memory_refs.read().unwrap();
101//!         mref.get(key.as_ref()).map(|r| r.clone())
102//!     }
103//!
104//!     pub fn remove<K>(&self, key: K) -> bool
105//!         where
106//!             K: AsRef<str>,
107//!     {
108//!         let mut mref = self.memory_refs.write().unwrap();
109//!         mref.remove(key.as_ref()).is_some()
110//!     }
111//! }
112//!
113//! impl DecisionLoader for MemoryLoader {
114//! fn load<'a>(&'a self, key: &'a str) -> impl Future<Output = LoaderResponse> + 'a {
115//!     async move {
116//!         self.get(&key)
117//!             .ok_or_else(|| LoaderError::NotFound(key.to_string()).into())
118//!     }
119//! }
120//! ```
121
122#![deny(clippy::unwrap_used)]
123#![allow(clippy::module_inception)]
124
125mod config;
126mod decision;
127mod decision_graph;
128mod engine;
129pub mod error;
130pub mod loader;
131pub mod model;
132pub mod nodes;
133
134pub use config::ZEN_CONFIG;
135pub use decision::Decision;
136pub use decision_graph::{DecisionGraphResponse, DecisionGraphTrace, DecisionGraphValidationError};
137pub use engine::{
138    DecisionEngine, EvaluationOptions, EvaluationSerializedOptions, EvaluationTraceKind,
139};
140pub use error::EvaluationError;
141pub use zen_expression::Variable;
zen_engine/lib.rs

zen_engine/
lib.rs
