/walkeros-understanding-transformers

name: walkeros-understanding-transformers
description:
  Use when working with walkerOS transformers, understanding event
  validation/enrichment/redaction, or learning about transformer chaining.
  Covers interface, return values, and pipeline integration.

Understanding walkerOS Transformers

Overview

Transformers are middleware for **validating**, **enriching**, and **redacting** events in the walkerOS pipeline. They run in chains at configurable points between sources, collector, and destinations.

**Core principle:** Transformers transform events. They don't capture (sources) or deliver (destinations)—they modify events in-flight.

Use Cases

| Use Case | Purpose | Example | | ------------ | ----------------------------------------- | ------------------------ | | **Validate** | Ensure events match schema contracts | JSON Schema validation | | **Enrich** | Add server-side data to events | User segments, geo data | | **Redact** | Remove sensitive data before destinations | Strip PII, anonymize IPs |

Available Packages

| Package | Env | Purpose | | ------------------------------------------ | ------ | -------------------------------------------------- | | `@walkeros/transformer-validate` | both | Enforce JSON Schema contracts on events at runtime | | `@walkeros/transformer-ga4` | server | Decode GA4 Measurement Protocol hits into events | | `@walkeros/server-transformer-bot` | server | Annotate an automation score and client category | | `@walkeros/server-transformer-fingerprint` | server | Derive a stable visitor fingerprint |

Contract validation

`@walkeros/transformer-validate` is the runtime arm of a [contract](../../website/docs/getting-started/flow/contract.mdx). Event shapes live in the top-level `contract` block; the transformer references one via `$contract.<name>` in its `contract` setting and validates the canonical event. `mode: "strict"` drops invalid events (chain-stop); `mode: "pass"` (default) annotates `event.source.valid` and continues so a downstream step can route on the verdict. `format: true` additionally checks the canonical `WalkerOS.Event` structure. Filtering is the same mechanism: an inline schema that rejects the unwanted events plus `mode: "strict"`, there is no separate `ignore` field. See [Website: Validate transformer](../../website/docs/transformers/validate.mdx).

Transformer Interface

See [packages/core/src/types/transformer.ts](../../packages/core/src/types/transformer.ts) for canonical interface.

Init Function (Context Pattern)

Transformers use a context-based initialization pattern:

import type { Transformer } from '@walkeros/core';

export const transformerMyTransformer: Transformer.Init<Types> = (context) => {
  const { config = {}, env, logger, id } = context;
  // Apply defaults inline — flow.json is developer-controlled, so no
  // runtime validation. Shape checks live in ./schemas and are used by
  // `walkeros validate` and dev tooling, never at runtime.
  const userSettings = config.settings || {};
  const settings = {
    ...userSettings,
    // example default: threshold: userSettings.threshold ?? 100,
  };

  return {
    push(event, pushContext) {
      // Process event
      return { event };
    },
  };
};

**Init Context contains:**

| Property | Type | Purpose | | ----------- | -------------------- | --------------------------------------- | | `config` | `Transformer.Config` | Settings, mapping, next chain | | `env` | `Types['env']` | Environment deps (stores via `$store.`) | | `logger` | `Logger` | Logging functions | | `id` | `string` | Transformer identifier | | `collector` | `Collector.Instance` | Reference to collector | | `ingest` | `Ingest` (optional) | Request metadata from source |

Instance Methods

| Method | Purpose | Required | | --------- | ------------------------------------ | ------------ | | `push` | Process event, return modified/false | **Required** | | `init` | One-time initialization | Optional | | `destroy` | Cleanup resources | Optional |

Return Values

The `push` function controls event flow:

| Return | Behavior | | -------------------- | --------------------------------------------------------------------- | | `{ event }` | Continue chain with modified event | | `void` | Continue chain, event unchanged | | `false` | Stop chain, event dropped | | `{ event, next }` | Route via `next` in place of its own `next`, then the chain continues | | `{ event, respond }` | Continue chain with wrapped respond function | | `Result[]` | Fork: each result is its own copy with a derived `event.id` |

A `push` that throws also stops the chain and drops the event; the collector logs it and counts it in `status.failed`. Catch a library error inside `push` when the event should continue.

push(event, context) {
  if (!event.data?.id) {
    context.logger.error('Missing required id');
    return false;  // Stop chain
  }

  event.data.enrichedAt = Date.now();
  return { event };  // Continue with modified event
}

Inline Code Transformers

For simple transformations without external packages, use inline code with the `$code:` string prefix in JSON configs. The `$code:` prefix tells the CLI bundler to parse t