mikel 0.28.0 → 0.30.0

package/README.md

@@ -433,10 +433,10 @@ const result = m(template, data, options);
 console.log(result); // Output: "Hello, World!"
 ```
 
-Custom helper functions receive a single object as argument, containing the following keys:
+Custom helper functions receive a single `params` object as argument, containing the following fields:
 
 - `args`: an array containing the variables with the helper is called in the template.
-- `opt`: an object containing the keyword arguments provided to the helper.
+- `options`: an object containing the keyword arguments provided to the helper.
 - `data`: the current data where the helper has been executed.
 - `variables`: an object containing the runtime variables available in the current context (e.g., `@root`, `@index`, etc.).
 - `fn`: a function that executes the template provided in the helper block and returns a string with the evaluated template in the provided context.
@@ -562,10 +562,10 @@ Mikel allows users to define custom functions that can be used within templates
 
 Functions should be provided in the `options.functions` field of the options object when rendering a template. Each function is defined by a name and a corresponding function that performs the desired operation.
 
-Functions will receive a single object as argument, containing the following keys:
+Functions will receive a single `params` object as argument, containing the following keys:
 
 - `args`: an array containing the variables with the function is called in the template.
-- `opt`: an object containing the keyword arguments provided to the function.
+- `options`: an object containing the keyword arguments provided to the function.
 - `data`: the current data object where the function has been executed.
 - `variables`: an object containing the runtime variables available in the current context (e.g., `@root`, `@index`, etc.).
 
@@ -592,7 +592,7 @@ console.log(result); // --> "My name is: John Doe"
 
 #### Expand function arguments using the spread operator
 
-> This feature was addedin `v0.20.0`.
+> This feature was added in `v0.20.0`.
 
 You can use the spread operator `...` to expand the arguments of a function. This allows you to pass an array of values as individual arguments to the function, or to pass an object as keyword arguments.
 
@@ -632,7 +632,7 @@ const data = {
 const options = {
     functions: {
         fullName: params => {
-            return `${params.opt.firstName} ${params.opt.lastName}`;
+            return `${params.options.firstName} ${params.options.lastName}`;
         }
     },
 };
@@ -641,6 +641,66 @@ const result = m("Users: {{=fullName ...user1}} and {{=fullName ...user2}}", dat
 console.log(result); // --> "Users: John Doe and Alice Smith"
 ```
 
+Of course, Jose — here’s a version of the **Subexpressions** documentation written to perfectly match the tone, structure, and formatting conventions of the current README.  
+It follows the same patterns: short intro, version note, examples, concise explanations, no extra fluff.
+
+### Subexpressions  
+
+> Added in `v0.30.0`.
+
+Subexpressions allow you to evaluate a function call inside another function call. They are written using parentheses, and can be used anywhere a normal function argument is allowed. Example:
+
+```hbs
+{{=sum (sum 3 4) 3}}
+```
+
+In this example, the inner expression is evaluated first:
+
+- `(sum 3 4)` → `7`  
+- `sum 7 3` → `10`
+
+Result:
+
+```
+10
+```
+
+#### Nested subexpressions
+
+Subexpressions can be nested to any depth:
+
+```hbs
+{{=sum (sum 1 (sum 2 3)) 4}}
+```
+
+#### Using strings inside subexpressions
+
+Strings behave the same way inside subexpressions, including quoted strings with spaces:
+
+```hbs
+{{=concat "Hello " (upper name)}}
+```
+
+If `name = "world"`:
+
+```
+Hello WORLD
+```
+
+#### Variables inside subexpresspressions
+
+You can reference variables or paths normally:
+
+```hbs
+{{=sum (sum price tax) shipping}}
+```
+
+#### Limitations
+
+- Subexpressions are currently supported **only for functions** (`{{=...}}`).
+- Subexpressions inside helper arguments are not yet supported.
+- Parentheses must be balanced; malformed expressions will throw an error.
+
 
 ## API
 

package/index.d.ts

@@ -1,6 +1,7 @@
 export type MikelHelper = (params: {
     args: any[];
-    opt: Record<string, any>;
+    opt?: Record<string, any>;
+    options: Record<string, any>;
     tokens: string[];
     data: Record<string, any>;
     variables: Record<string, any>;
@@ -14,7 +15,8 @@ export type MikelPartial = {
 
 export type MikelFunction = (params: {
     args: any[];
-    opt: Record<string, any>;
+    opt?: Record<string, any>;
+    options: Record<string,any>;
     data: Record<string, any>;
     variables: Record<string, any>;
 }) => string | void;

package/index.js

@@ -26,29 +26,80 @@ const untokenize = (ts = [], s = "{{", e = "}}") => {
     return ts.length > 0 ? ts.reduce((p, t, i) => p + (i % 2 === 0 ? e : s) + t) : "";
 };
 
+// @description tokenize args
+const tokenizeArgs = (str = "", tokens = [], strings = []) => {
+    let current = "", depth = 0;
+    // 1. replace strings
+    str = str.replace(/"([^"\\]|\\.)*"/g, (match) => {
+        const id = `__STR${strings.length}__`;
+        strings.push(match);
+        return id;
+    });
+    // 2. tokenize arguments
+    for (let i = 0; i < str.length; i++) {
+        const c = str[i];
+        if (c === "(") {
+            depth++;
+            current = current + c;
+        } else if (c === ")") {
+            depth--;
+            current = current + c;
+        } else if (c === " " && depth === 0) {
+            if (current.trim()) {
+                tokens.push(current.trim());
+            }
+            current = "";
+        } else {
+            current = current + c;
+        }
+    }
+    // 3. add current token
+    if (current.trim()) {
+        tokens.push(current.trim());
+    }
+    // 4. replace strings back and return parsed tokens
+    return tokens.map(token => {
+        return token.replace(/__STR(\d+)__/g, (_, i) => strings[i]);
+    });
+};
+
 // @description parse string arguments
-const parseArgs = (str = "", data = {}, vars = {}, argv = [], opt = {}) => {
-    const [t, ...args] = str.trim().match(/(?:[^\s"]+|"[^"]*")+/g);
+const parseArgs = (str = "", data = {}, vars = {}, fns = {}, argv = [], opt = {}) => {
+    const [t, ...args] = tokenizeArgs(str.trim());
     args.forEach(argStr => {
         if (argStr.includes("=") && !argStr.startsWith(`"`)) {
             const [k, v] = argStr.split("=");
-            opt[k] = parse(v, data, vars);
+            opt[k] = parse(v, data, vars, fns);
         }
         else if (argStr.startsWith("...")) {
-            const value = parse(argStr.replace(/^\.{3}/, ""), data, vars);
+            const value = parse(argStr.replace(/^\.{3}/, ""), data, vars, fns);
             if (!!value && typeof value === "object") {
                 Array.isArray(value) ? argv.push(...value) : Object.assign(opt, value);
             }
         }
         else {
-            argv.push(parse(argStr, data, vars));
+            argv.push(parse(argStr, data, vars, fns));
         }
     });
     return [t, argv, opt];
 };
 
+// @description evaluate an expression
+const evaluateExpression = (str = "", data = {}, vars = {}, fns = {}) => {
+    const [ fnName, args, opt ] = parseArgs(str, data, vars, fns);
+    if (typeof fns[fnName] === "function") {
+        return fns[fnName]({args, opt, options: opt, data, variables: vars});
+    }
+    // if no function has been found with this name
+    // throw new Error(`Unknown function '${fnName}'`);
+    return "";
+};
+
 // @description parse a string value to a native type
-const parse = (v, data = {}, vars = {}) => {
+const parse = (v, data = {}, vars = {}, fns = {}) => {
+    if (v.startsWith("(") && v.endsWith(")")) {
+        return evaluateExpression(v.slice(1, -1).trim(), data, vars, fns);
+    }
     if ((v.startsWith(`"`) && v.endsWith(`"`)) || /^-?\d+\.?\d*$/.test(v) || v === "true" || v === "false" || v === "null") {
         return JSON.parse(v);
     }
@@ -75,9 +126,17 @@ const findClosingToken = (tokens, i, token) => {
 const defaultHelpers = {
     "each": p => {
         const items = typeof p.args[0] === "object" ? Object.entries(p.args[0] || {}) : [];
-        const limit = Math.min(items.length - (p.opt.skip || 0), p.opt.limit || items.length);
-        return items.slice(p.opt.skip || 0, (p.opt.skip || 0) + limit)
-            .map((item, index) => p.fn(item[1], {index: index, key: item[0], value: item[1], first: index === 0, last: index === items.length - 1}))
+        const limit = Math.min(items.length - (p.options?.skip || 0), p.options?.limit || items.length);
+        return items.slice(p.options?.skip || 0, (p.options?.skip || 0) + limit)
+            .map((item, index) => {
+                return p.fn(item[1], {
+                    index: index, 
+                    key: item[0],
+                    value: item[1],
+                    first: index === 0,
+                    last: index === items.length - 1,
+                });
+            })
             .join("");
     },
     "if": p => !!p.args[0] ? p.fn(p.data) : "",
@@ -181,10 +240,7 @@ const create = (options = {}) => {
                 }
             }
             else if (tokens[i].startsWith("=")) {
-                const [t, args, opt] = parseArgs(tokens[i].slice(1), data, vars);
-                if (typeof ctx.functions[t] === "function") {
-                    output.push(ctx.functions[t]({args, opt, data, variables: vars}) || "");
-                }
+                output.push(evaluateExpression(tokens[i].slice(1), data, vars, ctx.functions) ?? "");
             }
             else if (tokens[i].startsWith("/")) {
                 if (tokens[i].slice(1).trim() !== section) {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "mikel",
     "description": "Micro templating library with zero dependencies",
-    "version": "0.28.0",
+    "version": "0.30.0",
     "type": "module",
     "author": {
         "name": "Josemi Juanes",