Title: Text Replacer v3
Description: Powerful string template processor with variables, control structures, and transformation pipes
Tags: text-replacer, templates, variables, pipes
---
Text Replacer v3 Documentation
The Text Replacer v3 is a powerful, extensible string template processor that supports advanced template features including variable replacement, control structures, and transformation pipes.
Table of Contents
Overview
Basic Usage
Template Syntax
Variable Replacement
Control Structures
Transformation Pipes
Advanced Features
Migration from v2
API Reference
Overview
The Text Replacer v3 uses a new template syntax with #{...} delimiters and supports:
Variable replacement with nested property access
Control structures (if/unless/each loops)
Transformation pipes for data formatting
Recursive variable resolution
Extensible architecture for custom pipes
Key Features
🔧 Extensible pipe system - Easy to add custom transformations
🎯 Type-safe - Full TypeScript support
🚀 Performance optimized - Efficient template processing
🔄 Recursive resolution - Handle nested variable references
📊 Rich data handling - Support for objects, arrays, and complex data structures
Basic Usage
import { replaceVariables } from "./utils/text-replacer-v3";
const context = { name: "John", age: 30 };
const template = "Hello #{show name}, you are #{show age} years old!";
const result = replaceVariables(template, context);
console.log(result); // "Hello John, you are 30 years old!"
Shortcut Syntax
For convenience, you can omit the show keyword when accessing variables. This shortcut syntax makes templates more concise and easier to read:
import { replaceVariables } from "./utils/text-replacer-v3";
const context = { name: "John", age: 30 };
// Both syntaxes work identically:
const template1 = "Hello #{show name}, you are #{show age} years old!";
const template2 = "Hello #{name}, you are #{age} years old!"; // Shortcut syntax
const result = replaceVariables(template2, context);
console.log(result); // "Hello John, you are 30 years old!"
Key Points:
#{property} is automatically converted to #{show property}
Works with all features: nested properties, arrays, pipes, etc.
Control structures (if, unless, each) still require explicit keywords
You can mix both syntaxes in the same template
Template Syntax
Variable Expressions
Variables can be accessed using either the explicit #{show ...} syntax or the shortcut #{...} syntax:
// Explicit syntax (traditional)
#{show userName}
#{show user.name}
#{show user.profile.email}
// Shortcut syntax (recommended for simplicity)
#{userName}
#{user.name}
#{user.profile.email}
// Both work with nested properties
#{show address.street}
#{address.street} // Shortcut - cleaner and easier to read
// Both work with array access
#{show users.0.name}
#{users.0.name} // Shortcut
// Both work with transformation pipes
#{show price | round:2}
#{price | round:2} // Shortcut
#{show date | format:dd.MM.yyyy}
#{date | format:dd.MM.yyyy} // Shortcut
Control Structures
Conditional Blocks
Control structures still use explicit keywords, but you can use shortcut syntax for variables inside them:
// If condition - using shortcut syntax for variables
#{if user.isActive}
Welcome back, #{user.name}!
#{/if}
// Unless condition - mixing both syntaxes is fine
#{unless user.isBlocked}
You have access to this content, #{show user.email}.
#{/unless}
Loops
// Each loop - using shortcut syntax
#{each items as item}
#{item.name}: #{item.price}
#{/each}
// With index access
#{each users as user}
#{userIndex}: #{user.name}
#{/each}
Variable Replacement
Basic Variables
const context = { greeting: "Hello", name: "World" };
// Using traditional syntax
const template1 = "#{show greeting} #{show name}!";
// Using shortcut syntax (recommended)
const template2 = "#{greeting} #{name}!";
const result = replaceVariables(template2, context);
// Output: "Hello World!"
Nested Properties
The shortcut syntax really shines with nested properties:
const context = {
user: {
personal: {
firstName: "John",
lastName: "Doe"
}
}
};
// Traditional syntax
const template1 = "#{show user.personal.firstName} #{show user.personal.lastName}";
// Shortcut syntax - much cleaner!
const template2 = "#{user.personal.firstName} #{user.personal.lastName}";
const result = replaceVariables(template2, context);
// Output: "John Doe"
Real-World Example: Address Formatting
const context = {
address: {
street: "Hauptstraße 123",
city: "Berlin",
zip: "10115",
country: "Germany"
}
};
// Shortcut syntax makes this very readable
const template = "#{address.street}, #{address.zip} #{address.city}, #{address.country}";
const result = replaceVariables(template, context);
// Output: "Hauptstraße 123, 10115 Berlin, Germany"
Array Access
const context = {
colors: ["red", "green", "blue"],
users: [
{ name: "Alice", age: 25 },
{ name: "Bob", age: 30 }
]
};
// Shortcut syntax with arrays
const template = "Color: #{colors.1}, User: #{users.0.name}";
const result = replaceVariables(template, context);
// Output: "Color: green, User: Alice"
Recursive Variables
For complex recursive patterns, you may want to use the explicit show keyword:
const context = {
settings: { theme: "dark", language: "en" },
currentSetting: "theme",
prefix: "settings"
};
// For nested recursive variables, explicit 'show' is recommended
const template = "Current theme: #{show #{show prefix}.#{show currentSetting}}";
const result = replaceVariables(template, context);
// Output: "Current theme: dark"
Control Structures
If/Unless Conditions
const context = { user: { isAdmin: true, isActive: false } };
// If condition
const template1 =
#{if user.isAdmin}