@reldens/utils 0.51.0 → 0.53.0

package/README.md

@@ -2,7 +2,7 @@
 
 # Reldens - Utils
 
-### Features
+## Features
 
 - Interaction area calculation helper.
 - Page range provider helper.
@@ -13,6 +13,106 @@
 - Error Manager.
 - Events Manager and Events Manager Singleton.
 
+---
+
+## Usage examples
+
+### EventsManager
+Advanced event emitter with features like event sanitization, memory leak detection, key-based event management, and support for async/sync execution.
+
+```javascript
+const { EventsManager } = require('@reldens/utils');
+let eventsManager = new EventsManager();
+
+// Listen to events
+eventsManager.on('userLogin', (userData) => {
+    console.log('User logged in:', userData.username);
+});
+
+// Emit events
+eventsManager.emit('userLogin', { username: 'player1', id: 123 });
+
+// Listen with unique keys
+eventsManager.onWithKey('gameStart', callback, 'uniqueKey');
+eventsManager.offWithKey('uniqueKey'); // Remove by key
+```
+
+### InteractionArea
+Spatial interaction validation helper that determines if objects are within interaction range based on coordinates and area margins.
+
+```javascript
+const { InteractionArea } = require('@reldens/utils');
+let interactionArea = new InteractionArea();
+
+// Setup interaction area
+interactionArea.setupInteractionArea(50, 100, 200); // margin=50, x=100, y=200
+
+// Validate interaction
+let isValid = interactionArea.isValidInteraction(120, 210); // true
+let isInvalid = interactionArea.isValidInteraction(200, 300); // false
+```
+
+### Logger
+Advanced logging utility with multiple log levels, custom levels support, active level filtering, and environment-based configuration.
+
+```javascript
+const { Logger } = require('@reldens/utils');
+
+// Standard logging
+Logger.info('Application started');
+Logger.error('Database connection failed', errorDetails);
+Logger.debug('Processing user request', requestData);
+
+// Custom levels
+Logger.activeLogLevels = [3, 4, 10]; // Only critical, error, and custom level 10
+Logger.customLevels = [10, 11, 12];
+Logger.log(10, 'custom', 'Custom log message');
+
+// Configuration
+Logger.setForcedDisabled(false);
+Logger.setAddTimeStamp(true);
+```
+
+### PageRangeProvider
+Pagination helper that calculates page ranges for UI components, handling first/last page navigation and customizable display options.
+
+```javascript
+const { PageRangeProvider } = require('@reldens/utils');
+let pageProvider = new PageRangeProvider();
+
+// Generate page range
+let range = pageProvider.fetch(5, 20, 7, 'First', 'Last');
+// Returns: [{label: 'First', value: 1}, {label: 2, value: 2}, ...]
+
+// Simple range
+let simpleRange = pageProvider.fetch(3, 10, 5);
+// Returns pages around current page 3
+```
+
+### SchemaValidator
+Object validation utility that validates object properties against defined schemas with support for nested objects and custom validation rules.
+
+```javascript
+const { SchemaValidator } = require('@reldens/utils');
+
+let schema = {
+    username: { type: 'string', min: 3, max: 20 },
+    age: { type: 'int', min: 18 },
+    profile: { 
+        type: 'object', 
+        nested: {
+            email: { type: 'string', required: true }
+        }
+    }
+};
+
+let validator = new SchemaValidator(schema);
+let userData = { username: 'player1', age: 25, profile: { email: 'test@example.com' } };
+let isValid = validator.validate(userData);
+```
+
+---
+
 Need something specific?
 
 [Request a feature here: https://www.reldens.com/features-request](https://www.reldens.com/features-request)

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

@@ -32,6 +32,8 @@ class Logger
         this.maxLogArgLength = sc.get(context, 'RELDENS_LOGS_MAX_ARGUMENT_LENGTH', 0);
         this.maxStackTraceLength = sc.get(context, 'RELDENS_LOGS_MAX_STACK_TRACE_LENGTH', 0);
         this.applySanitizer = Boolean(sc.get(context, 'RELDENS_LOGS_APPLY_SANITIZER', false));
+        this.activeLogLevels = [];
+        this.customLevels = [];
     }
 
     context()
@@ -91,8 +93,21 @@ class Logger
         return (this.context().RELDENS_ENABLE_TRACE_FOR || '').split(',');
     }
 
-    log(levelLabel, ...args)
+    log(levelNumber, levelLabel, ...args)
     {
+        if(this.forcedDisabled){
+            return this;
+        }
+        if(0 < this.activeLogLevels.length){
+            if(-1 === this.activeLogLevels.indexOf(levelNumber)){
+                return this;
+            }
+        }
+        if(0 === this.activeLogLevels.length){
+            if(levelNumber > this.logLevel()){
+                return this;
+            }
+        }
         let date = !this.addTimeStamp ? '' : (new Date()).toISOString().slice(0, 19).replace('T', ' ')+' - ';
         let processedArgs = args;
         if(this.applySanitizer){
@@ -125,90 +140,42 @@ class Logger
 
     debug(...args)
     {
-        if(this.forcedDisabled){
-            return this;
-        }
-        if(8 > this.logLevel()){
-            return this;
-        }
-        return this.log('debug', ...args);
+        return this.log(8, 'debug', ...args);
     }
 
     info(...args)
     {
-        if(this.forcedDisabled){
-            return this;
-        }
-        if(7 > this.logLevel()){
-            return this;
-        }
-        return this.log('info', ...args);
+        return this.log(7, 'info', ...args);
     }
 
     notice(...args)
     {
-        if(this.forcedDisabled){
-            return this;
-        }
-        if(6 > this.logLevel()){
-            return this;
-        }
-        return this.log('notice', ...args);
+        return this.log(6, 'notice', ...args);
     }
 
     warning(...args)
     {
-        if(this.forcedDisabled){
-            return this;
-        }
-        if(5 > this.logLevel()){
-            return this;
-        }
-        return this.log('warning', ...args);
+        return this.log(5, 'warning', ...args);
     }
 
     error(...args)
     {
-        if(this.forcedDisabled){
-            return this;
-        }
-        if(4 > this.logLevel()){
-            return this;
-        }
-        return this.log('error', ...args);
+        return this.log(4, 'error', ...args);
     }
 
     critical(...args)
     {
-        if(this.forcedDisabled){
-            return this;
-        }
-        if(3 > this.logLevel()){
-            return this;
-        }
-        return this.log('critical', ...args);
+        return this.log(3, 'critical', ...args);
     }
 
     alert(...args)
     {
-        if(this.forcedDisabled){
-            return this;
-        }
-        if(2 > this.logLevel()){
-            return this;
-        }
-        return this.log('alert', ...args);
+        return this.log(2, 'alert', ...args);
     }
 
     emergency(...args)
     {
-        if(this.forcedDisabled){
-            return this;
-        }
-        if(1 > this.logLevel()){
-            return this;
-        }
-        return this.log('emergency', ...args);
+        return this.log(1, 'emergency', ...args);
     }
 
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@reldens/utils",
     "scope": "@reldens",
-    "version": "0.51.0",
+    "version": "0.53.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);
-}
+});