npm - miki-template - Versions diffs - 2.3.1 → 2.3.2 - Mend

miki-template 2.3.1 → 2.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (159) hide show

package/package.json +45 -1
package/.eslintrc.json +0 -16
package/.github/release-notes/v1.3.1.md +0 -55
package/.github/release-notes/v1.3.3.md +0 -77
package/.github/release-notes/v1.3.7.md +0 -20
package/.github/workflows/ci.yml +0 -42
package/.github/workflows/docs.yml +0 -107
package/.github/workflows/release.yml +0 -107
package/AGENT.md +0 -71
package/API_REFERENCE.md +0 -341
package/CHANGELOG.md +0 -173
package/CODE_OF_CONDUCT.md +0 -14
package/CONTRIBUTING.md +0 -27
package/ROADMAP.md +0 -40
package/assets/banner.png +0 -0
package/assets/logo.png +0 -0
package/benchmarks/ejs-results.json +0 -17
package/benchmarks/ejs.js +0 -38
package/benchmarks/handlebars-results.json +0 -17
package/benchmarks/handlebars.js +0 -45
package/benchmarks/miki-results.json +0 -17
package/benchmarks/miki.js +0 -39
package/benchmarks/pug-results.json +0 -17
package/benchmarks/pug.js +0 -38
package/benchmarks/report.json +0 -17
package/benchmarks/run.js +0 -81
package/benchmarks/stress.mjs +0 -647
package/benchmarks/templates/large.dtpl +0 -7
package/benchmarks/templates/medium.dtpl +0 -3
package/benchmarks/templates/small.dtpl +0 -7
package/context/component.md +0 -109
package/context/prd.md +0 -131
package/context/project-structure.md +0 -33
package/dir/base.html +0 -23
package/dir/cmpnt.html +0 -11
package/dir/footer.html +0 -3
package/dir/home.html +0 -80
package/dir/index.html +0 -80
package/dir/navbar.html +0 -9
package/docs/api/async-render.md +0 -170
package/docs/api/cache.md +0 -174
package/docs/api/compile.md +0 -256
package/docs/api/context-processors.md +0 -154
package/docs/api/filters.md +0 -437
package/docs/api/finder.md +0 -188
package/docs/api/helpers.md +0 -106
package/docs/api/i18n.md +0 -314
package/docs/api/index.md +0 -108
package/docs/api/libraries.md +0 -414
package/docs/api/render-partial.md +0 -162
package/docs/api/render.md +0 -184
package/docs/api/security.md +0 -290
package/docs/api/setup-express.md +0 -152
package/docs/api/tags.md +0 -268
package/docs/assets/banner.png +0 -0
package/docs/assets/logo.png +0 -0
package/docs/filter.md +0 -0
package/docs/guide/advanced-usage.md +0 -794
package/docs/guide/async-rendering.md +0 -616
package/docs/guide/context-processors.md +0 -514
package/docs/guide/custom-filters.md +0 -622
package/docs/guide/custom-tags.md +0 -542
package/docs/guide/filters.md +0 -1314
package/docs/guide/getting-started.md +0 -204
package/docs/guide/installation.md +0 -190
package/docs/guide/partial-templates.md +0 -734
package/docs/guide/quick-start.md +0 -444
package/docs/guide/security.md +0 -690
package/docs/guide/tags.md +0 -1566
package/docs/guide/template-discovery.md +0 -340
package/docs/guide/template-inheritance.md +0 -546
package/docs/guide/what-is-miki-template.md +0 -28
package/docs/guide/why-miki-template.md +0 -75
package/docs/index.md +0 -86
package/docs/integrations/elysia.md +0 -80
package/docs/integrations/express.md +0 -219
package/docs/integrations/fastify.md +0 -79
package/docs/integrations/hono.md +0 -80
package/docs/integrations/index.md +0 -68
package/docs/integrations/koa.md +0 -90
package/docs/integrations/nestjs.md +0 -80
package/docs/integrations/tsed.md +0 -83
package/docs/performance.md +0 -74
package/eslint.config.mjs +0 -42
package/ex.mjs +0 -36
package/live-test/integrations/elysia-example.js +0 -16
package/live-test/integrations/express-example.js +0 -24
package/live-test/integrations/fastify-example.js +0 -20
package/live-test/integrations/hono-example.js +0 -16
package/live-test/integrations/koa-example.js +0 -30
package/live-test/integrations/nestjs-example.js +0 -25
package/live-test/integrations/smoke-test.js +0 -166
package/live-test/integrations/tsed-example.js +0 -23
package/live-test/package-lock.json +0 -1150
package/live-test/package.json +0 -13
package/live-test/packages/product/templates/product/detail.html +0 -7
package/live-test/server.js +0 -38
package/live-test/templates/app_templates/detail.html +0 -6
package/live-test/views/base.html +0 -8
package/live-test/views/child.html +0 -7
package/live-test/views/home.html +0 -17
package/live-test/views/index.html +0 -1
package/miki-template-extension/.github/workflows/ci.yml +0 -116
package/miki-template-extension/.vscodeignore +0 -7
package/miki-template-extension/CHANGELOG.md +0 -99
package/miki-template-extension/LICENSE +0 -21
package/miki-template-extension/README.md +0 -273
package/miki-template-extension/extension.js +0 -1013
package/miki-template-extension/icon.png +0 -0
package/miki-template-extension/icon.svg +0 -10
package/miki-template-extension/miki-template-1.7.1.vsix +0 -0
package/miki-template-extension/package.json +0 -280
package/miki-template-extension/snippets/miki-template.json +0 -717
package/miki-template-extension/syntaxes/language-configuration.json +0 -114
package/miki-template-extension/syntaxes/miki-template.tmLanguage.json +0 -355
package/miki-template-extension/tests/grammar-tests.json +0 -162
package/miki-template-extension/tests/run-grammar-tests.js +0 -82
package/mkdocs.yml +0 -195
package/overrides/main.html +0 -26
package/requirements-docs.txt +0 -2
package/sample-app/package-lock.json +0 -901
package/sample-app/package.json +0 -9
package/sample-app/server.js +0 -14
package/sample-app/views/index.html +0 -1
package/scripts/build-vsix.js +0 -129
package/scripts/build-vsix.ps1 +0 -15
package/snippets/miki-template.json +0 -177
package/src/asyncRender.js +0 -21
package/src/types.d.ts +0 -107
package/syntaxes/language-configuration.json +0 -26
package/syntaxes/miki-template.tmLanguage.json +0 -146
package/tests/asyncRender.test.js +0 -17
package/tests/base.html +0 -6
package/tests/child.html +0 -3
package/tests/context_processors.test.js +0 -13
package/tests/esm.test.mjs +0 -61
package/tests/filters.test.js +0 -263
package/tests/finder-appdirs.test.js +0 -19
package/tests/finder.test.js +0 -17
package/tests/fixtures/views/nested/index.html +0 -1
package/tests/fixtures/views/partial.html +0 -1
package/tests/fixtures/views/sub/deepfile.html +0 -1
package/tests/fixtures/views-appdirs/product/site/detail.html +0 -1
package/tests/include_security.test.js +0 -9
package/tests/integration/README.md +0 -32
package/tests/integration/features.test.cjs +0 -1681
package/tests/integration/features.test.mjs +0 -1697
package/tests/integration/finder.esm.test.mjs +0 -13
package/tests/integration/partial-render.test.cjs +0 -13
package/tests/integration/templates/base.miki +0 -6
package/tests/integration/templates/child.miki +0 -6
package/tests/integration/templates/index.html +0 -17
package/tests/lexer.test.js +0 -45
package/tests/parser.test.js +0 -57
package/tests/partial.html +0 -1
package/tests/partialdef.test.js +0 -79
package/tests/production_checks.js +0 -57
package/tests/security.test.js +0 -28
package/tests/tags.test.js +0 -233

package/docs/guide/template-inheritance.md DELETED Viewed

@@ -1,546 +0,0 @@
-# Template Inheritance
-miki-template supports Django-style template inheritance via `{% extends %}` and `{% block %}`. This lets you build layout hierarchies where child templates override parent blocks.
-## Table of Contents
-- [Basic Inheritance](#basic-inheritance)
-- [block.super](#blocksuper)
-- [Multi-Level Inheritance](#multi-level-inheritance)
-- [Rendering a Single Block](#rendering-a-single-block)
-- [block Default Behavior](#block-default-behavior)
-- [Path Traversal Protection](#path-traversal-protection)
-- [Smart Template Discovery for Inheritance](#smart-template-discovery-for-inheritance)
----
-## Basic Inheritance
-### base.html
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>{% block title %}Default Title{% endblock %}</title>
-</head>
-<body>
-  <header>{% block header %}Default Header{% endblock %}</header>
-  <main>{% block content %}Default Content{% endblock %}</main>
-  <footer>{% block footer %}Default Footer{% endblock %}</footer>
-</body>
-</html>
-```
-### child.html
-```html
-{% extends "base.html" %}
-{% block title %}My Page{% endblock %}
-{% block content %}
-  <h1>Hello, {{ user.name }}!</h1>
-  {% for item in items %}
-    <p>{{ item }}</p>
-  {% endfor %}
-{% endblock %}
-```
-**Key behaviors:**
-- The child template's text outside `{% block %}` tags is **ignored** — only the blocks are used to override the parent.
-- Any blocks not overridden in the child use the parent's default content.
-- The parent is located using the `views` option (or Express's `views` directory).
-## block.super
-Inside a block, `{{ block.super }}` renders the parent template's version of that block. This is useful for augmentation rather than replacement.
-=== "Example"
-    ```html
-    {% extends "base.html" %}
-    {% block content %}
-      <h1>My Content</h1>
-      {{ block.super }}
-    {% endblock %}
-    ```
-If `base.html`'s content block is `<p>Original</p>`, the output is:
-```html
-<h1>My Content</h1>
-<p>Original</p>
-```
-**Real-world sidebar that adds to the parent:**
-```html
-<!-- base.html -->
-{% block sidebar %}
-  <ul class="nav">
-    <li><a href="/">Home</a></li>
-  </ul>
-{% endblock %}
-<!-- admin.html -->
-{% extends "base.html" %}
-{% block sidebar %}
-  {{ block.super }}
-  <li><a href="/admin">Admin Panel</a></li>
-{% endblock %}
-```
-## Multi-Level Inheritance
-Inheritance chains can be arbitrarily deep:
-```text
-base.html
-  └── child.html
-        └── grandchild.html
-```
-Each level can override blocks from its parent, and `{{ block.super }}` traverses the chain correctly.
-### Three-level example
-**base.html:**
-```html
-<html>
-<body>
-  {% block content %}Base content{% endblock %}
-</body>
-</html>
-```
-**child.html:**
-```html
-{% extends "base.html" %}
-{% block content %}
-  <h2>Child content</h2>
-  {{ block.super }}
-{% endblock %}
-```
-**grandchild.html:**
-```html
-{% extends "child.html" %}
-{% block content %}
-  <h1>Grandchild content</h1>
-  {{ block.super }}
-{% endblock %}
-```
-Rendering `grandchild.html` produces:
-```html
-<html>
-<body>
-  <h1>Grandchild content</h1>
-  <h2>Child content</h2>
-  Base content
-</body>
-</html>
-```
-## Rendering a Single Block
-Compile a template and render only one block — useful for AJAX or HTMX responses where you only need a portion of the page:
-=== "CommonJS"
-    ```javascript
-    const { compile } = require('miki-template');
-    const compiled = compile(childTemplateStr, { views: './templates' });
-    const partialHtml = compiled.renderBlock('content', context);
-    ```
-=== "ES Modules"
-    ```javascript
-    import { compile } from 'miki-template';
-    const compiled = compile(childTemplateStr, { views: './templates' });
-    const partialHtml = compiled.renderBlock('content', context);
-    ```
-### renderBlock behavior
-- If the block is not found, throws `Block 'blockName' not found in template`.
-- If the block has no overrides, renders the default body.
-- If the block has overrides, renders the child-most block first, then traverses up for `{{ block.super }}`.
-**Real-world HTMX use case:**
-```html
-<!-- layout.html -->
-{% block main %}
-  <div id="main-content">
-    <!-- default content -->
-  </div>
-{% endblock %}
-```
-```javascript
-// Return only the main block for an AJAX update
-app.get('/ajax/content', (req, res) => {
-  const compiled = miki.compile(template, { views: './views' });
-  res.send(compiled.renderBlock('main', { user: req.user }));
-});
-```
-## block Default Behavior
-If a child template does not override a block, the parent's default content is rendered:
-```html
-<!-- base.html -->
-<html>
-<body>
-  {% block sidebar %}Default sidebar{% endblock %}
-</body>
-</html>
-```
-```html
-<!-- child.html -->
-{% extends "base.html" %}
-{% block content %}Main content{% endblock %}
-<!-- sidebar block is not overridden, so "Default sidebar" is used -->
-```
-## Dynamic extends
-You can use expressions in `extends` for device-specific or conditional layouts:
-```html
-{% extends device_type|default:"base.html" %}
-```
-```html
-{% extends user.theme|default:"default.html" %}
-```
-## Path Traversal Protection
-`{% extends %}` and `{% include %}` paths are validated to prevent directory traversal attacks:
-```html
-{% extends "../../etc/passwd" %}  {# REJECTED #}
-{% include "../../secrets" %}      {# REJECTED #}
-```
-The engine checks that resolved paths stay within the allowed views directories. An `Error` with message starting `path traversal` is thrown if a path escapes the views root.
-## Smart Template Discovery for Inheritance
-When using `setupExpress()`, the engine automatically searches for parent templates in:
-- The configured `views` directory
-- Nested `templates/` directories inside the views root
-- Subdirectories of the views root
-- App-style `app/templates/...`, `packages/*/templates/...`, etc.
-This means you can organize templates like:
-```text
-project/
-├── views/
-│   ├── base.html
-│   └── home.html
-├── app/
-│   └── templates/
-│       └── admin/
-│           └── dashboard.html
-```
-And `{% extends "base.html" %}` will be found regardless of where the child template lives.
-## Next Steps
-- [Partial Templates](./partial-templates.md)
-- [Tags: extends and block](./tags.md#inheritance-tags)
-- [Template Discovery](./template-discovery.md)

package/docs/guide/what-is-miki-template.md DELETED Viewed

@@ -1,28 +0,0 @@
-# What is miki-template?
-miki-template is a **Django-style template engine for Node.js and Express**. It brings Django's beloved template language — variables, filters, tags, inheritance, and partials — to the Node.js ecosystem with first-class Express integration and modern JavaScript support.
-## Philosophy
-miki-template is designed for developers who love Django's template syntax but want the speed and flexibility of Node.js. It prioritizes:
-- **Developer experience**: Familiar Django syntax, excellent error messages, and sensible defaults.
-- **Performance**: Compiled AST rendering that scales to large, real-world templates.
-- **Modern Node.js**: Full ESM and CommonJS support, async rendering, and compatibility with current Express/Koa/Fastify/Hono/Elysia versions.
-- **Security**: Auto-escaping, safe strings, and Django-style security primitives built in.
-## Key Concepts
-- **Templates** are text files using `{{ variables }}`, `{% tags %}`, and `| filters`.
-- **Partials** let you define reusable components with `{% partialdef %}` and render them by name.
-- **Template inheritance** uses `{% extends %}` and `{% block %}` to build layout hierarchies.
-- **Smart discovery** finds templates across `views/`, `app/templates/`, and nested folders automatically.
-## Who is it for?
-miki-template is a great fit if you:
-- Prefer Django-style templates over JSX or pure string concatenation.
-- Need **partial rendering** for HTMX or AJAX-heavy apps.
-- Want a template engine that **scales** without rewriting templates as your app grows.
-- Value **security** and want XSS protection by default.

package/docs/guide/why-miki-template.md DELETED Viewed

@@ -1,75 +0,0 @@
-# Why miki-template?
-There are plenty of template engines for Node.js. Here is why miki-template stands out.
-## Django Syntax You Already Know
-If you have used Django, you already know miki-template. The syntax is intentionally aligned:
-```html
-{% if user.is_admin %}
-  <p>Welcome, {{ user.name|title }}!</p>
-{% elif user.is_staff %}
-  <p>Staff dashboard</p>
-{% else %}
-  <p>Please log in.</p>
-{% endif %}
-```
-No new DSL to learn. No context switching between backend and frontend templating styles.
-## Built for HTMX and Partial Responses
-Modern web apps increasingly use HTMX, Turbo, or custom AJAX. miki-template makes partial rendering trivial:
-```javascript
-app.get('/card/:id', (req, res) =>
-  res.render(`home#card`, { title: 'Hello', body: '...' })
-);
-```
-No extra middleware. No manual view resolution. Just `view#partial`.
-## Smart Template Discovery
-Forget `Failed to lookup view` errors. miki-template searches your project structure intelligently:
-- `views/`
-- `app/templates/`
-- `packages/*/templates/`
-- Any custom folder name you configure
-This mirrors Django's `APP_DIRS` behavior and means templates can live where they make sense in your codebase.
-## Performance That Scales
-miki-template's compiled AST approach is especially fast on realistic templates — the ones with loops, conditionals, filters, and partials that make up real pages.
-| 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 |
-On large templates, miki-template is **~150× faster** than pug, handlebars, and ejs.
-## Security by Default
-- Auto-escaping enabled by default.
-- SafeString wrapper for explicit bypass.
-- CSRF and CSP tags included.
-- No `eval()` or unsafe code execution.
-## First-Class Express Integration
-One function wires everything:
-```javascript
-miki.setupExpress(app, { extension: 'html', views: './views' });
-```
-That is it. No `app.engine()` boilerplate. No manual `res.render` patching. Partial responses work out of the box.
-## Extensible and Future-Proof
-Need a custom tag? A custom filter? The API is clean and well-documented. miki-template is built to grow with your app, not lock you into a fragile abstraction.

package/docs/index.md DELETED Viewed

@@ -1,86 +0,0 @@
-# miki-template
-Django-style template magic for Node.js — blazing fast partials, smart template discovery, and zero friction for HTMX.
-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.
-miki is secure and production ready with active maintainer and performance improvements.
-[Get Started](guide/quick-start.md) | [API Reference](api/index.md) | [GitHub](https://github.com/alainmiki/miki-template)
-![miki-template banner](assets/banner.png)
-## Why miki-template?
-miki-template brings Django's beloved template language to Node.js and Express. 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.
-- **Partial-powered templating**: `{% partialdef %}` blocks render by name anywhere — `res.render('home#card')`, `renderPartialFromSource(...)`, or `compiled.renderBlock('block')`. Built for HTMX-style partial responses.
-- **Smart template discovery**: Stop hardcoding view paths. The engine searches `templates/`, nested app directories, and custom folder names automatically — just like Django.
-- **One-line Express integration**: `miki.setupExpress(app, { extension: 'html', views: dir })` wires everything up. No boilerplate, no extra middleware.
-- **Full Django syntax parity**: Variables, dotted lookups, filters (`|`), block tags (`{% %}`), template inheritance with `extends` and `block.super`.
-- **Blazing fast**: Compiled AST rendering dominates on realistic pages — ~150× faster than pug, handlebars, and ejs on large templates.
-- **ESM & CommonJS**: Works seamlessly with both `import` and `require` syntax.
-- **Security by default**: Auto-escaping, `SafeString`, CSRF and CSP tags.
-## Quick example
-=== "CommonJS"
-    ```javascript
-    const express = require('express');
-    const miki = require('miki-template');
-    const app = express();
-    miki.setupExpress(app, { extension: 'html', views: './views' });
-    app.get('/', (req, res) => res.render('home', { user: req.user }));
-    app.get('/partials/:name', (req, res) =>
-      res.render(`home#${req.params.name}`, { user: req.user })
-    );
-    app.listen(3000);
-    ```
-=== "ES Modules"
-    ```javascript
-    import express from 'express';
-    import miki from 'miki-template';
-    const app = express();
-    miki.setupExpress(app, { extension: 'html', views: './views' });
-    app.get('/', (req, res) => res.render('home', { user: req.user }));
-    app.get('/partials/:name', (req, res) =>
-      res.render(`home#${req.params.name}`, { user: req.user })
-    );
-    app.listen(3000);
-    ```
-## Installation
-```bash
-npm install miki-template
-```
-See the [Installation guide](guide/installation.md) for pnpm, yarn, and Bun instructions.
-## Documentation
-- [What is miki-template?](guide/what-is-miki-template.md)
-- [Getting Started](guide/getting-started.md)
-- [Quick Start](guide/quick-start.md)
-- [Filters](guide/filters.md)
-- [Tags](guide/tags.md)
-- [Partial Templates](guide/partial-templates.md)
-- [Template Inheritance](guide/template-inheritance.md)
-- [Template Discovery](guide/template-discovery.md)
-- [Security](guide/security.md)
-- [Integrations](integrations/index.md)
-- [API Reference](api/index.md)
-- [Performance](performance.md)
-## License
-MIT