Templon

Advanced template compiler with deep variable resolution, object processing, and strict validation with circular reference protection.

Features

• Deep Variable Resolution: Access nested properties using dot notation (e.g., {{user.profile.name}})
• Object/Array Processing: Automatically handle complex data structures
• Strict Mode: Validate template variables and throw errors for missing values
• Custom Resolvers: Extend functionality with custom variable resolution logic
• Circular Reference Protection: Prevent infinite loops with depth limiting
• TypeScript Support: Full type safety and autocompletion
• Customizable Variable Pattern: Use your own regex pattern for variable matching

Installation

npm install templon
# or
yarn add templon
# or
pnpm add templon

Basic Usage

import { compileTemplate } from "templon";

// Simple string interpolation
const result = compileTemplate("Hello {{name}}", { name: "World" });
// Output: "Hello World"

// Nested object access
const result = compileTemplate("Hello {{user.profile.name}}", {
  user: {
    profile: {
      name: "John",
    },
  },
});
// Output: "Hello John"

// Array access
const result = compileTemplate("First user: {{users.0.name}}", {
  users: [{ name: "John" }, { name: "Jane" }],
});
// Output: "First user: John"

Note: The template engine uses radash under the hood for deep property access, which provides safe and efficient object traversal.

Advanced Examples

Working with Arrays

const template = "Users: {{users}}";
const data = {
  users: ["John", "Jane", "Bob"],
};
const result = compileTemplate(template, data);
// Output: "Users: John,Jane,Bob"

Custom Variable Pattern

const template = "Hello <name>";
const result = compileTemplate(
  template,
  { name: "World" },
  { variablePattern: /<([^{}]+)>/g }
);
// Output: "Hello World"

Strict Mode

const template = "Hello {{name}}";

try {
  compileTemplate(template, {}, { strict: true });
} catch (error) {
  // Error: Missing variable: name
}

Custom Resolver

const template = "Hello {{user.name}}";
const result = compileTemplate(
  template,
  {},
  {
    resolver: (path) => {
      if (path === "user.name") return "Custom User";

      return undefined;
    },
  }
);
// Output: "Hello Custom User"

Configuration Options

Option	Type	Default	Description
strict	boolean	false	Throw errors when variables are missing
preserveUndefined	boolean	false	Preserve undefined variables in output
autoStringifyObjects	boolean	true	Automatically stringify objects to JSON
parseStrings	boolean	true	Automatically parse strings in output
parseBinInts	boolean	false	Automatically parse BigInts in output
resolver	(path: string) => any	undefined	Custom variable resolver function
stringTransform	(value: string) => string	(s) => s	Transform function for final string output
maxVariableDepth	number	10	Maximum depth for variable resolution
variablePattern	RegExp	/{{([^{}]+)}}/g	Custom regex pattern for variable matching

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.