@rhinostone/swig-core 2.0.0-alpha.3

package/lib/cache.js

@@ -0,0 +1,75 @@
+/**
+ * Template cache primitives — shared across @rhinostone/swig-family engines.
+ *
+ * Each helper is pure: state (the memory cache object, the engine's options)
+ * is passed in explicitly so the same helpers can serve multiple frontends
+ * without closure state. The native Swig constructor wires its inline
+ * `self.cache` + `self.options.cache` through these at each call site.
+ *
+ * See .claude/architecture/multi-flavor-ir.md — cache keys are opaque
+ * strings; the cache layer has no filename awareness.
+ */
+
+/**
+ * Determine whether caching is disabled via the per-call options or the
+ * engine's default options.
+ *
+ * Match semantics of the previous inline closure in lib/swig.js:
+ *   return (options.hasOwnProperty('cache') && !options.cache) ||
+ *     !engineCache;
+ *
+ * @param  {object} [options]    Per-call Swig options. May have a `cache` key.
+ * @param  {*}      engineCache  The engine's default `options.cache` value.
+ * @return {boolean}             True if caching should be skipped.
+ */
+exports.shouldCache = function (options, engineCache) {
+  options = options || {};
+  return (options.hasOwnProperty('cache') && !options.cache) || !engineCache;
+};
+
+/**
+ * Read a compiled template from the cache.
+ *
+ * @param  {string} key          Resolved template identifier.
+ * @param  {object} [options]    Per-call Swig options.
+ * @param  {*}      engineCache  The engine's default `options.cache` value
+ *                               (`'memory'`, `false`, or a `{ get, set }` object).
+ * @param  {object} memoryStore  The engine's in-memory cache map
+ *                               (used only when engineCache === 'memory').
+ * @return {object|undefined}    Cached compiled template, or undefined on miss.
+ */
+exports.cacheGet = function (key, options, engineCache, memoryStore) {
+  if (exports.shouldCache(options, engineCache)) {
+    return;
+  }
+
+  if (engineCache === 'memory') {
+    return memoryStore[key];
+  }
+
+  return engineCache.get(key);
+};
+
+/**
+ * Store a compiled template in the cache.
+ *
+ * @param  {string} key          Resolved template identifier.
+ * @param  {object} [options]    Per-call Swig options.
+ * @param  {*}      val          Compiled template to cache.
+ * @param  {*}      engineCache  The engine's default `options.cache` value.
+ * @param  {object} memoryStore  The engine's in-memory cache map
+ *                               (used only when engineCache === 'memory').
+ * @return {undefined}
+ */
+exports.cacheSet = function (key, options, val, engineCache, memoryStore) {
+  if (exports.shouldCache(options, engineCache)) {
+    return;
+  }
+
+  if (engineCache === 'memory') {
+    memoryStore[key] = val;
+    return;
+  }
+
+  engineCache.set(key, val);
+};

package/lib/dateformatter.js

@@ -0,0 +1,201 @@
+var utils = require('./utils');
+
+var _months = {
+    full: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
+    abbr: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+  },
+  _days = {
+    full: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
+    abbr: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
+    alt: {'-1': 'Yesterday', 0: 'Today', 1: 'Tomorrow'}
+  };
+
+/*
+DateZ is licensed under the MIT License:
+Copyright (c) 2011 Tomo Universalis (http://tomouniversalis.com)
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+exports.tzOffset = 0;
+// Offset sign convention: minutes WEST of GMT, matching JS
+// Date#getTimezoneOffset() and PHP date(). Counterintuitive at
+// first glance: -240 renders as GMT+4, +240 renders as GMT-4.
+exports.DateZ = function () {
+  var members = {
+      'default': ['getUTCDate', 'getUTCDay', 'getUTCFullYear', 'getUTCHours', 'getUTCMilliseconds', 'getUTCMinutes', 'getUTCMonth', 'getUTCSeconds', 'toISOString', 'toGMTString', 'toUTCString', 'valueOf', 'getTime'],
+      z: ['getDate', 'getDay', 'getFullYear', 'getHours', 'getMilliseconds', 'getMinutes', 'getMonth', 'getSeconds', 'getYear', 'toDateString', 'toLocaleDateString', 'toLocaleTimeString']
+    },
+    d = this;
+
+  d.date = d.dateZ = (arguments.length > 1) ? new Date(Date.UTC.apply(Date, arguments) + ((new Date()).getTimezoneOffset() * 60000)) : (arguments.length === 1) ? new Date(new Date(arguments['0'])) : new Date();
+
+  d.timezoneOffset = d.dateZ.getTimezoneOffset();
+
+  utils.each(members.z, function (name) {
+    d[name] = function () {
+      return d.dateZ[name]();
+    };
+  });
+  utils.each(members['default'], function (name) {
+    d[name] = function () {
+      return d.date[name]();
+    };
+  });
+
+  this.setTimezoneOffset(exports.tzOffset);
+};
+exports.DateZ.prototype = {
+  getTimezoneOffset: function () {
+    return this.timezoneOffset;
+  },
+  setTimezoneOffset: function (offset) {
+    this.timezoneOffset = offset;
+    this.dateZ = new Date(this.date.getTime() + this.date.getTimezoneOffset() * 60000 - this.timezoneOffset * 60000);
+    return this;
+  }
+};
+
+// Day
+exports.d = function (input) {
+  return (input.getDate() < 10 ? '0' : '') + input.getDate();
+};
+exports.D = function (input) {
+  return _days.abbr[input.getDay()];
+};
+exports.j = function (input) {
+  return input.getDate();
+};
+exports.l = function (input) {
+  return _days.full[input.getDay()];
+};
+exports.N = function (input) {
+  var d = input.getDay();
+  return (d >= 1) ? d : 7;
+};
+exports.S = function (input) {
+  var d = input.getDate();
+  return (d % 10 === 1 && d !== 11 ? 'st' : (d % 10 === 2 && d !== 12 ? 'nd' : (d % 10 === 3 && d !== 13 ? 'rd' : 'th')));
+};
+exports.w = function (input) {
+  return input.getDay();
+};
+exports.z = function (input, offset, abbr) {
+  var year = input.getFullYear(),
+    e = new exports.DateZ(year, input.getMonth(), input.getDate(), 12, 0, 0),
+    d = new exports.DateZ(year, 0, 1, 12, 0, 0);
+
+  e.setTimezoneOffset(offset, abbr);
+  d.setTimezoneOffset(offset, abbr);
+  return Math.round((e - d) / 86400000);
+};
+
+// Week
+exports.W = function (input) {
+  var target = new Date(input.valueOf()),
+    dayNr = (input.getDay() + 6) % 7,
+    fThurs;
+
+  target.setDate(target.getDate() - dayNr + 3);
+  fThurs = target.valueOf();
+  target.setMonth(0, 1);
+  if (target.getDay() !== 4) {
+    target.setMonth(0, 1 + ((4 - target.getDay()) + 7) % 7);
+  }
+
+  return 1 + Math.ceil((fThurs - target) / 604800000);
+};
+
+// Month
+exports.F = function (input) {
+  return _months.full[input.getMonth()];
+};
+exports.m = function (input) {
+  return (input.getMonth() < 9 ? '0' : '') + (input.getMonth() + 1);
+};
+exports.M = function (input) {
+  return _months.abbr[input.getMonth()];
+};
+exports.n = function (input) {
+  return input.getMonth() + 1;
+};
+exports.t = function (input) {
+  return 32 - (new Date(input.getFullYear(), input.getMonth(), 32).getDate());
+};
+
+// Year
+exports.L = function (input) {
+  return new Date(input.getFullYear(), 1, 29).getDate() === 29;
+};
+exports.o = function (input) {
+  var target = new Date(input.valueOf());
+  target.setDate(target.getDate() - ((input.getDay() + 6) % 7) + 3);
+  return target.getFullYear();
+};
+exports.Y = function (input) {
+  return input.getFullYear();
+};
+exports.y = function (input) {
+  return (input.getFullYear().toString()).substr(2);
+};
+
+// Time
+exports.a = function (input) {
+  return input.getHours() < 12 ? 'am' : 'pm';
+};
+exports.A = function (input) {
+  return input.getHours() < 12 ? 'AM' : 'PM';
+};
+exports.B = function (input) {
+  var hours = input.getUTCHours(), beats;
+  hours = (hours === 23) ? 0 : hours + 1;
+  beats = Math.abs(((((hours * 60) + input.getUTCMinutes()) * 60) + input.getUTCSeconds()) / 86.4).toFixed(0);
+  return ('000'.concat(beats).slice(beats.length));
+};
+exports.g = function (input) {
+  var h = input.getHours();
+  return h === 0 ? 12 : (h > 12 ? h - 12 : h);
+};
+exports.G = function (input) {
+  return input.getHours();
+};
+exports.h = function (input) {
+  var h = input.getHours();
+  return ((h < 10 || (12 < h && 22 > h)) ? '0' : '') + ((h < 12) ? h : h - 12);
+};
+exports.H = function (input) {
+  var h = input.getHours();
+  return (h < 10 ? '0' : '') + h;
+};
+exports.i = function (input) {
+  var m = input.getMinutes();
+  return (m < 10 ? '0' : '') + m;
+};
+exports.s = function (input) {
+  var s = input.getSeconds();
+  return (s < 10 ? '0' : '') + s;
+};
+//u = function () { return ''; },
+
+// Timezone
+//e = function () { return ''; },
+//I = function () { return ''; },
+exports.O = function (input) {
+  var tz = input.getTimezoneOffset();
+  return (tz < 0 ? '-' : '+') + (tz / 60 < 10 ? '0' : '') + Math.abs((tz / 60)) + '00';
+};
+//T = function () { return ''; },
+exports.Z = function (input) {
+  return input.getTimezoneOffset() * 60;
+};
+
+// Full Date/Time
+exports.c = function (input) {
+  return input.toISOString();
+};
+exports.r = function (input) {
+  return input.toUTCString();
+};
+exports.U = function (input) {
+  return input.getTime() / 1000;
+};

package/lib/engine.js

@@ -0,0 +1,414 @@
+var utils = require('./utils'),
+  backend = require('./backend'),
+  cache = require('./cache');
+
+/**
+ * Empty function used as a fallback in compiled template code.
+ * @return {string} Empty string.
+ * @private
+ */
+function efn() { return ''; }
+
+/**
+ * Runtime engine plumbing shared across @rhinostone/swig-family frontends.
+ *
+ * Phase 1 carve — owns the `extends`-chain walker and block-remap helpers.
+ * The native Swig constructor in lib/swig.js delegates here so each frontend
+ * inherits the loader-walk + circular-extends detection + block merge logic
+ * for free.
+ *
+ * Each helper is pure: frontend-specific state (the resolving loader, the
+ * source-to-tokens parseFile, the cache lookup, the parent template cache)
+ * is injected via a `deps` parameter rather than captured through a
+ * closure. Helpers treat template identifiers as opaque strings — they do
+ * not know whether the loader's `resolve` output is a file path, a URL, or
+ * a Memcached key.
+ *
+ * See .claude/architecture/multi-flavor-ir.md — filename-aware code
+ * (utils.throwError wrapping, the engine's try/catch that attaches a
+ * filename to compile errors) stays in the frontend.
+ */
+
+/**
+ * Re-map block tags inside a parent token list to the child template's
+ * overriding block tags.
+ *
+ * @param  {object} blocks  Map of block name → overriding block token.
+ * @param  {array}  tokens  Parent token list.
+ * @return {array}          Remapped token list.
+ */
+exports.remapBlocks = function remapBlocks(blocks, tokens) {
+  return utils.map(tokens, function (token) {
+    var args = token.args ? token.args.join('') : '';
+    if (token.name === 'block' && blocks[args]) {
+      token = blocks[args];
+    }
+    if (token.content && token.content.length) {
+      token.content = remapBlocks(blocks, token.content);
+    }
+    return token;
+  });
+};
+
+/**
+ * Inject the child template's non-`block` block-level tags (e.g. `set`,
+ * `import`) onto the top of the rendered parent's token list so they run
+ * before the parent's body.
+ *
+ * @param  {object} blocks  Child template's block-level token map.
+ * @param  {array}  tokens  Token list to prepend onto.
+ * @return {undefined}
+ */
+exports.importNonBlocks = function (blocks, tokens) {
+  var temp = [];
+  utils.each(blocks, function (block) { temp.push(block); });
+  utils.each(temp.reverse(), function (block) {
+    if (block.name !== 'block') {
+      tokens.unshift(block);
+    }
+  });
+};
+
+/**
+ * Walk a template's `extends` chain and build the parent token tree.
+ * Detects circular inheritance.
+ *
+ * Deps are injected so each frontend can plug in its own loader and
+ * parse-to-tokens implementation:
+ *
+ *   deps.resolve(to, from)          → string     (loader.resolve)
+ *   deps.parseFile(pathname, opts)  → token tree (frontend-specific)
+ *   deps.cacheGet(key, options)     → token tree | undefined
+ *
+ * @param  {object} tokens    Parsed token tree for the child template.
+ *                            Must expose `.parent` (or falsy).
+ * @param  {object} [options] Per-call Swig options. `options.filename` is
+ *                            required when `tokens.parent` is set.
+ * @param  {object} deps      Injected frontend helpers.
+ * @return {array}            Parent templates, outermost-first.
+ */
+exports.getParents = function (tokens, options, deps) {
+  var parentName = tokens.parent,
+    parentFiles = [],
+    parents = [],
+    parentFile,
+    parent,
+    l;
+
+  while (parentName) {
+    if (!options || !options.filename) {
+      throw new Error('Cannot extend "' + parentName + '" because current template has no filename.');
+    }
+
+    parentFile = parentFile || options.filename;
+    parentFile = deps.resolve(parentName, parentFile);
+    parent = deps.cacheGet(parentFile, options) || deps.parseFile(parentFile, utils.extend({}, options, { filename: parentFile }));
+    parentName = parent.parent;
+
+    if (parentFiles.indexOf(parentFile) !== -1) {
+      throw new Error('Illegal circular extends of "' + parentFile + '".');
+    }
+    parentFiles.push(parentFile);
+
+    parents.push(parent);
+  }
+
+  // Remap each parent's(1) blocks onto its own parent(2), receiving the full
+  // token list for rendering the original parent(1) on its own.
+  l = parents.length;
+  for (l = parents.length - 2; l >= 0; l -= 1) {
+    parents[l].tokens = exports.remapBlocks(parents[l].blocks, parents[l + 1].tokens);
+    exports.importNonBlocks(parents[l].blocks, parents[l].tokens);
+  }
+
+  return parents;
+};
+
+/**
+ * Build a renderable template Function from a parsed token tree.
+ *
+ * Walks tokens via the swig-core backend codegen, wraps the emitted body
+ * in the `new Function('_swig', '_ctx', '_filters', '_utils', '_fn', ...)`
+ * construction, and returns the function. The argument list is the
+ * contract every tag's compile() output depends on — `_output`, `_ext`,
+ * `_ctx`, etc. are referenced by name in emitted code.
+ *
+ * Filename attribution on compile-time failures lives on the frontend
+ * per the seam rule (the caller knows which template the body came from
+ * and can attach that via options.filename in its own try/catch). This
+ * helper only throws whatever `new Function(...)` throws — the caller
+ * can catch and rewrap.
+ *
+ * @param  {object|array} tokens   Parsed token tree.
+ * @param  {array}  [parents]      Parent tokens from getParents().
+ * @param  {object} [options]      Swig options object.
+ * @return {Function}              Template function.
+ */
+exports.buildTemplateFunction = function (tokens, parents, options) {
+  return new Function('_swig', '_ctx', '_filters', '_utils', '_fn',
+    '  var _ext = _swig.extensions,\n' +
+    '    _output = "";\n' +
+    backend.compile(tokens, parents, options) + '\n' +
+    '  return _output;\n'
+    );
+};
+
+/**
+ * Install the swig-family runtime API on a Swig instance. Called by each
+ * frontend's constructor after state init (options, cache, extensions).
+ *
+ * The frontend supplies its per-flavor parser, tag/filter maps, option
+ * validator, and a filename-attribution error wrap. Install then attaches
+ * the full instance API — setFilter, setTag, setExtension, parse,
+ * parseFile, precompile, compile, compileFile, render, renderFile, run,
+ * invalidateCache — to `self`.
+ *
+ * Frontend contract:
+ *   frontend.parser           Module with a `.parse(swig, src, opts, tags, filters)` method.
+ *   frontend.tags             Tag map mutated by setTag.
+ *   frontend.filters          Filter map mutated by setFilter.
+ *   frontend.validateOptions  Per-flavor options validator. Called at every parse/setDefaults entry point.
+ *   frontend.onCompileError   Invoked with (err, options) when `new Function(body)` throws. Owns filename attribution per the seam rule.
+ *
+ * @param  {object} self      Swig instance. Must already have `options`,
+ *                            `cache`, and `extensions` populated.
+ * @param  {object} frontend  Per-flavor wiring. See above.
+ * @return {undefined}
+ */
+exports.install = function (self, frontend) {
+  var parser = frontend.parser,
+    tags = frontend.tags,
+    filters = frontend.filters,
+    validateOptions = frontend.validateOptions,
+    onCompileError = frontend.onCompileError;
+
+  function getLocals(options) {
+    if (!options || !options.locals) {
+      return self.options.locals;
+    }
+    return utils.extend({}, self.options.locals, options.locals);
+  }
+
+  function cacheGet(key, options) {
+    return cache.cacheGet(key, options, self.options.cache, self.cache);
+  }
+
+  function cacheSet(key, options, val) {
+    cache.cacheSet(key, options, val, self.options.cache, self.cache);
+  }
+
+  function getParentsInternal(tokens, options) {
+    return exports.getParents(tokens, options, {
+      resolve: function (to, from) { return self.options.loader.resolve(to, from); },
+      parseFile: self.parseFile,
+      cacheGet: cacheGet
+    });
+  }
+
+  self.invalidateCache = function () {
+    if (self.options.cache === 'memory') {
+      self.cache = {};
+    }
+  };
+
+  self.setFilter = function (name, method) {
+    if (typeof method !== "function") {
+      throw new Error('Filter "' + name + '" is not a valid function.');
+    }
+    filters[name] = method;
+  };
+
+  self.setTag = function (name, parse, compile, ends, blockLevel) {
+    if (typeof parse !== 'function') {
+      throw new Error('Tag "' + name + '" parse method is not a valid function.');
+    }
+    if (typeof compile !== 'function') {
+      throw new Error('Tag "' + name + '" compile method is not a valid function.');
+    }
+    tags[name] = {
+      parse: parse,
+      compile: compile,
+      ends: ends || false,
+      block: !!blockLevel
+    };
+  };
+
+  self.setExtension = function (name, object) {
+    self.extensions[name] = object;
+  };
+
+  self.parse = function (source, options) {
+    validateOptions(options);
+
+    var locals = getLocals(options),
+      opts = {},
+      k;
+
+    for (k in options) {
+      if (options.hasOwnProperty(k) && k !== 'locals') {
+        opts[k] = options[k];
+      }
+    }
+
+    options = utils.extend({}, self.options, opts);
+    options.locals = locals;
+
+    return parser.parse(self, source, options, tags, filters);
+  };
+
+  self.parseFile = function (pathname, options) {
+    var src;
+
+    if (!options) {
+      options = {};
+    }
+
+    pathname = self.options.loader.resolve(pathname, options.resolveFrom);
+    src = self.options.loader.load(pathname);
+
+    if (!options.filename) {
+      options = utils.extend({ filename: pathname }, options);
+    }
+
+    return self.parse(src, options);
+  };
+
+  self.precompile = function (source, options) {
+    var tokens = self.parse(source, options),
+      parents = getParentsInternal(tokens, options),
+      tpl;
+
+    if (parents.length) {
+      tokens.tokens = exports.remapBlocks(tokens.blocks, parents[0].tokens);
+      exports.importNonBlocks(tokens.blocks, tokens.tokens);
+    }
+
+    try {
+      tpl = exports.buildTemplateFunction(tokens, parents, options);
+    } catch (e) {
+      onCompileError(e, options);
+    }
+
+    return { tpl: tpl, tokens: tokens };
+  };
+
+  self.compile = function (source, options) {
+    var key = options ? options.filename : null,
+      cached = key ? cacheGet(key, options) : null,
+      context,
+      contextLength,
+      pre;
+
+    if (cached) {
+      return cached;
+    }
+
+    context = getLocals(options);
+    contextLength = utils.keys(context).length;
+    pre = self.precompile(source, options);
+
+    function compiled(locals) {
+      var lcls;
+      if (locals && contextLength) {
+        lcls = utils.extend({}, context, locals);
+      } else if (locals && !contextLength) {
+        lcls = locals;
+      } else if (!locals && contextLength) {
+        lcls = context;
+      } else {
+        lcls = {};
+      }
+      return pre.tpl(self, lcls, filters, utils, efn);
+    }
+
+    utils.extend(compiled, pre.tokens);
+
+    if (key) {
+      cacheSet(key, options, compiled);
+    }
+
+    return compiled;
+  };
+
+  self.compileFile = function (pathname, options, cb) {
+    var src, cached;
+
+    if (!options) {
+      options = {};
+    }
+
+    pathname = self.options.loader.resolve(pathname, options.resolveFrom);
+    if (!options.filename) {
+      options = utils.extend({ filename: pathname }, options);
+    }
+    cached = cacheGet(pathname, options);
+
+    if (cached) {
+      if (cb) {
+        cb(null, cached);
+        return;
+      }
+      return cached;
+    }
+
+    if (cb) {
+      self.options.loader.load(pathname, function (err, src) {
+        if (err) {
+          cb(err);
+          return;
+        }
+        var compiled;
+
+        try {
+          compiled = self.compile(src, options);
+        } catch (err2) {
+          cb(err2);
+          return;
+        }
+
+        cb(err, compiled);
+      });
+      return;
+    }
+
+    src = self.options.loader.load(pathname);
+    return self.compile(src, options);
+  };
+
+  self.render = function (source, options) {
+    return self.compile(source, options)();
+  };
+
+  self.renderFile = function (pathName, locals, cb) {
+    if (cb) {
+      self.compileFile(pathName, {}, function (err, fn) {
+        var result;
+
+        if (err) {
+          cb(err);
+          return;
+        }
+
+        try {
+          result = fn(locals);
+        } catch (err2) {
+          cb(err2);
+          return;
+        }
+
+        cb(null, result);
+      });
+      return;
+    }
+
+    return self.compileFile(pathName)(locals);
+  };
+
+  self.run = function (tpl, locals, filepath) {
+    var context = getLocals({ locals: locals });
+    if (filepath) {
+      cacheSet(filepath, {}, tpl);
+    }
+    return tpl(self, context, filters, utils, efn);
+  };
+};