@rhinostone/swig-core 2.0.1 → 2.2.0

package/lib/backend.js

@@ -273,6 +273,19 @@ exports.compile = function (template, parents, options, blockName) {
         '  return _output;\n' +
         '};\n' +
         '_ctx.' + node.name + '.safe = true;\n';
+      // Phase 3 (#T22): async-codegen mirrors the macro into _exports so
+      // {% import %} / Twig's {% from %} can bind macros across templates
+      // at runtime. The macro's closure still references _ctx (not
+      // _exports) for outer-ctx lookups — sync-semantics-preserving.
+      // Top-level filter is implicit: the existing macro body walker
+      // (above) only handles Text/Raw/LegacyJS children, so nested
+      // IRMacro never reaches this branch.
+      if (options && options.codegenMode === 'async') {
+        if (_security.dangerousProps.indexOf(node.name) !== -1) {
+          throw new Error('Macro name "' + node.name + '" is reserved.');
+        }
+        out += '_exports.' + node.name + ' = _ctx.' + node.name + ';\n';
+      }
       return;
     }
     if (node.type === 'Parent') {
@@ -295,6 +308,33 @@ exports.compile = function (template, parents, options, blockName) {
       // block, its body carries whichever generation's content is active.
       // Emit the body verbatim; the block name is carried as metadata for
       // downstream tooling (parent-chain walks happen in the parent tag).
+      //
+      // Phase 3 (#T22) async mode: block remapping happens at runtime
+      // instead of parse time. When _blocks is supplied (by an extending
+      // child via IRExtendsDeferred-emitted `_parent(_ctx, _mergedBlocks)`)
+      // and contains an override for this block name, call the override
+      // async fn and append its return string. Otherwise emit the parent's
+      // own body inline as the default (matches sync behavior). The
+      // override fn closes over the calling template's own _swig / _filters
+      // / _utils / _ext, since it was constructed inside that template's
+      // body wrapper — it does NOT see this template's local _output, which
+      // is correct (the override returns its own string and the outer
+      // _output += await ... appends it here).
+      if (options && options.codegenMode === 'async') {
+        var blockNameJS = JSON.stringify(node.name);
+        out += 'if (_blocks && _blocks[' + blockNameJS + ']) {\n';
+        out += '  _output += await _blocks[' + blockNameJS + '](_ctx);\n';
+        out += '} else {\n';
+        utils.each(node.body, function (b) {
+          if (b.type === 'LegacyJS') { out += b.js; return; }
+          if (b.type === 'Text' || b.type === 'Raw') {
+            out += '_output += "' + escapeTextValue(b.value) + '";\n';
+            return;
+          }
+        });
+        out += '}\n';
+        return;
+      }
       utils.each(node.body, function (b) {
         if (b.type === 'LegacyJS') { out += b.js; return; }
         if (b.type === 'Text' || b.type === 'Raw') {
@@ -343,6 +383,157 @@ exports.compile = function (template, parents, options, blockName) {
         (node.ignoreMissing ? '} catch (e) {}\n' : '');
       return;
     }
+    if (node.type === 'IncludeDeferred') {
+      // Phase 3 (#T22): async-codegen counterpart to Include. Resolves the
+      // path via `_swig.getTemplate(...)` at render time (Promise<TemplateFn>),
+      // then awaits the resolved template fn's call. The double-await flows
+      // correctly whether the loaded tpl is sync (returns string) or async-
+      // compiled (returns Promise<string>) — `await <non-Promise>` resolves
+      // to the value unchanged. Mirrors the Include branch's path/context/
+      // isolated/ignoreMissing dispatch; only the runtime call shape differs.
+      var incdPathJS, incdCtxJS;
+      if (node.path && typeof node.path === 'object' && typeof node.path.type === 'string') {
+        incdPathJS = exports.emitExpr(node.path);
+      } else {
+        incdPathJS = node.path;
+      }
+      if (node.context !== undefined) {
+        if (typeof node.context === 'object' && typeof node.context.type === 'string') {
+          incdCtxJS = exports.emitExpr(node.context);
+        } else {
+          incdCtxJS = node.context;
+        }
+      }
+      var incdSelector;
+      if (node.isolated && incdCtxJS) {
+        incdSelector = incdCtxJS;
+      } else if (!incdCtxJS) {
+        incdSelector = '_ctx';
+      } else {
+        incdSelector = '_utils.extend({}, _ctx, ' + incdCtxJS + ')';
+      }
+      var incdOpts = '{resolveFrom: "' + (node.resolveFrom || '') + '"}';
+      out += (node.ignoreMissing ? '  try {\n' : '') +
+        '_output += (await (await _swig.getTemplate(' + incdPathJS + ', ' + incdOpts + '))(' + incdSelector + ')).output;\n' +
+        (node.ignoreMissing ? '} catch (e) {}\n' : '');
+      return;
+    }
+    if (node.type === 'ImportDeferred') {
+      // Phase 3 (#T22): async-codegen counterpart to the parse-time
+      // import flow. The imported template is loaded via _swig.getTemplate
+      // and called with the parent's _ctx so its body's compiled JS
+      // closes over outer-ctx vars (sync-semantics-preserving). Only
+      // the resolved value's `.exports` is bound; the imported body's
+      // `.output` is discarded — import doesn't render.
+      if (_security.dangerousProps.indexOf(node.alias) !== -1) {
+        throw new Error('Import alias "' + node.alias + '" is reserved.');
+      }
+      var impdPathJS;
+      if (node.path && typeof node.path === 'object' && typeof node.path.type === 'string') {
+        impdPathJS = exports.emitExpr(node.path);
+      } else {
+        impdPathJS = node.path;
+      }
+      var impdOpts = '{resolveFrom: "' + (node.resolveFrom || '') + '"}';
+      out += '_ctx.' + node.alias + ' = (await (await _swig.getTemplate(' + impdPathJS + ', ' + impdOpts + '))(_ctx)).exports;\n';
+      return;
+    }
+    if (node.type === 'FromImportDeferred') {
+      // Phase 3 (#T22): async-codegen counterpart to Twig's `{% from
+      // "file" import a, b as c %}`. Single getTemplate call, then
+      // per-entry bind onto _ctx. Async IIFE keeps `_imp` local so
+      // multiple from-imports in the same template don't collide.
+      var fromdImports = node.imports || [];
+      utils.each(fromdImports, function (entry) {
+        if (_security.dangerousProps.indexOf(entry.name) !== -1) {
+          throw new Error('From-import name "' + entry.name + '" is reserved.');
+        }
+        var bindName = entry.alias || entry.name;
+        if (_security.dangerousProps.indexOf(bindName) !== -1) {
+          throw new Error('From-import binding "' + bindName + '" is reserved.');
+        }
+      });
+      var fromdPathJS;
+      if (node.path && typeof node.path === 'object' && typeof node.path.type === 'string') {
+        fromdPathJS = exports.emitExpr(node.path);
+      } else {
+        fromdPathJS = node.path;
+      }
+      var fromdOpts = '{resolveFrom: "' + (node.resolveFrom || '') + '"}';
+      var fromdBindings = '';
+      utils.each(fromdImports, function (entry) {
+        var bindName = entry.alias || entry.name;
+        fromdBindings += '  _ctx.' + bindName + ' = _imp["' + entry.name + '"];\n';
+      });
+      out += 'await (async function () {\n' +
+        '  var _imp = (await (await _swig.getTemplate(' + fromdPathJS + ', ' + fromdOpts + '))(_ctx)).exports;\n' +
+        fromdBindings +
+        '})();\n';
+      return;
+    }
+    if (node.type === 'ExtendsDeferred') {
+      // Phase 3 (#T22): async-codegen counterpart to engine.getParents +
+      // engine.precompile's parse-time block remap. Inverts at runtime
+      // via the _blocks parameter contract:
+      //
+      //   1. childIRs preludes (set / import / macros) emit via recursive
+      //      backend.compile so they populate _ctx and _exports with the
+      //      child's own bindings before the parent runs.
+      //   2. Build _localChildBlocks — each block in node.childBlocks
+      //      becomes an `async function (_ctx) -> Promise<string>` that
+      //      shadows _output to a local accumulator and returns it. The
+      //      block body uses the same shallow Text/Raw/LegacyJS walker as
+      //      the IRBlock branch above.
+      //   3. Merge: _mergedBlocks = _utils.extend({}, _localChildBlocks,
+      //      _blocks || {}). Inherited overrides from a deeper child win
+      //      per "child blocks override parent's wholesale per name"
+      //      (matches sync's remapBlocks). Multi-level chain (child →
+      //      middle → grandparent) propagates correctly: middle merges
+      //      its own block bodies with the inherited child overrides,
+      //      and grandparent sees the merged map.
+      //   4. Resolve parent via _swig.getTemplate (Promise<TemplateFn>),
+      //      then await _parent(_ctx, _mergedBlocks). Parent's body's
+      //      IRBlock branch consults _mergedBlocks and uses overrides
+      //      where present, defaults otherwise.
+      //   5. _output = _parentResult.output. Parent's _exports is
+      //      DISCARDED — _exports stays as the child's own preludes-
+      //      populated map. Matches sync where {% import "child" %}
+      //      exposes child's own top-level macros only and never
+      //      traverses extends. One semantic across sync and async.
+      if (node.childIRs && node.childIRs.length) {
+        out += exports.compile(node.childIRs, parents, options);
+      }
+      out += 'var _localChildBlocks = {};\n';
+      if (node.childBlocks) {
+        utils.each(node.childBlocks, function (block, name) {
+          var blockBodyJS = '';
+          utils.each(block.body, function (b) {
+            if (b.type === 'LegacyJS') { blockBodyJS += b.js; return; }
+            if (b.type === 'Text' || b.type === 'Raw') {
+              blockBodyJS += '_output += "' + escapeTextValue(b.value) + '";\n';
+              return;
+            }
+          });
+          out += '_localChildBlocks[' + JSON.stringify(name) + '] = async function (_ctx) {\n' +
+            '  var _output = "";\n' +
+            blockBodyJS +
+            '  return _output;\n' +
+            '};\n';
+        });
+      }
+      out += 'var _mergedBlocks = _utils.extend({}, _localChildBlocks, _blocks || {});\n';
+      var extPathJS;
+      if (node.path && typeof node.path === 'object' && typeof node.path.type === 'string') {
+        extPathJS = exports.emitExpr(node.path);
+      } else {
+        extPathJS = node.path;
+      }
+      var extOpts = '{resolveFrom: "' + (node.resolveFrom || '') + '"}';
+      out += 'var _parentTpl = await _swig.getTemplate(' + extPathJS + ', ' + extOpts + ');\n';
+      out += 'var _parentResult = await _parentTpl(_ctx, _mergedBlocks);\n';
+      out += '_output = _parentResult.output;\n';
+      return;
+    }
     if (node.type === 'With') {
       // Phase 3 Session 12: scoped-context region (Twig's `{% with %}`).
       // Emits an IIFE that shadows `_ctx` for the body's lexical scope;
@@ -606,20 +797,19 @@ function checkDotExpr(path, ctxPrefix) {
 }
 
 /*!
- * Replica of `TokenParser.prototype.checkMatch`. Kept as a local private
- * helper rather than imported from tokenparser.js because (a) it is a
- * pure function of its argument and (b) the backend must not acquire a
- * runtime dependency on the TokenParser module (which is a specific
+ * Build the dot-path emit. `(checkDot_ctx ? _ctx.<path> : (checkDot_closure
+ * ? <path> : ""))` — checks the `_ctx.<path>` walk first, falls back to a
+ * bare-closure walk (covers macro params, host-globals like `Math`), and
+ * coerces a missing path to `""` for safe interpolation. Kept as a local
+ * private helper rather than imported from tokenparser.js because (a) it
+ * is a pure function of its argument and (b) the backend must not acquire
+ * a runtime dependency on the TokenParser module (which is a specific
  * frontend concern, not a shared-backend one). @private
  */
 function checkMatchExpr(match) {
-  var result;
-
-  function buildDot(ctx) {
-    return '(' + checkDotExpr(match, ctx) + ' ? ' + ctx + match.join('.') + ' : "")';
-  }
-  result = '(' + checkDotExpr(match, '_ctx.') + ' ? ' + buildDot('_ctx.') + ' : ' + buildDot('') + ')';
-  return '(' + result + ' !== null ? ' + result + ' : ' + '"" )';
+  var leaf = match.join('.');
+  return '(' + checkDotExpr(match, '_ctx.') + ' ? _ctx.' + leaf
+    + ' : (' + checkDotExpr(match, '') + ' ? ' + leaf + ' : ""))';
 }
 
 /*!

package/lib/engine.js

@@ -1,7 +1,19 @@
 var utils = require('./utils'),
+  ir = require('./ir'),
   backend = require('./backend'),
   cache = require('./cache');
 
+/**
+ * Constructor for AsyncFunction. Not a global; resolved once at module
+ * load via the prototype-chain walk of an async function expression.
+ * Used by {@link buildTemplateFunction} to wrap async-codegen template
+ * bodies so they return a Promise. Available in any engine that supports
+ * the `async function` syntax — Node ≥ 7.6 / all modern browsers; the
+ * package's engine floor (>=12) guarantees it.
+ * @private
+ */
+var AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+
 /**
  * Empty function used as a fallback in compiled template code.
  * @return {string} Empty string.
@@ -68,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.
@@ -132,24 +220,46 @@ exports.getParents = function (tokens, options, deps) {
  * contract every tag's compile() output depends on — `_output`, `_ext`,
  * `_ctx`, etc. are referenced by name in emitted code.
  *
+ * When `options.codegenMode === 'async'` the body is wrapped with
+ * AsyncFunction instead so the function returns a
+ * `Promise<{output: string, exports: object}>`. The exports map collects
+ * top-level macros so async importers (`IRImportDeferred` /
+ * `IRFromImportDeferred`) can bind them under their alias at runtime
+ * without parse-time pre-resolution. Async mode is also the consumer
+ * of the deferred-resolution IR shapes (IRIncludeDeferred,
+ * IRImportDeferred, IRFromImportDeferred, IRExtendsDeferred) which emit
+ * `await` calls into the body. The async wrapper takes a 6th positional
+ * `_blocks` parameter — an optional `{name: async fn(_ctx) -> string}`
+ * map of block overrides supplied by an extending child template. The
+ * IRBlock async-emit consults `_blocks[name]` first and falls back to
+ * the parent's inline body when no override is registered. Sync mode
+ * argument list is unchanged.
+ *
  * 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.
+ * helper only throws whatever the wrapper constructor 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.
+ * @return {Function}              Template function (sync) or async template function (Promise-returning).
  */
 exports.buildTemplateFunction = function (tokens, parents, options) {
-  return new Function('_swig', '_ctx', '_filters', '_utils', '_fn',
-    '  var _ext = _swig.extensions,\n' +
+  if (options && options.codegenMode === 'async') {
+    var asyncBody = '  var _ext = _swig.extensions,\n' +
+      '    _output = "",\n' +
+      '    _exports = {};\n' +
+      backend.compile(tokens, parents, options) + '\n' +
+      '  return { output: _output, exports: _exports };\n';
+    return new AsyncFunction('_swig', '_ctx', '_filters', '_utils', '_fn', '_blocks', asyncBody);
+  }
+  var body = '  var _ext = _swig.extensions,\n' +
     '    _output = "";\n' +
     backend.compile(tokens, parents, options) + '\n' +
-    '  return _output;\n'
-    );
+    '  return _output;\n';
+  return new Function('_swig', '_ctx', '_filters', '_utils', '_fn', body);
 };
 
 /**
@@ -274,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 {
@@ -306,7 +428,7 @@ exports.install = function (self, frontend) {
     contextLength = utils.keys(context).length;
     pre = self.precompile(source, options);
 
-    function compiled(locals) {
+    function compiled(locals, blocks) {
       var lcls;
       if (locals && contextLength) {
         lcls = utils.extend({}, context, locals);
@@ -317,7 +439,13 @@ exports.install = function (self, frontend) {
       } else {
         lcls = {};
       }
-      return pre.tpl(self, lcls, filters, utils, efn);
+      // `blocks` is the optional async-mode block-override map supplied
+      // by an extending child template's IRExtendsDeferred-emitted
+      // `_parent(_ctx, _mergedBlocks)` call. Sync templates ignore the
+      // extra positional arg (regular Function discards unread args);
+      // async wrapper picks it up as `_blocks` and consults it from
+      // IRBlock emits.
+      return pre.tpl(self, lcls, filters, utils, efn, blocks);
     }
 
     utils.extend(compiled, pre.tokens);
@@ -374,12 +502,102 @@ exports.install = function (self, frontend) {
     return self.compile(src, options);
   };
 
+  /**
+   * Async-codegen runtime helper. Resolves a template path via the active
+   * loader (cb-shape preferred when supported, sync fallback otherwise),
+   * compiles the source in async-codegen mode, and returns a Promise that
+   * resolves to the compiled async template function. The compiled
+   * function, when called, returns a `Promise<{output: string, exports:
+   * object}>` — `output` is the rendered text, `exports` is the
+   * top-level-macro map used by `IRImportDeferred` /
+   * `IRFromImportDeferred` callers.
+   *
+   * Called from compiled bodies emitted for `IRIncludeDeferred`,
+   * `IRImportDeferred`, `IRFromImportDeferred` (and, in a subsequent
+   * slice, `IRExtendsDeferred`) when an async-mode template needs to
+   * load a child template at render time.
+   *
+   * Cache semantics — bypasses the cache via `options.cache = false` on
+   * the inner compile call. The sync compile cache and the async compile
+   * cache would otherwise share a key (the resolved filename) and serve
+   * a mode-mismatched compiled fn to the wrong caller. Cleaner
+   * namespacing (separate sync/async cache buckets, or a key suffix) is
+   * deferred to a follow-up slice.
+   *
+   * @param  {string} pathname    Template path; resolved via the active loader.
+   * @param  {object} [options]   Per-call options. Honored: `resolveFrom`,
+   *                              `filename`. Inherits `self.options` for the rest.
+   * @return {Promise<Function>}  Resolves with the compiled async template fn.
+   */
+  self.getTemplate = function (pathname, options) {
+    options = options || {};
+
+    var resolved;
+    try {
+      resolved = self.options.loader.resolve(pathname, options.resolveFrom);
+    } catch (e) {
+      return Promise.reject(e);
+    }
+
+    var compileOpts = utils.extend({}, options, {
+      filename: options.filename || resolved,
+      codegenMode: 'async',
+      cache: false
+    });
+
+    return new Promise(function (resolve, reject) {
+      function onLoaded(err, src) {
+        if (err) {
+          reject(err);
+          return;
+        }
+        var compiled;
+        try {
+          compiled = self.compile(src, compileOpts);
+        } catch (err2) {
+          reject(err2);
+          return;
+        }
+        resolve(compiled);
+      }
+
+      if (self.options.loader.load.length >= 2) {
+        try {
+          self.options.loader.load(resolved, onLoaded);
+        } catch (e) {
+          onLoaded(e);
+        }
+      } else {
+        var src;
+        try {
+          src = self.options.loader.load(resolved);
+        } catch (e) {
+          onLoaded(e);
+          return;
+        }
+        onLoaded(null, src);
+      }
+    });
+  };
+
   self.render = function (source, options) {
     return self.compile(source, options)();
   };
 
   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

@@ -273,13 +273,93 @@
  * @property {IRLoc} [loc]
  */
 
+/* ------------------------------------------------------------------ *
+ * Deferred-resolution shapes — async codegen path.
+ *
+ * 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
+ * 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
+ * AsyncFunction-shaped JS that hits a runtime `_swig.getTemplate(...)`
+ * call to resolve and apply the parent / included / imported template.
+ *
+ * Sync codegen uses the existing {@link IRInclude} / {@link IRImport}
+ * shapes and the parser's pre-resolution path. Async codegen uses
+ * these. The frontend tag handlers branch on the codegen mode.
+ * ------------------------------------------------------------------ */
+
+/**
+ * Deferred extends marker — replaces the parse-finalization
+ * `getParents()` walk for async-mode templates. The runtime backend
+ * loads the parent via `_swig.getTemplate(<path>)`, applies the
+ * child's block overrides via `remapBlocks`, prepends the child's
+ * non-block IR via `importNonBlocks`, then renders.
+ *
+ * @typedef {Object} IRExtendsDeferred
+ * @property {'ExtendsDeferred'} type
+ * @property {IRExpr} path                            Path expression. Resolved at render time.
+ * @property {Object<string, IRBlock>} [childBlocks]  Child template's block overrides.
+ * @property {IRStatement[]} [childIRs]               Child template's non-block IR (prepended at runtime).
+ * @property {string} [resolveFrom]                   Including template's filename for loader-relative resolution.
+ * @property {IRLoc} [loc]
+ */
+
+/**
+ * Deferred include — async codegen counterpart to {@link IRInclude}.
+ * Same field shape; the `'IncludeDeferred'` type tag is the dispatch
+ * signal that tells the backend to emit an async resolution call
+ * instead of an inlined sync include.
+ *
+ * @typedef {Object} IRIncludeDeferred
+ * @property {'IncludeDeferred'} type
+ * @property {IRExpr} path
+ * @property {IRExpr} [context]
+ * @property {boolean} [isolated]
+ * @property {boolean} [ignoreMissing]
+ * @property {string} [resolveFrom]
+ * @property {IRLoc} [loc]
+ */
+
+/**
+ * Deferred import — async codegen counterpart to {@link IRImport}.
+ * `alias` MUST pass the dangerousProps guard at backend emit time.
+ *
+ * @typedef {Object} IRImportDeferred
+ * @property {'ImportDeferred'} type
+ * @property {IRExpr} path
+ * @property {string} alias
+ * @property {string} [resolveFrom]
+ * @property {IRLoc} [loc]
+ */
+
+/**
+ * Deferred Twig `{% from "file" import macroA, macroB as alias %}` —
+ * async codegen path. Each `imports[]` entry binds the imported macro
+ * `name` as a callable in `_ctx` under `alias` (or under `name` when
+ * `alias` is null). Every `name` and every non-null `alias` MUST pass
+ * the dangerousProps guard at backend emit time.
+ *
+ * @typedef {Object} IRFromImportDeferred
+ * @property {'FromImportDeferred'} type
+ * @property {IRExpr} path
+ * @property {Array<{name: string, alias: (string|null)}>} imports
+ * @property {string} [resolveFrom]
+ * @property {IRLoc} [loc]
+ */
+
 /**
  * Any body-level IR node.
  *
  * @typedef {(
  *   IRText | IROutput | IRIf | IRFor | IRBlock | IRInclude | IRImport |
  *   IRMacro | IRCall | IRSet | IRRaw | IRParent | IRAutoescape | IRFilter |
- *   IRWith | IRLegacyJS
+ *   IRWith | IRLegacyJS |
+ *   IRExtendsDeferred | IRIncludeDeferred | IRImportDeferred | IRFromImportDeferred
  * )} IRStatement
  */
 
@@ -754,6 +834,81 @@ exports.legacyJS = function (js, loc) {
   return withLoc({ type: 'LegacyJS', js: js }, loc);
 };
 
+/* -- Deferred-resolution factories --------------------------------- */
+
+/**
+ * Build an {@link IRExtendsDeferred} node. The factory stores `path`,
+ * `childBlocks`, and `childIRs` opaquely.
+ *
+ * @param  {IRExpr}                       path
+ * @param  {Object<string, IRBlock>}      [childBlocks]
+ * @param  {IRStatement[]}                [childIRs]
+ * @param  {string}                       [resolveFrom]
+ * @param  {IRLoc}                        [loc]
+ * @return {IRExtendsDeferred}
+ */
+exports.extendsDeferred = function (path, childBlocks, childIRs, resolveFrom, loc) {
+  var node = { type: 'ExtendsDeferred', path: path };
+  if (childBlocks !== undefined) { node.childBlocks = childBlocks; }
+  if (childIRs !== undefined) { node.childIRs = childIRs; }
+  if (resolveFrom !== undefined) { node.resolveFrom = resolveFrom; }
+  return withLoc(node, loc);
+};
+
+/**
+ * Build an {@link IRIncludeDeferred} node. Async-codegen counterpart
+ * to {@link exports.include}.
+ *
+ * @param  {IRExpr}  path
+ * @param  {IRExpr}  [context]
+ * @param  {boolean} [isolated]
+ * @param  {boolean} [ignoreMissing]
+ * @param  {string}  [resolveFrom]
+ * @param  {IRLoc}   [loc]
+ * @return {IRIncludeDeferred}
+ */
+exports.includeDeferred = function (path, context, isolated, ignoreMissing, resolveFrom, loc) {
+  var node = { type: 'IncludeDeferred', path: path };
+  if (context !== undefined) { node.context = context; }
+  if (isolated !== undefined) { node.isolated = isolated; }
+  if (ignoreMissing !== undefined) { node.ignoreMissing = ignoreMissing; }
+  if (resolveFrom !== undefined) { node.resolveFrom = resolveFrom; }
+  return withLoc(node, loc);
+};
+
+/**
+ * Build an {@link IRImportDeferred} node. `alias` MUST pass the
+ * dangerousProps guard at backend emit time.
+ *
+ * @param  {IRExpr} path
+ * @param  {string} alias
+ * @param  {string} [resolveFrom]
+ * @param  {IRLoc}  [loc]
+ * @return {IRImportDeferred}
+ */
+exports.importDeferred = function (path, alias, resolveFrom, loc) {
+  var node = { type: 'ImportDeferred', path: path, alias: alias };
+  if (resolveFrom !== undefined) { node.resolveFrom = resolveFrom; }
+  return withLoc(node, loc);
+};
+
+/**
+ * Build an {@link IRFromImportDeferred} node. Each entry's `name` and
+ * non-null `alias` MUST pass the dangerousProps guard at backend emit
+ * time.
+ *
+ * @param  {IRExpr}                                          path
+ * @param  {Array<{name: string, alias: (string|null)}>}     imports
+ * @param  {string}                                          [resolveFrom]
+ * @param  {IRLoc}                                           [loc]
+ * @return {IRFromImportDeferred}
+ */
+exports.fromImportDeferred = function (path, imports, resolveFrom, loc) {
+  var node = { type: 'FromImportDeferred', path: path, imports: imports };
+  if (resolveFrom !== undefined) { node.resolveFrom = resolveFrom; }
+  return withLoc(node, loc);
+};
+
 /* -- Expression factories ------------------------------------------ */
 
 /**

package/lib/tokenparser.js

@@ -884,7 +884,8 @@ TokenParser.prototype = {
    * @private
    */
   checkMatch: function (match) {
-    var temp = match[0], result;
+    var temp = match[0],
+      leaf = match.join('.');
 
     function checkDot(ctx) {
       var c = ctx + temp,
@@ -904,11 +905,8 @@ TokenParser.prototype = {
       return build;
     }
 
-    function buildDot(ctx) {
-      return '(' + checkDot(ctx) + ' ? ' + ctx + match.join('.') + ' : "")';
-    }
-    result = '(' + checkDot('_ctx.') + ' ? ' + buildDot('_ctx.') + ' : ' + buildDot('') + ')';
-    return '(' + result + ' !== null ? ' + result + ' : ' + '"" )';
+    return '(' + checkDot('_ctx.') + ' ? _ctx.' + leaf
+      + ' : (' + checkDot('') + ' ? ' + leaf + ' : ""))';
   }
 };
 

package/package.json

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