@stackone/expressions 0.6.1 → 0.7.0

package/README.md

@@ -49,7 +49,7 @@ $ npm run lint:fix
 
 ## API Reference
 
-### evaluate(expression: string, context?: object)
+### evaluate(expression: string, context?: object, options?: { incrementalJsonPath?: boolean })
 
 Evaluates the given expression using the provided context.
 
@@ -61,6 +61,14 @@ evaluate("$.user.name", { user: { name: "John" } }); // Returns "John"
 evaluate("x + y", { x: 1, y: 2 }); // Returns 3
 ```
 
+- Setting incrementalJsonPath iterates through any JSON Path expression to check for failure, starting at the root.
+- This exchanges performance for better error messages, useful for AI validation and self-repair.
+
+```js
+evaluate("$.user.name", { user: { name: "John" } }, { incrementalJsonPath: true }); // Returns "John"
+evaluate("$.user.details.age", { user: { details: { name: "John" } } }, { incrementalJsonPath: true }); // Throws Error: "Key 'age' not found at '$.user.details'. Available keys: name"
+```
+
 ### isValidExpression(expression: string)
 
 Checks if the given expression is valid.
@@ -202,6 +210,9 @@ Examples:
 // Given the context: { name: "John", age: 30 }
 "Hello ${name}"       // Returns "Hello John"
 "User is ${age}"    // Returns "User is 30"
+// You can also use JEXL inside string syntax
+"Status: ${age > 18 ? 'Adult' : 'Minor'}" // Returns "Status: Adult"
+"Age in 5 years: ${age + 5}"             // Returns "Age in 5 years: 35"
 ```
 
 Note: If the expression is a string without any of the patterns described above, it will be returned as is.

package/dist/index.es.mjs

@@ -1 +1 @@
-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,s=(s,c)=>{const i=s?.trim();if(null==i||""===i)throw new Error("Empty expression");const l=t(c)?c:{},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 s=String(t);for(const t of n){const n=o(e,t.path);r(n)&&(s=s.replace(t.toReplace,`${String(n)}`))}return s})(f,l);if(m)return m;try{if(!u&&i.startsWith("$"))return((r,t)=>{n.parse(r);const e=n.query(t,r);if(0!==e.length)return 1===e.length?e[0]:e})(i,l)}catch(r){throw new Error(`Invalid JSON path: "${i}"`)}if(!m&&!u)return s;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}},c=(r,t)=>{try{return s(r,t)}catch(r){return null}},i=(r,t)=>{const e=r=>Array.isArray(r)?r.map(e):"object"==typeof r&&null!==r?i(r,t):"string"==typeof r?c(r,t):r;return Object.fromEntries(Object.entries(r).map((([r,t])=>[r,e(t)])))},l=r=>{try{return s(r),!0}catch(r){return!1}};export{s as evaluate,l as isValidExpression,c as safeEvaluate,i as safeEvaluateRecord};
+import{notMissing as r,isObject as t}from"@stackone/utils";import*as e from"jexl";import a from"jsonpath";import n from"lodash.get";const o=/\${([^}]+)}/g,i=(r,t)=>{try{return r.compile(t)}catch(r){return null}},l=(r,t)=>{a.parse(r);const e=a.query(t,r);if(0!==e.length)return 1===e.length?e[0]:e},s=(r,t,e)=>r.replace(t,String(e)),c=(t,e,a)=>{const l=t.match(o);if(!l)return;const c=l.length,u=new Array(c);for(let r=0;r<c;r++)u[r]={toReplace:l[r],path:l[r].slice(2,-1)};return u.reduce(((t,o)=>((t,e,a,o)=>{const l=t.path.trim();if(!l)return o;try{const c=i(e,l);if(c){const r=c.evalSync(a);if(void 0!==r)return s(o,t.toReplace,r)}const u=n(a,l);return r(u)?s(o,t.toReplace,u):o}catch(r){return o}})(o,a,e,t)),String(t))},u=(r,e,a,n)=>{if(Array.isArray(e)){const r=parseInt(a,10);if(!isNaN(r)&&(r<0||r>=e.length))return{value:void 0,error:`Invalid array index '${a}' at '${n}'`,availableKeys:e.map(((r,t)=>t.toString()))}}return t(e)?{value:void 0,error:`Key '${a}' not found at '${n}'`,availableKeys:Object.keys(e)}:{value:void 0,error:`${r} at '${n}'`,availableKeys:[]}},h=(r,e)=>{const a=/(\.\.)|(\[\*\])|(\[\?\()|(\[\d+:\d+\])/;try{if(a.test(r)){const t=l(r,e);return void 0===t?{value:void 0,error:`Invalid or empty JSONPath: '${r}'`}:{value:t}}const n=r.match(/\$|(?:\['([^']+)'\])|(?:\["([^"]+)"\])|\[\d+\]|[^[\].]+/g)||[];return((r,e)=>{if("$"!==r[0])return{value:void 0,error:"JSON path must start with $"};let a=e,n="$";for(let e=1;e<r.length;e++){const o=r[e],i=o.startsWith("[")?`${n}${o}`:`${n}.${o}`;if(Array.isArray(a)){const r=parseInt(o,10);if(isNaN(r)||r<0||r>=a.length)return u("Invalid array index",a,o,n);a=a[r],n=i}else{if(!t(a))return{value:void 0,error:`Cannot access '${o}' at '${n}' - parent is not an object`,availableKeys:[]};if(!Object.prototype.hasOwnProperty.call(a,o))return u("Key not found",a,o,n);a=a[o],n=i}}return{value:a}})(n.map((r=>r.replace(/^\['([^']+)'\]$/,"$1").replace(/^\["([^"]+)"\]$/,"$1").replace(/^\[(\d+)\]$/,"$1"))),e)}catch(r){return{value:void 0,error:`Something went wrong with evaluation of JSON path: ${String(r)}`}}},p=(r,a,n)=>{const o=r?.trim();if(null==o||""===o)throw new Error("Empty expression");const s=t(a)?a:{},u=((r=()=>new e.Jexl)=>r())(),p=(r=>{if(r.startsWith("{{")&&r.endsWith("}}"))return r.slice(2,-2)})(o),v=(r=>r.replace(/\$\./g,"").trim())(p??o),y=c(v,s,u);if(y)return y;if(!p&&o.startsWith("$"))return n?.incrementalJsonPath?((r,t)=>{const e=h(r,t);if(e.error)throw new Error(`${e.error}${e.availableKeys?.length?`. Available keys: ${e.availableKeys.join(", ")}`:""}`);return e.value})(o,s):((r,t)=>{try{return l(r,t)}catch{throw new Error(`Invalid JSON path: "${r}"`)}})(o,s);if(!y&&!p)return r;const f=i(u,v);if(!f||"."===v)throw new Error(`Invalid expression: "${o}"`);try{return f.evalSync(s)}catch{return}},v=(r,t)=>{try{return p(r,t)}catch(r){return null}},y=(r,t)=>{const e=r=>Array.isArray(r)?r.map(e):"object"==typeof r&&null!==r?y(r,t):"string"==typeof r?v(r,t):r;return Object.fromEntries(Object.entries(r).map((([r,t])=>[r,e(t)])))},f=r=>{try{return p(r),!0}catch(r){return!1}};export{p as evaluate,f as isValidExpression,v as safeEvaluate,y as safeEvaluateRecord};

package/dist/index.js

@@ -1 +1 @@
-"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 a=c(e);const s=/\${([^}]+)}/g,i=(e,c)=>{const i=e?.trim();if(null==i||""===i)throw new Error("Empty expression");const o=r.isObject(c)?c:{},u=(r=>{if(r.startsWith("{{")&&r.endsWith("}}"))return r.slice(2,-2)})(i),l=u??i,p=((r=()=>new a.Jexl)=>r())(),f=(r=>r.replace(/\$\./g,"").trim())(l),h=((e,t)=>{const c=e.match(s)?.map((r=>({toReplace:r,path:r.slice(2,-1)})));if(!c)return;let a=String(e);for(const e of c){const c=n(t,e.path);r.notMissing(c)&&(a=a.replace(e.toReplace,`${String(c)}`))}return a})(f,o);if(h)return h;try{if(!u&&i.startsWith("$"))return((r,e)=>{t.parse(r);const n=t.query(e,r);if(0!==n.length)return 1===n.length?n[0]:n})(i,o)}catch(r){throw new Error(`Invalid JSON path: "${i}"`)}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: "${i}"`);try{return y.evalSync(o)}catch(r){return}},o=(r,e)=>{try{return i(r,e)}catch(r){return null}},u=(r,e)=>{const t=r=>Array.isArray(r)?r.map(t):"object"==typeof r&&null!==r?u(r,e):"string"==typeof r?o(r,e):r;return Object.fromEntries(Object.entries(r).map((([r,e])=>[r,t(e)])))};exports.evaluate=i,exports.isValidExpression=r=>{try{return i(r),!0}catch(r){return!1}},exports.safeEvaluate=o,exports.safeEvaluateRecord=u;
+"use strict";var r=require("@stackone/utils"),e=require("jexl"),t=require("jsonpath"),n=require("lodash.get");function a(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=a(e);const o=/\${([^}]+)}/g,s=(r,e)=>{try{return r.compile(e)}catch(r){return null}},l=(r,e)=>{t.parse(r);const n=t.query(e,r);if(0!==n.length)return 1===n.length?n[0]:n},c=(r,e,t)=>r.replace(e,String(t)),u=(e,t,a)=>{const i=e.match(o);if(!i)return;const l=i.length,u=new Array(l);for(let r=0;r<l;r++)u[r]={toReplace:i[r],path:i[r].slice(2,-1)};return u.reduce(((e,i)=>((e,t,a,i)=>{const o=e.path.trim();if(!o)return i;try{const l=s(t,o);if(l){const r=l.evalSync(a);if(void 0!==r)return c(i,e.toReplace,r)}const u=n(a,o);return r.notMissing(u)?c(i,e.toReplace,u):i}catch(r){return i}})(i,a,t,e)),String(e))},v=(e,t,n,a)=>{if(Array.isArray(t)){const r=parseInt(n,10);if(!isNaN(r)&&(r<0||r>=t.length))return{value:void 0,error:`Invalid array index '${n}' at '${a}'`,availableKeys:t.map(((r,e)=>e.toString()))}}return r.isObject(t)?{value:void 0,error:`Key '${n}' not found at '${a}'`,availableKeys:Object.keys(t)}:{value:void 0,error:`${e} at '${a}'`,availableKeys:[]}},p=(e,t)=>{const n=/(\.\.)|(\[\*\])|(\[\?\()|(\[\d+:\d+\])/;try{if(n.test(e)){const r=l(e,t);return void 0===r?{value:void 0,error:`Invalid or empty JSONPath: '${e}'`}:{value:r}}const a=e.match(/\$|(?:\['([^']+)'\])|(?:\["([^"]+)"\])|\[\d+\]|[^[\].]+/g)||[];return((e,t)=>{if("$"!==e[0])return{value:void 0,error:"JSON path must start with $"};let n=t,a="$";for(let t=1;t<e.length;t++){const i=e[t],o=i.startsWith("[")?`${a}${i}`:`${a}.${i}`;if(Array.isArray(n)){const r=parseInt(i,10);if(isNaN(r)||r<0||r>=n.length)return v("Invalid array index",n,i,a);n=n[r],a=o}else{if(!r.isObject(n))return{value:void 0,error:`Cannot access '${i}' at '${a}' - parent is not an object`,availableKeys:[]};if(!Object.prototype.hasOwnProperty.call(n,i))return v("Key not found",n,i,a);n=n[i],a=o}}return{value:n}})(a.map((r=>r.replace(/^\['([^']+)'\]$/,"$1").replace(/^\["([^"]+)"\]$/,"$1").replace(/^\[(\d+)\]$/,"$1"))),t)}catch(r){return{value:void 0,error:`Something went wrong with evaluation of JSON path: ${String(r)}`}}},f=(e,t,n)=>{const a=e?.trim();if(null==a||""===a)throw new Error("Empty expression");const o=r.isObject(t)?t:{},c=((r=()=>new i.Jexl)=>r())(),v=(r=>{if(r.startsWith("{{")&&r.endsWith("}}"))return r.slice(2,-2)})(a),f=(r=>r.replace(/\$\./g,"").trim())(v??a),h=u(f,o,c);if(h)return h;if(!v&&a.startsWith("$"))return n?.incrementalJsonPath?((r,e)=>{const t=p(r,e);if(t.error)throw new Error(`${t.error}${t.availableKeys?.length?`. Available keys: ${t.availableKeys.join(", ")}`:""}`);return t.value})(a,o):((r,e)=>{try{return l(r,e)}catch{throw new Error(`Invalid JSON path: "${r}"`)}})(a,o);if(!h&&!v)return e;const y=s(c,f);if(!y||"."===f)throw new Error(`Invalid expression: "${a}"`);try{return y.evalSync(o)}catch{return}},h=(r,e)=>{try{return f(r,e)}catch(r){return null}},y=(r,e)=>{const t=r=>Array.isArray(r)?r.map(t):"object"==typeof r&&null!==r?y(r,e):"string"==typeof r?h(r,e):r;return Object.fromEntries(Object.entries(r).map((([r,e])=>[r,t(e)])))};exports.evaluate=f,exports.isValidExpression=r=>{try{return f(r),!0}catch(r){return!1}},exports.safeEvaluate=h,exports.safeEvaluateRecord=y;

package/dist/types/evaluate.d.ts

@@ -1,3 +1,5 @@
-export declare const evaluateExpression: (expression?: string | null, context?: unknown) => unknown;
+export declare const evaluateExpression: (expression?: string | null, context?: unknown, options?: {
+    incrementalJsonPath?: boolean;
+}) => unknown;
 export declare const safeEvaluateExpression: (expression?: string | null, context?: unknown) => unknown;
 export declare const safeEvaluateRecord: (record: Record<string, unknown>, context?: unknown) => Record<string, unknown>;

package/dist/types/types.d.ts

@@ -1,3 +1,8 @@
 export type ExpressionContext = {
     [key: string]: unknown;
 };
+export type JSONPathEvalResult = {
+    value: unknown;
+    error?: string;
+    availableKeys?: string[];
+};

package/dist/types/utils.d.ts

@@ -6,4 +6,11 @@ export declare const compileExpression: (expressionHandler: {
 }, 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;
+export declare const evaluateStringInterpolations: (expression: string, context: ExpressionContext, expressionHandler: {
+    compile: (expr: string) => Expression;
+}) => string | undefined;
+export declare const evaluateJsonPathIncremental: (path: string, context: unknown) => {
+    value: unknown;
+    error?: string;
+    availableKeys?: string[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stackone/expressions",
-    "version": "0.6.1",
+    "version": "0.7.0",
     "description": "",
     "main": "dist/index.js",
     "module": "dist/index.es.mjs",