Likescheme NPM

Description

likescheme is a plain Javascript implementation of the functional prefix-notation Scheme-like interpreted language. It evaluates functional logic statements represented as a string or an object in a provided execution environment scope. Syntaxically, likescheme is somewhat similar to Tcl language.

Use Case

Move logic from code to configuration.

likescheme lets you encode functional statements directly into the configuration layer of your app or service when coding it in Javascript is not feasible due to complexity or security considerations.

Examples:

UI elements visibility logic
workflow routing rules
data or ETL mapping logic

Why not Lisp or Scheme or Lua?

The following popular plain Javascript implementation of Lisp, Scheme or Lua could be considered an alternative.

However, we decided to create likescheme to limit functionality to conditional and aggregate operations only, which reduces complexity, the learning curve, and makes it safer.

Installation

npm i likescheme

Usage

import

ECMAScript Module

import {evaluate} from 'likescheme';

CommonJS Module

const likescheme = require('likescheme');
const evaluate = likescheme.evaluate;

In-browser Use

  ...
  <head>
    ...
    <script src="https://unpkg.com/likescheme/dist/index.browser.js"></script>
    ...
  </head>
  <body>
    ...
    <script>
      /* global likescheme */
      ...
      likescheme.evaluate("[eq '1', '1");
      ...
    </script>
  </body>
  ...

evaluate

Evaluates code in the context of the provided data object.

evaluate (
    code, // string, e.g. [gt [get amount] 100.0]
          // or Array, e.g. ['gt', ['get', 'amount']],
          // or JSON, e.g. {operator: 'gt', args: [{operator: 'get', args: ['amount']}, 100.0]}
    data, // object, JSON, optional, e.g. {price: 150.0}, nested objects and lists are supported (see examples)
    strict // boolean, optional, default=true, if true, unknown variable throws error, else they are set to undefined
)

Examples

evaluate(
    "[and [veq 'order.product' 'apple'] [vge 'order.quantity 1]]",
    {
        order: {
            product: 'apple',
            quantity: 1
        }
    }
);

// returns
true

More Examples

See more examples here

parse

Converts code from string to Array (list) representation.

parse(code)

Examples

import {parse} from 'likescheme';

parse("[and [veq 'order.product' 'apple'] [vge 'order.quantity' 1]]");

// returns
['and', [ 'veq', 'order.product', 'apple' ], [ 'vge', 'order.quantity', 1]]

compile

Converts code from Array to JSON representation.

compile( ['and', [ 'veq', 'order.product', 'apple' ], [ 'vge', 'order.quantity', 1]]);

// returns
{
  operator: 'and',
  args: [
    { operator: 'veq', args: [ 'order.product', 'apple' ] },
    { operator: 'vge', args: [ 'order.quantity', 1 ] }
  ]
}

Functions

get key
- returns the value of the data object property referenced by key. Nested objects supported via 'dot' notation.
  - "[get 'product.name']"
  - ['get', 'product.name']
  - {operator: 'get', args: ['product.name']}
list 'value1' ...
- returns the list (array) of values
  - "[list 'apple' 'banana' 'pear']"
  - ['list', 'apple', 'banana', 'pear' ]
  - {operator: 'list', args: ['apple', 'banana', 'pear']}
in value list
- returns true if the value is in the list provided in the second argument
  - "[in [get 'product.name'] [list 'apple' 'banana' 'pear']]"
  - ['in', ['get', 'product.name'], ['list', 'apple', 'banana', 'pear']]
  - {operator: 'in', args: [{operator: 'get', args:['product.name']}, {operator: 'list', args: ['apple', 'banana', 'pear']}]}
eq|ne|lt|gt|le|ge value1 value2
- returns true if value1 is equal|not-equal|less-then|greater-then|less-or-equal-then|greater-or-equal-then to value2
  - "[eq [get 'product.name'] 'apple']"
  - ['eq', ['get', 'product.name'], 'apple']
  - {operator: 'eq', args: [{operator: 'get', args: ['product.name']}, 'apple']}
- example: {operator: 'eq', args: [{operator: 'get', args: ['product.name']}, 'apple']}
isy|isn|isu key
- syntaxical sugar - returns true if the value of the data object property referenced by key is 'truthy', 'falsy' or unknown respectively
  - "[isy 'isTaxFree']"
  - ['isy', 'isTaxFree']
  - {operator: 'isy', args: [ 'isTaxFree' ]}
not value
- returns the boolean 'not' of its argument
  - "[not [in [get 'product.name'] [list 'apple' 'banana' 'pear']]]"
  - ['not', ['in', ['get', 'product.name'], ['list', 'apple', 'banana', 'pear']]]
  - {operator: 'not', args: [{operator: 'in', args: [{operator: 'get', args: ['product.name']}, {operator: 'list', args: ['apple', 'banana', 'pear']}]}]}
and|or value1, ...
- returns the boolean 'and|or' of its arguments
  - "[and [isy 'isRound'] [isy 'isRed']]"
  - ['and', ['isy', 'isRound'], ['isy', 'isRed']]
  - {operator: 'and', args: [{operator: 'isy', args: [Array]}, {operator: 'isy', args: [Array]}]}
undefined|null|true|false
- takes no arguments, returns undefined, null, true, and false respectively
isundefined key
- returns true if the data object does not contain the property referenced by key; this function is not affected by the strict argument value.
- note: to test for the actual undefined value of an existing data object property, use [eq [get 'myVar'] [undefined]]
veq|vne|vlt|vgt|vle|vge key value
- syntaxical sugar - returns true if the value of the data object property referenced by key is equal|not-equal|less-then|greater-then|less-or-equal-then|greater-or-equal-then to value
  - "[veq 'product.name' 'apple']"
  - ['veq', 'product.name', 'apple']
  - {operator: 'veq', args: [ 'product.name', 'apple' ]}
vin key list
- syntaxical sugar - returns true if the value of the data object propert referenced by key is in the list provided in the second argument
  - "[vin 'product.name' [list 'apple' 'banana' 'pear']]"
  - ['vin', 'product.name', ['list', 'apple', 'banana', 'pear']]
  - {operator: 'vin', args: ['product.name', {operator: 'list', args: ['apple', 'banana', 'pear']}]}
bw value fromValue thruValue
- returns true if value is between fromValue and thruValue, inclusive on both ends
  - "[bw [get 'product.price'] 5.0 15.0]"
min|max list
- returns min|max value in the list
  - "[min [list 1 10 11 101]]"
map value (key1, value1, ... keyX, valueX) defaultValue
- returns valueX, which corresponds to the keyX, which is equal to value or defaultValue if such keyX does not exist
- "[map [get 'product.name'] [list 'apple' 'fruit' 'banana' 'fruit' 'tomato' 'vegetable'] 'unknown']"
  - returns fruit if product.name is apple
days value1 value2
- returns the number of days between the two dates represented by value1 (from date) and value2 (thru date), exclusive of thru date
- the date value is expected to be a string parseable by Javascript Date.parse()
- if the date value cannot be parsed, the function returns NaN
- "[days '2022-06-01' '2022-06-17']"
  - returns 16
- code: "[days [get 'fromDate'] [get 'endDate']]", data: {fromDate: '2022-06-17', endDate: '2022-06-01'}
  - returns -16
vdays key1 key2
- syntaxical sugar for days
- returns the number of days between the two dates contained in the objects referenced by key1 and key2
- code: "[vdays 'fromDate' 'endDate']", data: {fromDate: '2022-06-01', endDate: '2022-06-17'}
  - returns 16
today
- returns today's date in YYYY-MM-DD format
- "[days [today] [today]]"
  - return 0
join|split|uniq|usort|lindex|lrange
- for these list functions see Examples and the actual code
sum|mult|div|neg|rem|sub
- for these aggregate functions see Examples and the actual code