mikel-eval 0.21.0

package/README.md

@@ -0,0 +1,212 @@
+# mikel-eval
+
+![npm version](https://badgen.net/npm/v/mikel-eval?labelColor=1d2734&color=21bf81)
+![license](https://badgen.net/github/license/jmjuanes/mikel?labelColor=1d2734&color=21bf81)
+
+The `mikel-eval` plugin extends the [mikel](https://github.com/jmjuanes/mikel) templating engine with expression evaluation capabilities. It allows you to evaluate mathematical, string, boolean, and array expressions directly within your templates.
+
+## Installation
+
+Install the plugin using **npm** or **yarn**:
+
+```bash
+# Using npm
+npm install mikel-eval
+
+# Using yarn
+yarn add mikel-eval
+```
+
+## Usage
+
+Import and register the plugin with Mikel:
+
+```javascript
+import mikel from "mikel";
+import mikelEval from "mikel-eval";
+
+// 1. create a new mikel instance for the given template
+const m = mikel.create(`{{x}} * 2 = {{=eval "x * 2"}}`);
+
+// 2. register the plugin
+m.use(mikelEval());
+
+// 3. render the template with the provided data context
+console.log(m({x: 5})); // --> "5 * 2 = 10"
+```
+
+You can also use this plugin with the default instance of Mikel:
+
+```javascript
+import mikel from "mikel";
+import mikelEval from "mikel-eval";
+
+// 1. get the options generated by mikelEval
+const options = mikelEval();
+
+// 2. render the template with the default instance of mikel
+console.log(mikel(`{{=eval "1 + 2"}}`, {}, options)); // --> "3"
+```
+
+## Features
+
+Supported expressions:
+
+- **Math:** `+`, `-`, `*`, `/`, `%`, `^`, and parentheses.
+- **Strings:** Concatenation with `+` and string functions.
+- **Booleans:** logical operators (`&&`, `||`, `!`) and comparisons (`==`, `!=`, `<`, `>`, `<=`, `>=`).
+- **Arrays:** Array functions like `len`, `indexOf`, `join`, `in`.
+- **Functions:** Built-in functions such as `abs`, `sqrt`, `max`, `min`, `replace`, `toUpperCase`, etc.
+
+## Built-in Functions
+
+The following functions are available by default in expressions evaluated by mikel-eval:
+
+### Common Functions
+
+#### `len(x)`
+
+Returns the length of a string, array, or the number of keys in an object. Examples: `len([1,2,3])` → `3`, `len("abc")` → `3`.
+
+#### `in(x, item)`
+
+Checks if `item` is present in array, string, or object values. Examples: `in([1,2,3], 2)` → `true`, `in("hello", "ll")` → `true`.
+
+#### `type(x)`
+
+Returns the JavaScript type of the provided argument as a string. Examples: `type(123)` → `"number"`, `type("abc")` → `"string"`.
+
+#### `if(condition, trueValue, falseValue)`
+
+Returns `trueValue` if `condition` is `true`, otherwise returns `falseValue`. Example: `if(1 < 2, "yes", "no")` → `"yes"`.
+
+### Array Functions
+
+#### `indexOf(array, item)`
+
+Returns the index of `item` in `array`, or `-1` if not found. Example: `indexOf([1,2,3], 2)` → `1`.
+
+#### `join(array, separator)`
+
+Joins array elements into a string, separated by `separator` (default: `","`). Example: `join([1,2,3], "-")` → `"1-2-3"`.
+
+### Object Functions
+
+#### `valueOf(obj, key)`
+
+Returns the value of `obj[key]`. Example: `valueOf(myObject, "b")`.
+
+### String Functions
+
+#### `startsWith(str, prefix)`
+
+Returns `true` if `str` starts with `prefix`. Example: `startsWith("hello", "he")` → `true`.
+
+#### `endsWith(str, suffix)`
+
+Returns `true` if `str` ends with `suffix`. Example: `endsWith("hello", "lo")` → `true`.
+
+#### `replace(str, search, replacement)`
+
+Replaces all occurrences of `search` in `str` with `replacement`. Example: `replace("foo bar", "bar", "baz")` → `"foo baz"`.
+
+#### `toUpperCase(str)`
+
+Converts `str` to uppercase. Example: `toUpperCase("abc")` → `"ABC"`.
+
+#### `toLowerCase(str)`
+
+Converts `str` to lowercase. Example: `toLowerCase("ABC")` → `"abc"`.
+
+#### `trim(str)`
+
+Removes whitespace from both ends of `str`. Example: `trim("  hello  ")` → `"hello"`.
+
+### Mathematical Functions
+
+#### `min(...args)`
+
+Returns the smallest of the provided numbers. Example: `min(1, 2, 3)` → `1`.
+
+#### `max(...args)`
+
+Returns the largest of the provided numbers. Example: `max(1, 2, 3)` → `3`.
+
+#### `abs(x)`
+
+Returns the absolute value of `x`. Example: `abs(-5)` → `5`.
+
+#### `round(x)`
+
+Rounds `x` to the nearest integer. Example: `round(2.5)` → `3`.
+
+#### `ceil(x)`
+
+Rounds `x` up to the next largest integer. Example: `ceil(2.1)` → `3`.
+
+#### `floor(x)`
+
+Rounds `x` down to the next smallest integer. Example: `floor(2.9)` → `2`.
+
+#### `sqrt(x)`
+
+Returns the square root of `x`. Example: `sqrt(16)` → `4`.
+
+#### `pow(x, y)`
+
+Returns `x` raised to the power of `y`. Example: `pow(2, 3)` → `8`.
+
+#### `random()`
+
+Returns a random number between 0 (inclusive) and 1 (exclusive). Example: `random()` → `0.123456...`.
+
+## API
+
+### `=eval` function
+
+Evaluates the given expression and prints the result.
+
+```javascript
+m(`{{=eval "1 + 2"}}`, {}); // Output: "3"
+```
+
+You can use variables from your data context:
+
+```javascript
+m(`{{=eval "'Hello ' + name"}}`, { name: "World" }); // Output: "Hello World"
+m(`{{=eval "x * y"}}`, { x: 2, y: 3 }); // Output: "6"
+```
+
+### `#when` helper
+
+Renders the block only if the evaluated expression is `true`.
+
+```javascript
+m(`{{#when "x > 1"}}x is greater than 1{{/when}}`, { x: 2 }); // Output: "x is greater than 1"
+m(`{{#when "'foo' == 'bar'"}}This will not render{{/when}}`, {}); // Output: ""
+```
+
+You use variables from your data context:
+
+```javascript
+m(`{{#when "x > 1"}}x is greater than 1{{/when}}`, { x: 2 }); // Output: "x is greater than 1"
+m(`{{#when "x < 1"}}x is less than 1{{/when}}`, { x: 2 }); // Output: ""
+```
+
+## Custom Functions
+
+You can provide your own functions via the plugin options:
+
+```javascript
+const options = mikelEval({
+    functions: {
+        double: x => x * 2,
+    },
+}));
+
+console.log(mikel(`{{=eval "double(5)"}}`, {}, options)); // Output: "10"
+```
+
+## License
+
+Licensed under the [MIT License](../../LICENSE).

package/index.js

@@ -0,0 +1,328 @@
+// @description comparision variables
+const comparationCharacters = ["=", "!", "<", ">", "&", "|"];
+const comparationFunctions = {
+    "===": (a, b) => a === b,
+    "!==": (a, b) => a !== b,
+    "==": (a, b) => a === b,
+    "!=": (a, b) => a !== b,
+    "<=": (a, b) => a <= b,
+    ">=": (a, b) => a >= b,
+    "<": (a, b) => a < b,
+    ">": (a, b) => a > b,
+    "&&": (a, b) => a && b,
+    "||": (a, b) => a || b,
+};
+
+// @description: get a nested object value
+const getIn = (c, p) => {
+    return (p === "." ? c : p.split(".").reduce((x, k) => x?.[k], c));
+};
+
+// parse a next character
+const nextChar = ctx => {
+    ctx.pos = ctx.pos + 1;
+    ctx.current = (ctx.pos < ctx.str.length) ? ctx.str.charAt(ctx.pos) : -1;
+};
+
+// check if the current character is the provided character
+const checkChar = (ctx, ch) =>{
+    while (ctx.current === " ") {
+        nextChar(ctx);
+    }
+    // Check if the current character is the provided character
+    if (ctx.current === ch) {
+        nextChar(ctx);
+        return true;
+    }
+    return false;
+};
+
+// parse a expression: addition or substraaction
+const parseExpression = ctx => {
+    let x = parseTerm(ctx);
+    for (;;) {
+        if (checkChar(ctx, "+")) {
+            x = x + parseTerm(ctx); // addition
+        }
+        else if (checkChar(ctx, "-")) {
+            x = x - parseTerm(ctx); // subtraction
+        }
+        else {
+            return x;
+        }
+    }
+};
+
+// parse a term: multiplication or division
+const parseTerm = ctx => {
+    let x = parseComparison(ctx);
+    for (;;) {
+        if (checkChar(ctx, "*")) {
+            x = x * parseComparison(ctx);
+        }
+        else if (checkChar(ctx, "/")) {
+            x = x / parseComparison(ctx);
+        }
+        else if (checkChar(ctx, "%")) {
+            x = x % parseComparison(ctx);
+        }
+        else {
+            return x;
+        }
+    }
+};
+
+// parse a comparison
+const parseComparison = ctx => {
+    let x = parseFactor(ctx);
+    for(;;) {
+        // save the current starting position
+        const startPos = ctx.pos;
+        if (comparationCharacters.indexOf(ctx.current) !== -1) {
+            while (comparationCharacters.indexOf(ctx.current) !== -1) {
+                nextChar(ctx);
+            }
+            // get the comparison operator
+            const comparator = ctx.str.substring(startPos, ctx.pos)
+            if (typeof comparationFunctions[comparator] !== "function") {
+                throw new Error(`Unknown operator '${comparator}'`);
+            }
+            x = comparationFunctions[comparator](x, parseFactor(ctx));
+        }
+        else {
+            return x;
+        }
+    }
+};
+
+// parse a list of items
+const parseList = ctx => {
+    const items = [];
+    do {
+        items.push(parseExpression(ctx));
+    }
+    while(checkChar(ctx, ","));
+    return items;
+};
+
+// parse a factor
+const parseFactor = ctx => {
+    if (checkChar(ctx, "!")) {
+        return !parseFactor(ctx);
+    }
+    if (checkChar(ctx, "+")) {
+        return parseFactor(ctx);
+    }
+    if (checkChar(ctx, "-")) {
+        return -parseFactor(ctx);
+    }
+    let x;
+    const startPos = ctx.pos;
+    // subexpression
+    if (checkChar(ctx, "(")) { 
+        x = parseExpression(ctx);
+        checkChar(ctx, ")");
+    }
+    else if (checkChar(ctx, "[")) {
+        x = parseList(ctx);
+        checkChar(ctx, "]");
+    }
+    // string factor
+    else if (checkChar(ctx, "'")) {
+        x = "";
+        while(ctx.current !== "'") {
+            x = x + ctx.current;
+            nextChar(ctx);
+        }
+        checkChar(ctx, "'");
+    }
+    // digit
+    else if ((ctx.current >= "0" && ctx.current <= "9") || ctx.current == ".") {
+        while ((ctx.current >= "0" && ctx.current <= "9") || ctx.current == ".") {
+            nextChar(ctx);
+        }
+        x = parseFloat(ctx.str.substring(startPos, ctx.pos));
+    }
+    // values functions
+    else if (ctx.current !== -1 && ctx.current.match(/^[A-Za-z]$/) !== null) {
+        while (ctx.current !== -1 && ctx.current.match(/^[a-zA-Z\[\]'"0-9\.\_]$/) !== null) {
+            nextChar(ctx);
+        }
+        let name = ctx.str.substring(startPos, ctx.pos);
+        if (name === "null" || name === "true" || name === "false") {
+            x = JSON.parse(name); // parse null, true or false
+        }
+        // check if there is a function to apply
+        else if (typeof ctx.functions[name] === "function") {
+            if (!checkChar(ctx, "(")) {
+                throw new Error(`Unexpected character '${ctx.current}' after function name '${name}'`);
+            }
+            const args = parseList(ctx);
+            if (!checkChar(ctx, ")")) {
+                throw new Error(`Unexpected character '${ctx.current}' after function arguments`);
+            }
+            // execute the function and save the value
+            x = ctx.functions[name].apply(null, args);
+        }
+        else {
+            x = getIn(ctx.values, name);
+        }
+    }
+    else {
+        throw new Error(`Unexpected character '${ctx.current}' at position ${ctx.pos}`);
+    }
+    // exponential operator ?
+    if (checkChar(ctx, "^")) {
+        x = Math.pow(x, parseFactor(ctx));
+    }
+    return x;
+};
+
+// @description default functions
+const defaultFunctions = {
+    // common functions
+    len: x => {
+        if (Array.isArray(x) || typeof x === "string") {
+            return x.length;
+        } else if (typeof x === "object" && x !== null) {
+            return Object.keys(x).length;
+        }
+        throw new Error(`len() cannot be applied to type ${typeof x}`);
+    },
+    in: (x, item) => {
+        if (Array.isArray(x) || typeof x === "string") {
+            return x.includes(item);
+        }
+        else if (typeof x === "object" && x !== null) {
+            return Object.values(x).includes(item);
+        }
+        throw new Error(`in() cannot be applied to type ${typeof x}`);
+    },
+    type: x => typeof x,
+    if: (condition, trueValue, falseValue) => {
+        if (typeof condition !== "boolean") {
+            throw new Error(`if() expects a boolean condition, got ${typeof condition}`);
+        }
+        return condition ? trueValue : falseValue;
+    },
+    // array functions
+    indexOf: (array, item) => {
+        if (!Array.isArray(array)) {
+            throw new Error(`indexOf() expects an array, got ${typeof array}`);
+        }
+        return array.indexOf(item);
+    },
+    join: (array, separator = ",") => {
+        if (!Array.isArray(array)) {
+            throw new Error(`join() expects an array, got ${typeof array}`);
+        }
+        return array.join(separator);
+    },
+    // object functions
+    valueOf: (obj, key) => {
+        if (typeof obj !== "object" || obj === null) {
+            throw new Error(`valueOf() expects an object, got ${typeof obj}`);
+        }
+        return obj[key];
+    },
+    // string functions
+    startsWith: (str, prefix) => {
+        if (typeof str !== "string") {
+            throw new Error(`startsWith() expects a string, got ${typeof str}`);
+        }
+        return str.startsWith(prefix);
+    },
+    endsWith: (str, suffix) => {
+        if (typeof str !== "string") {
+            throw new Error(`endsWith() expects a string, got ${typeof str}`);
+        }
+        return str.endsWith(suffix);
+    },
+    replace: (str, search, replacement) => {
+        if (typeof str !== "string") {
+            throw new Error(`replace() expects a string, got ${typeof str}`);
+        }
+        return str.replace(new RegExp(search, "g"), replacement || "");
+    },
+    toUpperCase: str => {
+        if (typeof str !== "string") {
+            throw new Error(`toUpperCase() expects a string, got ${typeof str}`);
+        }
+        return str.toUpperCase();
+    },
+    toLowerCase: str => {
+        if (typeof str !== "string") {
+            throw new Error(`toLowerCase() expects a string, got ${typeof str}`);
+        }
+        return str.toLowerCase();
+    },
+    trim: str => {
+        if (typeof str !== "string") {
+            throw new Error(`trim() expects a string, got ${typeof str}`);
+        }
+        return str.trim();
+    },
+    // mathematical functions
+    min: (...args) => Math.min(...args),
+    max: (...args) => Math.max(...args),
+    abs: x => Math.abs(x),
+    round: x => Math.round(x),
+    ceil: x => Math.ceil(x),
+    floor: x => Math.floor(x),
+    sqrt: x => Math.sqrt(x),
+    pow: (x, y) => Math.pow(x, y),
+    random: () => Math.random(),
+};
+
+// @description: evaluate a string expression
+// @param str {string} the expression to evaluate
+// @param options {object} the options to use
+// @param options.values {object} context where the expression will be evaluated
+// @param options.functions {object} functions to use in the expression
+const evaluate = (str = "", options = {}) => {
+    const context = {
+        pos: 0,
+        current: str.charAt(0) || "",
+        str: str,
+        values: options.values || {},
+        functions: {
+            ...defaultFunctions,
+            ...(options.functions || {}),
+        },
+    };
+    const result = parseExpression(context);
+    if (context.pos < context.str.length) {
+        throw new Error(`Unexpected '${context.current}' at position ${context.pos}`);
+    }
+    return result;
+};
+
+// @description evaluate plugin
+const evaluatePlugin = (options = {}) => {
+    return {
+        functions: {
+            eval: params => {
+                return evaluate(params.args[0], {
+                    values: params.data,
+                    functions: options.functions,
+                });
+            },
+        },
+        helpers: {
+            when: params => {
+                const condition = evaluate(params.args[0], {
+                    values: params.data,
+                    functions: options.functions,
+                });
+                return !!condition ? params.fn(params.data) : "";
+            },
+        },
+    };
+};
+
+// assign additional options for this plugin
+evaluatePlugin.evaluate = evaluate;
+evaluatePlugin.defaultFunctions = defaultFunctions;
+
+// export the evaluate plugin
+export default evaluatePlugin;

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "mikel-eval",
+    "description": "A mikel plugin for evaluating JavaScript expressions.",
+    "version": "0.21.0",
+    "type": "module",
+    "license": "MIT",
+    "author": {
+        "name": "Josemi Juanes",
+        "email": "hello@josemi.xyz"
+    },
+    "repository": "https://github.com/jmjuanes/mikel",
+    "bugs": "https://github.com/jmjuanes/mikel/issues",
+    "exports": {
+        ".": "./index.js",
+        "./index.js": "./index.js",
+        "./package.json": "./package.json"
+    },
+    "scripts": {
+        "test": "node ./test.js"
+    },
+    "files": [
+        "README.md",
+        "index.js"
+    ],
+    "keywords": [
+        "mikel",
+        "plugin",
+        "eval",
+        "evaluate"
+    ]
+}