miki-template 1.2.0

package/src/tags/util.js

@@ -0,0 +1,322 @@
+/**
+ * Utility template tags: static, url, regroup, spaceless.
+ */
+
+// Helper to resolve expression values
+function resolveValue(token, context) {
+  if (!token) return '';
+  if ((token.startsWith('"') && token.endsWith('"')) || (token.startsWith('\'') && token.endsWith('\''))) {
+    return token.slice(1, -1);
+  }
+  return context.get(token);
+}
+
+class StaticNode {
+  constructor(pathExpr) {
+    this.pathExpr = pathExpr;
+  }
+
+  render(context) {
+    const resolvedPath = resolveValue(this.pathExpr, context);
+    
+    // Resolve static prefix
+    let prefix = '/static/';
+    if (context.options && context.options.staticUrl) {
+      prefix = context.options.staticUrl;
+    } else if (context.options && context.options.settings && context.options.settings.staticUrl) {
+      prefix = context.options.settings.staticUrl;
+    }
+
+    // Ensure double-slash doesn't occur and ends/starts correctly
+    const base = prefix.endsWith('/') ? prefix : prefix + '/';
+    const relative = resolvedPath.startsWith('/') ? resolvedPath.slice(1) : resolvedPath;
+    
+    return base + relative;
+  }
+}
+
+class UrlNode {
+  constructor(routeNameExpr, argsExprs) {
+    this.routeNameExpr = routeNameExpr;
+    this.argsExprs = argsExprs || [];
+  }
+
+  render(context) {
+    const routeName = resolveValue(this.routeNameExpr, context);
+    const resolvedArgs = this.argsExprs.map(arg => resolveValue(arg, context));
+
+    // If an Express urlHelper is provided, use it
+    if (context.options && typeof context.options.urlHelper === 'function') {
+      return context.options.urlHelper(routeName, ...resolvedArgs);
+    }
+
+    // Fallback URL generator
+    return '/' + [routeName, ...resolvedArgs].filter(Boolean).join('/');
+  }
+}
+
+class RegroupNode {
+  constructor(listPath, attr, targetName) {
+    this.listPath = listPath;
+    this.attr = attr;
+    this.targetName = targetName;
+  }
+
+  render(context) {
+    const list = context.get(this.listPath);
+    if (!Array.isArray(list)) {
+      context.scopes[0][this.targetName] = [];
+      return '';
+    }
+
+    const groups = [];
+    const groupMap = new Map();
+
+    for (const item of list) {
+      // Resolve attribute (support nested lookup on item)
+      let val = '';
+      if (item && typeof item === 'object') {
+        const parts = this.attr.split('.');
+        let current = item;
+        for (const part of parts) {
+          if (current && typeof current === 'object' && part in current) {
+            current = current[part];
+          } else {
+            current = undefined;
+            break;
+          }
+        }
+        val = current !== undefined ? current : '';
+      }
+
+      if (!groupMap.has(val)) {
+        const newGroup = { grouper: val, list: [] };
+        groupMap.set(val, newGroup);
+        groups.push(newGroup);
+      }
+      groupMap.get(val).list.push(item);
+    }
+
+    // Store in the current context scope
+    context.scopes[0][this.targetName] = groups;
+    return '';
+  }
+}
+
+class SpacelessNode {
+  constructor(body) {
+    this.body = body;
+  }
+
+  render(context) {
+    const content = this.body.map(n => n.render(context)).join('');
+    // Remove space between HTML tags
+    return content.replace(/>\s+</g, '><');
+  }
+}
+
+class CsrfTokenNode {
+  render(context) {
+    const token = context.get('csrf_token') || '';
+    const html = `<input type="hidden" name="csrfmiddlewaretoken" value="${token}">`;
+    const { markSafe } = require('../security');
+    return markSafe(html);
+  }
+}
+
+class CspNonceAttrNode {
+  render(context) {
+    const nonce = context.get('csp_nonce') || '';
+    if (!nonce) return '';
+    const html = `nonce="${nonce}"`;
+    const { markSafe } = require('../security');
+    return markSafe(html);
+  }
+}
+
+// --- Tag Registry Parsers ---
+
+function parseStatic(tagContent, _parser) {
+  // tagContent: "static 'css/style.css'"
+  const pathExpr = tagContent.slice(6).trim();
+  return new StaticNode(pathExpr);
+}
+
+function parseUrl(tagContent, _parser) {
+  // tagContent: "url 'route_name' arg1 arg2"
+  const content = tagContent.slice(3).trim();
+  
+  // Extract route name and arguments
+  const argRegex = /(".*?"|'.*?'|[^\s]+)/g;
+  const matches = content.match(argRegex) || [];
+  
+  const routeNameExpr = matches[0];
+  const argsExprs = matches.slice(1);
+
+  return new UrlNode(routeNameExpr, argsExprs);
+}
+
+function parseRegroup(tagContent, _parser) {
+  // tagContent: "regroup people by gender as grouped"
+  const match = tagContent.match(/^regroup\s+(.+?)\s+by\s+(.+?)\s+as\s+(.+)$/);
+  if (!match) {
+    throw new Error(`Invalid regroup tag format: '${tagContent}'`);
+  }
+
+  const listPath = match[1].trim();
+  const attr = match[2].trim();
+  const targetName = match[3].trim();
+
+  return new RegroupNode(listPath, attr, targetName);
+}
+
+function parseSpaceless(tagContent, parser) {
+  const body = parser.parse(['endspaceless']);
+  const next = parser.peek();
+  if (next && next.type === 'block' && next.content.split(/\s+/)[0] === 'endspaceless') {
+    parser.advance();
+  }
+  return new SpacelessNode(body);
+}
+
+function parseCsrfToken(_tagContent, _parser) {
+  return new CsrfTokenNode();
+}
+
+class WidthRatioNode {
+  constructor(value, maxValue, maxWidth) {
+    this.value = parseFloat(value);
+    this.maxValue = parseFloat(maxValue);
+    this.maxWidth = parseInt(maxWidth, 10);
+  }
+
+  render(_context) {
+    if (!isFinite(this.value) || !isFinite(this.maxValue) || this.maxValue === 0) {
+      return '0';
+    }
+    const ratio = Math.floor((this.value / this.maxValue) * this.maxWidth);
+    return String(Math.max(0, Math.min(ratio, this.maxWidth)));
+  }
+}
+
+class DebugNode {
+  render(context) {
+    // Dump the current context (scopes) for debugging
+    const dump = {
+      scopes: context.scopes.map(s => {
+        if (s && typeof s === 'object') {
+          const out = {};
+          for (const k of Object.keys(s)) {
+            if (k.startsWith('__')) continue;
+            try {
+              const v = s[k];
+              out[k] = typeof v === 'function' ? '[function]' : v;
+            } catch {
+              out[k] = '[unreadable]';
+            }
+          }
+          return out;
+        }
+        return String(s);
+      })
+    };
+    const { escapeHtml, markSafe } = require('../security');
+    return markSafe('<pre>' + escapeHtml(JSON.stringify(dump, null, 2)) + '</pre>');
+  }
+}
+
+function parseWidthRatio(tagContent, _parser) {
+  // {% widthratio this_value max_value max_width %}
+  const parts = tagContent.replace(/^widthratio\s+/, '').trim().split(/\s+/);
+  if (parts.length < 3) {
+    throw new Error('\'widthratio\' tag requires 3 arguments: value, max_value, max_width');
+  }
+  return new WidthRatioNode(parts[0], parts[1], parts[2]);
+}
+
+function parseDebug(_tagContent, _parser) {
+  return new DebugNode();
+}
+
+function parseCspNonceAttr(_tagContent, _parser) {
+  return new CspNonceAttrNode();
+}
+
+class LoadNode {
+  constructor(libraries) {
+    this.libraries = Array.isArray(libraries) ? libraries : [libraries];
+  }
+
+  render(_context) {
+    const { activateLibrary, hasLibrary } = require('../libraries');
+    for (const lib of this.libraries) {
+      if (hasLibrary(lib)) {
+        activateLibrary(lib);
+      } else {
+        // Emit a comment-style warning for missing library
+        console.warn(`[miki-template] Library not found: '${lib}'`);
+      }
+    }
+    return '';
+  }
+}
+
+class TemplatetagNode {
+  constructor(token) {
+    this.token = token;
+  }
+
+  render(_context) {
+    const map = {
+      'openblock': '{%',
+      'closeblock': '%}',
+      'openvariable': '{{',
+      'closevariable': '}}',
+      'openbrace': '{',
+      'closebrace': '}',
+      'opencomment': '{#',
+      'closecomment': '#}'
+    };
+    return map[this.token] || this.token;
+  }
+}
+
+function parseLoad(tagContent, _parser) {
+  const parts = tagContent.trim().split(/\s+/);
+  if (parts.length === 0) {
+    throw new Error('\'load\' tag requires at least one argument');
+  }
+  return new LoadNode(parts);
+}
+
+function parseTemplatetag(tagContent, _parser) {
+  const parts = tagContent.trim().split(/\s+/);
+  // First part is the tag name, rest is the argument
+  const token = parts.length > 1 ? parts.slice(1).join(' ') : parts[0];
+  return new TemplatetagNode(token);
+}
+
+module.exports = {
+  StaticNode,
+  UrlNode,
+  RegroupNode,
+  SpacelessNode,
+  CsrfTokenNode,
+  CspNonceAttrNode,
+  LoadNode,
+  TemplatetagNode,
+  WidthRatioNode,
+  DebugNode,
+  parsers: {
+    static: parseStatic,
+    url: parseUrl,
+    regroup: parseRegroup,
+    spaceless: parseSpaceless,
+    csrf_token: parseCsrfToken,
+    csp_nonce_attr: parseCspNonceAttr,
+    load: parseLoad,
+    templatetag: parseTemplatetag,
+    widthratio: parseWidthRatio,
+    debug: parseDebug
+  }
+};

package/src/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * TypeScript definitions for miki-template
+ * Generated manually to match the actual runtime API.
+ */
+
+declare namespace miki {
+  /**
+   * A compiled template instance returned by `compile()`.
+   */
+  interface CompiledTemplate {
+    /** Synchronously render the template. */
+    render(context?: TemplateContext): string;
+    /** Asynchronously render the template (awaits Promise helpers). */
+    asyncRender(context?: TemplateContext): Promise<string>;
+    /** Render a single named block. */
+    renderBlock(blockName: string, context?: TemplateContext): string;
+    /** Render a defined `{% partialdef %}` by name. */
+    renderPartial(partialName: string, context?: TemplateContext): string;
+  }
+
+  /** Context object passed to render functions. */
+  interface TemplateContext {
+    [key: string]: any;
+  }
+
+  /** Options for `compile()` and `render()`. */
+  interface CompileOptions {
+    /** Directories to search for `extends`/`include` templates. */
+    views?: string | string[];
+    /** Prefix for the `{% static %}` tag. */
+    staticUrl?: string;
+    /** Custom URL resolver for `{% url %}` tag. */
+    urlHelper?: (routeName: string, ...args: any[]) => string;
+  }
+
+  /** A custom filter function. */
+  type FilterFunction = (value: any, arg?: any) => any;
+
+  /** A custom tag parser function. */
+  type TagParserFunction = (tagContent: string, parser: any) => ASTNode;
+
+  /** A custom helper function (block tag). */
+  type HelperFunction = (content: string, context: any) => string | Promise<string>;
+
+  /** A context processor. */
+  type ContextProcessor = (context: TemplateContext) => TemplateContext | void;
+
+  /** An AST node with a `render(context)` method. */
+  interface ASTNode {
+    render(context: any): string | Promise<string>;
+  }
+
+  /**
+   * SafeString — a string marker that bypasses HTML auto-escaping.
+   */
+  class SafeString {
+    constructor(value: string);
+    toString(): string;
+  }
+}
+
+declare module "miki-template" {
+  export = miki;
+  export as namespace miki;
+
+  /** Compile a template string into a reusable renderable object. */
+  export function compile(templateStr: string, options?: miki.CompileOptions): miki.CompiledTemplate;
+
+  /** One-off template render. */
+  export function render(templateStr: string, context?: miki.TemplateContext, options?: miki.CompileOptions): string;
+
+  /** Async one-off render (supports async helpers). */
+  export function asyncRender(templateStr: string, context?: miki.TemplateContext, options?: miki.CompileOptions): Promise<string>;
+
+  /** Express view engine adapter. */
+  export function __express(filePath: string, options: miki.TemplateContext, callback: (err: Error | null, html?: string) => void): void;
+
+  /** Async Express view engine adapter (Express 5+). */
+  export function __expressAsync(filePath: string, options: miki.TemplateContext): Promise<string>;
+
+  /** Clear the in-memory compiled template cache. */
+  export function clearCache(): void;
+
+  /** Register a custom tag parser. */
+  export function registerTag(name: string, parserFn: miki.TagParserFunction): void;
+
+  /** Register a custom filter. */
+  export function registerFilter(name: string, filterFn: miki.FilterFunction): void;
+
+  /** Register a custom block helper. */
+  export function registerHelper(name: string, fn: miki.HelperFunction): void;
+
+  /** Register a context processor. */
+  export function registerContextProcessor(fn: miki.ContextProcessor): void;
+
+  /** Mark a value as HTML-safe (bypasses auto-escaping). */
+  export function markSafe(value: any): miki.SafeString;
+
+  /** Check if a value is a SafeString. */
+  export function isSafe(value: any): boolean;
+
+  /** Escape HTML special characters. */
+  export function escapeHtml(str: string): string;
+
+  /** SafeString class for marking values as safe. */
+  export const SafeString: typeof miki.SafeString;
+}

package/syntaxes/language-configuration.json

@@ -0,0 +1,26 @@
+{
+  "comments": {
+    "lineComment": "{#",
+    "blockComment": ["{#", "#}"]
+  },
+  "brackets": [
+    ["{", "}"],
+    ["[", "]"],
+    ["(", ")"]
+  ],
+  "autoClosingPairs": [
+    { "open": "{", "close": "}" },
+    { "open": "[", "close": "]" },
+    { "open": "(", "close": ")" },
+    { "open": "\"", "close": "\"", "notIn": ["string"] },
+    { "open": "'", "close": "'", "notIn": ["string", "comment"] }
+  ],
+  "surroundingPairs": [
+    { "open": "{", "close": "}" },
+    { "open": "[", "close": "]" },
+    { "open": "(", "close": ")" },
+    { "open": "\"", "close": "\"" },
+    { "open": "'", "close": "'" }
+  ],
+  "wordPattern": "[a-zA-Z_][a-zA-Z0-9_.]*"
+}

package/syntaxes/miki-template.tmLanguage.json

@@ -0,0 +1,146 @@
+{
+  "scopeName": "text.html.miki",
+  "name": "miki-template",
+  "patterns": [
+    {
+      "include": "#comment"
+    },
+    {
+      "include": "#tag"
+    },
+    {
+      "include": "#variable"
+    },
+    {
+      "include": "#string"
+    }
+  ],
+  "repository": {
+    "comment": {
+      "name": "comment.block.miki",
+      "begin": "\\{#",
+      "end": "#\\}",
+      "beginCaptures": {
+        "0": { "name": "punctuation.definition.comment.begin.miki" }
+      },
+      "endCaptures": {
+        "0": { "name": "punctuation.definition.comment.end.miki" }
+      }
+    },
+    "tag": {
+      "name": "meta.tag.miki",
+      "begin": "\\{%",
+      "end": "%\\}",
+      "beginCaptures": {
+        "0": { "name": "punctuation.definition.tag.begin.miki" }
+      },
+      "endCaptures": {
+        "0": { "name": "punctuation.definition.tag.end.miki" }
+      },
+      "patterns": [
+        {
+          "name": "entity.name.tag.miki",
+          "match": "(?i)\\b(if|elif|else|endif|for|empty|endfor|with|endwith|cycle|comment|endcomment|verbatim|endverbatim|include|extends|block|endblock|partialdef|endpartialdef|partial|load|templatetag|trans|blocktrans|language|endlanguage|plural|widthratio|debug|endif|endfor|endwith|endblock|endcomment|endverbatim|endpartialdef|endblocktrans|endlanguage|endcache|endmarkdown)\\b"
+        },
+        {
+          "name": "string.quoted.double.miki",
+          "match": "\"[^\"]*\""
+        },
+        {
+          "name": "string.quoted.single.miki",
+          "match": "'[^']*'"
+        },
+        {
+          "name": "constant.numeric.miki",
+          "match": "\\b\\d+\\b"
+        },
+        {
+          "name": "keyword.operator.miki",
+          "match": "(?i)\\b(and|or|not|in|not in)\\b"
+        },
+        {
+          "name": "punctuation.separator.miki",
+          "match": "="
+        }
+      ]
+    },
+    "variable": {
+      "name": "variable.other.miki",
+      "begin": "\\{\\{",
+      "end": "\\}\\}",
+      "beginCaptures": {
+        "0": { "name": "punctuation.definition.variable.begin.miki" }
+      },
+      "endCaptures": {
+        "0": { "name": "punctuation.definition.variable.end.miki" }
+      },
+      "patterns": [
+        {
+          "name": "variable.other.miki",
+          "match": "[a-zA-Z_][a-zA-Z0-9_.]*"
+        },
+        {
+          "include": "#filter"
+        },
+        {
+          "name": "string.quoted.double.miki",
+          "match": "\"[^\"]*\""
+        },
+        {
+          "name": "string.quoted.single.miki",
+          "match": "'[^']*'"
+        }
+      ]
+    },
+    "filter": {
+      "name": "meta.filter.miki",
+      "begin": "\\|",
+      "end": "(?=\\}|$)",
+      "beginCaptures": {
+        "0": { "name": "punctuation.separator.filter.miki" }
+      },
+      "patterns": [
+        {
+          "name": "support.function.miki",
+          "match": "[a-zA-Z_][a-zA-Z0-9_]*"
+        },
+        {
+          "begin": ":",
+          "beginCaptures": {
+            "0": { "name": "punctuation.separator.filter.argument.miki" }
+          },
+          "end": "(?=\\||\\}\\})",
+          "patterns": [
+            {
+              "name": "string.quoted.double.miki",
+              "match": "\"[^\"]*\""
+            },
+            {
+              "name": "string.quoted.single.miki",
+              "match": "'[^']*'"
+            },
+            {
+              "name": "constant.numeric.miki",
+              "match": "\\b\\d+\\b"
+            },
+            {
+              "name": "variable.other.miki",
+              "match": "[a-zA-Z_][a-zA-Z0-9_.]*"
+            }
+          ]
+        }
+      ]
+    },
+    "string": {
+      "name": "string.quoted.double.miki",
+      "begin": "\"",
+      "end": "\"",
+      "beginCaptures": {
+        "0": { "name": "punctuation.definition.string.begin.miki" }
+      },
+      "endCaptures": {
+        "0": { "name": "punctuation.definition.string.end.miki" }
+      }
+    }
+  }
+}

package/tests/asyncRender.test.js

@@ -0,0 +1,17 @@
+// tests/asyncRender.test.js
+const test = require('node:test');
+const { asyncRender, registerHelper } = require('../src');
+
+// Register a simple async helper that sleeps
+registerHelper('sleep', async (content) => {
+  const ms = parseInt(content, 10) || 0;
+  await new Promise(r => setTimeout(r, ms));
+  return `slept ${ms}ms`;
+});
+
+test('asyncRender with sleep helper', async () => {
+  const tmpl = `{% sleep %}30{% endsleep %}`;
+  const result = await asyncRender(tmpl, {});
+  const assert = require('node:assert');
+  assert.strictEqual(result, 'slept 30ms');
+});

package/tests/base.html

@@ -0,0 +1,6 @@
+<html>
+<body>
+  {% block header %}Default Header{% endblock %}
+  {% block content %}{% endblock %}
+</body>
+</html>

package/tests/child.html

@@ -0,0 +1,3 @@
+{% extends "base.html" %}
+{% block header %}Child Header ({{ block.super }}){% endblock %}
+{% block content %}Child Content{% endblock %}

package/tests/context_processors.test.js

@@ -0,0 +1,13 @@
+// Context Processors test using node:test
+const test = require('node:test');
+const assert = require('node:assert');
+const { registerContextProcessor, clearContextProcessors } = require('../src/context_processors');
+const { compile } = require('../src');
+
+test('Context processor injects variable', () => {
+  clearContextProcessors();
+  registerContextProcessor(() => ({ siteName: 'DemoSite' }));
+  const tmpl = '{{ siteName }}';
+  const rendered = compile(tmpl).render({});
+  assert.strictEqual(rendered, 'DemoSite');
+});

package/tests/esm.test.mjs

@@ -0,0 +1,26 @@
+// Test ESM import support
+import { render, compile, SafeString, markSafe } from '../src/esm.mjs';
+import test from 'node:test';
+import assert from 'node:assert';
+
+test('ESM - default named imports', () => {
+  const result = render('Hello {{ name }}!', { name: 'ESM' });
+  assert.strictEqual(result, 'Hello ESM!');
+});
+
+test('ESM - compile import', () => {
+  const compiled = compile('Hi {{ user }}!');
+  assert.strictEqual(compiled.render({ user: 'World' }), 'Hi World!');
+});
+
+test('ESM - SafeString import', () => {
+  const html = new SafeString('<b>Bold</b>');
+  const result = render('{{ html }}', { html });
+  assert.strictEqual(result, '<b>Bold</b>');
+});
+
+test('ESM - markSafe import', () => {
+  const safe = markSafe('<i>Italic</i>');
+  const result = render('{{ x }}', { x: safe });
+  assert.strictEqual(result, '<i>Italic</i>');
+});