@jbrowse/jexl 2.3.1

package/CHANGELOG.md

@@ -0,0 +1,222 @@
+# Jexl Change Log
+
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [development]
+
+Nothing yet!
+
+## [v2.3.0]
+
+### Added
+
+- Top-level expression functions, along with `jexl.addFunction` and
+  `jexl.addFunctions`. (#25)
+- Binary operators can now be set to evaluate their operands manually, allowing
+  them to decide if and when to resolve the value of the left or right sides.
+  See the new `manualEval` option in `jexl.addBinaryOp`.
+- Support for Latin 1 Suppliment characters in identifiers (#68) (@heharkon)
+- Support for Russian chatacters in identifiers (#90) (@a-gorbunov)
+- ES5 build for browser support (#87) (@czosel)
+
+### Fixed
+
+- The binary operators `&&` and `||` now evaluate the right operand
+  conditionally, depending on the value of the left.
+
+## [v2.2.2]
+
+### Changes
+
+- Jexl now officially supports Node v12. It's been working, but now CI tests it!
+
+### Fixed
+
+- Accessing children of null should resolve to undefined rather than throwing
+  (#64)
+
+## [v2.2.1]
+
+### Fixed
+
+- Relative collection filters didn't function appropriately when evalSync was
+  used, as it would sometimes revert to using an actual Promise object.
+  (#61)
+
+## [v2.2.0]
+
+### Added
+
+- Introducing the `Expression` object, which allows expressions to be compiled
+  only once and evaluated many times
+- Get an Expression by calling `jexl.createExpression('2 + 2')`
+- Get a pre-compiled expression by calling `jexl.compile('2 + 2')`
+- Evaluate Expressions asyncronoushly or synchronously by calling
+  `myExpression.eval(context)` or `myExpression.evalSync(context)`
+- Create expressions using a convenient tagged template: `` jexl.expr`2 + 2` ``
+
+### Fixed
+
+- Transform errors did not always get thrown when using `evalSync` (#55, #56)
+  (@bitghostm)
+- Arbitrary whitespace is now re-supported (#54) (@czosel)
+- Strings were not tokenized correctly when ending with an escaped quote (#51)
+  (@rehandalal)
+- Identifier names can now start with `$` (#36) (@glromeo)
+
+## [v2.1.1]
+
+### Fixed
+
+- Applying a filter to an undefined identifier now returns an empty array
+  instead of an array with one undefined element.
+
+## [v2.1.0]
+
+### Added
+
+- Jexl now has synchronous evaluation! Just call `evalSync`.
+
+## [v2.0.2]
+
+### Fixed
+
+- Issue #47: Revert unintentional change to strict === and !== comparisons
+
+## [v2.0.1]
+
+### Fixed
+
+- Issue where Jexl might mistake an identifier as being relative to a parent
+  when it should refer to the top level of the context in one specific case
+
+## [v2.0.0]
+
+### Changed
+
+- The pre-minified Jexl has been removed; in modern times, frontend
+  webapps have their own build stack, and Jexl should't make assumptions
+  about the module format a frontend app wants to use.
+- Support for Node 4 and earlier has been dropped.
+- The codebase has been modernized to the subset of ES6 supported in
+  Node 6 LTS and beyond. Tests require Node 8 or later.
+- The codebase has been shifted to Standard JS style.
+- jexl.eval no longer accepts a callback function. Jexl is now promises-only.
+- Tests have been converted to Jest to eliminate sneaky error swallowing
+
+## [v1.1.4]
+
+### Fixed
+
+- Falsey identifiers are no longer treated as undefined
+
+## [v1.1.3]
+
+### Fixed
+
+- Binary operators after nested identifiers were not balanced properly,
+  resulting in a broken expression/AST
+- Gulp (or one of its plugins) had a breaking change in a minor release,
+  preventing the frontend build from running. This build method will be
+  removed from the next major version of Jexl. For now, Jexl is now version-
+  locked to the original gulp+plugins that worked.
+
+## [v1.1.2]
+
+### Changed
+
+- Code coverage thresholds are now enforced through `gulp coverage-test`
+
+### Fixed
+
+- Operators found in identifier names (such as 'in' in 'incident') were being
+  tokenized separately from the rest of the identifier
+
+## [v1.1.1]
+
+### Fixed
+
+- Minus did not denote a negative number at the start of a ternary's consequent
+  section
+
+## [v1.1.0]
+
+### Added
+
+- The ability to define new binary and unary operators, or override existing
+  ones.
+- The ability to delete existing binary and unary operators.
+
+## [v1.0.2]
+
+### Fixed
+
+- Bad Gulpfile resulted in frontend dist falling out of sync. Fixed and
+  re-synced.
+
+## [v1.0.1]
+
+### Changed
+
+- Refactored Parser and Evaluator. Both operations are now marginally faster.
+- Removed balance tracking in favor of passing maps of token types at which
+  the sub-parser should stop.
+
+### Fixed
+
+- Object literals could not be defined in the consequent section of a ternary
+  expression.
+
+## [v1.0.0]
+
+### Added
+
+- Object literals. Objects can now be defined inline with
+  `{standard: 'syntax'}`.
+- Array literals. Arrays can also be defined with `["standard", 'syntax']`.
+- The 'in' operator, for checking to see if a string appears inside a larger
+  string, or if an element exists in an array.
+- Ternary expressions with `this ? "standard" : "syntax"`
+- Ternary expressions with `alternate ?: "syntax"`
+
+### Changed
+
+- Simplified Grammar, reduced RAM footprint
+- Dot notation can now be used to access properties of literals, such as
+  `"someString".length` or `{foo: 'bar'}.foo`.
+- Transform syntax has changed. Arguments are now passed in parentheses, and
+  multiple arguments can be defined. Arguments are no longer limited to object
+  literals.
+
+## [v0.2.0]
+
+### Added
+
+- "Divide and floor" operator: //
+- Documentation outlining running expressions against XML.
+
+## v0.1.0
+
+### Added
+
+- Initial release
+
+[development]: https://github.com/TomFrost/Jexl/compare/v2.3.0...HEAD
+[v2.3.0]: https://github.com/TomFrost/Jexl/compare/v2.2.2...v2.3.0
+[v2.2.2]: https://github.com/TomFrost/Jexl/compare/v2.2.1...v2.2.2
+[v2.2.1]: https://github.com/TomFrost/Jexl/compare/v2.2.0...v2.2.1
+[v2.2.0]: https://github.com/TomFrost/Jexl/compare/v2.1.1...v2.2.0
+[v2.1.1]: https://github.com/TomFrost/Jexl/compare/v2.1.0...v2.1.1
+[v2.1.0]: https://github.com/TomFrost/Jexl/compare/v2.0.2...v2.1.0
+[v2.0.2]: https://github.com/TomFrost/Jexl/compare/v2.0.1...v2.0.2
+[v2.0.1]: https://github.com/TomFrost/Jexl/compare/v2.0.0...v2.0.1
+[v2.0.0]: https://github.com/TomFrost/Jexl/compare/1.1.4...v2.0.0
+[v1.1.4]: https://github.com/TomFrost/Jexl/compare/1.1.3...1.1.4
+[v1.1.3]: https://github.com/TomFrost/Jexl/compare/1.1.2...1.1.3
+[v1.1.2]: https://github.com/TomFrost/Jexl/compare/1.1.1...1.1.2
+[v1.1.1]: https://github.com/TomFrost/Jexl/compare/1.1.0...1.1.1
+[v1.1.0]: https://github.com/TomFrost/Jexl/compare/1.0.2...1.1.0
+[v1.0.2]: https://github.com/TomFrost/Jexl/compare/1.0.1...1.0.2
+[v1.0.1]: https://github.com/TomFrost/Jexl/compare/1.0.0...1.0.1
+[v1.0.0]: https://github.com/TomFrost/Jexl/compare/0.2.0...1.0.0
+[v0.2.0]: https://github.com/TomFrost/Jexl/compare/0.1.0...0.2.0

package/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2020 Tom Shawver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# @jbrowse/jexl
+
+A fork of the jexl lang for jbrowse
+
+## Quick Examples
+
+```javascript
+const context = {
+  name: { first: 'Sterling', last: 'Archer' },
+  assoc: [
+    { first: 'Lana', last: 'Kane' },
+    { first: 'Cyril', last: 'Figgis' },
+    { first: 'Pam', last: 'Poovey' }
+  ],
+  age: 36
+}
+
+// Template strings with interpolation
+jexl.evalSync('`Hello ${name.first} ${name.last}`', context)
+// "Hello Sterling Archer"
+
+jexl.evalSync('`Age in 5 years: ${age + 5}`', context)
+// "Age in 5 years: 41"
+
+// Filter arrays
+jexl.evalSync('assoc[.first == "Lana"].last', context)
+// "Kane"
+
+// Math operations
+jexl.evalSync('age * (3 - 1)', context)
+// 72
+
+// String concatenation
+jexl.evalSync('name.first + " " + name.last', context)
+// "Sterling Archer"
+
+// Conditional logic
+jexl.evalSync('age > 62 ? "retired" : "working"', context)
+// "working"
+
+// Array indexes
+jexl.evalSync('assoc[1].first', context)
+// "Cyril"
+```
+
+## Language Reference
+
+### Native Types
+
+| Type             | Examples                                             |
+| ---------------- | ---------------------------------------------------- |
+| Booleans         | `true`, `false`                                      |
+| Strings          | `"Hello \"user\""`, `'Hey there!'`                   |
+| Template Strings | `` `Hello ${name}` ``, `` `Total: ${price * qty}` `` |
+| Numerics         | `6`, `-7.2`, `5`, `-3.14159`                         |
+| Objects          | `{hello: "world!"}`                                  |
+| Arrays           | `['hello', 'world!']`                                |
+
+### Template Strings
+
+Template strings use backticks and support expression interpolation with `${}`:
+
+```javascript
+const context = { name: 'World', price: 10, qty: 3 }
+
+jexl.evalSync('`Hello ${name}!`', context)
+// "Hello World!"
+
+jexl.evalSync('`Total: $${price * qty}`', context)
+// "Total: $30"
+
+// Escape backticks and dollar signs with backslash
+jexl.evalSync('`Code: \\`example\\``')
+// "Code: `example`"
+
+jexl.evalSync('`Price: \\$100`')
+// "Price: $100"
+```
+
+### Operators
+
+**Unary:** `!` (negate)
+
+**Binary:**
+
+- Arithmetic: `+`, `-`, `*`, `/`, `//` (floor division), `%`, `^` (power)
+- Comparison: `==`, `!=`, `>`, `>=`, `<`, `<=`, `in`
+- Logical: `&&`, `||`
+- Assignment: `=` (assigns value to variable)
+
+**Ternary:** `condition ? consequent : alternate`
+
+**Sequence:** `;` (separates multiple expressions)
+
+### Identifiers
+
+Access context variables by name. Use dot notation or brackets for nested properties:
+
+```javascript
+const context = {
+  name: { first: 'Malory', last: 'Archer' },
+  exes: ['Nikolai', 'Len', 'Burt'],
+  lastEx: 2
+}
+
+jexl.evalSync('name.first', context) // "Malory"
+jexl.evalSync('name["last"]', context) // "Archer"
+jexl.evalSync('exes[2]', context) // "Burt"
+jexl.evalSync('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.evalSync('employees[.first == "Sterling"]', context)
+// [{ first: 'Sterling', last: 'Archer', age: 36 }]
+
+jexl.evalSync('employees[.age >= 30 && .age < 40]', context)
+// [{ first: 'Sterling', ... }, { first: 'Lana', ... }]
+
+jexl.evalSync('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.evalSync('"hello"|upper')
+// "HELLO"
+
+jexl.evalSync('"firstName lastName"|split(" ")[0]')
+// "firstName"
+```
+
+### Functions
+
+Call functions in expressions:
+
+```javascript
+jexl.addFunction('min', Math.min)
+jexl.addFunction('max', Math.max)
+
+jexl.evalSync('min(5, 2, 9)')
+// 2
+
+jexl.evalSync('max(temperature, threshold)')
+// evaluates with context
+```
+
+### Multiple Expressions
+
+Separate multiple expressions with semicolons. The result is the value of the last expression:
+
+```javascript
+jexl.evalSync('5; 10; 15')
+// 15
+
+jexl.evalSync('1 + 1; 2 + 2; 3 + 3')
+// 6
+```
+
+### Variable Assignment
+
+Assign values to variables using `=` (no `let`, `var`, or `const` needed). Assignments mutate the context and return the assigned value:
+
+```javascript
+jexl.evalSync('x = 5')
+// 5
+
+jexl.evalSync('x = 5; x * 2')
+// 10
+
+jexl.evalSync('x = 5; y = 10; x + y')
+// 15
+
+const context = {}
+jexl.evalSync('x = 5; y = x * 2; y', context)
+// 10
+// context is now { x: 5, y: 10 }
+```
+
+## Usage
+
+```javascript
+import jexl from 'jexl'
+
+// Synchronous evaluation
+const result = jexl.evalSync('expression', context)
+
+// Asynchronous evaluation (supports async transforms/functions)
+const result = await jexl.eval('expression', context)
+
+// Compile once, evaluate many times
+const expr = jexl.compile('name.first + " " + name.last')
+expr.evalSync({ name: { first: 'John', last: 'Doe' } })
+```
+
+## License
+
+MIT License - see LICENSE.txt for details

package/dist/Expression.d.ts

@@ -0,0 +1,38 @@
+import PromiseSync from './PromiseSync.ts';
+import type { AstNode } from './types.ts';
+interface Grammar {
+    elements: Record<string, any>;
+    [key: string]: any;
+}
+type PromiseConstructor = typeof Promise | typeof PromiseSync;
+declare class Expression {
+    _grammar: Grammar;
+    _exprStr: string;
+    _ast: AstNode | null;
+    constructor(grammar: Grammar, exprStr: string);
+    /**
+     * Forces a compilation of the expression string that this Expression object
+     * was constructed with. This function can be called multiple times; useful
+     * if the language elements of the associated Jexl instance change.
+     * @returns {Expression} this Expression instance, for convenience
+     */
+    compile(): this;
+    /**
+     * Asynchronously evaluates the expression within an optional context.
+     * @param {Object} [context] A mapping of variables to values, which will be
+     *      made accessible to the Jexl expression when evaluating it
+     * @returns {Promise<*>} resolves with the result of the evaluation.
+     */
+    eval(context?: {}): Promise<any> | PromiseSync<any>;
+    /**
+     * Synchronously evaluates the expression within an optional context.
+     * @param {Object} [context] A mapping of variables to values, which will be
+     *      made accessible to the Jexl expression when evaluating it
+     * @returns {*} the result of the evaluation.
+     * @throws {*} on error
+     */
+    evalSync(context?: {}): unknown;
+    _eval(context: any, promise: PromiseConstructor): Promise<any> | PromiseSync<any>;
+    _getAst(): AstNode | null;
+}
+export default Expression;

package/dist/Expression.js

@@ -0,0 +1,75 @@
+"use strict";
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Lexer_ts_1 = __importDefault(require("./Lexer.js"));
+const PromiseSync_ts_1 = __importDefault(require("./PromiseSync.js"));
+const Evaluator_ts_1 = __importDefault(require("./evaluator/Evaluator.js"));
+const Parser_ts_1 = __importDefault(require("./parser/Parser.js"));
+class Expression {
+    constructor(grammar, exprStr) {
+        this._grammar = grammar;
+        this._exprStr = exprStr;
+        this._ast = null;
+    }
+    /**
+     * Forces a compilation of the expression string that this Expression object
+     * was constructed with. This function can be called multiple times; useful
+     * if the language elements of the associated Jexl instance change.
+     * @returns {Expression} this Expression instance, for convenience
+     */
+    compile() {
+        const lexer = new Lexer_ts_1.default(this._grammar);
+        const parser = new Parser_ts_1.default(this._grammar, lexer);
+        const tokens = lexer.tokenize(this._exprStr);
+        parser.addTokens(tokens);
+        this._ast = parser.complete();
+        return this;
+    }
+    /**
+     * Asynchronously evaluates the expression within an optional context.
+     * @param {Object} [context] A mapping of variables to values, which will be
+     *      made accessible to the Jexl expression when evaluating it
+     * @returns {Promise<*>} resolves with the result of the evaluation.
+     */
+    eval(context = {}) {
+        return this._eval(context, Promise);
+    }
+    /**
+     * Synchronously evaluates the expression within an optional context.
+     * @param {Object} [context] A mapping of variables to values, which will be
+     *      made accessible to the Jexl expression when evaluating it
+     * @returns {*} the result of the evaluation.
+     * @throws {*} on error
+     */
+    evalSync(context = {}) {
+        const res = this._eval(context, PromiseSync_ts_1.default);
+        if (res.error) {
+            if (res.error instanceof Error) {
+                throw res.error;
+            }
+            throw new Error(typeof res.error === 'string' ? res.error : JSON.stringify(res.error));
+        }
+        return res.value;
+    }
+    _eval(context, promise) {
+        return promise.resolve().then(() => {
+            const ast = this._getAst();
+            const evaluator = new Evaluator_ts_1.default(this._grammar, context, undefined, promise);
+            return evaluator.eval(ast);
+        });
+    }
+    _getAst() {
+        if (!this._ast) {
+            this.compile();
+        }
+        return this._ast;
+    }
+}
+exports.default = Expression;
+//# sourceMappingURL=Expression.js.map

package/dist/Expression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Expression.js","sourceRoot":"","sources":["../src/Expression.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;AAEH,0DAA8B;AAC9B,sEAA0C;AAC1C,4EAAgD;AAChD,mEAAuC;AAWvC,MAAM,UAAU;IAKd,YAAY,OAAgB,EAAE,OAAe;QAC3C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;QACvB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAED;;;;;OAKG;IACH,OAAO;QACL,MAAM,KAAK,GAAG,IAAI,kBAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACtC,MAAM,MAAM,GAAG,IAAI,mBAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;QAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC5C,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;QAC7B,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAO,GAAG,EAAE;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IACrC,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,GAAG,EAAE;QACnB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,wBAAkB,CAAgB,CAAA;QAClE,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACd,IAAI,GAAG,CAAC,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC/B,MAAM,GAAG,CAAC,KAAK,CAAA;YACjB,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAA;QACxF,CAAC;QACD,OAAO,GAAG,CAAC,KAAK,CAAA;IAClB,CAAC;IAED,KAAK,CAAC,OAAY,EAAE,OAA2B;QAC7C,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;YACjC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,CAAA;YAC1B,MAAM,SAAS,GAAG,IAAI,sBAAS,CAC7B,IAAI,CAAC,QAAQ,EACb,OAAO,EACP,SAAS,EACT,OAAO,CACR,CAAA;YACD,OAAO,SAAS,CAAC,IAAI,CAAC,GAAI,CAAC,CAAA;QAC7B,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,IAAI,CAAC,OAAO,EAAE,CAAA;QAChB,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAA;IAClB,CAAC;CACF;AAED,kBAAe,UAAU,CAAA"}