mikel 0.18.1 → 0.19.0

package/README.md

@@ -380,7 +380,8 @@ Custom helper functions receive a single object as argument, containing the foll
 
 - `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.
+- `data`: the current data where the helper has been executed.
+- `context` (**DEPRECATED**): 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. Example:
@@ -537,6 +538,20 @@ console.log(template({name: "Susan"})); // --> "Hello, Susan!"
 
 It also exposes the following additional methods:
 
+#### `template.use(options)`
+
+> Added in `v0.19.0`.
+
+Allows to extend the templating with custom **helpers**, **functions**, and **partials**.
+
+```javascript
+template.use({
+    partials: {
+        foo: "bar",
+    },
+});
+```
+
 #### `template.addHelper(helperName, helperFn)`
 
 Allows to register a new helper instead of using the `options` object.

package/index.d.ts

@@ -2,6 +2,7 @@ declare type HelperFunction = (params: {
     args: any[];
     opt: Record<string, any>;
     context: Record<string, any>;
+    data: Record<string, any>;
     fn: (context?: Record<string, any>, vars?: Record<string, any>, output?: string[]) => string;
 }) => string;
 
@@ -21,14 +22,20 @@ declare interface Functions {
     }) => string | void;
 }
 
+declare interface Variables {
+    [key: string]: any;
+}
+
 declare interface MikelOptions {
     helpers?: Helpers;
     partials?: Partials;
     functions?: Functions;
+    variables?: Variables;
 }
 
 declare interface MikelTemplate {
     (data?: any): string;
+    use(options: Partial<MikelOptions>): MikelTemplate;
     addHelper(name: string, fn: HelperFunction): void;
     removeHelper(name: string): void;
     addFunction(name: string, fn: (params: any) => string | void): void;

package/index.js

@@ -17,22 +17,22 @@ const untokenize = (ts = [], s = "{{", e = "}}") => {
 };
 
 // @description parse string arguments
-const parseArgs = (argString = "", context = {}, vars = {}) => {
+const parseArgs = (argString = "", data = {}, vars = {}) => {
     const [t, ...args] = argString.trim().match(/(?:[^\s"]+|"[^"]*")+/g);
-    const argv = args.filter(a => !a.includes("=")).map(a => parse(a, context, vars));
+    const argv = args.filter(a => !a.includes("=")).map(a => parse(a, data, vars));
     const opt = Object.fromEntries(args.filter(a => a.includes("=")).map(a => {
         const [k, v] = a.split("=");
-        return [k, parse(v, context, vars)];
+        return [k, parse(v, data, vars)];
     }));
     return [t, argv, opt];
 };
 
 // @description parse a string value to a native type
-const parse = (v, context = {}, vars = {}) => {
+const parse = (v, data = {}, vars = {}) => {
     if ((v.startsWith(`"`) && v.endsWith(`"`)) || /^-?\d+\.?\d*$/.test(v) || v === "true" || v === "false" || v === "null") {
         return JSON.parse(v);
     }
-    return (v || "").startsWith("@") ? get(vars, v.slice(1)) : get(context, v || ".");
+    return (v || "").startsWith("@") ? get(vars, v.slice(1)) : get(data, v || ".");
 };
 
 // @description default helpers
@@ -44,35 +44,40 @@ const defaultHelpers = {
             .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": 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) : "",
+    "if": p => !!p.args[0] ? p.fn(p.data) : "",
+    "unless": p => !!!p.args[0] ? p.fn(p.data) : "",
+    "eq": p => p.args[0] === p.args[1] ? p.fn(p.data) : "",
+    "ne": p => p.args[0] !== p.args[1] ? p.fn(p.data) : "",
     "with": p => p.fn(p.args[0]),
-    "escape": p => escape(p.fn(p.context)),
+    "escape": p => escape(p.fn(p.data)),
 };
 
 // @description create a new instance of mikel
 const create = (template = "", options = {}) => {
-    const helpers = Object.assign({}, defaultHelpers, options?.helpers || {});
-    const partials = Object.assign({}, options?.partials || {});
-    const functions = options?.functions || {};
+    const ctx = {
+        tokens: tokenize(template),
+        helpers: Object.assign({}, defaultHelpers, options?.helpers || {}),
+        partials: Object.assign({}, options?.partials || {}),
+        functions: options?.functions || {},
+        variables: {},
+    };
     // internal method to compile the template
-    const compile = (tokens, output, context, vars, index = 0, section = "") => {
+    const compile = (tokens, output, data, vars, index = 0, section = "") => {
         let i = index;
         while (i < tokens.length) {
             if (i % 2 === 0) {
                 output.push(tokens[i]);
             }
-            else if (tokens[i].startsWith("#") && typeof helpers[tokens[i].slice(1).trim().split(" ")[0]] === "function") {
-                const [t, args, opt] = parseArgs(tokens[i].slice(1), context, vars);
+            else if (tokens[i].startsWith("#") && typeof ctx.helpers[tokens[i].slice(1).trim().split(" ")[0]] === "function") {
+                const [t, args, opt] = parseArgs(tokens[i].slice(1), data, vars);
                 const j = i + 1;
-                output.push(helpers[t]({
+                output.push(ctx.helpers[t]({
                     args: args,
                     opt: opt,
-                    context: context,
-                    fn: (blockContext = {}, blockVars = {}, blockOutput = []) => {
-                        i = compile(tokens, blockOutput, blockContext, {...vars, ...blockVars, root: vars.root}, j, t);
+                    data: data,
+                    context: data,
+                    fn: (blockData = {}, blockVars = {}, blockOutput = []) => {
+                        i = compile(tokens, blockOutput, blockData, {...vars, ...blockVars, root: vars.root}, j, t);
                         return blockOutput.join("");
                     },
                 }));
@@ -83,7 +88,7 @@ const create = (template = "", options = {}) => {
             }
             else if (tokens[i].startsWith("#") || tokens[i].startsWith("^")) {
                 const t = tokens[i].slice(1).trim();
-                const value = get(context, t);
+                const value = get(data, t);
                 const negate = tokens[i].startsWith("^");
                 if (!negate && value && Array.isArray(value)) {
                     const j = i + 1;
@@ -93,7 +98,7 @@ const create = (template = "", options = {}) => {
                 }
                 else {
                     const includeOutput = (!negate && !!value) || (negate && !!!value);
-                    i = compile(tokens, includeOutput ? output : [], context, vars, i + 1, t);
+                    i = compile(tokens, includeOutput ? output : [], data, vars, i + 1, t);
                 }
             }
             else if (tokens[i].startsWith("<")) {
@@ -101,31 +106,31 @@ const create = (template = "", options = {}) => {
                 const lastIndex = partialTokens.findIndex((token, j) => {
                     return j % 2 !== 0 && token.trim().startsWith("/") && token.trim().endsWith(t);
                 });
-                if (typeof partials[t] === "undefined") {
-                    partials[t] = untokenize(partialTokens.slice(0, lastIndex));
+                if (typeof ctx.partials[t] === "undefined") {
+                    ctx.partials[t] = untokenize(partialTokens.slice(0, lastIndex));
                 }
                 i = i + lastIndex + 1;
             }
             else if (tokens[i].startsWith(">")) {
-                const [t, args, opt] = parseArgs(tokens[i].replace(/^>{1,2}/, ""), context, vars);
+                const [t, args, opt] = parseArgs(tokens[i].replace(/^>{1,2}/, ""), data, vars);
                 const blockContent = []; // to store partial block content
                 if (tokens[i].startsWith(">>")) {
-                    i = compile(tokens, blockContent, context, vars, i + 1, t);
+                    i = compile(tokens, blockContent, data, vars, i + 1, t);
                 }
-                if (typeof partials[t] === "string" || typeof partials[t]?.body === "string") {
-                    const newCtx = args.length > 0 ? args[0] : (Object.keys(opt).length > 0 ? opt : context);
+                if (typeof ctx.partials[t] === "string" || typeof ctx.partials[t]?.body === "string") {
+                    const newData = args.length > 0 ? args[0] : (Object.keys(opt).length > 0 ? opt : data);
                     const newVars = {
                         ...vars,
                         content: blockContent.join(""),
-                        partial: partials[t]?.attributes || partials[t]?.data || {},
+                        partial: ctx.partials[t]?.attributes || ctx.partials[t]?.data || {},
                     };
-                    compile(tokenize(partials[t]?.body || partials[t]), output, newCtx, newVars, 0, "");
+                    compile(tokenize(ctx.partials[t]?.body || ctx.partials[t]), output, newData, newVars, 0, "");
                 }
             }
             else if (tokens[i].startsWith("=")) {
-                const [t, args, opt] = parseArgs(tokens[i].slice(1), context, vars);
-                if (typeof functions[t] === "function") {
-                    output.push(functions[t]({args, opt, context}) || "");
+                const [t, args, opt] = parseArgs(tokens[i].slice(1), data, vars);
+                if (typeof ctx.functions[t] === "function") {
+                    output.push(ctx.functions[t]({args, opt, data}) || "");
                 }
             }
             else if (tokens[i].startsWith("/")) {
@@ -138,10 +143,10 @@ const create = (template = "", options = {}) => {
                 const t = tokens[i].split("||").map(v => {
                     // check if the returned value should not be escaped
                     if (v.trim().startsWith("!")) {
-                        return parse(v.trim().slice(1).trim(), context, vars);
+                        return parse(v.trim().slice(1).trim(), data, vars);
                     }
                     // escape the returned value
-                    return escape(parse(v.trim(), context, vars));
+                    return escape(parse(v.trim(), data, vars));
                 });
                 output.push(t.find(v => !!v) ?? "");
             }
@@ -151,17 +156,28 @@ const create = (template = "", options = {}) => {
     };
     // entry method to compile the template with the provided data object
     const compileTemplate = (data = {}, output = []) => {
-        compile(tokenize(template), output, data, {root: data}, 0, "");
+        compile(ctx.tokens, output, data, {root: data, ...ctx.variables}, 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],
+        use: newOptions => {
+            if (typeof newOptions === "function") {
+                newOptions(ctx);
+            }
+            else if (!!newOptions && typeof newOptions === "object") {
+                ["helpers", "functions", "partials", "variables"].forEach(field => {
+                    Object.assign(ctx[field], newOptions?.[field] || {});
+                });
+            }
+            return compileTemplate;
+        },
+        addHelper: (name, fn) => ctx.helpers[name] = fn,
+        removeHelper: name => delete ctx.helpers[name],
+        addFunction: (name, fn) => ctx.functions[name] = fn,
+        removeFunction: name => delete ctx.functions[name],
+        addPartial: (name, partial) => ctx.partials[name] = partial,
+        removePartial: name => delete ctx.partials[name],
     });
 };
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "mikel",
     "description": "Micro templating library with zero dependencies",
-    "version": "0.18.1",
+    "version": "0.19.0",
     "type": "module",
     "author": {
         "name": "Josemi Juanes",
@@ -19,7 +19,8 @@
     },
     "scripts": {
         "release": "node ./scripts/release.js",
-        "test": "node test.js"
+        "test": "node test.js && yarn test:markdown",
+        "test:markdown": "node ./packages/mikel-markdown/test.js"
     },
     "keywords": [
         "template",