@gorules/zen-engine 0.14.0 → 0.15.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +185 -39
- package/index.js +36 -1
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -1,20 +1,18 @@
|
|
|
1
1
|
[](https://opensource.org/licenses/MIT)
|
|
2
2
|
|
|
3
|
-
# NodeJS Rules Engine
|
|
3
|
+
# NodeJS Rules Engine
|
|
4
4
|
|
|
5
|
-
ZEN Engine is a cross-platform, Open-Source Business Rules Engine (BRE). It is written in **Rust** and provides native bindings for **NodeJS** and **
|
|
5
|
+
ZEN Engine is a cross-platform, Open-Source Business Rules Engine (BRE). It is written in **Rust** and provides native bindings for **NodeJS**, **Python** and **Go**. ZEN Engine allows to load and execute [JSON Decision Model (JDM)](https://gorules.io/docs/rules-engine/json-decision-model) from JSON files.
|
|
6
6
|
|
|
7
|
-
<img width="
|
|
7
|
+
<img width="800" alt="Open-Source Rules Engine" src="https://gorules.io/images/jdm-editor.gif">
|
|
8
8
|
|
|
9
9
|
An open-source React editor is available on our [JDM Editor](https://github.com/gorules/jdm-editor) repo.
|
|
10
10
|
|
|
11
11
|
## Usage
|
|
12
12
|
|
|
13
|
-
ZEN Engine is built as embeddable BRE for your **Rust**, **NodeJS** or **
|
|
13
|
+
ZEN Engine is built as embeddable BRE for your **Rust**, **NodeJS**, **Python** or **Go** applications.
|
|
14
14
|
It parses JDM from JSON content. It is up to you to obtain the JSON content, e.g. from file system, database or service call.
|
|
15
15
|
|
|
16
|
-
If you are looking for a **Decision-as-a-Service** (DaaS) over REST, take a look at [GoRules Cloud](https://gorules.io).
|
|
17
|
-
|
|
18
16
|
### Installation
|
|
19
17
|
|
|
20
18
|
```bash
|
|
@@ -68,44 +66,109 @@ In the case above we will assume file `jdm_directory/jdm_graph1.json` exists.
|
|
|
68
66
|
|
|
69
67
|
Similar to this example you can also utilise loader to load from different places, for example from REST API, from S3, Database, etc.
|
|
70
68
|
|
|
69
|
+
### Supported Platforms
|
|
70
|
+
|
|
71
|
+
List of platforms where Zen Engine is natively available:
|
|
72
|
+
|
|
73
|
+
* **NodeJS** - [GitHub](https://github.com/gorules/zen/blob/master/bindings/nodejs/README.md) | [Documentation](https://gorules.io/docs/developers/bre/engines/nodejs) | [npmjs](https://www.npmjs.com/package/@gorules/zen-engine)
|
|
74
|
+
* **Python** - [GitHub](https://github.com/gorules/zen/blob/master/bindings/python/README.md) | [Documentation](https://gorules.io/docs/developers/bre/engines/python) | [pypi](https://pypi.org/project/zen-engine/)
|
|
75
|
+
* **Go** - [GitHub](https://github.com/gorules/zen-go) | [Documentation](https://gorules.io/docs/developers/bre/engines/go)
|
|
76
|
+
* **Rust (Core)** - [GitHub](https://github.com/gorules/zen) | [Documentation](https://gorules.io/docs/developers/bre/engines/rust) | [crates.io](https://crates.io/crates/zen-engine)
|
|
77
|
+
|
|
78
|
+
For a complete **Business Rules Management Systems (BRMS)** solution:
|
|
79
|
+
|
|
80
|
+
* [Self-hosted BRMS](https://gorules.io)
|
|
81
|
+
* [GoRules Cloud BRMS](https://gorules.io/signin/verify-email)
|
|
82
|
+
|
|
71
83
|
## JSON Decision Model (JDM)
|
|
72
84
|
|
|
73
|
-
JDM
|
|
85
|
+
GoRules JDM (JSON Decision Model) is a modeling framework designed to streamline the representation and implementation of decision models.
|
|
86
|
+
|
|
87
|
+
#### Understanding GoRules JDM
|
|
88
|
+
At its core, GoRules JDM revolves around the concept of decision models as interconnected graphs stored in JSON format.
|
|
89
|
+
These graphs capture the intricate relationships between various decision points, conditions, and outcomes in a GoRules Zen-Engine.
|
|
90
|
+
|
|
91
|
+
Graphs are made by linking nodes with edges, which act like pathways for moving information from one node to another, usually from the left to the right.
|
|
92
|
+
|
|
93
|
+
The Input node serves as an entry for all data relevant to the context, while the Output nodes produce the result of decision-making process. The progression of data follows a path from the Input Node to the Output Node, traversing all interconnected nodes in between. As the data flows through this network, it undergoes evaluation at each node, and connections determine where the data is passed along the graph.
|
|
94
|
+
|
|
95
|
+
To see JDM Graph in action you can use [Free Online Editor](https://editor.gorules.io) with built in Simulator.
|
|
96
|
+
|
|
97
|
+
There are 5 main node types in addition to a graph Input Node (Request) and Output Node (Response):
|
|
98
|
+
* Decision Table Node
|
|
99
|
+
* Switch Node
|
|
100
|
+
* Function Node
|
|
101
|
+
* Expression Node
|
|
102
|
+
* Decision Node
|
|
103
|
+
|
|
104
|
+
### Decision Table Node
|
|
105
|
+
|
|
106
|
+
#### Overview
|
|
107
|
+
|
|
108
|
+
Tables provide a structured representation of decision-making processes, allowing developers and business users to express complex rules in a clear and concise manner.
|
|
109
|
+
|
|
110
|
+
<img width="960" alt="Decision Table" src="https://gorules.io/images/decision-table.png">
|
|
111
|
+
|
|
112
|
+
#### Structure
|
|
113
|
+
|
|
114
|
+
At the core of the Decision Table is its schema, defining the structure with inputs and outputs. Inputs encompass business-friendly expressions using the ZEN Expression Language, accommodating a range of conditions such as equality, numeric comparisons, boolean values, date time functions, array functions and more. The schema's outputs dictate the form of results generated by the Decision Table.
|
|
115
|
+
Inputs and outputs are expressed through a user-friendly interface, often resembling a spreadsheet. This facilitates easy modification and addition of rules, enabling business users to contribute to decision logic without delving into intricate code.
|
|
74
116
|
|
|
75
|
-
|
|
117
|
+
#### Evaluation Process
|
|
76
118
|
|
|
77
|
-
|
|
119
|
+
Decision Tables are evaluated row by row, from top to bottom, adhering to a specified hit policy.
|
|
120
|
+
Single row is evaluated via Inputs columns, from left to right. Each input column represents `AND` operator. If cell is empty that column is evaluated **truthfully**, independently of the value.
|
|
78
121
|
|
|
79
|
-
|
|
122
|
+
If a single cell within a row fails (due to error, or otherwise), the row is skipped.
|
|
80
123
|
|
|
81
|
-
|
|
124
|
+
**HitPolicy**
|
|
82
125
|
|
|
83
|
-
|
|
126
|
+
The hit policy determines the outcome calculation based on matching rules.
|
|
84
127
|
|
|
85
|
-
|
|
128
|
+
The result of the evaluation is:
|
|
86
129
|
|
|
87
|
-
|
|
130
|
+
* **an object** if the hit policy of the decision table is `first` and a rule matched. The structure is defined by the output fields. Qualified field names with a dot (.) inside lead to nested objects.
|
|
131
|
+
* **`null`/`undefined`** if no rule matched in `first` hit policy
|
|
132
|
+
* **an array of objects** if the hit policy of the decision table is `collect` (one array item for each matching rule) or empty array if no rules match
|
|
88
133
|
|
|
89
|
-
**Inputs**
|
|
90
134
|
|
|
91
|
-
|
|
135
|
+
#### Inputs
|
|
136
|
+
|
|
137
|
+
In the assessment of rules or rows, input columns embody the `AND` operator. The values typically consist of (qualified) names, such as `customer.country` or `customer.age`.
|
|
138
|
+
|
|
139
|
+
There are two types of evaluation of inputs, `Unary` and `Expression`.
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
**Unary Evaluation**
|
|
143
|
+
|
|
144
|
+
Unary evaluation is usually used when we would like to compare single fields from incoming context separately, for example `customer.country` and `cart.total` . It is activated when a column has `field` defined in its schema.
|
|
145
|
+
|
|
146
|
+
***Example***
|
|
147
|
+
|
|
148
|
+
For the input:
|
|
92
149
|
|
|
93
150
|
```json
|
|
94
151
|
{
|
|
95
|
-
"cart": {
|
|
96
|
-
"total": 1000
|
|
97
|
-
},
|
|
98
152
|
"customer": {
|
|
99
153
|
"country": "US"
|
|
154
|
+
},
|
|
155
|
+
"cart": {
|
|
156
|
+
"total": 1500
|
|
100
157
|
}
|
|
101
158
|
}
|
|
102
159
|
```
|
|
103
160
|
|
|
104
|
-
|
|
161
|
+
<img width="960" alt="Decision Table Unary Test" src="https://gorules.io/images/decision-table.png">
|
|
162
|
+
|
|
163
|
+
This evaluation translates to
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
IF customer.country == 'US' AND cart.total > 1000 THEN {"fees": {"percent": 2}}
|
|
167
|
+
ELSE IF customer.country == 'US' THEN {"fees": {"flat": 30}}
|
|
168
|
+
ELSE IF customer.country == 'CA' OR customer.country == 'MX' THEN {"fees": {"flat": 50}}
|
|
169
|
+
ELSE {"fees": {"flat": 150}}
|
|
170
|
+
```
|
|
105
171
|
|
|
106
|
-
* Side-effect free
|
|
107
|
-
* Dynamic types
|
|
108
|
-
* Simple syntax for broad audiences
|
|
109
172
|
|
|
110
173
|
List shows basic example of the unary tests in the Input Fields:
|
|
111
174
|
|
|
@@ -126,17 +189,45 @@ List shows basic example of the unary tests in the Input Fields:
|
|
|
126
189
|
|
|
127
190
|
Note: For the full list please visit [ZEN Expression Language](https://gorules.io/docs/rules-engine/expression-language/).
|
|
128
191
|
|
|
192
|
+
**Expression Evaluation**
|
|
193
|
+
|
|
194
|
+
Expression evaluation is used when we would like to create more complex evaluation logic inside single cell. It allows us to compare multiple fields from the incoming context inside same cell.
|
|
195
|
+
|
|
196
|
+
It can be used by providing an empty `Selector (field)` inside column configuration.
|
|
197
|
+
|
|
198
|
+
***Example***
|
|
199
|
+
|
|
200
|
+
For the input:
|
|
201
|
+
|
|
202
|
+
```json
|
|
203
|
+
{
|
|
204
|
+
"transaction": {
|
|
205
|
+
"country": "US",
|
|
206
|
+
"createdAt": "2023-11-20T19:00:25Z",
|
|
207
|
+
"amount": 10000
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
<img width="960" alt="Decision Table Expression" src="https://gorules.io/images/decision-table-expression.png">
|
|
213
|
+
|
|
214
|
+
```
|
|
215
|
+
IF time(transaction.createdAt) > time("17:00:00") AND transaction.amount > 1000 THEN {"status": "reject"}
|
|
216
|
+
ELSE {"status": "approve"}
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Note: For the full list please visit [ZEN Expression Language](https://gorules.io/docs/rules-engine/expression-language/).
|
|
220
|
+
|
|
221
|
+
|
|
129
222
|
**Outputs**
|
|
130
223
|
|
|
131
|
-
|
|
224
|
+
Output columns serve as the blueprint for the data that the decision table will generate when the conditions are met during evaluation.
|
|
132
225
|
|
|
133
|
-
|
|
134
|
-
* `null`/`undefined` if no rule matched in FIRST hit policy
|
|
135
|
-
* an array of objects if the hit policy of the decision table is COLLECT (one array item for each matching rule) or empty array if no rules match
|
|
226
|
+
When a row in the decision table satisfies its specified conditions, the output columns determine the nature and structure of the information that will be returned. Each output column represents a distinct field, and the collective set of these fields forms the output or result associated with the validated row. This mechanism allows decision tables to precisely define and control the data output.
|
|
136
227
|
|
|
137
|
-
Example
|
|
228
|
+
***Example***
|
|
138
229
|
|
|
139
|
-
<img width="860" alt="
|
|
230
|
+
<img width="860" alt="Decision Table Output" src="https://gorules.io/images/decision-table-output.png">
|
|
140
231
|
|
|
141
232
|
And the result would be:
|
|
142
233
|
|
|
@@ -151,25 +242,80 @@ And the result would be:
|
|
|
151
242
|
}
|
|
152
243
|
}
|
|
153
244
|
```
|
|
245
|
+
### Switch Node (NEW)
|
|
246
|
+
|
|
247
|
+
The Switch node in GoRules JDM introduces a dynamic branching mechanism to decision models, enabling the graph to diverge based on conditions.
|
|
154
248
|
|
|
155
|
-
|
|
249
|
+
Conditions are written in a Zen Expression Language.
|
|
156
250
|
|
|
157
|
-
|
|
251
|
+
By incorporating the Switch node, decision models become more flexible and context-aware. This capability is particularly valuable in scenarios where diverse decision logic is required based on varying inputs. The Switch node efficiently manages branching within the graph, enhancing the overall complexity and realism of decision models in GoRules JDM, making it a pivotal component for crafting intelligent and adaptive systems.
|
|
252
|
+
|
|
253
|
+
The Switch node preserves the incoming data without modification; it forwards the entire context to the output branch(es).
|
|
254
|
+
|
|
255
|
+
<img width="960" alt="Switch / Branching" src="https://gorules.io/images/decision-graph.png">
|
|
256
|
+
|
|
257
|
+
#### HitPolicy
|
|
258
|
+
There are two HitPolicy options for the switch node, `first` and `collect`.
|
|
259
|
+
|
|
260
|
+
In the context of a first hit policy, the graph branches to the initial matching condition, analogous to the behavior observed in a table. Conversely, under a collect hit policy, the graph extends to all branches where conditions hold true, allowing branching to multiple paths.
|
|
261
|
+
|
|
262
|
+
Note: If there are multiple edges from the same condition, there is no guaranteed order of execution.
|
|
263
|
+
|
|
264
|
+
*Available from:*
|
|
265
|
+
* Python 0.16.0
|
|
266
|
+
* NodeJS 0.13.0
|
|
267
|
+
* Rust 0.16.0
|
|
268
|
+
* Go 0.1.0
|
|
269
|
+
|
|
270
|
+
### Functions Node
|
|
271
|
+
|
|
272
|
+
Function nodes are JavaScript snippets that allow for quick and easy parsing, re-mapping or otherwise modifying the data using JavaScript. Inputs of the node are provided as function's arguments. Functions are executed on top of QuickJS Engine that is bundled into the ZEN Engine.
|
|
273
|
+
|
|
274
|
+
Function timeout is set to a 50ms.
|
|
158
275
|
|
|
159
276
|
```js
|
|
160
|
-
const handler = (input) => {
|
|
161
|
-
return
|
|
277
|
+
const handler = (input, {dayjs, Big}) => {
|
|
278
|
+
return {
|
|
279
|
+
...input,
|
|
280
|
+
someField: 'hello'
|
|
281
|
+
};
|
|
162
282
|
};
|
|
163
283
|
```
|
|
164
284
|
|
|
165
|
-
|
|
285
|
+
There are two built in libraries:
|
|
286
|
+
* [dayjs](https://www.npmjs.com/package/dayjs) - for Date Manipulation
|
|
287
|
+
* [big.js](https://www.npmjs.com/package/big.js) - for arbitrary-precision decimal arithmetic.
|
|
288
|
+
|
|
289
|
+
### Expression Node
|
|
290
|
+
The Expression node serves as a tool for transforming input objects into alternative objects using the Zen Expression Language. When specifying the output properties, each property requires a separate row. These rows are defined by two fields:
|
|
291
|
+
- Key - qualified name of the output property
|
|
292
|
+
- Value - value expressed through the Zen Expression Language
|
|
293
|
+
|
|
294
|
+
Note: Any errors within the Expression node will bring the graph to a halt.
|
|
295
|
+
|
|
296
|
+
<img width="960" alt="Decision Table" src="https://gorules.io/images/expression.png">
|
|
166
297
|
|
|
167
|
-
Decision
|
|
298
|
+
### Decision Node
|
|
299
|
+
|
|
300
|
+
The "Decision" node is designed to extend the capabilities of decision models. Its function is to invoke and reuse other decision models during execution.
|
|
301
|
+
|
|
302
|
+
By incorporating the "Decision" node, developers can modularize decision logic, promoting reusability and maintainability in complex systems.
|
|
168
303
|
|
|
169
304
|
## Support matrix
|
|
170
305
|
|
|
171
|
-
|
|
|
172
|
-
|
|
173
|
-
|
|
|
306
|
+
| Arch | Rust | NodeJS | Python | Go |
|
|
307
|
+
|:----------------|:-------------------|:-------------------|:-------------------|:-------------------|
|
|
308
|
+
| linux-x64-gnu | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
|
|
309
|
+
| linux-arm64-gnu | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
|
|
310
|
+
| darwin-x64 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
|
|
311
|
+
| darwin-arm64 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
|
|
312
|
+
| win32-x64-msvc | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
|
|
313
|
+
|
|
314
|
+
We do not support linux-musl currently.
|
|
315
|
+
|
|
316
|
+
## Contribution
|
|
174
317
|
|
|
175
|
-
|
|
318
|
+
JDM standard is growing and we need to keep tight control over its development and roadmap as there are number of
|
|
319
|
+
companies that are using GoRules Zen-Engine and GoRules BRMS.
|
|
320
|
+
For this reason we can't accept any code contributions at this moment, apart from help with documentation and additional
|
|
321
|
+
tests.
|
package/index.js
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
/* tslint:disable */
|
|
2
|
+
/* eslint-disable */
|
|
3
|
+
/* prettier-ignore */
|
|
4
|
+
|
|
5
|
+
/* auto-generated by NAPI-RS */
|
|
6
|
+
|
|
1
7
|
const { existsSync, readFileSync } = require('fs')
|
|
2
8
|
const { join } = require('path')
|
|
3
9
|
|
|
@@ -11,7 +17,7 @@ function isMusl() {
|
|
|
11
17
|
// For Node 10
|
|
12
18
|
if (!process.report || typeof process.report.getReport !== 'function') {
|
|
13
19
|
try {
|
|
14
|
-
const lddPath = require('child_process').execSync('which ldd').toString().trim()
|
|
20
|
+
const lddPath = require('child_process').execSync('which ldd').toString().trim()
|
|
15
21
|
return readFileSync(lddPath, 'utf8').includes('musl')
|
|
16
22
|
} catch (e) {
|
|
17
23
|
return true
|
|
@@ -231,6 +237,35 @@ switch (platform) {
|
|
|
231
237
|
loadError = e
|
|
232
238
|
}
|
|
233
239
|
break
|
|
240
|
+
case 'riscv64':
|
|
241
|
+
if (isMusl()) {
|
|
242
|
+
localFileExisted = existsSync(
|
|
243
|
+
join(__dirname, 'zen-engine.linux-riscv64-musl.node')
|
|
244
|
+
)
|
|
245
|
+
try {
|
|
246
|
+
if (localFileExisted) {
|
|
247
|
+
nativeBinding = require('./zen-engine.linux-riscv64-musl.node')
|
|
248
|
+
} else {
|
|
249
|
+
nativeBinding = require('@gorules/zen-engine-linux-riscv64-musl')
|
|
250
|
+
}
|
|
251
|
+
} catch (e) {
|
|
252
|
+
loadError = e
|
|
253
|
+
}
|
|
254
|
+
} else {
|
|
255
|
+
localFileExisted = existsSync(
|
|
256
|
+
join(__dirname, 'zen-engine.linux-riscv64-gnu.node')
|
|
257
|
+
)
|
|
258
|
+
try {
|
|
259
|
+
if (localFileExisted) {
|
|
260
|
+
nativeBinding = require('./zen-engine.linux-riscv64-gnu.node')
|
|
261
|
+
} else {
|
|
262
|
+
nativeBinding = require('@gorules/zen-engine-linux-riscv64-gnu')
|
|
263
|
+
}
|
|
264
|
+
} catch (e) {
|
|
265
|
+
loadError = e
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
break
|
|
234
269
|
default:
|
|
235
270
|
throw new Error(`Unsupported architecture on Linux: ${arch}`)
|
|
236
271
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gorules/zen-engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.15.1",
|
|
4
4
|
"main": "index.js",
|
|
5
5
|
"types": "./index.d.ts",
|
|
6
6
|
"license": "MIT",
|
|
@@ -79,12 +79,12 @@
|
|
|
79
79
|
"prepublishOnly": "napi prepublish",
|
|
80
80
|
"version": "napi version"
|
|
81
81
|
},
|
|
82
|
-
"gitHead": "
|
|
82
|
+
"gitHead": "d45335674b79647776bac6d7cbc34f7042b2697d",
|
|
83
83
|
"optionalDependencies": {
|
|
84
|
-
"@gorules/zen-engine-darwin-x64": "0.
|
|
85
|
-
"@gorules/zen-engine-linux-x64-gnu": "0.
|
|
86
|
-
"@gorules/zen-engine-win32-x64-msvc": "0.
|
|
87
|
-
"@gorules/zen-engine-linux-arm64-gnu": "0.
|
|
88
|
-
"@gorules/zen-engine-darwin-arm64": "0.
|
|
84
|
+
"@gorules/zen-engine-darwin-x64": "0.15.1",
|
|
85
|
+
"@gorules/zen-engine-linux-x64-gnu": "0.15.1",
|
|
86
|
+
"@gorules/zen-engine-win32-x64-msvc": "0.15.1",
|
|
87
|
+
"@gorules/zen-engine-linux-arm64-gnu": "0.15.1",
|
|
88
|
+
"@gorules/zen-engine-darwin-arm64": "0.15.1"
|
|
89
89
|
}
|
|
90
90
|
}
|