miki-template 1.2.0

package/snippets/miki-template.json

@@ -0,0 +1,177 @@
+{
+  "miki-template": {
+    "if": {
+      "prefix": "if",
+      "body": [
+        "{% if ${1:condition} %}",
+        "  ${2:content}",
+        "{% endif %}"
+      ],
+      "description": "If block"
+    },
+    "ifelse": {
+      "prefix": "ifelse",
+      "body": [
+        "{% if ${1:condition} %}",
+        "  ${2:content}",
+        "{% else %}",
+        "  ${3:fallback}",
+        "{% endif %}"
+      ],
+      "description": "If/else block"
+    },
+    "for": {
+      "prefix": "for",
+      "body": [
+        "{% for ${1:item} in ${2:items} %}",
+        "  ${3:{{ ${1} }}}",
+        "{% empty %}",
+        "  ${4:No items}",
+        "{% endfor %}"
+      ],
+      "description": "For loop"
+    },
+    "block": {
+      "prefix": "block",
+      "body": [
+        "{% block ${1:name} %}",
+        "  ${2:content}",
+        "{% endblock %}"
+      ],
+      "description": "Block definition"
+    },
+    "extends": {
+      "prefix": "extends",
+      "body": "{% extends \"${1:base.html}\" %}",
+      "description": "Extends parent template"
+    },
+    "include": {
+      "prefix": "include",
+      "body": "{% include \"${1:header.html}\" %}",
+      "description": "Include template"
+    },
+    "with": {
+      "prefix": "with",
+      "body": [
+        "{% with ${1:var} as ${2:alias} %}",
+        "  ${3:{{ ${2} }}}",
+        "{% endwith %}"
+      ],
+      "description": "With block"
+    },
+    "cycle": {
+      "prefix": "cycle",
+      "body": "{% cycle '${1:odd}' '${2:even}' %}",
+      "description": "Cycle tag"
+    },
+    "trans": {
+      "prefix": "trans",
+      "body": "{% trans \"${1:Hello, World!}\" %}",
+      "description": "Translate string"
+    },
+    "blocktrans": {
+      "prefix": "blocktrans",
+      "body": [
+        "{% blocktrans with ${1:name}=${2:user.name} %}",
+        "  ${3:Hello {{ ${1} }}}",
+        "{% endblocktrans %}"
+      ],
+      "description": "Translate block"
+    },
+    "language": {
+      "prefix": "language",
+      "body": [
+        "{% language \"${1:fr}\" %}",
+        "  ${2}",
+        "{% endlanguage %}"
+      ],
+      "description": "Switch language"
+    },
+    "partialdef": {
+      "prefix": "partialdef",
+      "body": [
+        "{% partialdef ${1:name} %}",
+        "  ${2}",
+        "{% endpartialdef %}"
+      ],
+      "description": "Define partial"
+    },
+    "partial": {
+      "prefix": "partial",
+      "body": "{% partial ${1:name} %}",
+      "description": "Render partial"
+    },
+    "csrf": {
+      "prefix": "csrf",
+      "body": "{% csrf_token %}",
+      "description": "CSRF token input"
+    },
+    "csp": {
+      "prefix": "csp",
+      "body": "<script {% csp_nonce_attr %}></script>",
+      "description": "CSP nonce attribute"
+    },
+    "static": {
+      "prefix": "static",
+      "body": "{% static \"${1:css/app.css}\" %}",
+      "description": "Static file URL"
+    },
+    "url": {
+      "prefix": "url",
+      "body": "{% url \"${1:route_name}\" ${2:args} %}",
+      "description": "URL for named route"
+    },
+    "widthratio": {
+      "prefix": "widthratio",
+      "body": "{% widthratio ${1:value} ${2:max} ${3:max_width} %}",
+      "description": "Proportional width"
+    },
+    "debug": {
+      "prefix": "debug",
+      "body": "{% debug %}",
+      "description": "Dump template context"
+    },
+    "load": {
+      "prefix": "load",
+      "body": "{% load ${1:i18n} %}",
+      "description": "Load tag library"
+    },
+    "comment": {
+      "prefix": "comment",
+      "body": [
+        "{#",
+        "  ${1:comment}",
+        "#}"
+      ],
+      "description": "Comment block"
+    },
+    "verbatim": {
+      "prefix": "verbatim",
+      "body": [
+        "{% verbatim %}",
+        "  ${1}",
+        "{% endverbatim %}"
+      ],
+      "description": "Verbatim block"
+    },
+    "regroup": {
+      "prefix": "regroup",
+      "body": "{% for ${1:group} in ${2:items}|regroup:\"${3:category}\" %}{{ ${1}.grouper }}{% endfor %}",
+      "description": "Regroup by attribute"
+    },
+    "firstof": {
+      "prefix": "firstof",
+      "body": "{% firstof ${1:var1} ${2:var2} \"${3:fallback}\" %}",
+      "description": "First truthy value"
+    },
+    "filter_block": {
+      "prefix": "filter",
+      "body": [
+        "{% filter ${1:lower} %}",
+        "  ${2}",
+        "{% endfilter %}"
+      ],
+      "description": "Filter block"
+    }
+  }
+}

package/src/asyncRender.js

@@ -0,0 +1,21 @@
+// Async rendering utilities
+
+/**
+ * Async version of renderAST that awaits any Promise returned by node.render.
+ * Handles async nodes anywhere in the AST (inside conditionals, loops, etc.)
+ */
+async function asyncRenderAST(nodes, context) {
+  // Helper to render a single node, awaiting if needed, and recursively handling children
+  const renderNode = async (node) => {
+    const result = node.render(context);
+    return result instanceof Promise ? await result : result;
+  };
+
+  const parts = [];
+  for (const node of nodes) {
+    parts.push(await renderNode(node));
+  }
+  return parts.join('');
+}
+
+module.exports = { asyncRenderAST };

package/src/cache.js

@@ -0,0 +1,41 @@
+// Simple AST cache module
+
+/**
+ * In‑memory LRU cache for compiled templates.
+ * For demo purposes we use a plain Map limited to 100 entries.
+ */
+const CACHE_LIMIT = 100;
+const cache = new Map();
+
+/**
+ * Retrieve a compiled template from cache or compile it and store.
+ * @param {string} templateStr – template source
+ * @param {object} compileOptions – options passed to compile()
+ * @param {function} compileFn – the original compile function from src/index.js
+ * @returns {object} compiled template object
+ */
+function getCompiled(templateStr, compileOptions, compileFn) {
+  const key = JSON.stringify({ templateStr, compileOptions });
+  if (cache.has(key)) {
+    // Move to end to mark as recently used
+    const value = cache.get(key);
+    cache.delete(key);
+    cache.set(key, value);
+    return value;
+  }
+  const compiled = compileFn(templateStr, compileOptions);
+  cache.set(key, compiled);
+  // Trim if we exceed limit
+  if (cache.size > CACHE_LIMIT) {
+    const firstKey = cache.keys().next().value;
+    cache.delete(firstKey);
+  }
+  return compiled;
+}
+
+/** Clear the cache – useful for tests */
+function clearCache() {
+  cache.clear();
+}
+
+module.exports = { getCompiled, clearCache };

package/src/context.js

@@ -0,0 +1,122 @@
+/**
+ * Context manager handling scopes and dotted variable lookup.
+ */
+class Context {
+  constructor(initial = {}, options = {}) {
+    this.scopes = [initial];
+    this.options = options;
+    this.autoescape = true; // Autoescape state
+    this.blocks = {}; // For template inheritance blocks
+    this.parentTemplate = null; // For extends tag
+    this.cycleStates = new Map(); // Store state for cycle tags
+    this.partialDefs = new Map(); // Store partial definitions
+  }
+
+  /**
+   * Reset cycle state and blocks for a fresh render.
+   * Called at the start of each render pass.
+   */
+  reset() {
+    this.cycleStates.clear();
+    this.blocks = {};
+    this.parentTemplate = null;
+  }
+
+  /**
+   * Push a new scope onto the stack.
+   */
+  push(scope = {}) {
+    this.scopes.unshift(scope);
+    return this;
+  }
+
+  /**
+   * Pop the top scope from the stack.
+   */
+  pop() {
+    if (this.scopes.length > 1) {
+      this.scopes.shift();
+    }
+    return this;
+  }
+
+  /**
+   * Resolve a dotted path lookup.
+   * Examples: 'user.name', 'items.0', 'user.profile.age'
+   */
+  get(path) {
+    if (path === undefined || path === null || path === '') {
+      return '';
+    }
+
+    const parts = path.split('.');
+    const baseName = parts[0];
+
+    let current = null;
+    let found = false;
+
+    // Search scopes from top (most local) to bottom (most global)
+    for (const scope of this.scopes) {
+      if (scope && typeof scope === 'object' && baseName in scope) {
+        current = scope[baseName];
+        found = true;
+        break;
+      }
+    }
+
+    if (!found) {
+      return '';
+    }
+
+    // Traverse the rest of the dotted segments
+    for (let i = 1; i < parts.length; i++) {
+      if (current === undefined || current === null) {
+        return '';
+      }
+
+      const parent = current;
+      const part = parts[i];
+
+      // Resolve segment on the current value
+      if (typeof current === 'object' && part in current) {
+        current = current[part];
+      } else if (Array.isArray(current) && !isNaN(part)) {
+        // Handle array index resolution, e.g. items.0
+        current = current[parseInt(part, 10)];
+      } else {
+        return '';
+      }
+
+      // If the property value is a function, evaluate it (Django style)
+      if (typeof current === 'function') {
+        current = current.call(parent);
+      }
+    }
+
+    // If the final resolved value is a function, call it with no arguments
+    if (typeof current === 'function') {
+      current = current.call(null);
+    }
+
+    return current !== undefined && current !== null ? current : '';
+  }
+
+  /**
+   * Register a partial definition.
+   */
+  registerPartial(name, node) {
+    this.partialDefs.set(name, node);
+  }
+
+  /**
+   * Retrieve a registered partial.
+   */
+  getPartial(name) {
+    return this.partialDefs.get(name);
+  }
+
+}
+
+module.exports = {
+  Context
+};

package/src/context_processors.js

@@ -0,0 +1,41 @@
+// Context Processors – similar to Django's custom context processors
+// Allows users to register functions that inject additional variables into the rendering context.
+
+const processors = [];
+
+/**
+ * Register a context processor function.
+ * The function receives the current context object (plain JS object) and may return
+ * an object of key/value pairs to be merged into the context.
+ * @param {function(Object): (Object|undefined)} fn
+ */
+function registerContextProcessor(fn) {
+  if (typeof fn !== 'function') {
+    throw new Error('Context processor must be a function');
+  }
+  processors.push(fn);
+}
+
+/**
+ * Clear all registered context processors.
+ */
+function clearContextProcessors() {
+  processors.length = 0;
+}
+
+/**
+ * Apply all registered processors to the given context object.
+ * Mutates the context object by merging any returned values.
+ * @param {Object} ctx
+ */
+function applyContextProcessors(ctx) {
+  for (const fn of processors) {
+    const result = fn(ctx);
+    if (result && typeof result === 'object') {
+      Object.assign(ctx, result);
+    }
+  }
+  return ctx;
+}
+
+module.exports = { registerContextProcessor, applyContextProcessors, clearContextProcessors };

package/src/esm.mjs

@@ -0,0 +1,72 @@
+// ESM wrapper for miki-template
+// Re-exports the CommonJS module for use with `import` syntax.
+// Usage:
+//   import miki from 'miki-template';
+//   // or:
+//   import { render, compile, __express, SafeString, markSafe } from 'miki-template';
+
+import cjsModule from './index.js';
+
+const {
+  compile,
+  render,
+  asyncRender,
+  __express,
+  __expressAsync,
+  stripExpressContext,
+  clearCache,
+  registerTag,
+  registerFilter,
+  registerHelper,
+  registerContextProcessor,
+  registerTranslation,
+  unregisterTranslation,
+  setLanguage,
+  getLanguage,
+  setFallbackLanguage,
+  getFallbackLanguage,
+  getAvailableLanguages,
+  registerLibrary,
+  unregisterLibrary,
+  getLibrary,
+  getLibraryNames,
+  hasLibrary,
+  registerLibraryFromPath,
+  SafeString,
+  markSafe,
+  isSafe,
+  escapeHtml
+} = cjsModule;
+
+export {
+  compile,
+  render,
+  asyncRender,
+  __express,
+  __expressAsync,
+  stripExpressContext,
+  clearCache,
+  registerTag,
+  registerFilter,
+  registerHelper,
+  registerContextProcessor,
+  registerTranslation,
+  unregisterTranslation,
+  setLanguage,
+  getLanguage,
+  setFallbackLanguage,
+  getFallbackLanguage,
+  getAvailableLanguages,
+  registerLibrary,
+  unregisterLibrary,
+  getLibrary,
+  getLibraryNames,
+  hasLibrary,
+  registerLibraryFromPath,
+  SafeString,
+  markSafe,
+  isSafe,
+  escapeHtml
+};
+
+export default cjsModule;