Unexpected HTML escaping with custom toString in Handlebars helpers

Escaping Logic and Precedence

Handlebars applies escaping to the final string result of a helper's execution. If a helper is invoked with double mustaches ({{helper}}), Handlebars will escape the output unless the returned value is explicitly marked as a SafeString. A SafeString acts as a signal to the renderer to bypass escaping, making its behavior identical to triple mustache ({{{helper}}}) output regardless of the delimiters used in the template.

toString Conversion vs Escaping

When a helper returns an object with a custom toString method rather than a primitive string or a SafeString, the following sequence occurs:

1. The helper returns the object.
2. Handlebars converts the object to a string using the standard JavaScript stringification process (invoking valueOf then toString).
3. The resulting string is then passed to the escaping function if double mustaches are used.

Because the toString conversion happens before the escaping check, a custom toString method cannot inherently signal that its output is "safe." If you need the output of a custom object to avoid escaping while using double mustaches, the helper must wrap that object's string representation in a SafeString before returning it.

Verification Steps

To verify this behavior in your specific environment (assuming Handlebars 4.x), you can use the following scoped test:

const Handlebars = require('handlebars');

// Object with custom toString
const customObj = {
  toString: () => '<b>Bold</b>'
};

Handlebars.registerHelper('testHelper', () => customObj);

const template = Handlebars.compile('Double: {{testHelper}} | Triple: {{{testHelper}}}');
console.log(template({}));
// Expected: Double: &lt;b&gt;Bold&lt;/b&gt; | Triple: <b>Bold</b>

To bypass escaping for the object, modify the helper to return new Handlebars.SafeString(customObj.toString()).

Missing Diagnostic: Please confirm if the helper is returning the custom object directly or if it is returning a string generated by that object, as this determines if the SafeString wrapper is being bypassed.