@jbrowse/jexl 5.0.1 → 6.0.0

package/src/check.ts

@@ -3,15 +3,18 @@
  * Copyright 2020 Tom Shawver
  */
 
+import { literalValue } from './analyze.ts'
+import { unknownNode } from './errors.ts'
+import { toRegExp } from './operators.ts'
+import { isName, key, print, quote } from './print.ts'
+
 import type { AnalyzeOptions } from './analyze.ts'
 import type {
   AstNode,
-  AstNodeUnion,
   BinaryExpression,
   FunctionCall,
   Identifier,
-  Lambda,
-  Literal
+  Lambda
 } from './types.ts'
 
 /**
@@ -148,8 +151,6 @@ export interface CheckResult {
   type: Type
 }
 
-type Node = AstNodeUnion
-
 export const UNKNOWN: Type = { kind: 'unknown' }
 const UNDEFINED: Type = { kind: 'undefined' }
 const BOOLEAN: Type = { kind: 'boolean' }
@@ -160,203 +161,6 @@ const MAX_VALUES = 64
 const ARITHMETIC = new Set(['-', '*', '/', '//', '%', '^'])
 const ORDER = new Set(['<', '<=', '>', '>='])
 const EQUALITY = new Set(['==', '!='])
-const PRECEDENCE: Record<string, number> = {
-  '=': 2,
-  '||': 10,
-  '??': 10,
-  '&&': 11,
-  '==': 20,
-  '!=': 20,
-  '~': 20,
-  '!~': 20,
-  '<': 20,
-  '<=': 20,
-  '>': 20,
-  '>=': 20,
-  in: 20,
-  '+': 30,
-  '-': 30,
-  '*': 40,
-  '/': 40,
-  '//': 40,
-  '%': 50,
-  '^': 50
-}
-
-const RIGHT_ASSOCIATIVE = new Set(['^'])
-const LOGICAL = new Set(['||', '&&'])
-
-// how tightly each form binds, mirroring the Parser's levels: `;`, then `=`
-// and lambdas, then `?:`, then binary operators, then prefix operators
-const SEQUENCE = 0
-const ASSIGNMENT = 1
-const CONDITIONAL = 2
-const CUSTOM_BINARY = 3
-const UNARY = 100
-
-const letter = String.raw`a-zA-Zа-яА-Я_À-ÖØ-öø-ÿ$`
-const IDENTIFIER = new RegExp(`^[${letter}][${letter}0-9]*$`)
-const WORDS = new Set(['in', 'true', 'false', 'null'])
-
-function isName(text: string) {
-  return IDENTIFIER.test(text) && !WORDS.has(text)
-}
-
-function key(name: string) {
-  return isName(name) ? `.${name}` : `[${quote(name)}]`
-}
-
-function quote(text: string) {
-  return `'${text.replaceAll('\\', '\\\\').replaceAll("'", String.raw`\'`)}'`
-}
-
-function precedenceOf(node: Node) {
-  switch (node.type) {
-    case 'SequenceExpression': {
-      return SEQUENCE
-    }
-    case 'AssignmentExpression':
-    case 'Lambda': {
-      return ASSIGNMENT
-    }
-    case 'ConditionalExpression': {
-      // with no alternate, it ends only before `)`, `]`, `}`, `,`, `;` or the end
-      return node.alternate ? CONDITIONAL : SEQUENCE
-    }
-    case 'BinaryExpression': {
-      return PRECEDENCE[node.operator] ?? CUSTOM_BINARY
-    }
-    case 'UnaryExpression': {
-      return UNARY
-    }
-    default: {
-      return Infinity
-    }
-  }
-}
-
-function within(ast: AstNode, least: number) {
-  const text = print(ast)
-  return precedenceOf(ast as Node) < least ? `(${text})` : text
-}
-
-function binaryOperand(parent: BinaryExpression, ast: AstNode, left: boolean) {
-  const own = PRECEDENCE[parent.operator]
-  if (own === undefined) {
-    return within(ast, UNARY)
-  }
-  const child = ast as Node
-  const theirs = precedenceOf(child)
-  const chained =
-    child.type === 'BinaryExpression' &&
-    RIGHT_ASSOCIATIVE.has(parent.operator) &&
-    RIGHT_ASSOCIATIVE.has(child.operator)
-  const mixesNullish =
-    child.type === 'BinaryExpression' &&
-    ((parent.operator === '??' && LOGICAL.has(child.operator)) ||
-      (child.operator === '??' && LOGICAL.has(parent.operator)))
-  const text = print(ast)
-  return theirs < own || (theirs === own && left === chained) || mixesNullish
-    ? `(${text})`
-    : text
-}
-
-/**
- * Renders a tree back to expression text, for messages and suggestions. The
- * text parses back to the same tree.
- */
-export function print(ast: AstNode): string {
-  const node = ast as Node
-  switch (node.type) {
-    case 'Literal': {
-      const { value } = node
-      return typeof value === 'string'
-        ? quote(value)
-        : Object.is(value, -0)
-          ? '-0'
-          : String(value)
-    }
-    case 'Identifier': {
-      return node.from
-        ? within(node.from, Infinity) + key(node.value)
-        : node.value
-    }
-    case 'FilterExpression': {
-      return `${within(node.subject, Infinity)}[${within(node.expr, ASSIGNMENT)}]`
-    }
-    case 'BinaryExpression': {
-      return `${binaryOperand(node, node.left, true)} ${node.operator} ${binaryOperand(node, node.right!, false)}`
-    }
-    case 'UnaryExpression': {
-      const { operator } = node
-      const right = within(node.right!, UNARY)
-      // the Lexer folds a minus before a digit into the number
-      if (operator === '-' && /^\d/.test(right)) {
-        return `-(${right})`
-      }
-      return IDENTIFIER.test(operator)
-        ? `${operator} ${right}`
-        : operator + right
-    }
-    case 'ConditionalExpression': {
-      const test = within(node.test, CUSTOM_BINARY)
-      const consequent = node.consequent
-        ? ` ${within(node.consequent, ASSIGNMENT)} `
-        : ''
-      const alternate = node.alternate
-        ? ` ${within(node.alternate, ASSIGNMENT)}`
-        : ''
-      return `${test} ?${consequent}:${alternate}`
-    }
-    case 'FunctionCall': {
-      const args = node.args.map((arg) => within(arg, ASSIGNMENT))
-      return `${node.name}(${args.join(', ')})`
-    }
-    case 'ArrayLiteral': {
-      const items = node.value.map((item) => within(item, ASSIGNMENT))
-      return `[${items.join(', ')}]`
-    }
-    case 'ObjectLiteral': {
-      const entries = Object.entries(node.value).map(
-        ([name, value]) =>
-          `${isName(name) ? name : quote(name)}: ${within(value, ASSIGNMENT)}`
-      )
-      return `{${entries.join(', ')}}`
-    }
-    case 'TemplateLiteral': {
-      const parts = node.parts.map((part) =>
-        part.type === 'static'
-          ? part.value
-              .replaceAll('\\', '\\\\')
-              .replaceAll('`', '\\`')
-              .replaceAll('${', '\\${')
-          : `\${${print(part.value)}}`
-      )
-      return `\`${parts.join('')}\``
-    }
-    case 'SequenceExpression': {
-      const { expressions } = node
-      const text = expressions
-        .map((expr) => within(expr, ASSIGNMENT))
-        .join('; ')
-      return expressions.length === 1 ? `${text};` : text
-    }
-    case 'AssignmentExpression': {
-      return `${node.left.value} = ${within(node.right!, ASSIGNMENT)}`
-    }
-    case 'Lambda': {
-      const params =
-        node.params.length === 1
-          ? node.params[0]
-          : `(${node.params.join(', ')})`
-      return `${params} => ${within(node.body, ASSIGNMENT)}`
-    }
-    default: {
-      return '?'
-    }
-  }
-}
-
 function distance(a: string, b: string) {
   let before: number[] = []
   let previous = Array.from({ length: b.length + 1 }, (_, i) => i)
@@ -487,7 +291,7 @@ function isBoxed(type: Type): type is OfKind<'list'> {
 
 function isPattern(pattern: string) {
   try {
-    new RegExp(pattern.startsWith('(?i)') ? pattern.slice(4) : pattern)
+    toRegExp(pattern)
     return true
   } catch {
     return false
@@ -775,10 +579,9 @@ function negate(type: Type): Type {
 }
 
 function paramName(subject: AstNode, context: AstNode) {
-  const node = subject as Node
   const base =
-    node.type === 'Identifier'
-      ? node.value.toLowerCase().replaceAll(/\W/g, '')
+    subject.type === 'Identifier'
+      ? subject.value.toLowerCase().replaceAll(/\W/g, '')
       : ''
   const name = isName(base) ? base : 'x'
   const text = print(context)
@@ -789,10 +592,6 @@ function paramName(subject: AstNode, context: AstNode) {
   return candidate
 }
 
-function literalValue(node: AstNode) {
-  return node.type === 'Literal' ? (node as Literal).value : undefined
-}
-
 function describe(type: Type): string {
   switch (type.kind) {
     case 'list': {
@@ -1032,27 +831,20 @@ export function check(
     }
   }
 
-  function chain(node: Identifier): { base: AstNode; names: string[] } {
+  function dottedKey(node: Identifier): Type | undefined {
     const names = [node.value]
-    let base: AstNode = node
-    while (base.type === 'Identifier' && (base as Identifier).from) {
-      base = (base as Identifier).from!
-      if (base.type === 'Identifier') {
-        names.unshift((base as Identifier).value)
+    let base = node
+    while (base.from) {
+      if (base.from.type !== 'Identifier') {
+        return undefined
       }
+      base = base.from
+      names.unshift(base.value)
     }
-    return { base, names }
-  }
-
-  function dottedKey(node: Identifier): Type | undefined {
-    if (!node.from) {
-      return undefined
-    }
-    const { base, names } = chain(node)
-    if ((base as Identifier).from) {
+    if (base === node) {
       return undefined
     }
-    let type = variable(base as Identifier, false)
+    let type = variable(base, false)
     let subjectNode: AstNode = base
     for (let i = 1; i < names.length; i++) {
       const record = type.kind === 'record' ? type : undefined
@@ -1090,7 +882,7 @@ export function check(
         type: 'Identifier',
         value: names[i]!,
         from: subjectNode
-      } as Identifier
+      }
     }
     return undefined
   }
@@ -1134,34 +926,45 @@ export function check(
     return UNKNOWN
   }
 
-  function hyphenated(node: AstNodeUnion): Type | undefined {
+  function hyphenated(node: AstNode): Type | undefined {
     if (
       node.type !== 'BinaryExpression' ||
       node.operator !== '-' ||
       node.left.type !== 'Identifier' ||
-      node.right?.type !== 'Identifier' ||
-      (node.right as Identifier).from
+      node.right.type !== 'Identifier' ||
+      node.right.from
+    ) {
+      return undefined
+    }
+    const left = node.left
+    const name = left.value
+    if (
+      !left.from &&
+      (scope.has(name) || name === row || (env && Object.hasOwn(env, name)))
     ) {
       return undefined
     }
-    const left = node.left as Identifier
     const reported = diagnostics.length
     const subject = left.from ? infer(left.from) : root
     diagnostics.length = reported
-    if (subject.kind !== 'record' || subject.fields.has(left.value)) {
+    if (subject.kind !== 'record' || subject.fields.has(name)) {
       return undefined
     }
-    const whole = `${left.value}-${(node.right as Identifier).value}`
+    const whole = `${name}-${node.right.value}`
     const found = subject.fields.get(whole)
     if (!found) {
       return undefined
     }
+    // a bare name can't hold a hyphen, so only a row variable can spell it
+    const holder: AstNode | undefined =
+      left.from ??
+      (row === undefined ? undefined : { type: 'Identifier', value: row })
     report(
       'unknown-field',
       'warning',
       node,
       `${print(node)} subtracts; ${whole} is one field`,
-      [text(left.from, whole)]
+      holder ? [text(holder, whole)] : []
     )
     return found
   }
@@ -1244,11 +1047,9 @@ export function check(
     }
   }
 
-  function binary(
-    node: Extract<AstNodeUnion, { type: 'BinaryExpression' }>
-  ): Type {
+  function binary(node: BinaryExpression): Type {
     const { operator } = node
-    const rightNode = node.right!
+    const rightNode = node.right
     if (operator === '&&' || operator === '||' || operator === '??') {
       const left = infer(node.left)
       const right = infer(rightNode)
@@ -1343,7 +1144,7 @@ export function check(
     if (EQUALITY.has(operator)) {
       const leftLiteral = literalOf(leftItem)
       const rightLiteral = literalOf(rightItem)
-      if (rightLiteral !== undefined && node.right?.type === 'Literal') {
+      if (rightLiteral !== undefined && node.right.type === 'Literal') {
         compareLiteral(leftItem, rightLiteral, node)
       } else if (leftLiteral !== undefined && node.left.type === 'Literal') {
         compareLiteral(rightItem, leftLiteral, node)
@@ -1430,7 +1231,7 @@ export function check(
           type: 'Identifier',
           value: name,
           from: subjectNode
-        } as Identifier
+        }
       }
       for (const name of prefix) {
         step(String(name), node)
@@ -1457,9 +1258,7 @@ export function check(
           node,
           `no function ${name}` +
             (near.length ? `; did you mean ${near.join(', ')}?` : ''),
-          near.map((candidate) =>
-            print({ ...node, name: candidate } as FunctionCall)
-          )
+          near.map((candidate) => print({ ...node, name: candidate }))
         )
       }
       return UNKNOWN
@@ -1486,10 +1285,10 @@ export function check(
       }
       const accepted: readonly ParamType[] =
         typeof declared === 'string' ? [declared] : declared
-      if ((arg as Node).type === 'Lambda') {
+      if (arg.type === 'Lambda') {
         const item =
           lastCollection?.kind === 'list' ? lastCollection.of : UNKNOWN
-        types.push(lambda(arg as Lambda, lambdaParams(name, item)))
+        types.push(lambda(arg, lambdaParams(name, item)))
         continue
       }
       const type = infer(arg)
@@ -1537,8 +1336,7 @@ export function check(
     return returns ?? UNKNOWN
   }
 
-  function infer(ast: AstNode): Type {
-    const node = ast as Node
+  function infer(node: AstNode): Type {
     switch (node.type) {
       case 'Literal': {
         const { value } = node
@@ -1599,7 +1397,7 @@ export function check(
         return binary(node)
       }
       case 'UnaryExpression': {
-        const right = infer(node.right!)
+        const right = infer(node.right)
         if (node.operator === '!') {
           return BOOLEAN
         }
@@ -1664,7 +1462,7 @@ export function check(
         return last
       }
       case 'AssignmentExpression': {
-        const value = infer(node.right!)
+        const value = infer(node.right)
         scope.set(node.left.value, value)
         return value
       }
@@ -1672,7 +1470,7 @@ export function check(
         return lambda(node)
       }
       default: {
-        throw new Error(`Corrupt AST: unknown node type '${ast.type}'`)
+        return unknownNode(node)
       }
     }
   }

package/src/collections.ts

@@ -34,13 +34,23 @@ function isPlainObject(value: JexlValue): value is Record<string, JexlValue> {
   return proto === Object.prototype || proto === null
 }
 
+/**
+ * Marks the functions lambdas evaluate to. A collection function calls only
+ * these, never a function an expression reads, since reads reach host
+ * functions: `reduce(['x', body], ''.constructor.constructor)` built a
+ * function from `body`, and `map` then ran it.
+ */
+export const LAMBDA = Symbol('lambda')
+
+type Lambda = JexlFunction & { [LAMBDA]?: true }
+
 const identity = (value: JexlValue) => value
 
 function callback(name: string, fn: JexlValue): JexlFunction {
   if (fn === undefined) {
     return identity
   }
-  if (typeof fn !== 'function') {
+  if (typeof fn !== 'function' || !(fn as Lambda)[LAMBDA]) {
     throw new TypeError(`${name}() expects a lambda, such as x => x > 1`)
   }
   return fn

package/src/conditions.ts

@@ -3,11 +3,11 @@
  * Copyright 2020 Tom Shawver
  */
 
-import { analyze } from './analyze.ts'
-import { print } from './check.ts'
+import { analyze, literalValue } from './analyze.ts'
+import { print } from './print.ts'
 
 import type { PathKey } from './analyze.ts'
-import type { AstNode, AstNodeUnion } from './types.ts'
+import type { AstNode } from './types.ts'
 
 export type Scalar = string | number | boolean | null
 
@@ -50,38 +50,25 @@ const FLIP: Record<string, Condition['op']> = {
   '>=': '<='
 }
 
-function scalar(ast: AstNode): { value: Scalar } | undefined {
-  const node = ast as AstNodeUnion
-  if (node.type === 'Literal') {
-    return { value: node.value }
-  }
-  return node.type === 'TemplateLiteral' &&
-    node.parts.every((part) => part.type === 'static')
-    ? { value: node.parts.map((part) => part.value).join('') }
+function scalars(nodes: AstNode[]) {
+  const values = nodes.map(literalValue)
+  return values.every((value): value is Scalar => value !== undefined)
+    ? values
     : undefined
 }
 
-function isRow(ast: AstNode | undefined, row: string) {
-  const node = ast as AstNodeUnion | undefined
+function isRow(node: AstNode | undefined, row: string) {
   return node?.type === 'Identifier' && !node.from && node.value === row
 }
 
-function subjectOf(ast: AstNode, opts: ConditionOptions): Subject | undefined {
-  const node = ast as AstNodeUnion
+function subjectOf(node: AstNode, opts: ConditionOptions): Subject | undefined {
   if (
     node.type === 'FunctionCall' &&
     opts.calls?.includes(node.name) &&
     isRow(node.args[0], opts.row)
   ) {
-    const rest = node.args.slice(1).map(scalar)
-    return rest.every(Boolean)
-      ? {
-          kind: 'call',
-          name: node.name,
-          args: rest.map((arg) => arg!.value),
-          node
-        }
-      : undefined
+    const args = scalars(node.args.slice(1))
+    return args && { kind: 'call', name: node.name, args, node }
   }
   const accessor =
     node.type === 'FunctionCall' &&
@@ -109,12 +96,11 @@ function subjectOf(ast: AstNode, opts: ConditionOptions): Subject | undefined {
 }
 
 function condition(
-  ast: AstNode,
+  node: AstNode,
   opts: ConditionOptions
 ): Condition | undefined {
-  const node = ast as AstNodeUnion
   if (node.type === 'UnaryExpression' && node.operator === '!') {
-    const inner = condition(node.right!, opts)
+    const inner = condition(node.right, opts)
     // only forms whose negation reads as a condition of its own; `!(QUAL > 30)`
     // holds where QUAL is missing, which `QUAL <= 30` does not
     return inner?.op === 'in' || inner?.op === 'has' || inner?.op === 'set'
@@ -126,43 +112,36 @@ function condition(
     return subject && { subject, op: 'set' }
   }
   const { operator, left } = node
-  const right = node.right!
+  const right = node.right
   if (COMPARE.has(operator)) {
     const subject = subjectOf(left, opts)
-    const value = scalar(right)
-    if (subject && value) {
-      return { subject, op: operator as '==', value: value.value }
+    const value = literalValue(right)
+    if (subject && value !== undefined) {
+      return { subject, op: operator as '==', value }
     }
     const flipped = subjectOf(right, opts)
-    const leftValue = scalar(left)
-    return flipped && leftValue
-      ? {
-          subject: flipped,
-          op: FLIP[operator] as '==',
-          value: leftValue.value
-        }
+    const leftValue = literalValue(left)
+    return flipped && leftValue !== undefined
+      ? { subject: flipped, op: FLIP[operator] as '==', value: leftValue }
       : undefined
   }
   if (operator === '~' || operator === '!~') {
     const subject = subjectOf(left, opts)
-    const value = scalar(right)
-    return subject && typeof value?.value === 'string'
-      ? { subject, op: operator, value: value.value }
+    const value = literalValue(right)
+    return subject && typeof value === 'string'
+      ? { subject, op: operator, value }
       : undefined
   }
   if (operator === 'in') {
     const subject = subjectOf(left, opts)
-    const list = right as AstNodeUnion
-    if (subject && list.type === 'ArrayLiteral') {
-      const values = list.value.map(scalar)
-      return values.length > 0 && values.every(Boolean)
-        ? { subject, op: 'in', value: values.map((value) => value!.value) }
-        : undefined
+    if (subject && right.type === 'ArrayLiteral') {
+      const values = scalars(right.value)
+      return values?.length ? { subject, op: 'in', value: values } : undefined
     }
-    const key = scalar(left)
+    const key = literalValue(left)
     const container = subjectOf(right, opts)
-    return container && typeof key?.value === 'string'
-      ? { subject: container, op: 'has', value: key.value }
+    return container && typeof key === 'string'
+      ? { subject: container, op: 'has', value: key }
       : undefined
   }
   return undefined
@@ -176,37 +155,35 @@ function condition(
  * misread.
  */
 export function conditions(
-  ast: AstNode | null,
+  node: AstNode | null,
   opts: ConditionOptions
 ): Condition[] | undefined {
-  const node = ast as AstNodeUnion | null
   if (!node) {
     return undefined
   }
   if (node.type === 'BinaryExpression' && node.operator === '&&') {
     const left = conditions(node.left, opts)
-    const right = left && conditions(node.right!, opts)
+    const right = left && conditions(node.right, opts)
     return left && right && [...left, ...right]
   }
   const found = condition(node, opts)
   return found && [found]
 }
 
-const literal = (value: Scalar) =>
-  print({ type: 'Literal', value } as AstNodeUnion)
+const literal = (value: Scalar) => print({ type: 'Literal', value })
 
 /** A subject reading `path` off the row, for a condition built from a picker. */
 export function pathSubject(row: string, path: PathKey[]): Subject {
-  let node: AstNode = { type: 'Identifier', value: row } as AstNodeUnion
+  let node: AstNode = { type: 'Identifier', value: row }
   for (const key of path) {
     node =
       typeof key === 'string'
-        ? ({ type: 'Identifier', value: key, from: node } as AstNodeUnion)
-        : ({
+        ? { type: 'Identifier', value: key, from: node }
+        : {
             type: 'FilterExpression',
             subject: node,
             expr: { type: 'Literal', value: key }
-          } as AstNodeUnion)
+          }
   }
   return { kind: 'path', path, node }
 }
@@ -217,14 +194,14 @@ export function callSubject(
   name: string,
   args: Scalar[] = []
 ): Subject {
-  const node = {
+  const node: AstNode = {
     type: 'FunctionCall',
     name,
     args: [
       { type: 'Identifier', value: row },
-      ...args.map((value) => ({ type: 'Literal', value }))
+      ...args.map((value): AstNode => ({ type: 'Literal', value }))
     ]
-  } as AstNodeUnion
+  }
   return { kind: 'call', name, args, node }
 }
 

package/src/errors.ts

@@ -13,3 +13,13 @@ export class JexlSyntaxError extends Error {
     this.offset = offset
   }
 }
+
+/**
+ * Throws for a node no case of a walk handled. Typing it `never` makes a new
+ * node type a compile error in every walk that doesn't handle it yet.
+ */
+export function unknownNode(node: never): never {
+  throw new Error(
+    `Corrupt AST: unknown node type '${(node as { type: string }).type}'`
+  )
+}