Filters

Filters are functions that take an input value and return a transformed output. TemplateDX ships ten built-in filters and exposes two ways to register your own: a global static API and a per-instance API on TemplateDX.

Creating custom filters (TypeScript)

`FilterRegistry.register` (static or instance API)

Static (global) registration is the simplest path; everything using the default transform/stringify exports sees it:

import { FilterRegistry } from '@agentmark-ai/templatedx';

FilterRegistry.register(name, filterFunction);

Parameters

name (string): The name used to call the filter in templates.
filterFunction (FilterFunction): The function that performs the transformation.

Instance (scoped) registration is for when you want filters isolated per engine:

import { TemplateDX } from '@agentmark-ai/templatedx';

const engine = new TemplateDX({ includeBuiltins: true });
engine.registerFilter(name, filterFunction);

const rendered = await engine.transform(ast, { /* props */ });

new TemplateDX({ includeBuiltins: true }) copies the built-in filters into the instance; pass false to start empty.

`FilterFunction` type

The FilterFunction type signature is:

type FilterFunction<
  Input = any,
  Output = any,
  Args extends any[] = any[]
> = (input: Input, ...args: Args) => Output;

input - The first argument is always the value the filter receives.
...args - Additional arguments passed to the filter.

Example: custom filter

Here’s an example of creating a custom reverse filter that reverses a string:

import { FilterRegistry, FilterFunction } from '@agentmark-ai/templatedx';

const reverse: FilterFunction<string, string> = (input) => {
  if (typeof input !== 'string') return input;
  return input.split('').reverse().join('');
};

FilterRegistry.register('reverse', reverse);

Usage:

{reverse("hello")}

Output

olleh

Example: filter with arguments

Filters can accept additional arguments. Here’s a pad filter that pads a string to a specified length:

import { FilterRegistry, FilterFunction } from '@agentmark-ai/templatedx';

const pad: FilterFunction<string, string, [number, string?]> = (
  input,
  length,
  char = ' '
) => {
  if (typeof input !== 'string') return input;
  return input.padStart(length, char);
};

FilterRegistry.register('pad', pad);

Usage:

{pad("42", 5, "0")}

Output

Creating custom filters (Python)

agentmark-templatedx (Python) mirrors the TS surface. Define a function and register it via the static (register_global) or instance API:

from templatedx import FilterRegistry

def reverse(value):
    if not isinstance(value, str):
        return value
    return value[::-1]

# Global (static) registration
FilterRegistry.register_global("reverse", reverse)

Unlike the tag registry (which takes the plugin first), filter registration takes the name first in both languages: register_global(name, func). For instance-scoped registration, construct the engine and use register_filter:

from templatedx import TemplateDX

engine = TemplateDX()  # always copies global built-ins on init
engine.register_filter("reverse", reverse)

result = await engine.transform(ast, {"name": "Alice"})

Built-in filters

`abs`

The abs filter returns the absolute value of a number. Syntax

abs(number_value)

Parameters

number_value (number): The input number.

Example

abs(-42)

Output

`capitalize`

The capitalize filter capitalizes the first character of a string. Syntax

capitalize(string_value)

Parameters

string_value (string): The input string to capitalize.

Example

capitalize("hello world")

Output

Hello world

`dump`

The dump filter serializes a JavaScript object into a JSON string. Syntax

dump(object_value)

Parameters

object_value (any): The input object to serialize.

Example

dump({ name: "TemplateDX", version: "1.0" })

Output

\{"name":"TemplateDX","version":"1.0"}

The leading backslash comes from the final stringify step, which escapes { at the start of text output. This applies to any filter output that begins with { or [.

`join`

The join filter joins elements of an array into a single string, separated by a specified separator. Syntax

join(array_value, separator)

Parameters

array_value (any[]): The input array.
separator (string, optional): The string to separate the array elements. Defaults to ", ".

Example

join(["apple", "banana", "cherry"], ", ")

Output

apple, banana, cherry

`lower`

The lower filter converts a string to lowercase letters. Syntax

lower(string_value)

Parameters

string_value (string): The input string to convert to lowercase.

Example

lower("HELLO WORLD")

Output

hello world

`replace`

The replace filter replaces all occurrences of a specified substring with a new substring. Syntax

replace(string_value, search, replace)

Parameters

string_value (string): The input string.
search (string): The substring to search for.
replace (string): The substring to replace with.

Example

replace("Hello World", "World", "TemplateDX")

Output

Hello TemplateDX

`round`

The round filter rounds a number to a specified number of decimal places. Syntax

round(number_value, decimals)

Parameters

number_value (number): The input number to round.
decimals (number, optional): The number of decimal places to round to. Defaults to 0.

Example

round(3.14159, 2)

Output

3.14

`truncate`

The truncate filter truncates a string to a specified length and appends an ellipsis (...) if necessary. Syntax

truncate(string_value, length)

Parameters

string_value (string): The input string to truncate.
length (number): The maximum length of the output string.

Example

truncate("The quick brown fox jumps over the lazy dog", 20)

Output

The quick brown fox ...

truncate takes the first length characters and appends ..., so the output is length + 3 characters total.

`upper`

The upper filter converts a string to uppercase letters. Syntax

upper(string_value)

Parameters

string_value (string): The input string to convert to uppercase.

Example

upper("hello world")

Output

HELLO WORLD

urlencode

The urlencode filter encodes a string to be safe for use in URLs. Syntax

urlencode(string_value)

Parameters

string_value (string): The input string to be URL-encoded.

Example

urlencode("Hello World!")

Output

Hello%20World!

urlencode uses encodeURIComponent, which leaves ! * ' ( ) unencoded by spec.

Next steps

Filters transform values inside expressions; for control flow and custom block behavior, see Tags.

Get started

Coding agents

Concepts

Build prompts

Evaluate

Observe

Deploy

Account & billing

Integrations

Reference

Creating custom filters (TypeScript)

`FilterRegistry.register` (static or instance API)

`FilterFunction` type

Example: custom filter

Example: filter with arguments

Creating custom filters (Python)

Built-in filters

`abs`

`capitalize`

`dump`

`join`

`lower`

`replace`

`round`

`truncate`

`upper`

urlencode

Next steps

​Creating custom filters (TypeScript)

​FilterRegistry.register (static or instance API)

​FilterFunction type

​Example: custom filter

​Example: filter with arguments

​Creating custom filters (Python)

​Built-in filters

​abs

​capitalize

​dump

​join

​lower

​replace

​round

​truncate

​upper

​urlencode

​Next steps

Creating custom filters (TypeScript)

`FilterRegistry.register` (static or instance API)

`FilterFunction` type

Example: custom filter

Example: filter with arguments

Creating custom filters (Python)

Built-in filters

`abs`

`capitalize`

`dump`

`join`

`lower`

`replace`

`round`

`truncate`

`upper`

urlencode

Next steps