eleventy-plugin-vento 4.1.0 → 4.1.1

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # eleventy-plugin-vento
 
+## 4.1.1
+
+### Patch Changes
+
+- 335f21e: Select type updates (shouldn't affect compilation, however should improve DX)
+
+  Changes are:
+
+  - split types into separate files
+  - namespace `ventojs` type imports
+  - make `PluginOptions` optional by default
+  - make Eleventy types more readable
+  - declare a special (`EleventyVentoEnvironment`) for this plugin to replace Vento's own `Environment`
+
+- 070109a: Refactored files and functions internally that shouldn't have any impact on usage or performance:
+
+  - Split `debug` functions into separate exports, renamed `runCompatiblityCheck -> compatibilityCheck` (dd4c379b)
+  - Utilities are now split into separate files (e06a83ab)
+  - Main file renamed from `index.ts` to `plugin.ts` (1b122d2a)
+
+- c382be0: Wrap all filters as regular synchronous functions to avoid ambiguity with sync and async handling. (fixes #96)
+
+  This change enforces explicit use of the `await` keyword to unwrap returned values from filters before chaining more or printing the result.
+
+  ```diff
+  <!-- Single filters -->
+  - {{ "Hello, async!" |> someAsyncFilter }}
+  + {{ "Hello, async!" |> await someAsyncFilter }}
+
+  <!-- Filter chains -->
+  - {{ "Hello, async!" |> someAsyncFilter |> someSyncFilter }}
+  + {{ "Hello, async!" |> await someAsyncFilter |> someSyncFilter }}
+  ```
+
+  See the [Vento docs on async chains](https://vento.js.org/syntax/pipes/#chain-pipes) for more information.
+
+- 9eaa059: Update `debug` to v4.4.0
+- 0b0f96a: Update ventojs to v1.12.14
+
+## 4.1.1-beta.0
+
+### Patch Changes
+
+- 335f21e: Select type updates (shouldn't affect compilation, however should improve DX)
+
+  Changes are:
+
+  - split types into separate files
+  - namespace `ventojs` type imports
+  - make `PluginOptions` optional by default
+  - make Eleventy types more readable
+  - declare a special (`EleventyVentoEnvironment`) for this plugin to replace Vento's own `Environment`
+
+- 9eaa059: Update `debug` to v4.4.0
+- f387b5e: Update `ventojs` to v1.12.13
+- 070109a: Refactored files and functions internally that shouldn't have any impact on usage or performance:
+
+  - Split `debug` functions into separate exports, renamed `runCompatiblityCheck -> compatibilityCheck` (dd4c379b)
+  - Utilities are now split into separate files (e06a83ab)
+  - Main file renamed from `index.ts` to `plugin.ts` (1b122d2a)
+
 ## 4.1.0
 
 ### Minor Changes

package/dist/{index.d.ts → plugin.d.ts}

@@ -1,13 +1,13 @@
-import { UserConfig } from '@11ty/eleventy';
-import { Options } from 'ventojs';
+import UserConfig from '@11ty/eleventy/UserConfig';
+import { LiteralUnion } from 'type-fest';
+import * as ventojs from 'ventojs';
 import { Plugin } from 'ventojs/src/environment.js';
 
-type AutotrimConfig = boolean | ('@11ty' | '@vento' | (string & Record<never, never>))[];
-interface VentoPluginOptions {
+interface PluginOptions {
     /**
      * An array of Vento plugins
      */
-    plugins: Plugin[];
+    plugins?: Plugin[];
     /**
      * Enables Vento's autotrim plugin.
      * ```js
@@ -20,13 +20,13 @@ interface VentoPluginOptions {
      * autotrim: true
      * ```
      */
-    autotrim: AutotrimConfig;
+    autotrim?: LiteralUnion<'@11ty' | '@vento', string>[] | boolean;
     /** Enable use of Eleventy filters */
-    filters: boolean;
+    filters?: boolean;
     /** Enable use of Eleventy shortcodes */
-    shortcodes: boolean;
+    shortcodes?: boolean;
     /** Enable use of Eleventy paired shortcodes */
-    pairedShortcodes: boolean;
+    pairedShortcodes?: boolean;
     /**
      * A Vento configuration object.
      *
@@ -34,13 +34,9 @@ interface VentoPluginOptions {
      * Eleventy's own `dir.includes` location.**
      * @see {@link https://vento.js.org/configuration/}
      */
-    ventoOptions: Options;
+    ventoOptions?: ventojs.Options;
 }
 
-/**
- * @file Main plugin declaration
- */
-
-declare function VentoPlugin(eleventyConfig: UserConfig, userOptions: Partial<VentoPluginOptions>): void;
+declare function VentoPlugin(eleventyConfig: UserConfig, userOptions: PluginOptions): void;
 
 export { VentoPlugin };

package/dist/{index.js → plugin.js}

@@ -1,88 +1,65 @@
-// src/index.ts
+// src/plugin.ts
 import path from "node:path";
 import autotrimPlugin, { defaultTags as autotrimDefaultTags } from "ventojs/plugins/auto_trim.js";
 
 // src/engine.ts
-import { default as ventojs } from "ventojs";
+import createVentoEnv from "ventojs";
 
-// src/create-vento-tag.ts
-function createVentoTag(spec) {
-  const IS_PAIRED = spec.group === "pairedShortcodes";
+// src/utils/create-vento-tag.ts
+function createVentoTag(tagInfo) {
+  const IS_PAIRED = tagInfo.group === "pairedShortcodes";
+  let INT = 0;
   const tag = (env, code, output, tokens) => {
-    if (!code.startsWith(spec.name)) return;
+    if (!code.startsWith(tagInfo.name)) return;
     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 fn = `__env.utils.eleventyFunctions.${tagInfo.group}.${tagInfo.name}`;
+    const args = [code.replace(tagInfo.name, "").trim()];
     const compiled = [];
     if (IS_PAIRED) {
-      args.unshift(env.compileFilters(tokens, varname, env.options.autoescape));
+      const nestedVarname = `__arg${INT++}`;
+      args.unshift(env.compileFilters(tokens, nestedVarname, env.options.autoescape));
       compiled.push(
         "{",
-        `let ${varname} = "";`,
-        ...env.compileTokens(tokens, varname, [`/${spec.name}`])
+        `let ${nestedVarname} = "";`,
+        ...env.compileTokens(tokens, nestedVarname, [`/${tagInfo.name}`])
       );
-      if (tokens.length > 0 && (tokens[0][0] !== "tag" || tokens[0][1] !== `/${spec.name}`)) {
-        throw new Error(`Vento: Missing closing tag for ${spec.name} tag: ${code}`);
+      if (tokens.length > 0 && (tokens[0][0] !== "tag" || tokens[0][1] !== `/${tagInfo.name}`)) {
+        throw new Error(`Vento: Missing closing tag for ${tagInfo.name} tag: ${code}`);
       }
       tokens.shift();
     }
     args.unshift(thisArg);
     compiled.push(
       "{",
-      `const __shortcode_result = await ${fn}.call(${args.filter(Boolean).join(", ")});`,
-      `${output} += ${env.compileFilters(tokens, "__shortcode_result", env.options.autoescape)}`,
+      `const __result = await ${fn}.call(${args.filter(Boolean).join(", ")});`,
+      `${output} += ${env.compileFilters(tokens, "__result", env.options.autoescape)}`,
       "}"
     );
     if (IS_PAIRED) {
       compiled.push("}");
     }
-    const compiledTag = compiled.join("\n");
-    return compiledTag;
+    return compiled.join("\n");
   };
   return Object.defineProperty(tag, "name", {
-    value: spec.name + IS_PAIRED ? `PairedTag` : `Tag`
+    value: `${tagInfo.name}_${IS_PAIRED ? `EleventyPairedTag` : `EleventyTag`}`
   });
 }
 
-// src/utils.ts
+// src/utils/debuggers.ts
 import createDebugger from "debug";
 var debugBaseNamespace = "Eleventy:Vento";
-var DEBUG = {
-  main: createDebugger(debugBaseNamespace),
-  cache: createDebugger(`${debugBaseNamespace}:Cache`),
-  render: createDebugger(`${debugBaseNamespace}:Render`)
-};
-var REQUIRED_API_METHODS = [
-  ["getShortcodes", "v3.0.0-alpha.15"],
-  ["getPairedShortcodes", "v3.0.0-alpha.15"],
-  ["getFilters", "v3.0.0-alpha.15"],
-  ["addExtension", "v1.0.0"]
-];
-function runCompatibilityCheck(config) {
-  DEBUG.main("Run compatibility check");
-  for (const [method, version] of REQUIRED_API_METHODS) {
-    if (!(method in config)) {
-      console.error(
-        "[eleventy-plugin-vento] Plugin compatibility error:",
-        `\`${method}\``,
-        "not found. Please use Eleventy",
-        version,
-        "or later."
-      );
-    }
-  }
-}
+var debugMain = createDebugger(debugBaseNamespace);
+var debugCache = createDebugger(`${debugBaseNamespace}:Cache`);
+var debugRender = createDebugger(`${debugBaseNamespace}:Render`);
 
 // src/engine.ts
 function createVentoEngine(options) {
-  const env = ventojs(options);
+  const env = createVentoEnv(options);
   env.utils.eleventyFunctions = { shortcodes: {}, pairedShortcodes: {} };
-  env.utils._11tyCtx = {};
   function loadPlugins(plugins) {
     for (const plugin of plugins) {
       env.use(plugin);
@@ -90,31 +67,33 @@ function createVentoEngine(options) {
   }
   function loadFilters(filters) {
     for (const [name, fn] of Object.entries(filters)) {
-      env.filters[name] = async function(...args) {
-        Object.assign(this, { page: this.data.page, eleventy: this.data.eleventy });
-        return await fn.apply(this, args);
+      env.filters[name] = function(...args) {
+        const { page, eleventy } = this.data;
+        return fn.apply({ ...this, page, eleventy }, args);
       };
     }
   }
   function loadShortcodes(shortcodes) {
     for (const [name, fn] of Object.entries(shortcodes)) {
       env.utils.eleventyFunctions.shortcodes[name] = fn;
-      env.tags.push(createVentoTag({ name, group: "shortcodes" }));
+      const shortcodeTag = createVentoTag({ name, group: "shortcodes" });
+      env.tags.push(shortcodeTag);
     }
   }
   function loadPairedShortcodes(pairedShortcodes) {
     for (const [name, fn] of Object.entries(pairedShortcodes)) {
       env.utils.eleventyFunctions.pairedShortcodes[name] = fn;
-      env.tags.push(createVentoTag({ name, group: "pairedShortcodes" }));
+      const shortcodeTag = createVentoTag({ name, group: "pairedShortcodes" });
+      env.tags.push(shortcodeTag);
     }
   }
   function getTemplateFunction(source, file, useVentoCache = true) {
     let template = env.cache.get(file);
-    if (template?.source === source) {
-      DEBUG.cache("Cache HIT for `%s`, used precompiled template", file);
+    if ((template == null ? void 0 : template.source) === source) {
+      debugCache("Cache HIT for `%s`, used precompiled template", file);
     } else {
       template = env.compile(source, file);
-      DEBUG.cache(
+      debugCache(
         `Cache MISS for \`%s\`, compiled new template:
 Use Vento cache: %o
 
@@ -138,15 +117,37 @@ ${template}`,
   };
 }
 async function renderVentoTemplate(template, data, from) {
-  DEBUG.render("Rendering `%s`", from);
+  debugRender("Rendering `%s`", from);
   const { content } = await template(data);
   return content;
 }
 
-// src/index.ts
+// src/utils/compat-check.ts
+var REQUIRED_API_METHODS = [
+  ["getShortcodes", "v3.0.0-alpha.15"],
+  ["getPairedShortcodes", "v3.0.0-alpha.15"],
+  ["getFilters", "v3.0.0-alpha.15"],
+  ["addExtension", "v1.0.0"]
+];
+function compatibilityCheck(config) {
+  debugMain("Run compatibility check");
+  for (const [method, version] of REQUIRED_API_METHODS) {
+    if (!(method in config)) {
+      console.error(
+        "[eleventy-plugin-vento] Plugin compatibility error:",
+        `\`${method}\``,
+        "not found. Please use Eleventy",
+        version,
+        "or later."
+      );
+    }
+  }
+}
+
+// src/plugin.ts
 function VentoPlugin(eleventyConfig, userOptions) {
-  DEBUG.main("Initializing eleventy-plugin-vento");
-  runCompatibilityCheck(eleventyConfig);
+  debugMain("Initializing eleventy-plugin-vento");
+  compatibilityCheck(eleventyConfig);
   const options = {
     // Define defaults
     autotrim: false,
@@ -160,13 +161,13 @@ function VentoPlugin(eleventyConfig, userOptions) {
     // Merge in user-provided options
     ...userOptions
   };
-  DEBUG.main("Merged default and user config: %O", options);
+  debugMain("Merged default and user config: %O", options);
   const filters = eleventyConfig.getFilters();
-  DEBUG.main("Reading filters from Eleventy: %o", filters);
+  debugMain("Reading filters from Eleventy: %o", filters);
   const shortcodes = eleventyConfig.getShortcodes();
-  DEBUG.main("Reading shortcodes from Eleventy: %o", shortcodes);
+  debugMain("Reading shortcodes from Eleventy: %o", shortcodes);
   const pairedShortcodes = eleventyConfig.getPairedShortcodes();
-  DEBUG.main("Reading paired shortcodes from Eleventy: %o", pairedShortcodes);
+  debugMain("Reading paired shortcodes from Eleventy: %o", pairedShortcodes);
   if (options.autotrim) {
     const defaults = ["@vento", "@11ty"];
     const tagSet = new Set(options.autotrim === true ? defaults : options.autotrim);
@@ -182,42 +183,42 @@ function VentoPlugin(eleventyConfig, userOptions) {
         tagSet.add(name);
       }
     }
-    DEBUG.main("Enabled autotrim for tags: %o", tagSet);
+    debugMain("Enabled autotrim for tags: %o", tagSet);
     options.plugins.push(autotrimPlugin({ tags: [...tagSet] }));
   }
-  DEBUG.main("Initializing Vento environment");
+  debugMain("Initializing Vento environment");
   const engine = createVentoEngine(options.ventoOptions);
-  DEBUG.main("Loading plugins: %o", options.plugins);
+  debugMain("Loading plugins: %o", options.plugins);
   engine.loadPlugins(options.plugins);
   if (options.filters) {
-    DEBUG.main("Loading filters: %o", filters);
+    debugMain("Loading filters: %o", filters);
     engine.loadFilters(filters);
   }
   if (options.shortcodes) {
-    DEBUG.main("Loading shortcodes: %o", shortcodes);
+    debugMain("Loading shortcodes: %o", shortcodes);
     engine.loadShortcodes(shortcodes);
   }
   if (options.pairedShortcodes) {
-    DEBUG.main("Loading paired shortcodes: %o", pairedShortcodes);
+    debugMain("Loading paired shortcodes: %o", pairedShortcodes);
     engine.loadPairedShortcodes(pairedShortcodes);
   }
-  DEBUG.main("Registering Vento cache handler on eleventy.beforeWatch event");
+  debugMain("Registering Vento cache handler on eleventy.beforeWatch event");
   eleventyConfig.on("eleventy.beforeWatch", async (updatedFiles) => {
     for (let file of updatedFiles) {
       file = path.normalize(file);
-      DEBUG.cache("Delete cache entry for %s", file);
+      debugCache("Delete cache entry for %s", file);
       engine.cache.delete(file);
     }
   });
-  DEBUG.main("Registering .vto as a template format");
+  debugMain("Registering .vto as a template format");
   eleventyConfig.addTemplateFormats("vto");
-  DEBUG.main("Registering .vto extension with eleventy");
+  debugMain("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);
+      debugMain("Getting template function for `%s`", inputPath);
       const template = engine.getTemplateFunction(inputContent, inputPath, false);
       return async (data) => await renderVentoTemplate(template, data, inputPath);
     },
@@ -228,13 +229,13 @@ function VentoPlugin(eleventyConfig, userOptions) {
           return permalinkContent;
         }
         inputPath = "Permalink::" + path.normalize(inputPath);
-        DEBUG.main("Getting template function for `%s`", inputPath);
+        debugMain("Getting template function for `%s`", inputPath);
         const template = engine.getTemplateFunction(permalinkContent, inputPath);
         return async (data) => await renderVentoTemplate(template, data, inputPath);
       }
     }
   });
-  DEBUG.main("eleventy-plugin-vento initialized");
+  debugMain("eleventy-plugin-vento initialized");
 }
 export {
   VentoPlugin

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "eleventy-plugin-vento",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "Adds support for the Vento templating language to Eleventy.",
   "type": "module",
   "engines": {
     "node": ">=18"
   },
-  "types": "./dist/index.d.ts",
+  "types": "./dist/plugin.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": "./dist/plugin.js",
+      "types": "./dist/plugin.d.ts"
     }
   },
   "files": [
@@ -36,25 +36,27 @@
   },
   "license": "MIT",
   "dependencies": {
-    "debug": "4.3.7",
-    "ventojs": "1.12.12"
+    "debug": "4.4.0",
+    "ventojs": "1.12.14"
   },
   "devDependencies": {
     "11ty.ts": "0.0.5",
-    "@11ty/eleventy": "3.0.0",
-    "@changesets/cli": "2.27.10",
-    "@eslint/js": "9.15.0",
+    "@11ty/eleventy": "3.0.1-alpha.1",
+    "@changesets/cli": "2.27.11",
+    "@eslint/js": "9.17.0",
     "@types/debug": "4.1.12",
     "@types/eslint-config-prettier": "6.11.3",
     "@types/eslint__js": "8.42.3",
-    "@types/node": "22.9.3",
-    "eslint": "9.15.0",
+    "@types/node": "22.10.5",
+    "eslint": "9.17.0",
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-unicorn": "56.0.1",
+    "globals": "15.14.0",
     "tsup": "8.3.5",
+    "type-fest": "4.31.0",
     "typescript": "5.7.2",
-    "typescript-eslint": "8.15.0",
-    "vitest": "2.1.5"
+    "typescript-eslint": "8.19.0",
+    "vitest": "2.1.8"
   },
   "prettier": {
     "bracketSameLine": true,
@@ -64,14 +66,13 @@
   },
   "scripts": {
     "test": "vitest --run",
-    "check": "pnpm --color run '/ts-check|lint/'",
-    "lint": "eslint '.'",
-    "ts-check": "tsc --noEmit",
+    "check": "pnpm --color run '/^check:/'",
+    "check:lint": "eslint '.'",
+    "check:types": "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",
     "format": "pnpm dlx prettier --config ./package.json --write ."
   }
 }

package/readme.md

@@ -62,9 +62,6 @@ export default function (eleventyConfig) {
     // to trim the default tags (see section on Auto-trimming)
     autotrim: false,
 
-    // Enable/disable ignore tag syntax (see section on ignoring tags)
-    ignoreTag: false,
-
     // A Vento configuration object
     ventoOptions: {
       includes: eleventyConfig.directories.includes,
@@ -92,27 +89,9 @@ If you'd prefer to set filters yourself (via a plugin or other method) or preven
 
 ### 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;
-});
-```
+Eleventy provides filters with scoped data via the `this.page` and `this.eleventy` objects (see [Filters#Scoped data in Filters](https://www.11ty.dev/docs/filters/#scoped-data-in-filters) in Eleventy's docs for more details). Likewise, Vento provides filters with `this.env` and `this.data` representing the Vento environment and the current template data. This plugin merges both objects together to make `this.page` (and `eleventy`/`env`/`data`) available on all filters processed by Vento.
 
-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:
+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 to improve performance:
 
 ```js
 import 'hash' from 'node:crypto'; // since Node v20.12.0
@@ -180,7 +159,8 @@ Eleventy: See [Shortcodes](https://www.11ty.dev/docs/shortcodes/) and the sub-se
 
 ## Vento Plugins
 
-_Note: The `auto_trim` plugin that ships with Vento has a specific implementation in the scope of this plugin. See [Auto-Trimming Tags](#auto-trimming-tags) for more details._
+> [!NOTE]
+> The `auto_trim` plugin that ships with Vento has a specific implementation in the scope of this plugin. See [Auto-Trimming Tags](#auto-trimming-tags) for more details.\_
 
 If you'd like to extend the Vento library with any plugins, include them in an array passed to the `plugins` option.