@jbrowse/jexl 3.0.2 → 3.2.0

package/esm/types.d.ts

@@ -1,11 +1,19 @@
+export interface TemplatePart {
+    type: 'static' | 'interpolation';
+    value: string;
+}
+export type JexlValue = string | number | boolean | null | undefined | JexlValue[] | {
+    [key: string]: JexlValue;
+};
 export interface Token {
     type: string;
-    value: any;
+    value: string | number | boolean | TemplatePart[];
     raw: string;
 }
 export interface AstNode {
     type: string;
     _parent?: AstNode;
+    right?: AstNode;
 }
 export interface Literal extends AstNode {
     type: 'Literal';
@@ -36,18 +44,22 @@ export interface ObjectLiteral extends AstNode {
     type: 'ObjectLiteral';
     value: Record<string, AstNode>;
 }
+export type TemplateLiteralPart = {
+    type: 'static';
+    value: string;
+} | {
+    type: 'expression';
+    value: AstNode;
+};
 export interface TemplateLiteral extends AstNode {
     type: 'TemplateLiteral';
-    parts: {
-        type: 'static' | 'expression';
-        value: string | AstNode;
-    }[];
+    parts: TemplateLiteralPart[];
 }
 export interface FunctionCall extends AstNode {
     type: 'FunctionCall';
     name: string;
     args: AstNode[];
-    pool: 'functions' | 'transforms';
+    pool: 'functions';
 }
 export interface FilterExpression extends AstNode {
     type: 'FilterExpression';
@@ -69,7 +81,6 @@ export interface AssignmentExpression extends AstNode {
     type: 'AssignmentExpression';
     operator: '=';
     left: Identifier;
-    right: AstNode;
 }
 export type AstNodeUnion = Literal | Identifier | BinaryExpression | UnaryExpression | ArrayLiteral | ObjectLiteral | TemplateLiteral | FunctionCall | FilterExpression | ConditionalExpression | SequenceExpression | AssignmentExpression;
 export type NodeByType<T extends AstNodeUnion['type']> = Extract<AstNodeUnion, {

package/package.json

@@ -1,16 +1,12 @@
 {
   "name": "@jbrowse/jexl",
-  "version": "3.0.2",
+  "version": "3.2.0",
   "description": "A fork of the jexl lang for jbrowse",
   "type": "module",
-  "types": "./dist/index.d.ts",
+  "main": "dist/index.js",
   "exports": {
-    "import": {
-      "import": "./esm/index.js"
-    },
-    "require": {
-      "require": "./dist/index.js"
-    }
+    "import": "./esm/index.js",
+    "require": "./dist/index.js"
   },
   "files": [
     "dist",
@@ -18,20 +14,24 @@
     "src"
   ],
   "scripts": {
-    "format": "prettier --write .",
-    "lint": "eslint --report-unused-disable-directives --max-warnings 0",
     "test": "vitest",
+    "coverage": "pnpm test --coverage",
     "clean": "rimraf dist esm",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint --report-unused-disable-directives --max-warnings 0",
+    "typecheck": "tsc --noEmit -p tsconfig.lint.json",
+    "prebuild": "pnpm clean",
     "build:esm": "tsc --outDir esm",
-    "build:es5": "tsc --module commonjs --outDir dist",
-    "build": "yarn build:esm && yarn build:es5",
-    "prebuild": "yarn clean",
+    "build:es5": "tsc --module commonjs --moduleResolution bundler --outDir dist",
     "postbuild:es5": "echo '{\"type\": \"commonjs\"}' > dist/package.json",
-    "preversion": "yarn lint && yarn test --run && yarn build"
+    "preversion": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test --run && pnpm build",
+    "postversion": "git push --follow-tags",
+    "build": "pnpm build:esm && pnpm build:es5"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/TomFrost/jexl"
+    "url": "https://github.com/GMOD/jexl.git"
   },
   "keywords": [
     "JSON",
@@ -46,22 +46,19 @@
   ],
   "author": "Tom Shawver <tom@frosteddesign.com>",
   "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/TomFrost/jexl/issues"
-  },
-  "homepage": "https://github.com/TomFrost/jexl",
+  "packageManager": "pnpm@11.20.0",
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.3.3",
-    "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^10.0.2",
-    "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-unicorn": "^63.0.0",
-    "prettier": "^3.8.1",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "eslint": "^10.2.1",
+    "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-unicorn": "^64.0.0",
+    "prettier": "^3.8.3",
     "rimraf": "^6.1.3",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1",
-    "vitest": "^4.0.18"
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.0",
+    "vitest": "^4.1.5"
   },
   "publishConfig": {
     "access": "public"

package/src/Expression.ts

@@ -5,24 +5,38 @@
 
 import Lexer from './Lexer.ts'
 import Evaluator from './evaluator/Evaluator.ts'
+import { compileAst } from './evaluator/compile.ts'
 import Parser from './parser/Parser.ts'
 
+import type { CompiledNode } from './evaluator/compile.ts'
+import type { Grammar } from './grammar.ts'
 import type { AstNode } from './types.ts'
 
-interface Grammar {
-  elements: Record<string, any>
-  [key: string]: any
-}
-
 class Expression {
   _grammar: Grammar
   _exprStr: string
+  /** The parsed tree, exposed for inspection. Legitimately null for an
+   * expression with no tokens, which is why compilation is tracked by
+   * `_compiled` rather than by this being set. */
   _ast: AstNode | null
+  _lexer: Lexer
+  _compiled = false
+  // the AST lowered to closures, so repeated eval() calls skip node dispatch
+  _fn: CompiledNode | null = null
 
-  constructor(grammar: Grammar, exprStr: string) {
+  /**
+   * @param {{}} grammar The grammar to compile and evaluate against
+   * @param {string} exprStr The Jexl expression string
+   * @param {Lexer} [lexer] A Lexer to reuse. Lexers memoize the regex used to
+   *      split expressions, which is expensive to build, so passing a shared
+   *      one avoids paying that cost per expression. It must be invalidated
+   *      via {@link Lexer#_clearCache} whenever the grammar's elements change.
+   */
+  constructor(grammar: Grammar, exprStr: string, lexer?: Lexer) {
     this._grammar = grammar
     this._exprStr = exprStr
     this._ast = null
+    this._lexer = lexer ?? new Lexer(grammar)
   }
 
   /**
@@ -32,11 +46,13 @@ class Expression {
    * @returns {Expression} this Expression instance, for convenience
    */
   compile() {
-    const lexer = new Lexer(this._grammar)
-    const parser = new Parser(this._grammar, lexer)
-    const tokens = lexer.tokenize(this._exprStr)
+    const parser = new Parser(this._grammar, this._lexer)
+    const tokens = this._lexer.tokenize(this._exprStr)
     parser.addTokens(tokens)
     this._ast = parser.complete()
+    // lower the tree to closures once, here, so that eval() is just a call
+    this._fn = this._ast ? compileAst(this._ast, this._grammar) : null
+    this._compiled = true
     return this
   }
 
@@ -48,16 +64,14 @@ class Expression {
    * @throws {*} on error
    */
   eval(context = {}) {
-    const ast = this._getAst()
-    const evaluator = new Evaluator(this._grammar, context)
-    return evaluator.eval(ast!)
-  }
-
-  _getAst() {
-    if (!this._ast) {
+    if (!this._compiled) {
       this.compile()
     }
-    return this._ast
+    // an expression with no tokens (empty or whitespace-only) has no AST
+    if (!this._fn) {
+      return undefined
+    }
+    return this._fn(new Evaluator(this._grammar, context))
   }
 }
 

package/src/Jexl.ts

@@ -4,12 +4,16 @@
  */
 
 import Expression from './Expression.ts'
+import Lexer from './Lexer.ts'
 import { getGrammar } from './grammar.ts'
 
-interface Grammar {
-  elements: Record<string, any>
-  functions: Record<string, (...args: any[]) => any>
-}
+import type {
+  BinaryOpEval,
+  BinaryOpEvalOnDemand,
+  Grammar,
+  GrammarElement
+} from './grammar.ts'
+import type { JexlValue } from './types.ts'
 
 /**
  * Jexl is the Javascript Expression Language, capable of parsing and
@@ -19,9 +23,13 @@ interface Grammar {
  */
 class Jexl {
   _grammar: Grammar
+  // shared by every Expression this instance creates, so that the expensive
+  // element-splitting regex is built once rather than per compile
+  _lexer: Lexer
 
   constructor() {
     this._grammar = getGrammar()
+    this._lexer = new Lexer(this._grammar)
     this.expr = this.expr.bind(this)
   }
 
@@ -47,14 +55,33 @@ class Jexl {
   addBinaryOp(
     operator: string,
     precedence: number,
-    fn: (left: any, right: any) => any,
+    fn: BinaryOpEval,
+    manualEval?: false
+  ): void
+  addBinaryOp(
+    operator: string,
+    precedence: number,
+    fn: BinaryOpEvalOnDemand,
+    manualEval: true
+  ): void
+  addBinaryOp(
+    operator: string,
+    precedence: number,
+    fn: BinaryOpEval | BinaryOpEvalOnDemand,
     manualEval?: boolean
   ) {
-    this._addGrammarElement(operator, {
-      type: 'binaryOp',
-      precedence: precedence,
-      [manualEval ? 'evalOnDemand' : 'eval']: fn
-    })
+    // 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 as BinaryOpEvalOnDemand
+          }
+        : { type: 'binaryOp', precedence, eval: fn as BinaryOpEval }
+    )
   }
 
   /**
@@ -65,7 +92,7 @@ class Jexl {
    *      expression function is invoked. It will be provided with each argument
    *      supplied in the expression, in the same order.
    */
-  addFunction(name: string, fn: (...args: any[]) => any) {
+  addFunction(name: string, fn: (...args: JexlValue[]) => JexlValue) {
     this._grammar.functions[name] = fn
   }
 
@@ -75,7 +102,7 @@ class Jexl {
    * function counterpart.
    * @param {{}} map A map of expression function names to javascript functions
    */
-  addFunctions(map: Record<string, (...args: any[]) => any>) {
+  addFunctions(map: Record<string, (...args: JexlValue[]) => JexlValue>) {
     Object.assign(this._grammar.functions, map)
   }
 
@@ -87,10 +114,10 @@ class Jexl {
    *      will be called with one argument: the literal value to the right of the
    *      operator. It should return the resulting value.
    */
-  addUnaryOp(operator: string, fn: (right: any) => any) {
+  addUnaryOp(operator: string, fn: (right: JexlValue) => JexlValue) {
     this._addGrammarElement(operator, {
       type: 'unaryOp',
-      weight: Infinity,
+      precedence: Infinity,
       eval: fn
     })
   }
@@ -115,7 +142,7 @@ class Jexl {
    * @returns {Expression} The Expression object representing the given string
    */
   createExpression(expression: string) {
-    return new Expression(this._grammar, expression)
+    return new Expression(this._grammar, expression, this._lexer)
   }
 
   /**
@@ -146,12 +173,21 @@ class Jexl {
    * @param {Array<string>} strs
    * @param  {...any} args
    */
-  expr(strs: TemplateStringsArray, ...args: any[]) {
+  expr(strs: TemplateStringsArray, ...args: JexlValue[]) {
     let exprStr = ''
-    for (let idx = 0; idx < strs.length; idx++) {
-      exprStr += strs[idx]
+    for (const [idx, str] of strs.entries()) {
+      exprStr += str
       if (idx < args.length) {
-        exprStr += args[idx]
+        const arg = args[idx]
+        if (
+          typeof arg === 'string' ||
+          typeof arg === 'number' ||
+          typeof arg === 'boolean'
+        ) {
+          exprStr += String(arg)
+        } else if (arg != null) {
+          exprStr += JSON.stringify(arg)
+        }
       }
     }
     return this.createExpression(exprStr)
@@ -163,8 +199,9 @@ class Jexl {
    */
   removeOp(operator: string) {
     const elem = this._grammar.elements[operator]
-    if (elem && (elem.type === 'binaryOp' || elem.type === 'unaryOp')) {
+    if (elem?.type === 'binaryOp' || elem?.type === 'unaryOp') {
       Reflect.deleteProperty(this._grammar.elements, operator)
+      this._lexer._clearCache()
     }
   }
 
@@ -175,8 +212,9 @@ class Jexl {
    *      grammar element
    * @private
    */
-  _addGrammarElement(str: string, obj: any) {
+  _addGrammarElement(str: string, obj: GrammarElement) {
     this._grammar.elements[str] = obj
+    this._lexer._clearCache()
   }
 }
 

package/src/Lexer.ts

@@ -3,12 +3,16 @@
  * Copyright 2020 Tom Shawver
  */
 
-import type { Token } from './types.ts'
+import type { Grammar } from './grammar.ts'
+import type { TemplatePart, Token } from './types.ts'
 
 const numericRegex = /^-?(?:(?:[0-9]*\.[0-9]+)|[0-9]+)$/
 const identRegex =
   /^[a-zA-Zа-яА-Я_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF$][a-zA-Zа-яА-Я0-9_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF$]*$/
-const escEscRegex = /\\\\/
+const escEscRegex = /\\\\/g
+// a string literal opens with one of exactly two quote characters, so the two
+// unescaping regexes can just be named rather than built and cached per quote
+const escQuoteRegex = { "'": /\\'/g, '"': /\\"/g }
 const whitespaceRegex = /^\s*$/
 const preOpRegexElems = [
   // Template strings
@@ -28,6 +32,11 @@ const postOpRegexElems = [
   // Numerics (without negative symbol)
   String.raw`(?:(?:[0-9]*\.[0-9]+)|[0-9]+)`
 ]
+const unaryMinusToken = (): Token => ({
+  type: 'unaryOp',
+  value: '-',
+  raw: '-'
+})
 const minusNegatesAfter = new Set([
   'binaryOp',
   'unaryOp',
@@ -39,10 +48,6 @@ const minusNegatesAfter = new Set([
   'semicolon'
 ])
 
-interface Grammar {
-  elements: Record<string, any>
-}
-
 /**
  * Lexer is a collection of stateless, statically-accessed functions for the
  * lexical parsing of a Jexl string.  Its responsibility is to identify the
@@ -56,12 +61,20 @@ interface Grammar {
 class Lexer {
   _grammar: Grammar
   _splitRegex?: RegExp
-  _escQuoteRegexCache = new Map<string, RegExp>()
 
   constructor(grammar: Grammar) {
     this._grammar = grammar
   }
 
+  /**
+   * Discards the memoized split regex, so that it is rebuilt on the next
+   * tokenize. Must be called whenever the grammar's elements change, since the
+   * regex is derived from their keys.
+   */
+  _clearCache() {
+    this._splitRegex = undefined
+  }
+
   /**
    * Splits a Jexl expression string into an array of expression elements.
    * @param {string} str A Jexl expression string
@@ -86,19 +99,31 @@ class Lexer {
   getTokens(elements: string[]) {
     const tokens: Token[] = []
     let negate = false
-    for (let i = 0; i < elements.length; i++) {
-      if (this._isWhitespace(elements[i])) {
-        if (tokens.length) {
-          tokens[tokens.length - 1].raw += elements[i]
+    for (const element of elements) {
+      if (this._isWhitespace(element)) {
+        const last = tokens.at(-1)
+        if (last) {
+          last.raw += element
         }
-      } else if (elements[i] === '-' && this._isNegative(tokens)) {
-        negate = true
-      } else {
+      } else if (element === '-' && this._isNegative(tokens)) {
+        // a second prefix minus in a row ("- -x"): emit the pending one as a
+        // unary operator so this one can negate whatever comes next
         if (negate) {
-          elements[i] = '-' + elements[i]
-          negate = false
+          tokens.push(unaryMinusToken())
         }
-        tokens.push(this._createToken(elements[i]))
+        negate = true
+      } else if (negate) {
+        negate = false
+        if (numericRegex.exec(element)) {
+          // fold the sign into the number, so "-1" stays a single literal
+          tokens.push(this._createToken('-' + element))
+        } else {
+          // anything else gets a standalone prefix operator, letting "-x",
+          // "-(a + b)" and "-foo.bar" negate a computed value
+          tokens.push(unaryMinusToken(), this._createToken(element))
+        }
+      } else {
+        tokens.push(this._createToken(element))
       }
     }
     // Catch a - at the end of the string. Let the parser handle that issue.
@@ -166,8 +191,8 @@ class Lexer {
       token.value = parseFloat(element)
     } else if (element === 'true' || element === 'false') {
       token.value = element === 'true'
-    } else if (this._grammar.elements[element]) {
-      token.type = this._grammar.elements[element].type
+    } else if (Object.hasOwn(this._grammar.elements, element)) {
+      token.type = this._grammar.elements[element]!.type
     } else if (identRegex.exec(element)) {
       token.type = 'identifier'
     } else {
@@ -234,7 +259,7 @@ class Lexer {
     if (!tokens.length) {
       return true
     }
-    return minusNegatesAfter.has(tokens[tokens.length - 1].type)
+    return minusNegatesAfter.has(tokens[tokens.length - 1]!.type)
   }
 
   /**
@@ -261,20 +286,15 @@ class Lexer {
    * @private
    */
   _unquote(str: string) {
-    const quote = str[0]
-    let escQuoteRegex = this._escQuoteRegexCache.get(quote)
-    if (!escQuoteRegex) {
-      escQuoteRegex = new RegExp('\\\\' + quote, 'g')
-      this._escQuoteRegexCache.set(quote, escQuoteRegex)
-    }
+    const quote = str.startsWith('"') ? '"' : "'"
     return str
       .slice(1, -1)
-      .replace(escQuoteRegex, quote)
-      .replace(escEscRegex, '\\')
+      .replaceAll(escQuoteRegex[quote], quote)
+      .replaceAll(escEscRegex, '\\')
   }
 
   _parseTemplateString(str: string) {
-    const parts: { type: 'static' | 'interpolation'; value: string }[] = []
+    const parts: TemplatePart[] = []
     let current = 1
     let staticStart = 1
 
@@ -297,14 +317,24 @@ class Lexer {
         current += 2
 
         while (current < str.length && braceDepth > 0) {
-          if (str[current] === '\\') {
+          const char = str[current]
+          if (char === '\\') {
             current += 2
             continue
           }
-          if (str[current] === '{') {
-            braceDepth++
+          // skip over string literals so that braces inside them, as in
+          // `${ f('}') }`, don't unbalance the depth count
+          if (char === '"' || char === "'") {
+            current++
+            while (current < str.length && str[current] !== char) {
+              current += str[current] === '\\' ? 2 : 1
+            }
+            current++
+            continue
           }
-          if (str[current] === '}') {
+          if (char === '{') {
+            braceDepth++
+          } else if (char === '}') {
             braceDepth--
           }
           current++

package/src/evaluator/Evaluator.ts

@@ -3,23 +3,23 @@
  * Copyright 2020 Tom Shawver
  */
 
-import * as handlers from './handlers.ts'
+import { compileAst } from './compile.ts'
 
-import type { AstNode } from '../types.ts'
-
-interface Grammar {
-  elements: Record<string, any>
-  [key: string]: any
-}
+import type { Grammar } from '../grammar.ts'
+import type { AstNode, JexlValue } from '../types.ts'
 
 /**
- * The Evaluator takes a Jexl expression tree as generated by the
- * {@link Parser} and calculates its value within a given context. The
- * collection of transforms, context, and a relative context to be used as the
- * root for relative identifiers, are all specific to an Evaluator instance.
- * When any of these things change, a new instance is required.  However, a
- * single instance can be used to simultaneously evaluate many different
+ * The Evaluator carries everything an expression is evaluated against: the
+ * grammar, the context, and a relative context to be used as the root for
+ * relative identifiers. When any of these change, a new instance is required.
+ * However, a single instance can be used to evaluate many different
  * expressions, and does not have to be reinstantiated for each.
+ *
+ * The work of evaluation itself lives in {@link compileAst}, which lowers a
+ * tree to closures. Prefer compiling once and reusing the result — that is what
+ * {@link Expression} does — over calling {@link #eval}, which compiles the tree
+ * it is given every time.
+ *
  * @param {{}} grammar A grammar object against which to evaluate the expression
  *      tree
  * @param {{}} [context] A map of variable keys to their values. This will be
@@ -29,46 +29,29 @@ interface Grammar {
  */
 class Evaluator {
   _grammar: Grammar
-  _context: any
-  _relContext: any
-
-  constructor(grammar: Grammar, context?: any, relativeContext?: any) {
+  _context: Record<string, JexlValue>
+  _relContext: Record<string, JexlValue>
+
+  constructor(
+    grammar: Grammar,
+    context?: Record<string, JexlValue>,
+    relativeContext?: Record<string, JexlValue>
+  ) {
     this._grammar = grammar
     this._context = context || {}
     this._relContext = relativeContext || this._context
   }
 
   /**
-   * Evaluates an expression tree within the configured context.
+   * Compiles and evaluates an expression tree within the configured context.
+   * Convenient for a one-shot evaluation; for repeated evaluation of the same
+   * tree, hold onto the closure from {@link compileAst} instead so the tree is
+   * only lowered once.
    * @param {{}} ast An expression tree object
    * @returns {*} the resulting value of the expression.
    */
-  eval(ast: AstNode) {
-    return (handlers as any)[ast.type].call(this, ast)
-  }
-
-  /**
-   * Evaluates each expression within an array, and delivers the response as an
-   * array with the resulting values at the same indexes as their originating
-   * expressions.
-   * @param {Array<string>} arr An array of expression strings to be evaluated
-   * @returns {Array<{}>} the result array
-   */
-  evalArray(arr: AstNode[]) {
-    return arr.map((elem: AstNode) => this.eval(elem))
-  }
-
-  /**
-   * Evaluates each expression within a map, and delivers the response as a map
-   * with the same keys, but with the evaluated result for each as their value.
-   * @param {{}} map A map of expression names to expression trees to be
-   *      evaluated
-   * @returns {{}} the result map.
-   */
-  evalMap(map: Record<string, AstNode>) {
-    const entries = Object.entries(map)
-    const vals = entries.map(([_, ast]) => this.eval(ast))
-    return Object.fromEntries(entries.map(([key], idx) => [key, vals[idx]]))
+  eval(ast: AstNode): JexlValue {
+    return compileAst(ast, this._grammar)(this)
   }
 }