@rhinostone/swig 2.1.0 → 2.2.0

package/.changes/v2.2.0.md

@@ -0,0 +1,8 @@
+[2.2.0](https://github.com/gina-io/swig/tree/v2.2.0) / 2026-05-11
+-----------------------------------------------------------------
+
+* **Added** `renderFile(path, locals, cb)` and `compileFile(path, options, cb)` automatically route to the async-codegen path when the configured loader signals async support via `loader.async === true`. The async path defers template resolution from parse time to render time via a new `_swig.getTemplate(path, options)` runtime helper that returns `Promise<TemplateFn>` — `extends`, `include`, `import`, and `from` emit deferred IR shapes from the frontend (`IRExtendsDeferred`, `IRIncludeDeferred`, `IRImportDeferred`, `IRFromImportDeferred`) and the shared backend wraps the compiled body in an `AsyncFunction`. Block overrides thread through the inheritance chain via a sixth `_blocks` positional argument on the wrapped template function; macro imports pick up exports via the new `Promise<{output, exports}>` template-fn return shape. Both `@rhinostone/swig` and `@rhinostone/swig-twig` flavors — parity across the two surfaces. Static template targets (string literals in `extends` / `include` / `import` / `from`) work end-to-end against async loaders; dynamic targets (`{% extends parent_var %}`, `{% include user_template %}`) are not yet supported on the async path and surface a clear runtime error with the unresolved expression visible in the message — full dynamic-target support is tracked as a follow-up. The sync render path is unchanged — loaders without `loader.async === true` continue to use the established sync `_swig.compileFile(...)` resolution, including the built-in `loaders.fs` and `loaders.memory` which remain dual-mode. End-to-end coverage at `tests/async/render-file-cb-dispatch.test.js` (native, 11 cases) and `tests/swig-twig/async/render-file-cb-dispatch.test.js` (Twig, 11 cases) covers static extends chains, includes, macro imports, mixed graphs, dynamic include paths surfacing the runtime error, the `ignoreMissing` flag, `with-context` isolation, bare-name and aliased `from` import, and error propagation.
+
+* **Changed** `renderFileAsync(path, locals, cb)` and `compileFileAsync(path, options, cb)` on both `@rhinostone/swig` and `@rhinostone/swig-twig` are soft-deprecated via JSDoc only — no runtime warning, no `console.warn`. Use `renderFile(path, locals, cb)` / `compileFile(path, options, cb)` with an async loader (`loader.async === true`) instead; the dispatch is automatic. The legacy pre-walker entry points remain fully functional in 2.x and will be removed in 3.0.
+
+* **Changed** Improved the performance of the `escape` / `e` filter in both `@rhinostone/swig` and `@rhinostone/swig-twig`. The HTML default branch now runs a two-pass form — an entity-aware first pass that preserves already-escaped sequences (`&amp;`, `&lt;`, `&gt;`, `&quot;`, `&#39;`) followed by a single character-class regex `[<>"']` with a lookup function for the rest — instead of five sequential single-character regex passes. A scalar fast-path also skips `iterateFilter.apply` when input is null, undefined, or a non-object. Output is byte-identical to the previous behavior on every input, including the entity-preservation semantics swig has shipped since the upstream fork. Measured against `benchmarks/render.js` (medians of 5 runs, autoescape on, Node 25), simple-var-output goes from ~2.46M to 3.86M ops/s (+57%, flipping the verdict from `nunjucks 1.32x faster` to `swig 1.18x faster`); filter chain +37%; for-loop (5 items) +54%; if/else branch +71%; nested for+if+filter +56%. The `case 'js'` branch and array-iteration fallback through `iterateFilter` are unchanged. All 1443 tests pass including the 9 CVE regressions.

package/HISTORY.md

@@ -1,3 +1,12 @@
+[2.2.0](https://github.com/gina-io/swig/tree/v2.2.0) / 2026-05-11
+-----------------------------------------------------------------
+
+* **Added** `renderFile(path, locals, cb)` and `compileFile(path, options, cb)` automatically route to the async-codegen path when the configured loader signals async support via `loader.async === true`. The async path defers template resolution from parse time to render time via a new `_swig.getTemplate(path, options)` runtime helper that returns `Promise<TemplateFn>` — `extends`, `include`, `import`, and `from` emit deferred IR shapes from the frontend (`IRExtendsDeferred`, `IRIncludeDeferred`, `IRImportDeferred`, `IRFromImportDeferred`) and the shared backend wraps the compiled body in an `AsyncFunction`. Block overrides thread through the inheritance chain via a sixth `_blocks` positional argument on the wrapped template function; macro imports pick up exports via the new `Promise<{output, exports}>` template-fn return shape. Both `@rhinostone/swig` and `@rhinostone/swig-twig` flavors — parity across the two surfaces. Static template targets (string literals in `extends` / `include` / `import` / `from`) work end-to-end against async loaders; dynamic targets (`{% extends parent_var %}`, `{% include user_template %}`) are not yet supported on the async path and surface a clear runtime error with the unresolved expression visible in the message — full dynamic-target support is tracked as a follow-up. The sync render path is unchanged — loaders without `loader.async === true` continue to use the established sync `_swig.compileFile(...)` resolution, including the built-in `loaders.fs` and `loaders.memory` which remain dual-mode. End-to-end coverage at `tests/async/render-file-cb-dispatch.test.js` (native, 11 cases) and `tests/swig-twig/async/render-file-cb-dispatch.test.js` (Twig, 11 cases) covers static extends chains, includes, macro imports, mixed graphs, dynamic include paths surfacing the runtime error, the `ignoreMissing` flag, `with-context` isolation, bare-name and aliased `from` import, and error propagation.
+
+* **Changed** `renderFileAsync(path, locals, cb)` and `compileFileAsync(path, options, cb)` on both `@rhinostone/swig` and `@rhinostone/swig-twig` are soft-deprecated via JSDoc only — no runtime warning, no `console.warn`. Use `renderFile(path, locals, cb)` / `compileFile(path, options, cb)` with an async loader (`loader.async === true`) instead; the dispatch is automatic. The legacy pre-walker entry points remain fully functional in 2.x and will be removed in 3.0.
+
+* **Changed** Improved the performance of the `escape` / `e` filter in both `@rhinostone/swig` and `@rhinostone/swig-twig`. The HTML default branch now runs a two-pass form — an entity-aware first pass that preserves already-escaped sequences (`&amp;`, `&lt;`, `&gt;`, `&quot;`, `&#39;`) followed by a single character-class regex `[<>"']` with a lookup function for the rest — instead of five sequential single-character regex passes. A scalar fast-path also skips `iterateFilter.apply` when input is null, undefined, or a non-object. Output is byte-identical to the previous behavior on every input, including the entity-preservation semantics swig has shipped since the upstream fork. Measured against `benchmarks/render.js` (medians of 5 runs, autoescape on, Node 25), simple-var-output goes from ~2.46M to 3.86M ops/s (+57%, flipping the verdict from `nunjucks 1.32x faster` to `swig 1.18x faster`); filter chain +37%; for-loop (5 items) +54%; if/else branch +71%; nested for+if+filter +56%. The `case 'js'` branch and array-iteration fallback through `iterateFilter` are unchanged. All 1443 tests pass including the 9 CVE regressions.
+
 [2.1.0](https://github.com/gina-io/swig/tree/v2.1.0) / 2026-05-10
 -----------------------------------------------------------------
 

package/ROADMAP.md

@@ -14,6 +14,7 @@ _No near-term scheduled items. See [Future (post-2.0)](#future-post-20) for upco
 
 | Status | Item |
 | --- | --- |
+| Planned | Async parse path for dynamic targets — full support for `{% extends parent_var %}`, `{% include user_template %}`, and runtime-resolved `import` / `from` paths on the async-codegen branch. Static-target async dispatch shipped in 2.2.0; dynamic-target support is on hold pending consumer demand. |
 | Planned | Ship Jinja2 and Django frontends as additional `@rhinostone/swig-*` packages. On demand — when there's concrete user demand. |
 | Planned | Test framework migration. Replace mocha 1.x + expect.js with `node:test` + `node:assert/strict`, swap mocha-phantomjs for a modern browser-test harness, swap blanket for `c8`. (The Node engines bump is upstream-driven by gina and is being treated as done.) |
 
@@ -21,6 +22,12 @@ _No near-term scheduled items. See [Future (post-2.0)](#future-post-20) for upco
 
 ## Completed
 
+### v2.2.0 (May 2026)
+
+- `renderFile(path, locals, cb)` and `compileFile(path, options, cb)` now automatically route to the async-codegen path when the configured loader signals async support via `loader.async === true`. The async path defers template resolution from parse time to render time via a new `_swig.getTemplate(path, options)` runtime helper that returns `Promise<TemplateFn>`; `extends`, `include`, `import`, and `from` emit deferred IR shapes and the shared backend wraps the compiled body in an `AsyncFunction`. Block overrides thread through the inheritance chain via a sixth `_blocks` positional argument; macro imports pick up exports via a `Promise<{output, exports}>` template-fn return shape. Both `@rhinostone/swig` and `@rhinostone/swig-twig` flavors — parity across the two surfaces. Static template targets (string literals in `extends` / `include` / `import` / `from`) work end-to-end against async loaders; dynamic targets surface a clear runtime error and are tracked as a follow-up. The sync render path is unchanged — loaders without `loader.async === true` continue to use the established sync `_swig.compileFile(...)` resolution, including the built-in `loaders.fs` and `loaders.memory` which remain dual-mode.
+- `renderFileAsync(path, locals, cb)` and `compileFileAsync(path, options, cb)` on both `@rhinostone/swig` and `@rhinostone/swig-twig` are soft-deprecated via JSDoc only — no runtime warning. Use `renderFile` / `compileFile` with an async loader (`loader.async === true`) instead; the dispatch is automatic. The legacy pre-walker entry points remain fully functional in 2.x and will be removed in 3.0.
+- Performance improvement to the `escape` / `e` filter in both flavors. The HTML default branch switched from a five-replace chain to an entity-preserving two-pass form (entity-aware first pass that preserves already-escaped sequences, followed by a single character-class regex with a lookup function). A scalar fast-path skips the array/object iteration when input is null, undefined, or a non-object. Output is byte-identical to the previous behavior on every input. Measured against `benchmarks/render.js` (medians of 5 runs, autoescape on, Node 25): simple-var-output `+57%` (flipping the bench verdict from `nunjucks 1.32x faster` to `swig 1.18x faster`); filter chain `+37%`; for-loop (5 items) `+54%`; if/else branch `+71%`; nested for+if+filter `+56%`.
+
 ### v2.1.0 (May 2026)
 
 - Async loader support via `renderFileAsync(path, locals, cb)` and `compileFileAsync(path, options, cb)` on `@rhinostone/swig` and `@rhinostone/swig-twig`. The implementation pre-walks the template dependency graph through the user loader's cb-shape arm, builds an in-memory map keyed by resolved path, then runs the existing sync render against an in-memory wrapper for the duration of the call. Supports `extends`, `include`, `import`, and Twig `from import` with string-literal paths; dynamic paths surface a `Pre-walked map missing path` error at render time. Existing sync `renderFile` / `compileFile` consumers are unaffected.

package/dist/swig.js

@@ -1,4 +1,4 @@
-/*! Swig v2.1.0 | https://github.com/gina-io/swig | @license https://github.com/gina-io/swig/blob/master/LICENSE */
+/*! Swig v2.2.0 | https://github.com/gina-io/swig | @license https://github.com/gina-io/swig/blob/master/LICENSE */
 /*! DateZ (c) 2011 Tomo Universalis | @license https://github.com/ocrybit/DateZ/blob/master/LISENCE */
 (() => {
   var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -844,32 +844,40 @@
       exports["default"] = function(input, def) {
         return typeof input !== "undefined" && (input || typeof input === "number") ? input : def;
       };
+      function escapeHtmlRest(ch) {
+        return ch === "<" ? "&lt;" : ch === ">" ? "&gt;" : ch === '"' ? "&quot;" : "&#39;";
+      }
       exports.escape = function(input, type) {
-        var out = iterateFilter.apply(exports.escape, arguments), inp = input, i = 0, code;
-        if (out !== void 0) {
-          return out;
+        var t, inp, out, i, code;
+        if (input === null || input === void 0) {
+          return input;
         }
-        if (typeof input !== "string") {
+        t = typeof input;
+        if (t !== "string") {
+          if (t === "object") {
+            out = iterateFilter.apply(exports.escape, arguments);
+            if (out !== void 0) {
+              return out;
+            }
+          }
           return input;
         }
-        out = "";
-        switch (type) {
-          case "js":
-            inp = inp.replace(/\\/g, "\\u005C");
-            for (i; i < inp.length; i += 1) {
-              code = inp.charCodeAt(i);
-              if (code < 32) {
-                code = code.toString(16).toUpperCase();
-                code = code.length < 2 ? "0" + code : code;
-                out += "\\u00" + code;
-              } else {
-                out += inp[i];
-              }
+        if (type === "js") {
+          inp = input.replace(/\\/g, "\\u005C");
+          out = "";
+          for (i = 0; i < inp.length; i += 1) {
+            code = inp.charCodeAt(i);
+            if (code < 32) {
+              code = code.toString(16).toUpperCase();
+              code = code.length < 2 ? "0" + code : code;
+              out += "\\u00" + code;
+            } else {
+              out += inp[i];
             }
-            return out.replace(/&/g, "\\u0026").replace(/</g, "\\u003C").replace(/>/g, "\\u003E").replace(/\'/g, "\\u0027").replace(/"/g, "\\u0022").replace(/\=/g, "\\u003D").replace(/-/g, "\\u002D").replace(/;/g, "\\u003B");
-          default:
-            return inp.replace(/&(?!amp;|lt;|gt;|quot;|#39;)/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+          }
+          return out.replace(/&/g, "\\u0026").replace(/</g, "\\u003C").replace(/>/g, "\\u003E").replace(/\'/g, "\\u0027").replace(/"/g, "\\u0022").replace(/\=/g, "\\u003D").replace(/-/g, "\\u002D").replace(/;/g, "\\u003B");
         }
+        return input.replace(/&(?!amp;|lt;|gt;|quot;|#39;)/g, "&amp;").replace(/[<>"']/g, escapeHtmlRest);
       };
       exports.e = exports.escape;
       exports.first = function(input) {
@@ -2993,9 +3001,19 @@
   var require_import = __commonJS({
     "lib/tags/import.js"(exports) {
       var utils = require_utils2();
+      var ir = require_ir();
       var backend = require_backend();
       var _dangerousProps = require_security().dangerousProps;
-      exports.compile = function(compiler, args) {
+      exports.compile = function(compiler, args, content, parents, options) {
+        if (options && options.codegenMode === "async") {
+          var asyncAlias = args[args.length - 1];
+          var asyncPath = args[0].path;
+          return ir.importDeferred(
+            ir.literal("string", asyncPath),
+            asyncAlias,
+            options.filename || ""
+          );
+        }
         var ctx = args.pop(), allMacros = utils.map(args, function(arg) {
           return arg.name;
         }).join("|"), out = "_ctx." + ctx + ' = {};\n  var _output = "";\n', replacements = utils.map(args, function(arg) {
@@ -3014,27 +3032,31 @@
         return out;
       };
       exports.parse = function(str, line, parser, types, stack, opts, swig2) {
-        var compiler = require_parser().compile, parseOpts = { resolveFrom: opts.filename }, compileOpts = utils.extend({}, opts, parseOpts), tokens, ctx;
+        var compiler = require_parser().compile, parseOpts = { resolveFrom: opts.filename }, compileOpts = utils.extend({}, opts, parseOpts), isAsync = !!(opts && opts.codegenMode === "async"), importPath, ctx;
         parser.on(types.STRING, function(token) {
           var self = this;
-          if (!tokens) {
-            tokens = swig2.parseFile(token.match.replace(/^("|')|("|')$/g, ""), parseOpts).tokens;
-            utils.each(tokens, function(token2) {
-              var out = "", macroName;
-              if (!token2 || token2.name !== "macro" || !token2.compile) {
-                return;
-              }
-              macroName = token2.args[0];
-              out += backend.compile([token2.compile(compiler, token2.args, token2.content, [], compileOpts)], [], compileOpts) + "\n";
-              self.out.push({ compiled: out, name: macroName });
-            });
+          if (importPath !== void 0) {
+            throw new Error("Unexpected string " + token.match + " on line " + line + ".");
+          }
+          importPath = token.match.replace(/^("|')|("|')$/g, "");
+          if (isAsync) {
+            self.out.push({ path: importPath });
             return;
           }
-          throw new Error("Unexpected string " + token.match + " on line " + line + ".");
+          var tokens = swig2.parseFile(importPath, parseOpts).tokens;
+          utils.each(tokens, function(token2) {
+            var out = "", macroName;
+            if (!token2 || token2.name !== "macro" || !token2.compile) {
+              return;
+            }
+            macroName = token2.args[0];
+            out += backend.compile([token2.compile(compiler, token2.args, token2.content, [], compileOpts)], [], compileOpts) + "\n";
+            self.out.push({ compiled: out, name: macroName });
+          });
         });
         parser.on(types.VAR, function(token) {
           var self = this;
-          if (!tokens || ctx) {
+          if (importPath === void 0 || ctx) {
             throw new Error('Unexpected variable "' + token.match + '" on line ' + line + ".");
           }
           if (token.match === "as") {
@@ -3071,6 +3093,9 @@
             w = void 0;
           }
         }
+        if (options && options.codegenMode === "async") {
+          return ir.includeDeferred(file, w || void 0, !!onlyCtx, !!ignoreMissing, parentFile);
+        }
         return ir.include(file, w || void 0, !!onlyCtx, !!ignoreMissing, parentFile);
       };
       exports.lowerExpr = function(parser, tokens) {
@@ -4130,6 +4155,7 @@
   var require_engine = __commonJS({
     "packages/swig-core/lib/engine.js"(exports) {
       var utils = require_utils();
+      var ir = require_ir();
       var backend = require_backend();
       var cache = require_cache();
       var AsyncFunction = Object.getPrototypeOf(async function() {
@@ -4160,6 +4186,45 @@
           }
         });
       };
+      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, void 0, blockToken);
+          if (result === void 0 || 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 || ""
+        );
+      }
       exports.getParents = function(tokens, options, deps) {
         var parentName = tokens.parent, parentFiles = [], parents = [], parentFile, parent, l;
         while (parentName) {
@@ -4267,10 +4332,16 @@
           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);
+          var tokens = self.parse(source, options), parents, tpl;
+          if (options && options.codegenMode === "async" && tokens.parent) {
+            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 {
             tpl = exports.buildTemplateFunction(tokens, parents, options);
@@ -4394,6 +4465,14 @@
         };
         self.renderFile = function(pathName, locals, cb) {
           if (cb) {
+            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;
               if (err) {
@@ -4434,7 +4513,7 @@
       var loaders = require_loaders2();
       var preWalker = require_pre_walker();
       var engine = require_engine();
-      exports.version = "2.1.0";
+      exports.version = "2.2.0";
       var defaultOptions = {
         autoescape: true,
         varControls: ["{{", "}}"],