eleventy-plugin-vento 3.0.2 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # eleventy-plugin-vento
 
+## 3.1.0
+
+### Minor Changes
+
+- 7e6ba68: Separate `shortcodes` and `pairedShortcodes` into seperate object namespaces. Prior to this version, Eleventy shortcodes and paired shortcodes were merged into a single object keyed as `_11ty.functions` which allowed for naming collisions between shortcodes and their paired counterparts.
+- b8f0a03: Adds new dependency on `debug` package, to help out with testing and getting more verbose logs. 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:Cache` - Logs updates to Vento's own internal cache, which is used in tandem with Eleventy's cache.
+  - `Eleventy:Vento:Template` - Logs rendered templates and other template related actions
+
+  Because it is a child of the `Eleventy:` namespace, the following command will include output from this plugin as well:
+
+  ```sh
+  $ 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
+  ```
+
+  ```sh
+  $ DEBUG='Eleventy:Vento:Template' npx @11ty/eleventy
+  ```
+
+  See [the docs on 11ty.dev](https://www.11ty.dev/docs/debugging/) as well as the [debug package README](https://github.com/debug-js/debug/blob/master/README.md) for more information.
+
+- ec02a76: Further caching improvements to e8111234 and e46ce6ea. Eleventy now defers all template caching to Vento.
+
+  Templates are now compiled directly instead of using Vento's `.runString` method which reduces overhead and enables this plugin to manage the Vento cache in a more direct manner.
+
+- 494b184: Permalink compilation optimizations:
+
+  - Permalinks now short-circuit to raw strings if they don't contain Vento template syntax, avoiding compilation entirely.
+  - Permalinks are now assigned (fake) pathnames in Vento's cache. If you change template content but don't change a dynamic permalink in development, Vento will reuse the compiled permalink template. Note that **any** modifications to a template file will **always** cause it to be recompiled (see 19c352fa) — this improvement just optimizes recompiling dynamic permalinks that haven't changed.
+
+### Patch Changes
+
+- 4b4b387: Entries for changed files are now deleted from Vento's cache when running the Eleventy Dev server. (fixes #38)
+
+## 3.0.3-next.0
+
+### Patch Changes
+
+- e811123: Partially reverts e46ce6ea, refine caching logic. Pre-compile, the plugin checks the Vento cache to see what source needs compiling and if that matches what was already compiled. If not, then the cache is cleared so Vento can recompile.
+- 2f32efb: Clear Vento cache on every template change, to help with #38. Resolution is still WIP.
+
 ## 3.0.2
 
 ### Patch Changes

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "eleventy-plugin-vento",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Adds support for the Vento templating language to Eleventy.",
   "type": "module",
   "engines": {
     "node": ">=16"
   },
+  "imports": {
+    "#11ty-test": "./tests/_utils/eleventy-test.js"
+  },
   "exports": {
     ".": {
       "import": "./src/index.js"
@@ -32,18 +35,19 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
+    "debug": "4.3.7",
     "ventojs": "1.12.10"
   },
   "devDependencies": {
     "@11ty/eleventy": "3.0.0",
     "@changesets/cli": "2.27.9",
-    "eslint": "9.12.0",
+    "@eslint/js": "9.13.0",
+    "eslint": "9.13.0",
     "eslint-config-flat-gitignore": "0.3.0",
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-unicorn": "56.0.0",
     "globals": "15.11.0",
-    "vitest": "2.1.2",
-    "zx": "8.1.9"
+    "vitest": "2.1.3"
   },
   "prettier": {
     "bracketSameLine": true,

package/readme.md

@@ -265,3 +265,33 @@ Rather than having to do multiple `{{ /echo }} ... {{ echo }}` statements, the p
   <p>Page built on: 09-19-2024</p>
 {{ /if }}
 ```
+
+## Debugging
+
+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:Cache` - Logs updates to Vento's own internal cache, which is used in tandem with Eleventy's cache.
+- `Eleventy:Vento:Template` - Logs rendered templates and other template related actions
+
+Because it is a child of the `Eleventy:` namespace, the following command will include output from this plugin as well:
+
+```sh
+$ 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
+```
+
+```sh
+$ DEBUG='Eleventy:Vento:Template' npx @11ty/eleventy
+```
+
+### Relevant Documentation
+
+Eleventy: See [Debug Mode](https://www.11ty.dev/docs/debugging/).
+
+Debug: See [`debug` on npm](https://www.npmjs.com/package/debug).

package/src/engine.js

@@ -16,24 +16,16 @@ import ventojs from 'ventojs';
 
 // Internal modules
 import { createVentoTag } from './modules/create-vento-tag.js';
-import { CONTEXT_DATA_KEYS } from './modules/utils.js';
+import { DEBUG, CONTEXT_DATA_KEYS } from './modules/utils.js';
 
 /** @param {import('ventojs').Options} options */
 export function createVentoEngine(options) {
 	/** @type {EleventyVentoEnvironment} */
 	const env = ventojs(options);
-	env.utils._11ty = { ctx: {}, functions: {} };
+	env.utils._11ty = { ctx: {}, shortcodes: {}, pairedShortcodes: {} };
 
 	return {
-		/** @param {string} path */
-		getCachedSource(path) {
-			return env.cache.get(path)?.source;
-		},
-
-		/** @param {string} path */
-		emptyCache(path) {
-			return path ? env.cache.delete(path) : env.cache.clear();
-		},
+		cache: env.cache,
 
 		/** @param {import('ventojs/src/environment.js').Plugin[]} plugins */
 		loadPlugins(plugins) {
@@ -57,26 +49,47 @@ export function createVentoEngine(options) {
 			}
 		},
 
-		/**
-		 * @param {Record<string, EleventyFunction>} shortcodes
-		 * @param {boolean} paired
-		 */
-		loadShortcodes(shortcodes, paired = false) {
+		/** @param {Record<string, EleventyFunction>} shortcodes */
+		loadShortcodes(shortcodes) {
 			for (const [name, fn] of Object.entries(shortcodes)) {
-				env.utils._11ty.functions[name] = fn;
-				env.tags.push(createVentoTag(name, paired));
+				env.utils._11ty.shortcodes[name] = fn;
+				env.tags.push(createVentoTag({ name, group: 'shortcodes' }));
+			}
+		},
+
+		/** @param {Record<string, EleventyFunction>} pairedShortcodes */
+		loadPairedShortcodes(pairedShortcodes) {
+			for (const [name, fn] of Object.entries(pairedShortcodes)) {
+				env.utils._11ty.pairedShortcodes[name] = fn;
+				env.tags.push(createVentoTag({ name, group: 'pairedShortcodes' }));
 			}
 		},
 
-		/** @param {{data: PageData, source: string, path: string}} input */
+		/** @param {{ source: string, data: PageData, file?: string }} input */
 		async process(input) {
 			// Reload context
 			this.loadContext(input.data);
+			DEBUG.setup('Reloaded Eleventy/Vento context. New value: %o', env.utils._11ty.ctx);
+
+			// Retrieve the template from the cache
+			let template = env.cache.get(input.file);
+
+			if (template?.source === input.source) {
+				DEBUG.cache('Cache HIT for `%s`, used precompiled template', input.file);
+			} else {
+				template = env.compile(input.source, input.file);
+
+				if (input.file) {
+					DEBUG.cache('Cache MISS for `%s`, compiled new template', input.file);
+					env.cache.set(input.file, template);
+				}
+			}
 
-			// Process the templates
-			const result = await env.runString(input.source, input.data, input.path);
+			// Run the template
+			DEBUG.template(template.code);
+			const { content } = await template(input.data);
 
-			return result.content;
+			return content;
 		},
 	};
 }

package/src/index.js

@@ -20,20 +20,35 @@
  * (See [Vento Docs](https://vento.js.org/configuration/#options))
  */
 
+// Built-ins
+import path from 'node:path';
+
 // External modules
 import autotrimPlugin, { defaultTags as autotrimDefaultTags } from 'ventojs/plugins/auto_trim.js';
 
 // Local modules
 import { createVentoEngine } from './engine.js';
 import { ignoreTagPlugin } from './modules/ignore-tag.js';
-import { runCompatibilityCheck } from './modules/utils.js';
+import { DEBUG, PERMALINK_PREFIX, REQUIRED_API_METHODS } from './modules/utils.js';
 
 /**
  * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
  * @param {Partial<VentoPluginOptions>} userOptions
  */
 export function VentoPlugin(eleventyConfig, userOptions) {
-	runCompatibilityCheck(eleventyConfig);
+	DEBUG.setup('Initializing eleventy-plugin-vento');
+	DEBUG.setup('Run compatibility check');
+	for (const [method, version] of REQUIRED_API_METHODS) {
+		if (!eleventyConfig?.[method]) {
+			console.error(
+				'[eleventy-plugin-vento] Plugin compatibility error:',
+				`\`${method}\``,
+				'not found. Please use Eleventy',
+				version,
+				'or later.'
+			);
+		}
+	}
 
 	/** @type {VentoPluginOptions} */
 	const options = {
@@ -52,10 +67,17 @@ export function VentoPlugin(eleventyConfig, userOptions) {
 		...userOptions,
 	};
 
+	DEBUG.setup('Merged default and user config: %O', options);
+
 	// Get list of filters, shortcodes and paired shortcodes
 	const filters = eleventyConfig.getFilters();
+	DEBUG.setup('Reading filters from Eleventy: %o', filters);
+
 	const shortcodes = eleventyConfig.getShortcodes();
+	DEBUG.setup('Reading shortcodes from Eleventy: %o', shortcodes);
+
 	const pairedShortcodes = eleventyConfig.getPairedShortcodes();
+	DEBUG.setup('Reading paired shortcodes from Eleventy: %o', pairedShortcodes);
 
 	// Add autotrim plugin if enabled
 	if (options.autotrim) {
@@ -78,61 +100,79 @@ export function VentoPlugin(eleventyConfig, userOptions) {
 			}
 		}
 
+		DEBUG.setup('Enabled autotrim for tags: %o', tagSet);
+
 		options.plugins.push(autotrimPlugin({ tags: [...tagSet] }));
 	}
 
 	// Add ignore tag plugin if enabled
 	if (options.ignoreTag) {
+		DEBUG.setup('Enabling `{{! ... }}` tag syntax');
 		options.plugins.push(ignoreTagPlugin);
 	}
 
 	// Create the vento engine instance
+	DEBUG.setup('Initializing Vento environment');
 	const engine = createVentoEngine(options.ventoOptions);
 
 	// Load plugins
+	DEBUG.setup('Loading plugins: %o', options.plugins);
 	engine.loadPlugins(options.plugins);
 
 	// Add filters, single and paired shortcodes if enabled
 	if (options.filters) {
+		DEBUG.setup('Loading filters: %o', filters);
 		engine.loadFilters(filters);
 	}
 	if (options.shortcodes) {
-		engine.loadShortcodes(shortcodes, false);
+		DEBUG.setup('Loading shortcodes: %o', shortcodes);
+		engine.loadShortcodes(shortcodes);
 	}
 	if (options.pairedShortcodes) {
-		engine.loadShortcodes(pairedShortcodes, true);
+		DEBUG.setup('Loading paired shortcodes: %o', pairedShortcodes);
+		engine.loadPairedShortcodes(pairedShortcodes);
 	}
 
+	// Handle emptying the cache when files are updated
+	DEBUG.setup('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);
+			engine.cache.delete(file);
+		}
+	});
+
 	// Add vto as a template format
+	DEBUG.setup('Registering .vto as a template format');
 	eleventyConfig.addTemplateFormats('vto');
 
 	// Add extension handling
+	DEBUG.setup('Registering .vto extension with eleventy');
 	eleventyConfig.addExtension('vto', {
 		outputFileExtension: 'html',
 		read: true,
 
 		// Main compile function
-		async compile(inputContent, inputPath) {
-			return async (data) => await engine.process({ data, source: inputContent, path: inputPath });
+		async compile(source, file) {
+			file = path.normalize(file);
+			return async (data) => await engine.process({ source, data, file });
 		},
 
-		// Custom permalink compilation
 		compileOptions: {
-			cache: true,
-			getCacheKey(inputContent, inputPath) {
-				if (engine.getCachedSource(inputPath) !== inputContent) {
-					engine.emptyCache(inputPath);
-				}
-
-				return engine.getCachedSource(inputPath);
-			},
-			permalink(linkContents) {
-				if (typeof linkContents !== 'string') {
-					return linkContents;
+			// Defer all caching to Vento
+			cache: false,
+			// Custom permalink compilation
+			permalink(source, file) {
+				// Short circuit if input isn't a string and doesn't look like a vento template
+				if (typeof source === 'string' && /\{\{\s+.+\s+\}\}/.test(source)) {
+					file = PERMALINK_PREFIX + path.normalize(file);
+					return async (data) => engine.process({ source, data, file });
 				}
 
-				return async (data) => engine.process({ data, source: linkContents });
+				return source;
 			},
 		},
 	});
+	DEBUG.setup('eleventy-plugin-vento initialized');
 }

package/src/modules/create-vento-tag.js

@@ -1,19 +1,20 @@
 /**
  * @file Helper function that creates vento tags from eleventy functions
  *
- * @param {string} name
- * @param {boolean} paired
+ * @param {{name: string, group: 'shortcodes' | 'pairedShortcodes' }} options
  */
 
-export function createVentoTag(name, paired) {
+export function createVentoTag(options) {
+	const IS_PAIRED = options.group === 'pairedShortcodes';
+
 	/** @type {import("ventojs/src/environment.js").Tag} */
 	const tag = (env, code, output, tokens) => {
-		if (!code.startsWith(name)) return;
+		if (!code.startsWith(options.name)) return;
 
-		// Declare helper object path strings
-		const fn = `__env.utils._11ty.functions.${name}`;
+		// Declare helper variables for repeated strings in template
+		const fn = `__env.utils._11ty.${options.group}.${options.name}`;
 		const ctx = '__env.utils._11ty.ctx';
-		let args = [code.replace(name, '').trim()];
+		const args = [code.replace(options.name, '').trim()];
 
 		const varname = output.startsWith('__shortcode_content')
 			? `${output}_precomp`
@@ -22,35 +23,38 @@ export function createVentoTag(name, paired) {
 		// Create an array to hold compiled template code
 		const compiled = [];
 
-		if (paired) {
+		if (IS_PAIRED) {
 			args.unshift(env.compileFilters(tokens, varname, env.options.autoescape));
 			compiled.push(
 				'{',
 				`let ${varname} = "";`,
-				...env.compileTokens(tokens, varname, [`/${name}`])
+				...env.compileTokens(tokens, varname, [`/${options.name}`])
 			);
-			if (tokens.length > 0 && (tokens[0][0] !== 'tag' || tokens[0][1] !== `/${name}`)) {
-				throw new Error(`Missing closing tag for ${name} tag: ${code}`);
+			if (tokens.length > 0 && (tokens[0][0] !== 'tag' || tokens[0][1] !== `/${options.name}`)) {
+				throw new Error(`Vento: Missing closing tag for ${options.name} tag: ${code}`);
 			}
 			tokens.shift();
 		}
 
-		// Compile arguments into a string
-		args = args.some(Boolean) ? `, ${args.filter(Boolean).join(', ')}` : '';
+		args.unshift(ctx);
 
 		compiled.push(
 			'{',
-			`const __shortcode_result = await ${fn}.call(${ctx + args});`,
+			`const __shortcode_result = await ${fn}.call(${args.filter(Boolean).join(', ')});`,
 			`${output} += ${env.compileFilters(tokens, '__shortcode_result', env.options.autoescape)}`,
 			'}'
 		);
 
-		if (paired) compiled.push('}');
+		if (IS_PAIRED) {
+			compiled.push('}');
+		}
 
-		// console.log(compiled);
+		const compiledTag = compiled.join('\n');
 
-		return compiled.join('\n');
+		return compiledTag;
 	};
 
-	return Object.defineProperty(tag, 'name', { value: paired ? `${name}PairedTag` : `${name}Tag` });
+	return Object.defineProperty(tag, 'name', {
+		value: options.name + IS_PAIRED ? `PairedTag` : `Tag`,
+	});
 }

package/src/modules/utils.js

@@ -1,3 +1,12 @@
+// Set up debugger global
+import createDebugger from 'debug';
+const debugBaseNamespace = 'Eleventy:Vento';
+export const DEBUG = {
+	setup: createDebugger(`${debugBaseNamespace}:Setup`),
+	cache: createDebugger(`${debugBaseNamespace}:Cache`),
+	template: createDebugger(`${debugBaseNamespace}:Template`),
+};
+
 // Project-wide constants
 export const REQUIRED_API_METHODS = [
 	['getShortcodes', 'v3.0.0-alpha.15'],
@@ -8,18 +17,4 @@ export const REQUIRED_API_METHODS = [
 
 export const CONTEXT_DATA_KEYS = ['page', 'eleventy'];
 
-// Project-wide helper functions
-export function logError(message) {
-	console.error(`[eleventy-plugin-vento] ${message}`);
-}
-
-/** @param {import("@11ty/eleventy").UserConfig} configApi */
-export function runCompatibilityCheck(configApi) {
-	for (const [method, version] of REQUIRED_API_METHODS) {
-		if (!configApi?.[method]) {
-			logError(
-				`Eleventy plugin compatibility error: '${method}' not available. Use Eleventy ${version} or later.`
-			);
-		}
-	}
-}
+export const PERMALINK_PREFIX = 'EleventyVentoPermalink:';