@rhinostone/swig-core 2.6.0 → 2.7.0

package/README.md

@@ -1,9 +1,9 @@
 @rhinostone/swig-core
 =====================
 
-[![NPM version](http://img.shields.io/npm/v/@rhinostone/swig-core.svg?style=flat)](https://www.npmjs.com/package/@rhinostone/swig-core) [![Socket Badge](https://socket.dev/api/badge/npm/package/@rhinostone/swig-core)](https://socket.dev/npm/package/@rhinostone/swig-core)
+[![NPM version](https://img.shields.io/npm/v/@rhinostone/swig-core.svg?style=flat)](https://www.npmjs.com/package/@rhinostone/swig-core) [![Socket Badge](https://socket.dev/api/badge/npm/package/@rhinostone/swig-core)](https://socket.dev/npm/package/@rhinostone/swig-core)
 
-> **Shared runtime** for the `@rhinostone/swig` family of template engines. Not intended for direct consumption unless you are building a custom frontend. Install [@rhinostone/swig](https://www.npmjs.com/package/@rhinostone/swig) for the default Swig (Jinja2/Django-inspired) flavor, [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig) for the Twig flavor, or [@rhinostone/swig-jinja2](https://www.npmjs.com/package/@rhinostone/swig-jinja2) for the Python Jinja2 flavor — they all pull this package in pinned to the matching version.
+> **Shared runtime** for the `@rhinostone/swig` family of template engines. Not intended for direct consumption unless you are building a custom frontend. Install [@rhinostone/swig](https://www.npmjs.com/package/@rhinostone/swig) for the default Swig (Jinja2/Django-inspired) flavor, [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig) for the Twig flavor, [@rhinostone/swig-jinja2](https://www.npmjs.com/package/@rhinostone/swig-jinja2) for the Python Jinja2 flavor, or [@rhinostone/swig-django](https://www.npmjs.com/package/@rhinostone/swig-django) for the Django flavor — they all pull this package in pinned to the matching version.
 
 Extracted from `@rhinostone/swig@1.6.0` during the `2.0.0-alpha.1` multi-flavor carve. See [ROADMAP.md](https://github.com/gina-io/swig/blob/develop/ROADMAP.md) for the release narrative.
 
@@ -22,6 +22,7 @@ Consumers
 * [@rhinostone/swig](https://www.npmjs.com/package/@rhinostone/swig) — default Swig flavor.
 * [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig) — Twig parity frontend.
 * [@rhinostone/swig-jinja2](https://www.npmjs.com/package/@rhinostone/swig-jinja2) — Python Jinja2 frontend.
+* [@rhinostone/swig-django](https://www.npmjs.com/package/@rhinostone/swig-django) — Django Template Language frontend.
 
 Versioning
 ----------

package/lib/backend.js

@@ -195,7 +195,20 @@ exports.compile = function (template, parents, options, blockName) {
         forBodyJS = '',
         ctxloopcache = ('_ctx.__loopcache' + Math.random()).replace(/\./g, ''),
         ctx = '_ctx.',
-        ctxloop = '_ctx.loop';
+        // Opt-in loop-context naming. A frontend may rename the loop
+        // variable (Django uses `forloop`), rename the counter fields, and
+        // expose the enclosing loop as `parentloop`. All three default to
+        // swig's own names, so an absent flag emits byte-identical JS — the
+        // native / Twig / Jinja2 frontends never set them and are untouched.
+        // The Django `for` tag sets all three on the IRFor node.
+        loopName = node.loopName || 'loop',
+        ctxloop = '_ctx.' + loopName,
+        loopFields = node.loopFields || {},
+        fIndex = loopFields.index || 'index',
+        fIndex0 = loopFields.index0 || 'index0',
+        fRevindex = loopFields.revindex || 'revindex',
+        fRevindex0 = loopFields.revindex0 || 'revindex0',
+        parentloopJS = node.loopParent ? ', parentloop: ' + ctxloopcache + '.' + loopName : '';
       if (node.iterable && typeof node.iterable === 'object' && typeof node.iterable.type === 'string') {
         forIterable = exports.emitExpr(node.iterable);
       } else {
@@ -226,18 +239,18 @@ exports.compile = function (template, parents, options, blockName) {
       out += '(function () {\n' +
         '  var __l = ' + forIterable + ', __len = (_utils.isArray(__l) || typeof __l === "string") ? __l.length : _utils.keys(__l).length;\n' +
         forEmptyCheck +
-        '    var ' + ctxloopcache + ' = { loop: ' + ctxloop + ', ' + forVal + ': ' + ctx + forVal + ', ' + forKey + ': ' + ctx + forKey + ' };\n' +
-        '    ' + ctxloop + ' = { first: false, index: 1, index0: 0, revindex: __len, revindex0: __len - 1, length: __len, last: false };\n' +
+        '    var ' + ctxloopcache + ' = { ' + loopName + ': ' + ctxloop + ', ' + forVal + ': ' + ctx + forVal + ', ' + forKey + ': ' + ctx + forKey + ' };\n' +
+        '    ' + ctxloop + ' = { first: false, ' + fIndex + ': 1, ' + fIndex0 + ': 0, ' + fRevindex + ': __len, ' + fRevindex0 + ': __len - 1, length: __len, last: false' + parentloopJS + ' };\n' +
         '  _utils.each(__l, function (' + forVal + ', ' + forKey + ') {\n' +
         '    ' + ctx + forVal + ' = ' + forVal + ';\n' +
         '    ' + ctx + forKey + ' = ' + forKey + ';\n' +
         '    ' + ctxloop + '.key = ' + forKey + ';\n' +
-        '    ' + ctxloop + '.first = (' + ctxloop + '.index0 === 0);\n' +
-        '    ' + ctxloop + '.last = (' + ctxloop + '.revindex0 === 0);\n' +
+        '    ' + ctxloop + '.first = (' + ctxloop + '.' + fIndex0 + ' === 0);\n' +
+        '    ' + ctxloop + '.last = (' + ctxloop + '.' + fRevindex0 + ' === 0);\n' +
         '    ' + forBodyJS +
-        '    ' + ctxloop + '.index += 1; ' + ctxloop + '.index0 += 1; ' + ctxloop + '.revindex -= 1; ' + ctxloop + '.revindex0 -= 1;\n' +
+        '    ' + ctxloop + '.' + fIndex + ' += 1; ' + ctxloop + '.' + fIndex0 + ' += 1; ' + ctxloop + '.' + fRevindex + ' -= 1; ' + ctxloop + '.' + fRevindex0 + ' -= 1;\n' +
         '  });\n' +
-        '  ' + ctxloop + ' = ' + ctxloopcache + '.loop;\n' +
+        '  ' + ctxloop + ' = ' + ctxloopcache + '.' + loopName + ';\n' +
         '  ' + ctx + forVal + ' = ' + ctxloopcache + '.' + forVal + ';\n' +
         '  ' + ctx + forKey + ' = ' + ctxloopcache + '.' + forKey + ';\n' +
         '  ' + ctxloopcache + ' = undefined;\n' +
@@ -781,6 +794,15 @@ function emitVarRef(node, d) {
   utils.each(node.path, function (segment) {
     checkDangerousSegment(segment, d, node);
   });
+  // Opt-in Django-style runtime resolution: dict / attribute / method
+  // lookup, numeric index access ({{ list.0 }}), and auto-call of callable
+  // leaves, via _utils.resolve. A frontend sets node.resolve; absent it,
+  // emit the unchanged static dot-path so the other flavors stay
+  // byte-identical. The parse-time _dangerousProps guard above still runs
+  // either way; _utils.resolve adds a matching runtime guard.
+  if (node.resolve) {
+    return '_utils.resolve(_ctx, ' + JSON.stringify(node.path) + ')';
+  }
   return checkMatchExpr(node.path);
 }
 

package/lib/ir.js

@@ -109,6 +109,14 @@
  * to a real {@link IRExpr}. Backends MUST tolerate both shapes — same
  * transitional widening as {@link IRSet}'s `target`.
  *
+ * `loopName` / `loopFields` / `loopParent` are opt-in flags a frontend
+ * sets to rename the loop-context object and its counter fields and to
+ * expose the enclosing loop. They default to swig's own names, so when a
+ * frontend leaves them unset the backend emits byte-identical JS (native /
+ * Twig / Jinja2 never set them). The Django frontend uses all three to
+ * surface `forloop` with `counter` / `counter0` / `revcounter` /
+ * `revcounter0` / `parentloop`.
+ *
  * @typedef {Object} IRFor
  * @property {'For'} type
  * @property {string} [key]                   Loop key var (second binding).
@@ -116,6 +124,9 @@
  * @property {IRExpr|string} iterable         Transitional — see note above.
  * @property {IRStatement[]} body
  * @property {IRStatement[]} [emptyBody]
+ * @property {string} [loopName]              Opt-in loop-context var name (default 'loop'; Django sets 'forloop').
+ * @property {Object} [loopFields]            Opt-in counter-field rename map ({index,index0,revindex,revindex0} → emit names); absent fields keep swig names.
+ * @property {boolean} [loopParent]           Opt-in: expose the enclosing loop as `<loopName>.parentloop` (Django forloop.parentloop).
  * @property {IRLoc} [loc]
  */
 

package/lib/utils.js

@@ -1,3 +1,5 @@
+var security = require('./security');
+
 var isArray;
 
 /**
@@ -311,3 +313,71 @@ exports.slice = function (obj, start, stop, step) {
 exports.coerceOutput = function (v) {
   return (v === null || v === undefined) ? '' : v;
 };
+
+/*!
+ * Resolve a single path segment against a value, Django-style. A plain
+ * property access (`obj[seg]`) covers dictionary, attribute, and array /
+ * string index lookup in one step (JS string-keys an array / string by a
+ * numeric segment, so `["a"][0]` and `["a"]["0"]` both yield the element).
+ * A callable leaf is auto-called with no arguments, bound to its receiver,
+ * honoring Django's opt-outs: `fn.alters_data === true` is not called and
+ * yields `undefined` (Django renders nothing for data-altering callables);
+ * `fn.do_not_call_in_templates === true` is returned uncalled. A call that
+ * throws (e.g. a method that needs arguments) yields `undefined`, mirroring
+ * Django's `string_if_invalid` fallback on a failed auto-call. The
+ * `_dangerousProps` segments are rejected at runtime as defense-in-depth.
+ * @private
+ */
+function resolveSeg(obj, seg) {
+  var val;
+  if (obj === null || obj === undefined) {
+    return undefined;
+  }
+  if (security.dangerousProps.indexOf(seg) !== -1) {
+    return undefined;
+  }
+  val = obj[seg];
+  if (typeof val === 'function') {
+    if (val.alters_data === true) {
+      return undefined;
+    }
+    if (val.do_not_call_in_templates === true) {
+      return val;
+    }
+    // Django auto-calls a callable leaf with no args and falls back to
+    // string_if_invalid ("") when the call raises; mirror that here.
+    try {
+      return val.call(obj);
+    } catch (e) {
+      return undefined;
+    }
+  }
+  return val;
+}
+
+/**
+ * Resolve a dotted path against a context object, Django-style — walk each
+ * segment through the per-segment lookup, short-circuiting to the missing
+ * value as soon as a segment resolves null / undefined. Powers the Django
+ * flavor's variable resolution (dict / attribute / method lookup, auto-call
+ * of callable leaves, `{{ list.0 }}` index access) when a frontend opts in
+ * via the `IRVarRef.resolve` flag. The raw resolved value (including null) is
+ * returned so downstream filters such as `default_if_none` see a real null;
+ * coercion to "" is deferred to the output drain (via `coerceOutput`).
+ *
+ * @param  {*}        obj   The root context (usually `_ctx`).
+ * @param  {string[]} path  Path segments.
+ * @return {*}              The resolved value, or null / undefined when a
+ *                          segment is missing.
+ */
+exports.resolve = function (obj, path) {
+  var cur = obj,
+    i;
+  for (i = 0; i < path.length; i += 1) {
+    cur = resolveSeg(cur, path[i]);
+    if (cur === null || cur === undefined) {
+      return cur;
+    }
+  }
+  return cur;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhinostone/swig-core",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Shared IR, backend, and runtime for the @rhinostone/swig family of template engines.",
   "keywords": [
     "template",