understanding-mapping

Use when transforming events at any point in the flow (source→collector or collector→destination), configuring data/map/loop/condition, or understanding value extraction. Covers all mapping strategies.

⭐309stars🔀16forks📁View on GitHub🕐Updated Dec 19, 2025

When & Why to Use This Skill

This Claude skill provides a comprehensive guide to walkerOS mapping, a universal transformation layer for event data. It enables developers to seamlessly configure data transformations at any point in the flow—from source to collector or collector to destination—using strategies like conditional logic, key extraction, and array processing.

Use Cases

  • 1. Data Normalization: Transform raw inputs such as HTTP requests or dataLayer pushes into standardized walkerOS events for consistent tracking.
  • 2. Vendor Integration: Map internal walkerOS events into specific vendor formats (e.g., GA4, Facebook Pixel) using custom transformation functions and object structures.
  • 3. Complex Data Handling: Process nested data structures and arrays using loops and recursive mapping to ensure all relevant event details are captured.
  • 4. Privacy Compliance: Implement consent-gated mapping to automatically filter or include specific data points based on the user's marketing or functional consent status.
nameunderstanding-mapping

Understanding walkerOS Mapping

Overview

Mapping transforms data at multiple points in the walkerOS flow:

  1. Source → Collector: Transform raw input (HTTP requests, dataLayer pushes) into walkerOS events
  2. Collector → Destination: Transform walkerOS events into vendor-specific formats

Core principle: Mapping is the universal transformation layer. Same strategies work everywhere in the flow.

Core Functions

See packages/core/src/mapping.ts for implementation.

Function Purpose
getMappingEvent(event, rules) Find mapping config for an event
getMappingValue(value, config) Transform a value using mapping config

Event Mapping

Match events to transformation rules by entity and action.

const mapping = {
  // Exact match
  product: {
    view: { name: 'view_item' },
    add: { name: 'add_to_cart' },
  },

  // Wildcard: any action
  foo: {
    '*': { name: 'foo_interaction' },
  },

  // Wildcard: any entity
  '*': {
    bar: { name: 'generic_bar' },
  },
};

Conditional Mapping

Array of conditions, first match wins:

order: {
  complete: [
    {
      condition: (event) => event.data?.value > 100,
      name: 'high_value_purchase',
    },
    { name: 'purchase' }, // Fallback
  ],
}

Value Mapping Strategies

Key Extraction (string)

Extract nested property from event:

'user.id'; // → event.user.id
'data.price'; // → event.data.price
'context.stage.0'; // → first element of stage array

Static Value

Fixed value regardless of event:

{
  value: 'USD';
}
{
  value: 99.99;
}
{
  value: true;
}

Function Transform

Custom transformation logic:

{
  fn: (event) => event.data.price * 100;
} // cents
{
  fn: (event) => event.user.email?.split('@')[1];
} // domain

Object Map

Transform to new structure:

{
  map: {
    item_id: 'data.id',
    item_name: 'data.name',
    price: 'data.price',
    currency: { value: 'USD' },
    category: { fn: (e) => e.nested?.[0]?.data?.name }
  }
}

Array Loop

Process arrays (e.g., nested entities):

{
  loop: [
    'nested', // Source array path
    {
      map: {
        item_id: 'data.id',
        quantity: 'data.quantity',
      },
    },
  ];
}

Only return value if consent granted:

{
  key: 'user.email',
  consent: { marketing: true }
}

Complete Example

const destinationConfig = {
  mapping: {
    product: {
      view: {
        name: 'view_item',
        data: {
          map: {
            currency: { value: 'USD' },
            value: 'data.price',
            items: {
              loop: [
                'nested',
                {
                  map: {
                    item_id: 'data.id',
                    item_name: 'data.name',
                  },
                },
              ],
            },
          },
        },
      },
    },
  },
};

Example-Driven Development

When creating sources or destinations, define mapping examples BEFORE implementation:

1. Create Input/Output Examples First

// src/examples/inputs.ts - What we receive
export const pageViewInput = {
  event: 'page_view',
  properties: { page_title: 'Home', page_path: '/home' },
};

// src/examples/outputs.ts - What we must produce
export const pageViewOutput = {
  method: 'track',
  args: ['pageview', { url: '/home', title: 'Home' }],
};

2. Define Mapping to Connect Them

// src/examples/mapping.ts
export const defaultMapping = {
  page: {
    view: {
      name: 'pageview',
      data: {
        map: {
          url: 'data.path',
          title: 'data.title',
        },
      },
    },
  },
};

3. Test Against Examples

test('produces expected output', () => {
  const result = transform(examples.inputs.pageViewInput);
  expect(result).toMatchObject(examples.outputs.pageViewOutput);
});

See:

Where Mapping Lives

Location Purpose
Source config Transform raw input → walkerOS events
Destination config Transform walkerOS events → vendor format
src/examples/mapping.ts Default mapping examples (example-driven)
packages/core/src/mapping.ts Core mapping functions
apps/quickstart/src/ Validated examples

Skills:

Source Files:

Examples:

Documentation: