Create your own transformer

Build custom transformers for validation, enrichment, or redaction.

The transformer interface

Transformers are functions that receive a context object and return a transformer instance:

The context contains:

The returned instance must implement:

Return values

Return	Behavior
`{ event }`	Continue chain with modified event
`void`	Continue chain, event unchanged
`false`	Stop chain, event dropped
`{ event, next }`	Redirect to a different chain (fan-out)
`{ event, respond }`	Continue chain with wrapped respond function

Minimal example

Push context

The push function receives an event and a push context:

config: Transformer configuration
env: Environment dependencies
logger: Scoped logger for output
id: Transformer identifier
collector: Access to collector instance
ingest: Request metadata from source (optional)

Examples

Enrich: add server-side data

Validate: custom check

Using your transformer

Pass-through steps

A path is the multi-step chain through a flow's transformer section. A pass-through step (short: pass) is a single step within a path that has no code and no package. The runtime synthesizes its push function for you, so the step exists purely to wire chain hops, run a cache check, or apply a declarative mapping.

Three variants exist:

1. Before/next chain only

A named hop in the chain. Useful for reusing a chain prefix across destinations.

"enrichServer": { "before": ["filterBots", "sessionLookup"] }

2. Cache only

A step that runs a cache check, often for dedup or response caching.

"dedup": {
  "cache": {
    "stop": true,
    "rules": [{ "key": ["event.id"], "ttl": 60 }]
  }
}

3. Mapping only

A step that runs a declarative event-to-event mapping using Mapping.Config primitives (policy, per-rule policy, mapping[].name, mapping[].ignore).

"redactPII": {
  "mapping": {
    "policy": { "user.email": { "value": "[redacted]" } }
  }
}

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 { "rules": [], "stop": true } at the top of a step (forgot the cache: wrapper).

Testing

Package convention

Every walkerOS package includes machine-readable metadata for tooling and discovery.

`walkerOS` field in package.json

Field	Required	Description
`walkerOS`	Yes	Object with `type` metadata (and `platform` for sources/destinations)

Build-time generation

Use buildDev() from the shared tsup config to auto-generate walkerOS.json:

This file contains your package's JSON Schemas and examples, enabling MCP tools and the CLI to validate configurations without installing your package.

Optional: Hints

Packages can export a hints record from src/dev.ts to provide lightweight, actionable context beyond schemas and examples, such as validation behavior, enrichment patterns, or troubleshooting tips. Hints are serialized into walkerOS.json and surfaced via MCP tools. See the walkeros-create-transformer skill for details.

Publishing checklist

walkerOS field in package.json
Keywords include walkeros and walkeros-transformer
buildDev() in tsup.config.ts
dist/walkerOS.json generated on build
npm run test passes
npm run lint passes

Next steps

Learn about creating sources
Learn about creating destinations

💡 Need implementation support?

elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)

The transformer interface​

Return values​

Minimal example​

Push context​

Examples​

Enrich: add server-side data​

Validate: custom check​

Using your transformer​

Pass-through steps​

1. Before/next chain only​

2. Cache only​

3. Mapping only​

Testing​

Package convention​

walkerOS field in package.json​

Build-time generation​

Optional: Hints​

Publishing checklist​

Next steps​