miki-template 2.3.0 → 2.3.2

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miki-template",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Django-Style template engine for Node.js and Express",
   "main": "src/index.js",
   "exports": {
@@ -10,6 +10,50 @@
       "default": "./src/index.js"
     }
   },
+  "files": [
+    "src/index.js",
+    "src/esm.mjs",
+    "src/lexer.js",
+    "src/parser.js",
+    "src/context.js",
+    "src/context_processors.js",
+    "src/filters.js",
+    "src/security.js",
+    "src/cache.js",
+    "src/utils.js",
+    "src/codegen.js",
+    "src/i18n.js",
+    "src/libraries.js",
+    "src/tags/helpers.js",
+    "src/tags/registry.js",
+    "src/tags/control.js",
+    "src/tags/inheritance.js",
+    "src/tags/util.js",
+    "src/tags/i18n.js",
+    "src/tags/extra.js"
+  ],
+  "files": [
+    "src/index.js",
+    "src/esm.mjs",
+    "src/lexer.js",
+    "src/parser.js",
+    "src/context.js",
+    "src/context_processors.js",
+    "src/filters.js",
+    "src/security.js",
+    "src/cache.js",
+    "src/utils.js",
+    "src/codegen.js",
+    "src/i18n.js",
+    "src/libraries.js",
+    "src/tags/helpers.js",
+    "src/tags/registry.js",
+    "src/tags/control.js",
+    "src/tags/inheritance.js",
+    "src/tags/util.js",
+    "src/tags/i18n.js",
+    "src/tags/extra.js"
+  ],
   "keywords": [
     "django",
     "template",

package/.eslintrc.json

@@ -1,16 +0,0 @@
-{
-  "env": {
-    "node": true,
-    "es2024": true
-  },
-  "extends": "eslint:recommended",
-  "parserOptions": {
-    "ecmaVersion": "latest",
-    "sourceType": "module"
-  },
-  "rules": {
-    "no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
-    "no-console": "off",
-    "semi": ["error", "always"]
-  }
-}

package/.github/release-notes/v1.3.1.md

@@ -1,55 +0,0 @@
-# miki-template v1.3.1
-
-## Highlights
-
-- **One-line Express integration**: `miki.setupExpress(app, { extension: 'html', views: dir })` wires the view engine, the views directory, and a `res.render` shim that makes HTMX-style partial responses Just Work.
-
-  ```js
-  const express = require('express');
-  const miki = require('miki-template');
-
-  const app = express();
-  miki.setupExpress(app, { extension: 'html', views: './views' });
-
-  // Full page
-  app.get('/', (req, res) => res.render('home', { user: req.user }));
-
-  // Partial — just append `#partialName` to the view name
-  app.get('/partials/:name', (req, res) =>
-    res.render(`home#${req.params.name}`, { user: req.user })
-  );
-  ```
-
-- **`miki.expressPartialRenderer()` middleware** for drop-in `res.renderPartial(view, locals)` without changing your existing `app.engine()` setup.
-- **`miki.express()`** factory for `app.engine('html', miki.express())` — honors `view#partial` selectors.
-- **`renderPartialFromSource(source, partialName, ctx, opts)`** and **`renderPartialFromFile(...)`** — render a single named `{% partialdef %}` from a string or file. Walks the AST (and the `extends` chain) to find partials nested inside blocks.
-- **`{% include "file.html#partial" with ... %}`** — partial-selector syntax works with `include`, not just `res.render`.
-- **Built-in libraries** (`humanize`, `cache`, `lorem`) are now auto-activated on module load. `{% lorem 5 p %}` works without `{% load lorem %}`.
-
-## Tag fixes
-
-- `{% with x=1, y=2 as pair %}` (multi-pair + alias) parses correctly.
-- `{% with a=x b=y %}` (multi-pair, no alias) now binds each pair instead of being treated as one expression.
-- `{% cycle 'a' 'b' as name %}` now emits nothing but stores the value (Django semantics).
-- `{{ block.super }}` works inside partials that override blocks.
-- `extends` resolves `views` from `options.settings.views` (Express path), `options.views`, or default.
-- Path-traversal protection applies to `extends` *and* `include`, including `include "file#partial"`.
-- `default` vs `default_if_none`: `default` falls back on `''`, `null`, and `undefined`; `default_if_none` only on `null`/`undefined` (Django parity).
-- `removetags` accepts multiple tag names.
-- `Context.get('a.b.c')` returns `undefined` for missing keys (was `''`), so `{% if x %}` and `default_if_none` work correctly.
-
-## Test coverage
-
-**382/382 tests pass.** Added a 190-test integration suite (`tests/integration/`) covering every tag, filter, and feature under both CommonJS and ESM, exercised against a real Express HTTP server on ephemeral ports. The test runner recursively picks up `.test.{cjs,mjs,js}` files.
-
-## Docs
-
-- `README.md` — promoted `miki.setupExpress` to the first listed feature; the Express section leads with the one-liner.
-- `docs/usage.md` — full Express section rewritten with the new setup, options table, and middleware variant.
-- `docs/api.md` — added rows for the new APIs; updated CJS/ESM import snippets.
-- `docs/partialdef.md` — documented `include "file#partial"`, `renderPartialFromSource/File`, and the HTMX-over-HTTP flow.
-- `CHANGELOG.md` — full entry for 1.3.1.
-
-## Compatibility
-
-No breaking changes. All existing public APIs continue to work; new APIs are opt-in.

package/.github/release-notes/v1.3.3.md

@@ -1,77 +0,0 @@
-# miki-template v1.3.3
-
-## Highlights
-
-- **Date/time filter fixed** — `{{ d|date:"yyyy-MM-dd" }}` now returns `"2024-06-15"` instead of `"24242424-JunJun-1515"`. Multi-character tokens (`yyyy`, `MM`, `dd`, `HH`, `mm`, `ii`, `ss`) are matched longest-first; backward-compatible single-character aliases (`m`/`d`/`H`/`i`/`s`) still work for Django-style unpadded values.
-- **Inheritance 4× faster** — `{% extends %}` no longer re-reads the parent file from disk on every render. A 64-entry LRU cache in `src/cache.js` memoises the parent source. Inheritance rendering improved from ~481 rps to **~2,056 rps** in the strict benchmark.
-
-## Installation
-
-```bash
-npm install miki-template@1.3.3
-```
-
-## Quick start
-
-```js
-const miki = require('miki-template');
-const express = require('express');
-
-const app = express();
-miki.setupExpress(app, { extension: 'html', views: './views' });
-
-// Full page
-app.get('/', (req, res) => res.render('home', { user: req.user }));
-
-// HTMX partial — just append #partialName
-app.get('/partials/:name', (req, res) =>
-  res.render(`home#${req.params.name}`, { user: req.user })
-);
-
-app.listen(3000);
-```
-
-## What's changed
-
-### Fixed
-- `date` and `time` filters — multi-character tokens render correctly.
-
-### Performance
-- Inheritance parent-source LRU cache in `src/cache.js` (`getParentSource` / `hasParentSource`). `clearCache()` also clears it.
-
-### Tooling
-- New `benchmarks/stress.mjs` — 37-check strict benchmark (correctness, compile speed, render speed, cache, scale, endurance, partial rendering, async, concurrency). Run with `node benchmarks/stress.mjs`. Exits with code 1 on any failure.
-- `eslint.config.mjs` — added `URL`, `URLSearchParams`, `TextEncoder`, `TextDecoder`, `fetch`, `crypto`, `performance` to the Node 18+ globals list.
-- Removed dead code: unused `elifBranches` variable in `parseIfChanged`, unused `extractPluralMappings` function in `i18n.js`.
-- Renamed unused tag-parser `parser` parameters to `_parser` in `lorem` library and `parseLoad`.
-
-## Verification
-
-| Check | Result |
-|---|---|
-| `npx eslint src/**/*.js` | 0 errors, 0 warnings |
-| `npm test` | 397/397 passing |
-| `node benchmarks/stress.mjs` | 37/37 passing |
-
-## Performance (from the stress benchmark)
-
-| Template | Speed |
-|---|---|
-| Small (76 B) | **175,439 rps** (0.006 ms) |
-| Medium (595 B) | 13,947 rps (0.072 ms) |
-| Large (1.6 KB, 6 sections × 12 items) | 2,277 rps (0.439 ms) |
-| Inheritance child | 2,056 rps (0.486 ms) |
-| Partials (50 entries) | 2,235 rps (0.447 ms) |
-| Scale: 50,000 items | 107 ms median |
-| Endurance: 100,000 renders | 7.5s total, RSS +0.9 MB |
-| Async: 200 concurrent LARGE | 237 ms total |
-
-## Compatibility
-
-No breaking changes. All existing public APIs continue to work; new APIs are opt-in.
-
-## Links
-
-- **Repository**: https://github.com/alainmiki/miki-template
-- **Tag**: https://github.com/alainmiki/miki-template/releases/tag/v1.3.3
-- **Previous**: [v1.3.1](https://github.com/alainmiki/miki-template/releases/tag/v1.3.1)

package/.github/release-notes/v1.3.7.md

@@ -1,20 +0,0 @@
-## v1.3.7 — Template discovery improvements
-
-- Add recursive/app-style template discovery so projects can place
-  templates in nested `templates/` folders (Django-style) and have
-  them discovered automatically.
-- `setupExpress` now expands `app.get('views')` to include nested
-  directories that contain template files so `res.render('name')`
-  works for templates located in project-level or package-level
-  `templates/` directories.
-- Expose `findTemplateInViews(name, roots)` helper and
-  `setAppTemplateDirNames()/getAppTemplateDirNames()` to configure
-  app-style template folder names.
-- Improve `res.render` fallback to use the recursive finder before
-  throwing Express's "Failed to lookup view" error.
-- Update docs and API reference with usage examples and migration
-  notes.
-
-CI: runs lint + tests (all passing locally). If you'd like a more
-comprehensive changelog, I can expand this with links to issues and
-code snippets.

package/.github/workflows/ci.yml

@@ -1,42 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-  workflow_dispatch:
-
-jobs:
-  lint:
-    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: ubuntu-latest
-    needs: lint
-    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 }}
-          cache: 'npm'
-      - 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

package/.github/workflows/docs.yml

@@ -1,107 +0,0 @@
-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
-        env:
-          NO_MKDOCS_2_WARNING: 1
-
-      - name: 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 }}/"
-
-  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/release.yml

@@ -1,107 +0,0 @@
-# Release workflow
-#
-# Fully automatic release pipeline. Triggered when a commit to main matches
-# the `chore(release): v*` pattern produced by `npm run release:patch|minor|major`.
-#
-# Flow:
-#   1. Detect the new version in package.json.
-#   2. Lint + test + stress benchmark (must pass before continuing).
-#   3. Create an annotated git tag v<version> and push it.
-#   4. Create a GitHub Release with notes from .github/release-notes/v<version>.md
-#      (or a generic message if the file is missing).
-#   5. Publish the package to npm using the NPM_TOKEN secret.
-#
-# Local usage:
-#   npm run release:patch    # 1.3.3 → 1.3.4
-#   npm run release:minor    # 1.3.3 → 1.4.0
-#   npm run release:major    # 1.3.3 → 2.0.0
-# That bumps package.json, creates a commit, pushes to main, and the rest
-# happens here.
-
-name: Release
-
-on:
-  push:
-    branches: [main]
-
-permissions:
-  contents: write
-  packages: write
-
-jobs:
-  release:
-    # Only run for the explicit "chore(release):" commits. Any other
-    # push to main is ignored so contributors can edit package.json
-    # without accidentally publishing.
-    if: startsWith(github.event.head_commit.message, 'chore(release):')
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Lint
-        run: npx eslint src/**/*.js
-
-      - name: Test
-        run: npm test
-
-      - name: Stress benchmark
-        run: node benchmarks/stress.mjs
-
-      - name: Read package version
-        id: ver
-        run: echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
-
-      - name: Check tag does not already exist
-        run: |
-          if git rev-parse "v${{ steps.ver.outputs.version }}" >/dev/null 2>&1; then
-            echo "::error::Tag v${{ steps.ver.outputs.version }} already exists."
-            exit 1
-          fi
-
-      - name: Create and push git tag
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git tag -a "v${{ steps.ver.outputs.version }}" -m "v${{ steps.ver.outputs.version }}"
-          git push origin "v${{ steps.ver.outputs.version }}"
-
-      - name: Build release body
-        id: notes
-        env:
-          NOTES_FILE: .github/release-notes/v${{ steps.ver.outputs.version }}.md
-          VERSION: ${{ steps.ver.outputs.version }}
-        run: |
-          {
-            echo "body<<EOF_RELEASE"
-            if [ -f "$NOTES_FILE" ]; then
-              cat "$NOTES_FILE"
-            else
-              echo "## v${VERSION}"
-              echo ""
-              echo "See [CHANGELOG.md](../../blob/main/CHANGELOG.md) for details."
-            fi
-            echo "EOF_RELEASE"
-          } >> "$GITHUB_OUTPUT"
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: v${{ steps.ver.outputs.version }}
-          name: v${{ steps.ver.outputs.version }}
-          body: ${{ steps.notes.outputs.body }}
-
-      - name: Publish to npm
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/AGENT.md

@@ -1,71 +0,0 @@
-# AGENT.md - Agent Instructions, Guardrails, & Architecture Rules
-
-This repository implements a Django-Style Template Engine for Node.js/Express. To ensure high code quality, consistent architecture, and full feature parity with Django without guesswork, all AI agents and developers must strictly follow these instructions and guardrails.
-
----
-
-## 🎯 Core Objectives
-1. **Full Feature Parity**: Match Django's template engine rules for rendering variables, dotted lookups, built-in tags, filters, and template inheritance.
-2. **Deterministic & Secure**: Escape output by default using a safe-string mechanism.
-3. **No Spaghetti Code**: Maintain a strict separation of Lexer, Parser, Renderer, Context, and Tag/Filter registries.
-
----
-
-## ⚠️ Strict Guardrails & Anti-Hallucination Rules
-
-> [!IMPORTANT]
-> **No Guesswork / Assumptions**
-> - If a tag or filter's behavior is not clearly defined in [prd.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/prd.md) or Django documentation, **DO NOT guess**. 
-> - If you notice ambiguities (e.g., how to handle circular extends or nested cycles), raise a question to the user immediately or throw a descriptive compilation error.
-
-> [!WARNING]
-> **No Regex-Based Global Search & Replace**
-> - You **must not** implement tags or filters using global regex replacements on the final string. All templates must go through:
->   `Lexer (String -> Tokens) -> Parser (Tokens -> AST) -> Renderer (AST + Context -> HTML)`.
-> - Direct regex replacement on HTML bypasses nesting, escaping, and blocks, which introduces severe bugs.
-
-> [!CAUTION]
-> **Security Guardrails**
-> - All variable output must be HTML-escaped by default.
-> - A variable is only safe from escaping if it is marked as a `SafeString` (e.g., using the `safe` filter or internally flagged).
-> - Dynamic expression evaluation (such as in `if` tags) **must not** use direct JS `eval()`. Use a safe AST evaluator or sandboxed parser to prevent remote code execution.
-
----
-
-## 🧩 Architectural Guidelines
-
-### 1. Lexing (`src/lexer.js`)
-*   Tokens must be generated for three primary types:
-    - `TEXT`: Plain HTML/text.
-    - `VAR`: Variables wrapped in `{{ ... }}`.
-    - `BLOCK`: Structural tags wrapped in `{% ... %}`.
-*   The Lexer must correctly handle verbatim blocks `{% verbatim %}` and comments `{% comment %}` by suppressing token output or passing raw text tokens.
-
-### 2. Parsing (`src/parser.js`)
-*   The Parser takes a stream of tokens and constructs an AST of nodes.
-*   Every node must implement a `.render(context)` method (async or sync).
-*   For tags that have closing tags (e.g., `{% if %}`...`{% endif %}`), the parser must parse nested tokens recursively until the matching close tag is encountered.
-
-### 3. Context & Scope Isolation (`src/context.js`)
-*   Context must support a stack-like structure: `.push()` to create a new scope, and `.pop()` to revert.
-*   **Variable Lookups**: Support dotted lookups:
-    - Example: `{{ user.profile.name }}` should search `user` in context, then resolve property `profile`, then property `name`.
-    - If a resolved value is a function, call it (without arguments, just like Django).
-    - If a lookup fails, return an empty string `""` by default, unless configured otherwise.
-
-### 4. Template Inheritance (`src/tags/inheritance.js`)
-*   Inheritance works by having a child template load a parent template via `{% extends "parent.html" %}`.
-*   The child overrides blocks defined as `{% block block_name %}`.
-*   During render, the parent's AST is evaluated, but block nodes are replaced by the child's corresponding block nodes.
-*   Support block nesting and the `{{ block.super }}` variable to render parent block content.
-
----
-
-## 🛠️ Step-by-Step Task Execution Protocol
-
-When executing tasks:
-1. **Analyze Requirements**: Check [prd.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/prd.md) and [component.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/component.md).
-2. **Check Existing Tests**: Run current test suite using `npm test` or `node --test` to ensure a green state.
-3. **Write Tests First**: For any new filter, tag, or parser logic, write a corresponding unit test in `tests/` showing the expected template string and its expected output.
-4. **Implement Modular Code**: Put tag handlers in `src/tags/`, filters in `src/filters.js`, and maintain registry isolation.
-5. **Verify**: Ensure the test suite passes, check for escaping vulnerabilities, and check that no scope leaks occur.