It is a Typescript package that provides a simple JSON Programming Language, allowing you to execute a safe logic in Frontend or Backend (NodeJS). Furthermore, it can be stored in the database and rendered to the Frontend-Side to execute/run some business logic.
JsonRules is designed to be extendable. You can define new rules with sync/async handlers.
npm install json-rules-js
- Typescript. It's a strongly typed npm package
- the JSONRules structure is Simple and Optimized. Its structure and rules have a shortcut to make your JSON in a small size.
- Its structure is always Consistent. i.e.
{"Rule": "R1", Input: ["value1", "value2", {"Rule": "R2", Input: [...] }, ...] }
. - Safe & Secure. Each Rule has a secure handler.
- Extendable. Easy to add new rules.
- Sync/Async. All rules in JSONRules are sync rules, but you can extend it and add async rules.
- DRY. You can pass any rule result in a variable to be used in another rule which makes JSONRules JSON more optimized
execute = (jsonRules: IJsonRules, data?: {}): RuleResult
Execute is used to run the JSON rules and takes two parameters.
- JsonRules: check the Structure
- Data: schemaless data object to read/write to it using Object Rules
Execute is the Sync
version of jsonRules, use it to run all builtin rules and any extended Sync
Rules
executeAsync = async (jsonRules: IJsonRules, data?: {}): Promise<RuleResult>
Execute is the Async
version of jsonRules, use it to run all builtin rules and any extended Sync
or Async
Rules
registerOne = (ruleIdentifier: RuleIdentifier, ruleHandler: RuleHandler): void
Extend JsonRules by adding 2 params
- ruleIdentifier: Object
{ name: string, shortName?: string }
,name
(required) is theRule
name, andshortName
(optional) is the shortcut. i.eSum
is thename
, and+
is theshortName
. - ruleHandler: Sync/Async Function
(inputs: RuleInput[], data?: {}) => RuleResult)
,inputs
(required) is array of all inputs needs for the handler check Input in Structure, anddata
is the schemaless data check Data in the Execute Section
registerMany(rules: Rules): void
registerMany allows registering a Map()
of rules. The Map key
is RuleIdentifier
, and the Map value
is the RuleHandler
JsonRules have three main parameters:
- Rule or R (shortcut): (
String
) is the rule name itself. i.e.and
,or
,==
,>
. - Input or I (shortcut): (
any[]
) is an array of inputs which will be passed to theRule
handler/function, their type depends on theRule
handler, or it can be a nested rule - Output or O (shortcut)?: (
Symbol [Optional]
), is an optional field, it accept a name of variable which used to save the Rule result in a variable and can be called in any other rule by{ "Rule": "Var": "Input": ["variableX"] }
. The output value should be unique. If you define the same value more than once, the last one will override the value of the previous one.
- Variable or Var
- Input[]: Array (Size: 1).
- Output: Any (depends on the output value).
- Description: used to get the value of any
Output
from any rules, Check the Output part.
- And or &&
- Input[]: Array (Size: Unlimited).
- Output: Boolean (true or false).
- Description: Do the
Anding
operation, if any value inInput[]
has a value of (null, 0, false), it will returnfalse
, else it will returntrue
.
- Or or ||
- Input[]: Array (Size: Unlimited).
- Output: Boolean (true or false).
- Description: Do the
Oring
operation, if all values inInput[]
has a value of (null, 0, false), it will returnfalse
, else it will returntrue
.
- All
- Input[]: Array (Size: Unlimited).
- Output: Array (Size: Unlimited).
- Description: It takes an array of inputs and returns them again. It is used to run a list of
nested Rules
.
- Equal or ==
- Input[]: Array (Size: 2).
- Output: Boolean (true or false).
- Description: It takes an array of 2 inputs to compare if element one
Equal
element two or not.
- NotEqual or =
- Input[]: Array (Size: 2).
- Output: Boolean (true or false).
- Description: It takes an array of 2 inputs to compare if element one
Not Equal
to element two or not.
- Not or !
- Input[]: Array (Size: 1).
- Output: Boolean (true or false).
- Description: It takes an array of 1 input inverts its value. If it
true
it will returnfalse
and vice versa.
- GreaterThan or >
- Input[]: Array (Size: 2).
- Output: Boolean (true or false).
- Description: It takes an array of 2 inputs to compare if element one
Greater Than
element two or not.
- LessThan or <
- Input[]: Array (Size: 2).
- Output: Boolean (true or false).
- Description: It takes an array of 2 inputs to compare if element one
Less Than
element two or not.
- GreaterThanOrEqual or >=
- Input[]: Array (Size: 2).
- Output: Boolean (true or false).
- Description: It takes an array of 2 inputs to compare if element one
Greater Than or Equal
element two or not.
- LessThanOrEqual or <=
- Input[]: Array (Size: 2).
- Output: Boolean (true or false).
- Description: It takes an array of 2 inputs to compare if element one
Less Than or Equal
element two or not.
- IsNumber or IsNum
- Input[]: Array (Size: 1).
- Output: Boolean (true or false).
- Description: Check if the value dataType is a number or not.
- Sum or +
- Input[]: Array (Size: unlimited).
- Output: number.
- Description: Used to Sum all values. i.e.
Input1 + Input2 + .... + InputN
.
- Subtract or -
- Input[]: Array (Size: unlimited).
- Output: number.
- Description: Used to Subtract all values. i.e.
Input1 - Input2 - .... - InputN
.
- Multiply or *
- Input[]: Array (Size: unlimited).
- Output: number.
- Description: Used to Multiply all values. i.e.
Input1 * Input2 * .... * InputN
.
- Divide or /
- Input[]: Array (Size: unlimited).
- Output: number.
- Description: Used to Divide all values. i.e.
Input1 / Input2 / .... / InputN
.
- Get [In Progress]
- Input[]: Array (Size: 2) {path: string, defaultValue?: any}.
- Output: Any.
- Description: It accepts two inputs, the 1st one (required) is a path to get the Data, and the 2nd one (optional) is a default value of the path is not found. the
path
must follow the dotted stylevar1.var2
for nested fields and brackets with number for arraysvar1.var2[3].var3
- Set [In Progress]
- Input[]: Array (Size: 2) {path: string, value: any}.
- Output: Any.
- Description: It accepts two inputs. The 1st one (required) is a path to update/mutate the Data, and the 2nd one is the value to set. the
path
must follow the dotted stylevar1.var2
for nested fields and brackets with number for arraysvar1.var2[3].var3
. If thepath
does not exist, theSet
Rule will create it.
- Update [In Progress]
- Input[]: Array (Size: 2) {path: string, value: any}.
- Output: Any.
- Description: It accepts two inputs. The 1st one (required) is a path to update/mutate the Data, and the 2nd one is the value to update. the
path
must follow the dotted stylevar1.var2
for nested fields and brackets with number for arraysvar1.var2[3].var3
. If thepath
does not exist, theUpdate
rule won't do anything.
- Delete [In Progress]
- Input[]: Array (Size: 1) {path: string}.
- Output: Any.
- Description: It accepts two inputs, a path to mutate the Data by deleting a field in the request path. the
path
must follow the dotted stylevar1.var2
for nested fields and brackets with number for arraysvar1.var2[3].var3
. If thepath
does not exist, theDelete
rule won't do anything.
- Push [In Progress]
- Input[]: Array (Size: 2) {path: string, defaultValue?: any}.
- Output: Any.
- Description: It accepts two inputs. The 1st one (required) is a path in the Data of any array element to push a value in it, and the 2nd one (optional) is a default value of the path that is not found. the
path
must follow the dotted stylevar1.var2
for nested fields and brackets with number for arraysvar1.var2[3].var3
. If thepath
does not exist or if thepath
is not a path of a non-array property, thePush
rule won't do anything.
import { JsonRules } from 'json-rules-js';
const jsonRules = new JsonRules();
jsonRules.execute( { "Rule": "LessThan" , "Input": [10, 20] } ); // true
// or for short
jsonRules.execute( { "R": "<" , "I": [10, 20] } ); // true
// or use the async function
jsonRules.executeAsync( { "R": "<" , "I": [10, 20] } )
.then(result => {
console.log(result); // true
});
import { JsonRules } from 'json-rules-js';
const jsonRules = new JsonRules();
const result = jsonRules.execute({
Rule: '+',
Input: [
{
R: '+',
I: [
1,
{ R: '*', I: [2, 3] },
5
]
},
{
R: '+',
I: [
1,
{ R: '*', I: [3, 3], O: 'x' },
5
]
},
{ R: 'Var', I: ['x'] },
{ R: 'Get', I: ['user.age'] }
]
}, { user: { name: 'test', age: 100 } });
console.log(result);
// 136
import { JsonRules } from 'json-rules-js';
const jsonRules = new JsonRules();
jsonRules.registerOne({ name: 'Test', shortName: 't' }, (inputs: any[]) => {
return `${inputs[0]} Test`
})
const result = jsonRules.execute({
Rule: 'Test',
Input: [
{ R: 'Get', I: ['user.age'] }
]
}, { user: { name: 'test', age: 100 } });
console.log(result);
// 100 Test
You can extend JsonRules and add any logic you want from well-known sync/async packages like lodash, moment, ajv, axios, mysql, mongoose, ...etc.
Just use the register functions and follow its structure to add whatever you want.
JsonRules can be extended with any function, and you can override the existing rules, but make sure that any method you will add won't:
- Have any security issue
- Async method without timeout or with unhandled errors
- Block the event loop in backend nodejs https://nodejs.org/en/docs/guides/dont-block-the-event-loop/
- abuse the CPU or the memory
This library uses Array.map
and Array.reduce
, so it's not exactly Internet Explorer 8 friendly.
- Adding more math, logic, object, array, date, and casting methods.
- Automation Testing for all methods and covering all cases.
- Allow importing packages to extend JsonRules easily.
- Provide plugins to wrap well-known packages like MathJs, Jsonata, Axios, Lodash, MomentJs, ...etc.
- Make a UI Editor generate the JSON of JsonRules.
- Allow Writing Rules as expression. i.e.
And(true, Or(1, Get('var1.var2', 0)))
. - Public website has good documentation, for example, playground to try JsonRules, use-cases session has many ideas for using JsonRules.
JsonRules is MIT licensed