Skip to main content
Ask your AI

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.

Source
Transformer(s)
Collector
Transformer(s)
Transformer(s)
Destination
123
1Source chain (source.next): after the source, before the collector2Collector chain (collector.next): once per event, for every destination3Destination chain (destination.before): for one destination only

Use cases​

Use CaseExample
ValidateEnsure events match JSON Schema contracts
EnrichAdd server-side data (user segments, geo)
RedactRemove PII before sending to destinations

Available transformers​

TransformerWebServerWhat it does
Bot detection-YesAnnotates events with a bot score, a client category, and stable reason codes. Never drops events.
File-YesServes a static file from a store backend by request path and stops the chain.
Fingerprint-YesCookieless visitor hash from the anonymized IP, reduced user agent and site, salted and rotating daily.
GA4-YesDecodes Google Analytics 4 Measurement Protocol v2 hits into walkerOS events.
ValidateYesYesChecks 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.

PropertyTypeDescriptionMore
envTransformer.EnvEnvironment dependencies (platform-specific)
idstringTransformer instance identifier (defaults to transformer key)
loggerLogger.ConfigLogger configuration (level, handler) to override the collector defaults
beforeRoutePre-transformer chain that runs before this transformer pushes
nextRouteGraph wiring to the next transformer in the chain
cacheEventCache.ConfigStep-level cache configuration for this transformer
stateState.Config | State.Config[]Declarative store get/set operations applied around this transformer
disabledbooleanCompletely skip this transformer in chains
timeoutnumberTimeout 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.
mappingMapping.ConfigDeclarative 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 one ERROR line at registration, and walkeros validate rejects them (MAPPING_NO_OP).

Timeout

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.

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
  • State - Declarative store get/set without $code:
  • Create your own - Custom transformer guide
💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)