@walkeros/core

Core Types & Utilities for walkerOS

Source Code • NPM Package

Core utilities are a collection of platform-agnostic functions that can be used across all walkerOS environments. They provide standardized building blocks for data manipulation, validation, mapping, and more.

Installation

npm install @walkeros/core

Quick Start

The core package provides types and utilities used across walkerOS. In a Flow configuration:

{
  "version": 3,
  "flows": {
    "default": {
      "web": {},
      "destinations": {
        "api": {
          "package": "@walkeros/web-destination-api",
          "config": {
            "url": "https://collect.example.com/events"
          }
        }
      }
    }
  }
}

Import utilities directly:

import { assign, anonymizeIP, getMappingValue } from '@walkeros/core';

Flow Configuration Syntax

Flow configurations support three dynamic patterns for reusable, environment-aware configs:

$def.name - Definition References

Reference reusable configuration blocks defined in definitions:

{
  "definitions": {
    "itemsLoop": {
      "loop": ["nested", { "map": { "item_id": "data.id" } }]
    }
  },
  "destinations": {
    "ga4": {
      "config": {
        "mapping": {
          "order": {
            "complete": {
              "data": { "map": { "items": "$def.itemsLoop" } }
            }
          }
        }
      }
    }
  }
}

$var.name - Variable References

Reference variables defined in variables for config-level values:

{
  "variables": {
    "currency": "EUR",
    "apiVersion": "v2"
  },
  "destinations": {
    "api": {
      "config": {
        "endpoint": "https://api.example.com/$var.apiVersion/collect",
        "defaultCurrency": "$var.currency"
      }
    }
  }
}

Variables can be defined at setup, flow, or source/destination level (higher specificity wins).

$env.NAME - Environment Variables

Reference environment variables with optional defaults:

{
  "destinations": {
    "ga4": {
      "config": {
        "measurementId": "$env.GA4_ID:G-DEMO123456"
      }
    }
  }
}

• $env.GA4_ID - Throws if not set
• $env.GA4_ID:default - Uses "default" if not set

Only $env supports defaults because environment variables are external and may not be set. Variables ($var) are explicitly defined in config, so missing ones indicate a configuration error.

Core Utilities

Data Manipulation

assign

assign<T, U>(target: T, source: U, options?): T & U merges two objects with advanced merging capabilities. It has special behavior for arrays: when merging, it concatenates arrays from both objects, removing duplicates.

interface AssignOptions {
  merge?: boolean; // Merge array properties (default: true)
  shallow?: boolean; // Create shallow copy (default: true)
  extend?: boolean; // Extend with new properties (default: true)
}

const obj1 = { a: 1, b: [1, 2] };
const obj2 = { b: [2, 3], c: 3 };

assign(obj1, obj2); // Returns { a: 1, b: [1, 2, 3], c: 3 }
assign(obj1, obj2, { merge: false }); // Returns { a: 1, b: [2, 3], c: 3 }

Path Operations

getByPath

getByPath(object: unknown, path: string, defaultValue?: unknown): unknown accesses nested properties using dot notation. Supports wildcard * for array iteration.

getByPath({ data: { id: 'wow' } }, 'data.id'); // Returns "wow"
getByPath({ nested: [1, 2, { id: 'cool' }] }, 'nested.*.id'); // Returns ['', '', 'cool']
getByPath({ arr: ['foo', 'bar'] }, 'arr.1'); // Returns "bar"

setByPath

setByPath(object: WalkerOS.Event, path: string, value: unknown): WalkerOS.Event sets nested values using dot notation, returning a new object with the updated value.

const updatedEvent = setByPath(event, 'data.id', 'new-value');
// Returns a new event with data.id set to 'new-value'

clone

clone<T>(original: T): T creates a deep copy of objects/arrays with circular reference handling.

const original = { foo: true, arr: ['a', 'b'] };
const cloned = clone(original);
original.foo = false; // cloned.foo remains true

castValue

castValue(value: unknown): WalkerOS.PropertyType converts string values to appropriate types (number, boolean).

castValue('123'); // Returns 123 (number)
castValue('true'); // Returns true (boolean)
castValue('hello'); // Returns 'hello' (unchanged)

Privacy & Security

anonymizeIP

anonymizeIP(ip: string): string anonymizes IPv4 addresses by setting the last oclet to zero.

anonymizeIP('192.168.1.100'); // Returns '192.168.1.0'

Hashing

getId(length?: number): string generates random alphanumeric strings for unique identifiers.

getId(); // Returns random 6-char string like 'a1b2c3'
getId(10); // Returns 10-character string

Event Processing

getMappingValue

getMappingValue(event: WalkerOS.Event, mapping: Mapping.Data, options?: Mapping.Options): Promise<WalkerOS.Property | undefined> extracts values from events using mapping configurations.

// Simple path mapping
await getMappingValue(event, 'data.productId');

// Complex mapping with conditions and loops
const mapping = {
  map: {
    orderId: 'data.id',
    products: {
      loop: [
        'nested',
        {
          condition: (entity) => entity.entity === 'product',
          map: { id: 'data.id', name: 'data.name' },
        },
      ],
    },
  },
};
await getMappingValue(event, mapping);

getMappingEvent

getMappingEvent(event: WalkerOS.PartialEvent, mapping?: Mapping.Rules): Promise<Mapping.Result> finds the appropriate mapping rule for an event.

Marketing & Analytics

getMarketingParameters

getMarketingParameters(url: URL, custom?: MarketingParameters, clickIds?: ClickIdEntry[]): WalkerOS.Properties extracts UTM and click ID parameters from URLs. When a known ad-platform click ID is present, the result also includes a platform field resolving to a canonical identifier (e.g. gclid → google, fbclid → meta).

getMarketingParameters(
  new URL('https://example.com/?utm_source=docs&gclid=123'),
);
// Returns { source: "docs", gclid: "123", clickId: "gclid", platform: "google" }

// With custom parameters
getMarketingParameters(url, { utm_custom: 'custom', partner: 'partnerId' });

// With a custom click-ID registry (extends or overrides defaults)
getMarketingParameters(url, undefined, [{ param: 'xyzclid', platform: 'xyz' }]);

Multi-click-ID URLs preserve every raw value, but clickId and platform reference the highest-priority match. See src/getMarketingParameters.ts for the full registry and priority order.

Type Validation

Type Checkers

A comprehensive set of type checking functions:

• isString(value), isNumber(value), isBoolean(value)
• isArray(value), isObject(value), isFunction(value)
• isDefined(value), isSameType(a, b)
• isPropertyType(value) - Checks if value is valid walkerOS property

Property Utilities

• castToProperty(value) - Casts to valid property type
• filterValues(object) - Filters object to valid properties only
• isPropertyType(value) - Type guard for property validation

Request Handling

requestToData

requestToData(parameter: unknown): WalkerOS.AnyObject | undefined converts query strings to JavaScript objects with type casting.

requestToData('a=1&b=true&c=hello&arr[0]=x&arr[1]=y');
// Returns { a: 1, b: true, c: 'hello', arr: ['x', 'y'] }

requestToParameter

requestToParameter(data: WalkerOS.AnyObject): string converts objects to URL-encoded query strings.

requestToParameter({ a: 1, b: true, arr: ['x', 'y'] });
// Returns 'a=1&b=true&arr[0]=x&arr[1]=y'

User Agent Parsing

parseUserAgent

parseUserAgent(userAgent?: string): WalkerOS.User extracts browser, OS, and device information.

parseUserAgent(navigator.userAgent);
// Returns { browser: 'Chrome', browserVersion: '91.0', os: 'Windows', ... }

Individual functions are also available:

• getBrowser(userAgent) - Returns browser name
• getBrowserVersion(userAgent) - Returns browser version
• getOS(userAgent) - Returns operating system
• getOSVersion(userAgent) - Returns OS version
• getDeviceType(userAgent) - Returns 'Desktop', 'Tablet', or 'Mobile'

Error Handling

tryCatch

tryCatch(tryFn: Function, catchFn?: Function, finallyFn?: Function) wraps functions with error handling.

const safeParse = tryCatch(JSON.parse, () => ({}));
safeParse('{"valid": "json"}'); // Parses successfully
safeParse('invalid'); // Returns {} instead of throwing

tryCatchAsync

tryCatchAsync(tryFn: Function, catchFn?: Function, finallyFn?: Function) for async operations.

const safeAsyncCall = tryCatchAsync(
  () => fetchUserData(),
  (error) => ({ error: 'Failed to load user' }),
);

Performance Optimization

debounce

debounce(fn: Function, wait?: number) delays function execution until after the wait time.

const debouncedSearch = debounce(searchFunction, 300);
// Only executes after 300ms of inactivity

throttle

throttle(fn: Function, wait?: number) limits function execution frequency.

const throttledScroll = throttle(scrollHandler, 100);
// Executes at most every 100ms

Utilities

trim

trim(str: string): string removes whitespace from string ends.

throwError

throwError(message: string) throws descriptive errors.

onLog

onLog(message: unknown, verbose?: boolean) provides consistent logging.

onLog('Debug info', true); // Logs message
onLog('Silent message'); // No output

Type Definitions

See src/types/ for TypeScript interfaces:

• event.ts - Event structure
• destination.ts - Destination interface
• source.ts - Source interface
• mapping.ts - Mapping configuration

Related

• Website Documentation
• Collector Package - Event processing engine
• Web Core - Browser-specific functions
• Server Core - Node.js server functions

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.