feat: allow to provide keyword arguments in helpers and functions (#23)

Author: jmjuanes

README.md

@@ -239,6 +239,7 @@ console.log(m("{{#with autor}}{{name}} <{{email}}>{{/with}}", data)); // --> 'Bo
 ### Custom Helpers
 
 > Added in `v0.5.0`.
+> Breaking change introduced in `v0.12.0`.
 
 Custom helpers should be provided as an object in the `options.helpers` field, where each key represents the name of the helper and the corresponding value is a function defining the helper's behavior.
 
@@ -251,8 +252,8 @@ const data = {
 };
 const options = {
     helpers: {
-        customHelper: value => {
-            return `Hello, ${value}!`;
+        customHelper: params => {
+            return `Hello, ${params.args[0]}!`;
         },
     },
 };
@@ -261,8 +262,10 @@ const result = m(template, data, options);
 console.log(result); // Output: "Hello, World!"
 ```
 
-Custom helper functions receive multiple arguments, where the first N arguments are the variables with the helper is called in the template, and the last argument is an options object containing the following keys:
+Custom helper functions receive a single object as argument, containing the following keys:
 
+- `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.
 - `context`: the current context (data) where the helper has been executed.
 - `fn`: a function that executes the template provided in the helper block and returns a string with the evaluated template in the provided context.
 
@@ -278,8 +281,8 @@ const data = {
 };
 const options = {
     helpers: {
-        customEach: (items, opt) => {
-            return items.map((item, index) => opt.fn({ ...item, index: index})).join("");
+        customEach: ({args, fn}) => {
+            return args[0].map((item, index) => fn({ ...item, index: index})).join("");
         },
     },
 };
@@ -343,11 +346,18 @@ The `@last` variable allows to check if the current iteration using the `#each`
 ### Functions
 
 > Added in `v0.8.0`.
+> Breaking change introduced in `v0.12.0`.
 
 Mikel allows users to define custom functions that can be used within templates to perform dynamic operations. Functions can be invoked in the template using the `=` character, followed by the function name and the variables to be provided to the function. Variables should be separated by spaces.
 
 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:
+
+- `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.
+- `context`: the current context (data) where the function has been executed.
+
 Example:
 
 ```javascript
@@ -359,8 +369,8 @@ const data = {
 };
 const options = {
     functions: {
-        fullName: (firstName, lastName) => {
-            return `${firstName} ${lastName}`;
+        fullName: ({args}) => {
+            return `${args[0]} ${args[1]}`;
         }
     },
 };
@@ -369,8 +379,6 @@ const result = m("My name is: {{=fullName user.firstName user.lastName}}", data,
 console.log(result); // --> "My name is: John Doe"
 ```
 
-In this example, the custom function `fullName` is defined to take two arguments, `firstName` and `lastName`, and return the full name. The template then uses this function to concatenate and render the full name.
-
 
 ## API
 

index.js

@@ -11,6 +11,18 @@ const escape = s => s.toString().replace(/[&<>\"']/g, m => escapedChars[m]);
 
 const get = (c, p) => (p === "." ? c : p.split(".").reduce((x, k) => x?.[k], c)) ?? "";
 
+// @description parse string arguments
+const parseArgs = (argString = "", context = {}, vars = {}) => {
+    const [t, ...args] = argString.trim().match(/(?:[^\s"]+|"[^"]*")+/g);
+    const argv = args.filter(a => !a.includes("=")).map(a => parse(a, context, vars));
+    const opt = Object.fromEntries(args.filter(a => a.includes("=")).map(a => {
+        const [k, v] = a.split("=");
+        return [k, parse(v, context, vars)];
+    }));
+    return [t, argv, opt];
+};
+
+// @description parse a string value to a native type
 const parse = (v, context = {}, vars = {}) => {
     if ((v.startsWith(`"`) && v.endsWith(`"`)) || /^-?\d+\.?\d*$/.test(v) || v === "true" || v === "false" || v === "null") {
         return JSON.parse(v);
@@ -64,10 +76,11 @@ const create = (template = "", options = {}) => {
                 output.push(get(context, tokens[i].slice(1).trim()));
             }
             else if (tokens[i].startsWith("#") && typeof helpers[tokens[i].slice(1).trim().split(" ")[0]] === "function") {
-                const [t, ...args] = tokens[i].slice(1).trim().match(/(?:[^\s"]+|"[^"]*")+/g);
+                const [t, args, opt] = parseArgs(tokens[i].slice(1), context, vars);
                 const j = i + 1;
                 output.push(helpers[t]({
-                    args: args.map(v => parse(v, context, vars)),
+                    args: args,
+                    opt: opt,
                     context: context,
                     fn: (blockContext = {}, blockVars = {}, blockOutput = []) => {
                         i = compile(tokens, blockOutput, blockContext, {...vars, ...blockVars, root: vars.root}, j, t);
@@ -101,12 +114,9 @@ const create = (template = "", options = {}) => {
                 }
             }
             else if (tokens[i].startsWith("=")) {
-                const [t, ...args] = tokens[i].slice(1).trim().match(/(?:[^\s"]+|"[^"]*")+/g);
+                const [t, args, opt] = parseArgs(tokens[i].slice(1), context, vars);
                 if (typeof functions[t] === "function") {
-                    output.push(functions[t]({
-                        args: args.map(v => parse(v, context, vars)),
-                        context: context,
-                    }) || "");
+                    output.push(functions[t]({args, opt, context}) || "");
                 }
             }
             else if (tokens[i].startsWith("/")) {

test.js

@@ -255,6 +255,15 @@ describe("templating", () => {
             assert.equal(m(`{{#customEqual value "no"}}Yes!!{{/customEqual}}`, {value: "yes"}, options), "");
             assert.equal(m(`{{#customEqual value false}}Yes!!{{/customEqual}}`, {value: "yes"}, options), "");
         });
+
+        it("should allow to provide keyword arguments", () => {
+            const options = {
+                helpers: {
+                    concat: params => params.args.join(params.opt.delimiter || " "),
+                },
+            };
+            assert.equal(m(`{{#concat a b delimiter=","}}{{/concat}}`, {a: "hello", b: "world"}, options), "hello,world");
+        });
     });
 
     describe("{{@root}}", () => {
@@ -285,7 +294,7 @@ describe("templating", () => {
         const options = {
             functions: {
                 toUpperCase: params => params.args[0].toUpperCase(),
-                concat: params => params.args.join(" "),
+                concat: params => params.args.join(params.opt.delimiter || " "),
             },
         };
 
@@ -308,6 +317,25 @@ describe("templating", () => {
         it("should allow to execute funcions inside helpers blocks", () => {
             assert.equal(m(`{{#each names}}{{=toUpperCase .}}, {{/each}}`, {names: ["bob", "susan"]}, options), "BOB, SUSAN, ");
         });
+
+        it("should support keywods in function arguments", () => {
+            assert.equal(m(`{{=concat a b delimiter=","}}`, {a: "Hello", b: "World"}, options), "Hello,World");
+        });
+
+        it("should support context variables as keyword arguments", () => {
+            const data = {
+                name: "Bob",
+                surname: "Doe",
+            };
+            const options = {
+                functions: {
+                    sayWelcome: ({args, opt}) => {
+                        return `Welcome, ${[args[0], opt.surname || ""].filter(Boolean).join(" ")}`;
+                    },
+                },
+            };
+            assert.equal(m("{{=sayWelcome name surname=surname}}", data, options), "Welcome, Bob Doe");
+        });
     });
 });