Skip to content
varcDocs
Varc
Docs

Tools

Transformers

Build and preview pure TypeScript value decoders, then use them across Varc's supported binary value viewers.

Transformers are saved TypeScript decoders for Redis and Valkey values. They receive exact bytes, return a typed presentation, and appear beside Varc’s built-in representations and structured decoders in supported value viewers.

Task Action
Preview the active draft Choose Preview or press Mod+Enter
Format TypeScript Choose Format in the editor header
Save the active transformer Choose Save or press Mod+S
Open a saved transformer Choose Open transformer in the tab bar
Create another draft Choose the plus button in the tab bar
Change matching metadata Edit Key pattern on a saved transformer’s footer

Mod means Command on macOS and Ctrl on Windows and Linux.

Open Transformers

Open a connection workspace, then choose Automate → Transformers in the Dock. Unlike Scripts, the Transformers editor and preview can work without an active Redis connection because a transformer cannot call Redis.

The first tab is an unsaved Untitled-1 draft. The upper pane contains the TypeScript editor. The lower pane pairs a UTF-8 sample input with preview output.

Preview your first transformer

Paste this into the editor:

import { toString } from "varc:bytes";

const parsed = JSON.parse(toString(value));
delete parsed.internalToken;

return {
  kind: "json",
  body: JSON.stringify(parsed, null, 2),
};

Paste a JSON object into Input, then choose Preview. Preview encodes that text as UTF-8 bytes and runs the current editor buffer; you do not need to save first. The Output pane displays the decoded result or the reason Varc fell back.

The preview input is text-only. When the saved transformer runs from a value viewer, value is the exact complete Uint8Array, so production use remains binary-safe.

Use the transformer input

Transformer runs expose two class-specific globals:

Global Meaning
value Exact value bytes as a Uint8Array.
complete Whether the input is complete. It is currently always true; truncated values are not transformed.

Pure embedded modules are available through static imports. For example, a MessagePack transformer can import @msgpack/msgpack, while byte-oriented code can use varc:bytes.

The selected Script environment is also available as frozen env values. Transformers cannot receive Clipboard, Dialogs, Notifications, or Network permission, and every Redis command is denied.

Return supported output

A transformer must explicitly return either a string, which Varc treats as text, or an object with string kind and body fields:

return { kind: "text", body: "decoded value" };
Kind Viewer behavior
text Shows the returned text.
json Shows JSON content using the structured JSON presentation.
html Renders allow-listed HTML in a sandboxed, network-blocked frame.
markdown Renders a safe Markdown subset without raw HTML or images.

Unknown extra fields are ignored. Returning another value shape, invalid UTF-8 text, or an unsupported kind makes the decode fail and preserves access to the raw bytes.

console.warn and console.error messages become bounded warnings beside the result. Other console output has no transformer transcript.

Save and set a key pattern

Choose Save or press Mod+S, then name the transformer. It is stored in the same local library and counts toward the same saved-script allowance as manual scripts and macros.

After saving, edit Key pattern in the editor footer. New transformers start with *. The pattern is persisted as transformer metadata.

The current value-picker does not filter or hide saved transformers by this pattern: every enabled saved transformer remains available in the Saved group. Treat the pattern as matching metadata for future suggestions, not as an access-control or execution rule.

Choose Open transformer to search, open, reorder, or delete saved transformers. Editing a saved transformer publishes a new revision; open viewers refresh their decoder catalog, and stale revision requests fail closed rather than silently running different source.

Use a saved transformer in value viewers

Supported viewers share the same Content presentation control:

  • the Keys value viewer;
  • Time Machine string history;
  • Pub/Sub payloads; and
  • held Debug deliveries.

Open the presentation picker, then choose your transformer under Saved. The selection switches the viewer from raw bytes to decoded content. Built-in raw representations and built-in structured decoders remain available in the same picker.

If a transformer is deleted, disabled, unavailable, or fails, the viewer returns safely to the raw-byte path. Decoder failure never replaces or mutates the Redis value.

Work with tabs and recovery drafts

Each transformer tab owns an independent source buffer. Tabs can be opened, reordered, and closed, and edited tabs show a dirty indicator. Closing a dirty tab offers Save, Don’t Save, and Cancel.

Typing updates a device-local recovery draft after a short pause. The recovery draft protects work across tool moves, renderer reloads, restarts, and crashes, but it does not publish a decoder to value viewers. Only Save creates or updates the library record.

Preview input and output belong to the current workspace session. They are not part of the saved transformer.

Isolation, limits, and fallback

Transformers may run while a viewer renders a value, so their execution class is deliberately tighter than a manual script:

Limit Transformer default
Deadline 500 milliseconds
Memory 16 MiB
Source 256 KiB
Input value 4 MiB
Rendered body 256 KiB
Output nesting depth 32
Captured console messages 32

The body, warning count, and warning sizes are bounded. When output is cut, Varc marks the result as truncated. Oversized input, timeout, cancellation, invalid output, and runtime errors all preserve the exact raw-value path.