miki-template 1.2.0 → 1.3.3

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

@@ -0,0 +1,55 @@
+# 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/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## [1.3.3] - 2026-09-04
+### Fixed
+- **`date` and `time` filters** — multi-character tokens (`yyyy`, `MM`, `dd`, `HH`, `mm`, `ii`, `ss`) now work correctly. Previously `"yyyy-MM-dd"` rendered as `"24242424-JunJun-1515"` because each character was treated as an independent token. The fix uses longest-first token matching and adds backward-compatible single-character aliases (`m`/`d`/`H`/`i`/`s` for Django-style unpadded values).
+
+### Performance
+- **Inheritance parent-source cache** — `{% extends %}` no longer re-reads the parent template from disk on every render. A 64-entry LRU cache in `src/cache.js` (`getParentSource` / `hasParentSource`) memoises the parent source. Inheritance rendering improved from ~481 rps to **~2,056 rps** in the stress benchmark (4.3× faster, no functional change).
+
+### Tooling
+- **`benchmarks/stress.mjs`** — comprehensive 37-check stress benchmark covering correctness, compile speed, render speed, cache behavior, scale, endurance, partial rendering, async, and 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 so `no-undef` no longer flags standard Web APIs.
+- Removed dead code flagged by the linter: 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
+- `npx eslint src/**/*.js` — 0 errors, 0 warnings
+- `npm test` — 397/397 passing
+- `node benchmarks/stress.mjs` — 37/37 passing
+
+## [1.3.1] - 2026-09-03
+### Highlights
+- **One-line Express integration**: `miki.setupExpress(app, { extension: 'html', views: dir })` — wires the view engine, `views` directory, and a `res.render` shim that lets you do `res.render('home#card', ...)` for HTMX-style partial responses. No more boilerplate, no extra middleware.
+- **Render-any-partial-from-string**: `renderPartialFromSource(source, partialName, ctx, opts)` loads a template string and returns only the named `{% partialdef %}` body. This is what powers `res.render('view#partial')` and HTMX responses.
+- **True built-in libraries**: `humanize`, `cache`, and `lorem` are now auto-activated on module load — `{% lorem %}` works without `{% load lorem %}`. Existing libraries now also expose helpers, not just tags.
+- **Comprehensive integration test suite**: 382 tests covering every tag, filter, and feature under both CommonJS and ESM, all running against a **real Express HTTP server** on ephemeral ports.
+
+### Added
+- `miki.setupExpress(app, { extension, views, async })` — one-line Express bootstrap. Sets `view engine`, registers the engine, and patches `res.render` to handle `view#partial` selectors. Replaces the need to call `app.engine()`, `app.set('views')`, and `app.set('view engine')` manually.
+- `miki.express()` — factory that returns a view-engine function suitable for `app.engine(...)`. Honors `view#partial` suffixes.
+- `miki.expressPartialRenderer()` — middleware that adds `res.renderPartial(view, locals)`. Useful as a drop-in HTMX helper.
+- `renderPartialFromSource(source, partialName, context, options)` — render a single named partial from a template string. Resolves `extends` chains so partials defined inside `{% block %}` tags are discoverable. Walks the AST and registers every `PartialDefNode` it finds, even when nested inside `{% for %}` or `{% if %}` blocks that won't render during partial lookup.
+- `renderPartialFromFile(filePath, partialName, context, options)` — file-based convenience wrapper.
+- `Context.get(name)` now returns `undefined` for missing keys (was `''`). This lets `default_if_none` distinguish "not provided" from an explicit empty string, matching Django.
+- `escapeHtml(value, force = false)` — added a `force` flag so the `|escape` filter re-escapes even a `SafeString` (Django parity).
+- `Context` constructor now supports `partialDefs` and `options` for cloning the partial registry.
+- New exports: `setupExpress`, `express`, `expressPartialRenderer`, `renderPartialFromFile`, `renderPartialFromSource`, `clearContextProcessors`.
+- ESM surface (`src/esm.mjs`) now exposes all the new helpers, with the same `default` + named import shape.
+- Lorem library now ships a real `{% lorem N method %}` tag, a `lorem` filter, plus helpers. Built-in and auto-activated.
+- `library.activate(name)` now also activates helpers and `registerTag` functions, not just filters.
+
+### Changed
+- Context processors now follow Django semantics: **existing context values win** over processor defaults. If you render with `{ user: req.user }` and a processor returns `{ user: 'Guest' }`, the explicit value is preserved.
+- `__express` and `__expressAsync` now detect a `#partial` suffix in the view name and delegate to `renderPartialFromSource` automatically. This makes `app.engine('html', miki.__express)` already HTMX-ready — `setupExpress` just adds convenience.
+- `cache.getCompiled` ignores function-valued and `undefined` options when building cache keys, so passing the same `urlHelper` function to multiple `compile()` calls no longer causes cache misses.
+- Lexer rewritten with brace-depth counting for more reliable `{{ }}` and `{% %}` tokenization in templates with nested braces, escaped braces, and unusual whitespace.
+- Filters now receive the rendering `context` as a final argument, so custom filters can read other context variables (e.g. for locale-aware formatting).
+- `for` and `with` tags fully reworked for the user-reported edge cases:
+  - `{% with x=1, y=2 as pair %}` — pair list followed by an alias.
+  - `{% with value=expr %}` — single pair (no comma).
+  - `{% with x=1, y=2 %}` — pure pair list (no alias).
+  - Quoted values containing commas (`{% with a="x,y" %}`) parse correctly.
+  - Pair values may be context variables.
+- `partial` now accepts `with` kwargs and overrides context for the partial scope.
+- `include` now supports `file#partial` syntax — the same partial-selector pattern works with `{% include %}` as with `res.render`.
+- `url` tag respects `urlHelper` more cleanly: kwargs (a trailing object literal) are passed as the last argument instead of being conflated with positional args.
+- `static` tag normalizes leading slashes; prefix can be customized.
+- `csrf_token` and `csp_nonce_attr` outputs are properly escaped to prevent attribute injection.
+
+### Fixed
+- `with a=x b=y` (multi-pair) was previously treated as a single value/expression. Now correctly binds each pair.
+- `cycle` with `as` form emits nothing but stores the value, matching Django.
+- `block.super` works inside partials that override blocks.
+- `extends` resolves `views` from `options.settings.views` (Express's normal path), `options.views`, or the default.
+- Path traversal protection now applies to `extends` *and* `include`, including `include "file#partial"` form.
+- `if` conditions handle dotted lookup, function auto-call, and missing variables without throwing.
+- `default` vs `default_if_none`: `default` falls back on empty string, `null`, and `undefined`; `default_if_none` only on `null`/`undefined`. Both now match Django exactly.
+- `removetags` filter now accepts multiple tag names.
+- `safe` / `escape` filters correctly re-escape `SafeString` only when forced.
+- `Context.get('a.b.c')` no longer stringifies `undefined` to `''`, fixing `{% if x %}` checks against missing variables.
+- Cache key collisions when passing the same template string with different function-valued options (e.g. `urlHelper`).
+
+### Compatibility
+- No breaking changes. All existing public APIs continue to work. New APIs are opt-in.
+
 ## [1.2.0] - 2026-09-01
 ### Added
 - Full **ESM** support via `src/esm.mjs` wrapper and conditional `package.json` exports.

package/README.md

@@ -1,4 +1,5 @@
 # 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)
 A robust, production-ready template engine that brings **Django's template language** features and syntax to Node.js and Express, fully compliant with modern JavaScript (ES6+), CommonJS, and **ESM** (`import`) support.
 
@@ -6,9 +7,11 @@ A robust, production-ready template engine that brings **Django's template langu
 
 ## 🚀 Features
 
+- **One-line Express integration**: `miki.setupExpress(app, { extension: 'html', views: dir })` — wires the engine, views directory, and a `res.render` shim that makes `res.render('home#card', ...)` Just Work for HTMX-style partial responses. **No boilerplate, no extra middleware.**
+- **Partial responses out of the box**: `{% partialdef %}` blocks can be rendered by name with `res.render('view#partial', ...)`, `miki.expressPartialRenderer()` middleware (`res.renderPartial(...)`), or `renderPartialFromSource(...)`.
 - **Full Syntax Parity**: Supports variables, dotted lookups, filters (`|`), and block tags (`{% %}`).
 - **Template Inheritance**: Multi-level inheritance with `extends`, block overrides, and `{{ block.super }}` support.
-- **Express Integration**: Simple, zero-config integration via `app.engine()`.
+- **Built-in libraries**: `humanize`, `cache`, and `lorem` ship pre-activated. `{% lorem 5 p %}` works without `{% load lorem %}`.
 - **ESM & CommonJS**: Works seamlessly with both `import` and `require` syntax.
 - **Security by Default**: Auto-escaping enabled by default with a `SafeString` wrapper.
 - **CSRF & CSP Support**: Native tags for `{% csrf_token %}` and `{% csp_nonce_attr %}` to keep apps secure out-of-the-box.
@@ -107,47 +110,61 @@ console.log(result); // Output: "Hello World!"
 
 ### Express Integration
 
-**CommonJS:**
+**The recommended, one-line setup** — wires the view engine, views directory, and partial responses in a single call:
+
 ```javascript
 const express = require('express');
-const { __express: renderDtpl } = require('miki-template');
+const miki = require('miki-template');
 
 const app = express();
+miki.setupExpress(app, { extension: 'html', views: './views' });
 
-// Register both .html and .miki extensions
-app.engine('html', renderDtpl);
-app.engine('miki', renderDtpl);
-app.set('view engine', 'miki');
-app.set('views', './views');
+// Full page
+app.get('/', (req, res) => res.render('home', { user: req.user }));
 
-app.get('/', (req, res) => {
-  res.render('home', {
-    title: 'Django Templates in Node!',
-    items: ['Apple', 'Banana', 'Orange']
-  });
-});
+// HTMX / partial response — just append `#partialName` to the view name
+app.get('/partials/:name', (req, res) =>
+  res.render(`home#${req.params.name}`, { user: req.user })
+);
 
-app.listen(3000, () => console.log('App listening on port 3000'));
+app.listen(3000);
 ```
 
-**ESM:**
+> `setupExpress` calls `app.engine()`, `app.set('views')`, and `app.set('view engine')` for you, and patches `res.render` so `view#partial` is dispatched to the partial renderer (not the file system). It works equally well for `.miki` files — just pass `extension: 'miki'`.
+
+**The classic, fully manual setup still works** if you prefer it:
+
 ```javascript
-import express from 'express';
-import { __express as renderDtpl } from 'miki-template';
+const express = require('express');
+const { __express } = require('miki-template');
 
 const app = express();
-app.engine('html', renderDtpl);
+app.engine('html', __express);
 app.set('view engine', 'html');
 app.set('views', './views');
+```
 
-app.get('/', (req, res) => {
-  res.render('home', {
-    title: 'Django Templates with ESM!',
-    items: ['Apple', 'Banana', 'Orange']
-  });
-});
+**ESM:**
+
+```javascript
+import express from 'express';
+import miki from 'miki-template';
+
+const app = express();
+miki.setupExpress(app, { extension: 'html', views: './views' });
+```
+
+**Async Express 5+:**
+```javascript
+miki.setupExpress(app, { extension: 'html', views: './views', async: true });
+```
+
+**Or, if you only want partial responses** without changing your engine registration, add the middleware:
+
+```javascript
+app.use(miki.expressPartialRenderer());
 
-app.listen(3000, () => console.log('App listening on port 3000'));
+app.get('/card', (req, res) => res.renderPartial('home#card', { user: req.user }));
 ```
 
 ---