mikel 0.29.0 → 0.30.1

package/README.md

@@ -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.
 
@@ -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.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);
     }
@@ -189,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, options: 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.29.0",
+    "version": "0.30.1",
     "type": "module",
     "author": {
         "name": "Josemi Juanes",