@rhinostone/swig-twig 2.0.0-alpha.3 → 2.0.0-alpha.4

package/lib/index.js

@@ -1,66 +1,209 @@
 /**
  * @rhinostone/swig-twig — Twig frontend for the @rhinostone/swig family.
  *
- * Phase 3 scaffold. Subsequent commits add the Twig lexer + parser
- * (source → IR), the Twig filter parity catalog, and the per-flavor
- * tag set. Source-to-IR lowering targets the swig-core IR schema
- * defined in @rhinostone/swig-core/lib/ir; built-in Twig tags lower at
- * parse time rather than registering through the runtime setTag
- * extension point.
+ * Phase 3 Session 17: end-to-end render wiring (Path A). The package now
+ * exposes a Twig constructor + default instance via `engine.install(self,
+ * frontend)` from @rhinostone/swig-core, so callers can `render(source,
+ * locals)` / `renderFile(path, locals, cb)` directly against Twig syntax.
  *
- * See .claude/architecture/multi-flavor-ir.md § Phase 3 for the
- * per-flavor split decision and migration sequence.
+ * See .claude/architecture/multi-flavor-ir.md § Phase 3 for the per-flavor
+ * split decision.
  */
 
+var utils = require('@rhinostone/swig-core/lib/utils'),
+  engine = require('@rhinostone/swig-core/lib/engine'),
+  loaders = require('@rhinostone/swig-core/lib/loaders'),
+  dateformatter = require('@rhinostone/swig-core/lib/dateformatter'),
+  parser = require('./parser'),
+  _tags = require('./tags'),
+  _filters = require('./filters');
+
 exports.name = 'twig';
 
 /**
  * Expression-level parser — Pratt-style recursive descent that consumes
  * Twig lexer tokens and returns swig-core IRExpr nodes.
  *
- * Exposed here so callers can import it from the package entry-point;
- * NOT wired into parse(source) yet (that still throws).
- *
  * @type {object}
  */
-exports.parser = require('./parser');
+exports.parser = parser;
 
 /**
- * Built-in Twig tag registry. See `./tags/index.js` for the per-tag shape.
+ * Built-in Twig tag registry.
  *
  * @type {object}
  */
-exports.tags = require('./tags');
+exports.tags = _tags;
 
 /**
- * Built-in Twig filter catalog. See `./filters.js` for the per-filter shape.
+ * Built-in Twig filter catalog.
  *
- * Shipped as the Twig frontend's `_filters` runtime map and `setFilter`
- * mutation target via `engine.install(self, frontend)`. Filters marked
- * `.safe = true` suppress the autoescape `e` tail injected by
- * `parseVariable`. Only `raw` carries `.safe = true` this session.
+ * @type {object}
+ */
+exports.filters = _filters;
+
+/**
+ * Template loaders re-exported from swig-core.
  *
  * @type {object}
  */
-exports.filters = require('./filters');
+exports.loaders = loaders;
+
+var defaultOptions = {
+    autoescape: true,
+    varControls: ['{{', '}}'],
+    tagControls: ['{%', '%}'],
+    cmtControls: ['{#', '#}'],
+    locals: {},
+    cache: 'memory',
+    loader: loaders.fs()
+  },
+  defaultInstance;
+
+/**
+ * Validate the Twig options object.
+ *
+ * @param  {?object} options Twig options object.
+ * @return {undefined}      Throws on malformed input.
+ * @private
+ */
+function validateOptions(options) {
+  if (!options) {
+    return;
+  }
+
+  utils.each(['varControls', 'tagControls', 'cmtControls'], function (key) {
+    if (!options.hasOwnProperty(key)) {
+      return;
+    }
+    if (!utils.isArray(options[key]) || options[key].length !== 2) {
+      throw new Error('Option "' + key + '" must be an array containing 2 different control strings.');
+    }
+    if (options[key][0] === options[key][1]) {
+      throw new Error('Option "' + key + '" open and close controls must not be the same.');
+    }
+    utils.each(options[key], function (a, i) {
+      if (a.length < 2) {
+        throw new Error('Option "' + key + '" ' + ((i) ? 'open ' : 'close ') + 'control must be at least 2 characters. Saw "' + a + '" instead.');
+      }
+    });
+  });
+
+  if (options.hasOwnProperty('cache')) {
+    if (options.cache && options.cache !== 'memory') {
+      if (!options.cache.get || !options.cache.set) {
+        throw new Error('Invalid cache option ' + JSON.stringify(options.cache) + ' found. Expected "memory" or { get: function (key) { ... }, set: function (key, value) { ... } }.');
+      }
+    }
+  }
+  if (options.hasOwnProperty('loader')) {
+    if (options.loader) {
+      if (!options.loader.load || !options.loader.resolve) {
+        throw new Error('Invalid loader option ' + JSON.stringify(options.loader) + ' found. Expected { load: function (pathname, cb) { ... }, resolve: function (to, from) { ... } }.');
+      }
+    }
+  }
+}
+
+/**
+ * Set defaults for the base and all new Twig environments.
+ *
+ * @param  {object} [options={}] Twig options object.
+ * @return {undefined}
+ */
+exports.setDefaults = function (options) {
+  validateOptions(options);
+  defaultInstance.options = utils.extend(defaultInstance.options, options);
+};
+
+/**
+ * Set the default TimeZone offset for date formatting via the date filter.
+ * Mutates the shared dateformatter's tzOffset — affects every frontend
+ * (native swig + swig-twig) because both consume the same module instance.
+ *
+ * @param  {number} offset Offset from GMT, in minutes (west of GMT).
+ * @return {undefined}
+ */
+exports.setDefaultTZOffset = function (offset) {
+  dateformatter.tzOffset = offset;
+};
+
+/**
+ * Create a new, separate Twig compile/render environment.
+ *
+ * @example
+ * var twig = require('@rhinostone/swig-twig');
+ * var mytwig = new twig.Twig({ autoescape: false });
+ * mytwig.render('Hello {{ name }}', { locals: { name: 'world' }});
+ *
+ * @param  {object} [opts={}] Twig options object.
+ * @return {object}           New Twig environment.
+ */
+exports.Twig = function (opts) {
+  validateOptions(opts);
+  this.options = utils.extend({}, defaultOptions, opts || {});
+  this.cache = {};
+  this.extensions = {};
+
+  engine.install(this, {
+    parser: parser,
+    tags: _tags,
+    filters: _filters,
+    validateOptions: validateOptions,
+    onCompileError: function (err, options) {
+      utils.throwError(err, null, options.filename);
+    }
+  });
+};
+
+/*!
+ * Export methods publicly via the default instance.
+ */
+defaultInstance = new exports.Twig();
+exports.setFilter = defaultInstance.setFilter;
+exports.setTag = defaultInstance.setTag;
+exports.setExtension = defaultInstance.setExtension;
+exports.parseFile = defaultInstance.parseFile;
+exports.precompile = defaultInstance.precompile;
+exports.compile = defaultInstance.compile;
+exports.compileFile = defaultInstance.compileFile;
+exports.render = defaultInstance.render;
+exports.renderFile = defaultInstance.renderFile;
+exports.run = defaultInstance.run;
+exports.invalidateCache = defaultInstance.invalidateCache;
+
+/**
+ * Express 3/4 compatibility alias.
+ *
+ * @example
+ * app.engine('twig', require('@rhinostone/swig-twig').__express);
+ * app.set('view engine', 'twig');
+ */
+exports.__express = defaultInstance.renderFile;
+
+var _parseDeprecationWarned = false;
 
 /**
  * Parse a Twig source string into the parse-tree shape consumed by
  * swig-core's `engine.compile`: `{ name, parent, tokens, blocks }`.
  *
- * Convenience wrapper around `exports.parser.parse(swig, source, options,
- * tags, filters)` — defaults `tags` to the built-in Twig registry and
- * `filters` to an empty map. Callers wiring Twig as a frontend through
- * `engine.install(self, frontend)` should call `exports.parser.parse`
- * directly so the engine's own filter and tag maps flow through.
+ * @deprecated since 2.0.0-alpha.4 — use `new exports.Twig(opts)` and the
+ * per-instance `precompile` / `compile` / `render` surface installed by
+ * `engine.install`. Slated for removal in `2.0.0` stable. The full-instance
+ * path uses closure-captured tag/filter maps and honors `setFilter` /
+ * `setTag` overrides; this Path B wrapper does not.
  *
  * @param  {string} source     Twig template source.
- * @param  {object} [options]  Per-call frontend options
- *                             (`autoescape`, `varControls`, `tagControls`,
- *                             `cmtControls`, `filename`, `tags`, `filters`).
+ * @param  {object} [options]  Per-call options.
  * @return {object}            `{ name, parent, tokens, blocks }`.
  */
 exports.parse = function (source, options) {
+  if (!_parseDeprecationWarned) {
+    _parseDeprecationWarned = true;
+    if (typeof console !== 'undefined' && console.warn) {
+      console.warn('[@rhinostone/swig-twig] exports.parse is deprecated and will be removed in 2.0.0. Use `new twig.Twig(opts)` and the per-instance precompile/compile/render API instead.');
+    }
+  }
   options = options || {};
   var tags = options.tags || exports.tags;
   var filters = options.filters || exports.filters;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhinostone/swig-twig",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.4",
   "description": "Twig frontend for the @rhinostone/swig-core template engine. Phase 3 of the multi-flavor architecture (see @rhinostone/swig #T16).",
   "keywords": [
     "template",
@@ -22,7 +22,7 @@
     "node": ">=12"
   },
   "peerDependencies": {
-    "@rhinostone/swig-core": "2.0.0-alpha.3"
+    "@rhinostone/swig-core": "2.0.0-alpha.4"
   },
   "publishConfig": {
     "access": "public"