@bernierllc/template-engine

A core utility for template rendering and variable substitution with support for Liquid and Handlebars engines. Features email-safe and documentation-safe preprocessing, template validation, and syntax checking.

Installation

``bash
npm install @bernierllc/template-engine
`

Usage

$3

`typescript
import { TemplateEngine } from '@bernierllc/template-engine';

// Create engine instance
const engine = new TemplateEngine({
defaultEngine: 'liquid' // or 'handlebars' or 'auto'
});

// Render a template
const template = 'Hello {{name}}, welcome to {{company}}!';
const context = { name: 'John', company: 'BernierLLC' };
const result = engine.render(template, context);
console.log(result); // "Hello John, welcome to BernierLLC!"
`

$3

`typescript
import { LiquidEngine, HandlebarsEngine } from '@bernierllc/template-engine';

// Liquid engine
const liquidEngine = new LiquidEngine();
const liquidResult = liquidEngine.render(
'Hello {{ name | upcase }}!',
{ name: 'world' }
);

// Handlebars engine
const hbsEngine = new HandlebarsEngine();
const hbsResult = hbsEngine.render(
'Hello {{name}}!',
{ name: 'world' }
);
`

$3

`typescript
const emailTemplate =

Hello {{name}}

Click
;

const safe = engine.preprocess(emailTemplate, {
emailSafe: true,
removeScripts: true,
sanitizeHTML: true
});

const result = engine.render(safe, { name: 'John' });
// Scripts and unsafe content removed
`

$3

`typescript
const docsTemplate =
# Documentation for {{project}}

## Features
- Feature 1
- Feature 2
;

const processed = engine.preprocess(docsTemplate, {
docsSafe: true,
engine: 'liquid'
});

const result = engine.render(processed, { project: 'MyApp' });
`

$3

`typescript
import { TemplateValidator } from '@bernierllc/template-engine';

const validator = new TemplateValidator();
const template = '{{name}} - {{#if active}}Active{{/if}}';

const validation = validator.validate(template, 'handlebars');

if (!validation.isValid) {
console.error('Validation errors:', validation.errors);
console.warn('Warnings:', validation.warnings);
}

console.log('Suggestions:', validation.suggestions);
`

$3

`typescript
// Liquid filters
const liquidEngine = new LiquidEngine();
liquidEngine.registerFilter('reverse', (value: string) => {
return value.split('').reverse().join('');
});

const result = liquidEngine.render(
'{{ name | reverse }}',
{ name: 'hello' }
); // "olleh"

// Handlebars helpers
const hbsEngine = new HandlebarsEngine();
hbsEngine.registerHelper('loud', (value: string) => {
return value.toUpperCase() + '!!!';
});

const hbsResult = hbsEngine.render(
'{{loud greeting}}',
{ greeting: 'hello' }
); // "HELLO!!!"
`

$3

`typescript
const engine = new TemplateEngine({
defaultEngine: 'auto' // Automatically detect engine from template syntax
});

// Detects Liquid syntax
const liquidResult = engine.render('{{ name | upcase }}', { name: 'test' });

// Detects Handlebars syntax
const hbsResult = engine.render('{{name}}', { name: 'test' });
`

API Reference

$3

Main class for template rendering with automatic engine detection.

#### Constructor Options

`typescript
interface EngineConfig {
defaultEngine?: 'liquid' | 'handlebars' | 'auto';
cacheSize?: number; // Number of compiled templates to cache (default: 100)
strictFilters?: boolean; // Throw on undefined filters (default: false)
strictVariables?: boolean; // Throw on undefined variables (default: false)
}
`

#### Methods

- render(template: string, context: TemplateContext): string - Render a template with context
- renderAsync(template: string, context: TemplateContext): Promise - Async rendering
- compile(template: string): CompiledTemplate - Compile template for reuse
- preprocess(template: string, options: PreprocessOptions): string - Preprocess for safety
- registerHelper(name: string, fn: HelperFunction): void - Register custom helper
- registerFilter(name: string, fn: FilterFunction): void - Register custom filter

$3

Liquid template engine implementation with email and docs preprocessing.

#### Built-in Filters

- upcase - Convert to uppercase
- downcase - Convert to lowercase
- capitalize - Capitalize first letter
- reverse - Reverse string
- size - Get length/size
- default - Provide default value
- strip_html - Remove HTML tags
- strip_newlines - Remove newlines
- date - Format dates

$3

Handlebars template engine implementation with email and docs preprocessing.

#### Built-in Helpers

- if - Conditional rendering
- unless - Inverse conditional
- each - Loop over arrays/objects
- with - Change context
- eq - Equality comparison
- ne - Not equal comparison
- lt, gt, lte, gte - Numeric comparisons
- and, or, not - Logical operations
- formatDate - Date formatting
- uppercase, lowercase - String transformations
- default - Default values

$3

Validates template syntax, security, and best practices.

#### Validation Types

- syntax - Template syntax errors
- variable - Undefined variable warnings
- security - Security vulnerabilities (XSS, script injection)
- performance - Performance suggestions
- best-practice - Best practice recommendations

#### Methods

- validate(template: string, engine: string): ValidationResult - Validate template
- validateSyntax(template: string, engine: string): TemplateError[] - Syntax check only
- checkSecurity(template: string): TemplateWarning[] - Security check only

Configuration

$3

`typescript
interface PreprocessOptions {
engine?: 'liquid' | 'handlebars' | 'auto';
emailSafe?: boolean; // Remove scripts, sanitize HTML
docsSafe?: boolean; // Preserve markdown, escape only when needed
removeScripts?: boolean; // Remove all script tags
sanitizeHTML?: boolean; // Sanitize HTML attributes
}
`

$3

`typescript
interface TemplateContext {
[key: string]: any;
_meta?: TemplateMetadata; // Optional metadata
_helpers?: Record; // Custom helpers
_filters?: Record; // Custom filters
}
`

Integration Status

$3

- Status: Not applicable
- Reason: Core utility package with no logging requirements. Silent operation by design.

$3

- Status: Ready
- Format: TypeDoc + Markdown
- Documentation: Full API documentation with TypeScript types and usage examples

$3

- Status: Not applicable
- Reason: Pure utility package with no service discovery or event requirements. Operates independently without runtime dependencies.

Security Considerations

The template engine includes built-in security features:

1. Script Removal: Automatically removes