Skip to main content
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 will see 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 being filtered.
  • ...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 
00042

​
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 
42

​
capitalize

The capitalize filter capitalizes the first character of a string. Syntax 
capitalize(string_value)
Parameters
  • string_value (string): The input string to be capitalized.
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 be serialized.
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 be converted 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 be rounded.
  • 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 be truncated.
  • 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 be converted 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.