Json-conditions NPM

Simple conditional logic testing of JSON objects

Simple json takes an array of conditions that can be compared against a JSON object to test if that object passes or fails the conditions.

Quickstart

npm install json-conditions

const checkConditions = require('json-conditions');

const reference = {
	topLevelNumber: 3,
	user: {
		preferredName: 'Alex',
		age: 4,
	},
	toy: {
		name: 'Model Train',
		prevTracks: 5,
		tracks: 18,
		engines: 1
		battery: true,
		previousOwners: ['Alice', 'Ahmed'],
		batteryStatus: [{
			type: 'AA',
			charge: 'empty',
		}, {
			type: 'AA',
			charge: 'full',
		}]
	}
};

const simpleRules = [
	{ property: 'toy.engines', op: 'gt', value: 2 },
	{ property: 'batteries', op: 'eq', value: true },
];

// Returns true
checkConditions({
	rules: simpleRules,
	satisfy: 'ANY',
	log: console.log,
}, reference);

// Returns false
checkConditions({
	rules: simpleRules,
	satisfy: 'ALL',
	log: console.log,
}, reference);

// Returns true
checkConditions({
	rules: [
		// A required condition must always be satisfied regardless of the value
		{ property: 'toy.tracks', op: 'gt', value: 2, required: true },
		{ property: 'batteries', op: 'eq', value: true },
		{ property: 'solarPanels', op: 'gte', value: 0 },
	],
	satisfy: 'ANY',
	log: console.log,
}, reference);

// Returns true
checkConditions({
	rules: [
		// transformValueFn causes value to be substituted with ref[value], which is reference.topLevelNumber, which is 3
		{ property: 'toy.tracks', op: 'gt', value: 'topLevelNumber' },
	],
	satisfy: 'ANY',
	log: console.log,
	transformValueFn: (val) => ref[val],
}, reference);

// Array rules - all return true
checkConditions({
	rules: [
		// A required condition must always be satisfied regardless of the value
		{ property: 'toy.previousOwners[]', op: 'some', value: 'Alice' },
	],
	satisfy: 'ANY',
	log: console.log,
}, reference);

checkConditions({
	rules: [
		// A required condition must always be satisfied regardless of the value
		{ property: 'toy.batteryStatus[].type', op: 'all', value: 'AA' },
	],
	satisfy: 'ANY',
	log: console.log,
}, reference);

checkConditions({
	rules: [
		{ property: 'toy.tracks', op: 'crosses', value: 10 },
	],
	satisfy: 'ANY',
	log: console.log,
	previousValueFn: (ref) => ref.toy.prevTracks,
}, reference);

checkConditions({
	rules: [
		// A required condition must always be satisfied regardless of the value
		{ property: 'toy.batteryStatus[].type', op: 'none', value: 'AAA' },
	],
	satisfy: 'ANY',
	log: console.log,
}, reference);

Parameters

Param	Type	Default	Description
settings.log	function		Optional function to log debug output from the evaluation
settings.rules	object[]		Rules, see below
settings.satisfy	string	ANY	How many rules must be satisfied to pass, 'ALL' or 'ANY'
settings.previousValueFn	function		Function that returns a previous value, takes arguments (reference, rule.property)
settings.transformValueFn	function		If defined, the return value from settings.transformValueFn(rule.value, reference, rule.property) will be subsituted for rule.value when performing the comparison
reference	object		The javascript object to evaluate the rules against

Rules

Each rule is described by an object with the following properties | property | Type | Default | Description | |---|---|---|---| | op | string | | The logical operator to use for comparison (see below) | | property | string | | The property in the reference object to check (evaluated by lodash.get() | | required | boolean | false | If true, this rule must always evaluate to true for the object to pass the conditions | | value | * | | Value to compare the property to |

Property is passed to lodash.get to lookup the value in the object. So effectively the rules are evaluated to get(reference, rule.property) ${rule.op} ${rule.value}

Operators

The following operators can be used in rules. Operators use javascript coersion (ie == not ===) Additionally, we assume that rule values may have come from a form, and so try to be forgiving when dealing with booleans. If the value of the property is a boolean, then the strings 'true' and 'false' (case insensitive) will be converted to booleans.

Operator	Javascript operation	Notes
eq	==
neq	!=
ne	!=	(Alias for neq)
gt	>
gte	>=
lt	<
lte	<=
crosses	Greater than, but previous value was less than	(See below)
absent	!
empty	!	(Alias for absent)
present	!!
startsWith	_.toString(x).startsWith()
endsWith	_.toString(x).endsWith()
contains	_.toString(x).includes()

Array Syntax

To check arrays for matches use [] in the property path to indicate that the preceeding path is an array. You can specify further paths to reference into if the array contains an object eg toy.batteryStatus[].type in the example at the top

Operator	Javascript operation	Notes
none	!x.includes(value)	Value is not in the array
some	x.includes(value)	Value is present at least once in the array
all	!x.find(i => i !== value)	Every entry in the array matches value

Crosses

Sometimes it's not enough to know if a property is greater than a given value, but you want to know if this is the first time it has risen above that value. For example, if you were running conditions against updates to some data and you want the condition to pass the first time a counter passes 10, but not after that. You could pass in an object like { oldCount, newCount } and use the crosses operator.

When using the crosses operator, you must pass in a previousValueFn that will return a previous value that can be used to check if the value has crossed the intended value