inkject/README.md

Inkject

A lightweight, powerful JavaScript template engine with support for conditionals, variables, and nested data structures.

Features

• Zero dependencies - Pure JavaScript implementation
• Variable interpolation with nested object support
• Conditional rendering with if/elseif/else logic
• Inline conditionals for compact templates
• Nested conditionals for complex logic
• Customizable delimiters - Use any delimiter you want
• Clean syntax - Easy to read and write templates

Installation

// Include the inkject class in your project
const inkject = require('inkject');
const renderer = new inkject();

Basic Usage

const template = "Hello &name&! You have &messages& new messages.";
const data = { 
    name: "Alice", 
    messages: 5 
};

const result = renderer.render(template, data);
console.log(result); // "Hello Alice! You have 5 new messages."

Syntax Reference

Variable Interpolation

Access data using dot notation for nested objects:

const template = `
Welcome &user.name&!
Email: &user.profile.email&
Score: &stats.points&
`;

const data = {
    user: {
        name: "John",
        profile: { email: "john@example.com" }
    },
    stats: { points: 1250 }
};

Custom Delimiters

Change delimiters by passing a third parameter:

// Using $$ as delimiters
renderer.render("Hello $$name$$", { name: "World" }, "$$$$");
// NOTE: It splits the delimiter string in two, so $$$$ means $$ for start and $$ for end

// Using different open/close delimiters
renderer.render("Hello {{name}}", { name: "World" }, "{{}}");

// Using triple delimiters
renderer.render("Hello $$$name$$$", { name: "World" }, "$$$$$$");

Conditionals

Basic If/Else

const template = `
&#if user.isActive&
Welcome back, &user.name&!
&#else&
Please activate your account.
&/if&
`;

If/Elseif/Else Chains

const template = `
&#if user.role === "admin"&
🔑 Administrator Access
&#elseif user.role === "manager"&
👔 Manager Access
&#else&
👤 Standard User
&/if&
`;

Inline Conditionals

Perfect for conditional text within sentences:

const template = `
You have &#if notifications > 0&&notifications& new&#else&no&/if& notifications.
Status: &#if user.isActive&✅ Active&#else&❌ Inactive&/if&`;

Comparison Operators

Support for all common comparison operators:

• === - Strict equality
• !== - Strict inequality
• == - Loose equality
• != - Loose inequality
• > - Greater than
• < - Less than
• >= - Greater than or equal
• <= - Less than or equal

const template = `
&#if age >= 18&
You are an adult.
&#elseif age >= 13&
You are a teenager.
&#else&
You are a child.
&/if&`;

Negation

Use ! to negate conditions:

const template = `
&#if !user.isSubscribed&
Subscribe now for premium features!
&/if&
`;

Nested Conditionals

Create complex logic with nested conditions:

const template = `
&#if user.isActive&
    Welcome, &user.name&!
    &#if user.role === "admin"&
        &#if company.employees > 100&
        Managing large organization (&company.employees& employees)
        &#else&
        Managing small team (&company.employees& employees)
        &/if&
    &/if&
&/if&
`;

Examples

User Dashboard

const dashboardTemplate = `
=== USER DASHBOARD ===

Welcome, &user.name&!

&#if user.role === "admin"&
🔑 ADMIN ACCESS GRANTED
You have full system privileges.

&#if company.employees > 100&
📊 Large Company Management:
- Company: &&company.name&&
- Total Employees: &&company.employees&
&#else&
📊 Small Company Management:
- Company: &&company.name&&
- Team Size: &company.employees&
&/if&

&#elseif user.role === "manager"&
👔 MANAGER ACCESS
You can view team data and reports.
&#else&
👤 USER ACCESS
Limited access to personal data only.
&/if&

Account Status: &#if user.isActive&✅ Active&#else&❌ Inactive&/if&
`;

const data = {
    user: {
        name: "Alice Johnson",
        role: "admin",
        isActive: true
    },
    company: {
        name: "TechCorp",
        employees: 150
    }
};

console.log(renderer.render(dashboardTemplate, data));

API Reference

render(template, data, delimiter)

Renders a template with the provided data.

Parameters:

• template (string): The template string to render
• data (object): The data object containing variables
• delimiter (string, optional): Custom delimiter (default: '&&')

Returns: Rendered string

Delimiter Rules

• Even length: Split in half for open/close (e.g., {{}} -> {{ and }})
• Odd length: Same delimiter for open/close (e.g., $$$ -> $$$ and $$$)

Error Handling

Inkject handles errors gracefully:

• Missing variables: Returns empty string
• Undefined nested properties: Returns empty string
• Invalid conditions: Evaluates to false
• Malformed templates: Processes what it can, leaves invalid syntax unchanged

Performance Tips

1. Reuse renderer instances - Create one inkject instance and reuse it
2. Simple conditions - Complex JavaScript expressions aren't supported
3. Avoid deep nesting - Keep conditional nesting reasonable for readability
4. Cache templates - Store frequently used templates in variables

Browser Compatibility

Works in all modern browsers and Node.js environments. No transpilation required.

License

MIT License - feel free to use in your projects!

---