Mapping.Rule
A Mapping.Rule is the object that sits at
config.mapping[entity][action] on a source or destination. It decides whether
an event applies, renames it, reshapes its data, and can
emit side effects (batching, custom settings). The shape is defined in
packages/core/src/types/mapping.ts.
Configuration
| Property | Type | Description | More |
|---|---|---|---|
name | string | Custom event name override (e.g., "view_item" for "product view") | |
data | any | any | Data transformation rules for event | |
settings | any | Destination-specific settings for this event mapping | |
condition | string | Condition function as string: the rule matches only when it returns true; otherwise the next rule is tried. A condition that throws fails the event. | |
consent | WalkerOS.Consent | Consent required for events this rule matches, in addition to the step consent. A destination holds (web) or skips (server) the event until granted; a source drops it. | |
policy | Mapping.Policy | Event-level policy overrides (applied after config-level policy) | |
batch | number | object | Batch scheduling: a number is the debounce wait window in ms; the object form sets wait, size and age. Works only on a destination with pushBatch. | |
include | Array<string> | Event sections (e.g. ["context", "globals"]) flattened into context.data | |
ignore | boolean | Skip the event entirely. No push, no side effects. Use for suppression. | |
silent | boolean | Run side effects (settings.identify, ...) but suppress the destination default push call. | |
extend | Mapping.RulePatch | Merge mode, only inside the settings.mapping of a package that ships default rules (@walkeros/transformer-ga4): a partial rule deep-merged onto the package-shipped default at this key instead of replacing it. A null value clears an inherited field. Validate rejects it in any other rule. | |
remove | Array<string> | Dotted paths stripped from the produced data payload after evaluation (applied last). |
Every value-shaped field (data, entries in policy, entries in settings
that take values) accepts any form documented in
Mapping.Value.
How destinations consume a rule
When an event reaches a destination, the collector picks one rule from
mapping[entity][action], where entity and action are the two words of the
event name. An array means "try each in order, first matching rule wins". A
'*' key on the entity or the action level is a wildcard. The lookup tries
four tiers, most specific first:
entity action, the exact key.entity *, the entity's own wildcard action.* action, a wildcard entity with the exact action.* *, the global wildcard.
The first tier that has a rule whose condition passes wins. A tier that has
rules but whose conditions all fail falls through to the next tier, so a
product * rule is still used when every product view rule fails its
condition.
In this example product click has no exact rule, so the second tier wins:
product * is used and * click is never consulted.
An event that matches no rule is still sent. The destination's push receives
it under its own name with no rule (context.rule is undefined), and
context.data holds only what the destination-level data and include
produce. What the destination sends for an unmapped event depends on the
destination; its page says. No setting sends only mapped events. To get that,
ignore everything with a catch-all rule and map the events you want:
{
'*': { '*': { ignore: true } },
order: { complete: { name: 'purchase' } },
}
With the catch-all in place, an event whose specific rules all fail their condition falls through to it and is ignored too.
Mapping wildcards are first-match: the lookup above picks one rule and no other rule is consulted. Contract wildcards are additive: every matching level merges in. The two systems intentionally pick different defaults: mapping selects a single transformation target, contract accumulates requirements.
A destination picks its rule once, as the event arrives: after the source chain
and collector.next, before its own before chain, state and config
policy. Those shape the payload; they do not change which rule applies. To
steer a destination's rule, rename the event in a source chain or
collector.next. If its before chain renames the event onto another rule,
that rule and its consent do not apply, and the collector logs one ERROR line
(rule-not-applied).
A rule's condition is checked while matching: the first rule whose
condition passes is used; if none passes, the lookup continues with the next
tier. A condition may be async: conditions are awaited one by one, in rule
order. One that does not settle within the destination's config.timeout fails
the event with the reason timeout. A condition that throws fails the event: it is not treated as no match,
because falling through could send an event the rule meant to stop. The push
answers ok: false with the reason mapping, and the collector logs one ERROR
line. Once a rule matches, the collector runs policy (event-level), resolves
data, then hands the result to the destination's push (or buffers it when
batch is set and the destination batches). Because a condition runs before the
before chain, it also runs for events that chain drops, and it must not push
events to its own destination: while the destination waits for that condition,
the event can fail with timeout.
A policy entry that resolves to nothing removes the field. That is how a
consent-gated entry redacts a value when consent is denied.
Rule consent
A rule's consent adds a requirement for the events it matches, on top of the
destination's config.consent: both must hold. Within one object any granted
key is enough. On the web a denied event waits in the destination's queue and
is sent once consent is granted; server flows built by the CLI skip it instead
(consentDenied: 'skip'). The rule is a gate, not a selector: if the selected
rule's consent is denied, the event waits instead of falling through to the
next rule. To choose a rule by consent, read context.consent in a
condition. An ignore rule's consent has no effect. At a source, a denied
rule drops the event. At a transformer, consent has no effect; walkeros validate and the bundle reject it (MAPPING_NO_OP).
A destination's config that sends every analytics event and order complete
only with marketing consent:
{
"consent": { "analytics": true },
"mapping": {
"order": {
"complete": { "name": "purchase", "consent": { "marketing": true } }
}
}
}
Batch scheduling
batch accepts a number (the debounce wait window in ms) or an object
{ wait?, size?, age? } for finer control:
wait(ms): debounce window. The timer resets on every push.size: hard count cap. Flushes immediately at this many events.age(ms): hard age cap since the first entry of the current window.
A rule-level batch splits this entity-action into its own buffer. When the
destination also sets config.batch, the rule's values override
destination-level per field (rule ?? config ?? default); fields the rule omits
fall back to config.batch. Setting config.batch alone batches all of the
destination's events into one shared buffer with no rule needed. Defaults when
batching is enabled: size: 1000, age: 30000. When events keep arriving
faster than wait, its timer keeps resetting, and the size and age caps
are what force the flush.
Batching works only on a destination that implements pushBatch; its page
says whether it does. On any other destination batch has no effect: every
event goes to push right away, and the collector logs one ERROR line naming
the batch when the destination registers (on inline code without
pushBatch, walkeros validate and the bundle reject it). Pending batches are
flushed when the collector shuts down
(walker shutdown, which the runner sends
on exit), waiting up to 5 seconds per batch. In the browser nothing sends
walker shutdown; the browser source sends
walker flush when the page goes away,
so pending batches are sent then. The
pushBatch contract
covers what the destination receives.
Conditional rules
Use an array with conditions to branch by event contents; the first matching rule wins.
Ignore vs silent
Two flags control what a destination does with an event whose rule matched:
ignore: true: the rule matched and the destination'spush()is not called, so nothing is sent and the rule'snameanddataare not applied. What runs before the rule is applied still runs: the destination'siniton its first event, itsbeforechain, the destination-levelpolicyanddata, and the rule'spolicy. Use for suppression. An ignored event counts as a deliberate skip: the push result lists the destination neither underdonenor underfailed,status.outand the destination'scountdo not move, andstatus.destinations.<id>.skippedcounts the event. The collector writes a DEBUG line, and Observe shows a skip with the reasonignored.silent: true: the rule matched and the destination'spush()is called with the rule. Every destination honourssilent:settings.identify,settings.revenue,settings.group, and other side effects still run and only the default forwarding call (e.g.track(),capture(),event()) is suppressed. Use for "identify without an event" style flows. A destination has no side effect to run for a rule that maps none, so the rule then sends nothing and is not a failure.
If both are set on the same rule, ignore wins.
ignore suppresses one destination. To drop an event before any destination
sees it, use a route stop in collector.next; to drop it for one destination
by condition, use a stop in that destination's before. See
Dropping an event with stop.
{
user: {
login: {
silent: true,
settings: { identify: { map: { user: 'data.id' } } },
},
},
}
On a destination such as Amplitude, the example runs the
identify() side effect on user login events but skips the default
forwarding call.
API reference
The two functions below resolve mappings. Destinations and sources call them through the collector, but they are exported for direct use in custom transformers or tests.
getMappingEvent
getMappingEvent(
event: WalkerOS.PartialEvent,
mapping?: Mapping.Rules,
collector?: Collector.Instance,
): Promise<Mapping.Result>
Resolves the matching rule for an event based on event.name (the
"entity action" string), in the lookup order above. Returns
{ eventMapping, mappingKey } where eventMapping is the matched
Mapping.Rule and mappingKey is the lookup key that matched (including
wildcards). When no rule matches, eventMapping is undefined and mappingKey
is an empty string. When there is no mapping, or the event name is a single
word with no action, the result is {}. Pass the collector when rules have
conditions: it is the conditions' context, and without it a condition gets
none. A condition that throws rejects the call with a mapping error.
getMappingValue
getMappingValue(
value: unknown,
mapping: Mapping.Data,
context: Mapping.ValueContext, // { collector, event?, consent? }
): Promise<WalkerOS.Property | undefined>
Resolves a Mapping.Value against an input. Used internally for every data,
policy, and set resolution. The companion reference for each value form
lives in Mapping.Value.
The context requires the running collector: inside a step, take it from the
step's context; elsewhere, use the one startFlow returns.
const { collector } = await startFlow();
await getMappingValue(event, 'data.id', { collector });
Rule-level examples
Source mapping
Normalize events before they reach the collector. At a source a rule renames
the event (name), edits it (policy) or drops it (ignore, or a consent that is not granted); data,
include, remove, batch, settings, extend and silent have no effect
there, because only the edited event moves on. walkeros validate and the
bundle reject those keys (MAPPING_NO_OP), naming the path and what applies at
a source; if such a config still runs, the collector logs one ERROR line when
the source registers, naming each key. A dropped event's push result is
{ ok: true, dropped: true }.
await startFlow({
sources: {
browser: {
code: sourceBrowser,
config: {
mapping: {
product: {
click: {
name: 'product view',
policy: {
'data.id': { fn: (e) => e.data?.id?.toUpperCase() },
},
},
},
test: { '*': { ignore: true } },
},
policy: {
'user.email': { fn: (e) => e.user?.email?.toLowerCase() },
},
},
},
},
});Destination mapping
Transform for a specific destination API:
await startFlow({
destinations: {
gtag: {
code: destinationGtag,
config: {
mapping: {
product: {
view: {
name: 'view_item',
data: {
map: {
item_id: 'data.id',
value: 'data.price',
currency: { value: 'USD' },
},
},
},
},
},
},
},
},
});Combined flow
The same event can be transformed at both stations:
1. Browser sends: "product click"
2. Source mapping: "product click" → "product view"
3. Destination mapping: "product view" → "view_item"
4. GA4 receives: "view_item"
Patching package-shipped rules
@walkeros/transformer-ga4 ships its own default mapping rules. Normally, a
user rule at the same key replaces the default in full. Two keywords change
that:
extend (config layer)
extend holds a partial rule that is deep-merged onto the package-shipped
default at the same key instead of replacing it. The merge happens once at
init, before any event is evaluated. A null value clears an inherited field.
Use extend when you want to add or override one field of a default rule while
inheriting the rest unchanged. Only a package that ships defaults merges
extend, so it has an effect in @walkeros/transformer-ga4's
settings.mapping only. In any other rule, a destination's own mapping
included, walkeros validate and the bundle reject it (MAPPING_NO_OP): write
the fields on the rule itself.
remove (output layer)
remove is a list of dotted paths stripped from the produced data payload
after evaluation, regardless of how each field was produced (map, fn,
include, etc.). It is applied last, so it always wins.
Use remove when you must not emit a field (PII, a vendor-reserved parameter)
but do not want to rewrite the full rule. remove works in a destination's own
rules and in @walkeros/transformer-ga4's settings.mapping. In a source's or
a transformer's own mapping it does nothing, and walkeros validate and the
bundle reject it (MAPPING_NO_OP).
Mode switching
A rule that has neither extend nor remove replaces the default in
full. Presence of either keyword activates merge mode for that rule.
Example: patch a GA4 decoder rule
The transformer-ga4 purchase default ships id, currency, value, tax,
shipping, and coupon. The config below adds affiliation from a GA4 event
parameter and drops currency from the output, keeping all other default
fields:
{
"settings": {
"mapping": {
"purchase": {
"extend": {
"data": { "map": { "affiliation": "params.ep.affiliation" } }
},
"remove": ["currency"]
}
}
}
}
extend.data.map is deep-merged onto the default data.map, so affiliation
is added alongside the existing keys. remove: ["currency"] then strips that
field from the final payload.
See also
- Mapping.Value: the eight value forms used in every rule field
- Consent guide: consent model and gating
- Destinations reference: destination-specific
settings mapping.tssource