@orioro/expression NPM

node-expression

npm install @orioro/expression

Use cases

Data querying

Main modules: comparison and object

const person = {
  givenName: 'João',
  middleName: 'Cruz',
  familyName: 'Silva',
  age: 32,
  interests: ['sport', 'music', 'books'],
  mother: {
    givenName: 'Maria',
    familyName: 'Cruz',
    age: 57
  },
  father: {
    givenName: 'Pedro',
    familyName: 'Silva',
    age: 56
  }
}

const context = {
  interpreters,
  scope: { $$VALUE: person }
}

// Simple equality comparison
evaluate(context, ['$objectMatches', { givenName: 'João' }]) // true
evaluate(context, ['$objectMatches', { givenName: 'Maria' }]) // false

// Use dot (.) path notation to access nested properties
evaluate(context, ['$objectMatches', {
  'mother.age': { $gte: 20, $lte: 50 },
  'father.age': { $gte: 20, $lte: 50 }
}]) // false

Tree structure formatting

TODO

Conditional evaluation

TODO
// const context = {
//   interpreters,
//   scope: {
//     $$VALUE: {
//       name: 'João',
//       interests: ['music', 'sports']
//       age: 30
//     }
//   }
// }

// const cases = [
//   [['$objectMatches', {
//     interests: {
//       $arrayIncludes: 'music'
//     }
//   }]]
// ]

API

Array
Boolean
Comparison
Date
Functional
Logical
Math
Number
Object
String
Type
Value

Array

$arrayIncludes(searchValueExp, arrayExp)
$arrayIncludesAll(searchValuesExp, arrayExp)
$arrayIncludesAny(searchValueExp, arrayExp)
$arrayLength(arrayExp)
$arrayReduce(reduceExp, startExp, arrayExp)
$arrayMap(mapExp, arrayExp)
$arrayFilter(queryExp, arrayExp)
$arrayIndexOf(queryExp, arrayExp)
$arrayFind(queryExp, arrayExp)
$arrayReverse(arrayExp)
$arraySort(sortExp, arrayExp)
$arrayPush(arrayExp)
$arrayUnshift(valueExp, arrayExp)
$arrayShift(arrayExp)
$arraySlice(startExp, endExp, arrayExp)
$arraySubstitute(startExp, endExp, valuesExp, arrayExp)
$arrayAddAt(indexExp, valuesExp, arrayExp)
$arrayRemoveAt(indexExp, countExp, arrayExp)
$arrayJoin(separatorExp, arrayExp)
$arrayAt(indexExp, arrayExp)

`$arrayIncludes(searchValueExp, arrayExp)`

Equivalent of Array.prototype.includes.

searchValueExp {*}
arrayExp {Array}
Returns: includes {boolean}

`$arrayIncludesAll(searchValuesExp, arrayExp)`

Similar to $arrayIncludes, but receives an array of values to be searched for and returns whether the context array contains all of the searched values.

searchValuesExp {Array}
arrayExp {Array}
Returns: includesAll {boolean}

`$arrayIncludesAny(searchValueExp, arrayExp)`

Similar to $arrayIncludes, but returns true if any of the searched values is in the array.

searchValueExp {Array}
arrayExp {Array}
Returns: includesAny {boolean}

`$arrayLength(arrayExp)`

arrayExp {Array}
Returns: length {number}

`$arrayReduce(reduceExp, startExp, arrayExp)`

reduceExp {Expression}
startExp {*}
arrayExp {Array}

`$arrayMap(mapExp, arrayExp)`

mapExp {Expression}
arrayExp {Array}

`$arrayFilter(queryExp, arrayExp)`

queryExp {BooleanExpression}
arrayExp {Array}

`$arrayIndexOf(queryExp, arrayExp)`

queryExp {BooleanExpression}
arrayExp {Array}

`$arrayFind(queryExp, arrayExp)`

queryExp {BooleanExpression}
arrayExp {Array}

`$arrayReverse(arrayExp)`

arrayExp {Array}

`$arraySort(sortExp, arrayExp)`

sortExp {number}
arrayExp {Array}

`$arrayPush(arrayExp)`

arrayExp {Array}

`$arrayUnshift(valueExp, arrayExp)`

valueExp {*}
arrayExp {Array}

`$arrayShift(arrayExp)`

arrayExp {Array}

`$arraySlice(startExp, endExp, arrayExp)`

startExp {number}
endExp {number}
arrayExp {Array}
Returns: {Array}

`$arraySubstitute(startExp, endExp, valuesExp, arrayExp)`

startExp {number}
endExp {number}
valuesExp {Array}
arrayExp {Array}
Returns: {Array}

`$arrayAddAt(indexExp, valuesExp, arrayExp)`

Adds items at the given position.

indexExp {number}
valuesExp {Array}
arrayExp {Array}
Returns: resultingArray {Array} The array with items added at position

`$arrayRemoveAt(indexExp, countExp, arrayExp)`

indexExp {number}
countExp {number}
arrayExp {Array}
Returns: resultingArray {Array} The array without the removed item

`$arrayJoin(separatorExp, arrayExp)`

separatorExp {StringExpression}
arrayExp {Array}
Returns: {string}

`$arrayAt(indexExp, arrayExp)`

indexExp {number}
arrayExp {Array}
Returns: value {*}

Boolean

$boolean(valueExp)

`$boolean(valueExp)`

valueExp {*}
Returns: {boolean}

`$eq(referenceExp, valueExp)`

Checks if the two values

referenceExp {*}
valueExp {*}
Returns: {boolean}

`$notEq(referenceExp, valueExp)`

referenceExp {*}
valueExp {*}
Returns: {boolean}

`$in(arrayExp, valueExp)`

Checks whether the value is in the given array.

arrayExp {Array}
valueExp {*}
Returns: {boolean}

`$notIn(arrayExp, valueExp)`

Checks whether the value is not in the given array.

arrayExp {Array}
valueExp {*}
Returns: {boolean}

`$gt(referenceExp, valueExp)`

Greater than value > threshold

referenceExp {number}
valueExp {number}
Returns: {boolean}

`$gte(referenceExp, valueExp)`

Greater than or equal value >= threshold

referenceExp {number}
valueExp {number}
Returns: {boolean}

`$lt(referenceExp, valueExp)`

Lesser than value < threshold

referenceExp {number}
valueExp {number}
Returns: {boolean}

`$lte(referenceExp, valueExp)`

Lesser than or equal value <= threshold

referenceExp {number}
valueExp {number}
Returns: {boolean}

`$matches(criteriaExp, valueExp)`

Checks if the value matches the set of criteria.

criteriaExp {Object}
valueExp {number}
Returns: {boolean}

Date

Set of expressions aimed at solving common date-related operations: parse, format, compare, validate, manipulate (e.g. move forward, move back). Most (if not all) operations are based on and built with Luxon DateTime. If not stated otherwise, date operations return a string in ISO 8601 format (2021-01-27T20:38:12.807Z).

DateFormat
ISODate
Duration
$date(parseFmtArgs, serializeFmtArgs, date)
$dateNow(serializeFmtArgs)
$dateIsValid()
$dateStartOf(unitExp, date)
$dateEndOf(unitExp, date)
$dateSet(valuesExp, dateExp)
$$dateSetConfig(configExp, date)
$dateGt(referenceDateExp, date)
$dateGte(referenceDateExp, date)
$dateLt(referenceDateExp, date)
$dateLte(referenceDateExp, date)
$dateEq(referenceDateExp, compareUnitExp, date)
$dateMoveForward(duration, date)
$dateMoveBackward(duration, date)

`DateFormat`

Arguments to be forwarded to Luxon corresponding DateTime parser. If a string, will be considered as the name of the format. If an Array, will be considered as a tuple consisting of format, formatOptions. Recognized formats (exported as constants DATE_{FORMAT_IN_CONSTANT_CASE}):

ISO
ISODate
ISOWeekDate
ISOTime
RFC2822
HTTP
SQL
SQLTime
SQLTime
UnixEpochMs
UnixEpochS
JSDate
PlainObject
LuxonDateTime

`ISODate`

String in the full ISO 8601 format: 2017-04-20T11:32:00.000-04:00

`Duration`

Duration represented in an object format:

duration {Object}
- years {number}
- quarters {number}
- months {number}
- weeks {number}
- days {number}
- hours {number}
- minutes {number}
- seconds {number}
- milliseconds {number}

`$date(parseFmtArgs, serializeFmtArgs, date)`

Parses a date from a given input format and serializes it into another format. Use this expression to convert date formats into your requirements. E.g. UnixEpochMs into ISO.

parseFmtArgs {DateFormat}
serializeFmtArgs {DateFormat}
date {string | number | Object | Date}
Returns: date {string | number | Object | Date} Output will vary according to serializeFmtArgs

`$dateNow(serializeFmtArgs)`

Generates a ISO date string from Date.now

serializeFmtArgs {DateFormat}
Returns: date {string | number | Object | Date}

`$dateIsValid()`

Verifies whether the given date is valid. From Luxon docs:

The most common way to do that is to over- or underflow some unit:
February 40th
28:00
4 pm
etc See https://github.com/moment/luxon/blob/master/docs/validity.md

{ISODate}
Returns: isValid {boolean}

`$dateStartOf(unitExp, date)`

Returns the date at the start of the given unit (e.g. day, month).

unitExp {string}
date {ISODate}
Returns: date {ISODate}

`$dateEndOf(unitExp, date)`

Returns the date at the end of the given unit (e.g. day, month).

unitExp {string}
date {ISODate}
Returns: date {ISODate}

`$dateSet(valuesExp, dateExp)`

Modifies date specific units and returns resulting date. See DateTime#set and DateTime.fromObject

valuesExp {Object}
- year {number}
- month {number}
- day {number}
- ordinal {number}
- weekYear {number}
- weekNumber {number}
- weekday {number}
- hour {number}
- minute {number}
- second {number}
- millisecond {number}
dateExp {ISODate}
Returns: date {ISODate}

`$$dateSetConfig(configExp, date)`

Modifies a configurations of the date.

configExp {Object}
date {ISODate}
Returns: date {ISODate}

`$dateGt(referenceDateExp, date)`

Greater than date > reference

referenceDateExp {ISODate}
date {ISODate}
Returns: {boolean}

`$dateGte(referenceDateExp, date)`

Greater than or equal date >= reference

referenceDateExp {ISODate}
date {ISODate}
Returns: {boolean}

`$dateLt(referenceDateExp, date)`

Lesser than date < reference

referenceDateExp {ISODate}
date {ISODate}
Returns: {boolean}

`$dateLte(referenceDateExp, date)`

Lesser than or equal date <= reference

referenceDateExp {ISODate}
date {ISODate}
Returns: {boolean}

`$dateEq(referenceDateExp, compareUnitExp, date)`

date == reference Converts both date and reference and compares their specified compareUnit. By default compares millisecond unit so that checks whether are exactly the same millisecond in time, but could be used to compare other units, such as whether two dates are within the same day, month or year.