miki-template 1.2.0

package/context/project-structure.md

@@ -0,0 +1,33 @@
+/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/docs/README.md

@@ -0,0 +1,18 @@
+# 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

@@ -0,0 +1,71 @@
+# 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

@@ -0,0 +1,102 @@
+# 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. | `app.set('view engine', 'miki');` |
+| `__expressAsync(filePath, options)` | `__expressAsync(string, object) → Promise<string>` | Async Express 5+ view engine adapter. Returns a Promise that resolves to rendered HTML. | `app.engine('html', miki.__expressAsync);` |
+| `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,
+  stripExpressContext,
+  clearCache,
+  registerTag,
+  registerFilter,
+  getFilter,
+  registerHelper,
+  registerContextProcessor,
+  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,
+  stripExpressContext,
+  clearCache,
+  registerTag,
+  registerFilter,
+  getFilter,
+  registerHelper,
+  registerContextProcessor,
+  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 } = 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`