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

``bash
npm install @walkeros/core
`

Quick Start

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

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

Import utilities directly:

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

Flow Configuration Syntax

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

$3

Reference reusable configuration blocks defined in definitions:

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

$3

Reference variables defined in variables for config-level values:

`json
{
"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).

$3

Reference environment variables with optional defaults:

`json
{
"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

$3

#### assign

assign(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.

`ts
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.

`js
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.

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

#### clone

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

`js
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).

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

$3

#### anonymizeIP

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

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

#### Hashing

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

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

$3

#### getMappingValue

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

`ts
// 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
finds the appropriate mapping rule for an event.

$3

#### getMarketingParameters

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

`js
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' });
`

$3

#### 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

$3

#### requestToData

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

`js
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.

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

$3

#### parseUserAgent

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

`js
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'

$3

#### tryCatch

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

`js
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.

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

$3

#### debounce

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

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

#### throttle

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

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

$3

#### 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.

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

$3

#### validateEvent

validateEvent(obj: unknown, customContracts?: Schema.Contracts): WalkerOS.Event | never`
validates event structure and throws on invalid events.

#### validateProperty

Validates that values conform to walkerOS property types.

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.