Update 1.0.0-Dev.10

Author: jamesgober

.gitignore

@@ -59,6 +59,8 @@ yarn.lock
 *.env.test.local
 *.env.production.local
 src/copyright.js
+jest.config.js
+jest.setup.js
 
 # Developer-specific folder
 dev/

README.md

@@ -1 +1,23 @@
-# Event Engine
+<h1 align="center">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="./docs/media/jamesgober-logo-dark.png">
+        <img width="72" height="72" alt="Official brand mark and logo of James Gober. Image shows JG stylish initials encased in a hexagon outline." src="./docs/media/jamesgober-logo.png">
+    </picture>
+    <br>
+    <b>EventEngine</b>
+    <br>
+    <sup>
+        <small>JavaScript Library</small>
+    </sup>
+    <br>
+</h1>
+
+&nbsp;
+
+
+## Licence & copyright
+The **EventEngine** JavaScript library is an open-source project licensed under the **MIT** license. 
+
+All rights not explicitly granted in the MIT license are reserved. View the [LICENSE](https://github.com/jamesgober/EventEngine/blob/main/LICENSE) file that was provided with this source code for more information.
+
+Copyright &copy; 2024 James Gober (https://jamesgober.com).

VERSION

@@ -1 +1 @@
-1.0.0-Dev.9
+1.0.0-Dev.10

package.json

@@ -2,7 +2,7 @@
     "name": "eventengine",
     "version": "1.0.0",
     "description": "EventEngine: A lightweight, extensible JavaScript library for managing DOM events with features like namespacing, throttling, debouncing, observables, debugging tools, and a focus on performance and flexibility.",
-    "main": "dist/eventengine.min.js",
+    "main": "dist/events.min.js",
     "scripts": {
         "test": "jest",
         "build": "rollup -c",
@@ -35,7 +35,18 @@
     "devDependencies": {
         "@rollup/plugin-terser": "^0.4.4",
         "eslint": "^8.0.0",
-        "jest": "^29.0.0",
+        "jest": "^29.7.0",
+        "jest-environment-jsdom": "^29.7.0",
+        "jsdom": "^25.0.1",
         "rollup": "^3.20.0"
+    },
+    "jest": {
+        "testEnvironment": "jest-environment-jsdom",
+        "setupFilesAfterEnv": [
+            "<rootDir>/jest.setup.js"
+        ]
+    },
+    "dependencies": {
+        "util": "^0.12.5"
     }
 }

src/EventUtils.js

@@ -0,0 +1,53 @@
+/**
+ * EventUtils - Utility methods for throttling, debouncing, and other event-related operations.
+ */
+const EventUtils = {
+    /**
+     * Creates a throttled version of the given function.
+     *
+     * @param {Function} func - The function to throttle.
+     * @param {number} limit - The time limit in milliseconds.
+     * @returns {Function} - The throttled function.
+     */
+    throttle: function (func, limit) {
+        let lastCall = 0;
+        return function (...args) {
+            const now = Date.now();
+            if (now - lastCall >= limit) {
+                lastCall = now;
+                func.apply(this, args);
+            }
+        };
+    },
+
+    /**
+     * Creates a debounced version of the given function.
+     *
+     * @param {Function} func - The function to debounce.
+     * @param {number} delay - The delay in milliseconds.
+     * @returns {Function} - The debounced function.
+     */
+    debounce: function (func, delay) {
+        let timeoutId;
+        return function (...args) {
+            clearTimeout(timeoutId);
+            timeoutId = setTimeout(() => func.apply(this, args), delay);
+        };
+    },
+
+    /**
+     * Executes an event callback with additional safety and debugging.
+     *
+     * @param {Event} event - The event object.
+     * @param {Function} callback - The callback function.
+     */
+    doEvent: function (event, callback) {
+        try {
+            callback(event);
+        } catch (error) {
+            console.error('Error executing event callback:', error);
+        }
+    },
+};
+// Export the entire EventUtils object
+module.exports = EventUtils;

src/eventengine.js src/events.jssrc/eventengine.js renamed to src/events.js

@@ -1,4 +1,5 @@
-/*                    _                          _                          
+/*
+                      _                          _                          
                      | |                        (_)                         
   _____   _____ _ __ | |_    ___ _ __   __ _ _ _ __   ___ 
  / _ \ \ / / _ \ '_ \| __/  / _ \ '_ \ / _` | | '_ \ / _ \
@@ -7,6 +8,7 @@
                                         __/ |  JS LIBRARY
                                        |___/ 
 */
+
  /*!
  * Event Engine - A High-Performance JavaScript DOM Events Library
  * 
@@ -25,6 +27,16 @@
  * Roles: Developer, Architect, Maintainer, Designer, Project Lead, Author 
  */
 
+
+
+const isNode = typeof window === 'undefined';
+const context = isNode ? {} : window; // Fallback to an empty object in Node.js
+
+// Mock addEventListener in Node.js environment
+if (isNode) {
+  context.addEventListener = () => {}; // No-op
+}
+
 /**
  * Events Module
  * Provides an API for handling browser events with features like namespacing,
@@ -49,10 +61,18 @@
         global.Events = factory(global);
     }
 
-}(typeof global !== 'undefined' ? global : typeof window !== 'undefined' ? window : this, function (window) {
+}(typeof window !== 'undefined' ? window : global, function (window) {
     'use strict';
 
-    const { throttle, debounce, doEvent } = EventUtils; // Import utility methods
+    // import { throttle, debounce, doEvent } from './EventUtils';
+    const EventUtils = require('./EventUtils'); // Adjust the path as needed
+
+    // Destructure the utilities
+    const { throttle, debounce, doEvent } = EventUtils; 
+
+    if (isNode) {
+        console.warn('Events library is running in a Node.js environment. DOM operations are disabled.');
+    }
 
     /**
      * Container for all event handling functionalities.
@@ -64,6 +84,7 @@
      * @private
      */
     const liveEvents = new Map();
+
     /**
      * Stores debugging and analytics data.
      * @private
@@ -84,6 +105,12 @@
      */
     const groups = new Map();
 
+    // Refactor selector validation
+    const isValidSelector = selector =>
+        selector instanceof HTMLElement || 
+        selector === window || 
+        selector === document;
+
     /**
      * Enables debugging mode for event tracking.
      */
@@ -147,56 +174,47 @@
      * @param {boolean} [once=false] - If true, the listener is removed after the first execution.
      * @param {string} [group=''] - Optional group to organize listeners.
      */
-    Events.add = function (types, selector, callback, options = {}, namespace = '', once = false, group = '') {
+    Events.add = function (types, target, callback, options = {}, namespace = '', once = false, group = '') {
+        if (!(target instanceof context.HTMLElement || target === context || target === context.document)) {
+            throw new Error('Invalid target. Must be an instance of HTMLElement, Window, or Document.');
+        }
+
         types.split(',').forEach(type => {
             type = type.trim();
-            let handler = callback;
-
-            if (options.throttle) handler = throttle(callback, options.throttle);
-            if (options.debounce) handler = debounce(callback, options.debounce);
 
-            const listener = {
-                selector,
-                callback: handler,
-                originalCallback: callback,
-                namespace,
-                options,
-                once,
-                priority: options.priority || 0,
-            };
+            const handler = options.throttle
+                ? throttle(callback, options.throttle)
+                : options.debounce
+                ? debounce(callback, options.debounce)
+                : callback;
 
             if (!liveEvents.has(type)) liveEvents.set(type, []);
-            liveEvents.get(type).push(listener);
+            liveEvents.get(type).push({ target, callback: handler });
+
+            target.addEventListener(type, handler, { capture: options.capture || false });
 
             if (group) {
                 if (!groups.has(group)) groups.set(group, []);
-                groups.get(group).push({ type, listener });
+                groups.get(group).push({ type, target, handler });
             }
-
-            window.addEventListener(type, function eventHandlerWrapper(event) {
-                handler.call(selector, event);
-                if (once) {
-                    Events.remove(type, selector, callback, namespace);
-                    window.removeEventListener(type, eventHandlerWrapper, options.capture || false);
-                }
-            }, { capture: options.capture || false, passive: options.passive || false });
         });
     };
 
     /**
      * Removes an event listener or all listeners for a type/namespace.
      */
-    Events.remove = function (types, selector, callback, namespace = '') {
+    /**
+     * Removes an event listener.
+     */
+    Events.remove = function (types, target, callback) {
         types.split(',').forEach(type => {
-            const listeners = liveEvents.get(type) || [];
-            const updatedListeners = listeners.filter(listener =>
-                !(listener.selector === selector && listener.originalCallback === callback && (!namespace || listener.namespace === namespace))
-            );
-
-            if (updatedListeners.length) liveEvents.set(type, updatedListeners);
-            else {
-                liveEvents.delete(type);
-                window.removeEventListener(type, eventHandler, true);
+            target.removeEventListener(type.trim(), callback);
+
+            if (liveEvents.has(type)) {
+                liveEvents.set(
+                    type,
+                    liveEvents.get(type).filter(e => e.target !== target || e.callback !== callback)
+                );
             }
         });
     };

tests/events.test.js

@@ -0,0 +1,34 @@
+const Events = require('../src/events');
+
+describe('Events Module', () => {
+    beforeEach(() => {
+        document.body.innerHTML = ''; // Reset DOM
+    });
+
+    test('should add and trigger an event', () => {
+        const div = document.createElement('div');
+        document.body.appendChild(div);
+
+        const mockCallback = jest.fn();
+        Events.add('click', div, mockCallback);
+
+        const event = new CustomEvent('click');
+        div.dispatchEvent(event);
+
+        expect(mockCallback).toHaveBeenCalledTimes(1);
+    });
+
+    test('should remove an event listener', () => {
+        const div = document.createElement('div');
+        document.body.appendChild(div);
+
+        const mockCallback = jest.fn();
+        Events.add('click', div, mockCallback);
+        Events.remove('click', div, mockCallback);
+
+        const event = new CustomEvent('click');
+        div.dispatchEvent(event);
+
+        expect(mockCallback).not.toHaveBeenCalled();
+    });
+});

tests/sample.test.js

@@ -0,0 +1,3 @@
+test('adds 1 + 2 to equal 3', () => {
+    expect(1 + 2).toBe(3);
+});