mikel-frontmatter 0.31.0 → 0.33.0

package/README.md

@@ -3,11 +3,11 @@
 ![npm version](https://badgen.net/npm/v/mikel-frontmatter?labelColor=1d2734&color=21bf81)
 ![license](https://badgen.net/github/license/jmjuanes/mikel?labelColor=1d2734&color=21bf81)
 
-A [mikel](https://github.com/jmjuanes/mikel) plugin to define new data inside templates using a frontmatter-like syntax. Supports both **YAML** and **JSON** formats.
+A [mikel](https://github.com/jmjuanes/mikel) plugin to define new data inside templates using a frontmatter-like syntax. Supports **YAML**, **JSON**, and **TOML** formats.
 
 ## Installation
 
-You can install Mikel via npm or yarn:
+You can install it via npm or yarn:
 
 ```bash
 ## Install using npm
@@ -19,362 +19,146 @@ $ yarn add mikel mikel-frontmatter
 
 ## Usage
 
-This plugin provides a `{{#frontmatter}}` helper that allows you to define metadata at the beginning of your templates, similar to frontmatter in Markdown files. The parsed data is stored as a variable accessible via `@frontmatter` (or a custom variable name).
-
-The plugin automatically detects the format:
-- **YAML format**: When the content doesn't start with `{`
-- **JSON format**: When the content starts with `{` and ends with `}`
-
-### YAML Example
+Import the `mikel-frontmatter` package:
 
 ```javascript
 import mikel from "mikel";
 import mikelFrontmatter from "mikel-frontmatter";
+```
 
-const template = `
-{{#frontmatter}}
-title: My Page Title
-author: John Doe
-date: 2026-02-03
-tags:
-  - javascript
-  - templating
-settings:
-  published: true
-  featured: false
-{{/frontmatter}}
-
-<h1>{{@frontmatter.title}}</h1>
-<p>By {{@frontmatter.author}} on {{@frontmatter.date}}</p>
-
-{{#if @frontmatter.settings.published}}
-  <span class="badge">Published</span>
-{{/if}}
-
-<ul>
-{{#each @frontmatter.tags}}
-  <li>{{this}}</li>
-{{/each}}
-</ul>
-`;
+Include the plugin using the `use` method of mikel:
 
-const render = mikel.create();
-render.use(mikelFrontmatter());
+```javascript
+const m = mikel.create();
 
-const result = render(template, {});
-console.log(result);
+m.use(mikelFrontmatter({ ... }));
 ```
 
-### JSON Example
+In your template, the `{{#frontmatter}}` helper allows you to define metadata at the beginning of your templates, similar to frontmatter in Markdown files. The parsed data is stored as a state variable accessible via `@frontmatter` (or a custom variable name, see below).
 
-```javascript
-import mikel from "mikel";
-import mikelFrontmatter from "mikel-frontmatter";
+Example:
 
-const template = `
+```html
 {{#frontmatter}}
-{
-  "title": "My Page Title",
-  "author": "John Doe",
-  "date": "2026-02-03",
-  "tags": ["javascript", "templating"],
-  "settings": {
-    "published": true,
-    "featured": false
-  }
-}
+title: My Page Title
+author: John Doe
+date: 2026-02-03
+tags:
+  - javascript
+  - templating
 {{/frontmatter}}
-
 <h1>{{@frontmatter.title}}</h1>
 <p>By {{@frontmatter.author}} on {{@frontmatter.date}}</p>
-
-{{#if @frontmatter.settings.published}}
-  <span class="badge">Published</span>
-{{/if}}
-
 <ul>
-{{#each @frontmatter.tags}}
-  <li>{{this}}</li>
-{{/each}}
+    {{#each @frontmatter.tags}}
+    <li>{{this}}</li>
+    {{/each}}
 </ul>
-`;
-
-const render = mikel.create();
-render.use(mikelFrontmatter());
-
-const result = render(template, {});
-console.log(result);
 ```
 
-## Features
-
-### Format Auto-Detection
-
-The plugin automatically detects whether your frontmatter is in YAML or JSON format:
-
-```javascript
-// YAML format (default)
-{{#frontmatter}}
-title: My Title
-author: John Doe
-{{/frontmatter}}
-
-// JSON format (automatically detected)
-{{#frontmatter}}
-{
-  "title": "My Title",
-  "author": "John Doe"
-}
-{{/frontmatter}}
-```
-
-### Basic Key-Value Pairs
-
-```javascript
-const template = `
-{{#frontmatter}}
-title: Hello World
-author: Jane Smith
-version: 1.0.0
-{{/frontmatter}}
-
-Title: {{@frontmatter.title}}
-`;
-```
-
-### Data Types
-
-The plugin supports common data types in both YAML and JSON:
+Note that this helper doesn't produce any output in the rendered template.
 
-**YAML:**
-- **Strings**: `name: John Doe` or `name: "John Doe"` or `name: 'John Doe'`
-- **Numbers**: `age: 25` or `price: 19.99`
-- **Booleans**: `published: true` or `active: false` (also `yes/no`, `on/off`)
-- **Null**: `value: null` or `value: ~` or `value:`
+### Customization
 
-**JSON:**
-- **Strings**: `"name": "John Doe"`
-- **Numbers**: `"age": 25` or `"price": 19.99`
-- **Booleans**: `"published": true` or `"active": false`
-- **Null**: `"value": null`
+The `{{#frontmatter}}` helper accepts the following arguments:
 
-### Nested Objects
+#### as
 
-Both YAML and JSON support nested objects:
+Custom state variable name to save parsed metadata. If not provided, parsed metadata will be saved in `@frontmatter`. Example:
 
-**YAML:**
-```javascript
-const template = `
-{{#frontmatter}}
-author:
-  name: John Doe
-  email: john@example.com
-  social:
-    twitter: @johndoe
-    github: johndoe
-{{/frontmatter}}
-
-Author: {{@frontmatter.author.name}} ({{@frontmatter.author.email}})
-Twitter: {{@frontmatter.author.social.twitter}}
-`;
-```
-
-**JSON:**
-```javascript
-const template = `
-{{#frontmatter}}
-{
-  "author": {
-    "name": "John Doe",
-    "email": "john@example.com",
-    "social": {
-      "twitter": "@johndoe",
-      "github": "johndoe"
-    }
-  }
-}
-{{/frontmatter}}
-
-Author: {{@frontmatter.author.name}} ({{@frontmatter.author.email}})
-Twitter: {{@frontmatter.author.social.twitter}}
-`;
-```
-
-### Arrays
-
-Both formats support arrays:
-
-**YAML:**
-```javascript
-const template = `
-{{#frontmatter}}
-tags:
-  - javascript
-  - nodejs
-  - template
-colors:
-  - red
-  - green
-  - blue
-{{/frontmatter}}
-
-Tags: {{#each @frontmatter.tags}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}
-`;
-```
-
-**JSON:**
-```javascript
-const template = `
-{{#frontmatter}}
-{
-  "tags": ["javascript", "nodejs", "template"],
-  "colors": ["red", "green", "blue"]
-}
+```html
+{{#frontmatter as="meta"}}
+name: Bob
 {{/frontmatter}}
-
-Tags: {{#each @frontmatter.tags}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}
-`;
+<div>Hello {{@meta.name}}</div>
 ```
 
-### Arrays of Objects
+#### format
 
-**YAML:**
-```javascript
-const template = `
-{{#frontmatter}}
-contributors:
-  - name: Alice
-    role: Developer
-  - name: Bob
-    role: Designer
-  - name: Carol
-    role: Manager
-{{/frontmatter}}
+The format of the frontmatter content. Supported values are `yaml` (default), `json`, and `toml`.
 
-{{#each @frontmatter.contributors}}
-  <div>{{name}} - {{role}}</div>
-{{/each}}
-`;
-```
+Example using JSON:
 
-**JSON:**
-```javascript
-const template = `
-{{#frontmatter}}
+```html
+{{#frontmatter format="json"}}
 {
-  "contributors": [
-    { "name": "Alice", "role": "Developer" },
-    { "name": "Bob", "role": "Designer" },
-    { "name": "Carol", "role": "Manager" }
-  ]
+  "title": "My JSON Page",
+  "tags": ["json", "mikel"]
 }
 {{/frontmatter}}
-
-{{#each @frontmatter.contributors}}
-  <div>{{name}} - {{role}}</div>
-{{/each}}
-`;
 ```
 
-### Custom Variable Name
+Example using TOML:
 
-Use the `as` option to store the frontmatter data in a custom variable:
+```html
+{{#frontmatter format="toml"}}
+title = "My TOML Page"
+tags = ["toml", "mikel"]
 
-```javascript
-const template = `
-{{#frontmatter as="meta"}}
-title: My Page
-description: A great page
+[author]
+name = "John Doe"
 {{/frontmatter}}
-
-<title>{{@meta.title}}</title>
-<meta name="description" content="{{@meta.description}}">
-`;
-```
-
-### Multiple Frontmatter Blocks
-
-You can have multiple `{{#frontmatter}}` blocks in a template. Later blocks will overwrite earlier ones:
-
-```javascript
-const template = `
-{{#frontmatter}}
-title: Original Title
-author: John
-{{/frontmatter}}
-
-{{#frontmatter}}
-title: Updated Title
-status: draft
-{{/frontmatter}}
-
-Title: {{@frontmatter.title}}
-Author: {{@frontmatter.author}}
-Status: {{@frontmatter.status}}
-`;
-
-// Output:
-// Title: Updated Title
-// Author: (empty, overwritten)
-// Status: draft
 ```
 
 ## API
 
 ### mikelFrontmatter(options?)
 
-Creates a new instance of the frontmatter plugin.
-
-**Parameters:**
-- `options` (optional): Configuration options for the plugin.
-  - `parser` (Function): Custom parser function to override the default YAML/JSON parser.
-
-**Returns:** A plugin object with a `frontmatter` helper.
-
-### Helper: `{{#frontmatter}}...{{/frontmatter}}`
+Creates a new instance of the frontmatter plugin. It accepts an `options` parameters containing the following fields:
+- `parser` (Function): Custom parser function to override the default YAML/JSON/TOML parser.
 
-Parses the content inside the block as YAML or JSON (auto-detected) and stores it as a variable.
 
-**Options:**
-- `as`: Custom variable name (default: `"frontmatter"`). Example: `{{#frontmatter as="meta"}}`
-
-**Output:** This helper doesn't produce any output in the rendered template.
-
-### Custom Parser
+## Custom Parser
 
 You can provide a custom parser function if you need special parsing logic:
 
 ```javascript
-const customParser = (content) => {
-    // Your custom parsing logic
+const customParser = (content, format) => {
+    // Your custom parsing logic based on content and format
     return parsedData;
 };
 
 const render = mikel.create();
-render.use(mikelFrontmatter({ parser: customParser }));
+render.use(mikelFrontmatter({
+    parser: customParser,
+}));
 ```
 
 ## YAML Syntax Support
 
 This plugin includes a basic YAML parser that supports:
 
-- ✅ Key-value pairs
-- ✅ Nested objects (with indentation)
-- ✅ Arrays (using `- item` syntax)
-- ✅ Arrays of objects
-- ✅ Strings, numbers, booleans, null
-- ✅ Quoted strings (`"..."` or `'...'`)
-- ✅ Comments (lines starting with `#`)
-- ✅ Boolean variants (`yes/no`, `on/off`, `true/false`)
-- ❌ Multi-line strings (with `|` or `>`)
-- ❌ Anchors and aliases (`&anchor`, `*alias`)
-- ❌ Complex YAML features
-
-For most common use cases, this subset is sufficient.
+- ✅ Key-value pairs.
+- ✅ Nested objects (with indentation).
+- ✅ Arrays (using `- item` syntax).
+- ✅ Arrays of objects.
+- ✅ Inline arrays `[item1, item2, ...]`.
+- ✅ Inline objects `{key1: value1, key2: value2, ...}`.
+- ✅ Boolean variants (`yes/no`, `on/off`, `true/false`).
+- ❌ Multi-line strings (with `|` or `>`).
+- ❌ Multi-document syntax (`---`).
+- ❌ Anchors and aliases (`&anchor`, `*alias`).
+- ❌ Complex YAML features (e.g., tags, merge keys).
+
+## TOML Support
+
+The plugin includes a basic TOML parser that supports:
+
+- ✅ Key-value pairs (`key = "value"`).
+- ✅ Tables (`[section]`).
+- ✅ Nested tables (`[section.subsection]`).
+- ✅ Array of Tables (`[[table]]`).
+- ✅ Inline arrays and objects.
+- ✅ Strings, integers, floats, booleans, and null.
+- ✅ Comments (starting with `#`).
+- ❌ Multi-line strings (`"""` or `'''`).
+- ❌ Date and time values.
+- ❌ Dotted keys (e.g. `a.b = "val"`) in a single line.
+- ❌ Hex, octal, binary, and scientific notation.
 
 ## JSON Support
 
-The plugin fully supports standard JSON syntax through the native `JSON.parse()` method. If the frontmatter content starts with `{` and ends with `}`, it will be automatically parsed as JSON.
+The plugin fully supports standard JSON syntax through the native `JSON.parse()` method.
 
 ## License
 

package/index.d.ts

@@ -7,7 +7,7 @@ export interface MikelFrontmatterOptions {
      * @param content - The raw frontmatter content string
      * @returns Parsed data object
      */
-    parser?: (content: string) => Record<string, any>;
+    parser?: (content: string, format: string) => Record<string, any>;
 }
 
 /**
@@ -17,6 +17,13 @@ export interface MikelFrontmatterOptions {
  */
 export type YamlParser = (yaml: string) => Record<string, any>;
 
+/**
+ * TOML parser function
+ * @param toml - TOML string to parse
+ * @returns Parsed object
+ */
+export type TomlParser = (toml: string) => Record<string, any>;
+
 /**
  * Mikel frontmatter plugin
  * @param options - Plugin configuration options
@@ -26,12 +33,11 @@ declare function mikelFrontmatter(options?: MikelFrontmatterOptions): {
     helpers: {
         frontmatter: (params: {
             args: any[];
-            opt?: Record<string, any>;
             options: Record<string, any>;
             tokens: string[];
             data: Record<string, any>;
-            variables: Record<string, any>;
-            fn: (blockData?: Record<string, any>, blockVars?: Record<string, any>, blockOutput?: string[]) => string;
+            state: Record<string, any>;
+            fn: (blockData?: Record<string, any>, blockState?: Record<string, any>, blockOutput?: string[]) => string;
         }) => string;
     };
 };
@@ -41,6 +47,7 @@ declare function mikelFrontmatter(options?: MikelFrontmatterOptions): {
  */
 declare namespace mikelFrontmatter {
     export const yamlParser: YamlParser;
+    export const tomlParser: TomlParser;
 }
 
 export default mikelFrontmatter;

package/index.js

@@ -1,17 +1,42 @@
+// @description split a string by separator, ignoring separators inside quotes
+const splitSafe = (str = "", separator = ",") => {
+    const result = [];
+    let current = "", inQuotes = false, quoteChar = null;
+    for (let i = 0; i < str.length; i++) {
+        const char = str[i];
+        if ((char === '"' || char === "'")) {
+            if (!inQuotes) {
+                inQuotes = true;
+                quoteChar = char;
+            } else if (char === quoteChar) {
+                inQuotes = false;
+                quoteChar = null;
+            }
+        }
+        if (char === separator && !inQuotes) {
+            result.push(current);
+            current = "";
+        } else {
+            current = current + char;
+        }
+    }
+    result.push(current);
+    return result;
+};
+
 // @description parse a single value from YAML
 const parseValue = (str = "") => {
-    // str = str.trim();
     // 1. quoted strings
     if ((str.startsWith(`"`) && str.endsWith(`"`)) || (str.startsWith(`'`) && str.endsWith(`'`))) {
         return str.slice(1, -1);
     }
     // 2. inline array
     if (str.startsWith("[") && str.endsWith("]")) {
-        return str.slice(1, -1).split(",").map(item => parseValue(item.trim()));
+        return splitSafe(str.slice(1, -1), ",").map(item => parseValue(item.trim()));
     }
     // 3. inline object
     if (str.startsWith("{") && str.endsWith("}")) {
-        return str.slice(1, -1).split(",").reduce((result, pair) => {
+        return splitSafe(str.slice(1, -1), ",").reduce((result, pair) => {
             const [key, value] = pair.split(":");
             if (key && value) {
                 result[key.trim()] = parseValue(value.trim());
@@ -43,77 +68,72 @@ const getIndent = (line = "") => {
     return line.length - line.trimStart().length;
 };
 
+// @description extract a key-value pair from a line
+const extractKeyValue = (line = "", separator = ":") => {
+    const separatorIndex = line.indexOf(separator);
+    return [
+        line.slice(0, separatorIndex).trim(),
+        line.slice(separatorIndex + 1).trim(),
+    ];
+};
+
 // @description parse a simple YAML string into an object
 const parseYaml = (yaml = "") => {
-    const lines = yaml.split("\n");
+    const lines = yaml.split("\n").filter(line => {
+        return line.trim() !== "" && !line.trim().startsWith("#");
+    });
     let i = 0;
     const parse = (minIndent = 0, result = {}) => {
         while (i < lines.length) {
-            const line = lines[i];
-            const trimmed = line.trim();
-            const indent = getIndent(line);
-      
-            // skip empty and comments
-            if (!trimmed || trimmed[0] === "#") {
-                i++;
-                continue;
-            }
-            // Return if dedented
+            const line = lines[i].trim();
+            const indent = getIndent(lines[i]);
+            // 1. return if dedented
             if (indent < minIndent) {
                 return result;
             }
-            // Array item
-            if (trimmed.startsWith("- ")) {
-                // First array item - initialize array
+            // 2. array item
+            else if (line.startsWith("- ")) {
+                // first array item - initialize array
                 if (!Array.isArray(result)) {
                     result = [];
                 }
-                const content = trimmed.slice(2).trim();
+                const content = line.slice(2).trim();
                 i++;
+                // check for nested content on next lines
                 if (!content) {
-                    // Nested content on next lines
                     result.push(parse(indent + 2, {}));
                 }
                 // inline content with key:value (object)
                 else if (content.includes(":")) {
                     const obj = {};
-                    const colonIdx = content.indexOf(":");
-                    if (colonIdx > 0) {
-                        obj[content.slice(0, colonIdx).trim()] = parseValue(content.slice(colonIdx + 1).trim());
-                    }
-                    // Check for nested content on following lines
+                    const [key, value] = extractKeyValue(content, ":");
+                    obj[key] = !!value ? parseValue(value) : null;
+                    // check for nested content on following lines
                     if (i < lines.length && getIndent(lines[i]) > indent) {
                         Object.assign(obj, parse(indent + 2, {}));
                     }
                     result.push(obj);
                 }
+                // simple value
                 else {
-                    // Simple value
                     result.push(parseValue(content));
                 }
             }
-            // Key-value pair
-            else if (trimmed.includes(":")) {
-                const colonIdx = trimmed.indexOf(":");
-                const key = trimmed.slice(0, colonIdx).trim();
-                const value = trimmed.slice(colonIdx + 1).trim();
+            // 3. key-value pair
+            else if (line.includes(":")) {
+                const [key, value] = extractKeyValue(line, ":");
                 i++;
-                if (!value) {
-                    // Check if next line is an array or object
-                    if (i < lines.length && getIndent(lines[i]) > indent) {
-                        const nextLine = lines[i].trim();
-                        if (nextLine.startsWith("- ")) {
-                            result[key] = parse(indent + 2, []);
-                        } else {
-                            result[key] = parse(indent + 2, {});
-                        }
-                    } else {
-                        result[key] = null;
-                    }
-                } else {
+                result[key] = null;
+                // check for inline content with key: value (object)
+                if (value) {
                     result[key] = parseValue(value);
                 }
+                // check if the next line is an array or object
+                else if (!value && i < lines.length && getIndent(lines[i]) > indent) {
+                    result[key] = parse(indent + 2, lines[i].trim().startsWith("- ") ? [] : {});
+                }
             }
+            // 4. other case??
             else {
                 i++;
             }
@@ -123,43 +143,92 @@ const parseYaml = (yaml = "") => {
     return parse(0, {});
 };
 
+// @description parse a simple TOML string into an object
+const parseToml = (toml = "") => {
+    const lines = toml.split("\n");
+    const result = {};
+    let currentTable = result;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!!line && !line.startsWith("#")) {
+            // 1. table header [section] or [[array]]
+            if (line.startsWith("[") && line.endsWith("]")) {
+                const isArray = line.startsWith("[[") && line.endsWith("]]");
+                const path = isArray ? line.slice(2, -2).trim() : line.slice(1, -1).trim();
+                currentTable = result;
+                path.split(".").forEach((part, index, parts) => {
+                    const isLast = index === parts.length - 1;
+                    // 1.1. if is an array of tables and is the last part
+                    if (isLast && isArray) {
+                        if (!Array.isArray(currentTable[part])) {
+                            currentTable[part] = [];
+                        }
+                        currentTable[part].push({});
+                        currentTable = currentTable[part][currentTable[part].length - 1];
+                    }
+                    // 1.2. other cases
+                    else {
+                        if (!currentTable[part]) {
+                            currentTable[part] = {};
+                        }
+                        if (Array.isArray(currentTable[part])) {
+                            currentTable = currentTable[part][currentTable[part].length - 1];
+                        }
+                        else {
+                            currentTable = currentTable[part];
+                        }
+                    }
+                });
+            }
+            // 2. key-value pair: key = value
+            else if (line.includes("=")) {
+                const [key, value] = extractKeyValue(line, "=");
+                currentTable[key] = parseValue(value);
+            }
+        }
+    }
+    return result;
+};
+ 
+
 // @description internal method to parse the content of the frontmatter block
-const parseFrontmatterBlock = (content = "", parser = null) => {
+const parseFrontmatterBlock = (content = "", format = "yaml", parser = null) => {
     // 1. use custom parser if provided
     if (typeof parser === "function") {
-        return parser(content);
+        return parser(content, format);
     }
-    // 2. guess format (YAML or JSON)
-    const trimmed = content.trim();
-    if ((trimmed.startsWith("{") && trimmed.endsWith("}")) || (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
-        return JSON.parse(content);
+    // 2. use the appropriate parser based on the format
+    if (format === "json") {
+        return JSON.parse(content.trim());
     }
+    if (format === "toml") {
+        return parseToml(content);
+    }
+    // 3. fallback to YAML
     return parseYaml(content);
 };
 
 // @description plugin to register a #frontmatter helper
 // @param {Object} options - plugin options
 // @param {Function} options.parser - custom YAML parser function
-const mikelFrontmatter = (options = {}) => {
-    return {
-        helpers: {
-            frontmatter: params => {
-                const variableName = params.options.as || "frontmatter";
-                // const format = params.options.format || "yaml";
-                const content = parseFrontmatterBlock(params.fn(params.data) || "", options.parser);
-                // register the variable (overwrite if it already exists)
-                Object.assign(params.variables, {
-                    [variableName]: content,
-                });
-                // don't render anything
-                return "";
-            },
+const mikelFrontmatter = (options = {}) => ({
+    helpers: {
+        frontmatter: params => {
+            const variableName = params.options.as || "frontmatter";
+            const format = params.options.format || "yaml";
+            // register the variable (overwrite if it already exists)
+            Object.assign(params.state, {
+                [variableName]: parseFrontmatterBlock(params.fn(params.data) || "", format, options.parser),
+            });
+            // don't render anything
+            return "";
         },
-    };
-};
+    },
+});
 
 // assign additional metadata to the plugin function
 mikelFrontmatter.yamlParser = parseYaml;
+mikelFrontmatter.tomlParser = parseToml;
 
 // export the plugin as default
 export default mikelFrontmatter;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "mikel-frontmatter",
     "description": "A mikel plugin to define new data inside templates using a frontmatter-like syntax.",
-    "version": "0.31.0",
+    "version": "0.33.0",
     "type": "module",
     "license": "MIT",
     "author": "Josemi Juanes",