miki-template 2.3.1 → 2.3.2

package/context/component.md

@@ -1,109 +0,0 @@
-# Component Hierarchy — Django-Style Template Engine (Node.js/Express)
-
-## 📖 Purpose
-This document defines the **modules, responsibilities, and relationships** for the template engine. It ensures clarity in implementation and maintainability.
-
----
-
-## 🧩 Core Components
-
-### 1. **Lexer**
-- **Responsibility**: Tokenize template strings into `TEXT`, `VAR`, `BLOCK`.
-- **Inputs**: Raw template string.
-- **Outputs**: Token stream.
-- **Dependencies**: None.
-
-### 2. **Parser**
-- **Responsibility**: Convert tokens into an AST (Abstract Syntax Tree).
-- **Inputs**: Token stream.
-- **Outputs**: AST nodes (`Text`, `Var`, `If`, `For`, `Block`, etc.).
-- **Dependencies**: Lexer.
-
-### 3. **Renderer**
-- **Responsibility**: Walk AST, evaluate expressions, apply filters, render output.
-- **Inputs**: AST + context.
-- **Outputs**: Final HTML string.
-- **Dependencies**: Parser, Filter Registry, Tag Handlers.
-
----
-
-## 🔧 Supporting Modules
-
-### 4. **Filter Registry**
-- **Responsibility**: Store and apply filters.
-- **Built-in Filters**: `upper`, `lower`, `date`, `truncatechars`, `safe`, `escape`, etc.
-- **Extensibility**: Developers can register custom filters.
-- **Dependencies**: Renderer.
-
-### 5. **Tag Handlers**
-- **Responsibility**: Implement logic for each tag.
-- **Control Flow**: `if`, `elif`, `else`, `for`, `empty`, `with`, `cycle`.
-- **Inheritance**: `extends`, `block`, `include`.
-- **Utilities**: `url`, `static`, `regroup`, `spaceless`, `comment`, `verbatim`.
-- **Security**: `autoescape`, `csrf_token`, `csp_nonce_attr`.
-- **Dependencies**: Renderer, Context.
-
-### 6. **Inheritance System**
-- **Responsibility**: Manage parent/child templates, block overrides.
-- **Mechanism**: Block registry + AST merging.
-- **Dependencies**: Parser, Renderer.
-
-### 7. **Context Manager**
-- **Responsibility**: Provide variables to templates.
-- **Features**: Dotted lookups (`user.name`), querystring injection, context processors.
-- **Dependencies**: Renderer.
-
----
-
-## 🔐 Security Components
-
-### 8. **Escaping Engine**
-- **Responsibility**: Autoescape HTML by default.
-- **Features**: `safe` filter disables escaping, `escape` forces escaping.
-- **Dependencies**: Renderer, Filter Registry.
-
----
-
-## 📦 Integration Layer
-
-### 9. **Express Adapter**
-- **Responsibility**: Integrate engine with Express.
-- **API**: `app.engine('dtpl', renderFile)`.
-- **Dependencies**: Renderer, Context Manager.
-
----
-
-## 🛠️ Extensibility Components
-
-### 10. **Custom Tag API**
-- **Responsibility**: Allow developers to register new tags.
-- **Mechanism**: Tag registry with handler functions.
-
-### 11. **Custom Filter API**
-- **Responsibility**: Allow developers to register new filters.
-- **Mechanism**: Filter registry extension.
-
-### 12. **Context Processors**
-- **Responsibility**: Inject global variables (e.g., `user`, `request`).
-- **Mechanism**: Middleware-like hooks.
-
----
-
-## 📋 Relationships Diagram (Textual)
-
-- **Lexer → Parser → Renderer**
-- **Renderer → Filter Registry + Tag Handlers + Context Manager**
-- **Tag Handlers → Inheritance System + Escaping Engine**
-- **Express Adapter → Renderer**
-- **Custom APIs → Filter Registry + Tag Handlers**
-- **Context Processors → Context Manager**
-
----
-
-## 🎯 Deliverables
-- Modular codebase with clear separation of concerns.
-- Each tag/filter implemented as independent handler.
-- Extensible APIs for developers.
-- Secure rendering pipeline with autoescape.
-- Seamless Express integration.
-

package/context/prd.md

@@ -1,131 +0,0 @@
-# Django-Style Template Engine for Node.js/Express
-
-## 📖 Overview
-A custom template engine for Express that replicates **Django’s template language** in Node.js. It supports variables, filters, tags, inheritance, partials, escaping, and extensibility — providing full parity with Django templates while integrating seamlessly into Express.
-
----
-
-## 🎯 Goals
-- Full Django template feature parity in Node.js.
-- Simple Express integration via `app.engine`.
-- Extensible API for custom tags, filters, and context processors.
-- Secure by default (autoescape enabled).
-- Production-ready performance (AST caching, error handling).
-
----
-
-## 🧩 Core Architecture
-1. **Lexer** → Tokenizes template into `TEXT`, `VAR`, `BLOCK`.
-2. **Parser** → Builds AST nodes for tags/filters.
-3. **Renderer** → Walks AST, evaluates expressions, applies filters.
-4. **Filter Registry** → Built-in + custom filters.
-5. **Tag Handlers** → Functions for each tag (`if`, `for`, `block`, etc.).
-6. **Inheritance System** → Block registry + parent merging.
-7. **Express Integration** → `app.engine('dtpl', renderFile)`.
-
----
-
-## 🏷️ Built-in Template Tags
-
-| Tag | Purpose | Node.js Implementation |
-|-----|---------|------------------------|
-| **autoescape** | Toggle HTML escaping. | Maintain `context.autoescape` flag. |
-| **block** | Define overridable content. | Store block AST in registry. |
-| **extends** | Template inheritance. | Load parent file, merge blocks. |
-| **include** | Insert partial template. | Load file, render with context. |
-| **if/elif/else** | Conditional rendering. | Evaluate JS expression safely. |
-| **for/empty** | Loop over iterable. | Inject `forloop` vars (`counter`, `first`, `last`). |
-| **with** | Assign temporary variable. | Extend context object. |
-| **cycle** | Alternate values. | Maintain cycle state per loop. |
-| **comment** | Ignore enclosed content. | Strip from AST. |
-| **verbatim** | Raw output. | Treat enclosed text as literal. |
-| **csrf_token** | CSRF protection. | Insert token from context. |
-| **csp_nonce_attr** | CSP nonce attribute. | Render `nonce="value"`. |
-| **url** | Generate route URL. | Integrate with Express router. |
-| **static** | Reference static files. | Map to Express static dir. |
-| **regroup** | Group list by attribute. | Use JS `reduce`. |
-| **spaceless** | Strip whitespace. | Regex replace in output. |
-
----
-
-## 🔧 Built-in Filters
-
-| Filter | Purpose | Node.js Implementation |
-|--------|---------|------------------------|
-| **Text** | `upper`, `lower`, `title`, `capfirst`, `truncatewords`, `truncatechars`, `wordcount`, `linebreaks`, `linebreaksbr`, `striptags`, `slugify` | JS string methods, regex, libraries. |
-| **HTML** | `safe`, `escape` | Use `he` for escaping; safe flag. |
-| **List** | `length`, `join`, `slice`, `dictsort`, `dictsortreversed` | JS array methods. |
-| **Date/Time** | `date`, `time`, `timesince`, `timeuntil` | Wrap JS `Date` with `Intl.DateTimeFormat`. |
-| **Numeric** | `add`, `divisibleby`, `floatformat` | Arithmetic ops; `toFixed`. |
-| **Default** | `default`, `default_if_none` | Fallback values. |
-| **Misc** | `pluralize`, `yesno`, `filesizeformat` | String transformations; filesize units. |
-
----
-
-## 🔐 Escaping & Security
-- Autoescape enabled by default.
-- `safe` filter disables escaping.
-- `escape` filter forces escaping.
-- Use `he` library for HTML entity encoding.
-
----
-
-## 🛠️ Extensibility
-- **Custom filters**: `filters[name] = fn`.
-- **Custom tags**: Register handler functions in tag registry.
-- **Context processors**: Middleware to inject globals (e.g., `user`, `request`).
-
----
-
-## 📋 Development Roadmap
-
-### Phase 1 — Core Foundations
-- Lexer, parser, renderer.
-- Express integration.
-
-### Phase 2 — Variables & Filters
-- Variables with dotted lookups.
-- Full filter system (text, list, date, numeric, misc).
-- Custom filter API.
-
-### Phase 3 — Control Flow Tags
-- `if/elif/else`, `for/empty`, `with`, `cycle`, `comment`, `verbatim`.
-
-### Phase 4 — Template Inheritance
-- `extends`, `block`, nested blocks.
-- `include` for partials.
-
-### Phase 5 — Utilities & Helpers
-- `static`, `url`, `regroup`, `spaceless`.
-
-### Phase 6 — Security
-- Autoescape, safe strings, escape filter.
-
-### Phase 7 — Extensibility
-- Custom tags/filters.
-- Context processors.
-
-### Phase 8 — Advanced Features
-- Querystring/context passing.
-- Template partials with context overrides.
-- Error handling.
-- Performance optimizations (AST caching).
-
-### Phase 9 — Developer Experience
-- Documentation.
-- Testing suite.
-- Packaging as npm module.
-- Example apps.
-
----
-
-## 🎯 Final Deliverables
-- **Engine core**: Lexer, parser, renderer.
-- **Filter library**: All Django filters.
-- **Tag handlers**: All Django tags.
-- **Inheritance system**: Full block/extends support.
-- **Express integration**: `app.engine('dtpl', ...)`.
-- **Extensibility API**: Custom tags/filters/context processors.
-- **Security**: Autoescape + safe strings.
-- **Docs & tests**: Full coverage.
-

package/context/project-structure.md

@@ -1,33 +0,0 @@
-/project-root
-  /src
-    lexer.js
-    parser.js
-    renderer.js
-    filters.js
-    security.js
-    cache.js
-    context.js
-    tags/
-      control.js
-      inheritance.js
-      util.js
-    index.js
-  /templates
-    base.html
-    home.html
-    header.html
-  /examples
-    app.js
-  /tests
-    lexer.test.js
-    parser.test.js
-    renderer.test.js
-    filters.test.js
-    tags.test.js
-    security.test.js
-  README.md
-  API_REFERENCE.md
-  ROADMAP.md
-  CONTRIBUTING.md
-  CODE_OF_CONDUCT.md
-  package.json

package/dir/base.html

@@ -1,23 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>
-        
-        {% block title %}
-            Document
-        {% endblock title %}
-            
-    </title>
-</head>
-<body>
-    {% include "navbar.html" %}
-    
-    {% block content %}
-        
-    {% endblock content %}
-    {% include "footer.html" %}
-        
-</body>
-</html>

package/dir/cmpnt.html

@@ -1,11 +0,0 @@
-{% partialdef me %}
-<h2>here is some content</h2>
-{% endpartialdef %}
-{% partialdef you %}
-<h2>here is some content for you</h2>
-{% endpartialdef %}
-{% partialdef us inline %}
-{% partial me%}
-{% partial you%}
-<h2>here is some content for us</h2>
-{% endpartialdef %}

package/dir/footer.html

@@ -1,3 +0,0 @@
-<footer>
-    <h3>some footer content with : {{siteName}}</h3>
-</footer>

package/dir/home.html

@@ -1,80 +0,0 @@
-{% extends 'base.html' %}
-
-{% block title %}
-  {{ siteName|default:'Home page Here'|title }} | {{ block.super }}
-{% endblock %}
-
-{% block content %}
-  {% partialdef card  inline %}
-  <div class="card">
-    <h3>{{ title|default:'No title' }}</h3>
-    <p>{{ description|default:'{% lorem 20 %}'|upper }}</p>
-  </div>
-  {% endpartialdef %}
-
-  {% partial card with title='Hello' description='World' %}
-
-  {% with a=5 %}
-    <marquee behavior="" direction="">
-      <span>some new stuff with with tag : {{ a|add:5 }}</span>
-    </marquee>
-  {% endwith %}
-
-  {{ name }}
-  {{ login.name }}
-  {{ login.email }}
-  <h1>Users table goes below</h1>
-  <table border="3">
-    <th>name</th>
-    <th>email</th>
-    <th>action</th>
-
-    {% for user in users %}
-      <tr>
-        <td>{{ user.name|title }}</td>
-        <td>{{ user.email }}</td>
-        <td>
-          <a href="">Delete user</a>
-        </td>
-      </tr>
-    {% endfor %}
-    
-  </table>
-  <h1>Data list</h1>
-  <h2>data list of data</h2>
-  {% for obj in data %}
-    {% partialdef mike inline %}
-
-    <li>{{ obj.name }}</li>
-    <li>{{ forloop.counter }}</li>
-   <li> {{ obj.email }}</li>
-    {% endpartialdef %}
-  {% endfor %}
-
-  <h2>users list of data</h2>
-  <ul style="background-color: aqua;color: blueviolet; list-style-type:upper-roman;">
-
-    {% for obj in users %}
-    {% partial mike %}
-    {% endfor %}
-  </ul>
-
-  <h3>form with crsf</h3>
-
-  <form action="">
-    {% csrf_token %}
-    <input type="text" name="" id="" title="some text"/>
-  </form>
-<h3>included content here</h3>
-  {% include 'cmpnt.html#me' %}
-
-  {{"2324"|filesizeformat}}
-  {{"224"|filesizeformat}}
-  {{ "123456789"|filesizeformat }}
-  {{ "1234567890"|filesizeformat }}
-  {{ "1234567890123"|filesizeformat }}
-  {{ "1234567890123456"|filesizeformat }}
-  {{ "1234567890123456789"|filesizeformat }}
-
-
-{% endblock %}

package/dir/index.html

@@ -1,80 +0,0 @@
-{% extends 'base.html' %}
-
-{% block title %}
-  {{ siteName|default:'Home page Here'|title }} | {{ block.super }}
-{% endblock %}
-
-{% block content %}
-  {% partialdef card  inline %}
-  <div class="card">
-    <h3>{{ title|default:'No title' }}</h3>
-    <p>{{ description|default:'{% lorem 20 %}'|upper }}</p>
-  </div>
-  {% endpartialdef %}
-
-  {% partial card with title='Hello' description='World' %}
-
-  {% with a=5 %}
-    <marquee behavior="" direction="">
-      <span>some new stuff with with tag : {{ a|add:5 }}</span>
-    </marquee>
-  {% endwith %}
-
-  {{ name }}
-  {{ login.name }}
-  {{ login.email }}
-  <h1>Users table goes below</h1>
-  <table border="3">
-    <th>name</th>
-    <th>email</th>
-    <th>action</th>
-
-    {% for user in users %}
-      <tr>
-        <td>{{ user.name|title }}</td>
-        <td>{{ user.email }}</td>
-        <td>
-          <a href="">Delete user</a>
-        </td>
-      </tr>
-    {% endfor %}
-    
-  </table>
-  <h1>Data list</h1>
-  <h2>data list of data</h2>
-  {% for obj in data %}
-    {% partialdef mike inline %}
-
-    <li>{{ obj.name }}</li>
-    <li>{{ forloop.counter }}</li>
-   <li> {{ obj.email }}</li>
-    {% endpartialdef %}
-  {% endfor %}
-
-  <h2>users list of data</h2>
-  <ul style="background-color: aqua;color: blueviolet; list-style-type:upper-roman;">
-
-    {% for obj in users %}
-    {% partial mike %}
-    {% endfor %}
-  </ul>
-
-  <h3>form with crsf</h3>
-
-  <form action="">
-    {% csrf_token %}
-    <input type="text" name="" id="" title="some text"/>
-  </form>
-<h3>included content here</h3>
-  {% include 'cmpnt.html#me' %}
-
-  {{"2324"|filesizeformat}}
-  {{"224"|filesizeformat}}
-  {{ "123456789"|filesizeformat }}
-  {{ "1234567890"|filesizeformat }}
-  {{ "1234567890123"|filesizeformat }}
-  {{ "1234567890123456"|filesizeformat }}
-  {{ "1234567890123456789"|filesizeformat }}
-
-
-{% endblock %}

package/dir/navbar.html

@@ -1,9 +0,0 @@
-<header>
-    <div class="brand">
-        <img src="/path/to/logo.png" alt="Logo" width="40px">
-    </div>
-    <nav>
-        <a href="/">Home</a>
-
-    </nav>
-</header>

package/docs/api/async-render.md

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