miki-template 2.2.3 → 2.3.1

package/.github/workflows/docs.yml

@@ -37,9 +37,11 @@ jobs:
 
       - name: Verify docs build
         run: mkdocs build --strict
+        env:
+          NO_MKDOCS_2_WARNING: 1
 
       - name: Deploy docs to GitHub Pages
-        run: 'mkdocs gh-deploy --force --message "chore: deploy docs to GitHub Pages "'
+        run: 'mkdocs gh-deploy --force --message "chore: deploy docs to GitHub Pages"'
 
       - name: Output Pages URL
         run: echo "Docs deployed to https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"

package/.github/workflows/release.yml

@@ -105,8 +105,3 @@ jobs:
         run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Publish to GitHub Packages
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/README.md

@@ -1,11 +1,16 @@
 # 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)
 
 **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.
 
+miki comes with more tags and filters that are not in django/jinja and miki templates supports all django tags and filters plus it own additional tags and filters.
+you can register your own custom filters and filters in miki templates.
+
 ---
 
 ## 🚀 Features
@@ -61,11 +66,18 @@ miki-template is built for real-world apps. Its compiled-AST engine is especiall
 
 **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 |
+
+| Template | miki-template | pug | handlebars | ejs |
+
+|----------|--------------|-----|------------|-----|
+
+| Small | ~1.1M rps | 1.1M rps | 300k rps | 113k rps |
+
+| Medium | ~40k rps | 27k rps | 4k rps | 2k rps |
+
+| Large | **~2530 rps** | 1886 rps | 493 rps | 1881 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.
 

package/benchmarks/ejs-results.json

@@ -1,17 +1,17 @@
 [
   {
     "name": "ejs:small",
-    "medianMs": 0.00549999999999784,
-    "rps": 181818
+    "medianMs": 0.005599999999994054,
+    "rps": 178571
   },
   {
     "name": "ejs:medium",
-    "medianMs": 0.033799999999985175,
-    "rps": 29586
+    "medianMs": 0.3426000000000613,
+    "rps": 2919
   },
   {
     "name": "ejs:large",
-    "medianMs": 3.5704000000000633,
-    "rps": 280
+    "medianMs": 4.021499999999833,
+    "rps": 249
   }
 ]

package/benchmarks/ejs.js

@@ -2,11 +2,13 @@ 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 MEDIUM = `<% big_items.forEach(i => { %>\n<% if (i % 2 === 0) { %>Even: <%= i %>\n<% } else { %>Odd: <%= i %>\n<% } }) %>`;
+const LARGE = `<% big_items.forEach(i => { %>\n<% small_items.forEach(j => { %>\n<%= i %>:<%= j %> <%= 'x'.repeat(10) %>\n<% }) }) %>`;
 
 const data = {
-  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
+  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon'],
+  big_items: Array.from({ length: 500 }, (_, i) => i),
+  small_items: Array.from({ length: 5 }, (_, j) => j)
 };
 
 function bench(name, tpl, data, iterations = 5000) {

package/benchmarks/handlebars-results.json

@@ -1,17 +1,17 @@
 [
   {
     "name": "handlebars:small",
-    "medianMs": 0.0024999999999977263,
-    "rps": 400000
+    "medianMs": 0.0024000000000086175,
+    "rps": 416667
   },
   {
     "name": "handlebars:medium",
-    "medianMs": 0.019200000000012096,
-    "rps": 52083
+    "medianMs": 0.16540000000009059,
+    "rps": 6046
   },
   {
     "name": "handlebars:large",
-    "medianMs": 1.5285000000001219,
-    "rps": 654
+    "medianMs": 1.5188000000000557,
+    "rps": 658
   }
 ]

package/benchmarks/handlebars.js

@@ -2,14 +2,9 @@ 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}}`;
+const MEDIUM = `{{#each big_items}}{{#if (isEven this)}}Even: {{this}}\n{{else}}Odd: {{this}}\n{{/if}}{{/each}}`;
+const LARGE = `{{#each big_items}}{{#each ../small_items}}{{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;
 });
@@ -18,7 +13,9 @@ Handlebars.registerHelper('repeat', function(str, n) {
 });
 
 const data = {
-  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
+  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon'],
+  big_items: Array.from({ length: 500 }, (_, i) => i),
+  small_items: Array.from({ length: 5 }, (_, j) => j)
 };
 
 function bench(name, tpl, data, iterations = 5000) {

package/benchmarks/miki-results.json

@@ -1,17 +1,17 @@
 [
   {
     "name": "miki:small",
-    "medianMs": 0.00899999999998613,
-    "rps": 111111
+    "medianMs": 0.0009000000000014552,
+    "rps": 1111111
   },
   {
     "name": "miki:medium",
-    "medianMs": 0.0021999999999593456,
-    "rps": 454545
+    "medianMs": 0.009999999999990905,
+    "rps": 100000
   },
   {
     "name": "miki:large",
-    "medianMs": 0.002200000000016189,
-    "rps": 454545
+    "medianMs": 0.30579999999997654,
+    "rps": 3270
   }
 ]

package/benchmarks/miki.js

@@ -2,11 +2,14 @@ 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 MEDIUM = `{% for i in big_items %}{% if i % 2 == 0 %}Even: {{ i }}\n{% else %}Odd: {{ i }}\n{% endif %}{% endfor %}`;
+const LARGE = `{% for i in big_items %}{% for j in small_items %}{{ i }}:{{ j }} {{ x10|repeat:5 }}\n{% endfor %}{% endfor %}`;
 
 const data = {
-  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
+  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon'],
+  big_items: Array.from({ length: 500 }, (_, i) => i),
+  small_items: Array.from({ length: 5 }, (_, j) => j),
+  x10: 'x'
 };
 
 function bench(name, tpl, data, iterations = 5000) {

package/benchmarks/pug-results.json

@@ -1,17 +1,17 @@
 [
   {
     "name": "pug:small",
-    "medianMs": 0.0006999999999948159,
-    "rps": 1428571
+    "medianMs": 0.0006000000000199179,
+    "rps": 1666667
   },
   {
     "name": "pug:medium",
-    "medianMs": 0.001599999999996271,
-    "rps": 625000
+    "medianMs": 0.019200000000012096,
+    "rps": 52083
   },
   {
     "name": "pug:large",
-    "medianMs": 0.33320000000003347,
-    "rps": 3001
+    "medianMs": 0.3955999999999449,
+    "rps": 2528
   }
 ]

package/benchmarks/pug.js

@@ -2,11 +2,13 @@ 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 MEDIUM = `each i in big_items\n  if i % 2 === 0\n    | Even: #{i}\n  else\n    | Odd: #{i}\n`;
+const LARGE = `each i in big_items\n  each j in small_items\n    | #{i}:#{j} #{'x'.repeat(10)}\n`;
 
 const data = {
-  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
+  items: ['alpha', 'beta', 'gamma', 'delta', 'epsilon'],
+  big_items: Array.from({ length: 500 }, (_, i) => i),
+  small_items: Array.from({ length: 5 }, (_, j) => j)
 };
 
 function bench(name, tpl, data, iterations = 5000) {

package/docs/api/async-render.md

@@ -1,85 +1,170 @@
-# asyncRender()
+# 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)
+
+
+- [render()](./render.md)
+
+- [compile()](./compile.md)
+

package/docs/api/cache.md

@@ -1,87 +1,174 @@
-# Cache API
+# 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](../)
+
+
+- [Advanced Usage: Caching](../guide/advanced-usage.md#caching)
+
+- [API Reference](../index.md)
+