feat: implement left associative operators and a corresponding option

Author: josdejong

README.md

@@ -10,7 +10,7 @@ Try it out on the online playground: <https://jsonquerylang.org>
 
 ## Features
 
-- Small: just `3.5 kB` when minified and gzipped! The JSON query engine without parse/stringify is only `1.7 kB`.
+- Small: just `3.7 kB` when minified and gzipped! The JSON query engine without parse/stringify is only `1.7 kB`.
 - Feature rich (50+ powerful functions and operators)
 - Easy to interoperate with thanks to the intermediate JSON format.
 - Expressive
@@ -404,9 +404,9 @@ Here:
 
     ```ts
     type CustomOperator =
-      | { name: string; op: string; at: string; vararg?: boolean }
-      | { name: string; op: string; after: string; vararg?: boolean }
-      | { name: string; op: string; before: string; vararg?: boolean }
+      | { name: string; op: string; at: string; vararg?: boolean, leftAssociative?: boolean }
+      | { name: string; op: string; after: string; vararg?: boolean, leftAssociative?: boolean }
+      | { name: string; op: string; before: string; vararg?: boolean, leftAssociative?: boolean }
     ```
 
     The defined operators can be used in a text query. Only operators with both a left and right hand side are supported, like `a == b`. They can only be executed when there is a corresponding function. For example:
@@ -428,8 +428,10 @@ Here:
       }
       ```
 
-    When the function of the operator supports more than two arguments, like `and(a, b, c, ...)`, the option `vararg` can be set `true` to allow using a chain of multiple operators without parenthesis, like `a and b and c`. When `vararg` is not set `true`, this would throw an exception, which can be solved by using parenthesis like `(a and b) and c`.
+    To allow using a chain of multiple operators without parenthesis, like `a and b and c`, the option `leftAssociative` can be set `true`. Without this, an exception will be thrown, which can be solved by using parenthesis like `(a and b) and c`.
 
+    When the function of the operator supports more than two arguments, like `and(a, b, c, ...)`, the option `vararg` can be set `true`. In that case, a chain of operators like `a and b and c` will be parsed into the JSON Format `["and", a, b, c, ...]`.  Operators that do not support variable arguments, like `1 + 2 + 3`, will be parsed into a nested JSON Format like `["add", ["add", 1, 2], 3]`.
+  
     All build-in operators and their precedence are listed in the section [Operators](#operators).
 
 Here an example of using the function `jsonquery`:

src/functions.ts

@@ -27,10 +27,6 @@ export function buildFunction(fn: (...args: unknown[]) => unknown): FunctionBuil
   }
 }
 
-const reduceArgs = (fn: (...args: unknown[]) => unknown) => {
-  return (...args: unknown[]) => args.reduce(fn)
-}
-
 export const functions: FunctionBuildersMap = {
   pipe: (...entries: JSONQuery[]) => {
     const _entries = entries.map((entry) => compile(entry))
@@ -251,8 +247,8 @@ export const functions: FunctionBuildersMap = {
 
   max: () => (data: number[]) => Math.max(...data),
 
-  and: buildFunction(reduceArgs((a, b) => !!(a && b))),
-  or: buildFunction(reduceArgs((a, b) => !!(a || b))),
+  and: buildFunction((...args) => args.reduce((a, b) => !!(a && b))),
+  or: buildFunction((...args) => args.reduce((a, b) => !!(a || b))),
   not: buildFunction((a: unknown) => !a),
 
   exists: (queryGet: JSONQueryFunction) => {
@@ -297,11 +293,11 @@ export const functions: FunctionBuildersMap = {
   lte: buildFunction((a, b) => a <= b),
   ne: buildFunction((a, b) => a !== b),
 
-  add: buildFunction(reduceArgs((a: number, b: number) => a + b)),
-  subtract: buildFunction(reduceArgs((a: number, b: number) => a - b)),
-  multiply: buildFunction(reduceArgs((a: number, b: number) => a * b)),
-  divide: buildFunction(reduceArgs((a: number, b: number) => a / b)),
-  mod: buildFunction(reduceArgs((a: number, b: number) => a % b)),
+  add: buildFunction((a: number, b: number) => a + b),
+  subtract: buildFunction((a: number, b: number) => a - b),
+  multiply: buildFunction((a: number, b: number) => a * b),
+  divide: buildFunction((a: number, b: number) => a / b),
+  mod: buildFunction((a: number, b: number) => a % b),
   pow: buildFunction((a: number, b: number) => a ** b),
 
   abs: buildFunction(Math.abs),

src/operators.ts

@@ -13,7 +13,8 @@ export const operators: OperatorGroup[] = [
   { or: 'or' }
 ]
 
-export const varargOperators = ['|', '*', '/', '%', '+', '-', 'and', 'or']
+export const varargOperators = ['|', 'and', 'or']
+export const leftAssociativeOperators = ['|', 'and', 'or', '*', '/', '%', '+', '-']
 
 export function extendOperators(operators: OperatorGroup[], customOperators: CustomOperator[]) {
   // backward compatibility error with v4 where `operators` was an object
@@ -43,15 +44,3 @@ function extendOperator(
 
   throw new Error('Invalid custom operator')
 }
-
-export function extendVarargOperators(
-  varargOperators: string[],
-  customOperators: CustomOperator[]
-): string[] {
-  return [
-    ...varargOperators,
-    ...customOperators
-      .filter((customOperator) => customOperator.vararg)
-      .map((customOperator) => customOperator.op)
-  ]
-}

src/parse.test.ts

@@ -65,12 +65,28 @@ describe('customization', () => {
     expect(() => parse('2 ~= 3 ~= 4', options)).toThrow("Unexpected part '~= 4'")
   })
 
-  test('should parse a custom operator with vararg', () => {
+  test('should parse a custom operator with vararg without leftAssociative', () => {
     const options: JSONQueryParseOptions = {
       operators: [{ name: 'aboutEq', op: '~=', at: '==', vararg: true }]
     }
 
     expect(parse('2 and 3 and 4', options)).toEqual(['and', 2, 3, 4])
+    expect(parse('2 ~= 3', options)).toEqual(['aboutEq', 2, 3])
+    expect(parse('2 ~= 3 and 4', options)).toEqual(['and', ['aboutEq', 2, 3], 4])
+    expect(parse('2 and 3 ~= 4', options)).toEqual(['and', 2, ['aboutEq', 3, 4]])
+    expect(parse('2 == 3 ~= 4', options)).toEqual(['aboutEq', ['eq', 2, 3], 4])
+    expect(parse('2 ~= 3 == 4', options)).toEqual(['eq', ['aboutEq', 2, 3], 4])
+    expect(() => parse('2 ~= 3 ~= 4', options)).toThrow("Unexpected part '~= 4'")
+    expect(() => parse('2 == 3 == 4', options)).toThrow("Unexpected part '== 4'")
+  })
+
+  test('should parse a custom operator with vararg with leftAssociative', () => {
+    const options: JSONQueryParseOptions = {
+      operators: [{ name: 'aboutEq', op: '~=', at: '==', vararg: true, leftAssociative: true }]
+    }
+
+    expect(parse('2 and 3 and 4', options)).toEqual(['and', 2, 3, 4])
+    expect(parse('2 ~= 3', options)).toEqual(['aboutEq', 2, 3])
     expect(parse('2 ~= 3 ~= 4', options)).toEqual(['aboutEq', 2, 3, 4])
     expect(() => parse('2 == 3 == 4', options)).toThrow("Unexpected part '== 4'")
   })

src/parse.ts

@@ -1,5 +1,5 @@
 import { functions } from './functions'
-import { extendOperators, extendVarargOperators, operators, varargOperators } from './operators'
+import { extendOperators, leftAssociativeOperators, operators, varargOperators } from './operators'
 import {
   startsWithIntRegex,
   startsWithKeywordRegex,
@@ -30,7 +30,12 @@ export function parse(query: string, options?: JSONQueryParseOptions): JSONQuery
   const allFunctions = { ...functions, ...options?.functions }
   const allOperators = extendOperators(operators, customOperators)
   const allOperatorsMap = Object.assign({}, ...allOperators)
-  const allVarargOperators = extendVarargOperators(varargOperators, customOperators)
+  const allVarargOperators = varargOperators.concat(
+    customOperators.filter((op) => op.vararg).map((op) => op.op)
+  )
+  const allLeftAssociativeOperators = leftAssociativeOperators.concat(
+    customOperators.filter((op) => op.leftAssociative).map((op) => op.op)
+  )
 
   const parseOperator = (precedenceLevel: number) => {
     const currentOperators = allOperators[precedenceLevel]
@@ -54,12 +59,15 @@ export function parse(query: string, options?: JSONQueryParseOptions): JSONQuery
 
       const childName = left[0]
       const chained = name === childName && !leftParenthesis
-      if (chained && !allVarargOperators.includes(allOperatorsMap[name])) {
+      if (chained && !allLeftAssociativeOperators.includes(allOperatorsMap[name])) {
         i = start
         break
       }
 
-      left = chained ? [...left, right] : [name, left, right]
+      left =
+        chained && allVarargOperators.includes(allOperatorsMap[name])
+          ? [...left, right]
+          : [name, left, right]
     }
 
     return left

src/types.ts

@@ -34,9 +34,9 @@ export type FunctionBuildersMap = Record<string, FunctionBuilder>
 export type Getter = [key: string, Fun]
 export type OperatorGroup = Record<string, string>
 export type CustomOperator =
-  | { name: string; op: string; at: string; vararg?: boolean }
-  | { name: string; op: string; after: string; vararg?: boolean }
-  | { name: string; op: string; before: string; vararg?: boolean }
+  | { name: string; op: string; at: string; vararg?: boolean; leftAssociative?: boolean }
+  | { name: string; op: string; after: string; vararg?: boolean; leftAssociative?: boolean }
+  | { name: string; op: string; before: string; vararg?: boolean; leftAssociative?: boolean }
 
 export interface Entry<T> {
   key: string

test-suite/compile.test.json

@@ -948,13 +948,6 @@
       "query": ["and", true, true],
       "output": true
     },
-    {
-      "category": "and",
-      "description": "should calculate and with more than two arguments",
-      "input": null,
-      "query": ["and", true, true, false],
-      "output": false
-    },
 
     {
       "category": "or",
@@ -1282,13 +1275,6 @@
       "query": ["add", "is:", true],
       "output": "is:true"
     },
-    {
-      "category": "add",
-      "description": "should add more than two arguments",
-      "input": null,
-      "query": ["add", 6, 2, 3],
-      "output": 11
-    },
 
     {
       "category": "subtract",
@@ -1304,13 +1290,6 @@
       "query": ["subtract", 6, 2],
       "output": 4
     },
-    {
-      "category": "subtract",
-      "description": "should subtract more than two arguments",
-      "input": null,
-      "query": ["subtract", 6, 2, 1],
-      "output": 3
-    },
 
     {
       "category": "multiply",
@@ -1326,13 +1305,6 @@
       "query": ["multiply", 6, 2],
       "output": 12
     },
-    {
-      "category": "multiply",
-      "description": "should multiply more than two arguments",
-      "input": null,
-      "query": ["multiply", 6, 2, 3],
-      "output": 36
-    },
 
     {
       "category": "divide",
@@ -1348,13 +1320,6 @@
       "query": ["divide", 6, 2],
       "output": 3
     },
-    {
-      "category": "divide",
-      "description": "should divide more than two arguments",
-      "input": null,
-      "query": ["divide", 6, 2, 3],
-      "output": 1
-    },
 
     {
       "category": "pow",
@@ -1392,13 +1357,6 @@
       "query": ["mod", 8, 3],
       "output": 2
     },
-    {
-      "category": "mod",
-      "description": "should calculate the modulus for more than two arguments",
-      "input": null,
-      "query": ["mod", 20, 12, 3],
-      "output": 2
-    },
 
     {
       "category": "abs",

test-suite/parse.test.json

@@ -167,11 +167,11 @@
       "tests": [
         { "input": "1 and 2 and 3", "output": ["and", 1, 2, 3] },
         { "input": "1 or 2 or 3", "output": ["or", 1, 2, 3] },
-        { "input": "1 * 2 * 3", "output": ["multiply", 1, 2, 3] },
-        { "input": "1 / 2 / 3", "output": ["divide", 1, 2, 3] },
-        { "input": "1 % 2 % 3", "output": ["mod", 1, 2, 3] },
-        { "input": "1 + 2 + 3", "output": ["add", 1, 2, 3] },
-        { "input": "1 - 2 - 3", "output": ["subtract", 1, 2, 3] }
+        { "input": "1 * 2 * 3", "output": ["multiply", ["multiply", 1, 2], 3] },
+        { "input": "1 / 2 / 3", "output": ["divide", ["divide", 1, 2], 3] },
+        { "input": "1 % 2 % 3", "output": ["mod", ["mod", 1, 2], 3] },
+        { "input": "1 + 2 + 3", "output": ["add", ["add", 1, 2], 3] },
+        { "input": "1 - 2 - 3", "output": ["subtract", ["subtract", 1, 2], 3] }
       ]
     },
     {