@jbrowse/jexl 4.0.0 → 5.0.0

package/src/grammar.ts

@@ -5,6 +5,16 @@
 
 /* eslint eqeqeq:0 */
 
+import { collectionFunctions } from './collections.ts'
+import {
+  addsPairwise,
+  anyPair,
+  isIn,
+  isList,
+  matches,
+  pairwise
+} from './operators.ts'
+
 import type { JexlValue } from './types.ts'
 
 export type BinaryOpEval = (left: JexlValue, right: JexlValue) => JexlValue
@@ -40,6 +50,8 @@ export interface BinaryOp {
    * which is how `-x` is distinguished from `a - x`.
    */
   unaryEval?: (right: JexlValue) => JexlValue
+  /** Groups a chain from the right, so `a ^ b ^ c` is `a ^ (b ^ c)`. */
+  rightAssociative?: boolean
 }
 
 export type UnaryOpEval = (right: JexlValue) => JexlValue
@@ -52,9 +64,9 @@ export interface UnaryOp {
 
 /**
  * The punctuation elements of the grammar. Unlike operators these carry no
- * behavior of their own; the Parser's state machine gives them meaning. The
- * type is a literal union rather than `string` so that `GrammarElement` is a
- * discriminated union, letting operator properties be accessed without casts.
+ * behavior of their own; the Parser gives them meaning. The type is a literal
+ * union rather than `string` so that `GrammarElement` is a discriminated union,
+ * letting operator properties be accessed without casts.
  */
 export interface SimpleElement {
   type:
@@ -69,6 +81,7 @@ export interface SimpleElement {
     | 'closeParen'
     | 'question'
     | 'semicolon'
+    | 'arrow'
 }
 
 export type GrammarElement = BinaryOp | UnaryOp | SimpleElement
@@ -76,20 +89,58 @@ export type GrammarElement = BinaryOp | UnaryOp | SimpleElement
 /** A registered function, as jexl calls it once the operands are evaluated. */
 export type GrammarFn = (...args: JexlValue[]) => JexlValue
 
+/**
+ * Reads `key` off `subject` for `subject.key` and `subject[key]`, in place of
+ * a plain property read. Like a registered function, it is handed host values
+ * jexl has no type for, so the subject is only promised not to be nullish.
+ */
+export type GetMember = (
+  subject: NonNullable<unknown>,
+  key: string | number
+) => unknown
+
+/**
+ * Called once per bare variable name as an expression compiles. A reader it
+ * returns replaces `context[name]` for that name; `undefined` keeps it.
+ */
+export type VariableReader = (
+  name: string
+) => ((context: Record<string, unknown>) => unknown) | undefined
+
 export interface Grammar {
   elements: Record<string, GrammarElement>
   functions: Record<string, GrammarFn>
+  getMember?: GetMember
+  variableReader?: VariableReader
 }
 
-/**
- * Returns the binding power of a grammar element, or 0 for elements that
- * aren't operators and therefore don't participate in precedence.
- */
-export function precedenceOf(elem: GrammarElement | undefined) {
-  return elem && (elem.type === 'binaryOp' || elem.type === 'unaryOp')
-    ? elem.precedence
-    : 0
-}
+const plus = (left: JexlValue, right: JexlValue) =>
+  (left as number) + (right as number)
+const minus = (left: JexlValue, right: JexlValue) =>
+  (left as number) - (right as number)
+const times = (left: JexlValue, right: JexlValue) =>
+  (left as number) * (right as number)
+const divide = (left: JexlValue, right: JexlValue) =>
+  (left as number) / (right as number)
+const floorDivide = (left: JexlValue, right: JexlValue) =>
+  Math.floor((left as number) / (right as number))
+const modulo = (left: JexlValue, right: JexlValue) =>
+  (left as number) % (right as number)
+const power = (left: JexlValue, right: JexlValue) =>
+  (left as number) ** (right as number)
+const loose = (left: JexlValue, right: JexlValue) => left == right
+// a missing value orders against nothing, as bcftools skips one; JavaScript
+// alone would read null as 0, making [null, 0.2] < 0.05 true
+const greater = (left: JexlValue, right: JexlValue) =>
+  left != null && right != null && (left as number) > (right as number)
+const atLeast = (left: JexlValue, right: JexlValue) =>
+  left != null && right != null && (left as number) >= (right as number)
+const less = (left: JexlValue, right: JexlValue) =>
+  left != null && right != null && (left as number) < (right as number)
+const atMost = (left: JexlValue, right: JexlValue) =>
+  left != null && right != null && (left as number) <= (right as number)
+const equals = (left: JexlValue, right: JexlValue) =>
+  isList(left, right) ? anyPair(loose, left, right) : left == right
 
 export const getGrammar = (): Grammar => ({
   /**
@@ -109,75 +160,113 @@ export const getGrammar = (): Grammar => ({
     ')': { type: 'closeParen' },
     '?': { type: 'question' },
     ';': { type: 'semicolon' },
+    '=>': { type: 'arrow' },
     '+': {
       type: 'binaryOp',
       precedence: 30,
-      eval: (left, right) => (left as number) + (right as number)
+      eval: (left, right) =>
+        addsPairwise(left, right)
+          ? pairwise(plus, left, right)
+          : plus(left, right)
     },
     '-': {
       type: 'binaryOp',
       precedence: 30,
-      eval: (left, right) => (left as number) - (right as number),
-      unaryEval: (right) => -(right as number)
+      eval: (left, right) =>
+        isList(left, right) ? pairwise(minus, left, right) : minus(left, right),
+      unaryEval: (right) =>
+        Array.isArray(right)
+          ? right.map((value) => -(value as number))
+          : -(right as number)
     },
     '*': {
       type: 'binaryOp',
       precedence: 40,
-      eval: (left, right) => (left as number) * (right as number)
+      eval: (left, right) =>
+        isList(left, right) ? pairwise(times, left, right) : times(left, right)
     },
     '/': {
       type: 'binaryOp',
       precedence: 40,
-      eval: (left, right) => (left as number) / (right as number)
+      eval: (left, right) =>
+        isList(left, right)
+          ? pairwise(divide, left, right)
+          : divide(left, right)
     },
     '//': {
       type: 'binaryOp',
       precedence: 40,
-      eval: (left, right) => Math.floor((left as number) / (right as number))
+      eval: (left, right) =>
+        isList(left, right)
+          ? pairwise(floorDivide, left, right)
+          : floorDivide(left, right)
     },
     '%': {
       type: 'binaryOp',
       precedence: 50,
-      eval: (left, right) => (left as number) % (right as number)
+      eval: (left, right) =>
+        isList(left, right)
+          ? pairwise(modulo, left, right)
+          : modulo(left, right)
     },
     '^': {
       type: 'binaryOp',
       precedence: 50,
-      eval: (left, right) => (left as number) ** (right as number)
+      rightAssociative: true,
+      eval: (left, right) =>
+        isList(left, right) ? pairwise(power, left, right) : power(left, right)
     },
     '==': {
       type: 'binaryOp',
       precedence: 20,
-      eval: (left, right) => left == right
+      eval: equals
     },
     '!=': {
       type: 'binaryOp',
       precedence: 20,
-      eval: (left, right) => left != right
+      eval: (left, right) => !equals(left, right)
+    },
+    '~': {
+      type: 'binaryOp',
+      precedence: 20,
+      eval: matches
+    },
+    '!~': {
+      type: 'binaryOp',
+      precedence: 20,
+      eval: (left, right) => !matches(left, right)
     },
     '>': {
       type: 'binaryOp',
       precedence: 20,
-      eval: (left, right) => (left as number) > (right as number)
+      eval: (left, right) =>
+        isList(left, right)
+          ? anyPair(greater, left, right)
+          : greater(left, right)
     },
     '>=': {
       type: 'binaryOp',
       precedence: 20,
-      eval: (left, right) => (left as number) >= (right as number)
+      eval: (left, right) =>
+        isList(left, right)
+          ? anyPair(atLeast, left, right)
+          : atLeast(left, right)
     },
     '<': {
       type: 'binaryOp',
       precedence: 20,
-      eval: (left, right) => (left as number) < (right as number)
+      eval: (left, right) =>
+        isList(left, right) ? anyPair(less, left, right) : less(left, right)
     },
     '<=': {
       type: 'binaryOp',
       precedence: 20,
-      eval: (left, right) => (left as number) <= (right as number)
+      eval: (left, right) =>
+        isList(left, right) ? anyPair(atMost, left, right) : atMost(left, right)
     },
     '&&': {
       type: 'binaryOp',
-      precedence: 10,
+      precedence: 11,
       evalOnDemand: (left, right) => {
         const leftVal = left.eval()
         if (!leftVal) {
@@ -197,23 +286,15 @@ export const getGrammar = (): Grammar => ({
         return right.eval()
       }
     },
+    '??': {
+      type: 'binaryOp',
+      precedence: 10,
+      evalOnDemand: (left, right) => left.eval() ?? right.eval()
+    },
     in: {
       type: 'binaryOp',
       precedence: 20,
-      eval: (left, right) => {
-        if (typeof right === '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'
-            ? right.includes(String(left))
-            : false
-        }
-        return Array.isArray(right) ? right.includes(left) : false
-      }
+      eval: isIn
     },
     '!': {
       type: 'unaryOp',
@@ -243,5 +324,5 @@ export const getGrammar = (): Grammar => ({
    * than throw. An error is only appropriate when the function would normally
    * return a value, but cannot due to some other failure.
    */
-  functions: {}
+  functions: { ...collectionFunctions }
 })

package/src/index.ts

@@ -4,7 +4,22 @@
  */
 
 export { Jexl, default } from './Jexl.ts'
+export type { JexlOptions } from './Jexl.ts'
+export type { GetMember, VariableReader } from './grammar.ts'
 export { default as Expression } from './Expression.ts'
+export { analyze } from './analyze.ts'
+export { check, print, recordOf, union } from './check.ts'
+export {
+  callSubject,
+  conditions,
+  fromConditions,
+  pathSubject,
+  printCondition
+} from './conditions.ts'
 export { default as Lexer } from './Lexer.ts'
+export { JexlSyntaxError } from './errors.ts'
 export { getGrammar } from './grammar.ts'
+export type * from './analyze.ts'
+export type * from './check.ts'
+export type * from './conditions.ts'
 export type * from './types.ts'

package/src/operators.ts

@@ -0,0 +1,151 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+import type { JexlValue } from './types.ts'
+
+type Test = (left: JexlValue, right: JexlValue) => boolean
+type Arithmetic = (left: JexlValue, right: JexlValue) => JexlValue
+
+export function isList(left: JexlValue, right: JexlValue) {
+  return Array.isArray(left) || Array.isArray(right)
+}
+
+/**
+ * A comparison over list operands: it holds when it holds for any value, as
+ * bcftools compares a multi-valued tag, so `AF > 0.05` is true when any
+ * allele's frequency is and `CLNSIG == 'Pathogenic'` when any significance is.
+ * Each operator calls this only once {@link isList} says it must, so the
+ * comparison of two single values stays a direct call V8 can inline.
+ */
+export function anyPair(
+  test: Test,
+  left: JexlValue,
+  right: JexlValue
+): boolean {
+  return Array.isArray(left)
+    ? left.some((l) => anyPair(test, l, right))
+    : Array.isArray(right)
+      ? right.some((r) => anyPair(test, left, r))
+      : test(left, right)
+}
+
+function hasText(value: JexlValue) {
+  return (
+    typeof value === 'string' ||
+    (Array.isArray(value) && value.some((item) => typeof item === 'string'))
+  )
+}
+
+/**
+ * Whether `+` pairs its operands value by value: only when a list is involved
+ * and neither side holds text, so `REF + '>' + ALT` still joins as JavaScript
+ * joins, `'A>T,C'`, while `DP + 1` adds.
+ */
+export function addsPairwise(left: JexlValue, right: JexlValue) {
+  return isList(left, right) && !hasText(left) && !hasText(right)
+}
+
+/**
+ * Arithmetic over list operands, value by value, as bcftools and R apply it:
+ * `AC / AN` divides each count, and a list of one, or a lone value, pairs with
+ * every value of the other side. Lists of two other lengths have no pairing
+ * and yield undefined.
+ */
+export function pairwise(
+  fn: Arithmetic,
+  left: JexlValue,
+  right: JexlValue
+): JexlValue {
+  const ls = Array.isArray(left) ? left : [left]
+  const rs = Array.isArray(right) ? right : [right]
+  if (ls.length !== rs.length && ls.length !== 1 && rs.length !== 1) {
+    return undefined
+  }
+  const length = ls.length === 1 ? rs.length : ls.length
+  const out: JexlValue[] = new Array(length)
+  for (let i = 0; i < length; i++) {
+    out[i] = fn(
+      ls.length === 1 ? ls[0] : ls[i],
+      rs.length === 1 ? rs[0] : rs[i]
+    )
+  }
+  return out
+}
+
+const patterns = new Map<string, RegExp>()
+const MAX_PATTERNS = 1000
+
+/**
+ * The regular expression a pattern string stands for. A leading `(?i)`, the
+ * inline flag PCRE, Python and Go read, makes it case-insensitive.
+ */
+function regex(pattern: string) {
+  let re = patterns.get(pattern)
+  if (!re) {
+    try {
+      re = pattern.startsWith('(?i)')
+        ? new RegExp(pattern.slice(4), 'i')
+        : new RegExp(pattern)
+    } catch {
+      throw new Error(`Invalid regular expression: ${pattern}`)
+    }
+    if (patterns.size >= MAX_PATTERNS) {
+      patterns.clear()
+    }
+    patterns.set(pattern, re)
+  }
+  return re
+}
+
+/** Whether a value, or any value of a list, matches a pattern string. */
+export function matches(value: JexlValue, pattern: JexlValue): boolean {
+  if (typeof pattern !== 'string') {
+    return false
+  }
+  const re = regex(pattern)
+  const test = (v: JexlValue) =>
+    (typeof v === 'string' ||
+      typeof v === 'number' ||
+      typeof v === 'boolean') &&
+    re.test(String(v))
+  return Array.isArray(value) ? value.some(test) : test(value)
+}
+
+/**
+ * Whether a value is in a container: a substring of a string, a member of a
+ * list or Set, or a key of a Map or plain object. A list on the left is in
+ * the container when any of its values is.
+ */
+export function isIn(left: JexlValue, right: JexlValue): boolean {
+  if (Array.isArray(left)) {
+    return left.some((l) => isIn(l, right))
+  }
+  if (typeof right === '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
+    return typeof left === 'string' ||
+      typeof left === 'number' ||
+      typeof left === 'boolean'
+      ? right.includes(String(left))
+      : false
+  }
+  if (Array.isArray(right)) {
+    return right.includes(left)
+  }
+  if (right instanceof Set || right instanceof Map) {
+    return right.has(left)
+  }
+  if (
+    typeof right === 'object' &&
+    right !== null &&
+    (typeof left === 'string' ||
+      typeof left === 'number' ||
+      typeof left === 'boolean')
+  ) {
+    return Object.hasOwn(right, String(left))
+  }
+  return false
+}