@jbrowse/jexl 4.0.1 → 5.0.0

package/src/evaluator/compile.ts

@@ -4,7 +4,13 @@
  */
 
 import type { Grammar } from '../grammar.ts'
-import type { AstNode, AstNodeUnion, JexlValue } from '../types.ts'
+import type {
+  AstNode,
+  AstNodeUnion,
+  JexlFunction,
+  JexlValue,
+  Literal
+} from '../types.ts'
 
 /** The variables an expression is evaluated against. */
 export type Context = Record<string, JexlValue>
@@ -36,15 +42,24 @@ function assignOwn(target: Context, key: string, value: JexlValue) {
   target[key] = value
 }
 
+/** The key `subject[index]` reads under, or undefined when it reads nothing. */
+function memberKey(index: JexlValue) {
+  return typeof index === 'string' || typeof index === 'number'
+    ? index
+    : indexKey(index)
+}
+
 /**
  * The key a bracket index that is neither a string nor a number reads under:
  * its string form, when it has one worth using.
  *
  * A boolean and an array of primitives do — `['a']` is the key `'a'`, exactly
- * as JS would index by it. A plain object does not, since '[object Object]' is
- * not a key anything is stored under, so it and an array holding one answer
- * `undefined` instead; indexing by either reached that lookup and missed
- * anyway. null and undefined are the same case.
+ * as JS would index by it, and how a `@gmod/vcf` INFO value (always a list,
+ * `Number=1` included) indexes a lookup table. A multi-valued list is the key
+ * `'a,b'`, and misses rather than guess which value was meant. A plain object
+ * does not, since '[object Object]' is not a key anything is stored under, so
+ * it and an array holding one answer `undefined` instead. null and undefined
+ * are the same case.
  */
 function indexKey(value: JexlValue): string | undefined {
   if (typeof value === 'boolean') {
@@ -66,19 +81,197 @@ function isKeyPart(
   )
 }
 
-/** Renders an interpolated value for a template literal. */
-function stringify(value: JexlValue) {
-  if (value == null) {
-    return ''
+/**
+ * The value of an object or array literal holding only primitives, built once.
+ * Indexing such a table, as in `{CDS: 'red', exon: 'blue'}[feature.type]`,
+ * can only yield a primitive, so the table never escapes and one frozen copy
+ * serves every evaluation.
+ */
+function literalTable(node: AstNode) {
+  const literal = node as AstNodeUnion
+  if (literal.type === 'ArrayLiteral') {
+    return literal.value.every((item) => item.type === 'Literal')
+      ? Object.freeze(literal.value.map((item) => (item as Literal).value))
+      : undefined
   }
-  if (
-    typeof value === 'string' ||
-    typeof value === 'number' ||
-    typeof value === 'boolean'
+  if (literal.type === 'ObjectLiteral') {
+    const entries = Object.entries(literal.value)
+    if (entries.every(([, value]) => value.type === 'Literal')) {
+      const table: Context = {}
+      for (const [key, value] of entries) {
+        defineOwn(table, key, (value as Literal).value)
+      }
+      return Object.freeze(table)
+    }
+  }
+  return undefined
+}
+
+const unassigned = Symbol('unassigned')
+
+/**
+ * The slot each name an expression assigns is kept in, and the frame holding
+ * those slots for the evaluation in progress.
+ */
+interface Locals {
+  slots: ReadonlyMap<string, number>
+  frame: { locals: unknown[] }
+}
+
+/**
+ * One call of a lambda. A name the lambda binds reads from `args`, a name bound
+ * by a lambda around it from `outer`, a name the expression assigns from
+ * `locals` — the evaluation's own, captured when the lambda was made, so a
+ * lambda called after its evaluation ends still sees them — and any other name
+ * from `context`.
+ */
+class LambdaFrame {
+  args: JexlValue[]
+  outer: LambdaFrame | undefined
+  context: Context
+  locals: unknown[] | undefined
+
+  constructor(
+    args: JexlValue[],
+    outer: LambdaFrame | undefined,
+    context: Context,
+    locals: unknown[] | undefined
   ) {
-    return String(value)
+    this.args = args
+    this.outer = outer
+    this.context = context
+    this.locals = locals
+  }
+}
+
+/** The parameters of the lambdas around a node, innermost first. */
+interface Params {
+  names: string[]
+  outer: Params | undefined
+}
+
+interface Scope {
+  locals?: Locals
+  params?: Params
+}
+
+// the closures compiled inside a lambda are handed its LambdaFrame in place of
+// the context, and only the ones that read a name, below, look inside it
+const asFrame = (env: Context) => env as unknown as LambdaFrame
+const asContext = (frame: LambdaFrame) => frame as unknown as Context
+
+function compileName(
+  name: string,
+  grammar: Grammar,
+  scope: Scope
+): CompiledNode {
+  let hops = 0
+  for (let p = scope.params; p; p = p.outer) {
+    const index = p.names.indexOf(name)
+    if (index !== -1) {
+      return hops === 0 ? (env) => asFrame(env).args[index] : climb(hops, index)
+    }
+    hops++
+  }
+  const read =
+    (grammar.variableReader?.(name) as CompiledNode | undefined) ??
+    ((ctx) => ctx[name])
+  const fromContext: CompiledNode = scope.params
+    ? (env) => read(asFrame(env).context)
+    : read
+  const slot = scope.locals?.slots.get(name)
+  if (slot === undefined) {
+    return fromContext
+  }
+  if (scope.params) {
+    return (env) => {
+      const local = asFrame(env).locals![slot]
+      return local === unassigned ? fromContext(env) : (local as JexlValue)
+    }
+  }
+  const { frame } = scope.locals!
+  return (env) => {
+    const local = frame.locals[slot]
+    return local === unassigned ? fromContext(env) : (local as JexlValue)
+  }
+}
+
+function climb(hops: number, index: number): CompiledNode {
+  return (env) => {
+    let frame = asFrame(env)
+    for (let i = 0; i < hops; i++) {
+      frame = frame.outer!
+    }
+    return frame.args[index]
   }
-  return JSON.stringify(value)
+}
+
+function assignedNames(ast: AstNode | undefined, names = new Set<string>()) {
+  const node = ast as AstNodeUnion | undefined
+  switch (node?.type) {
+    case 'AssignmentExpression': {
+      names.add(node.left.value)
+      assignedNames(node.right, names)
+      break
+    }
+    case 'Identifier': {
+      assignedNames(node.from, names)
+      break
+    }
+    case 'BinaryExpression': {
+      assignedNames(node.left, names)
+      assignedNames(node.right, names)
+      break
+    }
+    case 'UnaryExpression': {
+      assignedNames(node.right, names)
+      break
+    }
+    case 'ConditionalExpression': {
+      assignedNames(node.test, names)
+      assignedNames(node.consequent, names)
+      assignedNames(node.alternate, names)
+      break
+    }
+    case 'FilterExpression': {
+      assignedNames(node.subject, names)
+      assignedNames(node.expr, names)
+      break
+    }
+    case 'ArrayLiteral':
+    case 'FunctionCall':
+    case 'SequenceExpression': {
+      const children =
+        node.type === 'ArrayLiteral'
+          ? node.value
+          : node.type === 'FunctionCall'
+            ? node.args
+            : node.expressions
+      for (const child of children) {
+        assignedNames(child, names)
+      }
+      break
+    }
+    case 'ObjectLiteral': {
+      for (const child of Object.values(node.value)) {
+        assignedNames(child, names)
+      }
+      break
+    }
+    case 'TemplateLiteral': {
+      for (const part of node.parts) {
+        if (part.type === 'expression') {
+          assignedNames(part.value, names)
+        }
+      }
+      break
+    }
+    case 'Lambda': {
+      assignedNames(node.body, names)
+      break
+    }
+  }
+  return names
 }
 
 /**
@@ -90,16 +283,61 @@ function stringify(value: JexlValue) {
  * times.
  *
  * Operators are bound here, so a grammar change after compilation requires
- * recompiling, which is what {@link Expression#compile} already documents.
- * Functions are looked up per call, since they are commonly registered after
- * an expression has been compiled.
+ * recompiling. Functions are looked up per call, since they are commonly
+ * registered after an expression has been compiled.
  *
- * @param {{}} ast An expression tree, as produced by the Parser
- * @param {{}} grammar The grammar to resolve operators against
- * @returns {function} a closure returning the expression's value
- * @throws {Error} if the tree contains an unrecognized node type
+ * Each name the expression assigns gets a slot, numbered at compile time, in a
+ * frame that lasts one evaluation, so an assignment never touches the context
+ * and a context reused from one evaluation to the next comes back unchanged. A
+ * name reads its slot once assigned, and resolves as usual until then. An
+ * expression that assigns nothing gets no frame. The frame is not a layer over
+ * the context via `Object.create`: V8 gives every object used as a prototype a
+ * map of its own, which made evaluating against a context built per evaluation
+ * six times slower.
  */
 export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
+  const names = [...assignedNames(ast)]
+  if (names.length === 0) {
+    return compileNode(ast, grammar, {})
+  }
+  const slots = new Map(names.map((name, i) => [name, i]))
+  const empty = names.map(() => unassigned)
+  const frame = { locals: empty }
+  const fn = compileNode(ast, grammar, { locals: { slots, frame } })
+  // saved and restored, so a function that evaluates this same expression
+  // again from inside it leaves the outer evaluation's locals intact
+  return (ctx) => {
+    const outer = frame.locals
+    frame.locals = empty.slice()
+    try {
+      return fn(ctx)
+    } finally {
+      frame.locals = outer
+    }
+  }
+}
+
+/** Renders an interpolated value for a template literal. */
+function stringify(value: JexlValue) {
+  if (value == null) {
+    return ''
+  }
+  if (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return String(value)
+  }
+  return JSON.stringify(value)
+}
+
+function compileNode(
+  ast: AstNode,
+  grammar: Grammar,
+  scope: Scope
+): CompiledNode {
+  const compile = (child: AstNode) => compileNode(child, grammar, scope)
   // 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
@@ -113,49 +351,44 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     case 'Identifier': {
       const name = node.value
       if (!node.from) {
-        return (ctx) => ctx[name]
+        return compileName(name, grammar, scope)
       }
-      const from = compileAst(node.from, grammar)
-      return (ctx) => {
-        const subject = from(ctx)
-        if (subject == null) {
-          return undefined
+      const from = compile(node.from)
+      const { getMember } = grammar
+      if (getMember) {
+        return (ctx) => {
+          const target = from(ctx)
+          return target == null
+            ? undefined
+            : (getMember(target, name) as JexlValue)
         }
-        // an identifier chained off an array reads through its first element
-        const target = Array.isArray(subject) ? subject[0] : subject
+      }
+      return (ctx) => {
+        const target = from(ctx)
         return target == null ? undefined : (target as Context)[name]
       }
     }
 
     case 'BinaryExpression': {
       const op = grammar.elements[node.operator]
-      if (op?.type !== 'binaryOp') {
-        // matches the tree-walking behaviour: an unknown operator yields
-        // undefined without evaluating either operand
-        return () => undefined
-      }
-      const left = compileAst(node.left, grammar)
-      const right = compileAst(node.right!, grammar)
-      const { evalOnDemand } = op
-      if (evalOnDemand) {
+      const left = compile(node.left)
+      const right = compile(node.right!)
+      if (op?.type === 'binaryOp' && op.evalOnDemand) {
+        const { evalOnDemand } = op
         // operands stay unevaluated behind an `eval` thunk, so operators such
         // as && and || can short-circuit
         return (ctx) =>
           evalOnDemand({ eval: () => left(ctx) }, { eval: () => right(ctx) })
       }
-      const fn = op.eval
+      const fn = op?.type === 'binaryOp' ? op.eval : undefined
       if (!fn) {
-        return (ctx) => {
-          left(ctx)
-          right(ctx)
-          return undefined
-        }
+        throw new Error(`Unknown binary operator '${node.operator}'`)
       }
       return (ctx) => fn(left(ctx), right(ctx))
     }
 
     case 'UnaryExpression': {
-      const right = compileAst(node.right!, grammar)
+      const right = compile(node.right!)
       const elem = grammar.elements[node.operator]
       const fn =
         elem?.type === 'unaryOp'
@@ -164,23 +397,15 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
             ? elem.unaryEval
             : undefined
       if (!fn) {
-        // the operand is still evaluated for an unknown operator, as before
-        return (ctx) => {
-          right(ctx)
-          return undefined
-        }
+        throw new Error(`Unknown unary operator '${node.operator}'`)
       }
       return (ctx) => fn(right(ctx))
     }
 
     case 'ConditionalExpression': {
-      const test = compileAst(node.test, grammar)
-      const consequent = node.consequent
-        ? compileAst(node.consequent, grammar)
-        : undefined
-      const alternate = node.alternate
-        ? compileAst(node.alternate, grammar)
-        : undefined
+      const test = compile(node.test)
+      const consequent = node.consequent ? compile(node.consequent) : undefined
+      const alternate = node.alternate ? compile(node.alternate) : undefined
       return (ctx) => {
         const res = test(ctx)
         if (res) {
@@ -192,44 +417,30 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'FilterExpression': {
-      const subject = compileAst(node.subject, grammar)
-      const index = compileAst(node.expr, grammar)
+      const table = literalTable(node.subject)
+      const subject = table ? () => table : compile(node.subject)
+      const index = compile(node.expr)
+      const { getMember } = grammar
+      if (getMember) {
+        return (ctx) => {
+          const subjectVal = subject(ctx)
+          const key = memberKey(index(ctx))
+          return subjectVal == null || key === undefined
+            ? undefined
+            : (getMember(subjectVal, key) as JexlValue)
+        }
+      }
       return (ctx) => {
         const subjectVal = subject(ctx)
-        const indexVal = index(ctx)
-        if (subjectVal == null) {
-          return undefined
-        }
-        if (typeof indexVal === 'string' || typeof indexVal === 'number') {
-          return (subjectVal as Record<string | number, JexlValue>)[indexVal]
-        }
-        // A value with a meaningful string form is indexed by it, which is what
-        // JS does and what this did until the evaluator was lowered to closures
-        // — the tree-walking version was a bare `subject?.[index]`. Answering
-        // `undefined` for everything else reads as a deliberate strictness and
-        // is not: nothing wanted it, and the shape it rejects is common.
-        //
-        // That shape is a one-element array. Every `@gmod/vcf` INFO value is a
-        // list — `Number=1` included, so `CLNSIG=Pathogenic` parses to
-        // `['Pathogenic']` — and the natural way to colour by one is a lookup
-        // table indexed by it. The miss is silent, because such an expression
-        // always carries a `|| fallback` for the values it has no entry for,
-        // and that fallback then answers for every record.
-        //
-        // A multi-valued list still misses — `['a','b']` is the key 'a,b' —
-        // which is the honest answer rather than a lucky one: reading through
-        // to the first element would be the index guessing which value was
-        // meant. `Identifier` above does read through a one-element array, but
-        // it is navigating rather than selecting, so it has nothing to guess.
-        const key = indexKey(indexVal)
-        return key === undefined
+        const key = memberKey(index(ctx))
+        return subjectVal == null || key === undefined
           ? undefined
-          : (subjectVal as Record<string, JexlValue>)[key]
+          : (subjectVal as Record<string | number, JexlValue>)[key]
       }
     }
 
     case 'ArrayLiteral': {
-      const items = node.value.map((item) => compileAst(item, grammar))
+      const items = node.value.map(compile)
       const len = items.length
       return (ctx) => {
         const out: JexlValue[] = new Array(len)
@@ -243,7 +454,7 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     case 'ObjectLiteral': {
       const entries = Object.entries(node.value)
       const keys = entries.map(([key]) => key)
-      const values = entries.map(([, value]) => compileAst(value, grammar))
+      const values = entries.map(([, value]) => compile(value))
       const len = keys.length
       // resolved once, here, so the common case keeps its plain store
       const store = keys.includes('__proto__') ? defineOwn : assignOwn
@@ -263,7 +474,7 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
           const { value } = part
           return () => value
         }
-        const expr = compileAst(part.value, grammar)
+        const expr = compile(part.value)
         return (ctx) => stringify(expr(ctx))
       })
       return (ctx) => {
@@ -277,7 +488,7 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
 
     case 'FunctionCall': {
       const { name } = node
-      const args = node.args.map((arg) => compileAst(arg, grammar))
+      const args = node.args.map(compile)
       // hasOwn, so that inherited Object.prototype members such as `toString`
       // and `constructor` aren't callable as Jexl functions. Resolved per call
       // rather than baked in, since functions are routinely registered after
@@ -325,7 +536,7 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'SequenceExpression': {
-      const exprs = node.expressions.map((expr) => compileAst(expr, grammar))
+      const exprs = node.expressions.map(compile)
       const len = exprs.length
       return (ctx) => {
         let last: JexlValue
@@ -337,13 +548,34 @@ export function compileAst(ast: AstNode, grammar: Grammar): CompiledNode {
     }
 
     case 'AssignmentExpression': {
-      const name = node.left.value
-      const right = compileAst(node.right!, grammar)
-      const store = name === '__proto__' ? defineOwn : assignOwn
-      return (ctx) => {
-        const value = right(ctx)
-        store(ctx, name, value)
-        return value
+      if (scope.params) {
+        throw new Error('Assignment is not supported in a lambda')
+      }
+      const right = compile(node.right!)
+      const { slots, frame } = scope.locals!
+      const slot = slots.get(node.left.value)!
+      return (ctx) => (frame.locals[slot] = right(ctx))
+    }
+
+    case 'Lambda': {
+      const body = compileNode(node.body, grammar, {
+        ...scope,
+        params: { names: node.params, outer: scope.params }
+      })
+      if (!scope.params) {
+        const frame = scope.locals?.frame
+        return (ctx): JexlFunction => {
+          const locals = frame?.locals
+          return (...args) =>
+            body(asContext(new LambdaFrame(args, undefined, ctx, locals)))
+        }
+      }
+      return (env): JexlFunction => {
+        const outer = asFrame(env)
+        return (...args) =>
+          body(
+            asContext(new LambdaFrame(args, outer, outer.context, outer.locals))
+          )
       }
     }