Core types and platform-agnostic utilities for walkerOS
npm install @walkeros/coreCore 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.
``bash`
npm install @walkeros/core
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 configurations support three dynamic patterns for reusable,
environment-aware configs:
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" } }
}
}
}
}
}
}
}
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).
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$var
not be set. Variables () are explicitly defined in config, so missing ones
indicate a configuration error.
#### assign
assign 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 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)
#### 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
#### 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.
#### 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' });
`
#### 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 typefilterValues(object)
- - Filters object to valid properties onlyisPropertyType(value)
- - Type guard for property validation
#### 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'
#### 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 namegetBrowserVersion(userAgent)
- - Returns browser versiongetOS(userAgent)
- - Returns operating systemgetOSVersion(userAgent)
- - Returns OS versiongetDeviceType(userAgent)
- - Returns 'Desktop', 'Tablet', or 'Mobile'
#### 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' }),
);
#### 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
#### 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
#### 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.
See src/types/ for TypeScript interfaces:
- event.ts - Event structure
- destination.ts - Destination interface
- source.ts - Source interface
- mapping.ts - Mapping configuration
- Website Documentation
- Collector Package - Event processing engine
- Web Core - Browser-specific
functions
- Server Core - Node.js server
functions
Feel free to contribute by submitting an
issue, starting a
discussion, or getting in
contact.
This project is licensed under the MIT License.