mikel 0.9.2 → 0.11.0

package/README.md

@@ -219,6 +219,23 @@ The `ne` helper renders the block only if the two values provided as argument ar
 console.log(m(`{{#ne name "bob"}}Not bob{{/ne}}`, {name: "John"})); // --> 'Not bob'
 ```
 
+#### with
+
+> Added in `v0.10.0`.
+
+The `with` helper allows to change the data context of the block.
+
+```javascript
+const data = {
+    autor: {
+        name: "Bob",
+        email: "bob@email.com",
+    },
+};
+
+console.log(m("{{#with autor}}{{name}} <{{email}}>{{/with}}", data)); // --> 'Bob <bob@email.com>'
+```
+
 ### Custom Helpers
 
 > Added in `v0.5.0`.
@@ -323,27 +340,6 @@ The `@last` variable allows to check if the current iteration using the `#each`
 {{#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.
-
-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`.
-
 ### Functions
 
 > Added in `v0.8.0`.
@@ -386,7 +382,6 @@ Render the given template string with the provided data object and options.
 - `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.
 
@@ -403,6 +398,71 @@ const result = mikel("Hello, {{name}}!", data);
 console.log(result); // Output: "Hello, World!"
 ```
 
+### `mikel.create(template [, options])`
+
+Allows to create an isolated instance of mikel, useful when you want to compile the same template using different data. The `template` argument is the template string, and the optional `options` argument is the same options object that you can pass to `mikel` method.
+
+It returns a function that you can call with the data to compile the template.
+
+```javascript
+import mikel from "mikel";
+
+const template = mikel.create("Hello, {{name}}!");
+
+console.log(template({name: "Bob"})); // --> "Hello, Bob!"
+console.log(template({name: "Susan"})); // --> "Hello, Susan!"
+```
+
+It also exposes the following additional methods:
+
+#### `template.addHelper(helperName, helperFn)`
+
+Allows to register a new helper instead of using the `options` object.
+
+```javascript
+template.addHelper("foo", () => { ... });
+```
+
+#### `template.removeHelper(helperName)`
+
+Removes a previously added helper.
+
+```javascript
+template.removeHelper("foo");
+```
+
+#### `template.addPartial(partialName, partialCode)`
+
+Registers a new partial instead of using the `options` object.
+
+```javascript
+template.addPartial("bar", " ... ");
+```
+
+#### `template.removePartial(partialName)`
+
+Removes a previously added partial.
+
+```javascript
+template.removePartial("bar");
+```
+
+#### `template.addFunction(fnName, fn)`
+
+Registers a new function instead of using the `options` object.
+
+```javascript
+template.addFunction("foo", () => "...");
+```
+
+#### `template.removeFunction(fnName)`
+
+Removes a previously added function.
+
+```javascript
+template.removeFunction("foo");
+```
+
 ### `mikel.escape(str)`
 
 This function converts special HTML characters `&`, `<`, `>`, `"`, and `'` to their corresponding HTML entities.

package/index.js

@@ -1,5 +1,4 @@
 const tags = /\{\{|\}\}/;
-const endl = "\n";
 const escapedChars = {
     "&": "&",
     "<": "&lt;",
@@ -19,56 +18,6 @@ const parse = (v, context = {}, vars = {}) => {
     return (v || "").startsWith("@") ? get(vars, v.slice(1)) : get(context, v || ".");
 };
 
-// @description tiny yaml parser
-const yamlParser = (str = "") => {
-    const lines = str.split(endl), result = {}, levels = [{ctx: result, indent: 0}];
-    let level = 0, i = 0;
-    while (i < lines.length) {
-        const line = lines[i] || "";
-        if (!!line.trim() && !line.trim().startsWith("#")) {
-            const indent = (line.match(/^( *)/m)?.[0] || "").length;
-            while(level > 0 && indent < levels[level].indent) {
-                levels.pop();
-                level = level - 1;
-            }
-            const isArrayItem = line.trim().startsWith("-");
-            // TODO: improve the regex to capture the line structure
-            let [_, key, value] = (line.trim().match(/^([^:"]*):(.*)$/m) || ["", line]).map(v => v.trim());
-            // Check if is a new item of the array
-            if (isArrayItem) {
-                key = key.replace(/^(- *)/m, "");
-                if (typeof value === "undefined") {
-                    value = key;
-                }
-                else {
-                    const newIndent = (line.slice(0, line.indexOf(key))).length;
-                    levels[level].ctx.push({});
-                    levels.push({ctx: levels[level].ctx[levels[level].ctx.length - 1], indent: newIndent});
-                    level = level + 1;
-                }
-            }
-            // Check for empty value --> entering into a nested object or array
-            if (!value) {
-                const nextLine = lines[i + 1] || "";
-                const nextIndent = (nextLine.match(/^( *)/m)?.[0] || "").length;
-                levels[level].ctx[key] = nextLine.trim().startsWith("-") ? [] : {};
-                if (nextIndent > levels[level].indent) {
-                    levels.push({ctx: levels[level].ctx[key], indent: nextIndent});
-                    level = level + 1;
-                }
-            }
-            else if(value && Array.isArray(levels[level].ctx)) {
-                levels[level].ctx.push(JSON.parse(value));
-            }
-            else if (value) {
-                levels[level].ctx[key] = JSON.parse(value);
-            }
-        }
-        i = i + 1;
-    }
-    return result;
-};
-
 // @description tiny front-matter parser
 const frontmatter = (str = "", parser = null) => {
     let body = (str || "").trim(), data = {};
@@ -76,11 +25,12 @@ const frontmatter = (str = "", parser = null) => {
     if (matches?.length === 2 && matches[0].index === 0) {
         const front = body.substring(0 + matches[0][1].length, matches[1].index).trim();
         body = body.substring(matches[1].index + matches[1][1].length).trim();
-        data = typeof parser === "function" ? parser(front) : yamlParser(front);
+        data = typeof parser === "function" ? parser(front) : front;
     }
     return {body, data};
 };
 
+// @description default helpers
 const defaultHelpers = {
     "each": (value, opt) => {
         return (typeof value === "object" ? Object.entries(value || {}) : [])
@@ -91,90 +41,109 @@ const defaultHelpers = {
     "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),
 };
 
-const compile = (tokens, output, context, partials, helpers, vars, fn = {}, 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(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("#") && typeof helpers[tokens[i].slice(1).trim().split(" ")[0]] === "function") {
-            const [t, ...args] = tokens[i].slice(1).trim().match(/(?:[^\s"]+|"[^"]*")+/g);
-            const j = i + 1;
-            output.push(helpers[t](...args.map(v => parse(v, context, vars)), {
-                context: context,
-                fn: (blockContext = {}, blockVars = {}, blockOutput = []) => {
-                    i = compile(tokens, blockOutput, blockContext, partials, helpers, {...vars, ...blockVars, root: vars.root}, fn, j, t);
-                    return blockOutput.join("");
-                },
-            }));
-            // Make sure that this block is executed at least once
-            if (i + 1 === j) {
-                i = compile(tokens, [], {}, {}, helpers, {}, {}, j, t);
+// @description create a new instance of mikel
+const create = (template = "", options = {}) => {
+    // initialize internal context
+    const helpers = Object.assign({}, defaultHelpers, options?.helpers || {});
+    const partials = options?.partials || {};
+    const functions = options?.functions || {};
+    // internal method to compile the template
+    const compile = (tokens, output, context, vars, index = 0, section = "") => {
+        let i = index;
+        while (i < tokens.length) {
+            if (i % 2 === 0) {
+                output.push(tokens[i]);
             }
-        }
-        else if (tokens[i].startsWith("#") || tokens[i].startsWith("^")) {
-            const t = tokens[i].slice(1).trim();
-            const value = get(context, t);
-            const negate = tokens[i].startsWith("^");
-            if (!negate && value && Array.isArray(value)) {
+            else if (tokens[i].startsWith("@")) {
+                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("#") && typeof helpers[tokens[i].slice(1).trim().split(" ")[0]] === "function") {
+                const [t, ...args] = tokens[i].slice(1).trim().match(/(?:[^\s"]+|"[^"]*")+/g);
                 const j = i + 1;
-                (value.length > 0 ? value : [""]).forEach(item => {
-                    i = compile(tokens, value.length > 0 ? output : [], item, partials, helpers, vars, fn, j, t);
-                });
+                output.push(helpers[t](...args.map(v => parse(v, context, vars)), {
+                    context: context,
+                    fn: (blockContext = {}, blockVars = {}, blockOutput = []) => {
+                        i = compile(tokens, blockOutput, blockContext, {...vars, ...blockVars, root: vars.root}, j, t);
+                        return blockOutput.join("");
+                    },
+                }));
+                // Make sure that this block is executed at least once
+                if (i + 1 === j) {
+                    i = compile(tokens, [], {}, {}, j, t);
+                }
             }
-            else {
-                const includeOutput = (!negate && !!value) || (negate && !!!value);
-                i = compile(tokens, includeOutput ? output : [], context, partials, helpers, vars, fn, i + 1, t);
+            else if (tokens[i].startsWith("#") || tokens[i].startsWith("^")) {
+                const t = tokens[i].slice(1).trim();
+                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, vars, j, t);
+                    });
+                }
+                else {
+                    const includeOutput = (!negate && !!value) || (negate && !!!value);
+                    i = compile(tokens, includeOutput ? output : [], context, vars, 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, fn, 0, "");
+            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, vars, 0, "");
+                }
             }
-        }
-        else if (tokens[i].startsWith("=")) {
-            const [t, ...args] = tokens[i].slice(1).trim().match(/(?:[^\s"]+|"[^"]*")+/g);
-            if (typeof fn[t] === "function") {
-                output.push(fn[t](...args.map(v => parse(v, context, vars))) || "");
+            else if (tokens[i].startsWith("=")) {
+                const [t, ...args] = tokens[i].slice(1).trim().match(/(?:[^\s"]+|"[^"]*")+/g);
+                if (typeof functions[t] === "function") {
+                    output.push(functions[t](...args.map(v => parse(v, context, vars))) || "");
+                }
             }
-        }
-        else if (tokens[i].startsWith("/")) {
-            if (tokens[i].slice(1).trim() !== section) {
-                throw new Error(`Unmatched section end: {{${tokens[i]}}}`);
+            else if (tokens[i].startsWith("/")) {
+                if (tokens[i].slice(1).trim() !== section) {
+                    throw new Error(`Unmatched section end: {{${tokens[i]}}}`);
+                }
+                break;
             }
-            break;
-        }
-        else {
-            output.push(escape(get(context, tokens[i].trim())));
+            else {
+                output.push(escape(get(context, tokens[i].trim())));
+            }
+            i = i + 1;
         }
-        i = i + 1;
-    }
-    return i;
+        return i;
+    };
+    // entry method to compile the template with the provided data object
+    const compileTemplate = (data = {}, output = []) => {
+        compile(template.split(tags), output, data, {root: data}, 0, "");
+        return output.join("");
+    };
+    // assign api methods and return method to compile the template
+    return Object.assign(compileTemplate, {
+        addHelper: (name, fn) => helpers[name] = fn,
+        removeHelper: name => delete helpers[name],
+        addFunction: (name, fn) => functions[name] = fn,
+        removeFunction: name => delete functions[name],
+        addPartial: (name, partial) => partials[name] = partial,
+        removePartial: name => delete partials[name],
+    });
 };
 
 // @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, opt.functions || {}, 0, "");
-    return output.join("");
+const mikel = (template = "", data = {}, options = {}) => {
+    return create(template, options)(data);
 };
 
 // @description assign utilities
+mikel.create = create;
 mikel.escape = escape;
 mikel.get = get;
 mikel.parse = parse;
-mikel.yaml = yamlParser;
 mikel.frontmatter = frontmatter;
 
 export default mikel;

package/package.json

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