Transformers

Transformers are middleware for validating, enriching, and redacting events in the walkerOS pipeline. Together with Mapping, they give you full control over how events are shaped before reaching 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 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({
  transformers: {
    fingerprint: {
      code: transformerFingerprint,
      config: { settings: { /* ... */ } }
    }
  }
});

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
settings	Transformer.Settings	Implementation-specific configuration
env	Transformer.Env	Environment dependencies (platform-specific)
id	string	Transformer instance identifier (defaults to transformer key)
logger	Logger.Config
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
init	boolean	Whether to initialize immediately
disabled	boolean	Completely skip this transformer in chains
mock	Transformer.Mock	Return this value instead of calling push(). Global mock for all chains. Dev/testing only.
chainMocks	Record<string, Transformer.ChainMock>	Path-specific mock values keyed by chain path. Takes precedence over global mock. Dev/testing only.
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.

Dual semantic of mapping

The 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 a one-time warning at init.

Closed schema

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 (integrated collector mode)
• State - Declarative store get/set without $code:
• Create your own - Custom transformer guide