@ucast/js

What is @ucast/js?

@ucast/js is a JavaScript library for defining and evaluating conditions or rules. It is particularly useful for implementing access control, filtering data, and other scenarios where you need to evaluate conditions dynamically.

What are @ucast/js's main functionalities?

Define Conditions

This feature allows you to define conditions using a simple syntax. In this example, a condition is created to check if the 'age' field is greater than or equal to 18.

const { createCondition } = require('@ucast/js');

const condition = createCondition({
  field: 'age',
  operator: 'gte',
  value: 18
});

console.log(condition);

Evaluate Conditions

This feature allows you to evaluate conditions against data. In this example, the condition checks if the 'age' field in the data object is greater than or equal to 18, which returns true.

const { createCondition, evaluate } = require('@ucast/js');

const condition = createCondition({
  field: 'age',
  operator: 'gte',
  value: 18
});

const data = { age: 20 };
const result = evaluate(condition, data);

console.log(result); // true

Combine Conditions

This feature allows you to combine multiple conditions using logical operators like 'and' or 'or'. In this example, two conditions are combined to check if 'age' is greater than or equal to 18 and 'status' is 'active'.

const { createCondition, combineConditions, evaluate } = require('@ucast/js');

const condition1 = createCondition({
  field: 'age',
  operator: 'gte',
  value: 18
});

const condition2 = createCondition({
  field: 'status',
  operator: 'eq',
  value: 'active'
});

const combinedCondition = combineConditions('and', [condition1, condition2]);

const data = { age: 20, status: 'active' };
const result = evaluate(combinedCondition, data);

console.log(result); // true

Other packages similar to @ucast/js

json-rules-engine

json-rules-engine is a powerful, lightweight rules engine for JSON objects. It allows you to define rules in JSON format and evaluate them against data. Compared to @ucast/js, json-rules-engine offers more advanced rule definitions and supports complex nested conditions.

rulr

rulr is a validation library that allows you to define and evaluate rules for JavaScript objects. It is similar to @ucast/js in that it provides a way to define conditions, but it is more focused on data validation rather than general condition evaluation.

json-logic-js

json-logic-js is a library for building complex rules and logic using JSON. It allows you to define rules in a JSON format and evaluate them against data. Compared to @ucast/js, json-logic-js provides a more expressive and flexible way to define complex logic.

README

UCAST JavaScript

This package is a part of ucast ecosystem. It provides interpreter that can execute conditions AST in JavaScript against any JavaScript object.

Installation

npm i @ucast/js
# or
yarn add @ucast/js
# or
pnpm add @ucast/js

Getting Started

Interpret conditions AST

First of all, you need AST to interpret it. For the sake of an example, we will create it manually:

import { CompoundCondition, FieldCondition } from '@ucast/core';
import { interpret } from '@ucast/js';

// x > 5 && y < 10
const condition = new CompoundCondition('and', [
  new FieldCondition('gt', 'x', 5),
  new FieldCondition('lt', 'y', 10),
]);

interpret(condition, { x: 2, y: 1 }); // false
interpret(condition, { x: 6, y: 7 }); // true

The default interpret function:

• supports the next operators, implemented according to MongoDB query language:

  • eq, ne
  • lt, lte
  • gt, gte
  • within (the same as in but in is a reserved word in JavaScript), nin
  • all
  • regex
  • or, nor, and, not
  • exists
  • size
  • mod
  • where,
  • elemMatch

• supports dot notation to access nested object property values in conditions:

  const condition = new FieldCondition('eq', 'address.street', 'some street');
  interpret(condition, { address: { street: 'another street' } }); // false
  

• compare values by strict equality, so variables that reference objects are equal only if they are references to the same object:

  const address = { street: 'test' };
  const condition = new FieldCondition('eq', 'address', address);
  
  interpret(condition, { address }) // true
  interpret(condition, { address: { street: 'test' } }) // false, objects are compared by strict equality
  

Custom interpreter

Sometimes you may want to reduce (or restrict) amount of supported operators (e.g., to utilize tree-shaking and reduce bundle size). To do this you can create a custom interpreter manually:

import { FieldCondition } from '@ucast/core';
import { createJsInterpreter, eq, lt, gt } from '@ucast/js';

// supports only $eq, $lt and $gt operators
const interpret = createJsInterpreter({ eq, lt, gt });
const condition = new FieldCondition('in', 'x', [1, 2]);

interpret(condition, { x: 1 }) // throws Error, `$in` is not supported

Custom object matching

You can also provide a custom get or compare function. So, you can implement custom logic to get object's property or to compare values. compare is used everywhere equality or comparison is required (e.g., in $in, $lt, $gt). This function must return 1 if a > b, -1 if a < b and 0 if a === b.

Let's enhance our interpreter to support deep object comparison using [lodash]:

import isEqual from 'lodash/isEqual';
import { createJsInterpreter, allInterpreters, compare } from '@ucast/js';

const interpret = createJsInterpreter(allInterpreters, {
  compare(a, b) {
    if (typeof a === typeof b && typeof a === 'object' && isEqual(a, b)) {
      return 0;
    }

    return compare(a, b);
  }
});
const condition = new FieldCondition('eq', 'x', { active: true });

interpret(condition, { x: { active: true } }); // true

Custom Operator Interpreter

Any operator is just a function that accepts 3 parameters and returns boolean result. To see how to implement this function let's create $type interpreter that checks object property type using typeof operator:

import { createJsInterpreter } from '@ucast/js';

function type(condition, object, { get }) {
  return typeof get(object, condition.field) === condition.value;
}

const interpret = createJsInterpreter({ type });
const condition = new FieldCondition('type', 'x', 'number');

interpret(condition, { x: 1 }); // true

Pay attention that object property is got by using get function. Make sure that you always use get function in custom operators to get object's property value, otherwise your operator will not support dot notation.

Want to help?

Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on guidelines for contributing

License

Apache License, Version 2.0