@rhinostone/swig 2.1.0 → 2.3.0

package/HISTORY.md

@@ -1,3 +1,17 @@
+[2.3.0](https://github.com/gina-io/swig/tree/v2.3.0) / 2026-05-14
+-----------------------------------------------------------------
+
+* **Changed** Drop `yargs` and `terser` from production `dependencies`. CLI argument parsing now uses a small built-in zero-dependency parser; `terser` (used only by `swig compile --minify`) is loaded lazily and moves to `devDependencies`. A library install of `@rhinostone/swig` now pulls in only `@rhinostone/swig-core`.
+
+[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,16 @@ _No near-term scheduled items. See [Future (post-2.0)](#future-post-20) for upco
 
 ## Completed
 
+### v2.3.0 (May 2026)
+
+- Reduced `@rhinostone/swig`'s production dependency footprint to a single package. `yargs` and `terser` were CLI-only — the library entry point never loaded them — but sat in production `dependencies`, so every library install pulled in their full dependency trees. The CLI's argument parsing is now handled by a small built-in zero-dependency parser; `terser` (used only by `swig compile --minify`) is loaded lazily and ships as a `devDependency`, with `--minify` printing an install hint instead of crashing if it is absent. A library install of `@rhinostone/swig` now pulls in only `@rhinostone/swig-core`. No change to the CLI surface or rendering behavior.
+
+### 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/bin/swig.js

@@ -2,109 +2,73 @@
 /*jslint es5: true */
 
 var swig = require('../index'),
-  yargs = require('yargs'),
   fs = require('fs'),
   path = require('path'),
   filters = require('../lib/filters'),
-  utils = require('../lib/utils'),
-  terser = require('terser');
-
-var command,
-  wrapstart = 'var tpl = ',
-  wrapend = ';',
-  argv = yargs
-    .usage('\n Usage:\n' +
-      '    $0 compile [files] [options]\n' +
-      '    $0 compile --recursive <dir> [options]\n' +
-      '    $0 run [files] [options]\n' +
-      '    $0 render [files] [options]\n'
-      )
-    .describe({
-      v: 'Show the Swig version number.',
-      o: 'Output location.',
-      h: 'Show this help screen.',
-      j: 'Variable context as a JSON file.',
-      c: 'Variable context as a CommonJS-style file. Used only if option `j` is not provided.',
-      m: 'Minify compiled functions with terser',
-      r: 'Recursively compile every template in <dir> into a single AOT bundle module.',
-      'ext': 'Comma-separated list of file extensions to include when using --recursive (e.g. ".html,.swig"). Defaults to no filter.',
-      'filters': 'Custom filters as a CommonJS-style file',
-      'tags': 'Custom tags as a CommonJS-style file',
-      'options': 'Customize Swig\'s Options from a CommonJS-style file',
-      'wrap-start': 'Template wrapper beginning for "compile".',
-      'wrap-end': 'Template wrapper end for "compile".',
-      'method-name': 'Method name to set template to and run from.'
-    })
-    .alias('v', 'version')
-    .alias('o', 'output')
-    .default('o', 'stdout')
-    .alias('h', 'help')
-    .alias('j', 'json')
-    .alias('c', 'context')
-    .alias('m', 'minify')
-    .alias('r', 'recursive')
-    .default('wrap-start', wrapstart)
-    .default('wrap-end', wrapend)
-    .default('method-name', 'tpl')
-    .check(function (argv) {
-      if (argv.v) {
-        return true;
-      }
-
-      if (!argv._.length) {
-        throw new Error('');
-      }
+  utils = require('../lib/utils');
 
-      command = argv._.shift();
-      if (command !== 'compile' && command !== 'render' && command !== 'run') {
-        throw new Error('Unrecognized command "' + command + '". Use -h for help.');
-      }
+var wrapstart = 'var tpl = ',
+  wrapend = ';';
 
-      if (argv['method-name'] !== 'tpl' && argv['wrap-start'] !== wrapstart) {
-        throw new Error('Cannot use arguments "--method-name" and "--wrap-start" together.');
-      }
-
-      if (argv['method-name'] !== 'tpl') {
-        argv['wrap-start'] = 'var ' + argv['method-name'] + ' = ';
-      }
-
-      if (argv.r) {
-        if (command !== 'compile') {
-          throw new Error('--recursive can only be used with "compile".');
-        }
-        if (argv._.length) {
-          throw new Error('--recursive does not accept positional file arguments; pass a single directory via --recursive <dir>.');
-        }
-        if (argv['method-name'] !== 'tpl') {
-          throw new Error('--recursive cannot be combined with --method-name; the bundle exports a map of templates, not a single named function.');
-        }
-        if (argv['wrap-start'] !== wrapstart || argv['wrap-end'] !== wrapend) {
-          throw new Error('--recursive cannot be combined with --wrap-start / --wrap-end; the bundle wrapper is fixed.');
-        }
-      }
-
-      if (argv.ext && !argv.r) {
-        throw new Error('--ext is only meaningful with --recursive.');
-      }
-
-      return true;
-    })
-    .argv,
+/**
+ * CLI flag table. Each entry is keyed by the canonical name the rest of this
+ * file reads. <code>alias</code> is the long-form name folded onto that key,
+ * <code>boolean</code> marks flags that never consume the following token,
+ * and <code>default</code> seeds a value when the flag is absent.
+ *
+ * @private
+ */
+var FLAGS = {
+  'v': { alias: 'version', boolean: true },
+  'o': { alias: 'output', default: 'stdout' },
+  'h': { alias: 'help', boolean: true },
+  'j': { alias: 'json' },
+  'c': { alias: 'context' },
+  'm': { alias: 'minify', boolean: true },
+  'r': { alias: 'recursive' },
+  'ext': {},
+  'filters': {},
+  'tags': {},
+  'options': {},
+  'wrap-start': { default: wrapstart },
+  'wrap-end': { default: wrapend },
+  'method-name': { default: 'tpl' }
+};
+
+var argv = parseArgs(process.argv.slice(2)),
+  command,
   ctx = {},
   out = function (file, str) {
     console.log(str);
   },
   efn = function () {},
-  anonymous,
-  files,
   fn;
 
+// Show this help screen.
+if (argv.h) {
+  console.log(usage());
+  process.exit(0);
+}
+
 // What version?
 if (argv.v) {
   console.log(require('../package').version);
   process.exit(0);
 }
 
+// Validate the parsed arguments and resolve the subcommand. On any invalid
+// combination, print the message (when there is one) plus the usage screen
+// and exit non-zero — the behaviour the former yargs `.check()` gate had.
+try {
+  command = validate(argv);
+} catch (e) {
+  if (e.message) {
+    console.error(e.message);
+  }
+  console.error(usage());
+  process.exit(1);
+}
+
 // Pull in any context data provided
 if (argv.j) {
   ctx = JSON.parse(fs.readFileSync(argv.j, 'utf8'));
@@ -158,7 +122,7 @@ case 'compile':
     r = argv['wrap-start'] + r + argv['wrap-end'];
 
     if (argv.m) {
-      r = terser.minify_sync(r).code;
+      r = loadTerser().minify_sync(r).code;
     }
 
     out(file, r);
@@ -191,6 +155,227 @@ if (argv.r) {
   });
 }
 
+/**
+ * Parse a <code>process.argv</code> tail into a flag / positional map.
+ * Supports <code>--name</code>, <code>--name=value</code>,
+ * <code>--name value</code>, <code>-x</code>, <code>-x value</code>,
+ * <code>-x=value</code>, and a <code>--</code> terminator after which every
+ * token is positional. Long-form aliases are folded onto their canonical
+ * {@link FLAGS} key; boolean flags never consume the following token. Bare
+ * tokens collect into <code>argv._</code>. Unknown flags are tolerated and
+ * kept verbatim, matching the former non-strict yargs behaviour.
+ *
+ * @param  {string[]} args  <code>process.argv.slice(2)</code>.
+ * @return {object}         <code>{ _: [positionals], &lt;flag&gt;: value }</code>.
+ * @private
+ */
+function parseArgs(args) {
+  var argv = { _: [] },
+    i,
+    token,
+    body,
+    eq,
+    name,
+    canonical,
+    value,
+    key;
+
+  for (i = 0; i < args.length; i += 1) {
+    token = args[i];
+
+    if (token === '--') {
+      argv._ = argv._.concat(args.slice(i + 1));
+      break;
+    }
+
+    if (token.slice(0, 2) === '--') {
+      body = token.slice(2);
+    } else if (token.charAt(0) === '-' && token.length > 1) {
+      body = token.slice(1);
+    } else {
+      argv._.push(token);
+      continue;
+    }
+
+    eq = body.indexOf('=');
+    if (eq !== -1) {
+      name = body.slice(0, eq);
+      value = body.slice(eq + 1);
+    } else {
+      name = body;
+      value = undefined;
+    }
+
+    canonical = aliasToCanonical(name);
+
+    if (value === undefined) {
+      if (FLAGS[canonical] && FLAGS[canonical].boolean) {
+        value = true;
+      } else if (i + 1 < args.length && !isFlagToken(args[i + 1])) {
+        i += 1;
+        value = args[i];
+      } else {
+        value = true;
+      }
+    }
+
+    argv[canonical] = value;
+  }
+
+  // Seed defaults for any flag the caller did not pass.
+  for (key in FLAGS) {
+    if (FLAGS.hasOwnProperty(key) && FLAGS[key].hasOwnProperty('default') && !argv.hasOwnProperty(key)) {
+      argv[key] = FLAGS[key].default;
+    }
+  }
+
+  return argv;
+}
+
+/**
+ * Resolve a flag name to its canonical {@link FLAGS} key. A name that is
+ * already canonical, or that matches no known alias, is returned unchanged.
+ *
+ * @param  {string} name  Flag name as written on the command line.
+ * @return {string}       Canonical key.
+ * @private
+ */
+function aliasToCanonical(name) {
+  var key;
+  if (FLAGS.hasOwnProperty(name)) {
+    return name;
+  }
+  for (key in FLAGS) {
+    if (FLAGS.hasOwnProperty(key) && FLAGS[key].alias === name) {
+      return key;
+    }
+  }
+  return name;
+}
+
+/**
+ * Is <var>token</var> a flag rather than a value? Used to decide whether a
+ * value-taking flag should consume the next token.
+ *
+ * @param  {string}  token  Candidate token.
+ * @return {boolean}        True when the token looks like a flag.
+ * @private
+ */
+function isFlagToken(token) {
+  return token.charAt(0) === '-' && token.length > 1;
+}
+
+/**
+ * Validate the parsed arguments and resolve the subcommand. Mirrors the gate
+ * the former yargs <code>.check()</code> chain enforced — same checks, same
+ * messages, same <code>--method-name</code> &rarr; <code>--wrap-start</code>
+ * rewrite. Throws on any invalid combination; the caller prints the message
+ * plus the usage screen and exits non-zero.
+ *
+ * @param  {object} argv  Parsed argv from {@link parseArgs}.
+ * @return {string}       The resolved subcommand: compile, render, or run.
+ * @private
+ */
+function validate(argv) {
+  var cmd;
+
+  if (!argv._.length) {
+    throw new Error('');
+  }
+
+  cmd = argv._.shift();
+  if (cmd !== 'compile' && cmd !== 'render' && cmd !== 'run') {
+    throw new Error('Unrecognized command "' + cmd + '". Use -h for help.');
+  }
+
+  if (argv['method-name'] !== 'tpl' && argv['wrap-start'] !== wrapstart) {
+    throw new Error('Cannot use arguments "--method-name" and "--wrap-start" together.');
+  }
+
+  if (argv['method-name'] !== 'tpl') {
+    argv['wrap-start'] = 'var ' + argv['method-name'] + ' = ';
+  }
+
+  if (argv.r) {
+    if (cmd !== 'compile') {
+      throw new Error('--recursive can only be used with "compile".');
+    }
+    if (argv._.length) {
+      throw new Error('--recursive does not accept positional file arguments; pass a single directory via --recursive <dir>.');
+    }
+    if (argv['method-name'] !== 'tpl') {
+      throw new Error('--recursive cannot be combined with --method-name; the bundle exports a map of templates, not a single named function.');
+    }
+    if (argv['wrap-start'] !== wrapstart || argv['wrap-end'] !== wrapend) {
+      throw new Error('--recursive cannot be combined with --wrap-start / --wrap-end; the bundle wrapper is fixed.');
+    }
+  }
+
+  if (argv.ext && !argv.r) {
+    throw new Error('--ext is only meaningful with --recursive.');
+  }
+
+  return cmd;
+}
+
+/**
+ * Build the CLI usage screen — the command synopsis plus the option table.
+ *
+ * @return {string}  The full usage text.
+ * @private
+ */
+function usage() {
+  return [
+    '',
+    ' Usage:',
+    '    swig compile [files] [options]',
+    '    swig compile --recursive <dir> [options]',
+    '    swig run [files] [options]',
+    '    swig render [files] [options]',
+    '',
+    ' Options:',
+    '    -v, --version       Show the Swig version number.',
+    '    -o, --output        Output location.',
+    '    -h, --help          Show this help screen.',
+    '    -j, --json          Variable context as a JSON file.',
+    '    -c, --context       Variable context as a CommonJS-style file. Used only if option `j` is not provided.',
+    '    -m, --minify        Minify compiled functions with terser',
+    '    -r, --recursive     Recursively compile every template in <dir> into a single AOT bundle module.',
+    '    --ext               Comma-separated list of file extensions to include when using --recursive (e.g. ".html,.swig"). Defaults to no filter.',
+    '    --filters           Custom filters as a CommonJS-style file',
+    '    --tags              Custom tags as a CommonJS-style file',
+    '    --options           Customize Swig\'s Options from a CommonJS-style file',
+    '    --wrap-start        Template wrapper beginning for "compile".',
+    '    --wrap-end          Template wrapper end for "compile".',
+    '    --method-name       Method name to set template to and run from.',
+    ''
+  ].join('\n');
+}
+
+/**
+ * Lazily load the optional <code>terser</code> package, used only by the
+ * <code>--minify</code> flag. terser is a CLI-only dependency — the library
+ * entry point never needs it — so it ships as a devDependency rather than a
+ * runtime one, and a plain <code>npm install @rhinostone/swig</code> does not
+ * pull it in. Print a friendly install hint and exit non-zero if a CLI user
+ * reaches <code>--minify</code> without it.
+ *
+ * @return {object}  The terser module.
+ * @private
+ */
+function loadTerser() {
+  try {
+    return require('terser');
+  } catch (e) {
+    if (e.code !== 'MODULE_NOT_FOUND') {
+      throw e;
+    }
+    console.error('The --minify flag needs the "terser" package, which is not installed.');
+    console.error('Install it with:  npm install terser');
+    process.exit(1);
+  }
+}
+
 /**
  * Walk a directory recursively, returning every regular-file path found.
  * Skips dotfile entries and dot-directories so platform metadata such as
@@ -268,7 +453,7 @@ function bundleRecursive(dir) {
   output = 'module.exports = {\n' + parts.join(',\n') + '\n};\n';
 
   if (argv.m) {
-    output = terser.minify_sync(output).code;
+    output = loadTerser().minify_sync(output).code;
   }
 
   if (argv.o === 'stdout') {