@rhinostone/swig-core 2.1.0 → 2.3.0

package/lib/engine.js

@@ -1,4 +1,5 @@
 var utils = require('./utils'),
+  ir = require('./ir'),
   backend = require('./backend'),
   cache = require('./cache');
 
@@ -79,6 +80,82 @@ exports.importNonBlocks = function (blocks, tokens) {
   });
 };
 
+/**
+ * Build an `IRExtendsDeferred` node from a parsed child template.
+ *
+ * Walks `tokens.blocks` (the parser's map of every block-level tag that
+ * appeared at top level — both `{% block %}` overrides and non-block
+ * preludes like `{% set %}`, `{% import %}`, `{% macro %}`) and:
+ *
+ *   - For each `{% block %}` token: invokes its `.compile(...)` with an
+ *     empty parents list to obtain an `IRBlock` (body is one `IRLegacyJS`
+ *     wrapping the recursively-compiled JS source — same shape sync mode
+ *     produces). The IRBlock is keyed under the block name in `childBlocks`.
+ *   - For each non-`block` block-level token: invokes its `.compile(...)`
+ *     and wraps any JS-string return in `IRLegacyJS`. The resulting IR
+ *     node is pushed onto `childIRs` (the prelude list).
+ *
+ * The backend's `IRExtendsDeferred` emit branch handles runtime parent
+ * resolution via `_swig.getTemplate` and the `_blocks` parameter contract
+ * (see `packages/swig-core/lib/backend.js`).
+ *
+ * `tokens.parent` is lifted into an `IRLiteral('string', …)` so the
+ * backend's `emitExpr` path produces a quoted JS string literal. The
+ * native parser stashes `tokens.parent` as the literal text of the
+ * extends argument after stripping enclosing quotes (lib/parser.js:273),
+ * which works for `{% extends "layout.html" %}` but for a bare
+ * identifier (`{% extends parent_var %}`) yields a pre-lowered JS
+ * source fragment such as `((typeof _ctx.parent_var !== "undefined")
+ * ? _ctx.parent_var : …)`. Embedded here as a string literal it
+ * becomes a garbage template lookup at runtime
+ * (`Template not found: /((typeof _ctx.parent_var …`). Closing the
+ * dynamic-extends gap requires the parser to stash an IRExpr on
+ * `tokens.parent` and this helper to lower it through
+ * `ir.extendsDeferred`'s `parentExpr` slot — already designed as
+ * `<IRExpr>` per the deferred IR contract.
+ *
+ * @param  {object} tokens   Parsed child template (must have `.parent`).
+ * @param  {object} options  Per-call Swig options; `options.filename` is
+ *                           used as the deferred resolveFrom.
+ * @return {object}          IRExtendsDeferred node.
+ * @private
+ */
+function buildExtendsDeferred(tokens, options) {
+  var childBlocks = {};
+  var childIRs = [];
+  utils.each(tokens.blocks, function (blockToken) {
+    var args = blockToken.args ? blockToken.args.slice(0) : [];
+    var content = blockToken.content ? blockToken.content.slice(0) : [];
+    if (blockToken.name === 'block') {
+      var blockName = args.join('');
+      var blockIR = blockToken.compile(backend.compile, args, content, [], options, blockName, blockToken);
+      if (blockIR && typeof blockIR === 'object' && typeof blockIR.type === 'string') {
+        childBlocks[blockName] = blockIR;
+      }
+      return;
+    }
+    var result = blockToken.compile(backend.compile, args, content, [], options, undefined, blockToken);
+    if (result === undefined || result === null || result === '') { return; }
+    if (typeof result === 'string') {
+      childIRs.push(ir.legacyJS(result));
+      return;
+    }
+    if (utils.isArray(result)) {
+      utils.each(result, function (n) { childIRs.push(n); });
+      return;
+    }
+    if (typeof result === 'object' && typeof result.type === 'string') {
+      childIRs.push(result);
+    }
+  });
+  return ir.extendsDeferred(
+    ir.literal('string', tokens.parent),
+    childBlocks,
+    childIRs,
+    options.filename || ''
+  );
+}
+
 /**
  * Walk a template's `extends` chain and build the parent token tree.
  * Detects circular inheritance.
@@ -307,12 +384,24 @@ exports.install = function (self, frontend) {
 
   self.precompile = function (source, options) {
     var tokens = self.parse(source, options),
-      parents = getParentsInternal(tokens, options),
+      parents,
       tpl;
 
-    if (parents.length) {
-      tokens.tokens = exports.remapBlocks(tokens.blocks, parents[0].tokens);
-      exports.importNonBlocks(tokens.blocks, tokens.tokens);
+    if (options && options.codegenMode === 'async' && tokens.parent) {
+      // Async extends — defer parent walking and block remapping to
+      // runtime via the IRExtendsDeferred emit branch in backend.js.
+      // The deferred node carries the child's blocks + non-block
+      // preludes; the backend resolves the parent via _swig.getTemplate
+      // and threads block overrides through the _blocks parameter
+      // contract.
+      parents = [];
+      tokens.tokens = [buildExtendsDeferred(tokens, options)];
+    } else {
+      parents = getParentsInternal(tokens, options);
+      if (parents.length) {
+        tokens.tokens = exports.remapBlocks(tokens.blocks, parents[0].tokens);
+        exports.importNonBlocks(tokens.blocks, tokens.tokens);
+      }
     }
 
     try {
@@ -497,6 +586,18 @@ exports.install = function (self, frontend) {
 
   self.renderFile = function (pathName, locals, cb) {
     if (cb) {
+      // Async loader opt-in: route through getTemplate when
+      // loader.async === true. Explicit flag only — load.length is
+      // not a dispatch signal (the built-in fs + memory loaders are
+      // dual-mode with length 2 and must keep the sync-cb path).
+      if (self.options.loader && self.options.loader.async === true) {
+        self.getTemplate(pathName)
+          .then(function (fn) { return fn(locals); })
+          .then(function (result) { cb(null, result.output); })
+          .catch(cb);
+        return;
+      }
+
       self.compileFile(pathName, {}, function (err, fn) {
         var result;
 

package/lib/ir.js

@@ -1,14 +1,14 @@
 /**
  * Swig IR — intermediate representation for the shared backend.
  *
- * Phase 1: typedef stubs only. No runtime code here — Phase 1 keeps the
- * native frontend emitting JS source directly. Phase 2 ports the native
- * frontend to emit IR, at which point `@rhinostone/swig-core/lib/backend.js`
- * walks an IRTemplate and produces the compiled `new Function(...)` body.
+ * Two halves: the `@typedef` schema for every IR node shape, and the
+ * runtime factories (further down) that build them. Every frontend
+ * (native Swig, Twig, and future flavors) lowers its parse tree into
+ * these shapes; `@rhinostone/swig-core/lib/backend.js` then walks an
+ * IRTemplate and produces the compiled `new Function(...)` body.
  *
- * Every frontend (native Swig, Twig, Jinja2, Django) must lower its
- * parse tree into these shapes. Constructs that cannot lower cleanly
- * must throw at parse time — no silent partial behavior.
+ * Constructs that cannot lower cleanly must throw at parse time — no
+ * silent partial behavior.
  */
 
 /**
@@ -103,11 +103,17 @@
 /**
  * For-loop. `emptyBody` supports Twig/Django `{% for … %}{% else %}`.
  *
+ * `iterable` is typed `IRExpr | string` for Phase 2 — the native
+ * frontend still hands in a raw JS-source string (its `for` tag has
+ * not migrated to expression-level IR), while the Twig frontend lowers
+ * to a real {@link IRExpr}. Backends MUST tolerate both shapes — same
+ * transitional widening as {@link IRSet}'s `target`.
+ *
  * @typedef {Object} IRFor
  * @property {'For'} type
  * @property {string} [key]                   Loop key var (second binding).
  * @property {string} value                   Loop value var (first binding).
- * @property {IRExpr} iterable
+ * @property {IRExpr|string} iterable         Transitional — see note above.
  * @property {IRStatement[]} body
  * @property {IRStatement[]} [emptyBody]
  * @property {IRLoc} [loc]
@@ -279,12 +285,13 @@
  * In sync codegen mode the parser pre-resolves `extends` / `include` /
  * `import` / Twig `from` paths via `swig.parseFile(...)` and inlines
  * the resolved tokens at parse-finalization time. That model can't run
- * against an async-only loader (S3 / Redis / fetch-backed), and it
+ * against an async-only loader (S3 / Redis / network-backed), and it
  * can't handle dynamic paths (`{% extends parent_var %}`) since the
  * value isn't known until render.
  *
  * The deferred shapes carry the unresolved path expression to render
- * time. The async backend (`compileAsync`) emits cb-shaped or
+ * time. In async codegen mode (`backend.compile` with
+ * `options.codegenMode === 'async'`) the backend emits cb-shaped or
  * AsyncFunction-shaped JS that hits a runtime `_swig.getTemplate(...)`
  * call to resolve and apply the parent / included / imported template.
  *
@@ -511,7 +518,7 @@
  */
 
 /* ------------------------------------------------------------------ *
- * Runtime node factories — Phase 2 scaffold (Session 7, 2026-04-14).
+ * Runtime node factories.
  *
  * Each factory returns a plain JSON-serialisable object matching one
  * of the typedefs above. `loc` is always optional; when omitted it is
@@ -519,9 +526,8 @@
  * `'loc' in node`). All other parameters are required unless documented
  * otherwise on the corresponding typedef.
  *
- * No consumers yet — this commit introduces the schema surface only.
- * Subsequent sessions will migrate the native frontend's token-tree
- * production over to these shapes.
+ * Consumed by every frontend's tag handlers and `tokenparser.js` (which
+ * build the IR) and by `backend.js` (which walks it).
  * ------------------------------------------------------------------ */
 
 /*!

package/package.json

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