@stackone/expressions 0.3.1 → 0.4.1

package/README.md

@@ -1,13 +1,12 @@
 # @stackone/expressions
+
 ## Description
 
 This package can be used to parse and evaluate string expressions with support for variables replacement, functions and operators.
 
-This package uses the tech stack provided by the **Connect Monorepo** global setup. Please check the [root README](../../README.md) for more information.
-
 ## Requirements
 
-Please check the [root README](../../README.md) for requirements.
+Node.js 20+ is required to run this project.
 
 ## Installation
 
@@ -47,3 +46,169 @@ $ npm run lint
 # run linter and try to fix any error
 $ npm run lint:fix
 ```
+
+## API Reference
+
+### evaluate(expression: string, context?: object)
+
+Evaluates the given expression using the provided context.
+
+- Returns the evaluated result
+- Throws an error if the expression is invalid or evaluation fails
+
+```js
+evaluate("$.user.name", { user: { name: "John" } }); // Returns "John"
+evaluate("x + y", { x: 1, y: 2 }); // Returns 3
+```
+
+### isValidExpression(expression: string)
+
+Checks if the given expression is valid.
+
+- Returns `true` if the expression is valid
+- Returns `false` otherwise
+
+```js
+isValidExpression("$.user.name"); // Returns true
+isValidExpression("invalid $$$ expression"); // Returns false
+```
+
+### safeEvaluate(expression: string, context?: object)
+
+Safely evaluates the expression without throwing errors.
+
+- Returns the evaluated result if successful
+- Returns `null` if evaluation fails or the expression is invalid
+
+```js
+safeEvaluate("$.user.name", { user: { name: "John" } }); // Returns "John"
+safeEvaluate("$ invalid expression", {}); // Returns null
+```
+
+## Expression language syntax
+
+There are three types of expressions supported:
+
+### JSON Path Expressions
+
+When the expression starts with `$`, it is treated as a JSON Path expression and will be evaluated as such.
+
+#### JSON Path Syntax
+
+| JSON Path | Description |
+| --- | --- |
+| `$` | The root object |
+| `.` | Child operator |
+| `@` | The current object |
+| `*` | Wildcard. All elements in an array, or all properties of an object |
+| `..` | Recursive descent |
+| `[]` | Subscript operator |
+| `[,]` | Union operator |
+| `[start:end:step]` | Array slice operator |
+| `?(expression)` | Filter expression |
+| `()` | Script expression |
+
+Examples:
+
+```js
+// Given the context: { user: { name: "John", age: 30 }, "info/email": "info@email.com" }
+'$.user.name'         // Returns "John"
+'$.user.age'          // Returns 30
+'$.user[*]'           // Returns ["John", 30]
+'$["info/email"]'     // Returns "info@email.com"
+```
+
+For more information on JSON Path syntax, refer to the original [JSON Path documentation](https://goessner.net/articles/JsonPath/).
+
+### JEXL Expressions
+
+This kind of expression is enclosed in double brackets `{{expression}}`. It supports variables and operators.
+
+#### Operators
+
+| Operator | Description |
+| --- | --- |
+| `!` | Logical NOT |
+| `+` | Addition, string concatenation |
+| `-` | Subtraction |
+| `*` | Multiplication |
+| `/` | Division |
+| `//` | Floor division |
+| `%` | Modulus |
+| `^` | Exponentiation |
+| `&&` | Logical AND |
+| `\|\|` | Logical OR |
+| `==` | Equal |
+| `!=` | Not equal |
+| `>` | Greater than |
+| `>=` | Greater than or equal |
+| `<` | Less than |
+| `<=` | Less than or equal |
+| `in` | Element of string or array |
+| `? :` | Ternary operator |
+
+Examples:
+
+```js
+// Given the context: { x: 10, y: 5 }
+'{{x + y}}'                  // Returns 15
+'{{x * 2}}'                  // Returns 20
+'{{x > y}}'                  // Returns true
+'{{x == 10 ? "yes" : "no"}}' // Returns "yes"
+'{{x in [1, 2, 3]}}'         // Returns false
+'{{x != y}}'                 // Returns true
+```
+
+#### Identifiers
+
+Identifiers can be used to reference variables in the context.
+
+```js
+// Given the context:
+// { 
+//     name: {
+//         first: "John",
+//         last: "Smith"
+//     },
+//     jobs: ["Developer", "Designer"]
+// }
+`{{name.first}}`          // Returns "John"
+`{{jobs[1]}}`             // Returns "Designer"
+```
+
+#### Collections
+
+Collections, or arrays of objects, can be filtered by including a filter expression in brackets.
+
+```js
+// Given the context:
+// {
+//     users: [
+//         { name: "John", age: 30 },
+//         { name: "Jane", age: 25 }
+//     ]
+// }
+`{{users[.name == "John"].age}}` // Returns 30
+`{{users[.age > 25].name}}`      // Returns ["John"]
+```
+
+### String Interpolation
+
+To simplify strings usage, a more straightforward syntax is provided for string interpolation of variables using the `${var}` syntax.
+
+Examples:
+
+```js
+// Given the context: { name: "John", age: 30 }
+"Hello ${name}"       // Returns "Hello John"
+"User is ${age}"    // Returns "User is 30"
+```
+
+Note: If the expression is a string without any of the patterns described above, it will be returned as is.
+
+```js
+// Given the context: { name: "John", age: 30 }
+"Hello world"       // Returns "Hello world"
+```
+
+For more information on the JEXL syntax, refer to the [JEXL Syntax documentation](https://commons.apache.org/proper/commons-jexl/reference/syntax.html).

package/dist/index.es.mjs

@@ -1 +1 @@
-import{isObject as t,notMissing as r}from"@stackone/utils";import e from"lodash.get";import*as n from"jexl";const o=/\${([^}]+)}/g,c=(t=()=>new n.Jexl)=>t(),l=t=>t.replace(/\$\./g,"").trim(),a=(t,r)=>{try{return t.compile(r)}catch(t){return null}},s=(r,e)=>{const n=t(e)?e:{},o=c(),s=l(r),p=u(s,n);if(p)return p;const i=a(o,s);if(!i)return null;try{return i.evalSync(n)}catch(t){return null}},u=(t,n)=>{const c=t.match(o)?.map((t=>({toReplace:t,path:t.slice(2,-1)})));if(!c)return;let l=String(t);for(const t of c){const o=e(n,t.path);r(o)&&(l=l.replace(t.toReplace,`${String(o)}`))}return l},p=t=>{const r=c(),e=l(t),n=a(r,e);return!!i(e)||!(!n||"."===e)},i=t=>new RegExp(o).test(t);export{s as evaluate,i as isInterpolatedExpression,p as isValidExpression};
+import{notMissing as r,isObject as t}from"@stackone/utils";import*as e from"jexl";import n from"jsonpath";import o from"lodash.get";const a=/\${([^}]+)}/g,c=(c,s)=>{const i=c?.trim();if(null==i||""===i)throw new Error("Empty expression");const l=t(s)?s:{},u=(r=>{if(r.startsWith("{{")&&r.endsWith("}}"))return r.slice(2,-2)})(i),p=u??i,h=((r=()=>new e.Jexl)=>r())(),f=(r=>r.replace(/\$\./g,"").trim())(p),m=((t,e)=>{const n=t.match(a)?.map((r=>({toReplace:r,path:r.slice(2,-1)})));if(!n)return;let c=String(t);for(const t of n){const n=o(e,t.path);r(n)&&(c=c.replace(t.toReplace,`${String(n)}`))}return c})(f,l);if(m)return m;try{if(!u&&i.startsWith("$"))return((r,t)=>(n.parse(r),n.query(t,r)[0]))(i,l)}catch(r){throw new Error(`Invalid JSON path: "${i}"`)}if(!m&&!u)return c;const y=((r,t)=>{try{return r.compile(t)}catch(r){return null}})(h,f);if(!y||"."===f)throw new Error(`Invalid expression: "${i}"`);try{return y.evalSync(l)}catch(r){return}},s=(r,t)=>{try{return c(r,t)}catch(r){return null}},i=r=>{try{return c(r),!0}catch(r){return!1}};export{c as evaluate,i as isValidExpression,s as safeEvaluate};

package/dist/index.js

@@ -1 +1 @@
-"use strict";var e=require("@stackone/utils"),t=require("lodash.get");function r(e){var t=Object.create(null);return e&&Object.keys(e).forEach((function(r){if("default"!==r){var n=Object.getOwnPropertyDescriptor(e,r);Object.defineProperty(t,r,n.get?n:{enumerable:!0,get:function(){return e[r]}})}})),t.default=e,Object.freeze(t)}var n=r(require("jexl"));const c=/\${([^}]+)}/g,o=(e=()=>new n.Jexl)=>e(),s=e=>e.replace(/\$\./g,"").trim(),i=(e,t)=>{try{return e.compile(t)}catch(e){return null}},u=(r,n)=>{const o=r.match(c)?.map((e=>({toReplace:e,path:e.slice(2,-1)})));if(!o)return;let s=String(r);for(const r of o){const c=t(n,r.path);e.notMissing(c)&&(s=s.replace(r.toReplace,`${String(c)}`))}return s},a=e=>new RegExp(c).test(e);exports.evaluate=(t,r)=>{const n=e.isObject(r)?r:{},c=o(),a=s(t),l=u(a,n);if(l)return l;const p=i(c,a);if(!p)return null;try{return p.evalSync(n)}catch(e){return null}},exports.isInterpolatedExpression=a,exports.isValidExpression=e=>{const t=o(),r=s(e),n=i(t,r);return!!a(r)||!(!n||"."===r)};
+"use strict";var r=require("@stackone/utils"),e=require("jexl"),t=require("jsonpath"),n=require("lodash.get");function c(r){var e=Object.create(null);return r&&Object.keys(r).forEach((function(t){if("default"!==t){var n=Object.getOwnPropertyDescriptor(r,t);Object.defineProperty(e,t,n.get?n:{enumerable:!0,get:function(){return r[t]}})}})),e.default=r,Object.freeze(e)}var i=c(e);const a=/\${([^}]+)}/g,s=(e,c)=>{const s=e?.trim();if(null==s||""===s)throw new Error("Empty expression");const o=r.isObject(c)?c:{},u=(r=>{if(r.startsWith("{{")&&r.endsWith("}}"))return r.slice(2,-2)})(s),l=u??s,p=((r=()=>new i.Jexl)=>r())(),f=(r=>r.replace(/\$\./g,"").trim())(l),h=((e,t)=>{const c=e.match(a)?.map((r=>({toReplace:r,path:r.slice(2,-1)})));if(!c)return;let i=String(e);for(const e of c){const c=n(t,e.path);r.notMissing(c)&&(i=i.replace(e.toReplace,`${String(c)}`))}return i})(f,o);if(h)return h;try{if(!u&&s.startsWith("$"))return((r,e)=>(t.parse(r),t.query(e,r)[0]))(s,o)}catch(r){throw new Error(`Invalid JSON path: "${s}"`)}if(!h&&!u)return e;const y=((r,e)=>{try{return r.compile(e)}catch(r){return null}})(p,f);if(!y||"."===f)throw new Error(`Invalid expression: "${s}"`);try{return y.evalSync(o)}catch(r){return}};exports.evaluate=s,exports.isValidExpression=r=>{try{return s(r),!0}catch(r){return!1}},exports.safeEvaluate=(r,e)=>{try{return s(r,e)}catch(r){return null}};

package/dist/types/evaluate.d.ts

@@ -1 +1,2 @@
-export declare const evaluateExpression: (expression: string, context?: unknown) => unknown;
+export declare const evaluateExpression: (expression?: string | null, context?: unknown) => unknown;
+export declare const safeEvaluateExpression: (expression?: string | null, context?: unknown) => unknown;

package/dist/types/index.d.ts

@@ -1,2 +1,3 @@
 export { evaluateExpression as evaluate } from './evaluate';
-export { isValidExpression, isInterpolatedExpression } from './validate';
+export { safeEvaluateExpression as safeEvaluate } from './evaluate';
+export { isValidExpression } from './validate';

package/dist/types/utils.d.ts

@@ -1,5 +1,9 @@
 import Expression from 'jexl/Expression';
+import { ExpressionContext } from './types';
 export declare const cleanExpression: (expression: string) => string;
 export declare const compileExpression: (expressionHandler: {
     compile: (expr: string) => Expression;
 }, expression: string) => Expression | null;
+export declare const extractExpressionBetweenDoubleCurlyBraces: (expression: string) => string | undefined;
+export declare const evaluateJsonPath: (expression: string, context: unknown) => unknown;
+export declare const evaluateStringInterpolations: (expression: string, context: ExpressionContext) => string | undefined;

package/dist/types/validate.d.ts

@@ -1,2 +1 @@
-export declare const isValidExpression: (expression: string) => boolean;
-export declare const isInterpolatedExpression: (expression: string) => boolean;
+export declare const isValidExpression: (expression?: string | null) => boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stackone/expressions",
-    "version": "0.3.1",
+    "version": "0.4.1",
     "description": "",
     "main": "dist/index.js",
     "module": "dist/index.es.mjs",
@@ -34,10 +34,12 @@
     "dependencies": {
         "@stackone/utils": "*",
         "jexl": "^2.3.0",
+        "jsonpath": "^1.1.1",
         "lodash.get": "^4.4.2"
     },
     "devDependencies": {
         "@types/jexl": "^2.3.4",
+        "@types/jsonpath": "^0.2.4",
         "@types/lodash.get": "^4.4.9"
     }
 }