miki-template 1.2.0 → 1.3.6

package/src/cache.js

@@ -1,41 +1,80 @@
-// 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 };
+// 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();
+
+/**
+ * Parent-source cache shared across renders. Populated by
+ * renderAST/renderASTAsync in src/index.js so that `{% extends %}`
+ * doesn't re-read the parent file from disk on every render.
+ */
+const parentSourceCache = new Map();
+const PARENT_SOURCE_LIMIT = 64;
+
+function getParentSource(key, loader) {
+  if (parentSourceCache.has(key)) {
+    const v = parentSourceCache.get(key);
+    parentSourceCache.delete(key);
+    parentSourceCache.set(key, v);
+    return v;
+  }
+  const v = loader();
+  if (v != null) {
+    parentSourceCache.set(key, v);
+    if (parentSourceCache.size > PARENT_SOURCE_LIMIT) {
+      const firstKey = parentSourceCache.keys().next().value;
+      parentSourceCache.delete(firstKey);
+    }
+  }
+  return v;
+}
+
+function hasParentSource(key) {
+  return parentSourceCache.has(key);
+}
+
+/**
+ * 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) {
+  // Build a cache key that ignores non-serializable option values
+  // (e.g. functions like urlHelper, custom callbacks) — those don't
+  // affect template compilation, only render behavior.
+  const serializable = {};
+  for (const [k, v] of Object.entries(compileOptions || {})) {
+    if (typeof v === 'function' || typeof v === 'undefined') continue;
+    serializable[k] = v;
+  }
+  const key = JSON.stringify({ templateStr, compileOptions: serializable });
+  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();
+  parentSourceCache.clear();
+}
+
+module.exports = { getCompiled, clearCache, getParentSource, hasParentSource };

package/src/context.js

@@ -1,122 +1,126 @@
-/**
- * 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
-};
+/**
+ * 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 = undefined;
+    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) {
+      // Variable truly missing — return undefined so templates can
+      // distinguish "missing" from "explicitly null". The variable node
+      // and filters handle undefined gracefully.
+      return undefined;
+    }
+
+    // Traverse the rest of the dotted segments
+    for (let i = 1; i < parts.length; i++) {
+      if (current === undefined || current === null) {
+        return current === null ? null : undefined;
+      }
+
+      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 undefined;
+      }
+
+      // 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);
+    }
+
+    // Preserve null/undefined so filters like default_if_none can detect them.
+    return 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

@@ -1,41 +1,48 @@
-// 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 };
+// 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.
+ * Values returned by a processor that are already defined in the
+ * context are kept as-is (Django-style "existing values win" semantics
+ * so explicit render-time data always takes precedence over processor
+ * defaults).
+ * @param {Object} ctx
+ */
+function applyContextProcessors(ctx) {
+  for (const fn of processors) {
+    const result = fn(ctx);
+    if (result && typeof result === 'object') {
+      for (const [k, v] of Object.entries(result)) {
+        if (ctx[k] === undefined) {
+          ctx[k] = v;
+        }
+      }
+    }
+  }
+  return ctx;
+}
+
+module.exports = { registerContextProcessor, applyContextProcessors, clearContextProcessors };

package/src/esm.mjs

@@ -1,72 +1,84 @@
-// 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;
+// 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,
+  renderPartialFromFile,
+  renderPartialFromSource,
+  __express,
+  __expressAsync,
+  express,
+  setupExpress,
+  expressPartialRenderer,
+  stripExpressContext,
+  clearCache,
+  registerTag,
+  registerFilter,
+  registerHelper,
+  registerContextProcessor,
+  clearContextProcessors,
+  registerTranslation,
+  unregisterTranslation,
+  setLanguage,
+  getLanguage,
+  setFallbackLanguage,
+  getFallbackLanguage,
+  getAvailableLanguages,
+  registerLibrary,
+  unregisterLibrary,
+  getLibrary,
+  getLibraryNames,
+  hasLibrary,
+  registerLibraryFromPath,
+  SafeString,
+  markSafe,
+  isSafe,
+  escapeHtml
+} = cjsModule;
+
+export {
+  compile,
+  render,
+  asyncRender,
+  renderPartialFromFile,
+  renderPartialFromSource,
+  __express,
+  __expressAsync,
+  express,
+  setupExpress,
+  expressPartialRenderer,
+  stripExpressContext,
+  clearCache,
+  registerTag,
+  registerFilter,
+  registerHelper,
+  registerContextProcessor,
+  clearContextProcessors,
+  registerTranslation,
+  unregisterTranslation,
+  setLanguage,
+  getLanguage,
+  setFallbackLanguage,
+  getFallbackLanguage,
+  getAvailableLanguages,
+  registerLibrary,
+  unregisterLibrary,
+  getLibrary,
+  getLibraryNames,
+  hasLibrary,
+  registerLibraryFromPath,
+  SafeString,
+  markSafe,
+  isSafe,
+  escapeHtml
+};
+
+export default cjsModule;