@reldens/utils/CLAUDE.md

Reldens - Utils

## Package Overview

**@reldens/utils** is a core utility package used throughout the Reldens ecosystem. It provides essential utilities for:
- Object manipulation (Shortcuts class)
- Event management (EventsManager)
- Logging (Logger)
- Schema validation (SchemaValidator)
- Environment variables (EnvVar)
- Error handling (ErrorManager)
- Interaction area validation (InteractionArea)
- Pagination utilities (PageRangeProvider)
- Validator base interface (ValidatorInterface)

## Key Commands

```bash
# Run tests
npm test
```

## Architecture

### Core Classes

**Shortcuts** (`lib/shortcuts.js`):
- Provides utility methods for object manipulation, property access, and validation
- Imported as `sc` throughout the Reldens codebase
- Used instead of direct property access or Object.prototype methods
- Type checks: `isObject`, `isArray`, `isFunction`, `isObjectFunction`, `isString`, `isNumber`, `isInt`, `isFloat`, `isBoolean`, `isSymbol`, `isPromise`, `isTrue`
- Ownership/existence: `hasOwn`, `get`, `getByPath`, `getByPriority`, `length`
- Array utilities: `inArray`, `isNotEmptyArray`, `removeFromArray`, `randomValueFromArray`, `arraySort`, `sortObjectKeysBy`, `convertObjectsArrayToObjectByKeys`, `chunk`, `flatten`, `unique`
- Object utilities: `deepMergeProperties`, `propsAssign`, `pickProps`, `omitProps`, `hasDangerousKeys`
- Search: `fetchByProperty`, `fetchAllByProperty`, `fetchByPropertyOnObject`, `fetchAllByPropertyOnObject`
- JSON: `toJson`, `parseJson`, `deepJsonClone`, `toJsonString`
- String utilities: `startsWith`, `contains`, `cleanMessage`, `slugify`, `sanitize`, `sanitizeUrl`, `camelCase`, `capitalizedCamelCase`, `kebabCase`, `capitalize`, `truncate`, `splitToArray`
- Number utilities: `roundToPrecision`, `randomInteger`, `randomChars`, `randomCharsWithSymbols`, `randomString`, `clamp`, `parseNumber`, `isValidInteger`
- Date/time: `getCurrentDate`, `getDateForFileName`, `formatDate`, `getTime`
- Validation: `isValidUrl`, `isValidIsoCode`, `isSecurePath`, `validateInput`
- Functional: `debounce`, `throttle`, `serializeFormData`

**EventsManager** (`lib/events-manager.js`):
- Singleton event system used across Reldens
- Supports both sync (`emitSync`) and async (`emit`) events
- Allows event listeners to modify data via reference
- Debug mode available via `debug` property

**Logger** (`lib/logger.js`):
- Centralized logging utility with multiple log levels
- Levels: emergency, alert, critical, error, warning, notice, info, debug
- Configurable log level and trace options
- Used instead of console.log

**SchemaValidator** (`lib/schema-validator.js`):
- JSON schema validation utility
- Validates data structures against defined schemas
- Returns validation results with errors

**EnvVar** (`lib/env-var.js`):
- Environment variable utilities
- Type conversion and validation
- Safe environment variable access

**ErrorManager** (`lib/error-manager.js`):
- Singleton error handling utility
- Configurable error tracing via `enableTrace` property
- Supports custom error callbacks via `callback` property
- Default behavior throws Error with a message

**InteractionArea** (`lib/interaction-area.js`):
- Validates if positions are within interaction range
- Used for player-to-player, player-to-object interactions
- Configurable interaction area/margin
- Key methods: `setupInteractionArea`, `isValidInteraction`, `getPosition`

**PageRangeProvider** (`lib/page-range-provider.js`):
- Singleton pagination utility
- Generates page ranges for UI pagination
- Key method: `fetch(page, totalPages, totalDisplayedPages, firstLabel, lastLabel)`
- Returns array of page objects with label and value

**ValidatorInterface** (`lib/validator-interface.js`):
- Base interface for validator implementations
- Provides default `validate()` method that returns true
- Extend this class to create custom validators

## Important Notes

- This package has NO external dependencies
- All code must be pure JavaScript with no dependencies
- The Shortcuts class is used extensively across Reldens - any changes affect the entire ecosystem
- Singleton pattern is used for: ErrorManager, PageRangeProvider, and EventsManagerSingleton (exported alongside the EventsManager class)
- Logger methods should be used instead of console.log everywhere in Reldens
- InteractionArea is instantiable (not a singleton) - create instances for each interactive object