Transformers
Transformers are middleware that validate, enrich, and redact events in the walkerOS pipeline. Together with Mapping, they shape events before they reach destinations.
A transformer step can either run custom logic (via code or package) or
act as a pass-through step: a step with no code and no package, where
the runtime synthesizes the push. Pass-through steps cover three patterns:
chain-only hops (before / next), cache-only checks (cache), and
mapping-only mutations (mapping). See Create your own
for the full vocabulary.
Use cases
| Use Case | Example |
|---|---|
| Validate | Ensure events match JSON Schema contracts |
| Enrich | Add server-side data (user segments, geo) |
| Redact | Remove PII before sending to destinations |
Available transformers
| Transformer | Web | Server | What it does |
|---|---|---|---|
| Bot detection | - | Yes | Annotates events with a bot score, a client category, and stable reason codes. Never drops events. |
| File | - | Yes | Serves a static file from a store backend by request path and stops the chain. |
| Fingerprint | - | Yes | Cookieless visitor hash from the anonymized IP, reduced user agent and site, salted and rotating daily. |
| GA4 | - | Yes | Decodes Google Analytics 4 Measurement Protocol v2 hits into walkerOS events. |
| Validate | Yes | Yes | Checks events against JSON Schema contracts and records a verdict. |
Basic setup
Add a transformer to the transformers block of your flow and wire it into the
pipeline via a source's next, the collector's next, or a destination's
before. A transformer that no chain names never runs, and neither
walkeros validate nor the collector reports it. A stop in collector.next
drops the event for every destination; a stop in a destination's before
drops it for that destination only. See
Chain resolution and
Dropping an event with stop.
import { startFlow } from '@walkeros/collector';
import { transformerFingerprint } from '@walkeros/server-transformer-fingerprint';
await startFlow({
next: 'fingerprint',
transformers: {
fingerprint: {
code: transformerFingerprint,
config: {
settings: { salt: process.env.FINGERPRINT_SALT },
},
},
},
});Configuration
These fields are available on every transformer, regardless of package. They
wrap the package-specific settings field, which is documented on each
transformer's page.
| Property | Type | Description | More |
|---|---|---|---|
env | Transformer.Env | Environment dependencies (platform-specific) | |
id | string | Transformer instance identifier (defaults to transformer key) | |
logger | Logger.Config | Logger configuration (level, handler) to override the collector defaults | |
before | Route | Pre-transformer chain that runs before this transformer pushes | |
next | Route | Graph wiring to the next transformer in the chain | |
cache | EventCache.Config | Step-level cache configuration for this transformer | |
state | State.Config | State.Config[] | Declarative store get/set operations applied around this transformer | |
disabled | boolean | Completely skip this transformer in chains | |
timeout | number | Timeout in ms (default 10000) for init and for each push; one that does not settle in this window fails the push with code timeout, and the next push retries the init. | |
mapping | Mapping.Config | Declarative event-to-event mapping applied when this transformer step has no code; wins over the step-level mapping. At this position, only event-mutating fields apply (policy, and per rule condition, policy, name, ignore); consent, include, data, remove, batch, settings, extend and silent do nothing and are warned about at init. |
Beyond code, package, before, next, and cache, transformer entries
also accept a mapping field that takes a Mapping.Config value, and a
state field for declarative store get/set.
mappingThe mapping field uses the same Mapping.Config shape on destinations and
transformer steps, but the semantic differs by position. On a destination,
mapping shapes the vendor payload. On a transformer step, it mutates the
event itself. Only policy and a rule's condition, policy, name and
ignore apply there; every other field does nothing and is named in
one ERROR line at registration, and walkeros validate rejects them
(MAPPING_NO_OP).
config.timeout (milliseconds, default 10000) bounds a transformer's init and
each push. A push that does not settle fails the event with the code
timeout.
Transformer entries use a closed schema: unknown top-level keys are
errors. This catches typos like placing rules or stop at the top of a
step (forgot the cache: wrapper).
Next steps
- Cache - Cache pure handler results
- State - Declarative store get/set without
$code: - Create your own - Custom transformer guide