> Part of the walkerOS documentation. Project overview and full index: # Transformers Transformers are middleware for **validating**, **enriching**, and **redacting** events in the walkerOS pipeline. Together with [Mapping](https://www.walkeros.io/docs/mapping.md), 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](https://www.walkeros.io/docs/transformers/create-your-own.md#pass-through-steps) for the full vocabulary. ## Use cases[​](#use-cases "Direct link to 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[​](#available-transformers "Direct link to Available transformers") | Transformer | Web | Server | What it does | | --------------------------------------------------------------------------- | --- | ------ | -------------------------------------------------------------------------------------------------- | | **[Bot detection](https://www.walkeros.io/docs/transformers/bot.md)** | - | Yes | Annotates events with a bot score, a client category, and stable reason codes. Never drops events. | | **[File](https://www.walkeros.io/docs/transformers/file.md)** | - | Yes | Serves a static file from a store backend by request path and stops the chain. | | **[Fingerprint](https://www.walkeros.io/docs/transformers/fingerprint.md)** | - | Yes | Hashes configurable request fields into a deterministic identifier, without cookies. | | **[GA4](https://www.walkeros.io/docs/transformers/ga4.md)** | - | Yes | Decodes Google Analytics 4 Measurement Protocol v2 hits into walkerOS events. | | **[Validate](https://www.walkeros.io/docs/transformers/validate.md)** | Yes | Yes | Checks events against JSON Schema contracts and records a verdict. | ## Basic setup[​](#basic-setup "Direct link to Basic setup") Add a transformer to the `transformers` block of your flow and wire it into the pipeline via a source's `next` or a destination's `before`. ``` import { startFlow } from '@walkeros/collector'; import { transformerFingerprint } from '@walkeros/server-transformer-fingerprint'; await startFlow({ transformers: { fingerprint: { code: transformerFingerprint, config: { settings: { /* ... */ } } } } }); ``` ## Configuration[​](#configuration "Direct link to 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` | 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. At this position, only event-mutating fields apply (policy, mapping\[].policy, mapping\[].name, mapping\[].ignore, mapping\[].consent, include); vendor-payload fields are ignored. | | Beyond `code`, `package`, `before`, `next`, and `cache`, transformer entries also accept a `mapping` field that takes a `Mapping.Config` value, and a [`state`](https://www.walkeros.io/docs/collector/state.md) 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. Vendor-payload fields (`data`, per-rule `data`, `silent`) are ignored at the transformer position with 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[​](#next-steps "Direct link to Next steps") * **[Cache](https://www.walkeros.io/docs/collector/cache.md)** - Cache pure handler results (integrated collector mode) * **[State](https://www.walkeros.io/docs/collector/state.md)** - Declarative store get/set without `$code:` * **[Create your own](https://www.walkeros.io/docs/transformers/create-your-own.md)** - Custom transformer guide