mikel 0.5.0 → 0.7.0

package/README.md

@@ -234,11 +234,11 @@ Custom helper functions receive a single object parameter containing the followi
 
 The helper function must return a string, which will be injected into the result string.
 
-### Variables
+### 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,7 +266,27 @@ 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.
+
+```
+{{#each items}}{{@index}}:{{.}} {{#unless @last}},{{/unless}}{{/each}}
+```
+
+### Custom runtime variables
 
 > Added in `v0.5.0`
 
@@ -289,7 +309,7 @@ In this example, the custom data variable `customVariable` is defined with the v
 
 ## API
 
-### `m(template, data[, options])`
+### `mikel(template, data[, options])`
 
 Render the given template string with the provided data object.
 
@@ -303,16 +323,24 @@ Render the given template string with the provided data object.
 Returns: A string with the rendered output.
 
 ```javascript
-import m from "mikel";
+import mikel from "mikel";
 
 const data = {
     name: "World",
 };
 
-const result = m("Hello, {{name}}!", data);
+const result = mikel("Hello, {{name}}!", data);
 console.log(result); // Output: "Hello, World!"
 ```
 
+### `mikel.escape(str)`
+
+This function converts special HTML characters `&`, `<`, `>`, `"`, and `'` to their corresponding HTML entities.
+
+### `mikel.get(object, path)`
+
+This function returns the value in `object` following the provided `path` string.
+
 ## License
 
 This project is licensed under the [MIT License](LICENSE).

package/index.js

@@ -11,47 +11,44 @@ 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 helpers = new Map(Object.entries({
+const defaultHelpers = {
     "each": ({value, fn}) => {
-        return (typeof value === "object" ? Object.entries(value || {}) : [])
-            .map((item, index) => fn(item[1], {index: index, key: item[0], value: item[1]}))
+        const items = (typeof value === "object" ? Object.entries(value || {}) : []);
+        return items
+            .map((item, index) => 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) : "",
-}));
-
-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, context, opt, index = 0, section = "", vars = {}) => {
+const compile = (tokens, output, context, partials, helpers, vars, index = 0, section = "") => {
     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() ?? "_") ?? "");
+            output.push(get(vars, tokens[i].slice(1).trim() ?? "_") ?? "");
         }
         else if (tokens[i].startsWith("!")) {
             output.push(get(context, tokens[i].slice(1).trim()));
         }
-        else if (tokens[i].startsWith("#") && hasHelper(tokens[i].slice(1).trim().split(" ")[0], opt)) {
+        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 j = i + 1;
-            output.push(getHelper(t, opt)({
+            output.push(helpers[t]({
                 context: context,
                 key: v || ".",
-                value: get(context, v || "."),
-                options: opt,
+                value: (v || "").startsWith("@") ? get(vars, v.slice(1)) : get(context, v || "."),
                 fn: (blockContext = {}, blockVars = {}, blockOutput = []) => {
-                    i = compile(tokens, blockOutput, blockContext, opt, j, t, {root: vars.root, ...blockVars});
+                    i = compile(tokens, blockOutput, blockContext, partials, helpers, {...vars, ...blockVars, root: vars.root}, j, t);
                     return blockOutput.join("");
                 },
             }));
             // Make sure that this block has been executed
             if (i + 1 === j) {
-                i = compile(tokens, [], {}, opt, j, t, vars);
+                i = compile(tokens, [], {}, partials, helpers, vars, j, t);
             }
         }
         else if (tokens[i].startsWith("#") || tokens[i].startsWith("^")) {
@@ -61,18 +58,18 @@ const compile = (tokens, output, context, opt, index = 0, section = "", vars = {
             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, vars);
+                    i = compile(tokens, value.length > 0 ? output : [], item, partials, helpers, vars, j, t);
                 });
             }
             else {
                 const includeOutput = (!negate && !!value) || (negate && !!!value);
-                i = compile(tokens, includeOutput ? output : [], context, opt, i + 1, t, vars);
+                i = compile(tokens, includeOutput ? output : [], context, partials, helpers, vars, i + 1, t);
             }
         }
         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(context, v) : context, opt, 0, "", vars);
+            if (typeof partials[t] === "string") {
+                compile(partials[t].split(tags), output, v ? get(context, v) : context, partials, helpers, vars, 0, "");
             }
         }
         else if (tokens[i].startsWith("/")) {
@@ -89,7 +86,17 @@ const compile = (tokens, output, context, opt, index = 0, section = "", vars = {
     return i;
 };
 
-export default (str, context = {}, opt = {}, output = []) => {
-    compile(str.split(tags), output, context, opt, 0, "", {root: context});
+// @description main compiler function
+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, "");
     return output.join("");
 };
+
+// @description assign utilities
+mikel.escape = escape;
+mikel.get = get;
+
+export default mikel;

package/package.json

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