> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# 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[​](#installation "Direct link to Installation")

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

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

## Data manipulation[​](#data-manipulation "Direct link to Data manipulation")

### assign[​](#assign "Direct link to 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[​](#path-operations "Direct link to Path operations")

#### getByPath[​](#getbypath "Direct link to 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 "Direct link to 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 "Direct link to 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 "Direct link to 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[​](#privacy-and-security "Direct link to Privacy and security")

### anonymizeIP[​](#anonymizeip "Direct link to 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[​](#hashing "Direct link to 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[​](#event-processing "Direct link to Event processing")

### getMappingValue[​](#getmappingvalue "Direct link to getMappingValue")

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

[mapping configurations](https://www.walkeros.io/docs/mapping.md).

```
// 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 "Direct link to getMappingEvent")

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

## Marketing and analytics[​](#marketing-and-analytics "Direct link to Marketing and analytics")

### getMarketingParameters[​](#getmarketingparameters "Direct link to 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-validation "Direct link to Type validation")

### Type checkers[​](#type-checkers "Direct link to 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[​](#property-utilities "Direct link to 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[​](#request-handling "Direct link to Request handling")

### requestToData[​](#requesttodata "Direct link to 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 "Direct link to 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[​](#user-agent-parsing "Direct link to User agent parsing")

### parseUserAgent[​](#parseuseragent "Direct link to 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[​](#error-handling "Direct link to Error handling")

### tryCatch[​](#trycatch "Direct link to 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 "Direct link to tryCatchAsync")

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

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

## Performance optimization[​](#performance-optimization "Direct link to Performance optimization")

### debounce[​](#debounce "Direct link to 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 "Direct link to throttle")

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

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

## Utilities[​](#utilities "Direct link to Utilities")

### trim[​](#trim "Direct link to trim")

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

### throwError[​](#throwerror "Direct link to throwError")

`throwError(message: string)` throws descriptive errors.

### onLog[​](#onlog "Direct link to 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:

* [Web Core](https://www.walkeros.io/docs/core/web.md) - Browser-specific functions
* [Server Core](https://www.walkeros.io/docs/core/server.md) - Node.js server functions