Rm

Author: cmdcolin

CHANGELOG.md

@@ -13,19 +13,24 @@ Nothing yet!
 - **Removed async evaluation support**: Jexl now only supports synchronous evaluation
 - **Renamed methods**: `evalSync()` has been renamed to `eval()`. The async `eval()` method has been removed.
 - **Removed PromiseSync class**: Internal implementation detail removed
-- **Synchronous transforms/functions only**: Custom transforms and functions must now be synchronous. They should return values directly rather than Promises.
+- **Removed transforms**: The transform/pipe operator (`|`) has been completely removed. Use functions instead.
+- **Removed array filtering**: Relative filter expressions (e.g., `array[.property == value]`) have been removed. Bracket notation for array/object access (e.g., `array[0]`, `object["key"]`) still works.
+- **Removed transform methods**: `addTransform()`, `addTransforms()`, and `getTransform()` have been removed.
 
 ### Changed
 
 - Simplified codebase by removing Promise/PromiseSync abstraction layer
 - All evaluation is now synchronous, improving performance and simplifying error handling
 - Errors are now thrown directly rather than being rejected Promises
+- Removed pipe operator (`|`) from grammar
+- Removed filter bracket syntax for relative filtering
 
 ### Migration Guide
 
 - Replace `await jexl.eval(expr)` with `jexl.eval(expr)` (remove await)
 - Replace `jexl.evalSync(expr)` with `jexl.eval(expr)` (remove Sync suffix)
-- Update custom transforms/functions to be synchronous
+- Replace transforms with functions: change `value|transform(arg)` to `transform(value, arg)`
+- Remove uses of relative filtering syntax `array[.prop == value]` (note: direct indexing like `array[0]` still works)
 - Replace `.catch()` error handling with `try/catch` blocks
 
 ## [v2.3.0]

README.md

@@ -2,6 +2,16 @@
 
 A fork of the jexl lang for jbrowse
 
+## What's New in v3.0
+
+Version 3.0 is a major simplification of Jexl with breaking changes:
+
+- **Synchronous only** - All evaluation is synchronous. No async/await needed.
+- **No transforms** - The pipe operator (`|`) has been removed. Use functions instead.
+- **No filter expressions** - Relative filter syntax like `array[.property == value]` has been removed. Regular bracket notation for indexing (`array[0]`, `object["key"]`) still works.
+
+See [CHANGELOG.md](CHANGELOG.md) for migration guide.
+
 ## Quick Examples
 
 ```javascript
@@ -22,10 +32,6 @@ jexl.eval('`Hello ${name.first} ${name.last}`', context)
 jexl.eval('`Age in 5 years: ${age + 5}`', context)
 // "Age in 5 years: 41"
 
-// Filter arrays
-jexl.eval('assoc[.first == "Lana"].last', context)
-// "Kane"
-
 // Math operations
 jexl.eval('age * (3 - 1)', context)
 // 72
@@ -109,45 +115,6 @@ jexl.eval('exes[2]', context) // "Burt"
 jexl.eval('exes[lastEx - 1]', context) // "Len"
 ```
 
-### Filtering Collections
-
-Filter arrays using expressions in brackets. Reference properties with a leading dot:
-
-```javascript
-const context = {
-  employees: [
-    { first: 'Sterling', last: 'Archer', age: 36 },
-    { first: 'Malory', last: 'Archer', age: 75 },
-    { first: 'Lana', last: 'Kane', age: 33 },
-    { first: 'Cyril', last: 'Figgis', age: 45 }
-  ]
-}
-
-jexl.eval('employees[.first == "Sterling"]', context)
-// [{ first: 'Sterling', last: 'Archer', age: 36 }]
-
-jexl.eval('employees[.age >= 30 && .age < 40]', context)
-// [{ first: 'Sterling', ... }, { first: 'Lana', ... }]
-
-jexl.eval('employees[.last == "Kane"].first', context)
-// "Lana"
-```
-
-### Transforms
-
-Apply transforms to values using the pipe operator:
-
-```javascript
-jexl.addTransform('upper', (val) => val.toUpperCase())
-jexl.addTransform('split', (val, char) => val.split(char))
-
-jexl.eval('"hello"|upper')
-// "HELLO"
-
-jexl.eval('"firstName lastName"|split(" ")[0]')
-// "firstName"
-```
-
 ### Functions
 
 Call functions in expressions:
@@ -195,7 +162,9 @@ jexl.eval('x = 5; y = x * 2; y', context)
 // context is now { x: 5, y: 10 }
 ```
 
-## Usage
+## API
+
+### Evaluation
 
 ```javascript
 import jexl from '@jbrowse/jexl'
@@ -208,6 +177,42 @@ const expr = jexl.compile('name.first + " " + name.last')
 const result = expr.eval({ name: { first: 'John', last: 'Doe' } })
 ```
 
+### Adding Custom Functions
+
+```javascript
+// Add a single function
+jexl.addFunction('round', Math.round)
+jexl.addFunction('lower', (str) => str.toLowerCase())
+
+// Add multiple functions
+jexl.addFunctions({
+  min: Math.min,
+  max: Math.max,
+  abs: Math.abs
+})
+
+// Use in expressions
+jexl.eval('round(3.7)') // 4
+jexl.eval('lower(name)', { name: 'HELLO' }) // "hello"
+jexl.eval('max(1, 5, 3)') // 5
+```
+
+### Adding Custom Operators
+
+```javascript
+// Add a binary operator
+jexl.addBinaryOp('~=', 20, (left, right) =>
+  left.toLowerCase() === right.toLowerCase()
+)
+
+jexl.eval('"Hello" ~= "hello"') // true
+
+// Add a unary operator
+jexl.addUnaryOp('~', (right) => Math.floor(right))
+
+jexl.eval('~3.7') // 3
+```
+
 ## License
 
 MIT License, same as TomFrost/Jexl

package.json

@@ -52,6 +52,7 @@
   "homepage": "https://github.com/TomFrost/jexl",
   "devDependencies": {
     "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
     "eslint": "^9.39.2",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-unicorn": "^62.0.0",

src/Jexl.ts

@@ -9,7 +9,6 @@ import { getGrammar } from './grammar.ts'
 interface Grammar {
   elements: Record<string, any>
   functions: Record<string, (...args: any[]) => any>
-  transforms: Record<string, (val: any, ...args: any[]) => any>
 }
 
 /**
@@ -96,28 +95,6 @@ class Jexl {
     })
   }
 
-  /**
-   * Adds or replaces a transform function in this Jexl instance.
-   * @param {string} name The name of the transform function, as it will be used
-   *      within Jexl expressions
-   * @param {function} fn The function to be executed when this transform is
-   *      invoked. It will be provided with at least one argument:
-   *          - {*} value: The value to be transformed
-   *          - {...*} args: The arguments for this transform
-   */
-  addTransform(name: string, fn: (val: any, ...args: any[]) => any) {
-    this._grammar.transforms[name] = fn
-  }
-
-  /**
-   * Syntactic sugar for calling {@link #addTransform} repeatedly.  This function
-   * accepts a map of one or more transform names to their transform function.
-   * @param {{}} map A map of transform names to transform functions
-   */
-  addTransforms(map: Record<string, (val: any, ...args: any[]) => any>) {
-    Object.assign(this._grammar.transforms, map)
-  }
-
   /**
    * Creates an Expression object from the given Jexl expression string, and
    * immediately compiles it. The returned Expression object can then be
@@ -150,15 +127,6 @@ class Jexl {
     return this._grammar.functions[name]
   }
 
-  /**
-   * Retrieves a previously set transform function.
-   * @param {string} name The name of the transform function
-   * @returns {function} The transform function
-   */
-  getTransform(name: string) {
-    return this._grammar.transforms[name]
-  }
-
   /**
    * Evaluates a Jexl string within an optional context.
    * @param {string} expression The Jexl expression to be evaluated

src/evaluator/Evaluator.ts

@@ -32,11 +32,7 @@ class Evaluator {
   _context: any
   _relContext: any
 
-  constructor(
-    grammar: Grammar,
-    context?: any,
-    relativeContext?: any
-  ) {
+  constructor(grammar: Grammar, context?: any, relativeContext?: any) {
     this._grammar = grammar
     this._context = context || {}
     this._relContext = relativeContext || this._context
@@ -74,59 +70,6 @@ class Evaluator {
     const vals = entries.map(([_, ast]) => this.eval(ast))
     return 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 {Array} an array of values that passed the expression filter.
-   * @private
-   */
-  _filterRelative(subject: any, expr: AstNode) {
-    const arr = Array.isArray(subject)
-      ? subject
-      : subject == null
-        ? []
-        : [subject]
-
-    return arr.filter((elem) =>
-      new Evaluator(this._grammar, this._context, elem).eval(expr)
-    )
-  }
-
-  /**
-   * 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 {*} the value of the drill-down.
-   * @private
-   */
-  _filterStatic(subject: any, expr: AstNode) {
-    const res = this.eval(expr)
-    if (typeof res === 'boolean') {
-      return res ? subject : undefined
-    }
-    return subject?.[res]
-  }
 }
 
 export default Evaluator

src/evaluator/handlers.ts

@@ -7,8 +7,7 @@ import type { AstNode } from '../types.ts'
 import type Evaluator from './Evaluator.ts'
 
 const poolNames: Record<string, string> = {
-  functions: 'Jexl Function',
-  transforms: 'Transform'
+  functions: 'Jexl Function'
 }
 
 /**
@@ -67,19 +66,21 @@ export function ConditionalExpression(this: Evaluator, ast: any) {
 }
 
 /**
- * Evaluates a FilterExpression by applying it to the subject value.
+ * Evaluates a FilterExpression by applying bracket notation for array/object access.
+ * Note: Relative filtering (with leading dot) is not supported.
  * @param {{type: 'FilterExpression', relative: <boolean>, expr: {},
  *      subject: {}}} ast An expression tree with a FilterExpression as the top
  *      node
- * @returns {*} the value of the FilterExpression.
+ * @returns {*} the value at the specified index/property.
  * @private
  */
 export function FilterExpression(this: Evaluator, ast: any) {
   const subject = this.eval(ast.subject)
   if (ast.relative) {
-    return this._filterRelative(subject, ast.expr)
+    throw new Error('Relative filter expressions are not supported')
   }
-  return this._filterStatic(subject, ast.expr)
+  const index = this.eval(ast.expr)
+  return subject?.[index]
 }
 
 /**

src/grammar.ts

@@ -27,7 +27,6 @@ export type GrammarElement = BinaryOp | UnaryOp | SimpleElement
 export interface Grammar {
   elements: Record<string, GrammarElement>
   functions: Record<string, (...args: any[]) => any>
-  transforms: Record<string, (val: any, ...args: any[]) => any>
 }
 
 export const getGrammar = (): Grammar => ({
@@ -40,7 +39,6 @@ export const getGrammar = (): Grammar => ({
     '.': { type: 'dot' },
     '[': { type: 'openBracket' },
     ']': { type: 'closeBracket' },
-    '|': { type: 'pipe' },
     '{': { type: 'openCurl' },
     '}': { type: 'closeCurl' },
     ':': { type: 'colon' },
@@ -119,7 +117,9 @@ export const getGrammar = (): Grammar => ({
       precedence: 10,
       evalOnDemand: (left, right) => {
         const leftVal = left.eval()
-        if (!leftVal) {return leftVal}
+        if (!leftVal) {
+          return leftVal
+        }
         return right.eval()
       }
     },
@@ -128,7 +128,9 @@ export const getGrammar = (): Grammar => ({
       precedence: 10,
       evalOnDemand: (left, right) => {
         const leftVal = left.eval()
-        if (leftVal) {return leftVal}
+        if (leftVal) {
+          return leftVal
+        }
         return right.eval()
       }
     },
@@ -173,22 +175,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: {},
-
-  /**
-   * A map of transform names to transform functions. A transform function
-   * takes one ore more arguemnts:
-   *
-   *     - {*} val: A value to be transformed
-   *     - {*} ...args: A variable number of arguments passed to this transform.
-   *       All of these are pre-evaluated to their actual values before calling
-   *       the function.
-   *
-   * The transform function should return the transformed value, or throw when
-   * an unrecoverable error occurs. Transforms should generally return undefined
-   * when they don't make sense to be used on the given value type, rather than
-   * throw. An error is only appropriate when the transform would normally
-   * return a value, but cannot due to some other failure.
-   */
-  transforms: {}
+  functions: {}
 })

src/types.ts

@@ -104,4 +104,7 @@ export type AstNodeUnion =
   | SequenceExpression
   | AssignmentExpression
 
-export type NodeByType<T extends AstNodeUnion['type']> = Extract<AstNodeUnion, { type: T }>
+export type NodeByType<T extends AstNodeUnion['type']> = Extract<
+  AstNodeUnion,
+  { type: T }
+>