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.