Skip to main content
Ask your AI

Core utilities

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​

Import the core utilities directly from the @walkeros/core package:

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

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 and security​

anonymizeIP​

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

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

Hashing​

getId(length?: number, charset?: string): string generates random identifier strings. Defaults to a 6-character alphanumeric id; pass charset to restrict the allowed characters.

getId(); // Returns random 6-char string like 'a1b2c3'
getId(10); // Returns 10-character alphanumeric string
getId(5, 'abcdefghijklmnopqrstuvwxyz'); // Lowercase letters only

Event processing​

getMappingValue​

getMappingValue(event: WalkerOS.Event, mapping: Mapping.Data, context: Mapping.ValueContext): Promise<WalkerOS.Property | undefined> extracts values from events using

mapping configurations. The context requires the running collector: inside a step, take it from the step's context; elsewhere, use the one startFlow returns.

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

const { collector } = await startFlow();
const event = {
  name: 'order complete',
  data: { id: '0rd3r1d' },
  nested: [
    { entity: 'product', data: { id: 'ers', name: 'Everyday Ruck Snack' } },
    { entity: 'gift', data: { name: 'Surprise' } },
  ],
};

// Simple path mapping
await getMappingValue(event, 'data.id', { collector }); // '0rd3r1d'

// 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, { collector });
// { orderId: '0rd3r1d', products: [{ id: 'ers', name: 'Everyday Ruck Snack' }] }

getMappingEvent​

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

Marketing and analytics​

getMarketingParameters​

getMarketingParameters(url: URL, custom?: MarketingParameters): WalkerOS.Properties extracts UTM and click ID parameters from URLs.

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

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

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

Tag Mode loader​

moin​

moin() lets the walkerOS app open Tag Mode on your page, in the one browser tab the app opened for it. There is nothing to configure. walker.js and the web bundles the CLI builds call it first in their entry, so call it yourself only when you start a flow from your own browser code:

import { moin } from '@walkeros/core';

moin(); // once, early, before startFlow

It does nothing unless the page was opened with elbMoin in its address. On such a page it waits for the walkerOS app tab to answer and only then loads the Tag Mode script from https://cdn.walkeros.io; without that answer nothing loads. Without https://cdn.walkeros.io in your Content Security Policy's script-src, nothing loads either, unless the policy uses 'strict-dynamic', which trusts scripts added by a script that carries your nonce.

moin(target?: MoinTarget) takes no argument in normal use: the default, MOIN_PRODUCTION, trusts the walkerOS app at https://app.walkeros.io. MOIN_PARAM is the address parameter, 'elbMoin'.

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

For platform-specific utilities, see:

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)