@reldens/utils 0.53.0 → 0.54.0

package/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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
+- Key methods: `get`, `hasOwn`, `isObject`, `isArray`, `deepMerge`, `deepClone`, etc.
+- Used instead of direct property access or Object.prototype methods
+
+**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

package/README.md

@@ -78,14 +78,13 @@ Pagination helper that calculates page ranges for UI components, handling first/
 
 ```javascript
 const { PageRangeProvider } = require('@reldens/utils');
-let pageProvider = new PageRangeProvider();
 
-// Generate page range
-let range = pageProvider.fetch(5, 20, 7, 'First', 'Last');
+// Generate page range (it's a singleton, use directly)
+let range = PageRangeProvider.fetch(5, 20, 7, 'First', 'Last');
 // Returns: [{label: 'First', value: 1}, {label: 2, value: 2}, ...]
 
 // Simple range
-let simpleRange = pageProvider.fetch(3, 10, 5);
+let simpleRange = PageRangeProvider.fetch(3, 10, 5);
 // Returns pages around current page 3
 ```
 
@@ -98,8 +97,8 @@ const { SchemaValidator } = require('@reldens/utils');
 let schema = {
     username: { type: 'string', min: 3, max: 20 },
     age: { type: 'int', min: 18 },
-    profile: { 
-        type: 'object', 
+    profile: {
+        type: 'object',
         nested: {
             email: { type: 'string', required: true }
         }
@@ -111,6 +110,94 @@ let userData = { username: 'player1', age: 25, profile: { email: 'test@example.c
 let isValid = validator.validate(userData);
 ```
 
+### Shortcuts (sc)
+Core utility class providing essential object manipulation, property access, and validation methods used throughout Reldens.
+
+```javascript
+const { sc } = require('@reldens/utils');
+
+// Safe property access
+let value = sc.get(obj, 'nested.property.path', 'defaultValue');
+
+// Check property ownership
+if (sc.hasOwn(obj, 'propertyName')) {
+    // Property exists
+}
+
+// Type checking
+sc.isObject(value); // true/false
+sc.isArray(value); // true/false
+sc.isFunction(value); // true/false
+
+// Deep operations
+let cloned = sc.deepClone(originalObject);
+let merged = sc.deepMerge(obj1, obj2);
+
+// Property manipulation
+sc.getDef(obj, 'key', 'default'); // Get with default
+sc.getOneDef(obj, ['key1', 'key2'], 'default'); // Get first found key
+```
+
+### ErrorManager
+Singleton error handling utility with configurable tracing and custom error callbacks.
+
+```javascript
+const { ErrorManager } = require('@reldens/utils');
+
+// Enable stack traces
+ErrorManager.enableTrace = true;
+
+// Custom error handling
+ErrorManager.callback = (message) => {
+    // Custom error handling logic
+    console.error('Custom error:', message);
+    // Return false to prevent default throw
+    return false;
+};
+
+// Trigger error
+ErrorManager.error('Something went wrong');
+```
+
+### EnvVar
+Environment variable utilities with type conversion and validation for safe environment variable access.
+
+```javascript
+const { EnvVar } = require('@reldens/utils');
+
+// Get environment variables with type conversion
+let port = EnvVar.integer(process.env, 'PORT', 3000); // Returns integer or default
+let enabled = EnvVar.boolean(process.env, 'FEATURE_ENABLED', false); // Returns boolean
+let apiUrl = EnvVar.string(process.env, 'API_URL', 'http://localhost'); // Returns string
+
+// Other type helpers
+let portNumber = EnvVar.port(process.env, 'PORT', 8080); // Validates port range 1-65535
+let config = EnvVar.json(process.env, 'CONFIG', {}); // Parse JSON string
+let items = EnvVar.array(process.env, 'ITEMS', [], ','); // Split string to array
+let url = EnvVar.url(process.env, 'API_URL', 'http://localhost'); // Validate URL
+```
+
+### ValidatorInterface
+Base interface for creating custom validators with a standard validate method.
+
+```javascript
+const { ValidatorInterface } = require('@reldens/utils');
+
+// Extend to create custom validators
+class CustomValidator extends ValidatorInterface {
+    validate(data) {
+        // Custom validation logic
+        if (!data.requiredField) {
+            return false;
+        }
+        return true;
+    }
+}
+
+let validator = new CustomValidator();
+let isValid = validator.validate({ requiredField: 'value' });
+```
+
 ---
 
 Need something specific?

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@reldens/utils",
     "scope": "@reldens",
-    "version": "0.53.0",
+    "version": "0.54.0",
     "description": "Reldens - Utils",
     "author": "Damian A. Pastorini",
     "license": "MIT",