@reldens/utils 0.53.0 → 0.55.0

package/CLAUDE.md

@@ -0,0 +1,97 @@
+# 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
+- 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

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/lib/shortcuts.js

@@ -229,9 +229,9 @@ class Shortcuts
         return JSON.parse(this.toJsonString(obj));
     }
 
-    toJsonString(obj)
+    toJsonString(obj, ...args)
     {
-        return JSON.stringify(obj);
+        return JSON.stringify(obj, ...args);
     }
 
     get(obj, prop, defaultReturn)

package/package.json

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

package/tests/events-manager-test.js

@@ -57,7 +57,8 @@ class TestEventsManager
                 console.error('Test method failed:', methodName, error.message);
             }
         }
-        this.printSummary();
+        let failed = this.printSummary();
+        return {total: this.testCount, passed: this.passedCount, failed};
     }
 
     testConstructorCreatesInstance()
@@ -410,14 +411,14 @@ class TestEventsManager
                 username: 'test',
                 password: 'secret123',
                 authToken: 'token123',
-                apiKey: 'key123',
+                secretKey: 'key123',
                 safe: 'data'
             };
             let result = emitter.filterSensitiveData(obj);
             this.assert('test' === result.username, 'Should keep safe fields');
             this.assert('[FILTERED]' === result.password, 'Should filter password');
             this.assert('[FILTERED]' === result.authToken, 'Should filter token');
-            this.assert('[FILTERED]' === result.apiKey, 'Should filter key');
+            this.assert('[FILTERED]' === result.secretKey, 'Should filter key');
             this.assert('data' === result.safe, 'Should keep safe data');
         });
     }
@@ -450,14 +451,14 @@ class TestEventsManager
                     password: 'secret'
                 },
                 config: {
-                    apiKey: 'key123',
+                    secretKey: 'key123',
                     safe: 'value'
                 }
             };
             let result = emitter.filterSensitiveData(obj);
             this.assert('test' === result.user.name, 'Should keep nested safe fields');
             this.assert('[FILTERED]' === result.user.password, 'Should filter nested password');
-            this.assert('[FILTERED]' === result.config.apiKey, 'Should filter nested key');
+            this.assert('[FILTERED]' === result.config.secretKey, 'Should filter nested key');
             this.assert('value' === result.config.safe, 'Should keep nested safe value');
         });
     }
@@ -530,6 +531,7 @@ class TestEventsManager
     {
         this.test('emit uses sanitized arguments', async () => {
             let emitter = new EventsManager();
+            emitter.enableSensitiveDataFiltering = true;
             let receivedArgs = null;
 
             emitter.on('sanitize-test', (...args) => {
@@ -549,6 +551,7 @@ class TestEventsManager
     {
         this.test('emitSync uses sanitized arguments', () => {
             let emitter = new EventsManager();
+            emitter.enableSensitiveDataFiltering = true;
             let receivedArgs = null;
 
             emitter.on('sanitize-sync-test', (...args) => {
@@ -1084,26 +1087,20 @@ class TestEventsManager
 
     printSummary()
     {
-        console.log('\n'+'='.repeat(50));
-        console.log('TEST SUMMARY');
-        console.log('='.repeat(50));
-        console.log('Total tests:', this.testCount);
-        console.log('Passed:', this.passedCount);
-        console.log('Failed:', this.testCount - this.passedCount);
-        console.log('Success rate:', Math.round((this.passedCount / this.testCount) * 100)+'%');
-        if(this.testCount - this.passedCount > 0){
+        let failedCount = this.testCount - this.passedCount;
+        console.log('\n'+'='.repeat(60));
+        console.log('EVENTS MANAGER TEST SUMMARY');
+        console.log('='.repeat(60));
+        console.log('Total: '+this.testCount+' | Passed: '+this.passedCount+' | Failed: '+failedCount);
+        if(0 < failedCount){
             console.log('\nFailed tests:');
             for(let result of this.testResults){
                 if('FAIL' === result.status){
-                    console.log('-', result.name, ':', result.error);
+                    console.log('  ✗ '+result.name+': '+result.error);
                 }
             }
         }
-        console.log('\n'+'='.repeat(60));
-        if(this.testCount - this.passedCount === 0){
-            console.log('All tests completed successfully!');
-        }
-        console.log('='.repeat(60));
+        return failedCount;
     }
 
 }

package/tests/run.js

@@ -4,9 +4,22 @@ async function runTests(){
     console.log('='.repeat(60));
     console.log('TESTING IMPLEMENTATION');
     console.log('='.repeat(60));
+    let suites = [];
+    const { TestShortcuts } = require('./shortcuts-test.js');
+    suites.push(await (new TestShortcuts()).runAllTests());
     const { TestEventsManager } = require('./events-manager-test.js');
-    let testInstance = new TestEventsManager();
-    await testInstance.runAllTests();
+    suites.push(await (new TestEventsManager()).runAllTests());
+    let totalTests = suites.reduce((sum, s) => sum + s.total, 0);
+    let totalPassed = suites.reduce((sum, s) => sum + s.passed, 0);
+    let totalFailed = suites.reduce((sum, s) => sum + s.failed, 0);
+    console.log('\n'+'='.repeat(60));
+    console.log('FINAL TOTAL');
+    console.log('='.repeat(60));
+    console.log('Total: '+totalTests+' | Passed: '+totalPassed+' | Failed: '+totalFailed);
+    console.log('='.repeat(60));
+    if(0 < totalFailed){
+        process.exit(1);
+    }
 }
 
 runTests().catch(error => {