new option autoDataVarname

CHANGELOG.md

@@ -5,6 +5,10 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [1.12.12] - Unreleased
+### Added
+- New option `autoDataVarname` to replace `useWith`.
+  `useWith` is keept as an alias for backward compatibility but will be removed in the future.
+
 ### Fixed
 - `auto_trim` plugin: Trim comments.
 - `set` evaluates the expression twice.

bench/bench.ts

@@ -4,7 +4,7 @@ import { Liquid } from "npm:[email protected]";
 import { Eta } from "https://deno.land/x/[email protected]/src/index.ts";
 
 const env = vento({
-  useWith: true,
+  autoDataVarname: true,
 });
 const engine = new Liquid({
   cache: true,

docs/configuration.md

@@ -12,7 +12,7 @@ Pass an options object to the `vento()` function to customize Vento.
 // Example with the default options:
 const env = vento({
   dataVarname: "it",
-  useWith: true,
+  autoDataVarname: true,
   includes: Deno.cwd(),
   autoescape: false,
 });
@@ -41,24 +41,23 @@ Now you can use the `global` variable:
 {{ global.title }}
 ```
 
-### useWith
+### autoDataVarname
 
-Vento can append automatically the `it.` prefix to your variables. For example, instead of
-`{{ it.title }}` you can simply write `{{ title }}`. This avoid errors like _(ReferenceError: title is
-not defined)_ when you're trying to print a variable that doesn't exist.
+Vento can append automatically the `dataVarname` prefix (which by default is `.it`) to any variable that need it. For example, instead of
+`{{ it.title }}` you can simply write `{{ title }}` and vento automatically convert it to `{{ it.title }}`.
 
-In early versions, Vento used the [`with` statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with) to allow to use variables from the `it` object as global. But due `with` is no longer recommended and can affect to performance, starting from Vento 0.12 this has changed and now Vento transforms the code and appends the `it.` prefix to all variables that need it.
-
-The name of this option remains `useWith` for backward compatibility but it will be changed in the next major version.
-
-You can disable this behavior by setting this option to `false`:
+You can disable this behavior by setting the `autoDataVarname` option to `false`:
 
 ```js
 const env = vento({
-  useWith: false,
+  autoDataVarname: false,
 });
 ```
 
+> [!warning]
+>
+> The `useWith` option is an alias for backward compatibility ([when `with` was used](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with)) but it will be removed in the future.
+
 ### autoescape
 
 Set `true` to automatically escape printed variables:

mod.ts

@@ -16,8 +16,9 @@ import trim from "./plugins/trim.ts";
 
 export interface Options {
   includes?: string | Loader;
-  /** @deprecated */
+  /** @deprecated Use autoDataVarname */
   useWith?: boolean;
+  autoDataVarname?: boolean;
   dataVarname?: string;
   autoescape?: boolean;
 }
@@ -31,7 +32,7 @@ export default function (options: Options = {}): Environment {
     loader,
     dataVarname: options.dataVarname || "it",
     autoescape: options.autoescape ?? false,
-    useWith: options.useWith ?? true,
+    autoDataVarname: options.autoDataVarname ?? options.useWith ?? true,
   });
 
   // Register basic plugins

src/environment.ts

@@ -49,7 +49,7 @@ export interface Options {
   loader: Loader;
   dataVarname: string;
   autoescape: boolean;
-  useWith: boolean;
+  autoDataVarname: boolean;
 }
 
 export class Environment {
@@ -133,9 +133,9 @@ export class Environment {
     const tokens = this.tokenize(source, path);
     let code = this.compileTokens(tokens).join("\n");
 
-    const { dataVarname, useWith } = this.options;
+    const { dataVarname, autoDataVarname } = this.options;
 
-    if (useWith) {
+    if (autoDataVarname) {
       code = transformTemplateCode(code, dataVarname);
     }
 

test/echo.test.ts

@@ -72,7 +72,7 @@ Deno.test("Echo tag", async () => {
 
   testThrows({
     options: {
-      useWith: false,
+      autoDataVarname: false,
     },
     template: `
     Hello {{ world }}