mikel 0.3.2 → 0.5.0

package/README.md

@@ -68,7 +68,9 @@ const result = m("{{^isAdmin}}You are not Admin{{/isAdmin}}", data);
 // Output: 'You are not Admin'
 ```
 
-### Partials (added in v0.3.0)
+### Partials 
+
+> This feature was added in `v0.3.0`
 
 Partials allow you to include separate templates within your main template. Use the greater than symbol `>` followed by the partial name inside double curly braces `{{> partialName }}`.
 
@@ -87,7 +89,9 @@ const result = m("{{> hello}}", data, {partials});
 // Output: 'Hello Bob!'
 ```
 
-#### Custom context in partials (added in v0.3.1)
+#### Custom context in partials
+
+> This feature was added in `v0.3.1`.
 
 You can provide a custom context for the partial by specifying a field of the data: `{{> partialName dataField}}`.
 
@@ -106,6 +110,183 @@ const result = m("User: {{> user currentUser}}", data, {partials});
 // Output: 'User: John Doe <john@example.com>'
 ```
 
+### Built-in helpers
+
+> Added in `v0.4.0`.
+
+Helpers allows you to execute special functions within blocks or sections of your template. Mikel currently supports the following built-in helpers:
+
+#### each
+
+The `each` helper iterates over an array and renders the block for each item in the array.
+
+Syntax: `{{#each arrayName}} ... {{/each}}`.
+
+Example:
+
+```javascript
+const data = {
+    users: ["John", "Alice", "Bob"],
+};
+
+console.log(m("{{#each users}}{{.}}, {{/each}}", data)); // --> 'John, Alice, Bob, '
+```
+
+When looping throug arrays, you can use the variable `@index` to access to the current index of the item in the array:
+
+```javascript
+const data = {
+    users: ["John", "Alice", "Bob"],
+};
+
+console.log(m("{{#each users}}{{@index}}: {{.}}, {{/each}}", data)); // --> '0: John, 1: Alice, 2: Bob, '
+```
+
+The `each` helper can also iterate over objects:
+
+```javascript
+const data = {
+    values: {
+        foo: "bar",
+    },
+};
+
+console.log(m("{{#each values}}{{.}}{{/each}}", data)); // --> 'bar'
+```
+
+When looping throug objects, you can use the variable `@key` to access to the current key in the object, and the variable `@value` to access to the corresponding value:
+
+```javascript
+const data = {
+    values: {
+        foo: "0",
+        bar: "1",
+    },
+};
+
+console.log(m("{{#each values}}{{@key}}: {{@value}}, {{/each}}", data)); // --> 'foo: 0, bar: 1, '
+```
+
+#### if
+
+The `if` helper renders the block only if the condition is truthy.
+
+Syntax: `{{#if condition}} ... {{/if}}`
+
+Example:
+
+```javascript
+const data = {
+    isAdmin: true,
+};
+
+console.log(m("{{#if isAdmin}}Hello admin{{/if}}", data)); // --> 'Hello admin'
+```
+
+#### unless
+
+The `unless` helper renders the block only if the condition is falsy.
+
+Syntax: `{{#unless condition}} ... {{/unless}}`
+
+Example:
+
+```javascript
+const data = {
+    isAdmin: false,
+};
+
+console.log(m("{{#unless isAdmin}}Hello guest{{/unless}}", data)); // --> 'Hello guest'
+```
+
+### Custom Helpers
+
+> Added in `v0.5.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.
+
+Example:
+
+```javascript
+const template = "{{#greeting name}}{{/greeting}}";
+const data = {
+    name: "World!",
+};
+const options = {
+    helpers: {
+        customHelper: ({context, value, key, options, fn}) => {
+            return `Hello, ${value}!`;
+        },
+    },
+};
+
+const result = m(template, data, options);
+console.log(result); // Output: "Hello, World!"
+```
+
+Custom helper functions receive a single object parameter containing the following fields:
+
+- `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.
+
+The helper function must return a string, which will be injected into the result string.
+
+### 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.
+
+#### @root
+
+The `@root` variable grants access to the root data context provided to the template. It is always defined and enables users to retrieve values from the top-level data object.
+
+Example:
+
+```javascript
+const data = {
+    name: "World",
+};
+
+console.log(m("Hello, {{@root.name}}!", data)); // -> 'Hello, World!'
+```
+
+#### @index
+
+The `@index` variable facilitates access to the current index of the item when iterating over an array using the `#each` helper. It aids in dynamic rendering and indexing within loops.
+
+#### @key
+
+The `@key` variable allows users to retrieve the current key of the object entry when looping through an object using the `#each` helper. It provides access to object keys for dynamic rendering and customization.
+
+#### @value
+
+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
+
+> 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.
+
+Custom data variables should be provided in the `options.variables` field of the options object when rendering a template. Each custom data variable should be defined as a key-value pair, where the key represents the variable name and the value represents the data associated with that variable.
+
+Example:
+
+```javascript
+const result = m("Hello, {{@customVariable}}!", {}, {
+    variables: {
+        customVariable: "World",
+    },
+});
+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`.
+
 ## API
 
 ### `m(template, data[, options])`
@@ -116,6 +297,8 @@ Render the given template string with the provided data object.
 - `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.
 
 Returns: A string with the rendered output.
 

package/index.js

@@ -7,42 +7,72 @@ const escapedChars = {
     "'": "'",
 };
 
-const escape = str => {
-    return str.toString().replace(/[&<>\"']/g, m => escapedChars[m]);
-};
+const escape = s => s.toString().replace(/[&<>\"']/g, m => escapedChars[m]);
 
-const get = (ctx, path) => {
-    return path === "." ? ctx : (path.split(".").reduce((p, k) => p?.[k], ctx) || "");
-};
+const get = (c, p) => (p === "." ? c : p.split(".").reduce((x, k) => x?.[k], c)) ?? "";
+
+const helpers = new Map(Object.entries({
+    "each": ({value, fn}) => {
+        return (typeof value === "object" ? Object.entries(value || {}) : [])
+            .map((item, index) => fn(item[1], {index: index, key: item[0], value: item[1]}))
+            .join("");
+    },
+    "if": ({value, fn, context}) => !!value ? fn(context) : "",
+    "unless": ({value, fn, context}) => !!!value ? fn(context) : "",
+}));
+
+const hasHelper = (n, o) => helpers.has(n) || typeof o?.helpers?.[n] === "function";
+const getHelper = (n, o) => helpers.get(n) || o?.helpers?.[n];
 
-const compile = (tokens, output, ctx, opt, index, section) => {
+const compile = (tokens, output, context, opt, index = 0, section = "", vars = {}) => {
     let i = index;
     while (i < tokens.length) {
         if (i % 2 === 0) {
             output.push(tokens[i]);
         }
+        else if (tokens[i].startsWith("@")) {
+            output.push(get({...(opt?.variables), ...vars}, tokens[i].slice(1).trim() ?? "_") ?? "");
+        }
         else if (tokens[i].startsWith("!")) {
-            output.push(get(ctx, tokens[i].slice(1).trim()));
+            output.push(get(context, tokens[i].slice(1).trim()));
+        }
+        else if (tokens[i].startsWith("#") && hasHelper(tokens[i].slice(1).trim().split(" ")[0], opt)) {
+            const [t, v] = tokens[i].slice(1).trim().split(" ");
+            const j = i + 1;
+            output.push(getHelper(t, opt)({
+                context: context,
+                key: v || ".",
+                value: get(context, v || "."),
+                options: opt,
+                fn: (blockContext = {}, blockVars = {}, blockOutput = []) => {
+                    i = compile(tokens, blockOutput, blockContext, opt, j, t, {root: vars.root, ...blockVars});
+                    return blockOutput.join("");
+                },
+            }));
+            // Make sure that this block has been executed
+            if (i + 1 === j) {
+                i = compile(tokens, [], {}, opt, j, t, vars);
+            }
         }
         else if (tokens[i].startsWith("#") || tokens[i].startsWith("^")) {
             const t = tokens[i].slice(1).trim();
-            const value = get(ctx, t);
+            const value = get(context, t);
             const negate = tokens[i].startsWith("^");
             if (!negate && value && Array.isArray(value)) {
                 const j = i + 1;
                 (value.length > 0 ? value : [""]).forEach(item => {
-                    i = compile(tokens, value.length > 0 ? output : [], item, opt, j, t);
+                    i = compile(tokens, value.length > 0 ? output : [], item, opt, j, t, vars);
                 });
             }
             else {
                 const includeOutput = (!negate && !!value) || (negate && !!!value);
-                i = compile(tokens, includeOutput ? output : [], ctx, opt, i + 1, t);
+                i = compile(tokens, includeOutput ? output : [], context, opt, i + 1, t, vars);
             }
         }
         else if (tokens[i].startsWith(">")) {
             const [t, v] = tokens[i].slice(1).trim().split(" ");
             if (typeof opt?.partials?.[t] === "string") {
-                compile(opt.partials[t].split(tags), output, v ? get(ctx, v) : ctx, opt, 0, "");
+                compile(opt.partials[t].split(tags), output, v ? get(context, v) : context, opt, 0, "", vars);
             }
         }
         else if (tokens[i].startsWith("/")) {
@@ -52,14 +82,14 @@ const compile = (tokens, output, ctx, opt, index, section) => {
             break;
         }
         else {
-            output.push(escape(get(ctx, tokens[i].trim())));
+            output.push(escape(get(context, tokens[i].trim())));
         }
         i = i + 1;
     }
     return i;
 };
 
-export default (str, ctx = {}, opt = {}, output = []) => {
-    compile(str.split(tags), output, ctx, opt, 0, "");
+export default (str, context = {}, opt = {}, output = []) => {
+    compile(str.split(tags), output, context, opt, 0, "", {root: context});
     return output.join("");
 };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "mikel",
     "description": "Micro templating library with zero dependencies",
-    "version": "0.3.2",
+    "version": "0.5.0",
     "type": "module",
     "author": {
         "name": "Josemi Juanes",
@@ -20,7 +20,7 @@
         "test": "node test.js"
     },
     "keywords": [
-        "mustache",
+        "template",
         "templating"
     ],
     "files": [