@reldens/utils 0.50.0 → 0.52.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

@@ -2,55 +2,336 @@
  *
  * Reldens - EventsManager
  *
- * This extension includes a few new features:
- *
- * - The onWithKey and offWithKey methods will allow you to specify a "group" key for the event listener, the related
- * event will be referenced in a new property called "eventsByRemoveKey" so you can detach multiple listeners at the
- * time.
- *
- * - We override the "on" and "off" aliases override to include a debug check with a log. Using the debug property,
- * you can specify to log "all" the fire and listeners, or just by key. Note the key search will be applied in both
- * directions, it will check if the debug value exists in the event key or if the event key exists in the debug value.
- *
  */
 
-const AwaitEventEmitter = require('await-event-emitter').default;
 const Logger = require('./logger');
 const sc = require('./shortcuts');
 
-class AwaitEventEmitterExtended extends AwaitEventEmitter
+class EventsManager
 {
 
     constructor()
     {
-        super();
+        this._events = {};
         this.eventsByRemoveKeys = {};
         this.debug = false;
+        this._listenersCache = {};
+        this._validationCache = new Map();
+        this._debugPatterns = null;
+        this.maxEventKeyLength = 1000;
+        this.maxListeners = 10000;
+        this.maxEventArgs = 50;
+        this.sensitiveFields = ['password', 'token', 'secret', 'key', 'auth', 'credential'];
+        this.hasLoggedMaxListeners = false;
+        this.symbolString = '--[[await-event-emitter]]--';
+        this.typeKeyName = sc.isFunction(Symbol) ? Symbol.for(this.symbolString) : this.symbolString;
+    }
+
+    assertType(type)
+    {
+        if(!sc.isString(type) && !sc.isSymbol(type)){
+            throw new TypeError('type is not type of string or symbol!');
+        }
+    }
+
+    assertFn(fn)
+    {
+        if(!sc.isFunction(fn)){
+            throw new TypeError('fn is not type of Function!');
+        }
+    }
+
+    alwaysListener(fn)
+    {
+        return {
+            [this.typeKeyName]: 'always',
+            fn
+        };
+    }
+
+    onceListener(fn)
+    {
+        return {
+            [this.typeKeyName]: 'once',
+            fn
+        };
     }
 
     validateEventKey(eventKey)
     {
-        return !sc.hasDangerousKeys(null, eventKey);
+        if(this._validationCache.has(eventKey)){
+            return this._validationCache.get(eventKey);
+        }
+        if(sc.isString(eventKey) && eventKey.length > this.maxEventKeyLength){
+            Logger.critical('Event key exceeds maximum length: '+eventKey.length);
+            this._validationCache.set(eventKey, false);
+            return false;
+        }
+        let isValid = !sc.hasDangerousKeys(null, eventKey);
+        this._validationCache.set(eventKey, isValid);
+        return isValid;
+    }
+
+    sanitizeEventArgs(args)
+    {
+        if(!sc.isArray(args)){
+            return [];
+        }
+        if(args.length > this.maxEventArgs){
+            Logger.warning('Event arguments exceed maximum: '+args.length);
+            return [];
+        }
+        return args.map(arg => {
+            if(sc.isObject(arg)){
+                return this.filterSensitiveData(arg);
+            }
+            return arg;
+        });
+    }
+
+    filterSensitiveData(obj)
+    {
+        if(!sc.isObject(obj)){
+            return obj;
+        }
+        let filtered = {};
+        for(let key of Object.keys(obj)){
+            if(sc.hasDangerousKeys(null, key)){
+                continue;
+            }
+            let isKeywordSensitive = this.sensitiveFields.some(sensitive =>
+                key.toLowerCase().includes(sensitive.toLowerCase())
+            );
+            if(isKeywordSensitive){
+                filtered[key] = '[FILTERED]';
+                continue;
+            }
+            if(sc.isObject(obj[key])){
+                filtered[key] = this.filterSensitiveData(obj[key]);
+                continue;
+            }
+            filtered[key] = obj[key];
+        }
+        return filtered;
+    }
+
+    checkMemoryLeaks()
+    {
+        if(this.hasLoggedMaxListeners){
+            return true;
+        }
+        let totalListeners = 0;
+        for(let eventType of Object.keys(this._events)){
+            totalListeners += this._events[eventType].length;
+        }
+        if(totalListeners > this.maxListeners){
+            Logger.debug('High listener count detected: '+totalListeners+' total listeners');
+            this.hasLoggedMaxListeners = true;
+        }
+        return true;
+    }
+
+    addListener(type, fn)
+    {
+        return this.on(type, fn);
+    }
+
+    on(type, fn)
+    {
+        this.assertType(type);
+        this.assertFn(fn);
+        if(!this.validateEventKey(type)){
+            Logger.critical('Invalid event key detected: '+type);
+            return false;
+        }
+        if(false !== this.debug){
+            this.logDebugEvent(type, 'Listen');
+        }
+        this._events[type] = this._events[type] || [];
+        this._events[type].push(this.alwaysListener(fn));
+        delete this._listenersCache[type];
+        this.checkMemoryLeaks();
+        return this;
+    }
+
+    prependListener(type, fn)
+    {
+        return this.prepend(type, fn);
+    }
+
+    prepend(type, fn)
+    {
+        this.assertType(type);
+        this.assertFn(fn);
+        if(!this.validateEventKey(type)){
+            Logger.critical('Invalid event key detected: '+type);
+            return false;
+        }
+        this._events[type] = this._events[type] || [];
+        this._events[type].unshift(this.alwaysListener(fn));
+        delete this._listenersCache[type];
+        this.checkMemoryLeaks();
+        return this;
+    }
+
+    prependOnceListener(type, fn)
+    {
+        return this.prependOnce(type, fn);
+    }
+
+    prependOnce(type, fn)
+    {
+        this.assertType(type);
+        this.assertFn(fn);
+        if(!this.validateEventKey(type)){
+            Logger.critical('Invalid event key detected: '+type);
+            return false;
+        }
+        this._events[type] = this._events[type] || [];
+        this._events[type].unshift(this.onceListener(fn));
+        delete this._listenersCache[type];
+        this.checkMemoryLeaks();
+        return this;
+    }
+
+    listeners(type)
+    {
+        if(this._listenersCache[type]){
+            return this._listenersCache[type];
+        }
+        let result = (this._events[type] || []).map((x) => x.fn);
+        this._listenersCache[type] = result;
+        return result;
+    }
+
+    once(type, fn)
+    {
+        this.assertType(type);
+        this.assertFn(fn);
+        if(!this.validateEventKey(type)){
+            Logger.critical('Invalid event key detected: '+type);
+            return false;
+        }
+        this._events[type] = this._events[type] || [];
+        this._events[type].push(this.onceListener(fn));
+        delete this._listenersCache[type];
+        this.checkMemoryLeaks();
+        return this;
+    }
+
+    removeAllListeners()
+    {
+        this._events = {};
+        this._listenersCache = {};
+    }
+
+    off(type, nullOrFn)
+    {
+        return this.removeListener(type, nullOrFn);
+    }
+
+    removeListener(type, nullOrFn)
+    {
+        this.assertType(type);
+        if(!this.validateEventKey(type)){
+            Logger.critical('Invalid event key detected: '+type);
+            return false;
+        }
+        let listeners = this.listeners(type);
+        if(sc.isFunction(nullOrFn)){
+            let index = -1;
+            let found = false;
+            while(-1 < (index = listeners.indexOf(nullOrFn))){
+                listeners.splice(index, 1);
+                this._events[type].splice(index, 1);
+                found = true;
+            }
+            delete this._listenersCache[type];
+            return found;
+        }
+        delete this._events[type];
+        delete this._listenersCache[type];
+        return true;
+    }
+
+    async emit(type, ...args)
+    {
+        this.assertType(type);
+        if(!this.validateEventKey(type)){
+            Logger.critical('Invalid event key detected: '+type);
+            return false;
+        }
+        let sanitizedArgs = this.sanitizeEventArgs(args);
+        if(false !== this.debug){
+            this.logDebugEvent(type, 'Fire', sanitizedArgs);
+        }
+        this.checkMemoryLeaks();
+        let listeners = this.listeners(type);
+        let onceListeners = [];
+        if(listeners && listeners.length){
+            for(let i = 0; i < listeners.length; i++){
+                let event = listeners[i];
+                let rlt = event.apply(this, sanitizedArgs);
+                if(sc.isPromise(rlt)){
+                    await rlt;
+                }
+                if(this._events[type] && this._events[type][i] && 'once' === this._events[type][i][this.typeKeyName]){
+                    onceListeners.push(event);
+                }
+            }
+            for(let event of onceListeners){
+                this.removeListener(type, event);
+            }
+            return true;
+        }
+        return false;
+    }
+
+    emitSync(type, ...args)
+    {
+        this.assertType(type);
+        if(!this.validateEventKey(type)){
+            Logger.critical('Invalid event key detected: '+type);
+            return false;
+        }
+        let sanitizedArgs = this.sanitizeEventArgs(args);
+        let listeners = this.listeners(type);
+        let onceListeners = [];
+        if(listeners && listeners.length){
+            for(let i = 0; i < listeners.length; i++){
+                let event = listeners[i];
+                event.apply(this, sanitizedArgs);
+                if(this._events[type] && this._events[type][i] && 'once' === this._events[type][i][this.typeKeyName]){
+                    onceListeners.push(event);
+                }
+            }
+            for(let event of onceListeners){
+                this.removeListener(type, event);
+            }
+            return true;
+        }
+        return false;
     }
 
     onWithKey(eventName, callback, uniqueRemoveKey, masterKey)
     {
-        if(!this.validateEventKey(eventName) || !this.validateEventKey(uniqueRemoveKey)){
-            Logger.critical('Invalid event key detected: '+eventName+' or '+uniqueRemoveKey);
+        if(!this.validateEventKey(eventName)){
+            Logger.critical('Invalid event key detected: '+eventName);
+            return false;
+        }
+        if(!this.validateEventKey(uniqueRemoveKey)){
+            Logger.critical('Invalid remove key detected: '+uniqueRemoveKey);
             return false;
         }
         if(masterKey && !this.validateEventKey(masterKey)){
             Logger.critical('Invalid master key detected: '+masterKey);
             return false;
         }
-        if(
-            sc.hasOwn(this.eventsByRemoveKeys, uniqueRemoveKey)
-            || (
-                masterKey
-                && sc.hasOwn(this.eventsByRemoveKeys, masterKey)
-                && sc.hasOwn(this.eventsByRemoveKeys[masterKey], uniqueRemoveKey)
-            )
-        ){
+        if(sc.hasOwn(this.eventsByRemoveKeys, uniqueRemoveKey)){
+            Logger.debug('Event "'+eventName+'" exists with key "'+uniqueRemoveKey+'".');
+            return false;
+        }
+        if(masterKey && sc.hasOwn(this.eventsByRemoveKeys, masterKey) && sc.hasOwn(this.eventsByRemoveKeys[masterKey], uniqueRemoveKey)){
             Logger.debug('Event "'+eventName+'" exists with key "'+uniqueRemoveKey+'" and masterKey "'+masterKey+'".');
             return false;
         }
@@ -69,10 +350,6 @@ class AwaitEventEmitterExtended extends AwaitEventEmitter
         return currentListener;
     }
 
-    /**
-     * This method will remove a SINGLE event using the unique remove key.
-     * If the event listener was assigned using a masterKey then we need to pass it as well to find the event.
-     */
     offWithKey(uniqueRemoveKey, masterKey)
     {
         if(!this.validateEventKey(uniqueRemoveKey)){
@@ -109,6 +386,7 @@ class AwaitEventEmitterExtended extends AwaitEventEmitter
         if(0 === this._events[eventToRemove.eventName].length){
             delete this._events[eventToRemove.eventName];
         }
+        delete this._listenersCache[eventToRemove.eventName];
         if(masterKey){
             delete this.eventsByRemoveKeys[masterKey][uniqueRemoveKey];
             Logger.debug('Deleted event by removeKey "'+uniqueRemoveKey+'" and masterKey "'+masterKey+'".');
@@ -119,9 +397,6 @@ class AwaitEventEmitterExtended extends AwaitEventEmitter
         return true;
     }
 
-    /**
-     * This method will remove ALL the events below the specified masterKey.
-     */
     offByMasterKey(masterKey)
     {
         if(!this.validateEventKey(masterKey)){
@@ -132,14 +407,15 @@ class AwaitEventEmitterExtended extends AwaitEventEmitter
             Logger.debug('Events not found by masterKey "'+masterKey+'".');
             return false;
         }
-        // @NOTE: we loop all the events related to the masterKey and remove them one by one since the _events property
-        // is an object with multiple listeners attached.
         Logger.debug('Removing events by masterKey: '+masterKey, Object.keys(this.eventsByRemoveKeys[masterKey]));
-        for(let uniqueRemoveKey of Object.keys(this.eventsByRemoveKeys[masterKey])){
+        let eventsToRemove = Object.keys(this.eventsByRemoveKeys[masterKey]);
+        let affectedEvents = new Set();
+        for(let uniqueRemoveKey of eventsToRemove){
             let eventToRemove = this.eventsByRemoveKeys[masterKey][uniqueRemoveKey];
             if(!this.validateEventKey(eventToRemove.eventName)){
                 continue;
             }
+            affectedEvents.add(eventToRemove.eventName);
             let dataArr = this.listeners(eventToRemove.eventName);
             let currentListenerIndex = dataArr.indexOf(eventToRemove.callback);
             if(-1 === currentListenerIndex){
@@ -150,44 +426,28 @@ class AwaitEventEmitterExtended extends AwaitEventEmitter
                 delete this._events[eventToRemove.eventName];
             }
         }
-        delete this.eventsByRemoveKeys[masterKey];
-    }
-
-    on(key, callback)
-    {
-        if(!this.validateEventKey(key)){
-            Logger.critical('Invalid event key detected: '+key);
-            return false;
-        }
-        if(false !== this.debug){
-            this.logDebugEvent(key, 'Listen');
+        for(let eventName of affectedEvents){
+            delete this._listenersCache[eventName];
         }
-        super.on(key, callback);
+        delete this.eventsByRemoveKeys[masterKey];
     }
 
-    async emit(key, ...args)
+    logDebugEvent(key, type, args = null)
     {
-        if(!this.validateEventKey(key)){
-            Logger.critical('Invalid event key detected: '+key);
-            return false;
+        if(!this._debugPatterns){
+            this._debugPatterns = new Set(this.debug.split(','));
         }
-        if(false !== this.debug){
-            this.logDebugEvent(key, 'Fire');
+        if(!this._debugPatterns.has('all') && !this._debugPatterns.has(key) && -1 === key.indexOf(this.debug)){
+            return;
         }
-        await super.emit(key, ...args);
-    }
-
-    logDebugEvent(key, type)
-    {
-        if(
-            -1 !== this.debug.indexOf('all')
-            || -1 !== this.debug.indexOf(key)
-            || -1 !== key.indexOf(this.debug)
-        ){
-            Logger.debug(type+' Event:', key);
+        let logMessage = type+' Event: '+key;
+        if(args && 0 < args.length){
+            let filteredArgs = args.map(arg => this.filterSensitiveData(arg));
+            logMessage += ' with '+filteredArgs.length+' arguments';
         }
+        Logger.debug(logMessage);
     }
 
 }
 
-module.exports = AwaitEventEmitterExtended;
+module.exports = EventsManager;