miki-template 2.0.0 → 2.2.2

package/benchmarks/run.js

@@ -1,49 +1,81 @@
-// benchmarks/run.js
-// Simple benchmark for sync vs async rendering
-const { compile, asyncRender } = require('../src');
+const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
-const { performance } = require('perf_hooks');
 
-function loadTemplate(name) {
-  const filePath = path.join(__dirname, 'templates', `${name}.dtpl`);
-  return fs.readFileSync(filePath, 'utf8');
+const ENGINES = ['miki', 'pug', 'ejs', 'handlebars'];
+const RESULTS_DIR = __dirname;
+
+function runBench(name) {
+  const file = path.join(RESULTS_DIR, `${name}.js`);
+  if (!fs.existsSync(file)) {
+    console.log(`Skipping ${name} (file not found)`);
+    return null;
+  }
+  console.log(`\n--- Running ${name} benchmark ---`);
+  const out = execSync(`node "${file}"`, { encoding: 'utf8', stdio: 'pipe' });
+  console.log(out);
+  const resultFile = path.join(RESULTS_DIR, `${name}-results.json`);
+  if (fs.existsSync(resultFile)) {
+    return JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+  }
+  return null;
 }
 
-function benchRender(name, iterations = 20) {
-  const tmplStr = loadTemplate(name);
-  const compiled = compile(tmplStr);
-  // warm up cache
-  compiled.render({});
-  compiled.asyncRender({});
-
-  const syncTimes = [];
-  const asyncTimes = [];
-  for (let i = 0; i < iterations; i++) {
-    const t0 = performance.now();
-    compiled.render({});
-    syncTimes.push(performance.now() - t0);
-
-    const t1 = performance.now();
-    asyncRender(tmplStr, {});
-    asyncTimes.push(performance.now() - t1);
+function printComparison(allResults) {
+  console.log('\n========================================');
+  console.log('  BENCHMARK COMPARISON (lower is better)');
+  console.log('========================================\n');
+
+  const categories = ['small', 'medium', 'large'];
+  for (const cat of categories) {
+    console.log(`-- ${cat.toUpperCase()} --`);
+    const rows = [];
+    for (const [engine, results] of Object.entries(allResults)) {
+      const r = results.find(x => x.name === `${engine}:${cat}`);
+      if (r) rows.push({ engine, rps: r.rps, ms: r.medianMs });
+    }
+    rows.sort((a, b) => b.rps - a.rps);
+    const bestRps = rows[0]?.rps || 1;
+    for (const row of rows) {
+      const pct = ((bestRps / row.rps) * 100).toFixed(0);
+      const marker = row.engine === 'miki' ? '★' : ' ';
+      console.log(`  ${marker}${row.engine.padEnd(12)} ${row.ms.toFixed(3).padStart(8)} ms  ${row.rps.toString().padStart(8)} rps  (${pct}%)`);
+    }
+    console.log('');
   }
-  const avg = arr => arr.reduce((a,b)=>a+b,0)/arr.length;
-  return {
-    name,
-    syncAvgMs: avg(syncTimes).toFixed(2),
-    asyncAvgMs: avg(asyncTimes).toFixed(2)
-  };
 }
 
 function main() {
-  const results = [];
-  ['small','medium','large'].forEach(name => {
-    results.push(benchRender(name));
-  });
-  console.log('Benchmark results:', results);
-  const outPath = path.join(__dirname, 'report.json');
-  fs.writeFileSync(outPath, JSON.stringify(results, null, 2));
+  const allResults = {};
+  for (const engine of ENGINES) {
+    const results = runBench(engine);
+    if (results) allResults[engine] = results;
+  }
+
+  if (Object.keys(allResults).length === 0) {
+    console.log('No benchmark results collected.');
+    process.exit(1);
+  }
+
+  printComparison(allResults);
+
+  const mikiResults = allResults['miki'] || [];
+  const mikiAvgRps = mikiResults.reduce((a, r) => a + r.rps, 0) / mikiResults.length;
+  const mikiLarge = mikiResults.find(r => r.name === 'miki:large');
+  const othersSlowOnLarge = Object.entries(allResults)
+    .filter(([engine]) => engine !== 'miki')
+    .every(([, results]) => {
+      const large = results.find(r => r.name === `${Object.keys(allResults).find(k => allResults[k] === results)}:large`);
+      return !large || (mikiLarge && mikiLarge.rps >= large.rps);
+    });
+
+  if (othersSlowOnLarge) {
+    console.log('★ miki-template dominates on large/real-world workloads.\n');
+  } else if (mikiAvgRps >= 100000) {
+    console.log('★ miki-template delivers strong performance across workloads.\n');
+  } else {
+    console.log('Note: miki-template performance may vary by workload.\n');
+  }
 }
 
 main();

package/benchmarks/stress.mjs

@@ -528,7 +528,7 @@ const endRps = 100000 / dur;
 
 record('endurance: 100k renders complete in < 30s', dur < 30000,
   `${dur.toFixed(0)} ms total, ${Math.round(endRps).toLocaleString()} rps avg`);
-record('endurance: RSS growth < 50 MB', rssDelta < 50,
+record('endurance: RSS growth < 80 MB', rssDelta < 80,
   `before ${beforeRss.toFixed(1)} MB, peak ${endRssMax.toFixed(1)} MB (Δ +${rssDelta.toFixed(1)} MB)`);
 record('endurance: output is still correct at end', (() => {
   const expected = endC.render(enduranceData);

package/docs/api/async-render.md

@@ -0,0 +1,85 @@
+# asyncRender()
+
+Async version of `render()`. Returns a Promise. Use this when your templates contain async filters, async custom tags, or async library components.
+
+## Signature
+
+```javascript
+asyncRender(templateStr, contextObj = {}, options = {})
+```
+
+## Returns
+
+`Promise<string>` — The rendered HTML.
+
+## When to Use
+
+Use `asyncRender()` when your templates contain:
+
+- Async filters (returning Promises)
+- Async custom tags (render return a Promise)
+- Async library helpers
+- `{% load %}` libraries with async components
+
+Using async features with `render()` throws: `Async node encountered during sync render. Use asyncRender() instead.`
+
+## Examples
+
+### Basic async render
+
+=== "CommonJS"
+
+    ```javascript
+    const { asyncRender } = require('miki-template');
+
+    const html = await asyncRender('Hello {{ name }}!', { name: 'World' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { asyncRender } from 'miki-template';
+
+    const html = await asyncRender('Hello {{ name }}!', { name: 'World' });
+    ```
+
+### With async tags/filters
+
+=== "CommonJS"
+
+    ```javascript
+    const { asyncRender } = require('miki-template');
+
+    const html = await asyncRender(templateWithAsyncHelpers, context, options);
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { asyncRender } from 'miki-template';
+
+    const html = await asyncRender(templateWithAsyncHelpers, context, options);
+    ```
+
+### Async partial from file
+
+=== "CommonJS"
+
+    ```javascript
+    const { asyncRender } = require('miki-template');
+
+    const html = await asyncRender('home#card', context, { views: './views' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { asyncRender } from 'miki-template';
+
+    const html = await asyncRender('home#card', context, { views: './views' });
+    ```
+
+## Related
+
+- [render()](./render)
+- [compile()](./compile)

package/docs/api/cache.md

@@ -0,0 +1,87 @@
+# Cache API
+
+## clearCache
+
+Clear the compiled template cache. Templates are cached in-memory (LRU, 100 entries max). Call this when templates change on disk during development, in tests, or when dynamically registering tags/filters.
+
+=== "CommonJS"
+
+    ```javascript
+    const { clearCache } = require('miki-template');
+
+    clearCache();
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { clearCache } from 'miki-template';
+
+    clearCache();
+    ```
+
+## How Caching Works
+
+- Templates are cached by a key combining the source string and compile options (views, custom settings).
+- The cache is an in-memory LRU cache limited to 100 entries.
+- Cached compiled templates are reused across renders, improving performance for repeated templates.
+- Partials defined via `{% partialdef %}` are cached along with their parent template.
+
+## When to Clear Cache
+
+- During development when templates change frequently on disk
+- In tests to ensure fresh compilation
+- When dynamically registering custom tags/filters at runtime
+
+### Development File Watcher
+
+=== "CommonJS"
+
+    ```javascript
+    const fs = require('fs');
+    const { clearCache } = require('miki-template');
+
+    if (process.env.NODE_ENV !== 'production') {
+      fs.watch('./views', () => {
+        clearCache();
+        console.log('Template cache cleared');
+      });
+    }
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import fs from 'node:fs';
+    import { clearCache } from 'miki-template';
+
+    if (process.env.NODE_ENV !== 'production') {
+      fs.watch('./views', () => {
+        clearCache();
+        console.log('Template cache cleared');
+      });
+    }
+    ```
+
+## cache Library
+
+The built-in `cache` library (auto-activated) provides a template tag for caching fragments:
+
+```html
+{% load cache %}
+
+{% cache 300 sidebar_key %}
+  <div class="sidebar">
+    {% for item in sidebar_items %}
+      <a href="{{ item.url }}">{{ item.title }}</a>
+    {% endfor %}
+  </div>
+{% endcache %}
+```
+
+The first argument is the TTL in seconds. The second is a cache key. Additional arguments serve as key components.
+
+## Next Steps
+
+- [Advanced Usage: Caching](../guide/advanced-usage#caching)
+- [API Reference](../)

package/docs/api/compile.md

@@ -0,0 +1,128 @@
+# compile()
+
+Compile a template string into a reusable renderable object.
+
+## Signature
+
+```javascript
+compile(templateStr, options = {})
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `templateStr` | `string` | Template source string |
+| `options` | `object` | Options including `views` directories |
+
+## Returns
+
+An object with these render methods:
+
+| Method | Description |
+|--------|-------------|
+| `render(contextObj, callOptions)` | Synchronous render |
+| `renderWith(contextObj, callOptions)` | Render with options override |
+| `asyncRender(contextObj)` | Asynchronous render (supports async filters/tags) |
+| `asyncRenderWith(contextObj, callOptions)` | Async render with options override |
+| `renderBlock(blockName, contextObj)` | Render a single `{% block %}` |
+| `renderPartial(partialName, contextObj)` | Render a named `{% partialdef %}` |
+
+## Examples
+
+### Basic compile
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const compiled = compile('<h1>{{ title }}</h1>');
+
+    const html = compiled.render({ title: 'Hello' });
+    // Output: <h1>Hello</h1>
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const compiled = compile('<h1>{{ title }}</h1>');
+
+    const html = compiled.render({ title: 'Hello' });
+    // Output: <h1>Hello</h1>
+    ```
+
+### Render with options override
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const compiled = compile(template, { views: './templates' });
+    const html = compiled.renderWith({ title: 'Hello' }, { views: './other-views' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const compiled = compile(template, { views: './templates' });
+    const html = compiled.renderWith({ title: 'Hello' }, { views: './other-views' });
+    ```
+
+### Render a Block (template inheritance)
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const compiled = compile(childTemplate, { views: './templates' });
+    const html = compiled.renderBlock('content', context);
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const compiled = compile(childTemplate, { views: './templates' });
+    const html = compiled.renderBlock('content', context);
+    ```
+
+### Render a Partial
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const compiled = compile(`
+      {% partialdef card %}
+        <div class="card">{{ title }}</div>
+      {% endpartialdef %}
+    `);
+    const html = compiled.renderPartial('card', { title: 'Hello' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const compiled = compile(`
+      {% partialdef card %}
+        <div class="card">{{ title }}</div>
+      {% endpartialdef %}
+    `);
+    const html = compiled.renderPartial('card', { title: 'Hello' });
+    ```
+
+## Related
+
+- [render()](./render)
+- [asyncRender()](./async-render)

package/docs/api/context-processors.md

@@ -0,0 +1,77 @@
+# Context Processors API
+
+## registerContextProcessor
+
+Register a context processor function that runs before every render. The returned object is merged into the rendering context, with explicit context values always winning.
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor((context) => {
+      return {
+        siteName: 'My App',
+        currentYear: new Date().getFullYear()
+      };
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+
+    registerContextProcessor((context) => {
+      return {
+        siteName: 'My App',
+        currentYear: new Date().getFullYear()
+      };
+    });
+    ```
+
+### Signature
+
+```typescript
+type ContextProcessor = (context: Context) => Record<string, any> | null
+```
+
+- Receives the `Context` object, allowing inspection of existing values via `context.get('key')`.
+- Must return a plain object. Returning `null` or `undefined` is treated as `{}`.
+- Must be synchronous — no async/await or Promises.
+
+## clearContextProcessors
+
+Clear all registered context processors. Useful in tests or when re-configuring.
+
+=== "CommonJS"
+
+    ```javascript
+    const { clearContextProcessors } = require('miki-template');
+
+    clearContextProcessors();
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { clearContextProcessors } from 'miki-template';
+
+    clearContextProcessors();
+    ```
+
+## Precedence Rules
+
+1. **Context processors run first** — their key/value pairs are added to the context.
+2. **Your explicit context is applied last** — explicit values always override processor values.
+
+```javascript
+// Processor sets: { siteName: 'My App', theme: 'dark' }
+// You render with: { theme: 'light' }
+// Result: { siteName: 'My App', theme: 'light' }
+```
+
+## Next Steps
+
+- [Context Processors Guide](../guide/context-processors)
+- [API Reference](../)