miki-template 2.0.0 → 2.2.2

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)

package/docs/guide/context-processors.md

@@ -0,0 +1,257 @@
+# Context Processors
+
+Context processors are functions that automatically inject variables into every template render. This follows Django's context processor pattern — ideal for injecting global settings, user data, or feature flags.
+
+## Table of Contents
+
+- [How Context Processors Work](#how-context-processors-work)
+- [Register a Context Processor](#register-a-context-processor)
+- [Context Processor Signature](#context-processor-signature)
+- [Overriding Behavior](#overriding-behavior)
+- [Real-World Examples](#real-world-examples)
+- [Clearing Processors](#clearing-processors)
+
+---
+
+## How Context Processors Work
+
+Context processors run on **every render** (both `render()` and `compile().render()`). They return an object of key/value pairs that are merged into the rendering context **before** your template's local context is applied.
+
+```mermaid
+graph LR
+A[Your Context] --> B[Apply Processors]
+B --> C[Processor adds global vars]
+C --> D[Your Context wins]
+D --> E[Template renders]
+```
+
+**Key behavior:** Your explicit context values **always win** over processor values. This means you can override global defaults per-render without fighting the processor.
+
+## Register a Context Processor
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor((context) => {
+      return {
+        siteName: 'My App',
+        currentYear: new Date().getFullYear(),
+        debug: process.env.NODE_ENV !== 'production'
+      };
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+
+    registerContextProcessor((context) => {
+      return {
+        siteName: 'My App',
+        currentYear: new Date().getFullYear(),
+        debug: process.env.NODE_ENV !== 'production'
+      };
+    });
+    ```
+
+### Multiple Processors
+
+You can register multiple processors. They run in order — later processors can overwrite earlier ones:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor(() => ({ siteName: 'My App' }));
+    registerContextProcessor(() => ({ version: '2.0.0' }));
+    registerContextProcessor(() => ({
+      footerText: '© 2024 My App. All rights reserved.'
+    }));
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+
+    registerContextProcessor(() => ({ siteName: 'My App' }));
+    registerContextProcessor(() => ({ version: '2.0.0' }));
+    registerContextProcessor(() => ({
+      footerText: '© 2024 My App. All rights reserved.'
+    }));
+    ```
+
+## Context Processor Signature
+
+The processor function receives the rendering `context` as an argument and must return a plain object:
+
+```javascript
+registerContextProcessor((context) => {
+  // context is the full Context object — you can inspect contextObj
+  // but don't mutate it
+  return {
+    key: 'value'
+  };
+});
+```
+
+**Important:** If a processor returns `null`, `undefined`, or nothing, it's treated as returning an empty object `{}`. Processors must **not** return a Promise — if you need async data, compute it before rendering and pass it as context.
+
+## Overriding Behavior
+
+Since your explicit context always wins, you can override global defaults per-render:
+
+=== "CommonJS"
+
+    ```javascript
+    const { render } = require('miki-template');
+
+    // processor sets debug: false
+    // but this render overrides it:
+    render(template, { debug: true });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { render } from 'miki-template';
+
+    render(template, { debug: true });
+    ```
+
+## Real-World Examples
+
+### App-wide Settings
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor(() => ({
+      appName: process.env.APP_NAME || 'MyApp',
+      appVersion: require('./package.json').version,
+      environment: process.env.NODE_ENV || 'development',
+      apiUrl: process.env.API_URL || 'http://localhost:3000/api',
+      assetsUrl: process.env.ASSETS_URL || '/assets'
+    }));
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+    import pkg from './package.json' with { type: 'json' };
+
+    registerContextProcessor(() => ({
+      appName: process.env.APP_NAME || 'MyApp',
+      appVersion: pkg.version,
+      environment: process.env.NODE_ENV || 'development',
+      apiUrl: process.env.API_URL || 'http://localhost:3000/api',
+      assetsUrl: process.env.ASSETS_URL || '/assets'
+    }));
+    ```
+
+### User Authentication
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor((context) => {
+      const user = context.get('user');
+      if (!user) return {};
+      return {
+        user_name: user.name,
+        user_avatar: user.avatar || '/default-avatar.png',
+        user_is_admin: user.isAdmin || false
+      };
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+
+    registerContextProcessor((context) => {
+      const user = context.get('user');
+      if (!user) return {};
+      return {
+        user_name: user.name,
+        user_avatar: user.avatar || '/default-avatar.png',
+        user_is_admin: user.isAdmin || false
+      };
+    });
+    ```
+
+### Feature Flags
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor(() => ({
+      flags: {
+        newDashboard: process.env.FEATURE_NEW_DASHBOARD === 'true',
+        betaFeature: process.env.FEATURE_BETA === 'true',
+        darkModeDefault: process.env.FEATURE_DARK_MODE === 'true'
+      }
+    }));
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+
+    registerContextProcessor(() => ({
+      flags: {
+        newDashboard: process.env.FEATURE_NEW_DASHBOARD === 'true',
+        betaFeature: process.env.FEATURE_BETA === 'true',
+        darkModeDefault: process.env.FEATURE_DARK_MODE === 'true'
+      }
+    }));
+    ```
+
+Template usage:
+
+```html
+{% if flags.newDashboard %}
+  <a href="/new-dashboard">New Dashboard</a>
+{% else %}
+  <a href="/dashboard">Classic Dashboard</a>
+{% endif %}
+```
+
+## Clearing Processors
+
+Clear all registered processors (useful in tests or dynamic configuration):
+
+=== "CommonJS"
+
+    ```javascript
+    const { clearContextProcessors } = require('miki-template');
+
+    clearContextProcessors();
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { clearContextProcessors } from 'miki-template';
+
+    clearContextProcessors();
+    ```
+
+## Next Steps
+
+- [Advanced Usage: Context Processors](./advanced-usage)
+- [Async Rendering](./async-rendering)
+- [API Reference: Context Processors](../api/context-processors)