Collector for walkerOS

Source Code • NPM Package

The collector is the central processing engine of walkerOS that receives events from sources, enriches them with additional data, applies consent rules, and routes them to destinations. It acts as the intelligent middleware between event capture and event delivery.

What it does

The Collector transforms raw events into enriched, compliant data streams by:

• Event processing - Validates, normalizes, and enriches incoming events
• Consent management - Applies privacy rules and user consent preferences
• Data enrichment - Adds session data, user context, and custom properties
• Destination routing - Sends processed events to configured analytics platforms

Key features

• Compatibility - Works in both web browsers and server environments
• Privacy-first - Built-in consent management and data protection
• Event validation - Ensures data quality and consistency
• Flexible routing - Send events to multiple destinations simultaneously
• Chain branching - Transformers can dynamically redirect the chain at runtime using branch(), enabling router-style pattern matching on ingest metadata

Role in architecture

In the walkerOS data flow, the collector sits between sources and destinations:

Sources → Collector → Destinations

Sources capture events and send them to the collector, which processes and routes them to your chosen destinations like Google Analytics, custom APIs, or data warehouses.

Operating Modes

The collector can be used in two ways:

| Mode | Usage | Config | | -------------- | ---------------------------------- | -------------------------- | | Integrated | Import directly in your app | code: sourceBrowser | | Bundled | Bundle with CLI, deploy separately | package: "@walkeros/..." |

This README shows Integrated mode. For Bundled mode, see the CLI documentation.

Event Naming Convention

walkerOS enforces a "entity action" naming convention for all events. It makes it easier to standardize enhancements and validations. It follows a clear separation. The mapping translates walkerOS events into platform-specific ones.

✅ Correct: Use spaces to separate entity and action

await elb('order complete', { value: 99.99 });
await elb('product add', { id: 'abc123' });
await elb('page view', { path: '/home' });

❌ Incorrect: Do not use platform-specific formats

// Don't use these in walkerOS
await elb('purchase'); // GA4 format - wrong here
await elb('order_complete', data); // Wrong: underscores

The collector will validate event names and destinations handle platform-specific transformations. If the event name isn't separated into entity action by space the collector won't process it.

Installation

npm install @walkeros/collector

Quick Start (Integrated Mode)

Basic setup

import { startFlow } from '@walkeros/collector';

const config = {
  consent: { functional: true },
  sources: [
    // add your event sources
  ]
  },
};

const { collector, elb } = await startFlow(config);

Advanced setup

import { startFlow } from '@walkeros/collector';

const { collector, elb } = await startFlow({
  consent: { functional: true },
  sources: [
    // add your event sources
  ],
  destinations: [
    // add your event destinations
  ],
  logger: {
    level: 'debug', // 'debug' | 'info' | 'warn' | 'error'
    handler: (message, level) => {
      console.log(`[${level}] ${message}`);
    },
  },
});

Configuration

| Name | Type | Description | Required | Example | | -------------- | --------- | ------------------------------------------------------------ | -------- | --------------------------------------- | | run | boolean | Automatically start the collector pipeline on initialization | No | true | | sources | array | Configurations for sources providing events to the collector | No | [{ source, config }] | | destinations | array | Configurations for destinations receiving processed events | No | [{ destination, config }] | | consent | object | Initial consent state to control routing of events | No | { analytics: true, marketing: false } | | logger | object | Logger configuration with level and custom handler | No | { level: 'info', handler: fn } |

Using with CLI (Bundled Mode)

For Bundled mode, the collector is configured via JSON:

{
  "collector": {
    "consent": { "functional": true }
  }
}

See CLI documentation for complete flow configuration.

Type Definitions

See src/types/ for TypeScript interfaces:

• flow.ts - Flow configuration
• collector.ts - Collector interface

Related

• Website Documentation
• Core Package - Types and utilities
• Web Sources - Browser event sources
• Server Sources - Node.js event sources

Contribute

Feel free to contribute by submitting an issue, starting a discussion, or getting in contact.

License

This project is licensed under the MIT License.