mikel 0.33.1 → 0.35.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"}}!`, {});
@@ -807,19 +837,36 @@ console.log(mk("{{>hello}}", {name: "Susan"})); // --> "Hello, Susan!"
 
 It also exposes the following additional methods:
 
-#### `mk.use(options)`
+#### `mk.use(options | function)`
 
 > 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 all registered helpers, functions, and partials. This is the recommended approach for writing reusable plugins:
+ 
+```javascript
+const myPlugin = (ctx) => {
+    ctx.helpers.uppercase = ({ fn, data }) => {
+        return fn(data).toUpperCase();
+    };
+};
+ 
+mk.use(myPlugin);
+```
 
 #### `mk.addHelper(helperName, helperFn)`
 
@@ -877,6 +924,22 @@ 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.35.0`.
+
+Mikel includes a small set of built‑in plugins that provide common functionality without requiring additional packages.
+
+#### `mikel.SetStatePlugin(name, value)`
+
+Registers a static state variable that become available inside templates through the `@variable` syntax.
+
+```javascript
+mk.use(mikel.SetStatePlugin("version", "1.0.0"));
+```
+
 ## License
 
 This project is licensed under the [MIT License](LICENSE).

package/index.d.ts

@@ -24,26 +24,39 @@ 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>;
+    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 MikelSetStatePlugin = (name: string, value: any) => MikelPlugin;
 
 declare const mikel: {
     (template: string, data?: any, options?: Partial<MikelOptions>): string;
@@ -53,6 +66,7 @@ declare const mikel: {
     parse(value: string, context?: any, vars?: any): any;
     tokenize(str: string): string[];
     untokenize(tokens: string[], start?: string, end?: string): string;
+    SetStatePlugin: MikelSetStatePlugin;
 };
 
 export default mikel;

package/index.js

@@ -280,16 +280,22 @@ const create = (options = {}) => {
         initialState: {}, // Object.assign({}, options?.initialState || {}),
     });
     // entry method to compile the template with the provided data object
-    const compileTemplate = (template, data = {}, output = []) => {
+    const compileTemplate = (template, data = {}) => {
+        const output = [];
         compile(ctx, tokenize(template), output, data, { ...ctx.initialState, root: data }, 0, "");
         return 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 +311,13 @@ const mikel = (template = "", data = {}, options = {}) => {
     return create(options)(template, data);
 };
 
+// @description plugin to define a new state variable
+mikel.SetStatePlugin = (name, value) => {
+    return (context) => {
+        context.initialState[name] = value;
+    };
+};
+
 // @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.1",
+    "version": "0.35.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"