mikel 0.6.0 → 0.8.0

package/README.md

@@ -214,7 +214,7 @@ const data = {
 };
 const options = {
     helpers: {
-        customHelper: ({context, value, key, options, fn}) => {
+        customHelper: value => {
             return `Hello, ${value}!`;
         },
     },
@@ -224,21 +224,38 @@ const result = m(template, data, options);
 console.log(result); // Output: "Hello, World!"
 ```
 
-Custom helper functions receive a single object parameter containing the following fields:
+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:
 
-- `context`: The current context (data) where the helper has been executed.
-- `value`: The current value passed to the helper.
-- `key`: The field used to extract the value from the current context.
-- `options`: The global options object.
-- `fn`: A function that executes the template provided in the helper block and returns a string with the evaluated template in the provided context.
+- `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.
 
-The helper function must return a string, which will be injected into the result string.
+The helper function must return a string, which will be injected into the result string. Example:
 
-### Variables
+```javascript
+const data = {
+    items: [
+        { name: "John" },
+        { name: "Alice" },
+        { name: "Bob" },
+    ],
+};
+const options = {
+    helpers: {
+        customEach: (items, opt) => {
+            return items.map((item, index) => opt.fn({ ...item, index: index})).join("");
+        },
+    },
+};
+
+const result = m("{{#customEach items}}{{index}}: {{name}}, {{/customEach}}", data, options);
+console.log(result); // --> "0: John, 1: Alice, 2: Bob,"
+```
+
+### Runtime Variables
 
 > Added in `v0.4.0`.
 
-Data Variables in Mikel provide convenient access to special values within your templates. These variables, denoted by the `@` symbol, allow users to interact with specific data contexts or values.
+Runtime Variables in Mikel provide convenient access to special values within your templates. These variables, denoted by the `@` symbol, allow users to interact with specific data contexts or values at runtime. Runtime variables are usually generated by helpers like `#each`.
 
 #### @root
 
@@ -266,9 +283,29 @@ The `@key` variable allows users to retrieve the current key of the object entry
 
 The `@value` variable allows users to retrieve the current value of the object entry when iterating over an object using the `#each` helper. It simplifies access to object values for dynamic rendering and data manipulation.
 
-### Custom variables
+#### @first
+
+> Added in `v0.7.0`.
+
+The `@first` variable allows to check if the current iteration using the `#each` helper is the first item in the array or object.
+
+```
+{{#each items}} {{.}}: {{#if @first}}first item!{{/if}}{{#unless @first}}not first{{/if}} {{/each}}
+```
+
+#### @last
+
+> Added in `v0.7.0`.
+
+The `@last` variable allows to check if the current iteration using the `#each` helper is the last item in the array or object.
 
-> Added in `v0.5.0`
+```
+{{#each items}}{{@index}}:{{.}} {{#unless @last}},{{/unless}}{{/each}}
+```
+
+### Custom runtime variables
+
+> Added in `v0.5.0`.
 
 Mikel allows users to define custom data variables, providing enhanced flexibility and customization options for templates. These custom data variables can be accessed within the template using the `@` character.
 
@@ -287,18 +324,51 @@ console.log(result); // --> 'Hello, World!'
 
 In this example, the custom data variable `customVariable` is defined with the value `"World"`, and it can be accessed in the template using `@customVariable`.
 
+### Functions
+
+> Added in `v0.8.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.
+
+Example:
+
+```javascript
+const data = {
+    user: {
+        firstName: "John",
+        lastName: "Doe",
+    },
+};
+const options = {
+    functions: {
+        fullName: (firstName, lastName) => {
+            return `${firstName} ${lastName}`;
+        }
+    },
+};
+
+const result = m("My name is: {{=fullName user.firstName user.lastName}}", data, options);
+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
 
 ### `mikel(template, data[, options])`
 
-Render the given template string with the provided data object.
+Render the given template string with the provided data object and options.
 
-- `template` (string): The Mustache template string.
-- `data` (object): The data object containing the values to render.
-- `options` (object): An object containing the following optional values:
-    - `partials` (object): An object containing the available partials.
-    - `variables` (object): An object containing custom data variables.
-    - `helpers` (object): An object containing custom helpers.
+- `template` (string): the template string.
+- `data` (object): the data object containing the values to render.
+- `options` (object): an object containing the following optional values:
+    - `partials` (object): an object containing the available partials.
+    - `variables` (object): an object containing custom data variables.
+    - `helpers` (object): an object containing custom helpers.
+    - `functions` (object): and object containing custom functions.
 
 Returns: A string with the rendered output.
 

package/index.js

@@ -12,16 +12,16 @@ const escape = s => s.toString().replace(/[&<>\"']/g, m => escapedChars[m]);
 const get = (c, p) => (p === "." ? c : p.split(".").reduce((x, k) => x?.[k], c)) ?? "";
 
 const defaultHelpers = {
-    "each": ({value, fn}) => {
+    "each": (value, opt) => {
         return (typeof value === "object" ? Object.entries(value || {}) : [])
-            .map((item, index) => fn(item[1], {index: index, key: item[0], value: item[1]}))
+            .map((item, index, items) => opt.fn(item[1], {index: index, key: item[0], value: item[1], first: index === 0, last: index === items.length - 1}))
             .join("");
     },
-    "if": ({value, fn, context}) => !!value ? fn(context) : "",
-    "unless": ({value, fn, context}) => !!!value ? fn(context) : "",
+    "if": (value, opt) => !!value ? opt.fn(opt.context) : "",
+    "unless": (value, opt) => !!!value ? opt.fn(opt.context) : "",
 };
 
-const compile = (tokens, output, context, partials, helpers, vars, index = 0, section = "") => {
+const compile = (tokens, output, context, partials, helpers, vars, fn = {}, index = 0, section = "") => {
     let i = index;
     while (i < tokens.length) {
         if (i % 2 === 0) {
@@ -34,20 +34,18 @@ const compile = (tokens, output, context, partials, helpers, vars, index = 0, se
             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, v] = tokens[i].slice(1).trim().split(" ");
+            const [t, ...args] = tokens[i].slice(1).trim().split(" ");
             const j = i + 1;
-            output.push(helpers[t]({
+            output.push(helpers[t](...args.map(v => (v || "").startsWith("@") ? get(vars, v.slice(1)) : get(context, v || ".")), {
                 context: context,
-                key: v || ".",
-                value: get(context, v || "."),
                 fn: (blockContext = {}, blockVars = {}, blockOutput = []) => {
-                    i = compile(tokens, blockOutput, blockContext, partials, helpers, {...vars, ...blockVars, root: vars.root}, j, t);
+                    i = compile(tokens, blockOutput, blockContext, partials, helpers, {...vars, ...blockVars, root: vars.root}, fn, j, t);
                     return blockOutput.join("");
                 },
             }));
-            // Make sure that this block has been executed
+            // Make sure that this block is executed at least once
             if (i + 1 === j) {
-                i = compile(tokens, [], {}, partials, helpers, vars, j, t);
+                i = compile(tokens, [], {}, {}, {}, {}, {}, j, t);
             }
         }
         else if (tokens[i].startsWith("#") || tokens[i].startsWith("^")) {
@@ -57,18 +55,24 @@ const compile = (tokens, output, context, partials, helpers, vars, index = 0, se
             if (!negate && value && Array.isArray(value)) {
                 const j = i + 1;
                 (value.length > 0 ? value : [""]).forEach(item => {
-                    i = compile(tokens, value.length > 0 ? output : [], item, partials, helpers, vars, j, t);
+                    i = compile(tokens, value.length > 0 ? output : [], item, partials, helpers, vars, fn, j, t);
                 });
             }
             else {
                 const includeOutput = (!negate && !!value) || (negate && !!!value);
-                i = compile(tokens, includeOutput ? output : [], context, partials, helpers, vars, i + 1, t);
+                i = compile(tokens, includeOutput ? output : [], context, partials, helpers, vars, fn, i + 1, t);
             }
         }
         else if (tokens[i].startsWith(">")) {
             const [t, v] = tokens[i].slice(1).trim().split(" ");
             if (typeof partials[t] === "string") {
-                compile(partials[t].split(tags), output, v ? get(context, v) : context, partials, helpers, vars, 0, "");
+                compile(partials[t].split(tags), output, v ? get(context, v) : context, partials, helpers, vars, fn, 0, "");
+            }
+        }
+        else if (tokens[i].startsWith("=")) {
+            const [t, ...args] = tokens[i].slice(1).trim().split(" ");
+            if (typeof fn[t] === "function") {
+                output.push(fn[t](...args.map(v => (v || "").startsWith("@") ? get(vars, v.slice(1)) : get(context, v || "."))) || "");
             }
         }
         else if (tokens[i].startsWith("/")) {
@@ -90,7 +94,7 @@ const mikel = (str, context = {}, opt = {}, output = []) => {
     const partials = Object.assign({}, opt.partials || {});
     const helpers = Object.assign({}, defaultHelpers, opt.helpers || {});
     const variables = Object.assign({}, opt.variables || {}, {root: context});
-    compile(str.split(tags), output, context, partials, helpers, variables, 0, "");
+    compile(str.split(tags), output, context, partials, helpers, variables, opt.functions || {}, 0, "");
     return output.join("");
 };
 

package/package.json

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