@walkeros/core 4.1.0-next-1778668930820 → 4.1.0

package/README.md

@@ -4,14 +4,15 @@
   </a>
 </p>
 
-# Core Types & Utilities for walkerOS
+# @walkeros/core
 
-[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/core)
-&bull; [NPM Package](https://www.npmjs.com/package/@walkeros/core)
+Platform-agnostic types and utilities used across all walkerOS environments,
+providing standardized building blocks for data manipulation, validation, and
+mapping.
 
-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.
+[Documentation](https://www.walkeros.io/docs/core) &bull;
+[NPM Package](https://www.npmjs.com/package/@walkeros/core) &bull;
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/core)
 
 ## Installation
 
@@ -19,419 +20,18 @@ data manipulation, validation, mapping, and more.
 npm install @walkeros/core
 ```
 
-## Quick Start
-
-The core package provides types and utilities used across walkerOS. In a Flow
-configuration:
-
-```json
-{
-  "version": 3,
-  "flows": {
-    "default": {
-      "web": {},
-      "destinations": {
-        "api": {
-          "package": "@walkeros/web-destination-api",
-          "config": {
-            "url": "https://collect.example.com/events"
-          }
-        }
-      }
-    }
-  }
-}
-```
+## Quick start
 
-Import utilities directly:
+Import the types and utilities you need directly:
 
 ```ts
 import { assign, anonymizeIP, getMappingValue } from '@walkeros/core';
 ```
 
-## Flow Configuration Syntax
-
-Flow configurations support two dynamic patterns for reusable, environment-aware
-configs:
-
-### `$var.name` - Variable References
-
-Reference values defined in `variables`. Values can be scalars (string, number,
-boolean), objects, arrays, or whole mapping templates. The reference may include
-a deep path that walks the value:
-
-```json
-{
-  "variables": {
-    "currency": "EUR",
-    "apiVersion": "v2",
-    "itemsLoop": {
-      "loop": ["nested", { "map": { "item_id": "data.id" } }]
-    },
-    "api": { "version": "v2", "url": "https://api.example.com" }
-  },
-  "destinations": {
-    "api": {
-      "config": {
-        "endpoint": "https://api.example.com/$var.apiVersion/collect",
-        "defaultCurrency": "$var.currency"
-      }
-    },
-    "ga4": {
-      "config": {
-        "mapping": {
-          "order": {
-            "complete": {
-              "data": { "map": { "items": "$var.itemsLoop" } }
-            }
-          }
-        }
-      }
-    },
-    "split": {
-      "config": {
-        "endpoint": "$var.api.url",
-        "version": "$var.api.version"
-      }
-    }
-  }
-}
-```
-
-**Resolution rules:**
-
-- A whole-string reference (`"$var.itemsLoop"`) replaces the value with the
-  variable's native type. Object, array, number, and boolean values are
-  preserved.
-- An inline reference (`"Bearer $var.token"`) substitutes a scalar mid-string.
-  If the referenced variable resolves to an object or array, resolution throws;
-  only scalars (string, number, boolean) may be substituted inline.
-- Variables may reference other variables. Resolution is recursive with cycle
-  detection, mirroring the `$flow` reference resolver.
-
-Variables can be defined at setup, flow, or source/destination level (higher
-specificity wins).
-
-### `$env.NAME` - Environment Variables
-
-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
-
-### 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.
-
-```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<T>(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)
-```
-
-### Privacy & Security
-
-#### 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
-```
-
-### Event Processing
-
-#### 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/destinations/event-mapping).
-The `context` argument requires at least `{ collector }`; `event`, `logger`, and
-`consent` are derived or optional.
-
-```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<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`).
-
-```js
-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`](./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.
-
-```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'
-```
-
-### User Agent Parsing
-
-#### 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'
-
-### Error Handling
-
-#### 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' }),
-);
-```
-
-### Performance Optimization
-
-#### 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
-```
-
-### 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.
-
-```js
-onLog('Debug info', true); // Logs message
-onLog('Silent message'); // No output
-```
-
-## Type Definitions
-
-See [src/types/](./src/types/) for TypeScript interfaces:
-
-- [event.ts](./src/types/event.ts) - Event structure
-- [destination.ts](./src/types/destination.ts) - Destination interface
-- [source.ts](./src/types/source.ts) - Source interface
-- [mapping.ts](./src/types/mapping.ts) - Mapping configuration
-
-## Related
+## Documentation
 
-- [Website Documentation](https://www.walkeros.io/docs/)
-- [Collector Package](../collector/) - Event processing engine
-- [Web Core](https://www.walkeros.io/docs/sources/web/) - Browser-specific
-  functions
-- [Server Core](https://www.walkeros.io/docs/sources/server/) - Node.js server
-  functions
+Full configuration, mapping, and examples live in the docs:
+**https://www.walkeros.io/docs/core**
 
 ## Contribute
 
@@ -442,4 +42,4 @@ Feel free to contribute by submitting an
 
 ## License
 
-This project is licensed under the MIT License.
+MIT