@jbrowse/jexl 4.0.0 → 5.0.0

package/src/collections.ts

@@ -0,0 +1,148 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+import type { GrammarFn } from './grammar.ts'
+import type { JexlFunction, JexlValue } from './types.ts'
+
+/**
+ * A list as these functions read it. A lone value is a list of one and a
+ * missing one is empty, so that a field which is sometimes a scalar and
+ * sometimes an array, as VCF INFO fields are, needs no special case. A Set,
+ * a Map or a plain object, such as samples keyed by name, gives its values.
+ */
+function toList(value: JexlValue): JexlValue[] {
+  if (value == null) {
+    return []
+  }
+  if (Array.isArray(value)) {
+    return value
+  }
+  const held = value as unknown
+  if (held instanceof Set || held instanceof Map) {
+    return [...(held.values() as Iterable<JexlValue>)]
+  }
+  return isPlainObject(value) ? Object.values(value) : [value]
+}
+
+function isPlainObject(value: JexlValue): value is Record<string, JexlValue> {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+  const proto = Object.getPrototypeOf(value) as unknown
+  return proto === Object.prototype || proto === null
+}
+
+const identity = (value: JexlValue) => value
+
+function callback(name: string, fn: JexlValue): JexlFunction {
+  if (fn === undefined) {
+    return identity
+  }
+  if (typeof fn !== 'function') {
+    throw new TypeError(`${name}() expects a lambda, such as x => x > 1`)
+  }
+  return fn
+}
+
+/**
+ * The numbers a list holds, each read through `fn` when there is one. A
+ * boolean counts as 1 or 0, so `mean(samples, s => s.GQ > 90)` is the
+ * fraction that pass; anything else that is not a number is skipped, as
+ * bcftools skips a missing value.
+ */
+function numbers(name: string, list: JexlValue, fn: JexlValue) {
+  const read = callback(name, fn)
+  const out: number[] = []
+  for (const item of toList(list)) {
+    const value = read(item)
+    if (typeof value === 'number' && !Number.isNaN(value)) {
+      out.push(value)
+    } else if (typeof value === 'boolean') {
+      out.push(Number(value))
+    }
+  }
+  return out
+}
+
+/**
+ * The numbers `min` and `max` compare: a list and an optional lambda, as the
+ * other aggregates take, or any number of values and lists, as `Math.max`
+ * takes.
+ */
+function extremes(name: string, args: JexlValue[]) {
+  const last = args.at(-1)
+  if (typeof last !== 'function') {
+    return numbers(name, args.flatMap(toList), undefined)
+  }
+  if (args.length > 2) {
+    throw new TypeError(`${name}() takes a list and a lambda, or values`)
+  }
+  return numbers(name, args[0], last)
+}
+
+function sum(values: number[]) {
+  let total = 0
+  for (const value of values) {
+    total += value
+  }
+  return total
+}
+
+function ascending(a: JexlValue, b: JexlValue) {
+  return (a as number) < (b as number)
+    ? -1
+    : (a as number) > (b as number)
+      ? 1
+      : 0
+}
+
+/** The functions every Jexl instance starts with. A host may replace any. */
+export const collectionFunctions: Record<string, GrammarFn> = {
+  any: (list, fn) => toList(list).some(callback('any', fn)),
+  all: (list, fn) => toList(list).every(callback('all', fn)),
+  count: (list, fn) =>
+    fn === undefined
+      ? toList(list).length
+      : toList(list).filter(callback('count', fn)).length,
+  map: (list, fn) => toList(list).map(callback('map', fn)),
+  filter: (list, fn) => toList(list).filter(callback('filter', fn)),
+  find: (list, fn) => toList(list).find(callback('find', fn)),
+  sort: (list, fn) => {
+    const compare = fn === undefined ? ascending : callback('sort', fn)
+    return [...toList(list)].sort((a, b) => compare(a, b) as number)
+  },
+  sum: (list, fn) => sum(numbers('sum', list, fn)),
+  mean: (list, fn) => {
+    const values = numbers('mean', list, fn)
+    return values.length > 0 ? sum(values) / values.length : undefined
+  },
+  median: (list, fn) => {
+    const values = numbers('median', list, fn).sort((a, b) => a - b)
+    const mid = values.length >> 1
+    return values.length === 0
+      ? undefined
+      : values.length % 2
+        ? values[mid]
+        : (values[mid - 1]! + values[mid]!) / 2
+  },
+  min: (...args) => {
+    const values = extremes('min', args)
+    return values.length > 0 ? Math.min(...values) : undefined
+  },
+  max: (...args) => {
+    const values = extremes('max', args)
+    return values.length > 0 ? Math.max(...values) : undefined
+  },
+  reduce: (list, fn, ...initial) => {
+    const items = toList(list)
+    const step = callback('reduce', fn)
+    const seeded = initial.length > 0
+    let acc = seeded ? initial[0] : items[0]
+    for (let i = seeded ? 0 : 1; i < items.length; i++) {
+      acc = step(acc, items[i])
+    }
+    return acc
+  }
+}

package/src/conditions.ts

@@ -0,0 +1,262 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+import { analyze } from './analyze.ts'
+import { print } from './check.ts'
+
+import type { PathKey } from './analyze.ts'
+import type { AstNode, AstNodeUnion } from './types.ts'
+
+export type Scalar = string | number | boolean | null
+
+/**
+ * What a condition tests: a path off the row (`feature.INFO.DP`, or
+ * `get(feature, 'score')` through an accessor), or a host function of the row
+ * such as `maf(feature)` or `genotypeCount(feature, 'het')`.
+ */
+export type Subject =
+  | { kind: 'path'; path: PathKey[]; node: AstNode }
+  | { kind: 'call'; name: string; args: Scalar[]; node: AstNode }
+
+export type Condition =
+  | {
+      subject: Subject
+      op: '==' | '!=' | '<' | '<=' | '>' | '>='
+      value: Scalar
+    }
+  | { subject: Subject; op: '~' | '!~'; value: string }
+  | { subject: Subject; op: 'in' | '!in'; value: Scalar[] }
+  | { subject: Subject; op: 'has' | '!has'; value: string }
+  | { subject: Subject; op: 'set' | '!set' }
+
+export interface ConditionOptions {
+  /** The variable holding the record, e.g. `feature`. */
+  row: string
+  /** Functions that read a path off the row, as {@link analyze} takes them. */
+  accessors?: Record<string, readonly PathKey[]>
+  /** Host functions of the row, e.g. `maf`, that a condition may test. */
+  calls?: readonly string[]
+}
+
+const COMPARE = new Set(['==', '!=', '<', '<=', '>', '>='])
+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('') }
+    : undefined
+}
+
+function isRow(ast: AstNode | undefined, row: string) {
+  const node = ast as AstNodeUnion | undefined
+  return node?.type === 'Identifier' && !node.from && node.value === row
+}
+
+function subjectOf(ast: AstNode, opts: ConditionOptions): Subject | undefined {
+  const node = ast as AstNodeUnion
+  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 accessor =
+    node.type === 'FunctionCall' &&
+    Object.hasOwn(opts.accessors ?? {}, node.name)
+  if (
+    node.type !== 'Identifier' &&
+    node.type !== 'FilterExpression' &&
+    !accessor
+  ) {
+    return undefined
+  }
+  const read = analyze(node, { row: opts.row, accessors: opts.accessors })
+  const [first] = read.reads
+  const literalAccess =
+    accessor &&
+    read.reads.length === 1 &&
+    read.calls.length === 1 &&
+    read.calls[0]!.args.slice(1).every((arg) => arg.type === 'literal')
+  return (read.bare || literalAccess) &&
+    first?.root === opts.row &&
+    !first.dynamic &&
+    first.path.length > 0
+    ? { kind: 'path', path: first.path, node }
+    : undefined
+}
+
+function condition(
+  ast: AstNode,
+  opts: ConditionOptions
+): Condition | undefined {
+  const node = ast as AstNodeUnion
+  if (node.type === 'UnaryExpression' && node.operator === '!') {
+    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'
+      ? ({ ...inner, op: `!${inner.op}` } as Condition)
+      : undefined
+  }
+  if (node.type !== 'BinaryExpression') {
+    const subject = subjectOf(node, opts)
+    return subject && { subject, op: 'set' }
+  }
+  const { operator, left } = node
+  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 flipped = subjectOf(right, opts)
+    const leftValue = scalar(left)
+    return flipped && leftValue
+      ? {
+          subject: flipped,
+          op: FLIP[operator] as '==',
+          value: leftValue.value
+        }
+      : 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 }
+      : 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
+    }
+    const key = scalar(left)
+    const container = subjectOf(right, opts)
+    return container && typeof key?.value === 'string'
+      ? { subject: container, op: 'has', value: key.value }
+      : undefined
+  }
+  return undefined
+}
+
+/**
+ * Reads an expression as conditions all of which must hold — `a && b && …`,
+ * each comparing a field of the row with a literal — or answers undefined when
+ * any part is something else. A filter editor shows the conditions as rows and
+ * keeps anything undefined as text, so a line it cannot read is never
+ * misread.
+ */
+export function conditions(
+  ast: 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)
+    return left && right && [...left, ...right]
+  }
+  const found = condition(node, opts)
+  return found && [found]
+}
+
+const literal = (value: Scalar) =>
+  print({ type: 'Literal', value } as AstNodeUnion)
+
+/** 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
+  for (const key of path) {
+    node =
+      typeof key === 'string'
+        ? ({ type: 'Identifier', value: key, from: node } as AstNodeUnion)
+        : ({
+            type: 'FilterExpression',
+            subject: node,
+            expr: { type: 'Literal', value: key }
+          } as AstNodeUnion)
+  }
+  return { kind: 'path', path, node }
+}
+
+/** A subject calling a host function of the row, such as `maf(feature)`. */
+export function callSubject(
+  row: string,
+  name: string,
+  args: Scalar[] = []
+): Subject {
+  const node = {
+    type: 'FunctionCall',
+    name,
+    args: [
+      { type: 'Identifier', value: row },
+      ...args.map((value) => ({ type: 'Literal', value }))
+    ]
+  } as AstNodeUnion
+  return { kind: 'call', name, args, node }
+}
+
+/** Writes one condition as expression text that {@link conditions} reads back. */
+export function printCondition(c: Condition) {
+  const subject = print(c.subject.node)
+  switch (c.op) {
+    case 'set': {
+      return subject
+    }
+    case '!set': {
+      return `!${subject}`
+    }
+    case 'has': {
+      return `${literal(c.value)} in ${subject}`
+    }
+    case '!has': {
+      return `!(${literal(c.value)} in ${subject})`
+    }
+    case 'in': {
+      return `${subject} in [${c.value.map(literal).join(', ')}]`
+    }
+    case '!in': {
+      return `!(${subject} in [${c.value.map(literal).join(', ')}])`
+    }
+    default: {
+      return `${subject} ${c.op} ${literal(c.value)}`
+    }
+  }
+}
+
+/** Writes conditions as one expression requiring all of them. */
+export function fromConditions(list: readonly Condition[]) {
+  return list.map(printCondition).join(' && ')
+}

package/src/errors.ts

@@ -0,0 +1,15 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+/** A malformed expression. `offset` is where in the source it went wrong. */
+export class JexlSyntaxError extends Error {
+  offset: number
+
+  constructor(message: string, offset: number) {
+    super(message)
+    this.name = 'JexlSyntaxError'
+    this.offset = offset
+  }
+}