miki-template 1.2.0

package/src/libraries.js

@@ -0,0 +1,240 @@
+/**
+ * Plugin/filter library system.
+ *
+ * A "library" is a JavaScript object exporting:
+ *   { tags?: { [name]: parserFn }, filters?: { [name]: filterFn } }
+ *
+ * Libraries can be:
+ *  - Built-in (e.g. 'i18n', 'cache', 'humanize', 'markdown')
+ *  - Custom user-defined via `registerLibrary(name, lib)`
+ *  - Loaded from disk via `registerLibraryFromPath(name, path)`
+ *
+ * Once registered, a library is activated in templates via:
+ *   {% load library_name %}
+ *   {% load i18n cache humanize %}
+ */
+const fs = require('fs');
+const path = require('path');
+
+const libraries = new Map(); // Map<name, libraryDef>
+
+/**
+ * Register a library.
+ *
+ *   registerLibrary('markdown', {
+ *     tags: { markdown: parseMarkdown },
+ *     filters: { markdown: renderMarkdown }
+ *   });
+ */
+function registerLibrary(name, def) {
+  if (!name || typeof name !== 'string') {
+    throw new TypeError('Library name must be a non-empty string');
+  }
+  if (!def || typeof def !== 'object') {
+    throw new TypeError(`Library '${name}' definition must be an object`);
+  }
+  libraries.set(name, {
+    tags: def.tags || {},
+    filters: def.filters || {},
+    helpers: def.helpers || {}
+  });
+}
+
+/** Unregister a library or all libraries. */
+function unregisterLibrary(name) {
+  if (!name) {
+    libraries.clear();
+    return;
+  }
+  libraries.delete(name);
+}
+
+/** Get a registered library by name. */
+function getLibrary(name) {
+  return libraries.get(name);
+}
+
+/** List all registered library names. */
+function getLibraryNames() {
+  return Array.from(libraries.keys());
+}
+
+/**
+ * Load a library from a JavaScript file on disk.
+ * The file must be a CommonJS module exporting `{ tags, filters, helpers }`.
+ */
+function registerLibraryFromPath(name, filePath, options = {}) {
+  const absolutePath = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(options.baseDir || process.cwd(), filePath);
+  if (!fs.existsSync(absolutePath)) {
+    throw new Error(`Library file not found: ${absolutePath}`);
+  }
+  // Defensive: restrict to .js/.cjs/.mjs files
+  const ext = path.extname(absolutePath).toLowerCase();
+  if (ext !== '.js' && ext !== '.cjs' && ext !== '.mjs') {
+    throw new Error(`Library file extension '${ext}' is not allowed`);
+  }
+  // Clear require cache if not pinned
+  if (!options.pinned) {
+    delete require.cache[require.resolve(absolutePath)];
+  }
+  const def = require(absolutePath);
+  registerLibrary(name, def);
+  return def;
+}
+
+/**
+ * Apply the tags, filters, and helpers from a library to the runtime registries.
+ */
+function activateLibrary(name) {
+  const lib = libraries.get(name);
+  if (!lib) {
+    throw new Error(`Library not found: '${name}'`);
+  }
+  const { registerTag, registerFilter, registerHelper } = require('./index');
+  for (const [tagName, parserFn] of Object.entries(lib.tags || {})) {
+    registerTag(tagName, parserFn);
+  }
+  for (const [filterName, filterFn] of Object.entries(lib.filters || {})) {
+    registerFilter(filterName, filterFn);
+  }
+  for (const [helperName, helperFn] of Object.entries(lib.helpers || {})) {
+    registerHelper(helperName, helperFn);
+  }
+}
+
+/**
+ * Check if a library is registered.
+ */
+function hasLibrary(name) {
+  return libraries.has(name);
+}
+
+// --- Built-in libraries ---
+
+/** Humanize: nice-looking text formatting filters. */
+registerLibrary('humanize', {
+  filters: {
+    intcomma: (val) => {
+      const parts = String(val === null || val === undefined ? '' : val).split('.');
+      parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+      return parts.join('.');
+    },
+    intword: (val) => {
+      const n = parseFloat(val);
+      if (isNaN(n)) return String(val);
+      const abs = Math.abs(n);
+      if (abs >= 1e9) return (n / 1e9).toFixed(1).replace(/\.0$/, '') + ' billion';
+      if (abs >= 1e6) return (n / 1e6).toFixed(1).replace(/\.0$/, '') + ' million';
+      if (abs >= 1e3) return (n / 1e3).toFixed(1).replace(/\.0$/, '') + ' thousand';
+      return String(n);
+    },
+    apnumber: (val) => {
+      const n = parseInt(val, 10);
+      const words = ['zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten',
+        'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen', 'sixteen', 'seventeen', 'eighteen', 'nineteen'];
+      if (!isNaN(n) && n >= 0 && n < words.length) return words[n];
+      return String(val);
+    },
+    ordinal: (val) => {
+      const n = parseInt(val, 10);
+      if (isNaN(n)) return String(val);
+      const s = ['th', 'st', 'nd', 'rd'];
+      const v = n % 100;
+      return n + (s[(v - 20) % 10] || s[v] || s[0]);
+    },
+    naturalday: (val) => {
+      const d = new Date(val);
+      if (isNaN(d.getTime())) return String(val);
+      const today = new Date();
+      const yesterday = new Date(today);
+      yesterday.setDate(today.getDate() - 1);
+      const tomorrow = new Date(today);
+      tomorrow.setDate(today.getDate() + 1);
+      const sameDay = (a, b) =>
+        a.getFullYear() === b.getFullYear() &&
+        a.getMonth() === b.getMonth() &&
+        a.getDate() === b.getDate();
+      if (sameDay(d, today)) return 'today';
+      if (sameDay(d, yesterday)) return 'yesterday';
+      if (sameDay(d, tomorrow)) return 'tomorrow';
+      return String(val);
+    }
+  }
+});
+
+/** Cache: cache expensive template fragment results. */
+registerLibrary('cache', {
+  tags: {
+    cache: (tagContent, parser) => {
+      // {% cache timeout key1 key2 ... %}...{% endcache %}
+      const rest = tagContent.slice(5).trim();
+      const tokens = rest.split(/\s+/);
+      const timeout = parseInt(tokens[0], 10) || 0;
+      const key = tokens.slice(1).join(':') || 'default';
+      const body = parser.parse(['endcache']);
+      const next = parser.peek();
+      if (next && next.type === 'block' && next.content.split(/\s+/)[0] === 'endcache') {
+        parser.advance();
+      }
+      return {
+        render(context) {
+          const ctx = context;
+          const fullKey = `cache:${key}`;
+          if (ctx.cacheStore && ctx.cacheStore.has(fullKey)) {
+            const entry = ctx.cacheStore.get(fullKey);
+            if (Date.now() - entry.time < timeout * 1000) {
+              return entry.value;
+            }
+          }
+          const value = body.map(n => n.render(context)).join('');
+          if (ctx.cacheStore) {
+            ctx.cacheStore.set(fullKey, { time: Date.now(), value });
+          }
+          return value;
+        }
+      };
+    }
+  }
+});
+
+/** Lorem: generate placeholder text. */
+registerLibrary('lorem', {
+  filters: {
+    lorem: (val, arg) => {
+      const text = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.';
+      let n = parseInt(arg, 10);
+      if (isNaN(n)) n = 5;
+      if (n < 1) n = 1;
+      if (n > 100) n = 100;
+      const words = text.split(' ');
+      let result = [];
+      for (let i = 0; i < n; i++) {
+        result.push(words[i % words.length]);
+      }
+      return result.join(' ');
+    }
+  }
+});
+
+/** Static: additional static-file helpers. */
+registerLibrary('static', {
+  filters: {
+    static: (val) => {
+      // Returns the value prefixed with the staticUrl (configured at compile time)
+      return val; // Implementation lives in the {% static %} tag
+    }
+  }
+});
+
+module.exports = {
+  registerLibrary,
+  unregisterLibrary,
+  getLibrary,
+  getLibraryNames,
+  hasLibrary,
+  registerLibraryFromPath,
+  activateLibrary,
+  libraries
+};

package/src/parser.js

@@ -0,0 +1,250 @@
+/**
+ * Parser converting token stream into AST Nodes.
+ */
+const { escapeHtml, isSafe } = require('./security');
+const filtersModule = require('./filters');
+
+class TextNode {
+  constructor(content) {
+    this.content = content;
+  }
+
+  render(_context) {
+    return this.content;
+  }
+}
+
+class VariableNode {
+  constructor(varPath, filters, isLiteral = false, literalValue = null) {
+    this.varPath = varPath;
+    this.filters = filters;
+    this.isLiteral = isLiteral;
+    this.literalValue = literalValue;
+  }
+
+  render(context) {
+    let val = this.isLiteral ? this.literalValue : context.get(this.varPath);
+
+    for (const filterInfo of this.filters) {
+      const filterFn = filtersModule.getFilter(filterInfo.name);
+      if (!filterFn) {
+        throw new Error(`Unknown filter: '${filterInfo.name}'`);
+      }
+
+      let argVal = undefined;
+      if (filterInfo.arg) {
+        if (filterInfo.arg.type === 'literal') {
+          argVal = filterInfo.arg.value;
+        } else if (filterInfo.arg.type === 'variable') {
+          argVal = context.get(filterInfo.arg.value);
+        }
+      }
+
+      val = filterFn(val, argVal);
+    }
+
+    // Auto-escape logic – skip escaping if value is marked safe
+    if (context.autoescape && !isSafe(val)) {
+      return escapeHtml(val);
+    }
+
+    return val === null || val === undefined ? '' : String(val);
+  }
+}
+
+/**
+ * Parses a variable expression including filters and arguments.
+ * E.g., user.name|lower|default:"Guest"
+ */
+function parseVariableExpression(expr) {
+  let idx = 0;
+  const len = expr.length;
+
+  function skipWhitespace() {
+    while (idx < len && /\s/.test(expr[idx])) {
+      idx++;
+    }
+  }
+
+  let varPath = '';
+  let isLiteral = false;
+  let literalValue = null;
+
+  // Check for string literal as base value
+  if (idx < len && (expr[idx] === '"' || expr[idx] === '\'')) {
+    const quote = expr[idx];
+    idx++;
+    let strVal = '';
+    while (idx < len && expr[idx] !== quote) {
+      if (expr[idx] === '\\' && idx + 1 < len) {
+        idx++;
+      }
+      strVal += expr[idx];
+      idx++;
+    }
+    idx++; // Skip closing quote
+    isLiteral = true;
+    literalValue = strVal;
+    skipWhitespace();
+  }
+
+  // Parse main variable path
+  if (!isLiteral) {
+    while (idx < len && expr[idx] !== '|') {
+      varPath += expr[idx];
+      idx++;
+    }
+    varPath = varPath.trim();
+  }
+
+  const filters = [];
+  while (idx < len) {
+    if (expr[idx] === '|') {
+      idx++; // Skip '|'
+      skipWhitespace();
+
+      // Read filter name
+      let filterName = '';
+      while (idx < len && expr[idx] !== ':' && expr[idx] !== '|' && !/\s/.test(expr[idx])) {
+        filterName += expr[idx];
+        idx++;
+      }
+
+      skipWhitespace();
+      let arg = null;
+
+      if (idx < len && expr[idx] === ':') {
+        idx++; // Skip ':'
+        skipWhitespace();
+
+        // Parse argument (string literal, number, boolean, null, or variable)
+        if (expr[idx] === '"' || expr[idx] === '\'') {
+          const quote = expr[idx];
+          idx++; // Skip opening quote
+          let argVal = '';
+          while (idx < len && expr[idx] !== quote) {
+            if (expr[idx] === '\\') {
+              idx++;
+            }
+            if (idx < len) {
+              argVal += expr[idx];
+              idx++;
+            }
+          }
+          idx++; // Skip closing quote
+          arg = { type: 'literal', value: argVal };
+        } else {
+          // Read unquoted token
+          let argVal = '';
+          while (idx < len && expr[idx] !== '|' && !/\s/.test(expr[idx])) {
+            argVal += expr[idx];
+            idx++;
+          }
+          argVal = argVal.trim();
+
+          // Type coercion
+          if (!isNaN(argVal) && argVal !== '') {
+            arg = { type: 'literal', value: Number(argVal) };
+          } else if (argVal === 'true') {
+            arg = { type: 'literal', value: true };
+          } else if (argVal === 'false') {
+            arg = { type: 'literal', value: false };
+          } else if (argVal === 'none' || argVal === 'None' || argVal === 'null') {
+            arg = { type: 'literal', value: null };
+          } else {
+            // Variable lookup
+            arg = { type: 'variable', value: argVal };
+          }
+        }
+      }
+
+      filters.push({ name: filterName, arg });
+      skipWhitespace();
+    } else {
+      idx++;
+    }
+  }
+
+  return { varPath, filters, isLiteral, literalValue };
+}
+
+class Parser {
+  // Existing constructor and methods remain unchanged
+  /**
+   * Parse tokens until a specific end tag, consuming the end tag token.
+   * @param {string} endTag - Tag name to stop at (e.g., 'endsleep').
+   * @returns {Array} Parsed nodes.
+   */
+  parseUntilTag(endTag) {
+    const nodes = this.parse([endTag]);
+    // Advance past the end tag token if present
+    const next = this.peek();
+    if (next && next.type === 'block' && next.content.split(/\s+/)[0] === endTag) {
+      this.advance();
+    }
+    return nodes;
+  }
+
+  constructor(tokens, tagRegistry = {}) {
+    this.tokens = tokens;
+    this.index = 0;
+    this.tagRegistry = tagRegistry;
+  }
+
+  /**
+   * Parses tokens into AST nodes until one of the tags in untilTags is encountered.
+   */
+  parse(untilTags = []) {
+    const nodes = [];
+    while (this.index < this.tokens.length) {
+      const token = this.tokens[this.index];
+
+      if (token.type === 'text') {
+        nodes.push(new TextNode(token.content));
+        this.index++;
+      } else if (token.type === 'var') {
+        const parsed = parseVariableExpression(token.content);
+        nodes.push(new VariableNode(parsed.varPath, parsed.filters, parsed.isLiteral, parsed.literalValue));
+        this.index++;
+      } else if (token.type === 'block') {
+        const parts = token.content.split(/\s+/);
+        const tagName = parts[0];
+
+        // Stop parsing if we hit a stop tag
+        if (untilTags.includes(tagName)) {
+          break;
+        }
+
+        this.index++; // Consume block token
+
+        const tagParser = this.tagRegistry[tagName];
+        if (!tagParser) {
+          throw new Error(`Unknown template tag: '${tagName}'`);
+        }
+
+        const node = tagParser(token.content, this);
+        nodes.push(node);
+      }
+    }
+    // If we were looking for specific end tags but didn't find them, throw
+    if (untilTags.length > 0 && this.index >= this.tokens.length) {
+      throw new Error(`Unexpected end of template - expected one of: ${untilTags.map(t => '{% ' + t + ' %}').join(', ')}`);
+    }
+    return nodes;
+  }
+
+  peek() {
+    return this.tokens[this.index];
+  }
+
+  advance() {
+    this.index++;
+  }
+}
+
+module.exports = {
+  Parser,
+  TextNode,
+  VariableNode,
+  parseVariableExpression
+};

package/src/security.js

@@ -0,0 +1,51 @@
+/**
+ * Security and HTML auto-escaping mechanisms.
+ */
+const he = require('he');
+
+class SafeString {
+  constructor(value) {
+    this.value = value === null || value === undefined ? '' : String(value);
+  }
+
+  toString() {
+    return this.value;
+  }
+}
+
+/**
+ * Mark a string as safe so it is not auto-escaped during rendering.
+ */
+function markSafe(value) {
+  if (value instanceof SafeString) {
+    return value;
+  }
+  return new SafeString(value);
+}
+
+/**
+ * Check if a value is marked safe.
+ */
+function isSafe(value) {
+  return value instanceof SafeString;
+}
+
+/**
+ * Escape a string's HTML special characters unless it is marked safe.
+ */
+function escapeHtml(value) {
+  if (value instanceof SafeString) {
+    return value.toString();
+  }
+
+  const str = value === null || value === undefined ? '' : String(value);
+  // We use he.escape to convert <, >, &, ", ', etc. to entities
+  return he.escape(str);
+}
+
+module.exports = {
+  SafeString,
+  markSafe,
+  isSafe,
+  escapeHtml
+};