@jbrowse/jexl 3.1.0 → 3.3.0

package/src/evaluator/compile.ts

@@ -4,22 +4,7 @@
  */
 
 import type { Grammar } from '../grammar.ts'
-import type {
-  ArrayLiteral,
-  AssignmentExpression,
-  AstNode,
-  BinaryExpression,
-  ConditionalExpression,
-  FilterExpression,
-  FunctionCall,
-  Identifier,
-  JexlValue,
-  Literal,
-  ObjectLiteral,
-  SequenceExpression,
-  TemplateLiteral,
-  UnaryExpression
-} from '../types.ts'
+import type { AstNode, AstNodeUnion, JexlValue } from '../types.ts'
 import type Evaluator from './Evaluator.ts'
 
 /**
@@ -28,6 +13,34 @@ import type Evaluator from './Evaluator.ts'
  */
 export type CompiledNode = (ev: Evaluator) => JexlValue
 
+/**
+ * Writes a key that a plain assignment would mishandle. Storing to
+ * "__proto__" invokes the prototype setter rather than creating a property, so
+ * an object literal or assignment using that key silently lost its value (and
+ * re-pointed the target's prototype). Defining the property instead matches
+ * what `JSON.parse('{"__proto__":1}')` produces: an ordinary own property.
+ */
+function defineOwn(
+  target: Record<string, JexlValue>,
+  key: string,
+  value: JexlValue
+) {
+  Object.defineProperty(target, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true
+  })
+}
+
+function assignOwn(
+  target: Record<string, JexlValue>,
+  key: string,
+  value: JexlValue
+) {
+  target[key] = value
+}
+
 /** Renders an interpolated value for a template literal. */
 function stringify(value: JexlValue) {
   if (value == null) {
@@ -62,14 +75,17 @@ function stringify(value: JexlValue) {
  * @throws {Error} if the tree contains an unrecognized node type
  */
 export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
-  switch (ast.type) {
+  // AstNode types its `type` as a plain string so the Parser can build the tree
+  // loosely; narrowing to the union once, here, lets every case below see its
+  // own node type instead of repeating the same cast in each branch
+  const node = ast as AstNodeUnion
+  switch (node.type) {
     case 'Literal': {
-      const { value } = ast as Literal
+      const { value } = node
       return () => value
     }
 
     case 'Identifier': {
-      const node = ast as Identifier
       const name = node.value
       if (!node.from) {
         return node.relative
@@ -91,7 +107,6 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'BinaryExpression': {
-      const node = ast as BinaryExpression
       const op = grammar.elements[node.operator]
       if (op?.type !== 'binaryOp') {
         // matches the tree-walking behaviour: an unknown operator yields
@@ -119,7 +134,6 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'UnaryExpression': {
-      const node = ast as UnaryExpression
       const right = compileAst(node.right!, grammar)
       const elem = grammar.elements[node.operator]
       const fn =
@@ -139,7 +153,6 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'ConditionalExpression': {
-      const node = ast as ConditionalExpression
       const test = compileAst(node.test, grammar)
       const consequent = node.consequent
         ? compileAst(node.consequent, grammar)
@@ -158,7 +171,6 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'FilterExpression': {
-      const node = ast as FilterExpression
       if (node.relative) {
         // thrown on evaluation rather than compilation, as before
         return () => {
@@ -180,9 +192,7 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'ArrayLiteral': {
-      const items = (ast as ArrayLiteral).value.map((item) =>
-        compileAst(item, grammar)
-      )
+      const items = node.value.map((item) => compileAst(item, grammar))
       const len = items.length
       return (ev) => {
         const out: JexlValue[] = new Array(len)
@@ -194,14 +204,16 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'ObjectLiteral': {
-      const entries = Object.entries((ast as ObjectLiteral).value)
+      const entries = Object.entries(node.value)
       const keys = entries.map(([key]) => key)
-      const values = entries.map(([, node]) => compileAst(node, grammar))
+      const values = entries.map(([, value]) => compileAst(value, grammar))
       const len = keys.length
+      // resolved once, here, so the common case keeps its plain store
+      const store = keys.includes('__proto__') ? defineOwn : assignOwn
       return (ev) => {
         const out: Record<string, JexlValue> = {}
         for (let i = 0; i < len; i++) {
-          out[keys[i]!] = values[i]!(ev)
+          store(out, keys[i]!, values[i]!(ev))
         }
         return out
       }
@@ -209,16 +221,14 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
 
     case 'TemplateLiteral': {
       // every part renders to a string, so these are narrower than CompiledNode
-      const parts = (ast as TemplateLiteral).parts.map(
-        (part): ((ev: Evaluator) => string) => {
-          if (part.type === 'static') {
-            const { value } = part
-            return () => value
-          }
-          const expr = compileAst(part.value, grammar)
-          return (ev) => stringify(expr(ev))
+      const parts = node.parts.map((part): ((ev: Evaluator) => string) => {
+        if (part.type === 'static') {
+          const { value } = part
+          return () => value
         }
-      )
+        const expr = compileAst(part.value, grammar)
+        return (ev) => stringify(expr(ev))
+      })
       return (ev) => {
         let out = ''
         for (const part of parts) {
@@ -229,7 +239,6 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'FunctionCall': {
-      const node = ast as FunctionCall
       const { name } = node
       const args = node.args.map((arg) => compileAst(arg, grammar))
       // hasOwn, so that inherited Object.prototype members such as `toString`
@@ -279,9 +288,7 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'SequenceExpression': {
-      const exprs = (ast as SequenceExpression).expressions.map((expr) =>
-        compileAst(expr, grammar)
-      )
+      const exprs = node.expressions.map((expr) => compileAst(expr, grammar))
       const len = exprs.length
       return (ev) => {
         let last: JexlValue
@@ -293,12 +300,12 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'AssignmentExpression': {
-      const node = ast as AssignmentExpression
       const name = node.left.value
       const right = compileAst(node.right!, grammar)
+      const store = name === '__proto__' ? defineOwn : assignOwn
       return (ev) => {
         const value = right(ev)
-        ev._context[name] = value
+        store(ev._context, name, value)
         return value
       }
     }

package/src/grammar.ts

@@ -9,6 +9,21 @@ import type { JexlValue } from './types.ts'
 
 export type BinaryOpEval = (left: JexlValue, right: JexlValue) => JexlValue
 
+/**
+ * A function or operator implementation as its author writes it, for the
+ * registration methods on {@link Jexl} to accept.
+ *
+ * Jexl cannot check what a registered callback will be handed. The arguments
+ * are whatever the expression evaluated to, drawn from a context supplied at
+ * evaluation time, and that context routinely holds values jexl has no literal
+ * for — a host object with methods, a callback, a class instance. Requiring
+ * {@link JexlValue} parameters therefore rejected every callback actually
+ * written against such a value, since parameters are contravariant. The
+ * argument types are the caller's business; jexl only promises to pass along
+ * whatever the operands evaluated to.
+ */
+export type UncheckedFn = (...args: never[]) => unknown
+
 export type BinaryOpEvalOnDemand = (
   left: { eval: () => JexlValue },
   right: { eval: () => JexlValue }
@@ -27,10 +42,12 @@ export interface BinaryOp {
   unaryEval?: (right: JexlValue) => JexlValue
 }
 
+export type UnaryOpEval = (right: JexlValue) => JexlValue
+
 export interface UnaryOp {
   type: 'unaryOp'
   precedence: number
-  eval: (right: JexlValue) => JexlValue
+  eval: UnaryOpEval
 }
 
 /**
@@ -56,9 +73,12 @@ export interface SimpleElement {
 
 export type GrammarElement = BinaryOp | UnaryOp | SimpleElement
 
+/** A registered function, as jexl calls it once the operands are evaluated. */
+export type GrammarFn = (...args: JexlValue[]) => JexlValue
+
 export interface Grammar {
   elements: Record<string, GrammarElement>
-  functions: Record<string, (...args: JexlValue[]) => JexlValue>
+  functions: Record<string, GrammarFn>
 }
 
 /**
@@ -182,18 +202,17 @@ export const getGrammar = (): Grammar => ({
       precedence: 20,
       eval: (left, right) => {
         if (typeof right === 'string') {
-          const leftStr =
-            typeof left === 'string' ||
+          // only a primitive has a meaningful substring form. An absent or
+          // structured left operand is not "in" a string, and must not be
+          // coerced to '' — every string contains the empty string, so that
+          // made `feature.missingAttr in "someString"` true for every feature.
+          return typeof left === 'string' ||
             typeof left === 'number' ||
             typeof left === 'boolean'
-              ? String(left)
-              : ''
-          return right.includes(leftStr)
-        }
-        if (Array.isArray(right)) {
-          return right.includes(left)
+            ? right.includes(String(left))
+            : false
         }
-        return false
+        return Array.isArray(right) ? right.includes(left) : false
       }
     },
     '!': {

package/src/parser/Parser.ts

@@ -10,6 +10,25 @@ import type Lexer from '../Lexer.ts'
 import type { Grammar } from '../grammar.ts'
 import type { AstNode, SequenceExpression, Token } from '../types.ts'
 
+/**
+ * The handler to run for a token type when the state it appears in doesn't
+ * name one of its own. Token types absent here — the brackets, parens and
+ * separators — carry no behavior beyond the state transition the state machine
+ * gives them.
+ */
+const tokenHandlers: Record<
+  string,
+  ((this: Parser, token: Token) => void) | undefined
+> = {
+  binaryOp: handlers.binaryOp,
+  dot: handlers.dot,
+  identifier: handlers.identifier,
+  literal: handlers.literal,
+  semicolon: handlers.semicolon,
+  templateString: handlers.templateString,
+  unaryOp: handlers.unaryOp
+}
+
 /**
  * The Parser is a state machine that converts tokens from the {@link Lexer}
  * into an Abstract Syntax Tree (AST), capable of being evaluated in any
@@ -76,10 +95,8 @@ class Parser {
     const startExpr = this._exprStr
     this._exprStr += token.raw
     if (state.subHandler) {
-      if (!this._subParser) {
-        this._startSubExpression(startExpr)
-      }
-      const stopState = this._subParser!.addToken(token)
+      const subParser = this._subParser ?? this._startSubExpression(startExpr)
+      const stopState = subParser.addToken(token)
       if (stopState) {
         this._endSubExpression()
         if (stopState === '_semicolon') {
@@ -94,18 +111,10 @@ class Parser {
       return this._stopMap[token.type]!
     } else if (state.tokenTypes?.[token.type]) {
       const typeOpts = state.tokenTypes[token.type]!
-      let handleFunc = (
-        handlers as Record<
-          string,
-          ((this: Parser, token: Token) => void) | undefined
-        >
-      )[token.type]
-      if (typeOpts.handler) {
-        handleFunc = typeOpts.handler
-      }
-      if (handleFunc) {
-        handleFunc.call(this, token)
-      }
+      // the state's own handler wins over the token type's default one, and a
+      // token type with neither only drives the transition below
+      const handleFunc = typeOpts.handler ?? tokenHandlers[token.type]
+      handleFunc?.call(this, token)
       if (typeOpts.toState) {
         this._state = typeOpts.toState
       }
@@ -140,7 +149,14 @@ class Parser {
    *      the expression, indicating that the expression is incomplete
    */
   complete() {
-    if (this._cursor && !states[this._state]!.completable) {
+    // `_subParser` counts as unfinished business alongside `_cursor`: a group
+    // that opened before anything was placed in the tree, as in "(1", leaves
+    // the cursor null, and testing the cursor alone let the missing ")" pass
+    // silently and evaluate as if it were closed.
+    if (
+      (this._cursor || this._subParser) &&
+      !states[this._state]!.completable
+    ) {
       throw new Error(`Unexpected end of expression: ${this._exprStr}`)
     }
     if (this._subParser) {
@@ -231,6 +247,7 @@ class Parser {
    * Prepares the Parser to accept a subexpression by (re)instantiating the
    * subParser.
    * @param {string} [exprStr] The expression string to prefix to the new Parser
+   * @returns {Parser} the new subParser, also stored on this instance
    * @private
    */
   _startSubExpression(exprStr?: string) {
@@ -243,6 +260,7 @@ class Parser {
       endStates = { ...endStates, semicolon: '_semicolon' }
     }
     this._subParser = new Parser(this._grammar, this._lexer, exprStr, endStates)
+    return this._subParser
   }
 }
 

package/src/parser/handlers.ts

@@ -4,6 +4,9 @@
  */
 
 import { precedenceOf } from '../grammar.ts'
+// circular with Parser.ts, which is fine: the binding is only read from inside
+// a handler, long after both modules have finished evaluating
+import Parser from './Parser.ts'
 
 import type {
   ArrayLiteral,
@@ -20,7 +23,6 @@ import type {
   Token,
   UnaryExpression
 } from '../types.ts'
-import type Parser from './Parser.ts'
 
 /**
  * Handles a subexpression that's used to define a transform argument's value.
@@ -145,13 +147,26 @@ export function filter(this: Parser, ast: AstNode | null) {
 /**
  * Handles identifier tokens when used to indicate the name of a function to
  * be called.
- * @param {{type: <string>}} token A token object
+ *
+ * A call written against a value, `a.b(x)`, becomes `b(a, x)`: jexl functions
+ * live in one global pool and have no receiver, so the value the name was read
+ * from is passed as the first argument instead. Every function in the pool is
+ * already written that way — `get(feature, key)`, `split(str, sep)` — which is
+ * what makes the two spellings equivalent. Previously the receiver was simply
+ * dropped, so `refName.split(' ')` quietly called `split(' ')`.
  */
 export function functionCall(this: Parser) {
+  const cursor = this._cursor
+  if (cursor?.type !== 'Identifier') {
+    // reached by `a[expr]()`, whose subject is a filter rather than a name;
+    // there is nothing to look up in the function pool
+    throw new Error(`Functions must be called by name: ${this._exprStr}`)
+  }
+  const { from } = cursor as Identifier
   const node: FunctionCall = {
     type: 'FunctionCall',
-    name: (this._cursor as Identifier).value,
-    args: [],
+    name: (cursor as Identifier).value,
+    args: from ? [from] : [],
     pool: 'functions'
   }
   this._placeBeforeCursor(node)
@@ -209,11 +224,7 @@ export function templateString(this: Parser, token: Token) {
       })
     } else {
       const subTokens = this._lexer.tokenize(part.value)
-      const ParserClass = this.constructor as new (
-        grammar: typeof this._grammar,
-        lexer: typeof this._lexer
-      ) => Parser
-      const subParser = new ParserClass(this._grammar, this._lexer)
+      const subParser = new Parser(this._grammar, this._lexer)
       subParser.addTokens(subTokens)
       const subAst = subParser.complete()
 
@@ -261,7 +272,19 @@ export function objStart(this: Parser) {
  * @param {{type: <string>}} ast The subexpression tree
  */
 export function objVal(this: Parser, ast: AstNode | null) {
-  ;(this._cursor as ObjectLiteral).value[this._curObjKey!] = ast!
+  // defined rather than assigned so that the key "__proto__" becomes an
+  // ordinary entry of the node's key map instead of re-pointing its prototype,
+  // which dropped the entry before the Evaluator ever saw it
+  Object.defineProperty(
+    (this._cursor as ObjectLiteral).value,
+    this._curObjKey!,
+    {
+      value: ast!,
+      writable: true,
+      enumerable: true,
+      configurable: true
+    }
+  )
 }
 
 /**

package/src/parser/states.ts

@@ -22,6 +22,20 @@ interface StateDefinition {
 
 type States = Record<string, StateDefinition>
 
+/**
+ * The tokens that may follow a finished operand: an operator to combine it
+ * with, a dot or subscript to keep drilling into it, a question mark opening a
+ * ternary, or a semicolon ending the statement. Shared by every state that
+ * sits on a complete value, which is also why each of them is completable.
+ */
+const afterOperand: Record<string, TokenTypeOptions> = {
+  binaryOp: { toState: 'expectOperand' },
+  dot: { toState: 'traverse' },
+  openBracket: { toState: 'filter' },
+  question: { toState: 'ternaryMid', handler: h.ternaryStart },
+  semicolon: { handler: h.semicolon }
+}
+
 /**
  * A mapping of all states in the finite state machine to a set of instructions
  * for handling or transitioning into other states. Each state can be handled
@@ -68,13 +82,7 @@ export const states: States = {
     }
   },
   expectBinOp: {
-    tokenTypes: {
-      binaryOp: { toState: 'expectOperand' },
-      dot: { toState: 'traverse' },
-      openBracket: { toState: 'filter' },
-      question: { toState: 'ternaryMid', handler: h.ternaryStart },
-      semicolon: { handler: h.semicolon }
-    },
+    tokenTypes: afterOperand,
     completable: true
   },
   expectObjKey: {
@@ -90,23 +98,15 @@ export const states: States = {
     }
   },
   postArgs: {
-    tokenTypes: {
-      binaryOp: { toState: 'expectOperand' },
-      dot: { toState: 'traverse' },
-      openBracket: { toState: 'filter' },
-      question: { toState: 'ternaryMid', handler: h.ternaryStart },
-      semicolon: { handler: h.semicolon }
-    },
+    tokenTypes: afterOperand,
     completable: true
   },
   identifier: {
     tokenTypes: {
-      binaryOp: { toState: 'expectOperand' },
-      dot: { toState: 'traverse' },
-      openBracket: { toState: 'filter' },
-      openParen: { toState: 'argVal', handler: h.functionCall },
-      question: { toState: 'ternaryMid', handler: h.ternaryStart },
-      semicolon: { handler: h.semicolon }
+      ...afterOperand,
+      // a name is the only operand that can be followed by an argument list,
+      // since a function is called by name rather than evaluated as a value
+      openParen: { toState: 'argVal', handler: h.functionCall }
     },
     completable: true
   },