miki-template 2.0.1 → 2.2.2

package/mkdocs.yml

@@ -0,0 +1,217 @@
+site_name: miki-template
+site_url: https://alainmiki.github.io/miki-template/
+site_description: Django-style template engine for Node.js and Express
+site_author: Alain Miki
+
+repo_name: miki-template
+repo_url: https://github.com/alainmiki/miki-template
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  custom_dir: overrides
+  logo: assets/logo.png
+  favicon: assets/logo.png
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: custom
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  font:
+    text: Inter
+    code: JetBrains Mono
+  features:
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.instant.progress
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.path
+    - navigation.top
+    - navigation.footer
+    - navigation.prune
+    - navigation.indexes
+    - toc.integrate
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - announce.dismiss
+  icon:
+    repo: fontawesome/brands/github
+    admonition:
+      note: fontawesome/solid/note-sticky
+      abstract: fontawesome/solid/book-open
+      info: fontawesome/solid/circle-info
+      tip: fontawesome/solid/lightbulb
+      success: fontawesome/solid/check-circle
+      question: fontawesome/solid/question-circle
+      warning: fontawesome/solid/triangle-exclamation
+      failure: fontawesome/solid/circle-xmark
+      danger: fontawesome/solid/skull
+      bug: fontawesome/solid/robot
+      example: fontawesome/solid/flask
+      quote: fontawesome/solid/quote-left
+
+nav:
+  - Home: index.md
+  - Getting Started:
+      - What is miki-template?: guide/what-is-miki-template.md
+      - Why miki-template?: guide/why-miki-template.md
+      - Getting Started: guide/getting-started.md
+      - Installation: guide/installation.md
+      - Quick Start: guide/quick-start.md
+  - Core Features:
+      - Partial Templates: guide/partial-templates.md
+      - Smart Template Discovery: guide/template-discovery.md
+      - Template Inheritance: guide/template-inheritance.md
+      - Filters: guide/filters.md
+      - Tags: guide/tags.md
+      - Security: guide/security.md
+  - Advanced:
+      - Custom Tags: guide/custom-tags.md
+      - Custom Filters: guide/custom-filters.md
+      - Context Processors: guide/context-processors.md
+      - Async Rendering: guide/async-rendering.md
+      - Advanced Usage: guide/advanced-usage.md
+  - API Reference:
+      - API Overview: api/index.md
+      - render(): api/render.md
+      - compile(): api/compile.md
+      - asyncRender(): api/async-render.md
+      - renderPartial(): api/render-partial.md
+      - setupExpress(): api/setup-express.md
+      - Filters: api/filters.md
+      - Tags: api/tags.md
+      - Security: api/security.md
+      - i18n: api/i18n.md
+      - Libraries: api/libraries.md
+      - Cache: api/cache.md
+      - Finder: api/finder.md
+      - Helpers: api/helpers.md
+      - Context Processors: api/context-processors.md
+  - Integrations:
+      - Integrations Overview: integrations/index.md
+      - Express: integrations/express.md
+      - Koa: integrations/koa.md
+      - Fastify: integrations/fastify.md
+      - Hono: integrations/hono.md
+      - Elysia: integrations/elysia.md
+      - NestJS: integrations/nestjs.md
+      - TSDX / TSed: integrations/tsed.md
+  - Performance: performance.md
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - meta
+  - toc:
+      permalink: true
+      title: On this page
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+  - material.extensions.emoji:
+      options:
+        custom_icons:
+          - overrides/.icons
+  - material.extensions.tabbed
+  - material.extensions.anchor
+  - material.extensions.details
+  - material.extensions.superfences
+  - material.extensions.magic-link:
+      repo_url_shorthand: true
+      user: alainmiki
+      repo: miki-template
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/alainmiki/miki-template
+      name: miki-template on GitHub
+    - icon: fontawesome/brands/npm
+      link: https://www.npmjs.com/package/miki-template
+      name: miki-template on npm
+    - icon: fontawesome/brands/youtube
+      link: https://youtube.com/@codewithmiki6849
+      name: Code with Miki on YouTube
+    - icon: fontawesome/brands/facebook
+      link: https://www.facebook.com/profile.php?id=100063798107667
+      name: Alain Miki on Facebook
+    - icon: fontawesome/brands/instagram
+      link: https://www.instagram.com/alain_miki
+      name: Alain Miki on Instagram
+    - icon: fontawesome/brands/facebook
+      link: https://www.facebook.com/codewithmiki
+      name: Code with Miki on Facebook
+  version:
+    provider: mike
+  homepage: https://alainmiki.github.io/miki-template/
+  generator: false
+  annotate:
+    json: [.s2s]
+
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+  - tags
+  - meta
+  - offline:
+      enabled: !ENV [READTHEDOCS, false]
+  - social:
+      cards: true
+      cards_layout_options:
+        color: "#1a1a2e"
+        font_family: Roboto
+  - optimize:
+      enabled: !ENV [READTHEDOCS, false]
+      concurrency: 4
+      css:
+        transpile: true
+      js:
+        bundle: true
+
+extra_css:
+  - stylesheets/extra.css
+
+extra_javascript:
+  - javascripts/extra.js

package/overrides/main.html

@@ -0,0 +1,26 @@
+{% extends "base.html" %}
+
+{% block announce %}
+<div class="md-announce" role="banner">
+  <div class="md-announce__inner">
+    <span>🚀 <strong>miki-template v2.0</strong> is now available with improved performance and new features!</span>
+    <a href="https://github.com/alainmiki/miki-template/releases" target="_blank" rel="noopener">View Release Notes</a>
+    <button class="md-announce__button" onclick="this.closest('.md-announce').remove()" aria-label="Dismiss announcement">
+      <span class="md-icon">&#10005;</span>
+    </button>
+  </div>
+</div>
+{% endblock %}
+
+{% block extrahead %}
+<meta name="theme-color" content="#1a1a2e">
+<meta name="description" content="Django-style template magic for Node.js — blazing fast partials, smart template discovery, and zero friction for HTMX.">
+<meta property="og:title" content="miki-template - Django-style templating for Node.js">
+<meta property="og:description" content="Blazing fast partials, smart template discovery, and zero friction for HTMX. Bring Django's beloved template language to Node.js and Express.">
+<meta property="og:type" content="website">
+<meta property="og:url" content="https://alainmiki.github.io/miki-template/">
+<meta property="og:image" content="https://alainmiki.github.io/miki-template/social-card.png">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="miki-template - Django-style templating for Node.js">
+<meta name="twitter:description" content="Blazing fast partials, smart template discovery, and zero friction for HTMX.">
+{% endblock %}

package/overrides/partials/footer.html

@@ -0,0 +1,9 @@
+{% extends "partials/footer.html" %}
+
+{% block copyright %}
+Copyright &copy; 2024 - 2026 <a href="https://github.com/alainmiki">Alain Miki</a>
+{% endblock %}
+
+{% block generator %}
+Made with <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">Material for MkDocs</a>
+{% endblock %}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miki-template",
-  "version": "2.0.1",
+  "version": "2.2.2",
   "description": "Django-Style template engine for Node.js and Express",
   "main": "src/index.js",
   "exports": {
@@ -22,7 +22,7 @@
     "fastify",
     "nestjs"
   ],
-  "author": "",
+  "author": "Alain Miki aka Coder Miki",
   "license": "MIT",
   "dependencies": {
     "date-fns": "^3.6.0",
@@ -41,6 +41,8 @@
     "test": "node -e \"const fs=require('fs');const path=require('path');function walk(d){const out=[];for(const e of fs.readdirSync(d,{withFileTypes:true})){const p=path.join(d,e.name);if(e.isDirectory())out.push(...walk(p));else if(/\\\\.test\\\\.(cjs|mjs|js)$/.test(e.name))out.push(p);}return out;}const files=walk('tests');require('child_process').execSync('node --test '+files.join(' '),{stdio:'inherit'})\"",
     "lint": "eslint . -f unix",
     "bench": "node benchmarks/run.js",
+    "docs:build": "mkdocs build",
+    "docs:serve": "mkdocs serve",
     "release:patch": "npm version patch --no-git-tag-version -m \"chore(release): v%s\" && git push origin main",
     "release:minor": "npm version minor --no-git-tag-version -m \"chore(release): v%s\" && git push origin main",
     "release:major": "npm version major --no-git-tag-version -m \"chore(release): v%s\" && git push origin main"

package/requirements-docs.txt

@@ -0,0 +1 @@
+mkdocs-material[imaging]>=9.5

package/docs/README.md

@@ -1,18 +0,0 @@
-# Documentation Index
-
-Welcome to the **miki-template** documentation hub. Below is a quick navigation guide to all docs.
-
-| Document | Description |
-|---|---|
-| [overview.md](overview.md) | High‑level project overview and repository layout |
-| [installation.md](installation.md) | How to install the package and prerequisites |
-| [usage.md](usage.md) | Basic API usage, rendering, compilation, and block rendering |
-| [tags.md](tags.md) | Reference for every built‑in tag (`if`, `for`, `partialdef`, etc.) |
-| [filters.md](filters.md) | Comprehensive list of built‑in filters with examples |
-| [partialdef.md](partialdef.md) | Detailed guide for the `partialdef` feature (including inline, nesting, API) |
-| [security.md](security.md) | Security considerations (auto‑escaping, CSP, CSRF) |
-| [api.md](api.md) | Low‑level API surface – `compile`, `renderPartial`, `registerTag`, etc. |
-| [contributing.md](contributing.md) | Guidelines for contributing, pull‑request flow, and code style |
-| [roadmap.md](roadmap.md) | Future milestones and release schedule |
-
-All files are located under `c:/Users/Coder Miki/Desktop/miki-template/docs/`.

package/docs/advanced_usage.md

@@ -1,71 +0,0 @@
-# Advanced Usage
-
-This document showcases real‑world examples of the **miki‑template** engine.
-
-## 1. Partial Definition & Inclusion
-```django
-{% partialdef "header" %}
-<header>
-  <h1>{{ site.title }}</h1>
-</header>
-{% endpartialdef %}
-
-{% include "header" %}
-```
-*Result:* Renders a reusable header component.
-
----
-## 2. Custom Tag Helper – Markdown
-```js
-const { registerHelper } = require('./src/tags/helpers');
-const markdownIt = require('markdown-it')();
-registerHelper('markdown', (content) => markdownIt.render(content));
-```
-```django
-{% markdown %}
-# Hello World
-* Item 1
-* Item 2
-{% endmarkdown %}
-```
-*Result:* Converts markdown to HTML on‑the‑fly.
-
----
-## 3. Async Rendering with a Sleep Helper
-```js
-registerHelper('sleep', async (content) => {
-  await new Promise(r => setTimeout(r, 50));
-  return `Awake after ${content}`;
-});
-```
-```django
-{% sleep %}50ms{% endsleep %}
-```
-```js
-const { asyncRender } = require('./src');
-asyncRender(template, {} ).then(console.log);
-```
-*Result:* `Awake after 50ms`
-
----
-## 4. Extended Date Formatting
-```django
-{{ now|date_format:"yyyy-MM-dd HH:mm:ss" }}
-```
-*Result:* `2026-08-29 13:48:07`
-### Additional Date Filter Examples
-
-```django
-{{ now|strftime:"PPpp" }}          {# Full date-fns pattern #}
-{{ now|date:"Y-m-d H:i:s" }}        {# Django style with seconds #}
-{{ now|time:"H:i:s" }}              {# Time only #}
-```
-
-*Result:* Example outputs will appear when rendered.
-
----
-## 5. Performance Benchmark (see `benchmarks/run.js`)
-The benchmark renders three template sizes (small, medium, large) synchronously and asynchronously, reporting average render time and cache hit ratio.
-
----
-> **Tip:** All examples work with the default Express integration via `app.engine('dtpl', require('miki-template').__express);`

package/docs/api.md

@@ -1,122 +0,0 @@
-# API Reference
-
-This document lists the public API exported by **miki-template** for developers to integrate the engine into their projects.
-
-| Function / Export | Signature | Description | Example |
-|---|---|---|---|
-| `compile(templateStr, options?)` | `compile(string, object?) → { render, asyncRender, renderBlock, renderPartial }` | Compiles a template string into a renderable object. Optional `options` can include `views` directories, custom tags/filters, etc. | `const tpl = compile('Hello {{ name }}');` |
-| `render(templateStr, context?, options?)` | `render(string, object?, object?) → string` | One‑off rendering of a template string with the provided context. | `render('Hello {{ name }}', { name: 'World' });` |
-| `asyncRender(templateStr, context?, options?)` | `asyncRender(string, object?, object?) → Promise<string>` | Asynchronous rendering (useful with async helpers). | `await asyncRender(tpl, ctx);` |
-| `__express(filePath, options, callback)` | `__express(string, object, function)` | Express view engine adapter – reads the file at `filePath` and renders it. Honors `view#partial` suffixes for HTMX-style partial responses. | `app.engine('html', miki.__express);` |
-| `__expressAsync(filePath, options)` | `__expressAsync(string, object) → Promise<string>` | Async Express 5+ view engine adapter. Returns a Promise that resolves to rendered HTML. Also honors `view#partial` suffixes. | `app.engine('html', miki.__expressAsync);` |
-| `express(options?)` | `express(object?) → function` | Factory that returns a view-engine function suitable for `app.engine(...)`. Honors `view#partial` selectors. | `app.engine('html', miki.express());` |
-| `setupExpress(app, opts?)` | `setupExpress(expressApp, object?) → void` | **One-line Express integration.** Wires `app.engine(...)`, `app.set('views')`, and patches `res.render` so `res.render('view#partial', ...)` returns just that partial. Options: `{ extension?, views?, async? }`. | `miki.setupExpress(app, { extension: 'html', views: './views' });` |
-| `expressPartialRenderer()` | `expressPartialRenderer() → function` | Express middleware that adds `res.renderPartial(view, locals)`. Useful as a drop-in HTMX helper without the full `setupExpress` shim. | `app.use(miki.expressPartialRenderer());` |
-| `findTemplateInViews(name, viewsDirs)` | `findTemplateInViews(string, string[]|string) → string|null` | Search for a template by name across one or more `views` roots. Performs direct resolution first (supports explicit paths and extensions), then a recursive search for bare filenames in subdirectories. Returns the absolute file path or `null` if not found. | `miki.findTemplateInViews('detail', ['./views', './templates'])` |
-| `setAppTemplateDirNames(names)` | `setAppTemplateDirNames(string[]|string) → void` | Configure which directory names are treated as app-style template folders when scanning (default: `['templates']`). Useful when projects use a different convention. | `miki.setAppTemplateDirNames(['templates','app_templates'])` |
-| `getAppTemplateDirNames()` | `getAppTemplateDirNames() → string[]` | Retrieve the current configured app-template directory names. | `const names = miki.getAppTemplateDirNames()` |
-| `renderPartialFromFile(filePath, partialName, context?, options?)` | `renderPartialFromFile(string, string, object?, object?) → string` | Load a file from disk and render only the named `{% partialdef %}`. | `miki.renderPartialFromFile('views/home.html', 'card', { user });` |
-| `renderPartialFromSource(source, partialName, context?, options?)` | `renderPartialFromSource(string, string, object?, object?) → string` | Render a single named partial directly from a template string. Walks the AST (and `extends` chain) to discover partials nested inside blocks. | `miki.renderPartialFromSource(src, 'card', ctx, { views });` |
-| `stripExpressContext(options)` | `stripExpressContext(object) → object` | Remove Express framework keys (`_locals`, `settings`, `cache`) from an options object. | `const ctx = stripExpressContext(res.locals);` |
-| `clearCache()` | `clearCache() → void` | Clear the in-memory compiled template cache. | `clearCache();` |
-| `registerTag(name, parserFn)` | `registerTag(string, function)` | Register a custom tag parser. Must be called before compiling templates. | `registerTag('mytag', parserFn);` |
-| `registerFilter(name, fn)` | `registerFilter(string, function)` | Register a custom filter. | `registerFilter('reverse', str => str.split('').reverse().join(''));` |
-| `getFilter(name)` | `getFilter(string) → function` | Retrieve a registered filter function by name. | `const upper = getFilter('upper');` |
-| `registerHelper(name, fn)` | `registerHelper(string, function)` | Register a helper function available inside templates. | `registerHelper('upper', s => s.toUpperCase());` |
-| `registerContextProcessor(fn)` | `registerContextProcessor(function)` | Add a context processor that mutates the rendering context before each render. | `registerContextProcessor(ctx => ({ ...ctx, csrf_token: '123' }));` |
-| `registerTranslation(lang, messages)` | `registerTranslation(string, object) → void` | Register translation messages for a language. | `registerTranslation('fr', { 'Hello': 'Bonjour' });` |
-| `setLanguage(lang)` | `setLanguage(string) → void` | Set the active language for all subsequent renders. | `setLanguage('fr');` |
-| `getLanguage()` | `getLanguage() → string` | Get the currently active language. | `const lang = getLanguage();` |
-| `setFallbackLanguage(lang)` | `setFallbackLanguage(string) → void` | Set the fallback language for missing translations. | `setFallbackLanguage('en');` |
-| `getAvailableLanguages()` | `getAvailableLanguages() → string[]` | List all registered language codes. | `const langs = getAvailableLanguages();` |
-| `registerLibrary(name, def)` | `registerLibrary(string, object) → void` | Register a plugin library of tags, filters, and helpers. | `registerLibrary('humanize', { filters: { intcomma } });` |
-| `registerLibraryFromPath(name, path)` | `registerLibraryFromPath(string, string) → object` | Load a library from a JS file on disk. | `registerLibraryFromPath('myLib', './libs/my-lib.js');` |
-| `activateLibrary(name)` | `activateLibrary(string) → void` | Activate a registered library (makes its tags/filters available). | `activateLibrary('humanize');` |
-| `SafeString` | `class SafeString` | Wrapper class for values that should bypass auto‑escaping. Returned by `markSafe`. |
-| `markSafe(value)` | `markSafe(any) → SafeString` | Marks a value as safe, preventing HTML escaping. |
-| `isSafe(value)` | `isSafe(any) → boolean` | Checks if a value is a `SafeString`. |
-| `escapeHtml(str)` | `escapeHtml(string) → string` | Escapes HTML special characters. Used internally for auto‑escaping. |
-
-All of the above are exported from `src/index.js` and can be imported via:
-
-### CommonJS
-```js
-const {
-  compile,
-  render,
-  asyncRender,
-  __express,
-  __expressAsync,
-  express,
-  setupExpress,
-  expressPartialRenderer,
-  renderPartialFromFile,
-  renderPartialFromSource,
-  stripExpressContext,
-  clearCache,
-  registerTag,
-  registerFilter,
-  getFilter,
-  registerHelper,
-  registerContextProcessor,
-  clearContextProcessors,
-  registerTranslation,
-  setLanguage,
-  getLanguage,
-  setFallbackLanguage,
-  getAvailableLanguages,
-  registerLibrary,
-  registerLibraryFromPath,
-  activateLibrary,
-  SafeString,
-  markSafe,
-  isSafe,
-  escapeHtml
-} = require('miki-template');
-```
-
-### ES Modules (ESM)
-```js
-import {
-  compile,
-  render,
-  asyncRender,
-  __express,
-  __expressAsync,
-  express,
-  setupExpress,
-  expressPartialRenderer,
-  renderPartialFromFile,
-  renderPartialFromSource,
-  stripExpressContext,
-  clearCache,
-  registerTag,
-  registerFilter,
-  getFilter,
-  registerHelper,
-  registerContextProcessor,
-  clearContextProcessors,
-  registerTranslation,
-  setLanguage,
-  getLanguage,
-  setFallbackLanguage,
-  getAvailableLanguages,
-  registerLibrary,
-  registerLibraryFromPath,
-  activateLibrary,
-  SafeString,
-  markSafe,
-  isSafe,
-  escapeHtml
-} from 'miki-template';
-
-// Or import all as default
-import miki from 'miki-template';
-const { render: mikiRender, setupExpress } = miki;
-```
-
-For detailed usage, refer to the corresponding sections in the documentation:
-- **Usage** – `docs/usage.md`
-- **Tags** – `docs/tags.md`
-- **Filters** – `docs/filters.md`
-- **Security** – `docs/security.md`