@sygnl/mapper

Declarative event mapper for transforming events between different ad platform formats.

Install

npm install @sygnl/mapper

Quick Start

import { EventMapper, transforms } from '@sygnl/mapper';

const mapper = new EventMapper({
  eventNames: [
    { from: 'purchase', to: 'Purchase' }
  ],
  fields: [
    { from: 'user.email', to: 'userData.em' },
    { from: 'timestamp', to: 'event_time', transform: transforms.msToSeconds }
  ],
  static: [
    { to: 'action_source', value: 'website' }
  ]
});

const result = mapper.map(sourceEvent);

Use Cases

• Map events to Meta CAPI format
• Transform for Google Enhanced Conversions
• Adapt to Snapchat/TikTok/Bing APIs
• Build platform-agnostic event pipelines
• Define mappings once, reuse everywhere

API

EventMapper

const mapper = new EventMapper({
  eventNames?: EventNameMapping[],
  fields?: FieldMapping[],
  static?: StaticField[],
  sourceRoot?: string,
  targetRoot?: string
});

const result = mapper.map(source);
const results = mapper.mapBatch(sources);

Field Mapping

{
  from: 'source.path' | ['path1', 'path2'],  // Fallback sources
  to: 'target.path',
  transform?: (value, source) => any,
  condition?: (source) => boolean,
  default?: any,
  skipFalsy?: boolean
}

Transforms

Built-in transforms for common conversions:

import { transforms } from '@sygnl/mapper';

transforms.msToSeconds(timestamp);      // 1704067200000 → 1704067200
transforms.lowercase(str);              // "EMAIL" → "email"
transforms.toArray(value);              // "foo" → ["foo"]
transforms.pluck('id')(array);          // [{id:1},{id:2}] → [1,2]
transforms.pipe(fn1, fn2, fn3);         // Compose transforms

Examples

Meta CAPI Mapping

const metaMapper = new EventMapper({
  eventNames: [
    { from: ['purchase', 'order_completed'], to: 'Purchase' }
  ],
  fields: [
    { from: 'timestamp', to: 'event_time', transform: transforms.msToSeconds },
    { from: 'user.email', to: 'user_data.em' },
    { from: 'products', to: 'custom_data.content_ids', transform: transforms.pluck('id') },
    { from: 'value', to: 'custom_data.value' }
  ],
  static: [
    { to: 'action_source', value: 'website' }
  ],
  targetRoot: 'data.0'
});

Conditional Mapping

{
  from: 'revenue',
  to: 'purchase_value',
  condition: (source) => source.event_type === 'purchase',
  transform: (value) => Math.round(value * 100) / 100
}

Multiple Source Fallbacks

{
  from: ['user.email', 'email', 'user_email'],
  to: 'email'
}

License

Apache-2.0

Copyright 2026 Edge Foundry, Inc.