mikel 0.11.1 → 0.13.0

package/README.md

@@ -110,6 +110,27 @@ const result = m("User: {{> user currentUser}}", data, {partials});
 // Output: 'User: John Doe <john@example.com>'
 ```
 
+#### Keyword arguments in partials
+
+> This feature was added in `v0.13.0`.
+
+You can provide keyword arguments in partials to generate a new context object using the provided keywords.
+
+```javascript
+const data = {
+    name: "John Doe",
+    email: "john@example.com",
+};
+const partials = {
+    user: "{{userName}} <{{userEmail}}>",
+};
+
+const result = m("User: {{>user userName=name userEmail=email }}", data, {partials});
+// Output: 'User: John Doe <john@example.com>'
+```
+
+Please note that providing keyword arguments and a custom context to a partial is not supported. On this situation, the partial will be evaluated only with the custom context.
+
 ### Built-in helpers
 
 > Added in `v0.4.0`.
@@ -167,6 +188,17 @@ const data = {
 console.log(m("{{#each values}}{{@key}}: {{@value}}, {{/each}}", data)); // --> 'foo: 0, bar: 1, '
 ```
 
+The `each` helper also supports the following options, provided as keyword arguments:
+- `skip`: number of first items to skip (default is `0`).
+- `limit`: allows to limit the number of items to display (default equals to the length of the items list).
+
+Example:
+
+```javascript
+console.log(m("{{each values limit=2}}{{.}}{{/each}}", {values: [0, 1, 2, 3]})); // --> '01'
+```
+
+
 #### if
 
 The `if` helper renders the block only if the condition is truthy.
@@ -239,6 +271,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 +284,8 @@ const data = {
 };
 const options = {
     helpers: {
-        customHelper: value => {
-            return `Hello, ${value}!`;
+        customHelper: params => {
+            return `Hello, ${params.args[0]}!`;
         },
     },
 };
@@ -261,8 +294,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 +313,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 +378,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 +401,8 @@ const data = {
 };
 const options = {
     functions: {
-        fullName: (firstName, lastName) => {
-            return `${firstName} ${lastName}`;
+        fullName: ({args}) => {
+            return `${args[0]} ${args[1]}`;
         }
     },
 };
@@ -369,8 +411,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
 

package/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);
@@ -32,16 +44,18 @@ const frontmatter = (str = "", parser = null) => {
 
 // @description default helpers
 const defaultHelpers = {
-    "each": (value, opt) => {
-        return (typeof value === "object" ? Object.entries(value || {}) : [])
-            .map((item, index, items) => opt.fn(item[1], {index: index, key: item[0], value: item[1], first: index === 0, last: index === items.length - 1}))
+    "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}))
             .join("");
     },
-    "if": (value, opt) => !!value ? opt.fn(opt.context) : "",
-    "unless": (value, opt) => !!!value ? opt.fn(opt.context) : "",
-    "eq": (a, b, opt) => a === b ? opt.fn(opt.context) : "",
-    "ne": (a, b, opt) => a !== b ? opt.fn(opt.context) : "",
-    "with": (value, opt) => opt.fn(value),
+    "if": p => !!p.args[0] ? p.fn(p.context) : "",
+    "unless": p => !!!p.args[0] ? p.fn(p.context) : "",
+    "eq": p => p.args[0] === p.args[1] ? p.fn(p.context) : "",
+    "ne": p => p.args[0] !== p.args[1] ? p.fn(p.context) : "",
+    "with": p => p.fn(p.args[0]),
 };
 
 // @description create a new instance of mikel
@@ -64,9 +78,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.map(v => parse(v, context, vars)), {
+                output.push(helpers[t]({
+                    args: args,
+                    opt: opt,
                     context: context,
                     fn: (blockContext = {}, blockVars = {}, blockOutput = []) => {
                         i = compile(tokens, blockOutput, blockContext, {...vars, ...blockVars, root: vars.root}, j, t);
@@ -94,15 +110,16 @@ const create = (template = "", options = {}) => {
                 }
             }
             else if (tokens[i].startsWith(">")) {
-                const [t, v] = tokens[i].slice(1).trim().split(" ");
+                const [t, args, opt] = parseArgs(tokens[i].slice(1), context, vars);
                 if (typeof partials[t] === "string") {
-                    compile(partials[t].split(tags), output, v ? get(context, v) : context, vars, 0, "");
+                    const newCtx = args.length > 0 ? args[0] : (Object.keys(opt).length > 0 ? opt : context);
+                    compile(partials[t].split(tags), output, newCtx, vars, 0, "");
                 }
             }
             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.map(v => parse(v, context, vars))) || "");
+                    output.push(functions[t]({args, opt, context}) || "");
                 }
             }
             else if (tokens[i].startsWith("/")) {

package/package.json

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