@jbrowse/jexl 3.0.2 → 3.2.0

package/src/parser/handlers.ts

@@ -3,8 +3,26 @@
  * Copyright 2020 Tom Shawver
  */
 
-import type { AstNode, Token } from '../types.ts'
-import type Parser from './Parser.ts'
+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,
+  AssignmentExpression,
+  AstNode,
+  BinaryExpression,
+  ConditionalExpression,
+  FilterExpression,
+  FunctionCall,
+  Identifier,
+  Literal,
+  ObjectLiteral,
+  TemplateLiteral,
+  Token,
+  UnaryExpression
+} from '../types.ts'
 
 /**
  * Handles a subexpression that's used to define a transform argument's value.
@@ -12,7 +30,7 @@ import type Parser from './Parser.ts'
  */
 export function argVal(this: Parser, ast: AstNode | null) {
   if (ast) {
-    ;(this._cursor as any).args.push(ast)
+    ;(this._cursor as FunctionCall).args.push(ast)
   }
 }
 
@@ -21,10 +39,11 @@ export function argVal(this: Parser, ast: AstNode | null) {
  * initialized with an empty array.
  */
 export function arrayStart(this: Parser) {
-  this._placeAtCursor({
+  const node: ArrayLiteral = {
     type: 'ArrayLiteral',
     value: []
-  } as any)
+  }
+  this._placeAtCursor(node)
 }
 
 /**
@@ -33,7 +52,7 @@ export function arrayStart(this: Parser) {
  */
 export function arrayVal(this: Parser, ast: AstNode | null) {
   if (ast) {
-    ;(this._cursor as any).value.push(ast)
+    ;(this._cursor as ArrayLiteral).value.push(ast)
   }
 }
 
@@ -44,34 +63,45 @@ export function arrayVal(this: Parser, ast: AstNode | null) {
  */
 export function binaryOp(this: Parser, token: Token) {
   if (token.value === '=') {
-    if (this._cursor?.type !== 'Identifier') {
+    // `from` marks a member access such as `a.b`; only a bare name can be
+    // assigned to, since the Evaluator writes straight into the context
+    if (
+      this._cursor?.type !== 'Identifier' ||
+      (this._cursor as Identifier).from
+    ) {
       throw new Error('Left side of assignment must be a variable name')
     }
 
-    const node: any = {
+    const node: AssignmentExpression = {
       type: 'AssignmentExpression',
       operator: '=',
-      left: this._cursor
+      left: this._cursor as Identifier
     }
     this._cursor = this._cursor._parent
     this._placeAtCursor(node)
     return
   }
 
-  const precedence = this._grammar.elements[token.value].precedence || 0
+  const tokenValue = token.value as string
+  const precedence = precedenceOf(this._grammar.elements[tokenValue])
   let parent = this._cursor?._parent
-  while (
-    parent &&
-    (parent as any).operator &&
-    this._grammar.elements[(parent as any).operator].precedence >= precedence
-  ) {
+  while (parent) {
+    const parentExpr = parent as BinaryExpression
+    if (!parentExpr.operator) {
+      break
+    }
+    if (
+      precedenceOf(this._grammar.elements[parentExpr.operator]) < precedence
+    ) {
+      break
+    }
     this._cursor = parent
     parent = parent._parent
   }
-  const node: any = {
+  const node: BinaryExpression = {
     type: 'BinaryExpression',
-    operator: token.value,
-    left: this._cursor
+    operator: tokenValue,
+    left: this._cursor!
   }
   this._setParent(this._cursor!, node)
   this._cursor = parent
@@ -84,16 +114,16 @@ export function binaryOp(this: Parser, token: Token) {
  * AST.
  */
 export function dot(this: Parser) {
-  const isBinaryExprWithRight = (node: AstNode) =>
-    node.type === 'BinaryExpression' && (node as any).right
-
+  const cursor = this._cursor
+  // the dot continues an identifier chain unless the cursor is an operator
+  // still waiting on its right-hand side, in which case it opens a relative
+  // path instead — as in the leading dot of `list[.price > 5]`
   this._nextIdentEncapsulate =
-    this._cursor &&
-    this._cursor.type !== 'UnaryExpression' &&
-    (this._cursor.type !== 'BinaryExpression' ||
-      isBinaryExprWithRight(this._cursor))
+    !!cursor &&
+    cursor.type !== 'UnaryExpression' &&
+    (cursor.type !== 'BinaryExpression' || !!cursor.right)
 
-  this._nextIdentRelative = !this._cursor || !this._nextIdentEncapsulate
+  this._nextIdentRelative = !this._nextIdentEncapsulate
   if (this._nextIdentRelative) {
     this._relative = true
   }
@@ -105,26 +135,41 @@ export function dot(this: Parser) {
  * @param {{type: <string>}} ast The subexpression tree
  */
 export function filter(this: Parser, ast: AstNode | null) {
-  this._placeBeforeCursor({
+  const node: FilterExpression = {
     type: 'FilterExpression',
-    expr: ast,
+    expr: ast!,
     relative: this._subParser!.isRelative(),
-    subject: this._cursor
-  } as any)
+    subject: this._cursor!
+  }
+  this._placeBeforeCursor(node)
 }
 
 /**
  * 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) {
-  this._placeBeforeCursor({
+  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 any).value,
-    args: [],
+    name: (cursor as Identifier).value,
+    args: from ? [from] : [],
     pool: 'functions'
-  } as any)
+  }
+  this._placeBeforeCursor(node)
 }
 
 /**
@@ -132,12 +177,12 @@ export function functionCall(this: Parser) {
  * @param {{type: <string>}} token A token object
  */
 export function identifier(this: Parser, token: Token) {
-  const node: any = {
+  const node: Identifier = {
     type: 'Identifier',
-    value: token.value
+    value: token.value as string
   }
   if (this._nextIdentEncapsulate) {
-    node.from = this._cursor
+    node.from = this._cursor!
     this._placeBeforeCursor(node)
     this._nextIdentEncapsulate = false
   } else {
@@ -155,10 +200,11 @@ export function identifier(this: Parser, token: Token) {
  * @param {{type: <string>}} token A token object
  */
 export function literal(this: Parser, token: Token) {
-  this._placeAtCursor({
+  const node: Literal = {
     type: 'Literal',
-    value: token.value
-  } as any)
+    value: token.value as string | number | boolean
+  }
+  this._placeAtCursor(node)
 }
 
 /**
@@ -167,9 +213,10 @@ export function literal(this: Parser, token: Token) {
  * @param {{type: <string>}} token A token object
  */
 export function templateString(this: Parser, token: Token) {
-  const parts: { type: 'static' | 'expression'; value: string | AstNode }[] = []
+  const parts: TemplateLiteral['parts'] = []
+  const tokenParts = Array.isArray(token.value) ? token.value : []
 
-  for (const part of token.value) {
+  for (const part of tokenParts) {
     if (part.type === 'static') {
       parts.push({
         type: 'static',
@@ -177,10 +224,7 @@ export function templateString(this: Parser, token: Token) {
       })
     } else {
       const subTokens = this._lexer.tokenize(part.value)
-      const subParser = new (this.constructor as any)(
-        this._grammar,
-        this._lexer
-      )
+      const subParser = new Parser(this._grammar, this._lexer)
       subParser.addTokens(subTokens)
       const subAst = subParser.complete()
 
@@ -195,10 +239,11 @@ export function templateString(this: Parser, token: Token) {
     }
   }
 
-  this._placeAtCursor({
+  const node: TemplateLiteral = {
     type: 'TemplateLiteral',
-    parts: parts
-  } as any)
+    parts
+  }
+  this._placeAtCursor(node)
 }
 
 /**
@@ -206,7 +251,7 @@ export function templateString(this: Parser, token: Token) {
  * @param {{type: <string>}} token A token object
  */
 export function objKey(this: Parser, token: Token) {
-  this._curObjKey = token.value
+  this._curObjKey = token.value as string
 }
 
 /**
@@ -214,10 +259,11 @@ export function objKey(this: Parser, token: Token) {
  * initialized with an empty object.
  */
 export function objStart(this: Parser) {
-  this._placeAtCursor({
+  const node: ObjectLiteral = {
     type: 'ObjectLiteral',
     value: {}
-  } as any)
+  }
+  this._placeAtCursor(node)
 }
 
 /**
@@ -226,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 any).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
+    }
+  )
 }
 
 /**
@@ -243,7 +301,7 @@ export function subExpression(this: Parser, ast: AstNode | null) {
  * @param {{type: <string>}} ast The subexpression tree
  */
 export function ternaryEnd(this: Parser, ast: AstNode | null) {
-  ;(this._cursor as any).alternate = ast
+  ;(this._cursor as ConditionalExpression).alternate = ast ?? undefined
 }
 
 /**
@@ -251,7 +309,7 @@ export function ternaryEnd(this: Parser, ast: AstNode | null) {
  * @param {{type: <string>}} ast The subexpression tree
  */
 export function ternaryMid(this: Parser, ast: AstNode | null) {
-  ;(this._cursor as any).consequent = ast
+  ;(this._cursor as ConditionalExpression).consequent = ast ?? undefined
 }
 
 /**
@@ -260,37 +318,25 @@ export function ternaryMid(this: Parser, ast: AstNode | null) {
  * test element.
  */
 export function ternaryStart(this: Parser) {
-  this._tree = {
+  const node: ConditionalExpression = {
     type: 'ConditionalExpression',
-    test: this._tree
-  } as any
+    test: this._tree!
+  }
+  this._tree = node
   this._cursor = this._tree
 }
 
-/**
- * Handles identifier tokens when used to indicate the name of a transform to
- * be applied.
- * @param {{type: <string>}} token A token object
- */
-export function transform(this: Parser, token: Token) {
-  this._placeBeforeCursor({
-    type: 'FunctionCall',
-    name: token.value,
-    args: [this._cursor],
-    pool: 'transforms'
-  } as any)
-}
-
 /**
  * Handles token of type 'unaryOp', indicating that the operation has only
  * one input: a right side.
  * @param {{type: <string>}} token A token object
  */
 export function unaryOp(this: Parser, token: Token) {
-  this._placeAtCursor({
+  const node: UnaryExpression = {
     type: 'UnaryExpression',
-    operator: token.value
-  } as any)
+    operator: token.value as string
+  }
+  this._placeAtCursor(node)
 }
 
 /**

package/src/parser/states.ts

@@ -5,12 +5,12 @@
 
 import * as h from './handlers.ts'
 
-import type { AstNode } from '../types.ts'
+import type { AstNode, Token } from '../types.ts'
 import type Parser from './Parser.ts'
 
 interface TokenTypeOptions {
   toState?: string
-  handler?: (this: Parser, ...args: any[]) => void
+  handler?: (this: Parser, token: Token) => void
 }
 
 interface StateDefinition {
@@ -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,21 +82,9 @@ export const states: States = {
     }
   },
   expectBinOp: {
-    tokenTypes: {
-      binaryOp: { toState: 'expectOperand' },
-      pipe: { toState: 'expectTransform' },
-      dot: { toState: 'traverse' },
-      openBracket: { toState: 'filter' },
-      question: { toState: 'ternaryMid', handler: h.ternaryStart },
-      semicolon: { handler: h.semicolon }
-    },
+    tokenTypes: afterOperand,
     completable: true
   },
-  expectTransform: {
-    tokenTypes: {
-      identifier: { toState: 'postTransform', handler: h.transform }
-    }
-  },
   expectObjKey: {
     tokenTypes: {
       literal: { toState: 'expectKeyValSep', handler: h.objKey },
@@ -95,38 +97,16 @@ export const states: States = {
       colon: { toState: 'objVal' }
     }
   },
-  postTransform: {
-    tokenTypes: {
-      openParen: { toState: 'argVal' },
-      binaryOp: { toState: 'expectOperand' },
-      dot: { toState: 'traverse' },
-      openBracket: { toState: 'filter' },
-      pipe: { toState: 'expectTransform' },
-      question: { toState: 'ternaryMid', handler: h.ternaryStart },
-      semicolon: { handler: h.semicolon }
-    },
-    completable: true
-  },
   postArgs: {
-    tokenTypes: {
-      binaryOp: { toState: 'expectOperand' },
-      dot: { toState: 'traverse' },
-      openBracket: { toState: 'filter' },
-      pipe: { toState: 'expectTransform' },
-      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 },
-      pipe: { toState: 'expectTransform' },
-      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
   },

package/src/types.ts

@@ -3,15 +3,30 @@
  * Copyright 2020 Tom Shawver
  */
 
+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 {
@@ -49,19 +64,20 @@ export interface ObjectLiteral extends AstNode {
   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 {
@@ -87,7 +103,6 @@ export interface AssignmentExpression extends AstNode {
   type: 'AssignmentExpression'
   operator: '='
   left: Identifier
-  right: AstNode
 }
 
 export type AstNodeUnion =