# @isdk/template-engines

> A versatile template engine library that supports multiple template formats including environment variables, HuggingFace templates, GoLang templates, and Python f-strings. The library provides a unified interface for working with different template system

Latest version **0.6.12** (published 2026-10-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @isdk/template-engines
pnpm add @isdk/template-engines
yarn add @isdk/template-engines
bun add @isdk/template-engines
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.6.12 |
| Published | 2026-10-01 |
| First published | 2025-03-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.11.1 |
| Dependencies | 4 |
| Unpacked size | 473.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Riceball LEE <snowyu.lee@gmail.com> |
| Maintainers | isdk |
| Keywords | template, engine, jinja, jinja2, python, f-string, env, golang, go |

## Links

- npm: https://www.npmjs.com/package/@isdk/template-engines
- Homepage: https://github.com/isdk/template-engines.js/#readme
- npm.io page: https://npm.io/package/@isdk/template-engines

## Dependencies (4)

- [util-ex](https://npm.io/package/util-ex.md) 2.7.1
- [lodash-es](https://npm.io/package/lodash-es.md) ^4.18.1
- [custom-factory](https://npm.io/package/custom-factory.md) 3.0.1
- [@isdk/common-error](https://npm.io/package/@isdk/common-error.md) ^0.2.2

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [mongoose-typescript](https://npm.io/package/mongoose-typescript.md) — 85 weekly downloads

## Recent versions

- 0.6.12 (latest) — 2026-10-01
- 0.6.11 — 2026-06-25
- 0.6.10 — 2026-04-07
- 0.6.9 — 2026-03-26
- 0.6.8 — 2026-02-16
- 0.6.7 — 2025-11-03
- 0.6.6 — 2025-09-25
- 0.6.5 — 2025-06-28
- 0.6.4 — 2025-06-21
- 0.6.3 — 2025-04-24
- 0.6.2 — 2025-03-27
- 0.6.1 — 2025-03-25
- 0.6.0 — 2025-03-25

## README

# String Template Engines - @isdk/template-engines

This package contains the following template engines: jinja2(hf used), golang, python(f-string), env.

## Description

A versatile template engine library that supports multiple template formats including environment variables, HuggingFace templates, GoLang templates, and Python f-strings. The library provides a unified interface for working with different template systems.

## Features

- **Unified Interface**: Provide a consistent API (`format`, `from`, `isTemplate`) to interact with various template engines (Jinja2, GoLang, f-string, Env), making it easy to switch between formats without changing your logic.
- **Smart Placeholder Detection**: Effortlessly identify if a string is a "pure placeholder" (e.g., `{{name}}`). This is useful for detecting direct variable references.
- **Raw Value Preservation**: With the `raw` option, pure placeholders can return their original data types (objects, arrays, booleans) directly from the data source, bypassing string conversion—perfect for configuration management.
- **Advanced Partial Filling**: Supports pre-filling templates with static values or dynamic functions. Dynamic functions are executed at formatting time, allowing for real-time data like timestamps or session IDs.
- **Extensible Architecture**: Easily register new template formats and aliases using the built-in factory pattern, allowing the library to grow with your needs.
- **Partial Data Processing**: Reuse templates by creating new instances with pre-configured data context.
- **Recursive Rendering**: Automatically expand template variables if their values contain template-like syntax, supporting deeply nested data resolution.
- **Expansion Control**: Use `expandValue: false` or `StringTemplateFinalValue` to prevent secondary rendering, ensuring business data integrity.
- **Automatic Output Protection**: Rendering results that still contain template literals are returned as a `StringTemplateFinalString`, which behaves like a plain string in string contexts (interpolation, concatenation, JSON) but is never expanded again by later rendering passes.

## Installation

```bash
npm install @isdk/template-engines
```

## Usage

### 1. Basic Formatting

Simple variable replacement using the default engine (Jinja2).

```ts
import { StringTemplate } from '@isdk/template-engines'

const template = StringTemplate.from('Hello, {{name}}!')
const result = await template.format({ name: 'World' })
console.log(result) // "Hello, World!"
```

---

## Advanced Features

### 2. Placeholder Analysis

Identify if a string is a "pure placeholder" and extract the variable name. This is useful for building dynamic logic around template strings.

```ts
// Check for pure placeholders (ignores surrounding whitespace)
StringTemplate.isPurePlaceholder('{{name}}') // true
StringTemplate.isPurePlaceholder('Hello {{name}}') // false

// Extract variable names
StringTemplate.getPurePlaceholderVariable('{{user.profile.id}}') // "user.profile.id"
```

### 3. Data Type Preservation (Raw Mode)

Retrieve original data types (Objects, Arrays, Booleans) directly from the data source instead of converting them to strings.

```ts
const data = { active: true, config: { port: 8080 } }

// Returns boolean true
const active = await StringTemplate.format({
  template: '{{active}}',
  data,
  raw: true
})

// Returns the original object
const config = await StringTemplate.format({
  template: '{{config}}',
  data,
  raw: true
})
```

### 4. Partial Filling & Reusability

Create new template instances with pre-configured data context.

```ts
const base = StringTemplate.from('{{role}}: {{text}}')

// Pre-fill 'role'
const userMsg = base.partial({ role: 'user' })
const adminMsg = base.partial({ role: 'admin' })

console.log(await userMsg.format({ text: 'Hi' }))   // "user: Hi"
console.log(await adminMsg.format({ text: 'Reset' })) // "admin: Reset"
```

### 5. Dynamic Variables (Late Binding)

Inject dynamic data at formatting time using functions.

```ts
const template = StringTemplate.from('Time: {{now}}, Event: {{event}}')
const logger = template.partial({
  now: () => new Date().toISOString()
})

// 'now' function is executed every time format() is called
await logger.format({ event: 'Startup' }) // "Time: 2024-03-20..., Event: Startup"
```

### 6. Recursive Rendering

Automatically resolve templates nested inside variable values. This allows for deep data resolution.

```ts
const data = {
  name: 'Alice',
  greeting: 'Hello, {{name}}!', // This value is also a template
}

// "{{greeting}}" expands to "Hello, {{name}}!", then to "Hello, Alice!"
const result = await StringTemplate.format({
  template: 'System: {{greeting}}',
  data
})
console.log(result) // "System: Hello, Alice!"
```

### 7. Precise Rendering Control (Safety)

Control the recursive behavior to protect business data or performance.

```ts
import { StringTemplateFinalValue } from '@isdk/template-engines'

const data = {
  name: 'World',
  // Use expandValue: false to disable recursion for the entire operation
  msg: 'Template: {{name}}',
  // Use StringTemplateFinalValue to protect specific data
  code: new StringTemplateFinalValue('Code with {{syntax}}'),
}

// 1. Global control
await StringTemplate.format({ template: '{{msg}}', data, expandValue: false })
// Output: "Template: {{name}}"

// 2. Data-level protection
await StringTemplate.format({ template: '{{code}}', data })
// Output: "Code with {{syntax}}" (Preserved literally)

// 3. JSON Serialization Transparency (New)
// StringTemplateFinalValue automatically unwraps during JSON.stringify, 
// ensuring seamless data exchange.
console.log(JSON.stringify(data.code))
// Output: "Code with {{syntax}}"

// 4. Automatic output protection (StringTemplateFinalString)
// If a rendering result still contains template literals (expansion disabled,
// recursion blocked by a circular reference, or a consumed
// StringTemplateFinalValue), it is returned
// as a StringTemplateFinalString: a String object that interpolates, concatenates
// and serializes just like a plain string, but is never expanded again by later
// rendering passes.
const first = await StringTemplate.format({
  template: '{{code}}',
  data: { code: 'return "{{x}}"' },
  expandValue: false,
})
console.log(String(first)) // 'return "{{x}}"'

// A later pass renders it literally — no flags needed:
const second = await StringTemplate.format({
  template: 'CODE:\n{{code}}',
  data: { code: first, x: 'EXPANDED' },
})
console.log(String(second)) // 'CODE:\nreturn "{{x}}"'

// To opt back into expansion (multi-stage pipelines), unwrap it explicitly:
await StringTemplate.format({ template: String(first), data: { x: '1' } })
```

### 8. Extending the Engine (Custom Formats)

Register your own template implementation using the factory pattern.

```ts
import { StringTemplate, StringTemplateOptions } from '@isdk/template-engines'

class MySimpleTemplate extends StringTemplate {
  _initialize(options?: StringTemplateOptions) {
    // Custom initialization logic
  }

  _format(data: Record<string, any>): string {
    // Simple replacement: {var} -> data[var]
    return this.template.replace(/{(\w+)}/g, (_, key) => data[key] || '')
  }
}

// Register as 'myformat'
StringTemplate.register(MySimpleTemplate, { name: 'myformat' })

const result = await StringTemplate.format({
  template: 'Hello {name}',
  templateFormat: 'myformat',
  data: { name: 'Dev' }
})
console.log(result) // "Hello Dev"
```

---

## API Documentation

### StringTemplate Class

The main entry point for working with templates.

#### StringTemplateOptions

- `template?: string` The template string.
- `data?: Record<string, any>` The data for interpolation.
- `templateFormat?: string` The format of the template (e.g., 'hf', 'env', 'golang', 'f-string').
- `raw?: boolean` If true, returns the raw value for pure placeholders instead of a string.
- `expandValue?: boolean` If true (default), automatically expands template-like strings in variables.
- `inputVariables?: string[]` List of expected input variables.

#### Static Methods

- `from(template: string|StringTemplateOptions, options?: StringTemplateOptions)` Creates a new template instance.
- `async format(options: StringTemplateOptions)` Formats a template using provided options.
- `async formatIf(options: StringTemplateOptions)` Formats a template if it's valid.
- `isTemplate(templateOpt: StringTemplateOptions)` Checks if given options represent a valid template.
- `isPurePlaceholder(templateOpt: StringTemplateOptions|string)` Checks if the template is a pure placeholder (optionally surrounded by whitespace).
- `getPurePlaceholderVariable(templateOpt: StringTemplateOptions|string)` Returns the variable name if the template is a pure placeholder.

#### Instance Methods

- `filterData(data: Record<string, any>)` Filters input data to include only specified variables.
- `partial(data: Record<string, any>)` Creates a new template instance with partially filled data.
- `async format(data?: Record<string, any>):` Formats a template using provided options.
- `isPurePlaceholder()` Checks if the template instance is a pure placeholder.
- `getPurePlaceholderVariable()` Returns the variable name if the template instance is a pure placeholder.
- `toJSON()` Serializes the template instance to JSON.

### StringTemplateFinalString Class

A special string-like value returned by `format()` when the rendering result still contains template literals (e.g. `expandValue: false` was used, recursion was blocked by a circular reference, or a `StringTemplateFinalValue` was consumed). It is the automatic output counterpart of `StringTemplateFinalValue`:

- It extends `String`: `String(v)`, `v.toString()`, template literals and concatenation all yield the plain string content.
- `JSON.stringify(v)` serializes it as a plain string — safe to store or send over the wire.
- Empty results are never wrapped, so a `StringTemplateFinalString` value is always truthy.
- When used as data in a later `format()` call, its content is kept literally and never expanded again. Unwrap it with `String(v)` to opt back into expansion.
- Detection is cross-realm safe: use `isStringTemplateFinalString(v)` instead of `instanceof`.

```ts
import { isStringTemplateFinalString } from '@isdk/template-engines'

const first = await StringTemplate.format({
  template: '{{code}}',
  data: { code: 'return "{{x}}"' },
  expandValue: false,
})

isStringTemplateFinalString(first) // true
typeof first // 'object' — it is a String object; use String(first) for strict comparisons
```

#### Boundaries & Migration

**The tag lives on the value, not inside the string content**, so it travels with the value and is lost as soon as the value is converted to a plain string:

- **Works**: within one process, when each layer passes the result along by reference and does no string operation on it. Layers may be fully independent libraries, even loading separate copies of this package — detection uses a `Symbol.for` brand, so it works across realms.
- **Does not work**: across processes / services / databases / an LLM round-trip. After `JSON.stringify` it is a plain string again and the tag is gone.
- **Operations that drop the tag**: `+`, `slice` / `replace` / `trim` / `split`, `String(v)`, `structuredClone` — anything yielding a primitive string.
- **Position decides the role**: the same value still renders normally when passed as `template`; it is only protected when used as **data**. If a layer's output is meant to be the next layer's template, unwrap it explicitly with `String(v)`.

**The return type is a breaking change**: `format()` may now return a `String` object instead of a primitive string.

- `typeof result === 'string'` is now `'object'`;
- `result === '...'` fails — compare with `String(result)` instead;
- everything else (interpolation, `String()`, `JSON.stringify`, string methods) is unchanged.

To keep the previous behaviour, turn output tagging off with `tagFinalString: false` (this only disables *tagging* — protected values are still never expanded when used as data):

```ts
const result = await StringTemplate.format({
  template: '{{code}}',
  data: { code: 'return "{{x}}"' },
  expandValue: false,
  tagFinalString: false,
})

typeof result // 'string'
```

### Utilities

The library provides utility functions for identifying and cleaning template data.

#### `isStringTemplateFormatable(val: any): boolean`

Checks if a value is suitable for use in `StringTemplate` formatting.

- **Formatable values**:
  - **Primitives**: `string`, `number`, `boolean`, `bigint`, `symbol`, `null`, `undefined`.
  - **Functions**: Used as dynamic data sources.
  - **Arrays**: Recursively handled.
  - **Plain Objects**: Objects whose prototype is `Object.prototype` or `null`.
  - **Built-in Objects**: `Date`, `RegExp` (and their subclasses).
  - **Wrapper Objects**: `String`, `Number`, `Boolean`.
  - **`StringTemplateFinalValue`**: Special wrapper for literal protection.
  - **`StringTemplateFinalString`**: Rendering results tagged by the engine (previous output).
- **Non-formatable values**:
  - `Error` instances.
  - `Map`, `Set`, `Promise`.
  - Other custom class instances (not inheriting from allowed types).

#### `pickStringTemplateData(val: any, options?: PickStringTemplateDataOptions): any`

Recursively deep-cleans an object or array to ensure all values are formatable by `StringTemplate`.

- **Recursive Deep-Cleaning**:
  - Traverses Arrays and Plain Objects (enumerable properties only).
  - Handles circular references safely by maintaining reference identity.
  - Preserves `StringTemplateFinalValue` and `StringTemplateFinalString` as leaf nodes (no internal cleaning).
- **Options**:
  - `invalidUsage?: 'remove' | 'null' | 'undefined'`: Determines how to handle non-formatable values.
    - `'remove'` (default): Removes properties from objects or elements from arrays.
    - `'null'`: Sets non-formatable values to `null`.
    - `'undefined'`: Sets non-formatable values to `undefined`.

**Example Usage:**

```typescript
import { pickStringTemplateData } from '@isdk/template-engines';

const dirtyData = {
  name: 'Dev',
  logger: console.log, // Allowed as a function
  internal: new Map(), // Non-formatable
  error: new Error('fail'), // Non-formatable
  metadata: {
    tags: ['a', new Set()], // Nested non-formatable
  }
};

const cleaned = pickStringTemplateData(dirtyData);
// Result: { name: 'Dev', logger: console.log, metadata: { tags: ['a'] } }
```

### Template Engines

The library supports multiple template engines:

- Environment Variable Templates
  - Parses and interpolates environment variables
  - Supports variable extraction
- HuggingFace Templates
  - Jinja-based template engine
  - Supports complex template structures
  - Handles internal variables
- GoLang Templates
  - Supports Go-style template syntax
  - Extracts variables from template strings
- Python F-String Templates
  - Parses Python-style f-strings
  - Supports variable interpolation

### Error Handling

The library uses `CommonError` for error management with specific error codes:

- Invalid template formats
- Missing required parameters
- Template parsing errors

### Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
1. Create your feature branch (git checkout -b feature/fooBar)
1. Commit your changes (git commit -am 'Add some fooBar')
1. Push to the branch (git push origin feature/fooBar)
1. Create a new Pull Request

## License

MIT License

---
_Source: https://npm.io/package/@isdk/template-engines · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._