@jbrowse/jexl 2.3.1

package/src/evaluator/handlers.ts

@@ -0,0 +1,226 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+import type { AstNode } from '../types.ts'
+import type Evaluator from './Evaluator.ts'
+
+const poolNames: Record<string, string> = {
+  functions: 'Jexl Function',
+  transforms: 'Transform'
+}
+
+/**
+ * Evaluates an ArrayLiteral by returning its value, with each element
+ * independently run through the evaluator.
+ * @param {{type: 'ObjectLiteral', value: <{}>}} ast An expression tree with an
+ *      ObjectLiteral as the top node
+ * @returns {Promise.<[]>} resolves to a map contained evaluated values.
+ * @private
+ */
+export function ArrayLiteral(this: Evaluator, ast: any) {
+  return this.evalArray(ast.value)
+}
+
+/**
+ * Evaluates a BinaryExpression node by running the Grammar's evaluator for
+ * the given operator. Note that binary expressions support two types of
+ * evaluators: `eval` is called with the left and right operands pre-evaluated.
+ * `evalOnDemand`, if it exists, will be called with the left and right operands
+ * each individually wrapped in an object with an "eval" function that returns
+ * a promise with the resulting value. This allows the binary expression to
+ * evaluate the operands conditionally.
+ * @param {{type: 'BinaryExpression', operator: <string>, left: {},
+ *      right: {}}} ast An expression tree with a BinaryExpression as the top
+ *      node
+ * @returns {Promise<*>} resolves with the value of the BinaryExpression.
+ * @private
+ */
+export function BinaryExpression(this: Evaluator, ast: any) {
+  const grammarOp = this._grammar.elements[ast.operator]
+  if (grammarOp.evalOnDemand) {
+    const wrap = (subAst: AstNode) => ({ eval: () => this.eval(subAst) })
+    return grammarOp.evalOnDemand(wrap(ast.left), wrap(ast.right))
+  }
+  return this.Promise.all([this.eval(ast.left), this.eval(ast.right)]).then(
+    (arr: any[]) => grammarOp.eval(arr[0], arr[1])
+  )
+}
+
+/**
+ * Evaluates a ConditionalExpression node by first evaluating its test branch,
+ * and resolving with the consequent branch if the test is truthy, or the
+ * alternate branch if it is not. If there is no consequent branch, the test
+ * result will be used instead.
+ * @param {{type: 'ConditionalExpression', test: {}, consequent: {},
+ *      alternate: {}}} ast An expression tree with a ConditionalExpression as
+ *      the top node
+ * @private
+ */
+export function ConditionalExpression(this: Evaluator, ast: any) {
+  return this.eval(ast.test).then((res: any) => {
+    if (res) {
+      if (ast.consequent) {
+        return this.eval(ast.consequent)
+      }
+      return res
+    }
+    return this.eval(ast.alternate)
+  })
+}
+
+/**
+ * Evaluates a FilterExpression by applying it to the subject value.
+ * @param {{type: 'FilterExpression', relative: <boolean>, expr: {},
+ *      subject: {}}} ast An expression tree with a FilterExpression as the top
+ *      node
+ * @returns {Promise<*>} resolves with the value of the FilterExpression.
+ * @private
+ */
+export function FilterExpression(this: Evaluator, ast: any) {
+  return this.eval(ast.subject).then((subject: any) => {
+    if (ast.relative) {
+      return this._filterRelative(subject, ast.expr)
+    }
+    return this._filterStatic(subject, ast.expr)
+  })
+}
+
+/**
+ * Evaluates an Identifier by either stemming from the evaluated 'from'
+ * expression tree or accessing the context provided when this Evaluator was
+ * constructed.
+ * @param {{type: 'Identifier', value: <string>, [from]: {}}} ast An expression
+ *      tree with an Identifier as the top node
+ * @returns {Promise<*>|*} either the identifier's value, or a Promise that
+ *      will resolve with the identifier's value.
+ * @private
+ */
+export function Identifier(this: Evaluator, ast: any) {
+  if (!ast.from) {
+    const contextSource = ast.relative ? this._relContext : this._context
+    return contextSource[ast.value]
+  }
+  return this.eval(ast.from).then((context: any) => {
+    if (context == null) {
+      return undefined
+    }
+    const ctx = Array.isArray(context) ? context[0] : context
+    return ctx?.[ast.value]
+  })
+}
+
+/**
+ * Evaluates a Literal by returning its value property.
+ * @param {{type: 'Literal', value: <string|number|boolean>}} ast An expression
+ *      tree with a Literal as its only node
+ * @returns {string|number|boolean} The value of the Literal node
+ * @private
+ */
+export function Literal(this: Evaluator, ast: any) {
+  return ast.value
+}
+
+/**
+ * Evaluates a TemplateLiteral by evaluating each interpolated expression
+ * and concatenating all parts into a final string.
+ * @param {{type: 'TemplateLiteral', parts: Array<{}>}} ast An expression
+ *      tree with a TemplateLiteral as the top node
+ * @returns {Promise<string>} resolves with the final interpolated string
+ * @private
+ */
+export function TemplateLiteral(this: Evaluator, ast: any) {
+  const promises = ast.parts.map((part: any) => {
+    if (part.type === 'static') {
+      return this.Promise.resolve(part.value)
+    }
+    return this.eval(part.value).then((result: any) => {
+      if (result == null) {
+        return ''
+      }
+      return String(result)
+    })
+  })
+
+  return this.Promise.all(promises).then((values: string[]) => values.join(''))
+}
+
+/**
+ * Evaluates an ObjectLiteral by returning its value, with each key
+ * independently run through the evaluator.
+ * @param {{type: 'ObjectLiteral', value: <{}>}} ast An expression tree with an
+ *      ObjectLiteral as the top node
+ * @returns {Promise<{}>} resolves to a map contained evaluated values.
+ * @private
+ */
+export function ObjectLiteral(this: Evaluator, ast: any) {
+  return this.evalMap(ast.value)
+}
+
+/**
+ * Evaluates a FunctionCall node by applying the supplied arguments to a
+ * function defined in one of the grammar's function pools.
+ * @param {{type: 'FunctionCall', name: <string>}} ast An
+ *      expression tree with a FunctionCall as the top node
+ * @returns {Promise<*>|*} the value of the function call, or a Promise that
+ *      will resolve with the resulting value.
+ * @private
+ */
+export function FunctionCall(this: Evaluator, ast: any) {
+  const poolName = poolNames[ast.pool]
+  if (!poolName) {
+    throw new Error(`Corrupt AST: Pool '${ast.pool}' not found`)
+  }
+  const pool = (this._grammar as any)[ast.pool]
+  const func = pool?.[ast.name]
+  if (!func) {
+    throw new Error(`${poolName} ${ast.name} is not defined.`)
+  }
+  return this.evalArray(ast.args || []).then((args: any[]) => func(...args))
+}
+
+/**
+ * Evaluates a Unary expression by passing the right side through the
+ * operator's eval function.
+ * @param {{type: 'UnaryExpression', operator: <string>, right: {}}} ast An
+ *      expression tree with a UnaryExpression as the top node
+ * @returns {Promise<*>} resolves with the value of the UnaryExpression.
+ * @constructor
+ */
+export function UnaryExpression(this: Evaluator, ast: any) {
+  return this.eval(ast.right).then((right: any) =>
+    this._grammar.elements[ast.operator].eval(right)
+  )
+}
+
+/**
+ * Evaluates a SequenceExpression by evaluating each expression in order
+ * and returning the value of the last expression.
+ */
+export function SequenceExpression(this: Evaluator, ast: any) {
+  let lastValue: any
+  let promise = this.Promise.resolve()
+
+  for (const expr of ast.expressions) {
+    promise = promise.then(() =>
+      this.eval(expr).then((val: any) => {
+        lastValue = val
+      })
+    )
+  }
+
+  return promise.then(() => lastValue)
+}
+
+/**
+ * Evaluates an AssignmentExpression by evaluating the right side
+ * and assigning it to the variable name on the left side.
+ */
+export function AssignmentExpression(this: Evaluator, ast: any) {
+  return this.eval(ast.right).then((value: any) => {
+    const varName = ast.left.value
+    this._context[varName] = value
+    return value
+  })
+}

package/src/grammar.ts

@@ -0,0 +1,200 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+/* eslint eqeqeq:0 */
+
+export interface BinaryOp {
+  type: 'binaryOp'
+  precedence: number
+  eval?: (left: any, right: any) => any
+  evalOnDemand?: (left: { eval: () => Promise<any> }, right: { eval: () => Promise<any> }) => Promise<any>
+}
+
+export interface UnaryOp {
+  type: 'unaryOp'
+  precedence: number
+  eval: (right: any) => any
+}
+
+export interface SimpleElement {
+  type: string
+}
+
+export type GrammarElement = BinaryOp | UnaryOp | SimpleElement
+
+export interface Grammar {
+  elements: Record<string, GrammarElement>
+  functions: Record<string, (...args: any[]) => any>
+  transforms: Record<string, (val: any, ...args: any[]) => any>
+}
+
+export const getGrammar = (): Grammar => ({
+  /**
+   * A map of all expression elements to their properties. Note that changes
+   * here may require changes in the Lexer or Parser.
+   * @type {{}}
+   */
+  elements: {
+    '.': { type: 'dot' },
+    '[': { type: 'openBracket' },
+    ']': { type: 'closeBracket' },
+    '|': { type: 'pipe' },
+    '{': { type: 'openCurl' },
+    '}': { type: 'closeCurl' },
+    ':': { type: 'colon' },
+    ',': { type: 'comma' },
+    '(': { type: 'openParen' },
+    ')': { type: 'closeParen' },
+    '?': { type: 'question' },
+    ';': { type: 'semicolon' },
+    '+': {
+      type: 'binaryOp',
+      precedence: 30,
+      eval: (left, right) => left + right
+    },
+    '-': {
+      type: 'binaryOp',
+      precedence: 30,
+      eval: (left, right) => left - right
+    },
+    '*': {
+      type: 'binaryOp',
+      precedence: 40,
+      eval: (left, right) => left * right
+    },
+    '/': {
+      type: 'binaryOp',
+      precedence: 40,
+      eval: (left, right) => left / right
+    },
+    '//': {
+      type: 'binaryOp',
+      precedence: 40,
+      eval: (left, right) => Math.floor(left / right)
+    },
+    '%': {
+      type: 'binaryOp',
+      precedence: 50,
+      eval: (left, right) => left % right
+    },
+    '^': {
+      type: 'binaryOp',
+      precedence: 50,
+      eval: (left, right) => Math.pow(left, right)
+    },
+    '==': {
+      type: 'binaryOp',
+      precedence: 20,
+      eval: (left, right) => left == right
+    },
+    '!=': {
+      type: 'binaryOp',
+      precedence: 20,
+      eval: (left, right) => left != right
+    },
+    '>': {
+      type: 'binaryOp',
+      precedence: 20,
+      eval: (left, right) => left > right
+    },
+    '>=': {
+      type: 'binaryOp',
+      precedence: 20,
+      eval: (left, right) => left >= right
+    },
+    '<': {
+      type: 'binaryOp',
+      precedence: 20,
+      eval: (left, right) => left < right
+    },
+    '<=': {
+      type: 'binaryOp',
+      precedence: 20,
+      eval: (left, right) => left <= right
+    },
+    '&&': {
+      type: 'binaryOp',
+      precedence: 10,
+      evalOnDemand: (left, right) => {
+        return left.eval().then((leftVal) => {
+          if (!leftVal) {return leftVal}
+          return right.eval()
+        })
+      }
+    },
+    '||': {
+      type: 'binaryOp',
+      precedence: 10,
+      evalOnDemand: (left, right) => {
+        return left.eval().then((leftVal) => {
+          if (leftVal) {return leftVal}
+          return right.eval()
+        })
+      }
+    },
+    in: {
+      type: 'binaryOp',
+      precedence: 20,
+      eval: (left, right) => {
+        if (typeof right === 'string') {
+          return right.includes(left)
+        }
+        if (Array.isArray(right)) {
+          return right.includes(left)
+        }
+        return false
+      }
+    },
+    '!': {
+      type: 'unaryOp',
+      precedence: Infinity,
+      eval: (right) => !right
+    },
+    '=': {
+      type: 'binaryOp',
+      precedence: 2,
+      eval: (_left, _right) => {
+        throw new Error('Assignment handled specially')
+      }
+    }
+  },
+
+  /**
+   * A map of function names to javascript functions. A Jexl function
+   * takes zero ore more arguemnts:
+   *
+   *     - {*} ...args: A variable number of arguments passed to this function.
+   *       All of these are pre-evaluated to their actual values before calling
+   *       the function.
+   *
+   * The Jexl function should return either the transformed value, or
+   * a Promises/A+ Promise object that resolves with the value and rejects
+   * or throws only when an unrecoverable error occurs. Functions should
+   * generally return undefined when they don't make sense to be used on the
+   * given value type, rather than throw/reject. An error is only
+   * appropriate when the function would normally return a value, but
+   * cannot due to some other failure.
+   */
+  functions: {},
+
+  /**
+   * A map of transform names to transform functions. A transform function
+   * takes one ore more arguemnts:
+   *
+   *     - {*} val: A value to be transformed
+   *     - {*} ...args: A variable number of arguments passed to this transform.
+   *       All of these are pre-evaluated to their actual values before calling
+   *       the function.
+   *
+   * The transform function should return either the transformed value, or
+   * a Promises/A+ Promise object that resolves with the value and rejects
+   * or throws only when an unrecoverable error occurs. Transforms should
+   * generally return undefined when they don't make sense to be used on the
+   * given value type, rather than throw/reject. An error is only
+   * appropriate when the transform would normally return a value, but
+   * cannot due to some other failure.
+   */
+  transforms: {}
+})

package/src/index.ts

@@ -0,0 +1,10 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+export { Jexl, default } from './Jexl.ts'
+export { default as Expression } from './Expression.ts'
+export { default as Lexer } from './Lexer.ts'
+export { getGrammar } from './grammar.ts'
+export type * from './types.ts'

package/src/parser/Parser.ts

@@ -0,0 +1,235 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+import * as handlers from './handlers.ts'
+import { states } from './states.ts'
+
+import type Lexer from '../Lexer.ts'
+import type { AstNode, Token } from '../types.ts'
+
+interface Grammar {
+  elements: Record<string, any>
+}
+
+/**
+ * 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
+ * context by the {@link Evaluator}.  The Parser expects that all tokens
+ * provided to it are legal and typed properly according to the grammar, but
+ * accepts that the tokens may still be in an invalid order or in some other
+ * unparsable configuration that requires it to throw an Error.
+ * @param {{}} grammar The grammar object to use to parse Jexl strings
+ * @param {string} [prefix] A string prefix to prepend to the expression string
+ *      for error messaging purposes.  This is useful for when a new Parser is
+ *      instantiated to parse an subexpression, as the parent Parser's
+ *      expression string thus far can be passed for a more user-friendly
+ *      error message.
+ * @param {{}} [stopMap] A mapping of token types to any truthy value. When the
+ *      token type is encountered, the parser will return the mapped value
+ *      instead of boolean false.
+ */
+class Parser {
+  _grammar: Grammar
+  _lexer: Lexer
+  _state: string
+  _tree: AstNode | null
+  _exprStr: string
+  _relative: boolean
+  _stopMap: Record<string, any>
+  _cursor?: AstNode | null
+  _subParser?: Parser
+  _parentStop?: boolean
+  _nextIdentEncapsulate?: boolean
+  _nextIdentRelative?: boolean
+  _curObjKey?: string
+  _sequenceExpressions?: AstNode[]
+
+  constructor(
+    grammar: Grammar,
+    lexer: Lexer,
+    prefix?: string,
+    stopMap?: Record<string, any>
+  ) {
+    this._grammar = grammar
+    this._lexer = lexer
+    this._state = 'expectOperand'
+    this._tree = null
+    this._exprStr = prefix || ''
+    this._relative = false
+    this._stopMap = stopMap || {}
+  }
+
+  /**
+   * Processes a new token into the AST and manages the transitions of the state
+   * machine.
+   * @param {{type: <string>}} token A token object, as provided by the
+   *      {@link Lexer#tokenize} function.
+   * @throws {Error} if a token is added when the Parser has been marked as
+   *      complete by {@link #complete}, or if an unexpected token type is added.
+   * @returns {boolean|*} the stopState value if this parser encountered a token
+   *      in the stopState mapb false if tokens can continue.
+   */
+  addToken(token: Token): any {
+    if (this._state === 'complete') {
+      throw new Error('Cannot add a new token to a completed Parser')
+    }
+    const state = states[this._state]
+    const startExpr = this._exprStr
+    this._exprStr += token.raw
+    if (state.subHandler) {
+      if (!this._subParser) {
+        this._startSubExpression(startExpr)
+      }
+      const stopState = this._subParser!.addToken(token)
+      if (stopState) {
+        this._endSubExpression()
+        if (this._parentStop) {
+          return stopState
+        }
+        this._state = stopState
+      }
+    } else if (state.tokenTypes?.[token.type]) {
+      const typeOpts = state.tokenTypes[token.type]
+      let handleFunc = (handlers as any)[token.type]
+      if (typeOpts.handler) {
+        handleFunc = typeOpts.handler
+      }
+      if (handleFunc) {
+        handleFunc.call(this, token)
+      }
+      if (typeOpts.toState) {
+        this._state = typeOpts.toState
+      }
+    } else if (this._stopMap[token.type]) {
+      return this._stopMap[token.type]
+    } else {
+      throw new Error(
+        `Token ${token.raw} (${token.type}) unexpected in expression: ${this._exprStr}`
+      )
+    }
+    return false
+  }
+
+  /**
+   * Processes an array of tokens iteratively through the {@link #addToken}
+   * function.
+   * @param {Array<{type: <string>}>} tokens An array of tokens, as provided by
+   *      the {@link Lexer#tokenize} function.
+   */
+  addTokens(tokens: Token[]) {
+    tokens.forEach((token) => this.addToken(token))
+  }
+
+  /**
+   * Marks this Parser instance as completed and retrieves the full AST.
+   * @returns {{}|null} a full expression tree, ready for evaluation by the
+   *      {@link Evaluator#eval} function, or null if no tokens were passed to
+   *      the parser before complete was called
+   * @throws {Error} if the parser is not in a state where it's legal to end
+   *      the expression, indicating that the expression is incomplete
+   */
+  complete() {
+    if (this._cursor && !states[this._state].completable) {
+      throw new Error(`Unexpected end of expression: ${this._exprStr}`)
+    }
+    if (this._subParser) {
+      this._endSubExpression()
+    }
+
+    if (this._sequenceExpressions) {
+      this._sequenceExpressions.push(this._tree!)
+      const sequence: any = {
+        type: 'SequenceExpression',
+        expressions: this._sequenceExpressions
+      }
+      this._state = 'complete'
+      return sequence
+    }
+
+    this._state = 'complete'
+    return this._cursor ? this._tree : null
+  }
+
+  /**
+   * Indicates whether the expression tree contains a relative path identifier.
+   * @returns {boolean} true if a relative identifier exists false otherwise.
+   */
+  isRelative() {
+    return this._relative
+  }
+
+  /**
+   * Ends a subexpression by completing the subParser and passing its result
+   * to the subHandler configured in the current state.
+   * @private
+   */
+  _endSubExpression() {
+    states[this._state].subHandler!.call(this, this._subParser!.complete())
+    this._subParser = undefined
+  }
+
+  /**
+   * Places a new tree node at the current position of the cursor (to the 'right'
+   * property) and then advances the cursor to the new node. This function also
+   * handles setting the parent of the new node.
+   * @param {{type: <string>}} node A node to be added to the AST
+   * @private
+   */
+  _placeAtCursor(node: AstNode) {
+    if (!this._cursor) {
+      this._tree = node
+    } else {
+      ;(this._cursor as any).right = node
+      this._setParent(node, this._cursor)
+    }
+    this._cursor = node
+  }
+
+  /**
+   * Places a tree node before the current position of the cursor, replacing
+   * the node that the cursor currently points to. This should only be called in
+   * cases where the cursor is known to exist, and the provided node already
+   * contains a pointer to what's at the cursor currently.
+   * @param {{type: <string>}} node A node to be added to the AST
+   * @private
+   */
+  _placeBeforeCursor(node: AstNode) {
+    this._cursor = this._cursor?._parent
+    this._placeAtCursor(node)
+  }
+
+  /**
+   * Sets the parent of a node by creating a non-enumerable _parent property
+   * that points to the supplied parent argument.
+   * @param {{type: <string>}} node A node of the AST on which to set a new
+   *      parent
+   * @param {{type: <string>}} parent An existing node of the AST to serve as the
+   *      parent of the new node
+   * @private
+   */
+  _setParent(node: AstNode, parent: AstNode) {
+    Object.defineProperty(node, '_parent', {
+      value: parent,
+      writable: true
+    })
+  }
+
+  /**
+   * Prepares the Parser to accept a subexpression by (re)instantiating the
+   * subParser.
+   * @param {string} [exprStr] The expression string to prefix to the new Parser
+   * @private
+   */
+  _startSubExpression(exprStr?: string) {
+    let endStates = states[this._state].endStates
+    if (!endStates) {
+      this._parentStop = true
+      endStates = this._stopMap
+    }
+    this._subParser = new Parser(this._grammar, this._lexer, exprStr, endStates)
+  }
+}
+
+export default Parser