Web Core Utilities for walkerOS

Source Code • NPM Package

Web core utilities are browser-specific functions designed for client-side walkerOS implementations. These utilities handle DOM interactions, browser information, storage, sessions, and web-based communication.

Installation

Import web utilities from the @walkeros/web-core package:

import { getAttribute, sendWeb, sessionStart } from '@walkeros/web-core';

Utilities

DOM Utilities

getAttribute

getAttribute(element: Element, name: string): string retrieves attribute values from DOM elements with enhanced handling.

const element = document.querySelector('[data-elb="product"]');
const entityType = getAttribute(element, 'data-elb'); // Returns 'product'

Attribute Parsing

splitAttribute

splitAttribute(str: string, separator?: string): string[] splits attribute strings using specified separators.

splitAttribute('id:123,name:shirt', ','); // Returns ['id:123', 'name:shirt']

splitKeyVal

splitKeyVal(str: string): [string, string] splits key-value pairs from attribute strings.

splitKeyVal('id:123'); // Returns ['id', '123']

parseInlineConfig

parseInlineConfig(str: string): Record<string, unknown> parses inline configuration strings from HTML attributes.

parseInlineConfig('{"tracking": true, "debug": false}');
// Returns { tracking: true, debug: false }

Browser Information

getLanguage

getLanguage(navigatorRef: Navigator): string | undefined extracts the user's preferred language.

getLanguage(navigator); // Returns 'en-US' or user's language

getTimezone

getTimezone(): string | undefined gets the user's timezone from the Intl API.

getTimezone(); // Returns 'America/New_York' or user's timezone

getScreenSize

getScreenSize(windowRef: Window): string returns the window's screen dimensions.

getScreenSize(window); // Returns '1920x1080' or current screen size

Element Visibility

isVisible

isVisible(element: HTMLElement): boolean checks if an element is visible to the user.

const promoElement = document.getElementById('promotion');
if (isVisible(promoElement)) {
  // Element is visible on screen
}

This function considers:

• Element display and visibility styles
• Element position within viewport
• Parent element visibility
• Intersection with the visible area

Storage Management

Storage Operations

storageRead

storageRead(key: string, storage?: StorageType): WalkerOS.PropertyType reads data from browser storage with automatic type conversion.

// Default uses localStorage
const userId = storageRead('walker_user_id');

// Use sessionStorage
const sessionData = storageRead('session_data', 'sessionStorage');

storageWrite

storageWrite(key: string, value: WalkerOS.PropertyType, maxAgeInMinutes?: number, storage?: StorageType, domain?: string): WalkerOS.PropertyType writes data to storage with expiration and domain options.

// Store with 30-minute expiration
storageWrite('user_preference', 'dark-mode', 30);

// Store in sessionStorage
storageWrite('temp_data', { id: 123 }, undefined, 'sessionStorage');

// Store with custom domain for cookies
storageWrite('tracking_id', 'abc123', 1440, 'cookie', '.example.com');

storageDelete

storageDelete(key: string, storage?: StorageType) removes data from storage.

storageDelete('expired_data');
storageDelete('session_temp', 'sessionStorage');

Session Management

sessionStart

sessionStart(config?: SessionConfig): WalkerOS.SessionData | void initializes and manages user sessions with automatic renewal and tracking.

// Start session with default config
const session = sessionStart();

// Custom session configuration
const session = sessionStart({
  storage: true,
  domain: '.example.com',
  maxAge: 1440, // 24 hours
  sampling: 1.0, // 100% sampling
});

Session data includes:

• id - Unique session identifier
• start - Session start timestamp
• isNew - Whether this is a new session
• count - Number of events in session
• device - Device identifier
• storage - Whether storage is available

Advanced Session Functions

• sessionStorage - Session-specific storage operations
• sessionWindow - Window/tab session management

Web Communication

sendWeb

sendWeb<T>(url: string, data?: SendDataValue, options?: SendWebOptionsDynamic<T>): SendWebReturn<T> sends data using various web transport methods.

// Default fetch transport
await sendWeb('https://api.example.com/events', eventData);

// Use specific transport
await sendWeb(url, data, { transport: 'beacon' });
await sendWeb(url, data, { transport: 'xhr' });

// With custom headers
await sendWeb(url, data, {
  headers: { Authorization: 'Bearer token' },
  method: 'PUT',
});

Transport-Specific Functions

sendWebAsFetch

sendWebAsFetch(url: string, data?: SendDataValue, options?: SendWebOptionsFetch): Promise<SendResponse> uses the modern Fetch API with advanced options.

await sendWebAsFetch(url, data, {
  credentials: 'include',
  noCors: true,
  headers: { 'Content-Type': 'application/json' },
});

sendWebAsBeacon

sendWebAsBeacon(url: string, data?: SendDataValue): SendResponse uses the Beacon API for reliable data transmission, especially during page unload.

// Reliable sending during page unload
window.addEventListener('beforeunload', () => {
  sendWebAsBeacon('/analytics/pageview', { duration: Date.now() - startTime });
});

sendWebAsXhr

sendWebAsXhr(url: string, data?: SendDataValue, options?: SendWebOptions): SendResponse uses XMLHttpRequest for synchronous communication.

// Synchronous request (blocks execution)
const response = sendWebAsXhr(url, data, { method: 'POST' });

Web Hashing

getHashWeb

getHashWeb(str: string, length?: number): Promise<string> generates SHA-256 hashes using the Web Crypto API.

// Generate hash for fingerprinting
const userFingerprint = await getHashWeb(
  navigator.userAgent + navigator.language + screen.width,
  16,
);
// Returns shortened hash like '47e0bdd10f04ef13'

Configuration Types

SendWebOptions

interface SendWebOptions {
  headers?: Record<string, string>;
  method?: string; // Default: 'POST'
  transport?: 'fetch' | 'beacon' | 'xhr'; // Default: 'fetch'
}

interface SendWebOptionsFetch extends SendWebOptions {
  credentials?: 'omit' | 'same-origin' | 'include';
  noCors?: boolean;
}

SessionConfig

interface SessionConfig {
  storage?: boolean; // Enable storage persistence
  domain?: string; // Cookie domain
  maxAge?: number; // Session duration in minutes
  sampling?: number; // Sampling rate (0-1)
}

StorageType

type StorageType = 'localStorage' | 'sessionStorage' | 'cookie';

Usage Notes

• Consent Required: Browser information functions may require user consent depending on privacy regulations
• Storage Fallbacks: Storage functions gracefully handle unavailable storage with fallbacks
• Transport Selection: Choose transport based on use case:
  • fetch - Modern, flexible, supports responses
  • beacon - Reliable during page unload, small payloads
  • xhr - Synchronous when needed, broader browser support
• Performance: Session and storage operations are optimized for minimal performance impact

For platform-agnostic utilities, see Core Utilities.

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.