feat: 🎸 add initial codebase

Author: streamich

README.md

@@ -6,8 +6,111 @@ data model and syntax.
 
 JSON Expressions are JIT compiled to efficient machine code.
 
-Example `1 + 2` JSON Expression:
+JSON Expression is a simple JSON DSL, which allows to write expressions and
+evaluate expressions.
 
-```json
-["+", 1, 2]
+For example, the following expression
+
+```js
+['+', 1, 2]; // 1 + 2
+```
+
+evaluates to 3.
+
+
+## Usage
+
+`json-expression` library can immediately evaluate expressions or it can
+compile an efficient expression to a function, which will execute about
+an order of magnitude faster.
+
+Evaluating expression immediately as-is.
+
+```ts
+import {evaluate} from '@jsonjoy.com/json-expression';
+
+const expression = ['+', 1, ['$', '/foo']];
+const data = {foo: 2};
+
+evaluate(expression, {data}); // 3
+```
+
+Pre-compiling expression to an optimized function.
+
+```ts
+import {JsonExpressionCodegen} from '@jsonjoy.com/json-expression';
+
+const expression = ['+', 1, ['$', '/foo']];
+const codegen = new JsonExpressionCodegen({expression});
+const fn = codegen.run().compile();
+const data = {foo: 2};
+
+fn({data}); // 3
+```
+
+
+## Documentation
+
+`json-expression` library supports few dozen operators, see full list in `Expr`
+type [here](./types.ts).
+
+Parsing rules:
+
+1. JSON Expression is a valid JSON value.
+2. All expressions are JSON arrays, which start with a string which specifies
+   the operator and remaining array elements are operands. For example, the
+   "get" operator fetches some value from supplied data using JSON
+   Pointer:`["get", "/some/path"]`.
+3. All other values are treated as literals. Except for arrays, which need to
+   be enclosed in square brackets. For example, to specify an empty array, you
+   box your array in square brackets: `[[]]`. This evaluates to an empty array
+   JSON value `[]`.
+
+
+## Use Cases
+
+Consider you application receives a stream of JSON Cloud Events, like this:
+
+```js
+{
+  "specversion" : "1.0",
+  "type" : "com.example.someevent",
+  "source" : "/mycontext",
+  "subject": null,
+  "id" : "C234-1234-1234",
+  "time" : "2018-04-05T17:31:00Z",
+  "comexampleextension1" : "value",
+  "comexampleothervalue" : 5,
+  "datacontenttype" : "application/json",
+  "data" : {
+      "appinfoA" : "abc",
+      "appinfoB" : 123,
+      "appinfoC" : true
+  }
+}
+```
+
+You could write and compile a JSON Expression to efficiently filter out events
+you are interested in, for example your expression could look like this:
+
+```js
+[
+  'and',
+  ['==', ['$', '/specversion'], '1.0'],
+  ['starts', ['$', '/type'], 'com.example.'],
+  ['in', ['$', '/datacontenttype'], [['application/octet-stream', 'application/json']]],
+  ['==', ['$', '/data/appinfoA'], 'abc'],
+];
+```
+
+
+## Benchmark
+
+```
+node benchmarks/json-expression/main.js
+json-joy/json-expression JsonExpressionCodegen x 14,557,786 ops/sec ±0.09% (100 runs sampled), 69 ns/op
+json-joy/json-expression JsonExpressionCodegen with codegen x 170,098 ops/sec ±0.13% (101 runs sampled), 5879 ns/op
+json-joy/json-expression evaluate x 864,956 ops/sec ±0.10% (101 runs sampled), 1156 ns/op
+json-logic-js x 821,799 ops/sec ±0.18% (99 runs sampled), 1217 ns/op
+Fastest is json-joy/json-expression JsonExpressionCodegen
 ```

package.json

@@ -42,8 +42,11 @@
     "lint:fix": "biome lint --apply ./src",
     "clean": "npx rimraf@6.0.1 lib typedocs coverage gh-pages yarn-error.log",
     "build": "tsc --project tsconfig.build.json --module commonjs --target es2020 --outDir lib",
-    "test": "vitest ./src",
-    "coverage": "vitest run --coverage",
+    "jest": "jest",
+    "test": "jest --maxWorkers 7",
+    "test:all": "yarn lint && yarn test && yarn build:all && yarn test:cli:pointer && yarn test:cli:patch && yarn test:cli:pack && yarn demo:json-patch",
+    "test:ci": "yarn jest --maxWorkers 3 --no-cache",
+    "coverage": "yarn test --collectCoverage",
     "typedoc": "npx typedoc@0.25.13 --tsconfig tsconfig.build.json",
     "build:pages": "npx rimraf@6.0.1 gh-pages && mkdir -p gh-pages && cp -r typedocs/* gh-pages && cp -r coverage gh-pages/coverage",
     "deploy:pages": "gh-pages -d gh-pages",
@@ -53,16 +56,31 @@
     "tslib": "2"
   },
   "dependencies": {
+    "@jsonjoy.com/json-pointer": "^1.0.0",
     "@jsonjoy.com/util": "^1.3.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.3",
     "@types/benchmark": "^2.1.5",
-    "@vitest/coverage-v8": "^2.1.2",
+    "@types/jest": "^29.5.12",
     "benchmark": "^2.1.4",
     "config-galore": "^1.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
     "tslib": "^2.7.0",
-    "typescript": "^5.6.2",
-    "vitest": "^2.1.2"
+    "typescript": "^5.6.2"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "ts",
+      "js"
+    ],
+    "transform": {
+      "^.+\\.ts$": "ts-jest"
+    },
+    "transformIgnorePatterns": [
+      ".*/node_modules/.*"
+    ],
+    "testRegex": ".*/(__tests__|__jest__|demo)/.*\\.(test|spec)\\.ts$"
   }
 }

src/Vars.ts

@@ -0,0 +1,38 @@
+import {get} from '@jsonjoy.com/json-pointer/lib/get';
+import {toPath} from '@jsonjoy.com/json-pointer/lib/util';
+import {validateJsonPointer} from '@jsonjoy.com/json-pointer/lib/validate';
+
+export class Vars {
+  protected readonly vars: Map<string, unknown> = new Map();
+
+  constructor(public readonly env: unknown) {
+    this.env = env;
+  }
+
+  public get(name: string): unknown {
+    if (!name) return this.env;
+    return this.vars.get(name);
+  }
+
+  public set(name: string, value: unknown): void {
+    if (!name) throw new Error('Invalid varname.');
+    this.vars.set(name, value);
+  }
+
+  public has(name: string): boolean {
+    if (!name) return true;
+    return this.vars.has(name);
+  }
+
+  public del(name: string): boolean {
+    if (!name) throw new Error('Invalid varname.');
+    return this.vars.delete(name);
+  }
+
+  public find(name: string, pointer: string): unknown {
+    const data = this.get(name);
+    validateJsonPointer(pointer);
+    const path = toPath(pointer);
+    return get(data, path);
+  }
+}

src/__bench__/main.ts

@@ -0,0 +1,72 @@
+/* tslint:disable no-console */
+
+// npx ts-node src/json-expression/__bench__/main.ts
+
+import * as Benchmark from 'benchmark';
+import {JsonExpressionCodegen} from '../codegen';
+import {Expr} from '../types';
+import {evaluate} from '../evaluate';
+import {operatorsMap} from '../operators';
+import {Vars} from '../Vars';
+const jsonLogic = require('json-logic-js');
+
+const json = {
+  specversion: '1.0',
+  type: 'com.example.someevent',
+  source: '/mycontext',
+  subject: null,
+  id: 'C234-1234-1234',
+  time: '2018-04-05T17:31:00Z',
+  comexampleextension1: 'value',
+  comexampleothervalue: 5,
+  datacontenttype: 'application/json',
+  data: {
+    appinfoA: 'abc',
+    appinfoB: 123,
+    appinfoC: true,
+  },
+};
+
+const expression: Expr = [
+  'and',
+  ['==', ['get', '/specversion'], '1.0'],
+  ['starts', ['get', '/type'], 'com.example.'],
+  ['in', ['get', '/datacontenttype'], [['application/octet-stream', 'application/json']]],
+  ['==', ['$', '/data/appinfoA'], 'abc'],
+];
+
+const jsonLogicExpression = {
+  and: [
+    {'==': [{var: 'specversion'}, '1.0']},
+    {'==': [{substr: [{var: 'type'}, 0, 12]}, 'com.example.']},
+    {in: [{var: 'datacontenttype'}, ['application/octet-stream', 'application/json']]},
+    {'==': [{var: 'data.appinfoA'}, 'abc']},
+  ],
+};
+
+const codegen = new JsonExpressionCodegen({expression, operators: operatorsMap});
+const fn = codegen.run().compile();
+
+const suite = new Benchmark.Suite();
+suite
+  .add(`json-joy/json-expression JsonExpressionCodegen`, () => {
+    fn({vars: new Vars(json)});
+  })
+  .add(`json-joy/json-expression JsonExpressionCodegen with codegen`, () => {
+    const codegen = new JsonExpressionCodegen({expression, operators: operatorsMap});
+    const fn = codegen.run().compile();
+    fn({vars: new Vars(json)});
+  })
+  .add(`json-joy/json-expression evaluate`, () => {
+    evaluate(expression, {vars: new Vars(json)});
+  })
+  .add(`json-logic-js`, () => {
+    jsonLogic.apply(jsonLogicExpression, json);
+  })
+  .on('cycle', (event: any) => {
+    console.log(String(event.target) + `, ${Math.round(1000000000 / event.target.hz)} ns/op`);
+  })
+  .on('complete', () => {
+    console.log('Fastest is ' + suite.filter('fastest').map('name'));
+  })
+  .run();

src/__tests__/codegen.spec.ts

@@ -0,0 +1,27 @@
+import {Vars} from '../Vars';
+import {JsonExpressionCodegen} from '../codegen';
+import {operatorsMap} from '../operators';
+import {Expr, JsonExpressionCodegenContext} from '../types';
+import {jsonExpressionCodegenTests} from './jsonExpressionCodegenTests';
+import {jsonExpressionEvaluateTests} from './jsonExpressionEvaluateTests';
+import {jsonExpressionUnitTests} from './jsonExpressionUnitTests';
+
+const check = (
+  expression: Expr,
+  expected: unknown,
+  data: unknown = null,
+  options: JsonExpressionCodegenContext = {},
+) => {
+  const codegen = new JsonExpressionCodegen({
+    ...options,
+    expression,
+    operators: operatorsMap,
+  });
+  const fn = codegen.run().compile();
+  const result = fn(new Vars(data));
+  expect(result).toStrictEqual(expected);
+};
+
+jsonExpressionUnitTests(check);
+jsonExpressionCodegenTests(check);
+jsonExpressionEvaluateTests(check);

src/__tests__/evaluate.spec.ts

@@ -0,0 +1,20 @@
+import {Vars} from '../Vars';
+import {evaluate} from '../evaluate';
+import {Expr, JsonExpressionCodegenContext} from '../types';
+import {jsonExpressionCodegenTests} from './jsonExpressionCodegenTests';
+import {jsonExpressionEvaluateTests} from './jsonExpressionEvaluateTests';
+import {jsonExpressionUnitTests} from './jsonExpressionUnitTests';
+
+const check = (
+  expression: Expr,
+  expected: unknown,
+  data: unknown = null,
+  options: JsonExpressionCodegenContext = {},
+) => {
+  const res = evaluate(expression, {...options, vars: new Vars(data)});
+  expect(res).toStrictEqual(expected);
+};
+
+jsonExpressionUnitTests(check);
+jsonExpressionEvaluateTests(check);
+jsonExpressionCodegenTests(check, {skipOperandArityTests: true});

src/__tests__/impure.spec.ts

@@ -0,0 +1,32 @@
+import {Vars} from '../Vars';
+import {JsonExpressionCodegen} from '../codegen';
+import {operatorsMap} from '../operators';
+import {Expr, JsonExpressionCodegenContext} from '../types';
+
+const compile = (expression: Expr, options: JsonExpressionCodegenContext = {}) => {
+  const codegen = new JsonExpressionCodegen({
+    ...options,
+    expression,
+    operators: operatorsMap,
+  });
+  const fn = codegen.run().compile();
+  return (data: unknown) => fn(new Vars(data));
+};
+
+test('can execute expression twice with different inputs', () => {
+  const fn = compile(['+', 1, ['$', '']]);
+  expect(fn(2)).toBe(3);
+  expect(fn(3)).toBe(4);
+});
+
+test('constant expression is collapsed', () => {
+  const fn = compile(['+', 1, 2]);
+  expect(fn(2)).toBe(3);
+  expect(fn(3)).toBe(3);
+});
+
+test('linked in dependencies are linked only once', () => {
+  const fn = compile(['/', ['/', ['$', ''], 2], 3]);
+  expect(fn(24)).toBe(4);
+  // Check that "slash" function is linked only once.
+});