eleventy-plugin-vento 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # eleventy-plugin-vento
 
+## 3.2.0
+
+### Minor Changes
+
+- f9388e1: Further refine caching between Eleventy and Vento: commit ec02a765 deferred **all** caching to Vento and turned off Eleventy's cache (released in 3.1.0). This release allows Vento to cache only the templates that Eleventy can't cache (permalinks, includes, etc.), and Eleventy caches everything else.
+
+  A performance oversight has also been resolved by this change. Now, template functions are pre-compiled and saved by Eleventy, only running the template on render without having to go through a re-compile or get a template from the cache.
+
+### Patch Changes
+
+- 693e1a2: Refactored the following features internally:
+
+  - Reverts 2c3548c1 for modularity: The compatibility check has moved back to `modules/utils.js`
+  - Revises caching further: Instead of deferring to Vento for everything, permalink templates and templates loaded by Vento (like includes) are cached by Vento. Everything else is cached by Eleventy.
+  - Rename some internal variables to help with readability (`_11ty.ctx => _11Ctx`)
+  - `DEBUG` key `Eleventy:Vento:Template` renamed to `Eleventy:Vento:Render`
+  - Declare engine functions separately and return as an object after everything has been declared.
+
 ## 3.1.0
 
 ### Minor Changes

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "eleventy-plugin-vento",
-  "version": "3.1.0",
+  "version": "3.2.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"
@@ -47,7 +44,7 @@
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-unicorn": "56.0.0",
     "globals": "15.11.0",
-    "vitest": "2.1.3"
+    "vitest": "2.1.4"
   },
   "prettier": {
     "bracketSameLine": true,
@@ -56,7 +53,7 @@
     "trailingComma": "es5"
   },
   "scripts": {
-    "test": "vitest --run",
+    "test": "vitest",
     "lint": "eslint '**/*.js'",
     "ci:version": "changeset version && pnpm install --no-frozen-lockfile",
     "ci:publish": "changeset publish",

package/readme.md

@@ -17,6 +17,7 @@ An [Eleventy](https://11ty.dev/) plugin that adds support for [Vento](https://ve
 [Vento Plugins](#vento-plugins)<br>
 [Auto-Trimming Tags](#auto-trimming-tags)<br>
 [Ignoring Tags](#ignoring-tags)<br>
+[Debugging](#debugging)<br>
 
 ## Installing
 
@@ -28,7 +29,7 @@ npm install eleventy-plugin-vento
 
 This plugin is ESM only and cannot be required from CommonJS.
 
-If you're using CommonJS and loading it asynchronously (ie `await import`), you will need at **minimum** Eleventy v3.0.0-alpha.15 which provides internal methods this plugin uses to get Eleventy stuff from the config API.
+If you're using CommonJS and loading it asynchronously (ie `await import`), you will need at **minimum** Eleventy v3.0.0-alpha.15 which provides internal methods this plugin uses to retrieve Eleventy features from the config API.
 
 In your Eleventy config:
 
@@ -101,7 +102,7 @@ Eleventy: See [Filters](https://www.11ty.dev/docs/filters/)
 > [!NOTE]
 > Remember, Vento can print any return value from a Javascript expression, as well as [run arbitrary JavaScript](https://vento.js.org/syntax/javascript/) in templates through its `{{> ...}}` operator. In these cases, shortcodes may not be needed depending on your usage.
 
-Single and Paired Shortcodes added via Eleventy's `.addShortcode()`, `addAsyncShortcode()`, `addPairedShortcode()` or `.addAsyncPairedShortcode()` will be automatically loaded into Vento.
+Single and Paired Shortcodes added via Eleventy's `.addShortcode()`, `.addAsyncShortcode()`, `.addPairedShortcode()` or `.addAsyncPairedShortcode()` will be automatically loaded into Vento.
 
 When using shortcodes in your templates, write them like any other Vento tag:
 
@@ -272,7 +273,7 @@ Like Eleventy, this plugin uses the [`debug`](https://www.npmjs.com/package/debu
 
 - `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
+- `Eleventy:Vento:Render` - Logs when templates are rendered
 
 Because it is a child of the `Eleventy:` namespace, the following command will include output from this plugin as well:
 

package/src/engine.js

@@ -3,11 +3,15 @@
  * a simple API for Eleventy to interface with.
  *
  * @typedef {{eleventy?: Record<string, unknown>, page?: Record<string, unknown>}} EleventyContext
- * @typedef {Context & Record<string, unknown>} EleventyData
+ * @typedef {EleventyContext & Record<string, unknown>} EleventyData
  * @typedef {(...args: unknown[]) => unknown} EleventyFunction
+ * @typedef {Record<string, EleventyFunction>} EleventyFunctionSet
  * @typedef {import('ventojs/src/environment.js').Environment} VentoEnvironment
  * @typedef {VentoEnvironment & {
- *   utils: { _11ty: { ctx: Context, tags: Record<string, EleventyFunction> } }
+ *  utils: {
+ * 	_11tyFns: { shortcodes: EleventyFunctionSet, pairedShortcodes: EleventyFunctionSet }
+ * 	_11tyCtx: EleventyContext
+ * }
  * }} EleventyVentoEnvironment
  */
 
@@ -16,80 +20,107 @@ import ventojs from 'ventojs';
 
 // Internal modules
 import { createVentoTag } from './modules/create-vento-tag.js';
-import { DEBUG, CONTEXT_DATA_KEYS } from './modules/utils.js';
+import { CONTEXT_DATA_KEYS, DEBUG } from './modules/utils.js';
 
 /** @param {import('ventojs').Options} options */
 export function createVentoEngine(options) {
 	/** @type {EleventyVentoEnvironment} */
 	const env = ventojs(options);
-	env.utils._11ty = { ctx: {}, shortcodes: {}, pairedShortcodes: {} };
+	env.utils._11tyFns = { shortcodes: {}, pairedShortcodes: {} };
+	env.utils._11tyCtx = {};
 
-	return {
-		cache: env.cache,
+	/** @param {EleventyData} newContext */
+	function setContext(newContext) {
+		if (env.utils._11tyCtx?.page?.inputPath === newContext?.page?.inputPath) {
+			return;
+		}
 
-		/** @param {import('ventojs/src/environment.js').Plugin[]} plugins */
-		loadPlugins(plugins) {
-			for (const plugin of plugins) {
-				env.use(plugin);
-			}
-		},
+		for (const K of CONTEXT_DATA_KEYS) {
+			env.utils._11tyCtx[K] = newContext[K];
+		}
 
-		/** @param {PageData} newContext  */
-		loadContext(newContext) {
-			// Loop through allowed keys and load those into the context
-			for (const K of CONTEXT_DATA_KEYS) {
-				env.utils._11ty.ctx[K] = newContext[K];
-			}
-		},
+		DEBUG.setup('Reload context, new context is: %o', env.utils._11tyCtx);
+	}
 
-		/** @param {Record<string, EleventyFunction>} filters */
-		loadFilters(filters) {
-			for (const [name, fn] of Object.entries(filters)) {
-				env.filters[name] = (...args) => fn.apply(env.utils._11ty.ctx, args);
-			}
-		},
+	/** @param {import('ventojs/src/environment.js').Plugin[]} plugins */
+	function loadPlugins(plugins) {
+		for (const plugin of plugins) {
+			env.use(plugin);
+		}
+	}
 
-		/** @param {Record<string, EleventyFunction>} shortcodes */
-		loadShortcodes(shortcodes) {
-			for (const [name, fn] of Object.entries(shortcodes)) {
-				env.utils._11ty.shortcodes[name] = fn;
-				env.tags.push(createVentoTag({ name, group: 'shortcodes' }));
-			}
-		},
+	/** @param {Record<string, EleventyFunction>} filters */
+	function loadFilters(filters) {
+		for (const [name, fn] of Object.entries(filters)) {
+			env.filters[name] = fn.bind(env.utils._11tyCtx);
+		}
+	}
 
-		/** @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 {{ 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);
-				}
+	/** @param {Record<string, EleventyFunction>} shortcodes */
+	function loadShortcodes(shortcodes) {
+		for (const [name, fn] of Object.entries(shortcodes)) {
+			env.utils._11tyFns.shortcodes[name] = fn;
+			env.tags.push(createVentoTag({ name, group: 'shortcodes' }));
+		}
+	}
+
+	/** @param {Record<string, EleventyFunction>} pairedShortcodes */
+	function loadPairedShortcodes(pairedShortcodes) {
+		for (const [name, fn] of Object.entries(pairedShortcodes)) {
+			env.utils._11tyFns.pairedShortcodes[name] = fn;
+			env.tags.push(createVentoTag({ name, group: 'pairedShortcodes' }));
+		}
+	}
+
+	/**
+	 * @param {string} source
+	 * @param {string} file
+	 * @param {boolean} [useVentoCache=true]
+	 */
+	function getTemplateFunction(source, file, useVentoCache = true) {
+		// Attempt to retrieve template function from cache
+		let template = env.cache.get(file);
+
+		if (template?.source === source) {
+			DEBUG.cache('Cache HIT for `%s`, used precompiled template', file);
+		} else {
+			template = env.compile(source, file);
+
+			DEBUG.cache(
+				`Cache MISS for \`%s\`, compiled new template:\nUse Vento cache: %o\n\n${template}`,
+				file,
+				useVentoCache
+			);
+			if (useVentoCache) {
+				env.cache.set(file, template);
 			}
+		}
+
+		return template;
+	}
 
-			// Run the template
-			DEBUG.template(template.code);
-			const { content } = await template(input.data);
+	/**
+	 * @param {import('ventojs/src/environment.js').Template} template
+	 * @param {EleventyData} data
+	 * @param {string} from
+	 */
+	async function render(template, data, from) {
+		// Load new context
+		setContext(data);
 
-			return content;
-		},
+		// Render template
+		DEBUG.render('Rendering `%s`', from);
+		const { content } = await template(data);
+		return content;
+	}
+
+	return {
+		cache: env.cache,
+		loadPlugins,
+		loadFilters,
+		loadShortcodes,
+		loadPairedShortcodes,
+		getTemplateFunction,
+		render,
 	};
 }

package/src/index.js

@@ -29,7 +29,7 @@ import autotrimPlugin, { defaultTags as autotrimDefaultTags } from 'ventojs/plug
 // Local modules
 import { createVentoEngine } from './engine.js';
 import { ignoreTagPlugin } from './modules/ignore-tag.js';
-import { DEBUG, PERMALINK_PREFIX, REQUIRED_API_METHODS } from './modules/utils.js';
+import { DEBUG, runCompatibilityCheck } from './modules/utils.js';
 
 /**
  * @param {import('@11ty/eleventy').UserConfig} eleventyConfig
@@ -37,18 +37,7 @@ import { DEBUG, PERMALINK_PREFIX, REQUIRED_API_METHODS } from './modules/utils.j
  */
 export function VentoPlugin(eleventyConfig, userOptions) {
 	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.'
-			);
-		}
-	}
+	runCompatibilityCheck(eleventyConfig);
 
 	/** @type {VentoPluginOptions} */
 	const options = {
@@ -153,26 +142,36 @@ export function VentoPlugin(eleventyConfig, userOptions) {
 		outputFileExtension: 'html',
 		read: true,
 
-		// Main compile function
-		async compile(source, file) {
-			file = path.normalize(file);
-			return async (data) => await engine.process({ source, data, file });
+		compile(inputContent, inputPath) {
+			// Normalize input path
+			inputPath = path.normalize(inputPath);
+
+			// Retrieve the template function
+			const template = engine.getTemplateFunction(inputContent, inputPath, false);
+
+			// Return a render function
+			return async (data) => await engine.render(template, data, inputPath);
 		},
 
 		compileOptions: {
-			// Defer all caching to Vento
-			cache: false,
 			// Custom permalink compilation
-			permalink(source, file) {
+			permalink(permalinkContent, inputPath) {
 				// 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 });
+				if (typeof permalinkContent === 'string' && /\{\{\s+.+\s+\}\}/.test(permalinkContent)) {
+					// Normalize input path
+					inputPath = 'Permalink::' + path.normalize(inputPath);
+
+					// Retrieve the template function
+					const template = engine.getTemplateFunction(permalinkContent, inputPath);
+
+					// Return a render function
+					return async (data) => await engine.render(template, data, inputPath);
 				}
 
-				return source;
+				return permalinkContent;
 			},
 		},
 	});
+
 	DEBUG.setup('eleventy-plugin-vento initialized');
 }

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

@@ -12,8 +12,8 @@ export function createVentoTag(options) {
 		if (!code.startsWith(options.name)) return;
 
 		// Declare helper variables for repeated strings in template
-		const fn = `__env.utils._11ty.${options.group}.${options.name}`;
-		const ctx = '__env.utils._11ty.ctx';
+		const fn = `__env.utils._11tyFns.${options.group}.${options.name}`;
+		const ctx = '__env.utils._11tyCtx';
 		const args = [code.replace(options.name, '').trim()];
 
 		const varname = output.startsWith('__shortcode_content')

package/src/modules/utils.js

@@ -4,7 +4,7 @@ const debugBaseNamespace = 'Eleventy:Vento';
 export const DEBUG = {
 	setup: createDebugger(`${debugBaseNamespace}:Setup`),
 	cache: createDebugger(`${debugBaseNamespace}:Cache`),
-	template: createDebugger(`${debugBaseNamespace}:Template`),
+	render: createDebugger(`${debugBaseNamespace}:Render`),
 };
 
 // Project-wide constants
@@ -17,4 +17,18 @@ export const REQUIRED_API_METHODS = [
 
 export const CONTEXT_DATA_KEYS = ['page', 'eleventy'];
 
-export const PERMALINK_PREFIX = 'EleventyVentoPermalink:';
+// Helper functions
+export function runCompatibilityCheck(config) {
+	DEBUG.setup('Run compatibility check');
+	for (const [method, version] of REQUIRED_API_METHODS) {
+		if (!config?.[method]) {
+			console.error(
+				'[eleventy-plugin-vento] Plugin compatibility error:',
+				`\`${method}\``,
+				'not found. Please use Eleventy',
+				version,
+				'or later.'
+			);
+		}
+	}
+}