conscript.js

The JavaScript parser for the Conscript language. Conscript (pronounced CON-script) is a very simple language for writing potentially-complex sets of conditions according to which data should be evaluated. A script written in this language is called a “Conscription” and is usually only one line long. Think of it as being analogous to the WHERE component of a SQL query.

Here’s an example that uses Conscript in a calendar context:

const conscript = require('conscript')()

const date = new Date()
const vars = {
  year: date.getUTCFullYear(),
  month: date.getUTCMonth() + 1,
  day: date.getUTCDate(),
}

// This turns the string into a test function
const test = conscript('month=10 & day=28')

if (test(vars)) {
  // This will run if today is October 28
}

Installation

Requires Node.js 8.3.0 or above.

npm i conscript

API

The module exports a single function which returns a function which returns another function.

The first function is intended to be called at require-time, e.g. require('conscript')(globalOptions).

Parameter of the First Function

1. Optional: Object argument: Global options that will apply to all subsequent calls. Possible options:
   • allowRegexLiterals (bool): Whether to permit regular expression literals in condition scripts. Defaults to false.
   • debugOutput (function): A callback that will be invoked whenever the debug operator is used. The callback will be given two arguments: the evaluated syntax string, and the value.
   • safeCall (bool): If set to true, calling a non-function will fail silently and generate null. If omitted or set to false, an error will be thrown. Defaults to false.
   • safeNav (bool): If set to true, accessing a property of a non-object will fail silently and generate null. If omitted or set to false, an error will be thrown. Defaults to false.
   • safeOp (bool): If set to true, attempting to perform operations on values that are of the wrong type will fail silently. For math operations, the unhandled value will be converted to zero. For regular expression testing operations, false will always be returned. If this option is omitted or set to false, an error will be thrown in such cases. Defaults to false.
   • safe (bool): A shortcut for setting safeCall, safeNav, and safeOp simultaneously.
   • unknownsAre (string): A mode for handling unknown identifiers. Possible values are:
     • strings (default): Treat unknown identifiers as as strings.
     • null: Convert unknown identifiers to null.
     • errors: Throw a ReferenceError whenever an unknown identifier is found.

Parameters of the Second Function

1. conscription (string): A condition script.
2. Optional: options (object): Any options that should override the global options you set when you called the first function (see above).

Parameters of the Third Function

1. vars (function, object, or Map)
   • If vars is a function, it is called whenever Conscript comes across an identifier, and is passed two arguments: the identifier name, and a notAVar symbol to be returned if the identifier is not a variable.
   • If vars is an object or Map, its keys are considered the variables to which the values are mapped.
2. Optional: Object argument:
   • defaultLeft (any): A value to be used as the left operand for operations that omit a left operand.

Return Value

Returns the result of the condition script. Usually this is true or false if you used a comparison operator, or in most use cases involving defaultLeft, but otherwise theoretically can be any value to which your script evaluates.

Conscript Syntax

Here are some of the language features which you can use in the Conscript string that you pass to the parser:

Literals

Number Literals

Floats and negative numbers are supported.

const conscript = require('conscript')()
conscript('2 > 1')() // true
conscript('1.1 > 1')() // true
conscript('-1 < 0')() // true

Infinity can be represented as either ∞ or Infinity (case-insensitive).

String Literals

String literals are enclosed with either double or single quotes.

const conscript = require('conscript')()
conscript('"test" = "test"')() // true

If the unknownsAre setting is set to strings (which is the default), then strings do not need to be quoted.

const conscript = require('conscript')({unknownsAre: 'strings'})

// Two unquoted strings ("test" and "string") separated by the `is` operator:
conscript('test is string')() // true

Boolean and Null Literals

Conscript supports true, false, and null literals. These are case-insensitive.

const conscript = require('conscript')()
conscript('true')() // true
conscript('!false')() // true
conscript('!null')() // true

Unlike JavaScript, Conscript does not distinguish between null and undefined. Only null is used. Also unlike JavaScript, Conscript does not consider null to be an object.

Array Literals

Arrays are created using square brackets and can contain variables or other literals.

const conscript = require('conscript')()
// The *= operator checks to see if the array on the left contains the value on the right.
conscript('[123, "test", var] *= "value"')({var: 'value'}) // true

Function Literals

Function literals are generally used as callback arguments for other functions. To create a function, define the named parameters list, surrounded by parentheses, then define the function body, surrounded by curly brackets.

All Conscript syntax produces some sort of value (Conscript does not use statements), so Conscript function declarations do not use return.

If needed, you can call a function immediately after defining it. Functions are called using a parenthesized list of arguments, as in JavaScript.

const conscript = require('conscript')()

// This is the same as `typeof (x => x === 1) === 'function'` in JavaScript
conscript('(x){x=1} is function')({}) // true

// This calls the function immediately after defining it
conscript('(x,y){x=y}(1,1)')({}) // true

Regular Expression Literals

Regular expressions are surrounded on either side by @. Flags (such as i) can go after the final @. Regular expressions are used in conjunction with the matches operator. The regex can go on the left and the string on the right, or vice versa.

The use of regular expression literals (e.g. @regex@) requires the allowRegexLiterals option to be set to true.

const conscript = require('conscript')({allowRegexLiterals: true})
conscript('@^ex@ matches "Example"')() // false
conscript('@^ex@ !matches "Example"')() // true
conscript('@^ex@i matches "Example"')() // true
conscript('"Example" matches @^ex@i')() // true

Variables

const conscript = require('conscript')()
conscript('x=1')({x: 1}) // true
conscript('x=1')({x: 2}) // false

When Conscript comes across an identifier (x in the example above), it will look for its value in the vars argument.

Normally, variable names must be alphanumeric. If you need support for more characters, use the ${var} construction:

const conscript = require('conscript')()
conscript('${hello world!}=123')({'hello world!': 123}) // true

If you need "variable variables," use the $(expression) construction:

const conscript = require('conscript')()
conscript('$(x)="z"')({x: 'y', y: 'z'}) // true

$ also functions as an object that contains all provided variables:

const conscript = require('conscript')()
conscript('$ is object & $x = $.x')({x: 1}) // true

You can implement determined-at-runtime variable names by passing a function instead of a dictionary object. (If you do this, the $ global object will be empty.)

const conscript = require('conscript')()
conscript('variable="variable"')(varName => varName) // true

You can pass functions as variables and can call them from within the condition string.

const conscript = require('conscript')()
const vars = {
  sum (a, b) { return a + b },
}
conscript('sum(2,2)=4')(vars) // true

If the variable is not a function, the Conscript parser will throw an error. If you want non-function calls to fail silently, set the safeCall setting to true, like so:

const conscript = require('conscript')({safeCall: true})
conscript('sum(2,2)=4')({}) // false

Parentheses

Clauses can be grouped with parentheses, allowing for nested logical tests.

const conscript = require('conscript')()
conscript('(x>0&x<=y-1)|x=999')({x: 51, y: 100}) // true

Properties & Methods

Objects

If one of your variables is an object, you can access its properties like so:

const conscript = require('conscript')()
const vars = {
  obj: {a: 1},
}
conscript('obj.a=1')(vars) // true

Normally, property names must be alphanumeric. If you need support for more characters, use the .{prop} construction:

const conscript = require('conscript')()
const vars = {
  obj: {'number one': 1},
}
conscript('obj.{number one}=1')(vars) // true

If you need dynamic property access, use the .(expression) construction:

const conscript = require('conscript')()
const vars = {
  arr: [0, 10, 20],
}
conscript('arr.(1 + 1) = 20')(vars) // true

Arrays & Strings

You can access array elements and string characters with the same syntax used to access object properties. Arrays and strings are zero-indexed.

const conscript = require('conscript')()
conscript('[1, 2, 3].0 = 1')() // true
conscript('"Test".1 = "e"')() // true

Besides numeric indexes, arrays and strings have the following properties:

• empty returns true if the array has no items, and false otherwise.
• last is the same as arr.(arr.length - 1).
• length returns the number of elements in the array.
• multiple returns true if the array has more than one item, and false otherwise.

const conscript = require('conscript')()
conscript('[].empty')() // true
conscript('[2, 4, 6].length = 3')() // true
conscript('[2, 4, 6].last = 6')() // true
conscript('[1, 2].multiple')() // true

Arrays and strings also have the following methods:

• every
• map
• pop
• shift
• slice
• some

With the exception of pop and shift, these methods work like their JavaScript equivalents. Strings are treated as if they are arrays of characters.

const conscript = require('conscript')()
conscript('[1, 2, 3].every((x){x is number})')() // true
conscript('[1, 2, 3].map((x){x*2}) = [2, 4, 6]')() // true
conscript('[1, 2, 3].slice(1, 2) = [2]')() // true
conscript('[1, 2, 3].some((x){x=3})')() // true
conscript('"aaa".every((char){char="a"})')() // true

Because Conscript is an expression-based language, pop and shift do not modify the underlying array. Each method accepts two arguments. The first is the number of ending or starting elements to separate. The second is a callback, which will be called with a varying number of arguments. For pop, the first argument to the callback will be original array minus the popped elements, with one subsequent argument provided for each popped item. For shift, one argument will be provided for each shifted item, followed by an array of the remaining elements as the last argument. Both pop and shift will return the return value of the callback.

const conscript = require('conscript')()
conscript('[1, 2, 3, 4].pop(2, (x,y,z){x is array&x.length=2&x=[1,2]&y=3&z=4})')() // true
conscript('[1, 2, 3, 4].shift(2, (x,y,z){x=1&y=2&z=[3,4]})')() // true

Operator Precedence

Operators are evaluated in the following order of precedence:

1. Ternary Comparison Operator
2. Logical Operators
3. Comparison Operators
4. Math, String, Array, and Object Operators
5. Prefix Operators

Ternary Comparison Operator

Ternary operators have the highest precedence of all the operators (precedence level 1); that is, they are evaluated first.

const conscript = require('conscript')()
conscript('enabled ? x=1 : x=2')({x: 1, enabled: true}) // true
conscript('(x ?: 123) = 123')({x: false}) // true

Logical Operators

Logical operators are at precedence level 2.

Operator	Meaning
&	And
|	Or

Note that this differs from JavaScript, which uses double ampersand and pipe characters.

Comparison Operators

Comparison operators are at precedence level 3.

Operator	Meaning	Example
=	Equals, or has equal elements	1 = 1 "a" = "a" [1,2]=[1,2]
~=	Case-insensitively equals	"Abc" ~= "abc"
>	Greater than	2 > 1
>=	Greater than or equal to	1 >= 1
<	Less than	2 < 3
<=	Less than or equal to	2 <= 3
<>	Not equal to	100 <> 200 "a" <> "b" 0 <> -0
!=	Not equal to	100 != 200 "a" != "b" 0 != -0

Starts/Ends With

The use of these operators will cast both operands to strings.

Operator	Meaning	Example
^=	String starts with	"test" ^= "t"
^~=	String case-insensitively starts with	"Test" ^~= "t"
!^=	String does not start with	"test" !^= "T"
!^~=	String does not case-insensitively start with	"test" !^~= "x"
$=	String ends with	"test" $= "t"
$~=	String case-insensitively ends with	"Test" $~= "t"
!$=	String does not end with	"test" !$= "T"
!$~=	String does not case-insensitively end with	"test" !$~= "x"

Inclusion

Operator	Meaning	Example
*=	String or array contains	"test" *= "e" [1,2,3] *= 1
*~=	String or array case-insensitively contains	"test" *~= "E" ["Hello", "world"] *~= "hello"
!*=	String or array does not contain	"test" !*= "T" [1,2,3] !*= 4
!*~=	String or array does not case-insensitively contain	"test" !*~= "x"
in	Contained in string or array	"e" in "test" 1 in [1,2,3]
~in	Case-insensitively contained in string or array	"E" ~in "test" "hello" ~in ["Hello", "world"]
!in	Not contained in string or array	"T" !in "test"
not in	Not contained in string or array	4 not in [1,2,3]
!~in	Not case-insensitively contained in string or array	"x" !~in "test"
not ~in	Not case-insensitively contained in string or array	"x" not ~in "test"

Regex Matching

Theoretically, these operators can be used even when allowRegexLiterals is off, if you provide a regular expression as a variable.

Operator	Meaning	Example
matches	The regex pattern matches the string, or vice versa	@^t@ matches "test" "test" matches @^t@ "test" matches @^T@i
!matches	The regex pattern does not match the string, and vice versa	@^T@ !matches "test" "test" !matches @^T@

Type

Operator	Meaning	Example
is	The type/class of the value is	"test" is string [] is array [] is empty array now() is Date
!is	The type/class of the value is not	"0" !is number
is not	The type/class of the value is not	"0" is not number

To the right side of the type operators is a string representing a type check and/or a class name. For more information on what type checks are possible, refer to the documentation for the isit module.

Mathematical Operators

Math operators are at precedence level 4.

Operator	Meaning
+	Add
-	Subtract
*	Multiply
/	Divide
%	Modulo
^	Exponentiate

String Operators

String operators are at precedence level 4.

Operator	Meaning	Example
+	Concatenate	"prefix" + $str + "suffix"
-	Remove characters	"test" - "t" = "es"
before	Prefix the left operand to the right operand if the right is non-empty	"prefix" before $str
then	Suffix the right operand to the left operand if the left is non-empty	$str then "suffix"

Array Operators

Array operators are at precedence level 4.

Operator	Meaning	Example
+	Concatenate, push, or unshift	[1,2]+[3]=[1,2,3] [1,2]+3=[1,2,3] 1+[2,3]=[1,2,3]
-	Remove elements	[1,2]-[2,3]=[1] [1,2,3]-2=[1,3]

Object Operators

Object operators are at precedence level 4.

Operator	Meaning	Example
+	Merge	$obj1 + $obj2
-	Remove keys or entries	$obj - "key" $obj - ["key1", "key2"] $obj1 - $obj2

Prefix Operators

Prefix operators are at precedence level 5; that is, they are evaluated last.

Operator	Meaning	Example
!	Not	!true = false
debug	Send value to debugOutput	debug $var

Because the debug operator is at the lowest precedence, a statement like debug $x=123 will only output the value of $x. If you want debug to output the result of the comparison, you would need to use parentheses: debug ($x=123).

Default Left Operand

If you set the defaultLeft option, the left sides of operations can be omitted:

const conscript = require('conscript')()
conscript('>2 & <4 & *2=6')({}, {defaultLeft: 3}) // true

The only operator that cannot be used in this way is - (subtraction). For example, it would be ambiguous whether -1 is supposed to represent the number negative one or is supposed to be a subtraction from the default left operand. If you need to subtract from the default left operand, prefix your expression with a plus sign (e.g. +-1), since adding a negative number accomplishes the same thing as does subtraction.

If you are performing equality comparison (=), you can even omit the operator altogether:

conscript('"a"|"b"')({}, {defaultLeft: 'a'}) // true
conscript('"a"|"b"')({}, {defaultLeft: 'X'}) // false

Version Migration Guide

Here are backward-incompatible changes you need to know about.

0.2.0 ⇒ 0.3.0

• Math operators now behave differently when used on non-number, non-string values. Previous versions of Conscript.js would defer to JavaScript behavior: unrecognized values would get typecast to strings when using the + operator, and other operators would often produce NaN. Several changes have been made in this regard. First, the concept of NaN has been removed from Conscript. If you try to inject NaN into a Conscript environment, it will get converted to null. Second, attempting to perform math operations on values that cannot be converted to numbers will result in an error being thrown, unless the new safeOp option is set (in which case non-numbers will be treated as zero). Attempting to use + to add a non-string to a string will either fail or, if safeOp is set, will result in the non-string value being converted to an empty string. Third, the + operator now acts as a concatenation/push/unshift operator for arrays, and the - operator now acts as an element/character removal operator for arrays/strings. Previously the default JavaScript behavior was used in these contexts.
• Zero and negative zero are no longer considered equal.
• Non-bracketed identifiers can no longer begin or end with a space (i.e. $ var is now considered the same as $var). If you need to reference a variable that begins or ends in a space, use curly brackets: ${ var}.

0.1.0 ⇒ 0.2.0

• The minimum supported Node version is now 8.3.0 (instead of 7.0.0).
• A complete Conscript call now involves 3 function calls instead of 2. The first function call is an opportunity to specify global settings, e.g. require('conscript')(globalSettings). The only modification necessary to migrate your existing code is to change require('conscript') to require('conscript')().
• Regular expression literals are now disabled by default, to protect against ReDoS attacks when dealing with user input. Enabling them requires the allowRegexLiterals option to be set to true.

0.0.0 ⇒ 0.1.0

• In version 0.0.0, the return value function signature was ({vars, defaultLeft}). In version 0.1.0, the signature is (vars, {defaultLeft}). If you are using conscript('test')({vars}), you will need to change this to conscript('test')(vars). If you are using conscript('test')({vars, defaultLeft: 123}), you will need to change this to conscript('test')(vars, {defaultLeft: 123}).