mikel 0.33.0 → 0.34.0

package/README.md

@@ -25,11 +25,41 @@ Mikel supports the following syntax for rendering templates:
 
 Use double curly braces `{{ }}` to insert variables into your template. Variables will be replaced with the corresponding values from the data object.
 
+```javascript
+const result = m(`Hello {{name}}!`, { name: "World" });
+// Output: 'Hello World!'
+```
+
+#### Nested values
+
+You can access nested properties of an object using dot notation.
+
+```javascript
+const result = m(`Hello {{user.name}}!`, {
+    user: { name: "John" },
+});
+// Output: 'Hello John!'
+```
+
+#### Array values
+
+You can access a specific element of an array using its index in dot notation.
+
+```javascript
+const result = m(`Hello {{users.0.name}}!`, {
+    users: [
+        { name: "John" },
+        { name: "Alice" },
+    ],
+});
+// Output: 'Hello John!'
+```
+
 #### Fallback values
 
 > Added in `v0.14.0`.
 
-You can specify a value as a fallback, using the double OR `||` operator and followed by the fallback value.
+You can specify a fallback value using the `||` operator. This value will be used when the variable is not defined or is empty.
 
 ```javascript
 const result = m(`Hello {{name || "World"}}!`, {});
@@ -700,9 +730,6 @@ const result = m("Users: {{=fullName ...user1}} and {{=fullName ...user2}}", dat
 console.log(result); // --> "Users: John Doe and Alice Smith"
 ```
 
-Of course, Jose — here’s a version of the **Subexpressions** documentation written to perfectly match the tone, structure, and formatting conventions of the current README.  
-It follows the same patterns: short intro, version note, examples, concise explanations, no extra fluff.
-
 ### Subexpressions  
 
 > Added in `v0.30.0`.
@@ -814,15 +841,31 @@ It also exposes the following additional methods:
 
 > Added in `v0.19.0`.
 
-Allows to extend the templating with custom **helpers**, **functions**, and **partials**.
-
+Extends the instance with additional helpers, functions, partials, or hooks. Accepts either an options object or a plugin function.
+ 
+When called with an **object**, it registers the provided helpers, functions, and partials directly:
+ 
 ```javascript
 mk.use({
+    helpers: {
+        uppercase: ({ fn, data }) => fn(data).toUpperCase(),
+    },
     partials: {
-        foo: "bar",
+        foo: "Hello {{name}}!",
     },
 });
 ```
+ 
+When called with a **function**, the function receives the internal context of the instance, giving full access to the hooks system and all registered helpers, functions, and partials. This is the recommended approach for writing reusable plugins:
+ 
+```javascript
+const myPlugin = (ctx) => {
+    ctx.hooks.add("preRender", template => template.trim());
+    ctx.hooks.add("postRender", output => output.trim());
+};
+ 
+mk.use(myPlugin);
+```
 
 #### `mk.addHelper(helperName, helperFn)`
 
@@ -880,6 +923,72 @@ This function converts special HTML characters `&`, `<`, `>`, `"`, and `'` to th
 
 This function returns the value in `object` following the provided `path` string.
 
+## Advanced
+
+### Built‑in Plugins
+
+> Added in `v0.34.0`.
+
+Mikel includes a small set of built‑in plugins that provide common functionality without requiring additional packages. These plugins integrate directly into the compilation lifecycle and use the same hook system available to any external plugin.
+
+#### `mikel.WrapperPlugin(options)`
+
+Wraps the original template by inserting custom text before and/or after it. The wrapper is applied before rendering, which means it can contain mikel expressions (`{{variables}}`, helpers, etc.).
+
+```javascript
+mk.use(mikel.WrapperPlugin({
+    header: "<!-- START -->\n",
+    footer: "\n<!-- END -->",
+}));
+```
+
+#### `mikel.StatePlugin(state)`
+
+Defines static state variables that become available inside templates through the `@variable` syntax. These values are merged into the initial state before rendering.
+
+```javascript
+mk.use(mikel.StatePlugin({
+    version: "1.0.0",
+    environment: "development",
+}));
+```
+
+### Hooks
+ 
+> Added in `v0.34.0`.
+ 
+Hooks allows plugins to tap into different stages of the rendering pipeline. Hooks are registered using the `hooks.add` method inside a plugin function passed to `mk.use()`.
+
+```javascript
+mk.use((context) => {
+    context.hooks.add("someHook", (params) => {
+        // ...
+    });
+});
+```
+
+Available hooks:
+ 
+| Hook |  Type | Receives | Must return | Description |
+|------|-------|----------|-------------|-------------|
+| `preRender` | Waterfall | `template` (string) | `template` (string) | Called before rendering. The returned value is used as the template. |
+| `postRender` | Waterfall | `output` (string) | `output` (string) | Called after rendering. The returned value is used as the final output. |
+ 
+Example:
+ 
+```javascript
+const myPlugin = (context) => {
+    // trim the template before rendering
+    context.hooks.add("preRender", template => template.trim());
+    // minify the output after rendering
+    context.hooks.add("postRender", output => output.replace(/\s+/g, " ").trim());
+};
+ 
+mk.use(myPlugin);
+ 
+console.log(mk("  Hello {{name}}!  ", { name: "World" })); // --> "Hello World!"
+```
+
 ## License
 
 This project is licensed under the [MIT License](LICENSE).

package/index.d.ts

@@ -24,26 +24,45 @@ export type MikelFunction = (params: {
     state: Record<string, any>;
 }) => string | void;
 
+export type MikelState = Record<string, string>;
+
 export type MikelOptions = {
     helpers?: Record<string, MikelHelper>;
     partials?: Record<string, string | MikelPartial>;
     functions?: Record<string, MikelFunction>;
 };
 
-export type MikelUseOptions = MikelOptions & {
-    initialState?: Record<string, any>;
+export type MikelPluginOptions = MikelOptions & {
+    initialState?: MikelState;
+};
+
+export type MikelContext = {
+    helpers: Record<string, MikelFunction>;
+    functions: Record<string, MikelFunction>;
+    partials: Record<string, MikelPartial>;
+    hooks: {
+        add: (hookName: string, listener: Function) => void;
+        call: (hookName: string, ...args: any[]) => void;
+        callWaterfall: (hookName: string, value: any) => any;
+    };
+    initialState: MikelState;
 };
 
+export type MikelPlugin = (ctx: MikelContext) => void;
+
 export type Mikel = {
     (template: string, data?: any): string;
-    use(options: Partial<MikelUseOptions>): void;
+    use(plugin: Partial<MikelPluginOptions> | MikelPlugin): void;
     addHelper(name: string, fn: MikelHelper): void;
     removeHelper(name: string): void;
     addFunction(name: string, fn: MikelFunction): void;
     removeFunction(name: string): void;
     addPartial(name: string, partial: string | MikelPartial): void;
     removePartial(name: string): void;
-}
+};
+
+export type MikelWrapperPlugin = (options: { header?: string, footer?: string }) => MikelPlugin;
+export type MikelStatePlugin = (state: MikelState) => MikelPlugin;
 
 declare const mikel: {
     (template: string, data?: any, options?: Partial<MikelOptions>): string;
@@ -53,6 +72,8 @@ declare const mikel: {
     parse(value: string, context?: any, vars?: any): any;
     tokenize(str: string): string[];
     untokenize(tokens: string[], start?: string, end?: string): string;
+    WrapperPlugin: MikelWrapperPlugin;
+    StatePlugin: MikelStatePlugin;
 };
 
 export default mikel;

package/index.js

@@ -122,6 +122,24 @@ const findClosingToken = (tokens, i, token) => {
     throw new Error(`Unmatched section end: {{${token}}}`);
 };
 
+// @description create a hook manager for the provided hooks map
+const createHookManager = (hooks = new Map()) => {
+    return {
+        add: (hookName, listener) => {
+            if (!hooks.has(hookName.toLowerCase())) {
+                hooks.set(hookName.toLowerCase(), []);
+            }
+            hooks.get(hookName.toLowerCase()).push(listener);
+        },
+        call: (hookName, ...args) => {
+            hooks.get(hookName.toLowerCase())?.forEach((listener) => listener(...args));
+        },
+        callWaterfall: (hookName, value) => {
+            return (hooks.get(hookName.toLowerCase()) || []).reduce((v, listener) => listener(v), value);
+        },
+    };
+};
+
 // @description internal method to compile the template
 const compile = (ctx, tokens, output, data, state, index = 0, section = "") => {
     let i = index;
@@ -278,18 +296,26 @@ const create = (options = {}) => {
         partials: Object.assign({}, options?.partials || {}),
         functions: Object.assign({}, options?.functions || {}),
         initialState: {}, // Object.assign({}, options?.initialState || {}),
+        hooks: createHookManager(new Map()),
     });
     // entry method to compile the template with the provided data object
-    const compileTemplate = (template, data = {}, output = []) => {
+    const compileTemplate = (originalTemplate, data = {}) => {
+        const output = [];
+        const template = ctx.hooks.callWaterfall("prerender", originalTemplate || "");
         compile(ctx, tokenize(template), output, data, { ...ctx.initialState, root: data }, 0, "");
-        return output.join("");
+        return ctx.hooks.callWaterfall("postrender", output.join(""));
     };
     // assign api methods and return method to compile the template
     return Object.assign(compileTemplate, {
-        use: (newOptions = {}) => {
-            ["helpers", "functions", "partials", "initialState"].forEach(field => {
-                Object.assign(ctx[field], newOptions?.[field] || {});
-            });
+        use: (plugin) => {
+            if (typeof plugin === "function") {
+                plugin(ctx);
+            }
+            else if (typeof plugin === "object" && !!plugin) {
+                ["helpers", "functions", "partials", "initialState"].forEach(field => {
+                    Object.assign(ctx[field], plugin?.[field] || {});
+                });
+            }
         },
         addHelper: (name, fn) => ctx.helpers[name] = fn,
         removeHelper: name => delete ctx.helpers[name],
@@ -305,6 +331,22 @@ const mikel = (template = "", data = {}, options = {}) => {
     return create(options)(template, data);
 };
 
+// @description plugin to wrap template with custom text
+mikel.WrapperPlugin = (options = {}) => {
+    return (context) => {
+        context.hooks.add("prerender", template => {
+            return [options.header || "", template, options.footer || ""].join("");
+        });
+    };
+};
+
+// @description plugin to define state variables
+mikel.StatePlugin = (state = {}) => {
+    return (context) => {
+        Object.assign(context.initialState, state || {});
+    };
+};
+
 // @description assign utilities
 mikel.create = create;
 mikel.escape = escape;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "mikel",
     "description": "Micro templating library with zero dependencies",
-    "version": "0.33.0",
+    "version": "0.34.0",
     "type": "module",
     "author": {
         "name": "Josemi Juanes",
@@ -19,7 +19,8 @@
     },
     "scripts": {
         "release": "node ./scripts/release.js",
-        "test": "node test.js && yarn test:eval && yarn test:frontmatter && yarn test:markdown",
+        "test": "node test.js && yarn test:cli && yarn test:eval && yarn test:frontmatter && yarn test:markdown",
+        "test:cli": "cd packages/mikel-cli && yarn test",
         "test:eval": "node ./packages/mikel-eval/test.js",
         "test:frontmatter": "node ./packages/mikel-frontmatter/test.js",
         "test:markdown": "node ./packages/mikel-markdown/test.js"