eleventy-plugin-vento 4.0.1 → 4.1.0

package/CHANGELOG.md

@@ -1,10 +1,27 @@
 # eleventy-plugin-vento
 
+## 4.1.0
+
+### Minor Changes
+
+- eb33d79: Expose Vento's `FilterThis` on Eleventy-declared filters. (fixes #72)
+
+  > [!IMPORTANT]
+  > Using this feature incurs the same performance regression that [`eleventyComputed` template strings](https://www.11ty.dev/docs/data-computed/#using-a-template-string) do. Caching can assist with this, see [README](https://github.com/noelforte/eleventy-plugin-vento/blob/main/readme.md) for more information.
+
+  Vento binds its own `this` object when executing filter functions. The `this` object contains 2 keys, `this.env` and `this.data`, for getting access to both the Vento environment and the template data respectively.
+
+  In addition to Vento's object, `this.page` and `this.eleventy` are also cloned to the top level from `this.data` to maintain feature-parity with Eleventy.
+
+  With this change, you can now create filters that leverage the Vento environment. See [README](https://github.com/noelforte/eleventy-plugin-vento/blob/main/readme.md) for more info.
+
+- eb33d79: Update vento to 1.12.12
+
 ## 4.0.1
 
 ### Patch Changes
 
-- - hotfix - include `types` field in package.json to declare bundled types
+- hotfix - include `types` field in package.json to declare bundled types
 
 ## 4.0.0
 

package/dist/index.js

@@ -2,7 +2,7 @@
 import path from "node:path";
 import autotrimPlugin, { defaultTags as autotrimDefaultTags } from "ventojs/plugins/auto_trim.js";
 
-// src/create-vento-interface.ts
+// src/engine.ts
 import { default as ventojs } from "ventojs";
 
 // src/create-vento-tag.ts
@@ -10,8 +10,12 @@ function createVentoTag(spec) {
   const IS_PAIRED = spec.group === "pairedShortcodes";
   const tag = (env, code, output, tokens) => {
     if (!code.startsWith(spec.name)) return;
-    const fn = `__env.utils._11tyFns.${spec.group}.${spec.name}`;
-    const ctx = "__env.utils._11tyCtx";
+    const { dataVarname } = env.options;
+    const thisArg = `{
+			page: ${dataVarname}.page,
+			eleventy: ${dataVarname}.eleventy
+		}`;
+    const fn = `__env.utils.eleventyFunctions.${spec.group}.${spec.name}`;
     const args = [code.replace(spec.name, "").trim()];
     const varname = output.startsWith("__shortcode_content") ? `${output}_precomp` : "__shortcode_content";
     const compiled = [];
@@ -27,7 +31,7 @@ function createVentoTag(spec) {
       }
       tokens.shift();
     }
-    args.unshift(ctx);
+    args.unshift(thisArg);
     compiled.push(
       "{",
       `const __shortcode_result = await ${fn}.call(${args.filter(Boolean).join(", ")});`,
@@ -49,7 +53,7 @@ function createVentoTag(spec) {
 import createDebugger from "debug";
 var debugBaseNamespace = "Eleventy:Vento";
 var DEBUG = {
-  setup: createDebugger(`${debugBaseNamespace}:Setup`),
+  main: createDebugger(debugBaseNamespace),
   cache: createDebugger(`${debugBaseNamespace}:Cache`),
   render: createDebugger(`${debugBaseNamespace}:Render`)
 };
@@ -59,9 +63,8 @@ var REQUIRED_API_METHODS = [
   ["getFilters", "v3.0.0-alpha.15"],
   ["addExtension", "v1.0.0"]
 ];
-var CONTEXT_DATA_KEYS = ["page", "eleventy"];
 function runCompatibilityCheck(config) {
-  DEBUG.setup("Run compatibility check");
+  DEBUG.main("Run compatibility check");
   for (const [method, version] of REQUIRED_API_METHODS) {
     if (!(method in config)) {
       console.error(
@@ -75,20 +78,11 @@ function runCompatibilityCheck(config) {
   }
 }
 
-// src/create-vento-interface.ts
-function createVentoInterface(options) {
+// src/engine.ts
+function createVentoEngine(options) {
   const env = ventojs(options);
-  env.utils._11tyFns = { shortcodes: {}, pairedShortcodes: {} };
+  env.utils.eleventyFunctions = { shortcodes: {}, pairedShortcodes: {} };
   env.utils._11tyCtx = {};
-  function setContext(newContext) {
-    if (env.utils._11tyCtx?.page?.inputPath === newContext?.page?.inputPath) {
-      return;
-    }
-    for (const K of CONTEXT_DATA_KEYS) {
-      env.utils._11tyCtx[K] = newContext[K];
-    }
-    DEBUG.setup("Reload context, new context is: %o", env.utils._11tyCtx);
-  }
   function loadPlugins(plugins) {
     for (const plugin of plugins) {
       env.use(plugin);
@@ -96,18 +90,21 @@ function createVentoInterface(options) {
   }
   function loadFilters(filters) {
     for (const [name, fn] of Object.entries(filters)) {
-      env.filters[name] = fn.bind(env.utils._11tyCtx);
+      env.filters[name] = async function(...args) {
+        Object.assign(this, { page: this.data.page, eleventy: this.data.eleventy });
+        return await fn.apply(this, args);
+      };
     }
   }
   function loadShortcodes(shortcodes) {
     for (const [name, fn] of Object.entries(shortcodes)) {
-      env.utils._11tyFns.shortcodes[name] = fn;
+      env.utils.eleventyFunctions.shortcodes[name] = fn;
       env.tags.push(createVentoTag({ name, group: "shortcodes" }));
     }
   }
   function loadPairedShortcodes(pairedShortcodes) {
     for (const [name, fn] of Object.entries(pairedShortcodes)) {
-      env.utils._11tyFns.pairedShortcodes[name] = fn;
+      env.utils.eleventyFunctions.pairedShortcodes[name] = fn;
       env.tags.push(createVentoTag({ name, group: "pairedShortcodes" }));
     }
   }
@@ -131,26 +128,24 @@ ${template}`,
     }
     return template;
   }
-  async function render(template, data, from) {
-    setContext(data);
-    DEBUG.render("Rendering `%s`", from);
-    const { content } = await template(data);
-    return content;
-  }
   return {
     cache: env.cache,
     loadPlugins,
     loadFilters,
     loadShortcodes,
     loadPairedShortcodes,
-    getTemplateFunction,
-    render
+    getTemplateFunction
   };
 }
+async function renderVentoTemplate(template, data, from) {
+  DEBUG.render("Rendering `%s`", from);
+  const { content } = await template(data);
+  return content;
+}
 
 // src/index.ts
 function VentoPlugin(eleventyConfig, userOptions) {
-  DEBUG.setup("Initializing eleventy-plugin-vento");
+  DEBUG.main("Initializing eleventy-plugin-vento");
   runCompatibilityCheck(eleventyConfig);
   const options = {
     // Define defaults
@@ -165,13 +160,13 @@ function VentoPlugin(eleventyConfig, userOptions) {
     // Merge in user-provided options
     ...userOptions
   };
-  DEBUG.setup("Merged default and user config: %O", options);
+  DEBUG.main("Merged default and user config: %O", options);
   const filters = eleventyConfig.getFilters();
-  DEBUG.setup("Reading filters from Eleventy: %o", filters);
+  DEBUG.main("Reading filters from Eleventy: %o", filters);
   const shortcodes = eleventyConfig.getShortcodes();
-  DEBUG.setup("Reading shortcodes from Eleventy: %o", shortcodes);
+  DEBUG.main("Reading shortcodes from Eleventy: %o", shortcodes);
   const pairedShortcodes = eleventyConfig.getPairedShortcodes();
-  DEBUG.setup("Reading paired shortcodes from Eleventy: %o", pairedShortcodes);
+  DEBUG.main("Reading paired shortcodes from Eleventy: %o", pairedShortcodes);
   if (options.autotrim) {
     const defaults = ["@vento", "@11ty"];
     const tagSet = new Set(options.autotrim === true ? defaults : options.autotrim);
@@ -187,26 +182,26 @@ function VentoPlugin(eleventyConfig, userOptions) {
         tagSet.add(name);
       }
     }
-    DEBUG.setup("Enabled autotrim for tags: %o", tagSet);
+    DEBUG.main("Enabled autotrim for tags: %o", tagSet);
     options.plugins.push(autotrimPlugin({ tags: [...tagSet] }));
   }
-  DEBUG.setup("Initializing Vento environment");
-  const engine = createVentoInterface(options.ventoOptions);
-  DEBUG.setup("Loading plugins: %o", options.plugins);
+  DEBUG.main("Initializing Vento environment");
+  const engine = createVentoEngine(options.ventoOptions);
+  DEBUG.main("Loading plugins: %o", options.plugins);
   engine.loadPlugins(options.plugins);
   if (options.filters) {
-    DEBUG.setup("Loading filters: %o", filters);
+    DEBUG.main("Loading filters: %o", filters);
     engine.loadFilters(filters);
   }
   if (options.shortcodes) {
-    DEBUG.setup("Loading shortcodes: %o", shortcodes);
+    DEBUG.main("Loading shortcodes: %o", shortcodes);
     engine.loadShortcodes(shortcodes);
   }
   if (options.pairedShortcodes) {
-    DEBUG.setup("Loading paired shortcodes: %o", pairedShortcodes);
+    DEBUG.main("Loading paired shortcodes: %o", pairedShortcodes);
     engine.loadPairedShortcodes(pairedShortcodes);
   }
-  DEBUG.setup("Registering Vento cache handler on eleventy.beforeWatch event");
+  DEBUG.main("Registering Vento cache handler on eleventy.beforeWatch event");
   eleventyConfig.on("eleventy.beforeWatch", async (updatedFiles) => {
     for (let file of updatedFiles) {
       file = path.normalize(file);
@@ -214,30 +209,32 @@ function VentoPlugin(eleventyConfig, userOptions) {
       engine.cache.delete(file);
     }
   });
-  DEBUG.setup("Registering .vto as a template format");
+  DEBUG.main("Registering .vto as a template format");
   eleventyConfig.addTemplateFormats("vto");
-  DEBUG.setup("Registering .vto extension with eleventy");
+  DEBUG.main("Registering .vto extension with eleventy");
   eleventyConfig.addExtension("vto", {
     outputFileExtension: "html",
     read: true,
     compile(inputContent, inputPath) {
       inputPath = path.normalize(inputPath);
+      DEBUG.main("Getting template function for `%s`", inputPath);
       const template = engine.getTemplateFunction(inputContent, inputPath, false);
-      return async (data) => await engine.render(template, data, inputPath);
+      return async (data) => await renderVentoTemplate(template, data, inputPath);
     },
     compileOptions: {
       // Custom permalink compilation
       permalink(permalinkContent, inputPath) {
-        if (typeof permalinkContent === "string" && /\{\{\s+.+\s+\}\}/.test(permalinkContent)) {
-          inputPath = "Permalink::" + path.normalize(inputPath);
-          const template = engine.getTemplateFunction(permalinkContent, inputPath);
-          return async (data) => await engine.render(template, data, inputPath);
+        if (typeof permalinkContent !== "string" || !/\{\{\s+.+\s+\}\}/.test(permalinkContent)) {
+          return permalinkContent;
         }
-        return permalinkContent;
+        inputPath = "Permalink::" + path.normalize(inputPath);
+        DEBUG.main("Getting template function for `%s`", inputPath);
+        const template = engine.getTemplateFunction(permalinkContent, inputPath);
+        return async (data) => await renderVentoTemplate(template, data, inputPath);
       }
     }
   });
-  DEBUG.setup("eleventy-plugin-vento initialized");
+  DEBUG.main("eleventy-plugin-vento initialized");
 }
 export {
   VentoPlugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-vento",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Adds support for the Vento templating language to Eleventy.",
   "type": "module",
   "engines": {
@@ -37,24 +37,24 @@
   "license": "MIT",
   "dependencies": {
     "debug": "4.3.7",
-    "ventojs": "1.12.11"
+    "ventojs": "1.12.12"
   },
   "devDependencies": {
     "11ty.ts": "0.0.5",
     "@11ty/eleventy": "3.0.0",
-    "@changesets/cli": "2.27.9",
-    "@eslint/js": "9.14.0",
+    "@changesets/cli": "2.27.10",
+    "@eslint/js": "9.15.0",
     "@types/debug": "4.1.12",
     "@types/eslint-config-prettier": "6.11.3",
     "@types/eslint__js": "8.42.3",
-    "@types/node": "22.8.4",
-    "eslint": "9.14.0",
+    "@types/node": "22.9.3",
+    "eslint": "9.15.0",
     "eslint-config-prettier": "9.1.0",
-    "eslint-plugin-unicorn": "56.0.0",
+    "eslint-plugin-unicorn": "56.0.1",
     "tsup": "8.3.5",
-    "typescript": "5.6.3",
-    "typescript-eslint": "8.12.2",
-    "vitest": "2.1.4"
+    "typescript": "5.7.2",
+    "typescript-eslint": "8.15.0",
+    "vitest": "2.1.5"
   },
   "prettier": {
     "bracketSameLine": true,
@@ -68,6 +68,7 @@
     "lint": "eslint '.'",
     "ts-check": "tsc --noEmit",
     "build": "tsup",
+    "dev": "tsup --watch ./src",
     "ci:version": "changeset version && pnpm install --no-frozen-lockfile",
     "ci:publish": "changeset publish",
     "ci:generate-changesets": "node ./scripts/generate-changesets.js",

package/readme.md

@@ -90,6 +90,42 @@ Filters that are added via Eleventy's `.addFilter()` or `.addAsyncFilter()` meth
 
 If you'd prefer to set filters yourself (via a plugin or other method) or prevent Eleventy from loading filters into Vento, set `filters: false` in the plugin options.
 
+### Filters and `this`
+
+This plugin merges the keys normally expected from `this` with the `FilterThis` object Vento provides to filters. The final bound `this` object for filters is as follows:
+
+```ts
+{
+  env, // Vento environment
+  data, // all template global data
+  page, // this.page
+  eleventy, // this.eleventy
+}
+```
+
+This feature enables re-use of the Vento environment this plugin provides, within Eleventy filters. As an example use case, you could create a filter that compiles dynamic data and cache it with Vento's own cache:
+
+```js
+eleventyConfig.addFilter('vento', function (content) {
+  const res = this.env.runString(content, this.data);
+  return res.content;
+});
+```
+
+Because re-compilation introduces some overhead, you may want to cache your template strings compiled via a filter. With access to `this.env` you can use Vento's own cache:
+
+```js
+import 'hash' from 'node:crypto'; // since Node v20.12.0
+
+const sha1Hash(str) => hash('sha1', str, 'hex');
+
+eleventyConfig.addFilter('vento', function (content) {
+  const file = `dynamicString:${sha1Hash(content)}`;
+  const res = this.env.runString(content, this.data, file);
+  return res.content;
+});
+```
+
 ### Relevant documentation
 
 Vento: See [Filters](https://vento.js.org/configuration/#filters) and [Pipes](https://vento.js.org/syntax/pipes/)
@@ -202,7 +238,7 @@ Vento: See [Auto Trim Plugin](https://vento.js.org/plugins/auto-trim/).
 
 Like Eleventy, this plugin uses the [`debug`](https://www.npmjs.com/package/debug) package to handle verbose logging. The following `DEBUG` namespaces are implemented:
 
-- `Eleventy:Vento:Setup` - Logs initial setup of the plugin, loading features, pre-page compile setup steps (like changing `page` and `eleventy` objects)
+- `Eleventy:Vento` - Logs initial setup of the plugin, loading features, pre-page compile setup steps (like changing `page` and `eleventy` objects)
 - `Eleventy:Vento:Cache` - Logs updates to Vento's own internal cache, which is used in tandem with Eleventy's cache.
 - `Eleventy:Vento:Render` - Logs when templates are rendered
 
@@ -215,7 +251,7 @@ $ DEBUG='Eleventy:*' npx @11ty/eleventy
 Alternatively, use a finer grained namespace to see only the output generated by `eleventy-plugin-vento`.
 
 ```sh
-$ DEBUG='Eleventy:Vento:*' npx @11ty/eleventy
+$ DEBUG='Eleventy:Vento*' npx @11ty/eleventy
 ```
 
 ```sh