miki-template 2.0.1 → 2.2.2

package/.github/workflows/ci.yml

@@ -7,60 +7,36 @@ on:
     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
-# automatically when a `chore(release):` commit lands on main.
-
-name: CI
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-
 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

@@ -75,14 +75,13 @@ miki-template is built for real-world apps. Its compiled-AST engine is especiall
 
 ## 📚 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)
 
 ---
 
@@ -252,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`.
@@ -291,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

@@ -6,12 +6,12 @@
   },
   {
     "name": "ejs:medium",
-    "medianMs": 0.03449999999997999,
-    "rps": 28986
+    "medianMs": 0.033799999999985175,
+    "rps": 29586
   },
   {
     "name": "ejs:large",
-    "medianMs": 3.445900000000165,
-    "rps": 290
+    "medianMs": 3.5704000000000633,
+    "rps": 280
   }
 ]

package/benchmarks/handlebars-results.json

@@ -1,17 +1,17 @@
 [
   {
     "name": "handlebars:small",
-    "medianMs": 0.0024000000000086175,
-    "rps": 416667
+    "medianMs": 0.0024999999999977263,
+    "rps": 400000
   },
   {
     "name": "handlebars:medium",
-    "medianMs": 0.020599999999973306,
-    "rps": 48544
+    "medianMs": 0.019200000000012096,
+    "rps": 52083
   },
   {
     "name": "handlebars:large",
-    "medianMs": 1.512900000000002,
-    "rps": 661
+    "medianMs": 1.5285000000001219,
+    "rps": 654
   }
 ]

package/benchmarks/miki-results.json

@@ -1,8 +1,8 @@
 [
   {
     "name": "miki:small",
-    "medianMs": 0.008700000000004593,
-    "rps": 114943
+    "medianMs": 0.00899999999998613,
+    "rps": 111111
   },
   {
     "name": "miki:medium",
@@ -11,7 +11,7 @@
   },
   {
     "name": "miki:large",
-    "medianMs": 0.0020999999999844476,
-    "rps": 476190
+    "medianMs": 0.002200000000016189,
+    "rps": 454545
   }
 ]

package/benchmarks/pug-results.json

@@ -1,8 +1,8 @@
 [
   {
     "name": "pug:small",
-    "medianMs": 0.0006000000000199179,
-    "rps": 1666667
+    "medianMs": 0.0006999999999948159,
+    "rps": 1428571
   },
   {
     "name": "pug:medium",
@@ -11,7 +11,7 @@
   },
   {
     "name": "pug:large",
-    "medianMs": 0.3201000000000249,
-    "rps": 3124
+    "medianMs": 0.33320000000003347,
+    "rps": 3001
   }
 ]

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](../)