@jbrowse/jexl 2.3.1

package/src/Lexer.ts

@@ -0,0 +1,344 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+import type { 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 whitespaceRegex = /^\s*$/
+const preOpRegexElems = [
+  // Template strings
+  '`(?:[^`\\\\]|\\\\.)*`',
+  // Strings
+  String.raw`'(?:(?:\\')|[^'])*'`,
+  String.raw`"(?:(?:\\")|[^"])*"`,
+  // Whitespace
+  String.raw`\s+`,
+  // Booleans
+  String.raw`\btrue\b`,
+  String.raw`\bfalse\b`
+]
+const postOpRegexElems = [
+  // Identifiers
+  '[a-zA-Zа-яА-Я_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF\\$][a-zA-Z0-9а-яА-Я_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF\\$]*',
+  // Numerics (without negative symbol)
+  String.raw`(?:(?:[0-9]*\.[0-9]+)|[0-9]+)`
+]
+const minusNegatesAfter = new Set([
+  'binaryOp',
+  'unaryOp',
+  'openParen',
+  'openBracket',
+  'question',
+  'colon'
+])
+
+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
+ * "parts of speech" of a Jexl expression, and tokenize and label each, but
+ * to do only the most minimal syntax checking; the only errors the Lexer
+ * should be concerned with are if it's unable to identify the utility of
+ * any of its tokens.  Errors stemming from these tokens not being in a
+ * sensible configuration should be left for the Parser to handle.
+ * @type {{}}
+ */
+class Lexer {
+  _grammar: Grammar
+  _splitRegex?: RegExp
+  _escQuoteRegexCache = new Map<string, RegExp>()
+
+  constructor(grammar: Grammar) {
+    this._grammar = grammar
+  }
+
+  /**
+   * Splits a Jexl expression string into an array of expression elements.
+   * @param {string} str A Jexl expression string
+   * @returns {Array<string>} An array of substrings defining the functional
+   *      elements of the expression.
+   */
+  getElements(str: string) {
+    const regex = this._getSplitRegex()
+    return str.split(regex).filter(Boolean)
+  }
+
+  /**
+   * Converts an array of expression elements into an array of tokens.  Note that
+   * the resulting array may not equal the element array in length, as any
+   * elements that consist only of whitespace get appended to the previous
+   * token's "raw" property.  For the structure of a token object, please see
+   * {@link Lexer#tokenize}.
+   * @param {Array<string>} elements An array of Jexl expression elements to be
+   *      converted to tokens
+   * @returns {Array<{type, value, raw}>} an array of token objects.
+   */
+  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]
+        }
+      } else if (elements[i] === '-' && this._isNegative(tokens)) {
+        negate = true
+      } else {
+        if (negate) {
+          elements[i] = '-' + elements[i]
+          negate = false
+        }
+        tokens.push(this._createToken(elements[i]))
+      }
+    }
+    // Catch a - at the end of the string. Let the parser handle that issue.
+    if (negate) {
+      tokens.push(this._createToken('-'))
+    }
+    return tokens
+  }
+
+  /**
+   * Converts a Jexl string into an array of tokens.  Each token is an object
+   * in the following format:
+   *
+   *     {
+   *         type: <string>,
+   *         [name]: <string>,
+   *         value: <boolean|number|string>,
+   *         raw: <string>
+   *     }
+   *
+   * Type is one of the following:
+   *
+   *      literal, identifier, binaryOp, unaryOp
+   *
+   * OR, if the token is a control character its type is the name of the element
+   * defined in the Grammar.
+   *
+   * Name appears only if the token is a control string found in
+   * {@link grammar#elements}, and is set to the name of the element.
+   *
+   * Value is the value of the token in the correct type (boolean or numeric as
+   * appropriate). Raw is the string representation of this value taken directly
+   * from the expression string, including any trailing spaces.
+   * @param {string} str The Jexl string to be tokenized
+   * @returns {Array<{type, value, raw}>} an array of token objects.
+   * @throws {Error} if the provided string contains an invalid token.
+   */
+  tokenize(str: string) {
+    const elements = this.getElements(str)
+    return this.getTokens(elements)
+  }
+
+  /**
+   * Creates a new token object from an element of a Jexl string. See
+   * {@link Lexer#tokenize} for a description of the token object.
+   * @param {string} element The element from which a token should be made
+   * @returns {{value: number|boolean|string, [name]: string, type: string,
+   *      raw: string}} a token object describing the provided element.
+   * @throws {Error} if the provided string is not a valid expression element.
+   * @private
+   */
+  _createToken(element: string): Token {
+    const token: Token = {
+      type: 'literal',
+      value: element,
+      raw: element
+    }
+    if (element.startsWith('`')) {
+      token.type = 'templateString'
+      token.value = this._parseTemplateString(element)
+      return token
+    } else if (element.startsWith('"') || element.startsWith("'")) {
+      token.value = this._unquote(element)
+    } else if (numericRegex.exec(element)) {
+      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 (identRegex.exec(element)) {
+      token.type = 'identifier'
+    } else {
+      throw new Error(`Invalid expression token: ${element}`)
+    }
+    return token
+  }
+
+  /**
+   * Escapes a string so that it can be treated as a string literal within a
+   * regular expression.
+   * @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
+   * @private
+   */
+  _escapeRegExp(str: string) {
+    str = str.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
+    if (identRegex.exec(str)) {
+      str = String.raw`\b` + str + String.raw`\b`
+    }
+    return str
+  }
+
+  /**
+   * Gets a RegEx object appropriate for splitting a Jexl string into its core
+   * elements.
+   * @returns {RegExp} An element-splitting RegExp object
+   * @private
+   */
+  _getSplitRegex() {
+    if (!this._splitRegex) {
+      // Sort by most characters to least, then regex escape each
+      const elemArray = Object.keys(this._grammar.elements)
+        .sort((a, b) => {
+          return b.length - a.length
+        })
+        .map((elem) => {
+          return this._escapeRegExp(elem)
+        })
+      this._splitRegex = new RegExp(
+        '(' +
+          [
+            preOpRegexElems.join('|'),
+            elemArray.join('|'),
+            postOpRegexElems.join('|')
+          ].join('|') +
+          ')'
+      )
+    }
+    return this._splitRegex
+  }
+
+  /**
+   * Determines whether the addition of a '-' token should be interpreted as a
+   * negative symbol for an upcoming number, given an array of tokens already
+   * processed.
+   * @param {Array<Object>} tokens An array of tokens already processed
+   * @returns {boolean} true if adding a '-' should be considered a negative
+   *      symbol; false otherwise
+   * @private
+   */
+  _isNegative(tokens: Token[]) {
+    if (!tokens.length) {
+      return true
+    }
+    return minusNegatesAfter.has(tokens[tokens.length - 1].type)
+  }
+
+  /**
+   * A utility function to determine if a string consists of only space
+   * characters.
+   * @param {string} str A string to be tested
+   * @returns {boolean} true if the string is empty or consists of only spaces;
+   *      false otherwise.
+   * @private
+   */
+  _isWhitespace(str: string) {
+    return !!whitespaceRegex.exec(str)
+  }
+
+  /**
+   * Removes the beginning and trailing quotes from a string, unescapes any
+   * escaped quotes on its interior, and unescapes any escaped escape
+   * characters. Note that this function is not defensive; it assumes that the
+   * provided string is not empty, and that its first and last characters are
+   * actually quotes.
+   * @param {string} str A string whose first and last characters are quotes
+   * @returns {string} a string with the surrounding quotes stripped and escapes
+   *      properly processed.
+   * @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)
+    }
+    return str
+      .slice(1, -1)
+      .replace(escQuoteRegex, quote)
+      .replace(escEscRegex, '\\')
+  }
+
+  _parseTemplateString(str: string) {
+    const parts: { type: 'static' | 'interpolation'; value: string }[] = []
+    let current = 1
+    let staticStart = 1
+
+    while (current < str.length - 1) {
+      if (str[current] === '\\') {
+        current += 2
+        continue
+      }
+
+      if (str[current] === '$' && str[current + 1] === '{') {
+        if (current > staticStart) {
+          parts.push({
+            type: 'static',
+            value: str.slice(staticStart, current)
+          })
+        }
+
+        let braceDepth = 1
+        const interpStart = current + 2
+        current += 2
+
+        while (current < str.length && braceDepth > 0) {
+          if (str[current] === '\\') {
+            current += 2
+            continue
+          }
+          if (str[current] === '{') {
+            braceDepth++
+          }
+          if (str[current] === '}') {
+            braceDepth--
+          }
+          current++
+        }
+
+        if (braceDepth !== 0) {
+          throw new Error(`Unclosed interpolation in template string: ${str}`)
+        }
+
+        parts.push({
+          type: 'interpolation',
+          value: str.slice(interpStart, current - 1)
+        })
+
+        staticStart = current
+      } else {
+        current++
+      }
+    }
+
+    if (current > staticStart) {
+      parts.push({
+        type: 'static',
+        value: str.slice(staticStart, current)
+      })
+    }
+
+    return parts
+  }
+
+  _unescapeTemplateString(str: string) {
+    return str
+      .replaceAll('\\`', '`')
+      .replaceAll(String.raw`\$`, '$')
+      .replaceAll('\\\\', '\\')
+  }
+}
+
+export default Lexer

package/src/PromiseSync.ts

@@ -0,0 +1,86 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+class PromiseSync<T = unknown> {
+  value?: T
+  error?: unknown
+
+  constructor(fn: (resolve: (val: T) => void, reject: (error: unknown) => void) => void) {
+    fn(this._resolve.bind(this), this._reject.bind(this))
+  }
+
+  catch<TResult = never>(rejected: (error: unknown) => TResult): PromiseSync<T | TResult> {
+    if (this.error) {
+      try {
+        this._resolve(rejected(this.error) as any)
+      } catch (e) {
+        this._reject(e)
+      }
+    }
+    return this as any
+  }
+
+  // eslint-disable-next-line unicorn/no-thenable
+  then<TResult1 = T, TResult2 = never>(
+    resolved: (val: T) => TResult1,
+    rejected?: (error: unknown) => TResult2
+  ): PromiseSync<TResult1 | TResult2> {
+    if (!this.error) {
+      try {
+        this._resolve(resolved(this.value as T) as any)
+      } catch (e) {
+        this._reject(e)
+      }
+    }
+    if (rejected) {this.catch(rejected)}
+    return this as any
+  }
+
+  _reject(error: unknown) {
+    this.value = undefined
+    this.error = error
+  }
+
+  _resolve(val: any) {
+    if (val instanceof PromiseSync) {
+      if (val.error) {
+        this._reject(val.error)
+      } else {
+        this._resolve(val.value)
+      }
+    } else {
+      this.value = val
+      this.error = undefined
+    }
+  }
+
+  static all<T>(vals: (PromiseSync<T> | T)[]): PromiseSync<T[]> {
+    return new PromiseSync((resolve) => {
+      const resolved = vals.map((val) => {
+        while (val instanceof PromiseSync) {
+          if (val.error) {
+            if (val.error instanceof Error) {
+              throw val.error
+            }
+            throw new Error(typeof val.error === 'string' ? val.error : JSON.stringify(val.error))
+          }
+          val = val.value as T
+        }
+        return val
+      })
+      resolve(resolved)
+    })
+  }
+
+  static resolve<T>(val?: T): PromiseSync<T> {
+    return new PromiseSync<T>((resolve) => { resolve(val as T) })
+  }
+
+  static reject(error: unknown): PromiseSync<never> {
+    return new PromiseSync((_, reject) => { reject(error) })
+  }
+}
+
+export default PromiseSync

package/src/evaluator/Evaluator.ts

@@ -0,0 +1,153 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+import * as handlers from './handlers.ts'
+
+import type { AstNode } from '../types.ts'
+
+interface Grammar {
+  elements: Record<string, any>
+  [key: string]: any
+}
+
+// eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+type PromiseConstructor = typeof Promise | any
+
+/**
+ * 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
+ * expressions, and does not have to be reinstantiated for each.
+ * @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
+ *      accessed to resolve the value of each non-relative identifier. Any
+ *      Promise values will be passed to the expression as their resolved
+ *      value.
+ * @param {{}|Array<{}|Array>} [relativeContext] A map or array to be accessed
+ *      to resolve the value of a relative identifier.
+ * @param {function} promise A constructor for the Promise class to be used;
+ *      probably either Promise or PromiseSync.
+ */
+class Evaluator {
+  _grammar: Grammar
+  _context: any
+  _relContext: any
+  Promise: PromiseConstructor
+
+  constructor(
+    grammar: Grammar,
+    context?: any,
+    relativeContext?: any,
+    promise: PromiseConstructor = Promise
+  ) {
+    this._grammar = grammar
+    this._context = context || {}
+    this._relContext = relativeContext || this._context
+    this.Promise = promise
+  }
+
+  /**
+   * Evaluates an expression tree within the configured context.
+   * @param {{}} ast An expression tree object
+   * @returns {Promise<*>} resolves with the resulting value of the expression.
+   */
+  eval(ast: AstNode) {
+    return this.Promise.resolve().then(() => {
+      return (handlers as any)[ast.type].call(this, ast)
+    })
+  }
+
+  /**
+   * Simultaneously 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 {Promise<Array<{}>>} resolves with the result array
+   */
+  evalArray(arr: AstNode[]) {
+    return this.Promise.all(arr.map((elem: AstNode) => this.eval(elem)))
+  }
+
+  /**
+   * Simultaneously 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 {Promise<{}>} resolves with the result map.
+   */
+  evalMap(map: Record<string, AstNode>) {
+    const entries = Object.entries(map)
+    const promises = entries.map(([_, ast]) => this.eval(ast))
+    return this.Promise.all(promises).then((vals: any[]) =>
+      Object.fromEntries(entries.map(([key], idx) => [key, vals[idx]]))
+    )
+  }
+
+  /**
+   * Applies a filter expression with relative identifier elements to a subject.
+   * The intent is for the subject to be an array of subjects that will be
+   * individually used as the relative context against the provided expression
+   * tree. Only the elements whose expressions result in a truthy value will be
+   * included in the resulting array.
+   *
+   * If the subject is not an array of values, it will be converted to a single-
+   * element array before running the filter.
+   * @param {*} subject The value to be filtered usually an array. If this value is
+   *      not an array, it will be converted to an array with this value as the
+   *      only element.
+   * @param {{}} expr The expression tree to run against each subject. If the
+   *      tree evaluates to a truthy result, then the value will be included in
+   *      the returned array otherwise, it will be eliminated.
+   * @returns {Promise<Array>} resolves with an array of values that passed the
+   *      expression filter.
+   * @private
+   */
+  _filterRelative(subject: any, expr: AstNode) {
+    const arr = Array.isArray(subject)
+      ? subject
+      : subject == null
+        ? []
+        : [subject]
+
+    const promises = arr.map((elem) =>
+      new Evaluator(this._grammar, this._context, elem, this.Promise).eval(expr)
+    )
+
+    return this.Promise.all(promises).then((values: any[]) =>
+      arr.filter((_, idx) => values[idx])
+    )
+  }
+
+  /**
+   * Applies a static filter expression to a subject value.  If the filter
+   * expression evaluates to boolean true, the subject is returned if false,
+   * undefined.
+   *
+   * For any other resulting value of the expression, this function will attempt
+   * to respond with the property at that name or index of the subject.
+   * @param {*} subject The value to be filtered.  Usually an Array (for which
+   *      the expression would generally resolve to a numeric index) or an
+   *      Object (for which the expression would generally resolve to a string
+   *      indicating a property name)
+   * @param {{}} expr The expression tree to run against the subject
+   * @returns {Promise<*>} resolves with the value of the drill-down.
+   * @private
+   */
+  _filterStatic(subject: any, expr: AstNode) {
+    return this.eval(expr).then((res: any) => {
+      if (typeof res === 'boolean') {
+        return res ? subject : undefined
+      }
+      return subject?.[res]
+    })
+  }
+}
+
+export default Evaluator