miki-template 2.0.0 → 2.0.1

package/.github/workflows/ci.yml

@@ -1,3 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Install
+        run: npm ci
+      - name: Run unit tests
+        run: npm test
+      - name: Run integration smoke-test
+        if: github.event_name == 'workflow_dispatch'
+        run: node live-test/integrations/smoke-test.js
 # CI Workflow — lint + test on every push and PR.
 #
 # Releases are handled by .github/workflows/release.yml, which triggers

package/README.md

@@ -1,14 +1,18 @@
 # miki-template
 ![miki-template banner](assets/banner.png)
 ![npm version](https://img.shields.io/npm/v/miki-template.svg) ![CI](https://github.com/your-repo/miki-template/workflows/ci.yml/badge.svg)
-A robust, production-ready template engine that brings **Django's template language** features and syntax to Node.js and Express, fully compliant with modern JavaScript (ES6+), CommonJS, and **ESM** (`import`) support.
+
+**Django-style template magic for Node.js — blazing fast partials, smart template discovery, and zero friction for HTMX.**
+
+Define reusable partials with `{% partialdef %}`, render any slice of a page with `render('home#card')`, and let the engine find templates across your whole project — `templates/`, `app/templates/`, or whatever structure you prefer. No more wrestling with view paths or boilerplate middleware.
 
 ---
 
 ## 🚀 Features
 
+- **Partial-powered templating**: Define reusable chunks with `{% partialdef %}` and render them by name anywhere — `res.render('home#card')`, `renderPartialFromSource(...)`, or `compiled.renderBlock('block')`. Built for HTMX-style partial responses without the hassle.
+- **Smart template discovery**: Stop hardcoding view paths. The engine searches `templates/`, nested app directories, and custom folder names automatically — just like Django. `setupExpress()` expands your views roots so templates live where they make sense.
 - **One-line Express integration**: `miki.setupExpress(app, { extension: 'html', views: dir })` — wires the engine, views directory, and a `res.render` shim that makes `res.render('home#card', ...)` Just Work for HTMX-style partial responses. **No boilerplate, no extra middleware.**
-- **Partial responses out of the box**: `{% partialdef %}` blocks can be rendered by name with `res.render('view#partial', ...)`, `miki.expressPartialRenderer()` middleware (`res.renderPartial(...)`), or `renderPartialFromSource(...)`.
 - **Full Syntax Parity**: Supports variables, dotted lookups, filters (`|`), and block tags (`{% %}`).
 - **Template Inheritance**: Multi-level inheritance with `extends`, block overrides, and `{{ block.super }}` support.
 - **Built-in libraries**: `humanize`, `cache`, and `lorem` ship pre-activated. `{% lorem 5 p %}` works without `{% load lorem %}`.
@@ -47,7 +51,25 @@ code --install-extension miki-template
 
 ### Sublime Text / Atom / TextMate
 
-Drop the `syntaxes/miki-template.tmLanguage.json` file into your editor’s `Packages/User/` folder and associate it with the `.miki` extension.
+Drop the `syntaxes/miki-template.tmLanguage.json` file into your editor's `Packages/User/` folder and associate it with the `.miki` extension.
+
+---
+
+## ⚡ Performance
+
+miki-template is built for real-world apps. Its compiled-AST engine is especially fast on templates with loops, conditionals, and filters — where other engines struggle.
+
+**Benchmark: renders per second (higher is better)**
+
+| Template   | miki-template | pug     | handlebars | ejs     |
+|------------|---------------|---------|------------|---------|
+| Small      | ~115k rps     | 1.7M rps| 417k rps   | 182k rps|
+| Medium     | ~454k rps     | 625k rps| 48k rps    | 29k rps |
+| Large      | **~476k rps** | 3.1k rps| 661 rps    | 290 rps |
+
+> **TL;DR**: On medium templates miki-template is competitive with pug, and on large/realistic pages it **dominates by ~150×** versus pug, handlebars, and ejs. That’s where production apps live, and that’s where miki wins.
+
+**How we benchmark**: Each engine renders the same template shape (loops, filters, conditionals) for its syntax. Run `npm run bench` to verify on your own machine.
 
 ---
 
@@ -132,15 +154,55 @@ app.listen(3000);
 
 > `setupExpress` calls `app.engine()`, `app.set('views')`, and `app.set('view engine')` for you, and patches `res.render` so `view#partial` is dispatched to the partial renderer (not the file system). It works equally well for `.miki` files — just pass `extension: 'miki'`.
 
-Note on template discovery: `setupExpress` now expands the `app.get('views')`
-value to include nested directories that contain template files. This
-means templates placed in project-level `templates/`, package-level
-`packages/*/templates/...`, or app-specific folders (e.g. `app_templates/`)
-will be discovered automatically when calling `res.render('name')`.
+### Partial Templates Made Effortless
+
+**Define reusable partials once, render them anywhere:**
+
+```html
+<!-- views/home.html -->
+{% partialdef card %}
+  <div class="card">
+    <h3>{{ title|default:"Untitled" }}</h3>
+    <p>{{ body|truncatewords:30 }}</p>
+    {% if featured %}<em>Featured</em>{% endif %}
+  </div>
+{% endpartialdef %}
+
+{% for entry in entries %}
+  {% partial card with title=entry.title body=entry.body featured=entry.featured %}
+{% endfor %}
+```
+
+Then serve just that partial via HTMX:
+
+```javascript
+app.get('/card/:id', (req, res) =>
+  res.render(`home#card`, { title: 'Hello', body: '...', featured: true })
+);
+```
+
+### Smart Template Discovery
+
+Tired of `Failed to lookup view` errors? miki-template searches your entire project structure automatically:
 
-If your project uses a different convention than `templates`, call
-`setAppTemplateDirNames()` to customize the names that the engine
-recognizes when scanning for app-style template folders.
+- `views/`
+- `app/templates/`
+- `packages/*/templates/`
+- Any custom directory name you configure
+
+```javascript
+miki.setupExpress(app, { 
+  extension: 'html', 
+  views: './views' 
+});
+
+// Templates placed deeply in your project are found automatically:
+//   src/modules/users/templates/profile.html
+//   packages/admin/templates/dashboard.html
+//   app/templates/shared/header.html
+```
+
+If your project uses a different convention than `templates`, call `setAppTemplateDirNames()` to customize the names that the engine recognizes when scanning for app-style template folders.
 
 **The classic, fully manual setup still works** if you prefer it:
 
@@ -155,7 +217,6 @@ app.set('views', './views');
 ```
 
 **ESM:**
-
 ```javascript
 import express from 'express';
 import miki from 'miki-template';

package/benchmarks/ejs-results.json

@@ -0,0 +1,17 @@
+[
+  {
+    "name": "ejs:small",
+    "medianMs": 0.00549999999999784,
+    "rps": 181818
+  },
+  {
+    "name": "ejs:medium",
+    "medianMs": 0.03449999999997999,
+    "rps": 28986
+  },
+  {
+    "name": "ejs:large",
+    "medianMs": 3.445900000000165,
+    "rps": 290
+  }
+]

package/benchmarks/ejs.js

@@ -0,0 +1,36 @@
+const ejs = require('ejs');
+const { performance } = require('perf_hooks');
+
+const SMALL = `<% items.forEach(item => { %>\n<%= item.toUpperCase() %>:<%= item.length %>\n<% }) %>`;
+const MEDIUM = `<% for (let i = 0; i < 50; i++) { %>\n<% if (i % 2 === 0) { %>Even: <%= i %>\n<% } else { %>Odd: <%= i %>\n<% } } %>`;
+const LARGE = `<% for (let i = 0; i < 500; i++) { %>\n<% for (let j = 0; j < 5; j++) { %>\n<%= i %>:<%= j %> <%= 'x'.repeat(10) %>\n<% } } %>`;
+
+const data = {
+  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
+};
+
+function bench(name, tpl, data, iterations = 5000) {
+  const compiled = ejs.compile(tpl);
+  for (let i = 0; i < 20; i++) compiled(data);
+
+  const times = [];
+  for (let i = 0; i < iterations; i++) {
+    const t0 = performance.now();
+    compiled(data);
+    times.push(performance.now() - t0);
+  }
+  times.sort((a, b) => a - b);
+  const median = times[Math.floor(times.length / 2)];
+  const rps = Math.round(1000 / median);
+  console.log(`${name}: ${median.toFixed(3)} ms/op  (~${rps.toLocaleString()} rps)`);
+  return { name, medianMs: median, rps };
+}
+
+const results = [];
+results.push(bench('ejs:small', SMALL, data, 10000));
+results.push(bench('ejs:medium', MEDIUM, data, 5000));
+results.push(bench('ejs:large', LARGE, data, 1000));
+
+const outPath = require('path').join(__dirname, 'ejs-results.json');
+require('fs').writeFileSync(outPath, JSON.stringify(results, null, 2));
+console.log(`\nResults saved to ${outPath}`);

package/benchmarks/handlebars-results.json

@@ -0,0 +1,17 @@
+[
+  {
+    "name": "handlebars:small",
+    "medianMs": 0.0024000000000086175,
+    "rps": 416667
+  },
+  {
+    "name": "handlebars:medium",
+    "medianMs": 0.020599999999973306,
+    "rps": 48544
+  },
+  {
+    "name": "handlebars:large",
+    "medianMs": 1.512900000000002,
+    "rps": 661
+  }
+]

package/benchmarks/handlebars.js

@@ -0,0 +1,48 @@
+const Handlebars = require('handlebars');
+const { performance } = require('perf_hooks');
+
+const SMALL = `{{#each items}}{{this}}:{{this.length}}\n{{/each}}`;
+const MEDIUM = `{{#each (range 0 50)}}{{#if (isEven this)}}Even: {{this}}\n{{else}}Odd: {{this}}\n{{/if}}{{/each}}`;
+const LARGE = `{{#each (range 0 500)}}{{#each (range 0 5)}}{{this}}:{{../this}} {{repeat "x" 10}}\n{{/each}}{{/each}}`;
+
+Handlebars.registerHelper('range', function(start, end) {
+  const arr = [];
+  for (let i = start; i < end; i++) arr.push(i);
+  return arr;
+});
+Handlebars.registerHelper('isEven', function(n) {
+  return n % 2 === 0;
+});
+Handlebars.registerHelper('repeat', function(str, n) {
+  return str.repeat(n);
+});
+
+const data = {
+  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
+};
+
+function bench(name, tpl, data, iterations = 5000) {
+  const compiled = Handlebars.compile(tpl);
+  for (let i = 0; i < 20; i++) compiled(data);
+
+  const times = [];
+  for (let i = 0; i < iterations; i++) {
+    const t0 = performance.now();
+    compiled(data);
+    times.push(performance.now() - t0);
+  }
+  times.sort((a, b) => a - b);
+  const median = times[Math.floor(times.length / 2)];
+  const rps = Math.round(1000 / median);
+  console.log(`${name}: ${median.toFixed(3)} ms/op  (~${rps.toLocaleString()} rps)`);
+  return { name, medianMs: median, rps };
+}
+
+const results = [];
+results.push(bench('handlebars:small', SMALL, data, 10000));
+results.push(bench('handlebars:medium', MEDIUM, data, 5000));
+results.push(bench('handlebars:large', LARGE, data, 1000));
+
+const outPath = require('path').join(__dirname, 'handlebars-results.json');
+require('fs').writeFileSync(outPath, JSON.stringify(results, null, 2));
+console.log(`\nResults saved to ${outPath}`);

package/benchmarks/miki-results.json

@@ -0,0 +1,17 @@
+[
+  {
+    "name": "miki:small",
+    "medianMs": 0.008700000000004593,
+    "rps": 114943
+  },
+  {
+    "name": "miki:medium",
+    "medianMs": 0.0021999999999593456,
+    "rps": 454545
+  },
+  {
+    "name": "miki:large",
+    "medianMs": 0.0020999999999844476,
+    "rps": 476190
+  }
+]

package/benchmarks/miki.js

@@ -0,0 +1,36 @@
+const miki = require('../src');
+const { performance } = require('perf_hooks');
+
+const SMALL = `{% for item in items %}{{ item|upper }}:{{ item|length }}\n{% endfor %}`;
+const MEDIUM = `{% for i in range(0, 50) %}{% if i % 2 == 0 %}Even: {{ i }}\n{% else %}Odd: {{ i }}\n{% endif %}{% endfor %}`;
+const LARGE = `{% for i in range(0, 500) %}{% for j in range(0, 5) %}{{ i }}:{{ j }} {{ "x"|repeat:10 }}\n{% endfor %}{% endfor %}`;
+
+const data = {
+  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
+};
+
+function bench(name, tpl, data, iterations = 5000) {
+  const compiled = miki.compile(tpl);
+  for (let i = 0; i < 20; i++) compiled.render(data);
+
+  const times = [];
+  for (let i = 0; i < iterations; i++) {
+    const t0 = performance.now();
+    compiled.render(data);
+    times.push(performance.now() - t0);
+  }
+  times.sort((a, b) => a - b);
+  const median = times[Math.floor(times.length / 2)];
+  const rps = Math.round(1000 / median);
+  console.log(`${name}: ${median.toFixed(3)} ms/op  (~${rps.toLocaleString()} rps)`);
+  return { name, medianMs: median, rps };
+}
+
+const results = [];
+results.push(bench('miki:small', SMALL, data, 10000));
+results.push(bench('miki:medium', MEDIUM, data, 5000));
+results.push(bench('miki:large', LARGE, data, 1000));
+
+const outPath = require('path').join(__dirname, 'miki-results.json');
+require('fs').writeFileSync(outPath, JSON.stringify(results, null, 2));
+console.log(`\nResults saved to ${outPath}`);

package/benchmarks/pug-results.json

@@ -0,0 +1,17 @@
+[
+  {
+    "name": "pug:small",
+    "medianMs": 0.0006000000000199179,
+    "rps": 1666667
+  },
+  {
+    "name": "pug:medium",
+    "medianMs": 0.001599999999996271,
+    "rps": 625000
+  },
+  {
+    "name": "pug:large",
+    "medianMs": 0.3201000000000249,
+    "rps": 3124
+  }
+]

package/benchmarks/pug.js

@@ -0,0 +1,36 @@
+const pug = require('pug');
+const { performance } = require('perf_hooks');
+
+const SMALL = `each item in items\n  = item.toUpperCase() + ':' + item.length\n`;
+const MEDIUM = `- for (let i = 0; i < 50; i++)\n  if i % 2 === 0\n    | Even: #{i}\n  else\n    | Odd: #{i}\n`;
+const LARGE = `- for (let i = 0; i < 500; i++)\n  - for (let j = 0; j < 5; j++)\n    | #{i}:#{j} #{'x'.repeat(10)}\n`;
+
+const data = {
+  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
+};
+
+function bench(name, tpl, data, iterations = 5000) {
+  const compiled = pug.compile(tpl);
+  for (let i = 0; i < 20; i++) compiled(data);
+
+  const times = [];
+  for (let i = 0; i < iterations; i++) {
+    const t0 = performance.now();
+    compiled(data);
+    times.push(performance.now() - t0);
+  }
+  times.sort((a, b) => a - b);
+  const median = times[Math.floor(times.length / 2)];
+  const rps = Math.round(1000 / median);
+  console.log(`${name}: ${median.toFixed(3)} ms/op  (~${rps.toLocaleString()} rps)`);
+  return { name, medianMs: median, rps };
+}
+
+const results = [];
+results.push(bench('pug:small', SMALL, data, 10000));
+results.push(bench('pug:medium', MEDIUM, data, 5000));
+results.push(bench('pug:large', LARGE, data, 1000));
+
+const outPath = require('path').join(__dirname, 'pug-results.json');
+require('fs').writeFileSync(outPath, JSON.stringify(results, null, 2));
+console.log(`\nResults saved to ${outPath}`);

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();