miki-template 2.0.1 → 2.2.3

package/docs/guide/advanced-usage.md

@@ -0,0 +1,397 @@
+# Advanced Usage
+
+This guide covers advanced miki-template features: caching, library system, i18n, and more.
+
+## Table of Contents
+
+- [Caching](#caching)
+- [Library System](#library-system)
+- [i18n / Internationalization](#i18n--internationalization)
+- [Template Discovery](#template-discovery)
+- [Partial Templates](#partial-templates)
+- [Extending the Engine](#extending-the-engine)
+
+---
+
+## Caching
+
+miki-template caches compiled templates for performance. The cache is an in-memory LRU with a 100-entry limit.
+
+### Clearing the Cache
+
+=== "CommonJS"
+
+    ```javascript
+    const { clearCache } = require('miki-template');
+
+    clearCache();
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { clearCache } from 'miki-template';
+
+    clearCache();
+    ```
+
+### When to Clear Cache
+
+- **Development** — when templates change frequently on disk
+- **Tests** — to ensure fresh compilation
+- **Runtime filter/tag registration** — when dynamically registering custom tags/filters
+
+```javascript
+// Development middleware that clears cache on file changes
+const { clearCache } = require('miki-template');
+
+if (process.env.NODE_ENV !== 'production') {
+  fs.watch('./views', () => {
+    clearCache();
+    console.log('Template cache cleared');
+  });
+}
+```
+
+### How Caching Works
+
+- Templates are cached by source string and compile options.
+- The cache key combines the template source and the options object (views, custom settings).
+- Cached templates are reused across renders, improving performance for repeated templates.
+
+## Library System
+
+Libraries are bundles of filters, tags, and helpers that can be loaded into templates. Built-in libraries (humanize, cache, lorem, markdown, i18n) are auto-activated.
+
+### Registering a Library
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerLibrary } = require('miki-template');
+
+    registerLibrary('myutils', {
+      filters: {
+        shout: (val) => String(val).toUpperCase() + '!',
+        whisper: (val) => String(val).toLowerCase() + '...'
+      },
+      tags: {
+        timestamp: (tagContent, parser) => ({
+          render: () => new Date().toISOString()
+        })
+      },
+      helpers: {
+        formatPrice: (val) => `$${Number(val).toFixed(2)}`
+      }
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerLibrary } from 'miki-template';
+
+    registerLibrary('myutils', {
+      filters: {
+        shout: (val) => String(val).toUpperCase() + '!',
+        whisper: (val) => String(val).toLowerCase() + '...'
+      },
+      tags: {
+        timestamp: (tagContent, parser) => ({
+          render: () => new Date().toISOString()
+        })
+      },
+      helpers: {
+        formatPrice: (val) => `$${Number(val).toFixed(2)}`
+      }
+    });
+    ```
+
+### Loading Libraries in Templates
+
+Once registered, load the library with `{% load %}`:
+
+```html
+{% load myutils %}
+
+{{ price|formatPrice }}
+{{ message|shout }}
+{% timestamp %}
+```
+
+### Built-in Libraries
+
+The following libraries are auto-activated (no `{% load %}` needed):
+
+| Library | Features |
+|---------|----------|
+| `humanize` | Natural date formatting, number formatting |
+| `cache` | Cache control tags and filters |
+| `lorem` | Lorem ipsum placeholder text |
+| `markdown` | `{{ content|markdown }}` filter for Markdown→HTML |
+| `i18n` | `{% trans %}` and `{% blocktrans %}` for translations |
+
+### Deactivating and Re-registering
+
+=== "CommonJS"
+
+    ```javascript
+    const { unregisterLibrary, activateLibrary } = require('miki-template');
+
+    // Remove a library
+    unregisterLibrary('lorem');
+
+    // Re-activate
+    activateLibrary('lorem');
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { unregisterLibrary, activateLibrary } from 'miki-template';
+
+    unregisterLibrary('lorem');
+    activateLibrary('lorem');
+    ```
+
+## i18n / Internationalization
+
+miki-template includes a built-in i18n system supporting `{% trans %}` and `{% blocktrans %}` tags.
+
+### Registering Translations
+
+=== "CommonJS"
+
+    ```javascript
+    const miki = require('miki-template');
+
+    miki.setLanguage('fr');
+    miki.registerTranslation('fr', {
+      'Hello': 'Bonjour',
+      'Goodbye': 'Au revoir',
+      'Welcome, {name}!': 'Bienvenue, {name} !'
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { setLanguage, registerTranslation } from 'miki-template';
+
+    setLanguage('fr');
+    registerTranslation('fr', {
+      'Hello': 'Bonjour',
+      'Goodbye': 'Au revoir',
+      'Welcome, {name}!': 'Bienvenue, {name} !'
+    });
+    ```
+
+### Setting Fallback Language
+
+=== "CommonJS"
+
+    ```javascript
+    const { setLanguage, setFallbackLanguage } = require('miki-template');
+
+    setLanguage('fr');
+    setFallbackLanguage('en');
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { setLanguage, setFallbackLanguage } from 'miki-template';
+
+    setLanguage('fr');
+    setFallbackLanguage('en');
+    ```
+
+### Template Usage
+
+```html
+{% trans "Hello" %}
+{% blocktrans %}Welcome, {{ name }}!{% endblocktrans %}
+```
+
+### Managing Languages
+
+=== "CommonJS"
+
+    ```javascript
+    const {
+      registerTranslation,
+      unregisterTranslation,
+      setLanguage,
+      getLanguage,
+      setFallbackLanguage,
+      getFallbackLanguage,
+      getAvailableLanguages
+    } = require('miki-template');
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import {
+      registerTranslation,
+      unregisterTranslation,
+      setLanguage,
+      getLanguage,
+      setFallbackLanguage,
+      getFallbackLanguage,
+      getAvailableLanguages
+    } from 'miki-template';
+    ```
+
+## Template Discovery
+
+The `findTemplateInViews()` function intelligently locates templates in nested directories.
+
+=== "CommonJS"
+
+    ```javascript
+    const { findTemplateInViews, setAppTemplateDirNames } = require('miki-template');
+
+    // Customize which directory names are treated as app template roots
+    setAppTemplateDirNames(['templates', 'views', 'pages']);
+
+    // Search for a template by name
+    const found = findTemplateInViews('home', ['./views', './app/templates']);
+    console.log(found);
+    // → /absolute/path/to/app/templates/home.html
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { findTemplateInViews, setAppTemplateDirNames } from 'miki-template';
+
+    setAppTemplateDirNames(['templates', 'views', 'pages']);
+    const found = findTemplateInViews('home', ['./views', './app/templates']);
+    console.log(found);
+    ```
+
+## Partial Templates
+
+Partials let you define reusable template fragments using `{% partialdef %}` and render them on demand.
+
+### Defining and Rendering Partials
+
+```html
+{% partialdef card %}
+  <div class="card">
+    <h3>{{ user.name }}</h3>
+    <p>{{ user.email }}</p>
+  </div>
+{% endpartialdef %}
+```
+
+Render a partial:
+
+=== "CommonJS"
+
+    ```javascript
+    const { render, compile } = require('miki-template');
+
+    // Using render() with file partials:
+    const html = render('home#card', { user: userData }, { views: './views' });
+
+    // Using compiled.renderPartial():
+    const compiled = compile(templateString);
+    const partialHtml = compiled.renderPartial('card', { user: userData });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { render, compile } from 'miki-template';
+
+    const html = render('home#card', { user: userData }, { views: './views' });
+
+    const compiled = compile(templateString);
+    const partialHtml = compiled.renderPartial('card', { user: userData });
+    ```
+
+### Partial with Context
+
+```html
+{% partialdef greeting %}
+  Hello, {{ name }}! You have {{ count }} messages.
+{% endpartialdef %}
+
+{% partial greeting with name="Alice" count=3 %}
+```
+
+## Extending the Engine
+
+### Registering Custom Tags
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerTag } = require('miki-template');
+
+    registerTag('markdown', (tagContent, parser) => {
+      const nodelist = parser.parse(['endmarkdown']);
+      parser.skipTag();
+      const { marked } = require('marked');
+
+      return {
+        render: (context) => {
+          const body = nodelist.map(n => n.render(context)).join('');
+          return markSafe(marked(body));
+        }
+      };
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerTag, markSafe } from 'miki-template';
+    import { marked } from 'marked';
+
+    registerTag('markdown', (tagContent, parser) => {
+      const nodelist = parser.parse(['endmarkdown']);
+      parser.skipTag();
+
+      return {
+        render: (context) => {
+          const body = nodelist.map(n => n.render(context)).join('');
+          return markSafe(marked(body));
+        }
+      };
+    });
+    ```
+
+### Registering Custom Helpers
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerHelper } = require('miki-template');
+
+    registerHelper('truncate_words', (str, count) => {
+      const words = String(str).split(/\s+/);
+      return words.slice(0, count).join(' ') + (words.length > count ? '...' : '');
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerHelper } from 'miki-template';
+
+    registerHelper('truncate_words', (str, count) => {
+      const words = String(str).split(/\s+/);
+      return words.slice(0, count).join(' ') + (words.length > count ? '...' : '');
+    });
+    ```
+
+## Next Steps
+
+- [Custom Tags](./custom-tags)
+- [Custom Filters](./custom-filters)
+- [API Reference: Libraries](../api/libraries)
+- [API Reference: Cache](../api/cache)
+- [API Reference: i18n](../api/i18n)

package/docs/guide/async-rendering.md

@@ -0,0 +1,308 @@
+# Async Rendering
+
+miki-template supports async rendering for templates that use async filters, async custom tags, or async library components. Use `asyncRender()` instead of `render()` to await these operations.
+
+## Table of Contents
+
+- [When to Use Async Rendering](#when-to-use-async-rendering)
+- [asyncRender()](#asyncrender)
+- [compiled.asyncRender()](#compiledasyncrender)
+- [Async Filters](#async-filters)
+- [Async Custom Tags](#async-custom-tags)
+- [Express Async Engine](#express-async-engine)
+
+---
+
+## When to Use Async Rendering
+
+Use `asyncRender()` when your templates contain any of the following:
+
+- **Async filters** — filters that return Promises
+- **Async custom tags** — custom tags whose `render()` returns a Promise
+- **Async library components** — i18n translations loaded dynamically
+- **Async helpers** — helpers that perform I/O
+
+If you use async features with `render()` or `compiled.render()`, the engine throws:
+
+> Async node encountered during sync render. Use asyncRender() instead.
+
+## asyncRender()
+
+=== "CommonJS"
+
+    ```javascript
+    const { asyncRender } = require('miki-template');
+
+    const html = await asyncRender('Hello, {{ name }}!', { name: 'World' });
+    console.log(html);
+    // → "Hello, World!"
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { asyncRender } from 'miki-template';
+
+    const html = await asyncRender('Hello, {{ name }}!', { name: 'World' });
+    console.log(html);
+    // → "Hello, World!"
+    ```
+
+### With Views and Partials
+
+=== "CommonJS"
+
+    ```javascript
+    const { asyncRender } = require('miki-template');
+
+    // Render a single partial from a file
+    const html = await asyncRender('home#card', { user: userData }, {
+      views: './templates'
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { asyncRender } from 'miki-template';
+
+    const html = await asyncRender('home#card', { user: userData }, {
+      views: './templates'
+    });
+    ```
+
+## compiled.asyncRender()
+
+When you pre-compile a template, the returned object has `asyncRender()` and `asyncRenderWith()` methods:
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const template = `
+      {% load markdown %}
+      {{ content|markdown }}
+    `;
+
+    const compiled = compile(template);
+    const html = await compiled.asyncRender({ content: '# Hello World' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const template = `
+      {% load markdown %}
+      {{ content|markdown }}
+    `;
+
+    const compiled = compile(template);
+    const html = await compiled.asyncRender({ content: '# Hello World' });
+    ```
+
+## Async Filters
+
+Filters that return Promises are automatically awaited when using `asyncRender()`:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerFilter, asyncRender } = require('miki-template');
+
+    registerFilter('to_upper', (val) => val.toUpperCase());
+    registerFilter('fetch_url', async (url) => {
+      const res = await fetch(url);
+      return res.text();
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerFilter, asyncRender } from 'miki-template';
+
+    registerFilter('to_upper', (val) => val.toUpperCase());
+    registerFilter('fetch_url', async (url) => {
+      const res = await fetch(url);
+      return res.text();
+    });
+    ```
+
+Usage:
+
+```html
+{{ api_endpoint|fetch_url }}
+```
+
+**Real-world CMS content fetch:**
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerFilter, asyncRender } = require('miki-template');
+
+    registerFilter('cms_content', async (id) => {
+      const res = await fetch(`https://cms.example.com/api/content/${id}`);
+      const data = await res.json();
+      return data.html;
+    });
+
+    const html = await asyncRender(
+      '{% autoescape off %}{{ page_id|cms_content }}{% endautoescape %}',
+      { page_id: 'about' }
+    );
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerFilter, asyncRender } from 'miki-template';
+
+    registerFilter('cms_content', async (id) => {
+      const res = await fetch(`https://cms.example.com/api/content/${id}`);
+      const data = await res.json();
+      return data.html;
+    });
+
+    const html = await asyncRender(
+      '{% autoescape off %}{{ page_id|cms_content }}{% endautoescape %}',
+      { page_id: 'about' }
+    );
+    ```
+
+## Async Custom Tags
+
+Custom tags whose `render()` returns a Promise work with `asyncRender()`:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerTag, asyncRender } = require('miki-template');
+
+    registerTag('api_data', (tagContent, parser) => {
+      const endpoint = tagContent.trim();
+      return {
+        async render(context) {
+          const res = await fetch(context.get(endpoint));
+          const data = await res.json();
+          return JSON.stringify(data, null, 2);
+        }
+      };
+    });
+
+    const html = await asyncRender(
+      '{% api_data api_url %}',
+      { api_url: 'https://api.example.com/users' }
+    );
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerTag, asyncRender } from 'miki-template';
+
+    registerTag('api_data', (tagContent, parser) => {
+      const endpoint = tagContent.trim();
+      return {
+        async render(context) {
+          const res = await fetch(context.get(endpoint));
+          const data = await res.json();
+          return JSON.stringify(data, null, 2);
+        }
+      };
+    });
+
+    const html = await asyncRender(
+      '{% api_data api_url %}',
+      { api_url: 'https://api.example.com/users' }
+    );
+    ```
+
+## Express Async Engine
+
+For Express apps with async templates, use `__expressAsync` or `express({ async: true })`:
+
+=== "CommonJS"
+
+    ```javascript
+    const express = require('express');
+    const miki = require('miki-template');
+
+    const app = express();
+    app.engine('html', miki.express({ async: true }));
+    app.set('view engine', 'html');
+    app.set('views', './views');
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import express from 'express';
+    import miki from 'miki-template';
+
+    const app = express();
+    app.engine('html', miki.express({ async: true }));
+    app.set('view engine', 'html');
+    app.set('views', './views');
+    ```
+
+### Express 5+ Native Promise Support
+
+If you're using Express 5 (which supports Promise-based view engines), use `__expressAsync` directly:
+
+=== "CommonJS"
+
+    ```javascript
+    const express = require('express');
+    const miki = require('miki-template');
+
+    app.engine('html', miki.__expressAsync);
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import express from 'express';
+    import miki from 'miki-template';
+
+    app.engine('html', miki.__expressAsync);
+    ```
+
+## asyncRenderWith()
+
+Override compile-time options at render time:
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const compiled = compile(template, { views: './views' });
+
+    const html = await compiled.asyncRenderWith(
+      { user: userData },
+      { views: './other-views', customOption: true }
+    );
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const compiled = compile(template, { views: './views' });
+
+    const html = await compiled.asyncRenderWith(
+      { user: userData },
+      { views: './other-views', customOption: true }
+    );
+    ```
+
+## Next Steps
+
+- [Custom Filters: Async Filters](./custom-filters#async-filters)
+- [Custom Tags: Async Custom Tags](./custom-tags#async-custom-tags)
+- [API Reference: asyncRender](../api/async-render)