@jbrowse/jexl 4.0.1 → 5.0.0

package/README.md

@@ -9,6 +9,12 @@ Major changes include
 - Remove array filtering expressions
 - Added template strings
 - Added multiple expression evaluation
+- Added lambdas and collection functions (`any(xs, x => x > 1)`)
+- Added host hooks for member and name resolution
+- Added `analyze()`, which reports what an expression reads without running it
+- Added `check()`, which checks an expression against a host's fields and
+  functions, and `print()`, which renders a parsed expression back to text
+- Added bcftools-style list operators, regex matching (`~`) and aggregates
 
 ## Quick Examples
 
@@ -54,9 +60,10 @@ jexl.eval('assoc[1].first', context)
 | Type             | Examples                                             |
 | ---------------- | ---------------------------------------------------- |
 | Booleans         | `true`, `false`                                      |
+| Null             | `null`                                               |
 | Strings          | `"Hello \"user\""`, `'Hey there!'`                   |
 | Template Strings | `` `Hello ${name}` ``, `` `Total: ${price * qty}` `` |
-| Numerics         | `6`, `-7.2`, `5`, `-3.14159`                         |
+| Numerics         | `6`, `-7.2`, `.5`, `1e3`, `-5e-8`                    |
 | Objects          | `{hello: "world!"}`                                  |
 | Arrays           | `['hello', 'world!']`                                |
 
@@ -89,7 +96,10 @@ jexl.eval('`Price: \\$100`')
 
 - Arithmetic: `+`, `-`, `*`, `/`, `//` (floor division), `%`, `^` (power)
 - Comparison: `==`, `!=`, `>`, `>=`, `<`, `<=`, `in`
-- Logical: `&&`, `||`
+- Regular expression match: `~`, `!~` (`name ~ '^BRCA'`; a leading `(?i)`
+  ignores case)
+- Logical: `&&`, `||`, `??` (`a ?? b` is `b` only when `a` is `null` or
+  `undefined`, so `score ?? 0` keeps a real 0)
 - Assignment: `=` (assigns a value to a bare variable name; `a.b = 1` is not
   supported)
 
@@ -97,6 +107,67 @@ jexl.eval('`Price: \\$100`')
 
 **Sequence:** `;` (separates multiple expressions)
 
+From loosest to tightest:
+
+| Operators                                         | Groups             |
+| ------------------------------------------------- | ------------------ |
+| `;`                                               |                    |
+| `=`, lambdas                                      | right to left      |
+| `? :`                                             | right to left      |
+| `\|\|`, `??`                                      | left to right      |
+| `&&`                                              | left to right      |
+| `==`, `!=`, `>`, `>=`, `<`, `<=`, `in`, `~`, `!~` | left to right      |
+| `+`, `-`                                          | left to right      |
+| `*`, `/`, `//`                                    | left to right      |
+| `%`, `^`                                          | `^` from the right |
+| prefix `!`, `-`                                   |                    |
+| `.`, `[]`, calls                                  | left to right      |
+
+As in JavaScript, `??` does not mix with `&&` or `||` without parentheses:
+`a ?? b || c` is a syntax error, `(a ?? b) || c` is not.
+
+### Lists
+
+Operators read a list the way bcftools reads a multi-valued VCF tag.
+
+A comparison holds when it holds for any value of the list, and `!=` and `!~`
+hold when no value matches, so each stays the negation of `==` and `~`:
+
+```javascript
+const context = {
+  AF: [0.01, 0.2],
+  FILTER: ['PASS'],
+  CSQ: ['T|missense_variant|MODERATE', 'T|synonymous_variant|LOW']
+}
+
+jexl.eval('AF > 0.05', context) // true: the second allele's frequency is
+jexl.eval("FILTER != 'PASS'", context) // false
+jexl.eval("CSQ ~ 'missense_variant'", context) // true
+jexl.eval("['DEL'] in ['DEL', 'INS']") // true
+```
+
+Arithmetic pairs lists value by value, and a single value, or a list of one,
+pairs with every value of the other side:
+
+```javascript
+jexl.eval('AC / AN', { AC: [2, 4], AN: [10] }) // [0.2, 0.4]
+jexl.eval('DP + 1', { DP: [25] }) // [26]
+```
+
+`in` finds a substring of a string, a member of a list or Set, or a key of an
+object or Map, so a host can hand an expression a gene list loaded from a file
+as a Set: `name in genes`.
+
+`sum`, `mean`, `median`, `min` and `max` aggregate a list, reading each value
+through an optional lambda. They skip missing values, and count a boolean as 1
+or 0, which makes `mean` of a test the fraction that pass:
+
+```javascript
+jexl.eval('min(DV / DP) > 0.3', context) // bcftools MIN(DV/DP)>0.3
+jexl.eval('count(samples, s => s.GQ > 90)', context) // bcftools N_PASS(GQ>90)
+jexl.eval('mean(samples, s => s.GQ > 90)', context) // bcftools F_PASS(GQ>90)
+```
+
 ### Identifiers
 
 Access context variables by name. Use dot notation or brackets for nested properties:
@@ -112,21 +183,25 @@ jexl.eval('name.first', context) // "Malory"
 jexl.eval('name["last"]', context) // "Archer"
 jexl.eval('exes[2]', context) // "Burt"
 jexl.eval('exes[lastEx - 1]', context) // "Len"
+jexl.eval('exes.length', context) // 3
 ```
 
+A name chained off an array reads the array itself, so `exes.length` is 3 and
+`list.name` is `undefined`; index the element you mean, `list[0].name`.
+
 ### Functions
 
 Call functions in expressions:
 
 ```javascript
-jexl.addFunction('min', Math.min)
-jexl.addFunction('max', Math.max)
+jexl.addFunction('log10', Math.log10)
+jexl.addFunction('round', Math.round)
 
-jexl.eval('min(5, 2, 9)')
-// 2
+jexl.eval('round(log10(1234))')
+// 3
 
-jexl.eval('max(temperature, threshold)')
-// evaluates with context
+jexl.eval('-log10(pvalue) > threshold', { pvalue: 1e-9, threshold: 8 })
+// true
 ```
 
 Functions live in one global pool and have no receiver, so a call written
@@ -144,9 +219,27 @@ jexl.eval("split(refName, ' ')[0]", { refName: 'chr1 description' }) // "chr1"
 Note that this is a naming convention, not method dispatch: `a.b(x)` calls the
 function named `b` in the pool, never a method on the value of `a`.
 
+### Lambdas
+
+`x => body` and `(a, b) => body` are functions a registered function can call.
+A parameter shadows the context variable of the same name; any other name reads
+the context. A lambda body cannot assign.
+
+Jexl registers `any`, `all`, `count`, `map`, `filter`, `find`, `sort` and
+`reduce`, each taking a list and a lambda, and the aggregates above. A lone value counts as a list of one
+and a missing value as an empty list, which suits VCF INFO fields:
+
+```javascript
+jexl.eval('any(feature.INFO.AF, af => af > 0.05)', context)
+jexl.eval('map(xs, (x, i) => x * i)', { xs: [1, 2, 3] }) // [0, 2, 6]
+jexl.eval('xs.filter(x => x > 1)', { xs: [1, 2, 3] }) // [2, 3]
+```
+
+A host function of the same name replaces the built-in one.
+
 ### Variable Assignment
 
-Assign values to variables using `=` (no `let`, `var`, or `const` needed). Assignments mutate the context and return the assigned value:
+Assign values to variables using `=` (no `let`, `var`, or `const` needed). An assignment returns the assigned value, and the variable lasts for the rest of that evaluation. The context is never written to, so one context object can be reused across evaluations:
 
 ```javascript
 jexl.eval('x = 5')
@@ -158,13 +251,14 @@ jexl.eval('x = 5; x * 2')
 jexl.eval('x = 5; y = 10; x + y')
 // 15
 
-const context = {}
-jexl.eval('x = 5; y = x * 2; y', context)
-// 10
-// context is now { x: 5, y: 10 }
+const context = { x: 1 }
+jexl.eval('y = x * 2; x = y + 1; x', context)
+// 3
+// context is still { x: 1 }
 ```
 
-Separate multiple expressions with semicolons. The result is the value of the last expression:
+Separate multiple expressions with semicolons. The result is the value of the
+last expression.
 
 ## API
 
@@ -190,15 +284,14 @@ jexl.addFunction('lower', (str) => str.toLowerCase())
 
 // Add multiple functions
 jexl.addFunctions({
-  min: Math.min,
-  max: Math.max,
-  abs: Math.abs
+  abs: Math.abs,
+  sqrt: Math.sqrt
 })
 
 // Use in expressions
 jexl.eval('round(3.7)') // 4
 jexl.eval('lower(name)', { name: 'HELLO' }) // "hello"
-jexl.eval('max(1, 5, 3)') // 5
+jexl.eval('sqrt(abs(-16))') // 4
 ```
 
 ### Adding Custom Operators
@@ -214,11 +307,61 @@ jexl.addBinaryOp(
 jexl.eval('"Hello" ~= "hello"') // true
 
 // Add a unary operator
-jexl.addUnaryOp('~', (right) => Math.floor(right))
+jexl.addUnaryOp('#', (right) => Math.floor(right))
 
-jexl.eval('~3.7') // 3
+jexl.eval('#3.7') // 3
 ```
 
+### Resolving Names Through the Host
+
+When the values in a context keep their fields behind an accessor, a Jexl instance can resolve names itself instead of reading plain properties. Both hooks are fixed when the instance is constructed.
+
+```javascript
+import { Jexl } from '@jbrowse/jexl'
+
+const jexl = new Jexl({
+  // `a.b` and `a[k]`, on any value that isn't null or undefined
+  getMember: (subject, key) =>
+    subject instanceof Feature ? subject.get(key) : subject[key],
+  // a bare name, asked once per name as an expression compiles; returning
+  // undefined keeps the plain `context[name]` read
+  variableReader: (name) =>
+    name === 'feature'
+      ? undefined
+      : (context) => context.feature.get(name) ?? context[name]
+})
+
+const expr = jexl.compile('feature.score > 10 && -log10(pvalue) > 2')
+const context = { feature: undefined }
+for (const feature of features) {
+  context.feature = feature
+  expr.eval(context)
+}
+```
+
+A name the expression assigns reads the assignment once it has run, and goes through `variableReader` before then.
+
+### Analyzing Expressions
+
+`analyze` reports what an expression reads, without evaluating it or needing
+its functions registered:
+
+```javascript
+const expr = jexl.compile("get(feature, 'score') > 10 ? feature.name : 'n/a'")
+expr.analyze({ accessors: { get: [] }, row: 'feature' })
+// {
+//   variables: ['feature'],
+//   fields: [{ path: ['score'] }, { path: ['name'] }],
+//   bare: false,
+//   ...
+// }
+```
+
+`accessors` names functions that read a path off their first argument, so
+`get(feature, 'score')` and `feature.score` both read the field `score`. An
+expression with no `variables` is a constant; one whose `bare` is true is only
+a path, which a host can read without jexl.
+
 ## License
 
 MIT License, same as TomFrost/Jexl

package/dist/Expression.d.ts

@@ -1,4 +1,6 @@
 import Lexer from './Lexer.ts';
+import type { AnalyzeOptions } from './analyze.ts';
+import type { CheckOptions } from './check.ts';
 import type { CompiledNode } from './evaluator/compile.ts';
 import type { Grammar } from './grammar.ts';
 import type { AstNode } from './types.ts';
@@ -36,5 +38,19 @@ declare class Expression {
      * @throws {*} on error
      */
     eval(context?: {}): import("./types.ts").JexlValue;
+    /** The expression text this Expression was made from. */
+    get source(): string;
+    /** The parsed tree, or null for an expression with no tokens. */
+    get ast(): AstNode | null;
+    /**
+     * Lists what the expression reads from its context, without evaluating it.
+     * See {@link analyze}.
+     */
+    analyze(options?: AnalyzeOptions): import("./analyze.ts").Analysis;
+    /**
+     * Checks the expression against a host's fields and functions, without
+     * evaluating it. See {@link check}.
+     */
+    check(options?: CheckOptions): import("./check.ts").CheckResult;
 }
 export default Expression;

package/dist/Expression.js

@@ -8,6 +8,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const Lexer_ts_1 = __importDefault(require("./Lexer.js"));
+const analyze_ts_1 = require("./analyze.js");
+const check_ts_1 = require("./check.js");
 const compile_ts_1 = require("./evaluator/compile.js");
 const Parser_ts_1 = __importDefault(require("./parser/Parser.js"));
 class Expression {
@@ -42,10 +44,7 @@ class Expression {
      * @returns {Expression} this Expression instance, for convenience
      */
     compile() {
-        const parser = new Parser_ts_1.default(this._grammar, this._lexer);
-        const tokens = this._lexer.tokenize(this._exprStr);
-        parser.addTokens(tokens);
-        this._ast = parser.complete();
+        this._ast = new Parser_ts_1.default(this._grammar, this._lexer).parse(this._exprStr);
         // lower the tree to closures once, here, so that eval() is just a call
         this._fn = this._ast ? (0, compile_ts_1.compileAst)(this._ast, this._grammar) : null;
         this._compiled = true;
@@ -68,6 +67,31 @@ class Expression {
         }
         return this._fn(context);
     }
+    /** The expression text this Expression was made from. */
+    get source() {
+        return this._exprStr;
+    }
+    /** The parsed tree, or null for an expression with no tokens. */
+    get ast() {
+        if (!this._compiled) {
+            this.compile();
+        }
+        return this._ast;
+    }
+    /**
+     * Lists what the expression reads from its context, without evaluating it.
+     * See {@link analyze}.
+     */
+    analyze(options) {
+        return (0, analyze_ts_1.analyze)(this.ast, options);
+    }
+    /**
+     * Checks the expression against a host's fields and functions, without
+     * evaluating it. See {@link check}.
+     */
+    check(options) {
+        return (0, check_ts_1.check)(this.ast, options);
+    }
 }
 exports.default = Expression;
 //# sourceMappingURL=Expression.js.map

package/dist/Expression.js.map

@@ -1 +1 @@
-{"version":3,"file":"Expression.js","sourceRoot":"","sources":["../src/Expression.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;AAEH,0DAA8B;AAC9B,uDAAmD;AACnD,mEAAuC;AAMvC,MAAM,UAAU;IACd,QAAQ,CAAS;IACjB,QAAQ,CAAQ;IAChB;;oDAEgD;IAChD,IAAI,CAAgB;IACpB,MAAM,CAAO;IACb,SAAS,GAAG,KAAK,CAAA;IACjB,2EAA2E;IAC3E,GAAG,GAAwB,IAAI,CAAA;IAE/B;;;;;;;OAOG;IACH,YAAY,OAAgB,EAAE,OAAe,EAAE,KAAa;QAC1D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;QACvB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,MAAM,GAAG,KAAK,IAAI,IAAI,kBAAK,CAAC,OAAO,CAAC,CAAA;IAC3C,CAAC;IAED;;;;;OAKG;IACH,OAAO;QACL,MAAM,MAAM,GAAG,IAAI,mBAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QACrD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAClD,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;QAC7B,uEAAuE;QACvE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAA,uBAAU,EAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QAClE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,GAAG,EAAE;QACf,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,OAAO,EAAE,CAAA;QAChB,CAAC;QACD,qEAAqE;QACrE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACd,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAC1B,CAAC;CACF;AAED,kBAAe,UAAU,CAAA"}
+{"version":3,"file":"Expression.js","sourceRoot":"","sources":["../src/Expression.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;AAEH,0DAA8B;AAC9B,6CAAsC;AACtC,yCAAkC;AAClC,uDAAmD;AACnD,mEAAuC;AAQvC,MAAM,UAAU;IACd,QAAQ,CAAS;IACjB,QAAQ,CAAQ;IAChB;;oDAEgD;IAChD,IAAI,CAAgB;IACpB,MAAM,CAAO;IACb,SAAS,GAAG,KAAK,CAAA;IACjB,2EAA2E;IAC3E,GAAG,GAAwB,IAAI,CAAA;IAE/B;;;;;;;OAOG;IACH,YAAY,OAAgB,EAAE,OAAe,EAAE,KAAa;QAC1D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;QACvB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,MAAM,GAAG,KAAK,IAAI,IAAI,kBAAK,CAAC,OAAO,CAAC,CAAA;IAC3C,CAAC;IAED;;;;;OAKG;IACH,OAAO;QACL,IAAI,CAAC,IAAI,GAAG,IAAI,mBAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACvE,uEAAuE;QACvE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAA,uBAAU,EAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QAClE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,GAAG,EAAE;QACf,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,OAAO,EAAE,CAAA;QAChB,CAAC;QACD,qEAAqE;QACrE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACd,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAC1B,CAAC;IAED,yDAAyD;IACzD,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,QAAQ,CAAA;IACtB,CAAC;IAED,iEAAiE;IACjE,IAAI,GAAG;QACL,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,OAAO,EAAE,CAAA;QAChB,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAA;IAClB,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,OAAwB;QAC9B,OAAO,IAAA,oBAAO,EAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IACnC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAsB;QAC1B,OAAO,IAAA,gBAAK,EAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IACjC,CAAC;CACF;AAED,kBAAe,UAAU,CAAA"}

package/dist/Jexl.d.ts

@@ -1,7 +1,17 @@
 import Expression from './Expression.ts';
 import Lexer from './Lexer.ts';
-import type { BinaryOpEvalOnDemand, Grammar, GrammarElement, GrammarFn, UncheckedFn } from './grammar.ts';
+import type { BinaryOpEvalOnDemand, GetMember, Grammar, GrammarElement, GrammarFn, UncheckedFn, VariableReader } from './grammar.ts';
 import type { JexlValue } from './types.ts';
+/**
+ * Hooks for a host whose values keep their fields behind an accessor. Both are
+ * fixed at construction, since a compiled expression binds them.
+ */
+export interface JexlOptions {
+    /** Resolves `a.b` and `a[k]`. */
+    getMember?: GetMember;
+    /** Resolves a bare name, such as a field of the current row. */
+    variableReader?: VariableReader;
+}
 /**
  * Jexl is the Javascript Expression Language, capable of parsing and
  * evaluating basic to complex expression strings, combined with advanced
@@ -11,7 +21,8 @@ import type { JexlValue } from './types.ts';
 declare class Jexl {
     _grammar: Grammar;
     _lexer: Lexer;
-    constructor();
+    _compiled: Map<string, Expression>;
+    constructor({ getMember, variableReader }?: JexlOptions);
     /**
      * Adds a binary operator to Jexl at the specified precedence. The higher the
      * precedence, the earlier the operator is applied in the order of operations.
@@ -59,12 +70,10 @@ declare class Jexl {
      */
     addUnaryOp(operator: string, fn: UncheckedFn): void;
     /**
-     * Creates an Expression object from the given Jexl expression string, and
-     * immediately compiles it. The returned Expression object can then be
-     * evaluated multiple times with new contexts, without generating any
-     * additional string processing overhead.
-     * @param {string} expression The Jexl expression to be compiled
-     * @returns {Expression} The compiled Expression object
+     * Compiles an expression string, or returns the Expression this instance
+     * already compiled from the same string. Adding or removing an operator
+     * empties the cache, since a compiled expression binds its operators;
+     * functions are looked up per call and leave it alone.
      */
     compile(expression: string): Expression;
     /**
@@ -74,6 +83,8 @@ declare class Jexl {
      * @returns {Expression} The Expression object representing the given string
      */
     createExpression(expression: string): Expression;
+    /** Parses an expression string, or throws a JexlSyntaxError. */
+    parse(expression: string): import("./types.ts").AstNode | null;
     /**
      * Retrieves a previously set expression function.
      * @param {string} name The name of the expression function
@@ -109,6 +120,7 @@ declare class Jexl {
      * @private
      */
     _addGrammarElement(str: string, obj: GrammarElement): void;
+    _grammarChanged(): void;
 }
 declare const jexlInstance: Jexl;
 export default jexlInstance;

package/dist/Jexl.js

@@ -11,6 +11,7 @@ exports.Jexl = void 0;
 const Expression_ts_1 = __importDefault(require("./Expression.js"));
 const Lexer_ts_1 = __importDefault(require("./Lexer.js"));
 const grammar_ts_1 = require("./grammar.js");
+const MAX_COMPILED = 10_000;
 /**
  * Jexl is the Javascript Expression Language, capable of parsing and
  * evaluating basic to complex expression strings, combined with advanced
@@ -22,24 +23,30 @@ class Jexl {
     // shared by every Expression this instance creates, so that the expensive
     // element-splitting regex is built once rather than per compile
     _lexer;
-    constructor() {
-        this._grammar = (0, grammar_ts_1.getGrammar)();
+    _compiled = new Map();
+    constructor({ getMember, variableReader } = {}) {
+        this._grammar = { ...(0, grammar_ts_1.getGrammar)(), getMember, variableReader };
         this._lexer = new Lexer_ts_1.default(this._grammar);
         this.expr = this.expr.bind(this);
     }
     addBinaryOp(operator, precedence, fn, manualEval) {
+        // replacing `-` keeps its prefix form, which is a separate operation
+        const previous = this._grammar.elements[operator];
+        const unaryEval = previous?.type === 'binaryOp' ? previous.unaryEval : undefined;
         // the overloads above pair `fn` with `manualEval`; the implementation
         // signature can't express that correlation, hence the assertions
         this._addGrammarElement(operator, manualEval
             ? {
                 type: 'binaryOp',
                 precedence,
-                evalOnDemand: fn
+                evalOnDemand: fn,
+                unaryEval
             }
             : {
                 type: 'binaryOp',
                 precedence,
-                eval: fn
+                eval: fn,
+                unaryEval
             });
     }
     /**
@@ -80,16 +87,21 @@ class Jexl {
         });
     }
     /**
-     * Creates an Expression object from the given Jexl expression string, and
-     * immediately compiles it. The returned Expression object can then be
-     * evaluated multiple times with new contexts, without generating any
-     * additional string processing overhead.
-     * @param {string} expression The Jexl expression to be compiled
-     * @returns {Expression} The compiled Expression object
+     * Compiles an expression string, or returns the Expression this instance
+     * already compiled from the same string. Adding or removing an operator
+     * empties the cache, since a compiled expression binds its operators;
+     * functions are looked up per call and leave it alone.
      */
     compile(expression) {
-        const exprObj = this.createExpression(expression);
-        return exprObj.compile();
+        let compiled = this._compiled.get(expression);
+        if (!compiled) {
+            compiled = this.createExpression(expression).compile();
+            if (this._compiled.size >= MAX_COMPILED) {
+                this._compiled.delete(this._compiled.keys().next().value);
+            }
+            this._compiled.set(expression, compiled);
+        }
+        return compiled;
     }
     /**
      * Constructs an Expression object from a Jexl expression string.
@@ -100,6 +112,10 @@ class Jexl {
     createExpression(expression) {
         return new Expression_ts_1.default(this._grammar, expression, this._lexer);
     }
+    /** Parses an expression string, or throws a JexlSyntaxError. */
+    parse(expression) {
+        return this.compile(expression).ast;
+    }
     /**
      * Retrieves a previously set expression function.
      * @param {string} name The name of the expression function
@@ -117,8 +133,7 @@ class Jexl {
      * @throws {*} on error
      */
     eval(expression, context = {}) {
-        const exprObj = this.createExpression(expression);
-        return exprObj.eval(context);
+        return this.compile(expression).eval(context);
     }
     /**
      * A JavaScript template literal to allow expressions to be defined by the
@@ -152,7 +167,7 @@ class Jexl {
         const elem = this._grammar.elements[operator];
         if (elem?.type === 'binaryOp' || elem?.type === 'unaryOp') {
             Reflect.deleteProperty(this._grammar.elements, operator);
-            this._lexer._clearCache();
+            this._grammarChanged();
         }
     }
     /**
@@ -164,7 +179,11 @@ class Jexl {
      */
     _addGrammarElement(str, obj) {
         this._grammar.elements[str] = obj;
+        this._grammarChanged();
+    }
+    _grammarChanged() {
         this._lexer._clearCache();
+        this._compiled.clear();
     }
 }
 exports.Jexl = Jexl;

package/dist/Jexl.js.map

@@ -1 +1 @@
-{"version":3,"file":"Jexl.js","sourceRoot":"","sources":["../src/Jexl.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Jexl.js","sourceRoot":"","sources":["../src/Jexl.ts"],"names":[],"mappings":"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"}

package/dist/Lexer.d.ts

@@ -78,10 +78,11 @@ declare class Lexer {
      * @throws {Error} if the provided string is not a valid expression element.
      * @private
      */
-    _createToken(element: string): Token;
+    _createToken(element: string, offset?: number): Token;
     /**
      * Escapes a string so that it can be treated as a string literal within a
-     * regular expression.
+     * regular expression. A word such as `in` also stops matching inside a
+     * longer name.
      * @param {string} str The string to be escaped
      * @returns {string} the RegExp-escaped string.
      * @see https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Regular_Expressions
@@ -126,7 +127,7 @@ declare class Lexer {
      * @private
      */
     _unquote(str: string): string;
-    _parseTemplateString(str: string): TemplatePart[];
+    _parseTemplateString(str: string, offset?: number): TemplatePart[];
     _unescapeTemplateString(str: string): string;
 }
 export default Lexer;