miki-template 2.0.1 → 2.2.2

package/docs/installation.md

@@ -1,106 +0,0 @@
-# Installation
-
-## npm
-```bash
-npm install miki-template
-```
-
-## Prerequisites
-- **Node.js** >= 14 (ES6+ support)
-- **npm** (or **yarn**) for package management
-
-## Optional dependencies
-- **express** – for server‑side rendering integration (recommended).
-- **eslint** – for linting your project (dev dependency).
-
-## Module System Support
-
-`miki-template` supports both **CommonJS** (`require`) and **ESM** (`import`).
-
-### CommonJS (CJS)
-
-```js
-const { render, compile, __express, SafeString, markSafe } = require('miki-template');
-```
-
-### ES Modules (ESM)
-
-```js
-// Named imports
-import { render, compile, __express, SafeString, markSafe } from 'miki-template';
-
-// Default import (all exports)
-import miki from 'miki-template';
-const result = miki.render('Hello {{ name }}', { name: 'World' });
-```
-
-> **Note:** When using ESM in Node.js, either name your files `.mjs` or set `"type": "module"` in your `package.json`.
-
-## Publishing to npm
-
-This project is configured for automatic npm publishing via GitHub Actions. When you push to `main`, the CI workflow runs tests and, if they pass, publishes the package to npm.
-
-### Prerequisites for publishing
-
-1. You must have an npm account and be a maintainer of the `miki-template` package on npm.
-2. In your GitHub repository, go to **Settings → Secrets and variables → Actions**.
-3. Add a new repository secret named `NPM_TOKEN` with your npm automation token.
-   - Generate it at https://www.npmjs.com/settings/YOUR_USERNAME/tokens
-   - Select **Automation** as the token type.
-
-The CI workflow will then automatically publish on every push to `main`.
-
-### Manual publishing
-
-```bash
-npm version patch   # or minor/major
-npm publish --access public
-```
-
----
-
-## Quick Start
-
-### 1. Add the engine to your project
-
-**CJS:**
-```js
-const { render, compile } = require('miki-template');
-```
-
-**ESM:**
-```js
-import { render, compile } from 'miki-template';
-```
-
-### 2. (Express) Register the view engine
-
-**CJS:**
-```js
-const express = require('express');
-const { __express: renderDtpl } = require('miki-template');
-const app = express();
-app.engine('html', renderDtpl);
-app.set('view engine', 'html');
-app.set('views', './views');
-```
-
-**ESM:**
-```js
-import express from 'express';
-import { __express as renderDtpl } from 'miki-template';
-
-const app = express();
-app.engine('html', renderDtpl);
-app.set('view engine', 'html');
-app.set('views', './views');
-```
-
-### 3. Run the test suite to verify
-
-```bash
-npm test
-```
-
----
-

package/docs/integrations.md

@@ -1,214 +0,0 @@
-## Integrations — miki-template
-
-This document shows concise examples for integrating `miki-template` with popular Node.js and Bun web frameworks. Use the synchronous `render()` API for CPU-bound sync templates, and `asyncRender()` when using async helpers.
-
-Notes
-- For CommonJS: `const miki = require('miki-template');`
-- For ESM / Bun: `import miki from 'miki-template';` or `import * as miki from 'miki-template';`
-- When rendering files, pass `options.views` or set framework view roots so the engine can locate templates.
-
-Setup (install)
-
-```bash
-# npm
-npm install miki-template
-
-# bun
-bun add miki-template
-```
-
-Express (recommended: use `setupExpress`)
-
-CommonJS
-
-```js
-const express = require('express');
-const miki = require('miki-template');
-
-const app = express();
-
-// One-line setup: wires engine, sets views, and patches res.render to support `view#partial`
-miki.setupExpress(app, { extension: 'html', views: './views' });
-
-app.get('/', (req, res) => {
-  res.render('index', { user: req.user });
-});
-
-app.get('/partial/:name', (req, res) => {
-  // Renders only the named partial inside the template
-  res.render(`index#${req.params.name}`, { user: req.user });
-});
-
-app.listen(3000);
-```
-
-ESM / Bun (similar)
-
-```js
-import express from 'express';
-import miki from 'miki-template';
-
-const app = express();
-miki.setupExpress(app, { extension: 'html', views: './views' });
-app.listen(3000);
-```
-
-Koa
-
-```js
-// CommonJS
-const Koa = require('koa');
-const path = require('path');
-const miki = require('miki-template');
-
-const app = new Koa();
-
-// Simple render helper attached to context
-app.context.render = async function (view, locals = {}) {
-  const html = await miki.asyncRender(view, locals, { views: path.resolve('./views') });
-  this.type = 'text/html';
-  this.body = html;
-};
-
-app.use(async (ctx) => {
-  await ctx.render('index', { user: ctx.state.user });
-});
-
-app.listen(3000);
-```
-
-Fastify
-
-```js
-const Fastify = require('fastify');
-const path = require('path');
-const miki = require('miki-template');
-
-const app = Fastify();
-
-app.get('/', async (request, reply) => {
-  const html = await miki.asyncRender('index', { user: request.user }, { views: path.resolve('./views') });
-  reply.type('text/html').send(html);
-});
-
-app.listen(3000);
-```
-
-NestJS (Express under the hood)
-
-```ts
-// In main.ts
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from './app.module';
-import * as miki from 'miki-template';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  // Use the underlying Express instance
-  const expressApp = app.getHttpAdapter().getInstance();
-  miki.setupExpress(expressApp, { extension: 'html', views: './views' });
-  await app.listen(3000);
-}
-bootstrap();
-```
-
-Ts.ED
-
-```ts
-// In server bootstrap
-import { ServerLoader } from '@tsed/di';
-import * as miki from 'miki-template';
-
-// Ts.ED also runs on Express/Koa — obtain the underlying app
-// and call miki.setupExpress(...) when using the Express adapter.
-
-// Example when using Express adapter:
-// miki.setupExpress(server.rawApp, { extension: 'html', views: './views' });
-```
-
-Elysia (Bun-friendly)
-
-```js
-// ESM / Bun example
-import { Elysia } from 'elysia';
-import * as miki from 'miki-template';
-import path from 'path';
-
-const app = new Elysia();
-
-app.get('/', async () => {
-  const html = await miki.asyncRender('index', { }, { views: path.resolve('./views') });
-  return new Response(html, { headers: { 'Content-Type': 'text/html' } });
-});
-
-app.listen(3000);
-```
-
-Hono (Edge + Bun)
-
-```js
-import { Hono } from 'hono';
-import * as miki from 'miki-template';
-import path from 'path';
-
-const app = new Hono();
-
-app.get('/', async (c) => {
-  const html = await miki.asyncRender('index', { }, { views: path.resolve('./views') });
-  return c.html(html);
-});
-
-app.listen({ port: 3000 });
-```
-
-Nifra / other minimal frameworks
-
-```js
-// Generic handler pattern — works in almost any framework
-// (Nifra users can adapt the response API)
-const miki = require('miki-template');
-const path = require('path');
-
-async function handler(req, res) {
-  const html = await miki.asyncRender('index', { }, { views: path.resolve('./views') });
-  res.setHeader('Content-Type', 'text/html');
-  res.end(html);
-}
-```
-
-Bun-specific notes
-- Bun is ESM-first; import `miki-template` using `import miki from 'miki-template'`.
-- Use `bun add miki-template` to install.
-- When using Bun's native servers, call `miki.asyncRender(...)` and return/send the Response object accordingly.
-
-Tips and best practices
-- Prefer `miki.setupExpress()` for Express-based apps — it wires partial rendering and view expansion.
-- For non-Express frameworks, call `miki.render()` (sync) or `miki.asyncRender()` (async) and set `options.views` to your views root (or pass absolute file paths resolved with your framework).
-- To support Django-style app templates (e.g. `packages/*/templates/...`), call `miki.setAppTemplateDirNames(['templates','app_templates'])` early in your app startup if you use a custom folder name.
-
-Engine usage & partial rendering
-
-Use the engine APIs directly when you don't want framework-specific wiring or when you need fine-grained control over `views` roots.
-
-```js
-const miki = require('miki-template');
-const path = require('path');
-
-// Sync render of a named partial inside a template file
-const html = miki.render('home#card', { user: 'Alice', title: 'Card' }, { views: path.resolve('./views') });
-
-// Async render when templates use async helpers
-const htmlAsync = await miki.asyncRender('home#card', { user: 'Bob' }, { views: path.resolve('./views') });
-
-// If your project arranges templates under custom folder names, configure
-// what constitutes an "app template" directory before rendering:
-miki.setAppTemplateDirNames(['templates', 'app_templates']);
-
-// To locate a template file programmatically without rendering, use the
-// exported finder helper:
-const found = miki.findTemplateInViews('home', [path.resolve('./views')]);
-if (found) console.log('Resolved to', found);
-```
-
-Further reading
-- See the main API docs for `setupExpress`, `render`, and `asyncRender` in `docs/api.md`.

package/docs/overview.md

@@ -1,79 +0,0 @@
-# Overview
-
-Welcome to **miki-template** – a production‑ready, Django‑style template engine for Node.js and Express. This documentation mirrors the layout of popular open‑source libraries (e.g., Django, Jinja2, Mustache) and provides a clear, hierarchical guide for developers of all skill levels.
-
-- **Project structure** – quick glance at the repository layout.
-- **Feature list** – exhaustive rundown of supported tags, filters, security helpers, and the new `partialdef` system.
-- **Getting started** – installation, basic rendering, and Express integration.
-- **Advanced usage** – inheritance, block rendering, custom tags/filters, and performance tips.
-
----
-
-## Repository layout
-
-```
-📦 miki-template/
-├─ 📁 src/               # Core engine source files
-│  ├─ index.js           # Entry point, compile/render APIs
-│  ├─ lexer.js           # Tokenizer
-│  ├─ parser.js          # AST builder
-│  ├─ context.js         # Scope & partial registry
-│  └─ tags/              # Built‑in tag parsers (control, inheritance, util)
-│     ├─ control.js      # if, for, with, cycle, partialdef, …
-│     ├─ inheritance.js # extends, block, super
-│     └─ util.js         # comment, verbatim, etc.
-├─ 📁 filters/           # Built‑in filter implementations
-├─ 📁 tests/             # Jest‑style test suite
-├─ 📁 docs/              # 📖 Documentation (this folder)
-├─ README.md            # Project landing page (high‑level intro)
-├─ AGENT.md             # Agent guardrails (internal)
-├─ ROADMAP.md           # Future roadmap & milestones
-└─ package.json         # npm package definition
-```
-
-Each module is deliberately **single‑responsibility** and fully typed via JSDoc comments, making it easy to extend.
-
----
-
-## Where to start
-
-- **Installation** – see `docs/installation.md`.
-- **Basic rendering** – see `docs/usage.md`.
-- **Tag reference** – see `docs/tags.md`.
-- **Filter reference** – see `docs/filters.md`.
-- **Partial definitions** – see `docs/partialdef.md`.
-- **Security considerations** – see `docs/security.md`.
-
-## Recursive and app-style template discovery
-
-`miki-template` now supports Django-style recursive template discovery. When you configure your views directory (via `miki.setupExpress(app, { views: './views' })` or by passing `views` to `render()`), the engine will:
-
-- Resolve direct paths like `nested/index` relative to each `views` directory.
-- If a bare template name (e.g. `card`) is used, recursively scan subfolders of the configured `views` directories to find `card.html` or `card.miki`.
-- Discover app-style `templates` directories located under application packages (e.g. `project/apps/product/templates/...`) and include them in the search.
-
-Configuration:
-
-- Programmatically set which folder names should be treated as app template roots via the API:
-
-	- `setAppTemplateDirNames(['templates', 'site_templates'])` — sets the list of folder names that will be discovered under the views root.
-	- `getAppTemplateDirNames()` — returns the current list.
-
-Examples:
-
-	- `render('home#card', ctx, { views: './views' })` will search `./views` and any `templates/` subfolders for `home.html` or `home.miki`, and render the `card` partial.
-	- If your project places templates under `packages/product/templates/detail.html`, `render('detail', ..., { views: './views' })` will find it automatically.
-
-This behavior is opt‑out by simply clearing the app-dir names: `setAppTemplateDirNames([])` will disable app-style discovery.
-
-For API‑level details (e.g., `compile().renderPartial`) check `docs/api.md`.
-
----
-
-## Contributing
-
-We follow the standard open‑source workflow. Details are in `docs/contributing.md`.
-
----
-
-> **Tip**: All documentation files are located under `c:/Users/Coder Miki/Desktop/miki-template/docs/`.

package/docs/partialdef.md

@@ -1,70 +0,0 @@
-# Partial Definition (`partialdef`)
-
-`partialdef` is the cornerstone feature that brings Django‑style **named template fragments** to Node.js. It allows you to define a reusable block once and render it multiple times, optionally **inline** for immediate output. Combined with the `setupExpress` helper, partials can be served as standalone HTTP responses for HTMX-style UIs.
-
-## Syntax
-```html
-{% partialdef name [inline] %}
-  ...template code...
-{% endpartialdef %}
-```
-- `name` – identifier used with `{% partial name %}`.
-- Optional `inline` – if present, the block is rendered **where it is defined**; no separate `{% partial %}` call is required.
-
-## Rendering a Partial
-```html
-{% partial greeting %}
-```
-The engine looks up the definition in the current rendering **Context** (`context.partialDefs`) and injects the rendered output.
-
-## Including a Partial From Another File
-Use the `file#partial` syntax to include just a single named partial:
-```html
-{% include "home.html#card" with title="Hi" %}
-```
-
-## API Usage
-```js
-const tpl = `{% partialdef api %}API {{ data }}{% endpartialdef %}`;
-const compiled = compile(tpl);
-const out = compiled.renderPartial('api', { data: 123 }); // "API 123"
-```
-
-`renderPartialFromSource` and `renderPartialFromFile` are also exported at the top level:
-```js
-const miki = require('miki-template');
-miki.renderPartialFromFile('views/home.html', 'card', { user: req.user });
-miki.renderPartialFromSource(src, 'card', { user: req.user }, { views: 'views' });
-```
-
-## Serving a Partial Over HTTP (HTMX)
-With `miki.setupExpress(app, { extension: 'html', views: './views' })`, the same `res.render(...)` call you use for full pages also serves a single partial by appending `#partialName` to the view name:
-
-```javascript
-app.get('/partials/:name', (req, res) =>
-  res.render(`home#${req.params.name}`, { user: req.user })
-);
-```
-
-The same effect can be obtained via the lighter `expressPartialRenderer()` middleware:
-```javascript
-app.use(miki.expressPartialRenderer());
-app.get('/card', (req, res) => res.renderPartial('home#card', { user: req.user }));
-```
-
-## Features
-- **Full tag parity** – conditionals (`if`), loops (`for`), variable scoping (`with`) work inside a `partialdef`.
-- **Nested partials** – you can define a partial inside another; inner definitions are registered first and can be used by the outer.
-- **Scope isolation** – each rendering of a partial receives its own scope, mirroring Django’s behavior.
-- **Inline rendering** – render inline without an extra `{% partial %}` tag (`{% partialdef foo inline %}…{% endpartialdef %}`).
-- **`with` arguments** – bind extra context values when rendering: `{% partial card with title="Hello" description="World" %}`.
-- **Performance** – partials are compiled once per template; subsequent renders reuse the compiled AST.
-
-## Common Pitfalls
-| Issue | Symptom | Fix |
-|-------|---------|-----|
-| Missing partial name | `{% partial %}` renders nothing | Ensure the name matches a defined `partialdef`. |
-| Variable not found | Appears empty | Variables are resolved in the current context; use `{% with %}` inside the partial if you need a local alias. |
-| Inline vs non‑inline confusion | Duplicate output | Use `inline` only when you want immediate rendering. |
-
-> Implementation lives in `src/tags/control.js` (class `PartialDefNode` and `PartialNode`).

package/docs/security.md

@@ -1,27 +0,0 @@
-# Security
-
-`miki-template` is built with **secure defaults**. All variables are **auto‑escaped** unless explicitly marked safe.
-
-## Auto‑escaping
-- Every string output goes through `escapeHtml` before being concatenated.
-- Use the `|safe` filter or `markSafe(value)` to bypass escaping when you trust the data.
-
-## CSRF Protection
-- The `{% csrf_token %}` tag renders a hidden `<input>` containing the `csrf_token` value from the rendering context.
-- Example:
-  ```html
-  <form method="post">{% csrf_token %} ... </form>
-  ```
-- It is a thin wrapper; you must generate and store `csrf_token` in your Express middleware.
-
-## CSP Nonce
-- `{% csp_nonce_attr %}` injects `nonce="{{ csp_nonce }}"` when `csp_nonce` is present in the context.
-- Useful for inline scripts when you have a CSP policy with `script-src 'nonce-...';`.
-
-## SafeString Wrapper
-- Filters returning `SafeString` bypass auto‑escaping. The wrapper is applied automatically by the `safe` filter.
-
-## No `eval`
-- Template expressions are parsed into an AST and evaluated using a sandboxed evaluator that **never calls `eval` or `new Function`**.
-
-> Security‑related code lives in `src/security.js` and the tag implementations in `src/tags/control.js`.