feat(filters): add binary-safe base64_decode_bytes

[talboren]

Summary

Adds a base64_decode_bytes filter that decodes Base64 directly to raw bytes without interpreting them as UTF-8:

• returns a Node.js Buffer in the Node build;
• returns a Uint8Array in browser builds;
• leaves the existing base64_decode text behavior unchanged for backward compatibility.

This complements the Buffer support added to base64_encode in #881. Today, base64_decode calls Buffer.from(value, 'base64').toString('utf8'), which irreversibly replaces invalid UTF-8 byte sequences. Binary files such as PNGs and PDFs therefore cannot be decoded without corruption.

Usage

Use evalValue() or evalValueSync() to preserve the binary return value:

const bytes = engine.evalValueSync(
  'encoded | base64_decode_bytes',
  { encoded: 'iVBORw0KGgr//g==' }
)

Rendering the result directly into a text template still converts it to text, so the documentation calls this out explicitly.

Compatibility

Changing base64_decode itself to return bytes would break existing text templates and produce different rendered output between Node (Buffer) and browsers (Uint8Array). A separate filter keeps the existing Shopify-compatible behavior stable while providing an explicit binary-safe path.

Tests

• Raw PNG bytes, including invalid UTF-8 sequences
• Empty input
• Arbitrary-byte decode → encode round trip
• Browser Uint8Array behavior
• Full test suite: 1,636 tests passing
• Full lint and all Node/browser bundles passing

Made with Cursor

[skynetigor]

Since we're having base64_decode_bytes, can we also have opposite base64_encode_bytes to encode information into bytes array?

[talboren]

Since we're having base64_decode_bytes, can we also have opposite base64_encode_bytes to encode information into bytes array?

@skynetigor Encoding always returns Base64 text by definition. Existing base64_encode already accepts raw Buffer bytes without UTF-8 conversion, so it is binary-safe.

[harttle]

It seems to me that this filter is for a intermediate value (as it returns Uint8Array) instead of a text string for HTML. And it's not included by shopify/liquid yet.

I'd rather leave this open to see if there're enough use cases for this. In the meantime, you can publish this feature as a separate package and register to LiquidJS.