miki-template 2.0.0 → 2.2.2

package/.github/workflows/ci.yml

@@ -1,8 +1,3 @@
-# CI Workflow — lint + test on every push and PR.
-#
-# Releases are handled by .github/workflows/release.yml, which triggers
-# automatically when a `chore(release):` commit lands on main.
-
 name: CI
 
 on:
@@ -10,29 +5,38 @@ on:
     branches: [ main ]
   pull_request:
     branches: [ main ]
+  workflow_dispatch:
 
 jobs:
   lint:
-    runs-on: windows-latest
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '20'
+          cache: 'npm'
       - run: npm ci
       - name: Lint code
         run: npx eslint src/**/*.js
 
   test:
-    runs-on: windows-latest
+    runs-on: ubuntu-latest
     needs: lint
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
     steps:
       - uses: actions/checkout@v4
-      - name: Setup Node.js
+      - name: Use Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
       - run: npm ci
-      - name: Run test suite
+      - 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

package/.github/workflows/docs.yml

@@ -0,0 +1,105 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: 'requirements-docs.txt'
+
+      - name: Install MkDocs Material with imaging support
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-docs.txt
+
+      - name: Verify docs build
+        run: mkdocs build --strict
+
+      - name: Deploy docs to GitHub Pages
+        run: mkdocs gh-deploy --force --message "chore: deploy docs to GitHub Pages [skip ci]"
+
+      - name: Output Pages URL
+        run: echo "Docs deployed to https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"
+
+  sync-wiki:
+    runs-on: ubuntu-latest
+    needs: deploy-docs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Git config
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Create wiki clone directory
+        run: mkdir -p wiki-repo
+
+      - name: Clone wiki repository
+        run: |
+          git clone https://github.com/${{ github.repository }}.wiki.git wiki-repo || true
+
+      - name: Sync docs to wiki
+        if: hashFiles('wiki-repo/.git/config') != ''
+        run: |
+          cd wiki-repo
+          
+          # Copy all markdown docs preserving directory structure
+          cp -r ../docs/*.md .
+          cp -r ../docs/guide/*.md ./guide/ 2>/dev/null || true
+          cp -r ../docs/api/*.md ./api/ 2>/dev/null || true
+          cp -r ../docs/integrations/*.md ./integrations/ 2>/dev/null || true
+          
+          # Remove index.md if it exists (GitHub wiki uses README.md as home page)
+          if [ -f index.md ]; then
+            if [ -f README.md ]; then
+              rm index.md
+            else
+              mv index.md README.md
+            fi
+          fi
+          
+          # Create Home.md from index.md if README.md doesn't exist
+          if [ ! -f README.md ] && [ ! -f Home.md ] && [ -f docs/index.md ]; then
+            cp docs/index.md Home.md
+          fi
+          
+          # Commit and push if there are changes
+          git add -A
+          git diff --cached --quiet || {
+            git commit -m "docs: sync documentation to wiki"
+            git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.wiki.git master
+          }
+
+      - name: Wiki initialization hint
+        if: hashFiles('wiki-repo/.git/config') == ''
+        run: |
+          echo "::warning::Wiki repository not found. Enable the wiki in repository settings first."
+          echo "Go to https://github.com/${{ github.repository }}/settings/wiki and click 'Create the first page'"
+        continue-on-error: true

package/.github/workflows/npm-publish-github-packages.yml

@@ -0,0 +1,36 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+
+  publish-gpr:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://npm.pkg.github.com/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

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,20 +51,37 @@ 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.
 
 ---
 
 ## 📚 Documentation
 
-- [Installation](docs/installation.md)
-- [Usage Guide](docs/usage.md)
-- [Tags Reference](docs/tags.md)
-- [Filters Reference](docs/filters.md)
-- [Security](docs/security.md)
-- [API Reference](docs/api.md)
-- [Partial Definitions](docs/partialdef.md)
-- [Contributing](docs/advanced_usage.md)
+- **[Documentation](https://alainmiki.github.io/miki-template/)** — Full docs site
+- [Getting Started](https://alainmiki.github.io/miki-template/guide/getting-started)
+- [Installation](https://alainmiki.github.io/miki-template/guide/installation)
+- [Quick Start](https://alainmiki.github.io/miki-template/guide/quick-start)
+- [API Reference](https://alainmiki.github.io/miki-template/api/)
+- [Integrations](https://alainmiki.github.io/miki-template/integrations/)
+- [Performance](https://alainmiki.github.io/miki-template/performance)
 
 ---
 
@@ -132,15 +153,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 +216,6 @@ app.set('views', './views');
 ```
 
 **ESM:**
-
 ```javascript
 import express from 'express';
 import miki from 'miki-template';
@@ -191,13 +251,14 @@ Resolve properties dynamically on nested objects or arrays. If the resolved valu
 
 ### Built-in Filters
 Apply filters using pipes (`|`). Arguments are passed after a colon (`:`).
-- **Text**: `upper`, `lower`, `title`, `capfirst`, `slugify`, `wordcount`, `striptags`, `linebreaks`, `linebreaksbr`, `truncatewords:N`, `truncatechars:N`.
+- **Text**: `upper`, `lower`, `title`, `capfirst`, `slugify`, `wordcount`, `striptags`, `linebreaks`, `linebreaksbr`, `truncatewords:N`, `truncatechars:N`, `truncatechars_html:N`.
 - **HTML**: `safe`, `escape`.
-- **List**: `length`, `join:","`, `slice:"start:end"`, `dictsort:"key"`, `dictsortreversed:"key"`.
-- **Default**: `default:"fallback"`, `default_if_none:"fallback"`.
-- **Date/Time**: `date:"Y-m-d"`, `time:"H:i"`, `timesince`, `timeuntil`.
-- **Numeric**: `add:5`, `divisibleby:2`, `floatformat:2`.
-- **Misc**: `yesno:"yes,no,maybe"`, `pluralize:"suffix"`, `filesizeformat`.
+- **List**: `length`, `join:","`, `slice:"start:end"`, `dictsort:"key"`, `dictsortreversed:"key"`, `sort`, `unique`, `random`, `reverse`, `split:","`, `replace:"old,new"`.
+- **Default**: `default:"fallback"`, `default_if_none:"fallback"`, `firstof:v1 v2 v3`.
+- **Date/Time**: `date:"Y-m-d"`, `time:"H:i"`, `date_format:"yyyy-MM-dd"`, `strftime:"PPpp"`, `timesince`, `timeuntil`, `ago`, `until`, `time_diff:other_date`.
+- **Numeric**: `add:5`, `sub:3`, `mult:2`, `divisibleby:2`, `mod:3`, `floatformat:2`, `square`, `sqrt`, `abs`, `round:2`, `floor`, `ceil`, `min:10`, `max:100`, `sum`, `average`.
+- **Currency/Data**: `currency:"$"`, `phone_number`, `email`, `url`, `mask:"*"`, `whatsapp_link:"msg"`, `credit_card`, `ssn`, `ip_address`, `uuid`, `filesizeformat`, `yesno:"yes,no,maybe"`, `pluralize:"s"`, `urlencode`, `escapeuri`, `stringformat:"%s"`, `cut:"text"`, `addslashes`, `removetags:"p,div"`, `trans`, `regroup:"attr"`, `json`, `urlize`.
+- **Encoding**: `base64_encode`, `base64_decode`.
 
 ### Built-in Control Tags
 - **if / elif / else / endif**: Supports conditional expressions with operators: `==`, `!=`, `<`, `<=`, `>`, `>=`, `in`, `not in`, `and`, `or`, `not`.
@@ -230,9 +291,64 @@ Apply filters using pipes (`|`). Arguments are passed after a colon (`:`).
     <tr class="{% cycle 'row-odd' 'row-even' %}">...</tr>
   {% endfor %}
   ```
+- **firstof**: Return the first truthy value.
+  ```html
+  {% firstof var1 var2 var3 "fallback" %}
+  ```
+- **set**: Assign variables.
+  ```html
+  {% set total = price * quantity %}
+  {% set greeting %}Hello {{ name }}{% endset %}
+  ```
+- **ifchanged / endifchanged**: Render only when value changes.
+  ```html
+  {% for item in items %}
+    {% ifchanged item.category %}
+      <h2>{{ item.category }}</h2>
+    {% endifchanged %}
+  {% endfor %}
+  ```
+- **now**: Output current date/time.
+  ```html
+  {% now "Y-m-d H:i:s" %}
+  ```
+- **static**: Generate static file URLs.
+  ```html
+  {% static "css/style.css" %}
+  ```
+- **url**: Build URLs from route names.
+  ```html
+  {% url 'user.profile' user.id %}
+  ```
+- **regroup**: Group lists by attribute.
+  ```html
+  {% for group in items|regroup:"category" %}
+    <h3>{{ group.grouper }}</h3>
+  {% endfor %}
+  ```
+- **spaceless**: Remove whitespace between tags.
+  ```html
+  {% spaceless %}<div>  <span>hi</span>  </div>{% endspaceless %}
+  ```
+- **widthratio**: Calculate ratios.
+  ```html
+  {% widthratio value max max_width %}
+  ```
+- **debug**: Dump template context.
+  ```html
+  {% debug %}
+  ```
 - **autoescape on/off**: Control auto-escaping block behavior.
 - **verbatim / endverbatim**: Treat raw text inside literally.
 - **comment / endcomment**: Block comment ignored during parse.
+- **load**: Activate template libraries.
+  ```html
+  {% load lorem humanize %}
+  ```
+- **templatetag**: Output literal template tag tokens.
+  ```html
+  {% templatetag openblock %} if user.is_admin {% templatetag closeblock %}
+  ```
 
 ### Security Tags
 - **csrf_token**: Automatically outputs a hidden input carrying the CSRF token from the context variable `csrf_token`.

package/benchmarks/ejs-results.json

@@ -0,0 +1,17 @@
+[
+  {
+    "name": "ejs:small",
+    "medianMs": 0.00549999999999784,
+    "rps": 181818
+  },
+  {
+    "name": "ejs:medium",
+    "medianMs": 0.033799999999985175,
+    "rps": 29586
+  },
+  {
+    "name": "ejs:large",
+    "medianMs": 3.5704000000000633,
+    "rps": 280
+  }
+]

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.0024999999999977263,
+    "rps": 400000
+  },
+  {
+    "name": "handlebars:medium",
+    "medianMs": 0.019200000000012096,
+    "rps": 52083
+  },
+  {
+    "name": "handlebars:large",
+    "medianMs": 1.5285000000001219,
+    "rps": 654
+  }
+]

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.00899999999998613,
+    "rps": 111111
+  },
+  {
+    "name": "miki:medium",
+    "medianMs": 0.0021999999999593456,
+    "rps": 454545
+  },
+  {
+    "name": "miki:large",
+    "medianMs": 0.002200000000016189,
+    "rps": 454545
+  }
+]

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.0006999999999948159,
+    "rps": 1428571
+  },
+  {
+    "name": "pug:medium",
+    "medianMs": 0.001599999999996271,
+    "rps": 625000
+  },
+  {
+    "name": "pug:large",
+    "medianMs": 0.33320000000003347,
+    "rps": 3001
+  }
+]

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}`);