@reldens/utils 0.52.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/lib/events-manager.js

@@ -21,10 +21,11 @@ class EventsManager
         this.maxEventKeyLength = 1000;
         this.maxListeners = 10000;
         this.maxEventArgs = 50;
-        this.sensitiveFields = ['password', 'token', 'secret', 'key', 'auth', 'credential'];
+        this.sensitiveFields = ['password', 'token', 'secret', 'auth', 'credential'];
         this.hasLoggedMaxListeners = false;
         this.symbolString = '--[[await-event-emitter]]--';
         this.typeKeyName = sc.isFunction(Symbol) ? Symbol.for(this.symbolString) : this.symbolString;
+        this.enableSensitiveDataFiltering = false;
     }
 
     assertType(type)
@@ -81,6 +82,9 @@ class EventsManager
             Logger.warning('Event arguments exceed maximum: '+args.length);
             return [];
         }
+        if(!this.enableSensitiveDataFiltering){
+            return args;
+        }
         return args.map(arg => {
             if(sc.isObject(arg)){
                 return this.filterSensitiveData(arg);
@@ -89,11 +93,21 @@ class EventsManager
         });
     }
 
-    filterSensitiveData(obj)
+    filterSensitiveData(obj, visited = new WeakSet())
     {
         if(!sc.isObject(obj)){
             return obj;
         }
+        if(visited.has(obj)){
+            return '[CIRCULAR]';
+        }
+        if(obj instanceof Map || obj instanceof Set || obj instanceof Date || obj instanceof Array){
+            return obj;
+        }
+        if(Object.getPrototypeOf(obj) !== Object.prototype){
+            return obj;
+        }
+        visited.add(obj);
         let filtered = {};
         for(let key of Object.keys(obj)){
             if(sc.hasDangerousKeys(null, key)){
@@ -107,11 +121,16 @@ class EventsManager
                 continue;
             }
             if(sc.isObject(obj[key])){
-                filtered[key] = this.filterSensitiveData(obj[key]);
+                filtered[key] = this.filterSensitiveData(obj[key], visited);
+                continue;
+            }
+            if(sc.isFunction(obj[key])) {
+                filtered[key] = obj[key];
                 continue;
             }
             filtered[key] = obj[key];
         }
+        visited.delete(obj);
         return filtered;
     }
 
@@ -442,7 +461,9 @@ class EventsManager
         }
         let logMessage = type+' Event: '+key;
         if(args && 0 < args.length){
-            let filteredArgs = args.map(arg => this.filterSensitiveData(arg));
+            let filteredArgs = this.enableSensitiveDataFiltering
+                ? args.map(arg => this.filterSensitiveData(arg))
+                : args;
             logMessage += ' with '+filteredArgs.length+' arguments';
         }
         Logger.debug(logMessage);

package/package.json

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

package/tests/events-manager-test.js

@@ -1,3 +1,9 @@
+/**
+ *
+ * Reldens - TestEventsManager
+ *
+ */
+
 const EventsManager = require('../lib/events-manager');
 
 class TestEventsManager
@@ -8,6 +14,7 @@ class TestEventsManager
         this.testResults = [];
         this.testCount = 0;
         this.passedCount = 0;
+        this.currentTestMethod = '';
     }
 
     test(name, testFn)
@@ -15,11 +22,13 @@ class TestEventsManager
         this.testCount++;
         try{
             testFn();
-            console.log('✓ PASS:', name);
+            let logMessage = '✓ PASS: '+this.currentTestMethod+' - '+name;
+            console.log(logMessage);
             this.passedCount++;
             this.testResults.push({name, status: 'PASS'});
         } catch(error){
-            console.log('✗ FAIL:', name, '-', error.message);
+            let logMessage = '✗ FAIL: '+this.currentTestMethod+' - '+name+' - '+error.message;
+            console.log(logMessage);
             this.testResults.push({name, status: 'FAIL', error: error.message});
         }
     }
@@ -31,21 +40,23 @@ class TestEventsManager
         }
     }
 
-    runAllTests()
+    async runAllTests()
     {
         console.log('Running tests for EventsManager...\n');
-
         let methodNames = Object.getOwnPropertyNames(Object.getPrototypeOf(this));
         let testMethods = methodNames.filter(name =>
             name.startsWith('test') &&
             'function' === typeof this[name] &&
             name !== 'test'
         );
-
         for(let methodName of testMethods){
-            this[methodName]();
+            this.currentTestMethod = methodName;
+            try{
+                await this[methodName]();
+            } catch(error){
+                console.error('Test method failed:', methodName, error.message);
+            }
         }
-
         this.printSummary();
     }
 
@@ -289,16 +300,17 @@ class TestEventsManager
             let loggedMessages = [];
             let originalDebug = console.log;
 
-            console.log = (...args) => loggedMessages.push(args.join(' '));
-            process.env.RELDENS_LOG_LEVEL = 8;
-
-            for(let i = 0; i < 10; i++){
-                emitter.on('test-max-'+i, () => {});
+            try{
+                console.log = (...args) => loggedMessages.push(args.join(' '));
+                process.env.RELDENS_LOG_LEVEL = 8;
+                for(let i = 0; i < 10; i++){
+                    emitter.on('test-max-'+i, () => {});
+                }
+            } finally{
+                console.log = originalDebug;
+                delete process.env.RELDENS_LOG_LEVEL;
             }
 
-            console.log = originalDebug;
-            delete process.env.RELDENS_LOG_LEVEL;
-
             let debugLogs = loggedMessages.filter(log => log.includes('High listener count detected'));
             this.assert(1 === debugLogs.length, 'Should log high listener count only once');
             this.assert(true === emitter.hasLoggedMaxListeners, 'Should set flag after logging');
@@ -498,14 +510,15 @@ class TestEventsManager
             let loggedMessages = [];
             let originalLog = console.log;
 
-            console.log = (...args) => loggedMessages.push(args.join(' '));
-            process.env.RELDENS_LOG_LEVEL = 8;
-
-            let sensitiveArgs = [{password: 'secret', safe: 'data'}];
-            emitter.logDebugEvent('test', 'Fire', sensitiveArgs);
-
-            console.log = originalLog;
-            delete process.env.RELDENS_LOG_LEVEL;
+            try{
+                console.log = (...args) => loggedMessages.push(args.join(' '));
+                process.env.RELDENS_LOG_LEVEL = 8;
+                let sensitiveArgs = [{password: 'secret', safe: 'data'}];
+                emitter.logDebugEvent('test', 'Fire', sensitiveArgs);
+            } finally{
+                console.log = originalLog;
+                delete process.env.RELDENS_LOG_LEVEL;
+            }
 
             let debugLog = loggedMessages.find(log => log.includes('Fire Event: test'));
             this.assert(debugLog, 'Should log debug event');
@@ -580,13 +593,14 @@ class TestEventsManager
 
             let loggedMessages = [];
             let originalLog = console.log;
-            console.log = (...args) => loggedMessages.push(args.join(' '));
-            process.env.RELDENS_LOG_LEVEL = 8;
-
-            emitter.logDebugEvent('non-matching-key', 'Listen');
-
-            console.log = originalLog;
-            delete process.env.RELDENS_LOG_LEVEL;
+            try{
+                console.log = (...args) => loggedMessages.push(args.join(' '));
+                process.env.RELDENS_LOG_LEVEL = 8;
+                emitter.logDebugEvent('non-matching-key', 'Listen');
+            } finally{
+                console.log = originalLog;
+                delete process.env.RELDENS_LOG_LEVEL;
+            }
 
             let debugLogs = loggedMessages.filter(log => log.includes('Listen Event:'));
             this.assert(0 === debugLogs.length, 'Should not log when no pattern matches');
@@ -894,17 +908,16 @@ class TestEventsManager
             let emitter = new EventsManager();
             let loggedEvents = [];
             let originalLog = console.log;
-
-            console.log = (...args) => loggedEvents.push(args.join(' '));
-            process.env.RELDENS_LOG_LEVEL = 8;
-            emitter.debug = 'all';
-
-            emitter.on('debug-test', () => {});
-            await emitter.emit('debug-test');
-
-            console.log = originalLog;
-            delete process.env.RELDENS_LOG_LEVEL;
-
+            try{
+                console.log = (...args) => loggedEvents.push(args.join(' '));
+                process.env.RELDENS_LOG_LEVEL = 8;
+                emitter.debug = 'all';
+                emitter.on('debug-test', () => {});
+                await emitter.emit('debug-test');
+            } finally{
+                console.log = originalLog;
+                delete process.env.RELDENS_LOG_LEVEL;
+            }
             let hasListenLog = loggedEvents.some(log => log.includes('Listen Event:'));
             let hasFireLog = loggedEvents.some(log => log.includes('Fire Event:'));
             this.assert(hasListenLog, 'Should log listen events');
@@ -1058,6 +1071,17 @@ class TestEventsManager
         });
     }
 
+    testFilterSensitiveDataWithCircularReferences()
+    {
+        this.test('filterSensitiveData handles circular references', () => {
+            let emitter = new EventsManager();
+            let obj = {safe: 'data'};
+            obj.circular = obj;
+            let result = emitter.filterSensitiveData(obj);
+            this.assert('[CIRCULAR]' === result.circular, 'Should handle circular refs');
+        });
+    }
+
     printSummary()
     {
         console.log('\n'+'='.repeat(50));
@@ -1067,7 +1091,6 @@ class TestEventsManager
         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){
             console.log('\nFailed tests:');
             for(let result of this.testResults){
@@ -1076,9 +1099,13 @@ class TestEventsManager
                 }
             }
         }
+        console.log('\n'+'='.repeat(60));
+        if(this.testCount - this.passedCount === 0){
+            console.log('All tests completed successfully!');
+        }
+        console.log('='.repeat(60));
     }
 
 }
 
-let testRunner = new TestEventsManager();
-testRunner.runAllTests();
+module.exports.TestEventsManager = TestEventsManager;

package/tests/run.js

@@ -1,13 +1,15 @@
 console.log('Running all tests...\n');
 
-try{
+async function runTests(){
     console.log('='.repeat(60));
-    console.log('TESTING NEW IMPLEMENTATION');
+    console.log('TESTING IMPLEMENTATION');
     console.log('='.repeat(60));
-    require('./events-manager-test.js');
+    const { TestEventsManager } = require('./events-manager-test.js');
+    let testInstance = new TestEventsManager();
+    await testInstance.runAllTests();
+}
 
-    console.log('\n\nAll tests completed successfully!');
-} catch(error){
+runTests().catch(error => {
     console.error('\nTest execution failed:', error.message);
     process.exit(1);
-}
+});