@rhinostone/swig-twig 2.0.0-alpha.3 → 2.0.0-alpha.5

package/lib/index.js

@@ -1,66 +1,221 @@
 /**
  * @rhinostone/swig-twig — Twig frontend for the @rhinostone/swig family.
  *
- * Phase 3 scaffold. Subsequent commits add the Twig lexer + parser
- * (source → IR), the Twig filter parity catalog, and the per-flavor
- * tag set. Source-to-IR lowering targets the swig-core IR schema
- * defined in @rhinostone/swig-core/lib/ir; built-in Twig tags lower at
- * parse time rather than registering through the runtime setTag
- * extension point.
+ * Phase 3 Session 17: end-to-end render wiring (Path A). The package now
+ * exposes a Twig constructor + default instance via `engine.install(self,
+ * frontend)` from @rhinostone/swig-core, so callers can `render(source,
+ * locals)` / `renderFile(path, locals, cb)` directly against Twig syntax.
  *
- * See .claude/architecture/multi-flavor-ir.md § Phase 3 for the
- * per-flavor split decision and migration sequence.
+ * See .claude/architecture/multi-flavor-ir.md § Phase 3 for the per-flavor
+ * split decision.
  */
 
+var utils = require('@rhinostone/swig-core/lib/utils'),
+  engine = require('@rhinostone/swig-core/lib/engine'),
+  loaders = require('@rhinostone/swig-core/lib/loaders'),
+  dateformatter = require('@rhinostone/swig-core/lib/dateformatter'),
+  parser = require('./parser'),
+  _tags = require('./tags'),
+  _filters = require('./filters'),
+  _tests = require('./tests');
+
 exports.name = 'twig';
 
 /**
  * Expression-level parser — Pratt-style recursive descent that consumes
  * Twig lexer tokens and returns swig-core IRExpr nodes.
  *
- * Exposed here so callers can import it from the package entry-point;
- * NOT wired into parse(source) yet (that still throws).
- *
  * @type {object}
  */
-exports.parser = require('./parser');
+exports.parser = parser;
 
 /**
- * Built-in Twig tag registry. See `./tags/index.js` for the per-tag shape.
+ * Built-in Twig tag registry.
  *
  * @type {object}
  */
-exports.tags = require('./tags');
+exports.tags = _tags;
 
 /**
- * Built-in Twig filter catalog. See `./filters.js` for the per-filter shape.
+ * Built-in Twig filter catalog.
  *
- * Shipped as the Twig frontend's `_filters` runtime map and `setFilter`
- * mutation target via `engine.install(self, frontend)`. Filters marked
- * `.safe = true` suppress the autoescape `e` tail injected by
- * `parseVariable`. Only `raw` carries `.safe = true` this session.
+ * @type {object}
+ */
+exports.filters = _filters;
+
+/**
+ * Template loaders re-exported from swig-core.
  *
  * @type {object}
  */
-exports.filters = require('./filters');
+exports.loaders = loaders;
+
+var defaultOptions = {
+    autoescape: true,
+    varControls: ['{{', '}}'],
+    tagControls: ['{%', '%}'],
+    cmtControls: ['{#', '#}'],
+    locals: {},
+    cache: 'memory',
+    loader: loaders.fs()
+  },
+  defaultInstance;
+
+/**
+ * Validate the Twig options object.
+ *
+ * @param  {?object} options Twig options object.
+ * @return {undefined}      Throws on malformed input.
+ * @private
+ */
+function validateOptions(options) {
+  if (!options) {
+    return;
+  }
+
+  utils.each(['varControls', 'tagControls', 'cmtControls'], function (key) {
+    if (!options.hasOwnProperty(key)) {
+      return;
+    }
+    if (!utils.isArray(options[key]) || options[key].length !== 2) {
+      throw new Error('Option "' + key + '" must be an array containing 2 different control strings.');
+    }
+    if (options[key][0] === options[key][1]) {
+      throw new Error('Option "' + key + '" open and close controls must not be the same.');
+    }
+    utils.each(options[key], function (a, i) {
+      if (a.length < 2) {
+        throw new Error('Option "' + key + '" ' + ((i) ? 'open ' : 'close ') + 'control must be at least 2 characters. Saw "' + a + '" instead.');
+      }
+    });
+  });
+
+  if (options.hasOwnProperty('cache')) {
+    if (options.cache && options.cache !== 'memory') {
+      if (!options.cache.get || !options.cache.set) {
+        throw new Error('Invalid cache option ' + JSON.stringify(options.cache) + ' found. Expected "memory" or { get: function (key) { ... }, set: function (key, value) { ... } }.');
+      }
+    }
+  }
+  if (options.hasOwnProperty('loader')) {
+    if (options.loader) {
+      if (!options.loader.load || !options.loader.resolve) {
+        throw new Error('Invalid loader option ' + JSON.stringify(options.loader) + ' found. Expected { load: function (pathname, cb) { ... }, resolve: function (to, from) { ... } }.');
+      }
+    }
+  }
+}
+
+/**
+ * Set defaults for the base and all new Twig environments.
+ *
+ * @param  {object} [options={}] Twig options object.
+ * @return {undefined}
+ */
+exports.setDefaults = function (options) {
+  validateOptions(options);
+  defaultInstance.options = utils.extend(defaultInstance.options, options);
+};
+
+/**
+ * Set the default TimeZone offset for date formatting via the date filter.
+ * Mutates the shared dateformatter's tzOffset — affects every frontend
+ * (native swig + swig-twig) because both consume the same module instance.
+ *
+ * @param  {number} offset Offset from GMT, in minutes (west of GMT).
+ * @return {undefined}
+ */
+exports.setDefaultTZOffset = function (offset) {
+  dateformatter.tzOffset = offset;
+};
+
+/**
+ * Create a new, separate Twig compile/render environment.
+ *
+ * @example
+ * var twig = require('@rhinostone/swig-twig');
+ * var mytwig = new twig.Twig({ autoescape: false });
+ * mytwig.render('Hello {{ name }}', { locals: { name: 'world' }});
+ *
+ * @param  {object} [opts={}] Twig options object.
+ * @return {object}           New Twig environment.
+ */
+exports.Twig = function (opts) {
+  var self = this;
+  validateOptions(opts);
+  this.options = utils.extend({}, defaultOptions, opts || {});
+  this.cache = {};
+  this.extensions = {};
+
+  engine.install(this, {
+    parser: parser,
+    tags: _tags,
+    filters: _filters,
+    validateOptions: validateOptions,
+    onCompileError: function (err, options) {
+      utils.throwError(err, null, options.filename);
+    }
+  });
+
+  // Register Twig `is <name>` runtime helpers as `_ext._test_<name>`. The
+  // parser lowers `foo is odd` to a two-segment VarRef + FnCall pointing
+  // at this slot, so the helpers must be installed on every Twig
+  // instance (including the default one). `setExtension` attaches to the
+  // per-instance `extensions` map — consumers can still override a test
+  // with their own `setExtension('_test_<name>', fn)` after construction.
+  utils.each(_tests, function (fn, name) {
+    self.setExtension('_test_' + name, fn);
+  });
+};
+
+/*!
+ * Export methods publicly via the default instance.
+ */
+defaultInstance = new exports.Twig();
+exports.setFilter = defaultInstance.setFilter;
+exports.setTag = defaultInstance.setTag;
+exports.setExtension = defaultInstance.setExtension;
+exports.parseFile = defaultInstance.parseFile;
+exports.precompile = defaultInstance.precompile;
+exports.compile = defaultInstance.compile;
+exports.compileFile = defaultInstance.compileFile;
+exports.render = defaultInstance.render;
+exports.renderFile = defaultInstance.renderFile;
+exports.run = defaultInstance.run;
+exports.invalidateCache = defaultInstance.invalidateCache;
+
+/**
+ * Express 3/4 compatibility alias.
+ *
+ * @example
+ * app.engine('twig', require('@rhinostone/swig-twig').__express);
+ * app.set('view engine', 'twig');
+ */
+exports.__express = defaultInstance.renderFile;
+
+var _parseDeprecationWarned = false;
 
 /**
  * Parse a Twig source string into the parse-tree shape consumed by
  * swig-core's `engine.compile`: `{ name, parent, tokens, blocks }`.
  *
- * Convenience wrapper around `exports.parser.parse(swig, source, options,
- * tags, filters)` — defaults `tags` to the built-in Twig registry and
- * `filters` to an empty map. Callers wiring Twig as a frontend through
- * `engine.install(self, frontend)` should call `exports.parser.parse`
- * directly so the engine's own filter and tag maps flow through.
+ * @deprecated since 2.0.0-alpha.4 — use `new exports.Twig(opts)` and the
+ * per-instance `precompile` / `compile` / `render` surface installed by
+ * `engine.install`. Slated for removal in `2.0.0` stable. The full-instance
+ * path uses closure-captured tag/filter maps and honors `setFilter` /
+ * `setTag` overrides; this Path B wrapper does not.
  *
  * @param  {string} source     Twig template source.
- * @param  {object} [options]  Per-call frontend options
- *                             (`autoescape`, `varControls`, `tagControls`,
- *                             `cmtControls`, `filename`, `tags`, `filters`).
+ * @param  {object} [options]  Per-call options.
  * @return {object}            `{ name, parent, tokens, blocks }`.
  */
 exports.parse = function (source, options) {
+  if (!_parseDeprecationWarned) {
+    _parseDeprecationWarned = true;
+    if (typeof console !== 'undefined' && console.warn) {
+      console.warn('[@rhinostone/swig-twig] exports.parse is deprecated and will be removed in 2.0.0. Use `new twig.Twig(opts)` and the per-instance precompile/compile/render API instead.');
+    }
+  }
   options = options || {};
   var tags = options.tags || exports.tags;
   var filters = options.filters || exports.filters;

package/lib/parser.js

@@ -302,11 +302,11 @@ exports.parseExpr = function (tokens, filters, _posOut) {
     var m;
     switch (tok.type) {
     case _t.STRING:
-      return ir.literal('string', unquoteString(tok.match));
+      return parsePostfix(ir.literal('string', unquoteString(tok.match)));
     case _t.NUMBER:
-      return ir.literal('number', parseFloat(tok.match));
+      return parsePostfix(ir.literal('number', parseFloat(tok.match)));
     case _t.BOOL:
-      return ir.literal('bool', tok.match === 'true');
+      return parsePostfix(ir.literal('bool', tok.match === 'true'));
     case _t.NOT:
       return ir.unaryOp('!', parseUnary());
     case _t.OPERATOR:
@@ -371,13 +371,29 @@ exports.parseExpr = function (tokens, filters, _posOut) {
       // parses as `(foo is defined) and bar`.
       if (info.op === 'is' || info.op === 'is not') {
         var test = parseTest();
-        var testCall = ir.fnCall(ir.varRef(['_test_' + test.name]), [left].concat(test.args));
+        var testCall;
+        // VarRef subjects coerce null/undefined to "" through checkMatchExpr
+        // in emitVarRef, which loses the defined/undefined signal that
+        // `is defined` / `is null` need. Route both through IRVarRefExists
+        // (same shape as the `??` fallback from C3) so a path that is
+        // actually undefined or null yields the right boolean instead of
+        // being compared against the coerced "" placeholder. Non-VarRef
+        // subjects (Literal, BinaryOp, FnCall, FilterCall) evaluate to a
+        // concrete value with no coercion, so they fall through to the
+        // generic `_ext._test_<name>` helper path registered by the engine.
+        if (test.args.length === 0 && left.type === 'VarRef' && test.name === 'defined') {
+          testCall = ir.varRefExists(left.path, left.loc);
+        } else if (test.args.length === 0 && left.type === 'VarRef' && test.name === 'null') {
+          testCall = ir.unaryOp('!', ir.varRefExists(left.path, left.loc));
+        } else {
+          testCall = ir.fnCall(ir.varRef(['_ext', '_test_' + test.name]), [left].concat(test.args));
+        }
         left = info.op === 'is not' ? ir.unaryOp('!', testCall) : testCall;
         continue;
       }
       var right = parseExpression(info.prec + 1);
       if (info.op === '..') {
-        left = ir.fnCall(ir.varRef(['_range']), [left, right]);
+        left = ir.fnCall(ir.varRef(['_utils', 'range']), [left, right]);
       } else {
         left = ir.binaryOp(info.op, left, right);
       }

package/lib/tests/index.js

@@ -0,0 +1,109 @@
+/**
+ * @rhinostone/swig-twig — built-in test runtime helpers.
+ *
+ * Twig `is <name>` / `is not <name>` expressions lower to
+ * `_ext._test_<name>(subject, ...args)` at the IR layer. The Twig
+ * constructor registers each export here via `self.setExtension('_test_'
+ * + name, fn)`, which installs the helper onto the per-instance
+ * `_swig.extensions` map — so Path A (`new Twig().render(...)`) honors
+ * per-instance overrides without leaking cross-instance.
+ *
+ * Two tests (`defined`, `null`) are additionally special-cased in the
+ * Twig parser when the subject is a VarRef with no args: both route
+ * through IRVarRefExists to preserve the defined/undefined signal that
+ * `emitVarRef` coerces to "". The helpers below still run for non-VarRef
+ * subjects (literals, BinaryOp, FnCall) where the coercion isn't in
+ * play. See packages/swig-twig/lib/parser.js `parseExpression` IS/ISNOT
+ * branch for the special-case logic.
+ */
+
+function isNumber(v) {
+  return typeof v === 'number' && !isNaN(v);
+}
+
+/**
+ * `foo is defined` — true when the subject is not `undefined`. The
+ * VarRef-subject path bypasses this helper and uses IRVarRefExists.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['defined'] = function (v) {
+  return typeof v !== 'undefined';
+};
+
+/**
+ * `foo is null` — true when the subject is `null` or `undefined`. The
+ * VarRef-subject path bypasses this helper and uses `!IRVarRefExists`.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['null'] = function (v) {
+  return v === null || typeof v === 'undefined';
+};
+
+/**
+ * `foo is empty` — true for `null`, `undefined`, `""`, empty arrays,
+ * and objects with no own-enumerable keys.
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['empty'] = function (v) {
+  if (v === null || typeof v === 'undefined') { return true; }
+  if (typeof v === 'string') { return v.length === 0; }
+  if (Object.prototype.toString.call(v) === '[object Array]') { return v.length === 0; }
+  if (typeof v === 'object') {
+    for (var k in v) {
+      if (Object.prototype.hasOwnProperty.call(v, k)) { return false; }
+    }
+    return true;
+  }
+  return false;
+};
+
+/**
+ * `foo is iterable` — true for arrays and non-null objects (mirrors
+ * Twig's rule that dicts iterate by key).
+ *
+ * @param  {*} v
+ * @return {boolean}
+ */
+exports['iterable'] = function (v) {
+  if (v === null || typeof v === 'undefined') { return false; }
+  if (Object.prototype.toString.call(v) === '[object Array]') { return true; }
+  return typeof v === 'object';
+};
+
+/**
+ * `n is odd` — true for numbers whose remainder mod 2 is non-zero.
+ *
+ * @param  {number} v
+ * @return {boolean}
+ */
+exports['odd'] = function (v) {
+  return isNumber(v) && v % 2 !== 0;
+};
+
+/**
+ * `n is even` — true for numbers whose remainder mod 2 is zero.
+ *
+ * @param  {number} v
+ * @return {boolean}
+ */
+exports['even'] = function (v) {
+  return isNumber(v) && v % 2 === 0;
+};
+
+/**
+ * `n is divisibleby(m)` — true when `m` is a non-zero number and `n % m
+ * === 0`. Twig's canonical name for the test.
+ *
+ * @param  {number} v
+ * @param  {number} n
+ * @return {boolean}
+ */
+exports['divisibleby'] = function (v, n) {
+  return isNumber(v) && isNumber(n) && n !== 0 && v % n === 0;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhinostone/swig-twig",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.5",
   "description": "Twig frontend for the @rhinostone/swig-core template engine. Phase 3 of the multi-flavor architecture (see @rhinostone/swig #T16).",
   "keywords": [
     "template",
@@ -22,7 +22,7 @@
     "node": ">=12"
   },
   "peerDependencies": {
-    "@rhinostone/swig-core": "2.0.0-alpha.3"
+    "@rhinostone/swig-core": "2.0.0-alpha.5"
   },
   "publishConfig": {
     "access": "public"