@nodemod/core 1.0.0

package/dist/enhanced/events.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Internal event listener metadata for enhanced event management.
+ */
+export interface EventListener<T extends keyof nodemod.EventCallbacks> {
+    /** The wrapped handler function */
+    handler: nodemod.EventCallbacks[T];
+    /** The original handler function */
+    original: nodemod.EventCallbacks[T];
+    /** Priority level for execution order */
+    priority: number;
+}
+/**
+ * Options for configuring event listeners.
+ */
+export interface EventOptions {
+    /** Execute the handler only once, then automatically remove it */
+    once?: boolean;
+    /** Priority level (higher numbers execute first) */
+    priority?: number;
+}
+/**
+ * Enhanced player information for connection events.
+ */
+export interface PlayerInfo {
+    /** Player entity */
+    entity: nodemod.Entity;
+    /** Player entity index */
+    id: number;
+    /** Player display name */
+    name: string;
+    /** Player IP address (if available) */
+    address?: string;
+    /** Player Steam ID */
+    steamId: string;
+    /** Player user ID (if available) */
+    userId?: number;
+}
+/**
+ * Enhanced spawn information for entity/player spawn events.
+ */
+export interface SpawnInfo {
+    /** Spawned entity */
+    entity: nodemod.Entity;
+    /** Entity index */
+    id: number;
+    /** Entity name (for players) */
+    name?: string;
+    /** Entity class name */
+    className: string;
+}
+/**
+ * Frame timing and server state information.
+ */
+export interface FrameInfo {
+    /** Current server time */
+    time: number;
+    /** Current map name */
+    mapname: string;
+    /** Number of connected players */
+    playerCount: number;
+}
+/** Type alias for event handler functions */
+export type EventHandler<T extends keyof nodemod.EventCallbacks = keyof nodemod.EventCallbacks> = nodemod.EventCallbacks[T];
+/** Type alias for event filtering predicates */
+export type EventPredicate<T extends keyof nodemod.EventCallbacks = keyof nodemod.EventCallbacks> = (...args: Parameters<nodemod.EventCallbacks[T]>) => boolean;
+/** Type alias for event transformation functions */
+export type EventTransformer<T extends keyof nodemod.EventCallbacks = keyof nodemod.EventCallbacks> = (...args: Parameters<nodemod.EventCallbacks[T]>) => any;
+/**
+ * Enhanced event system providing advanced event handling capabilities on top of nodemod's native events.
+ * Features include priority-based execution, one-time listeners, event filtering, throttling, and debouncing.
+ *
+ * @example
+ * ```typescript
+ * // Basic event listening
+ * nodemodCore.events.on('dllClientConnect', (entity, name) => {
+ *   console.log(`${name} connected`);
+ * });
+ *
+ * // One-time event listener
+ * nodemodCore.events.once('dllSpawn', (entity) => {
+ *   console.log('First spawn event received');
+ * });
+ *
+ * // Priority-based event handling
+ * nodemodCore.events.on('dllClientCommand', handleCommand, { priority: 10 });
+ * nodemodCore.events.on('dllClientCommand', logCommand, { priority: 1 });
+ *
+ * // Event filtering
+ * nodemodCore.events.filter('dllClientConnect',
+ *   (entity, name) => name.startsWith('Admin'),
+ *   (entity, name) => console.log(`Admin ${name} connected`)
+ * );
+ *
+ * // Throttled events (max once per second)
+ * nodemodCore.events.throttle('dllStartFrame', frameHandler, 1000);
+ * ```
+ */
+export default class NodemodEvents {
+    /** Map of active event listeners organized by event name */
+    private eventListeners;
+    /**
+     * Creates a new NodemodEvents instance and initializes enhanced event handlers.
+     */
+    constructor();
+    /**
+     * Adds an event listener with enhanced options like priority and one-time execution.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param handler - Function to execute when event occurs
+     * @param options - Additional options for the listener
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Basic event listener
+     * nodemodCore.events.on('dllClientConnect', (entity, name) => {
+     *   console.log(`${name} joined the server`);
+     * });
+     *
+     * // High-priority listener (executes first)
+     * nodemodCore.events.on('dllClientCommand', (entity, command) => {
+     *   console.log('Processing command:', command);
+     * }, { priority: 100 });
+     *
+     * // One-time listener
+     * nodemodCore.events.on('dllSpawn', (entity) => {
+     *   console.log('First entity spawned');
+     * }, { once: true });
+     * ```
+     */
+    on<T extends keyof nodemod.EventCallbacks>(eventName: T, handler: nodemod.EventCallbacks[T], options?: EventOptions): this;
+    off<T extends keyof nodemod.EventCallbacks>(eventName: T, handler: nodemod.EventCallbacks[T]): this;
+    /**
+     * Adds a one-time event listener that automatically removes itself after first execution.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param handler - Function to execute when event occurs
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Listen for first player connection only
+     * nodemodCore.events.once('dllClientConnect', (entity, name) => {
+     *   console.log(`First player ${name} connected - starting game logic`);
+     * });
+     *
+     * // Wait for map change
+     * nodemodCore.events.once('dllSpawn', () => {
+     *   console.log('Map fully loaded');
+     * });
+     * ```
+     */
+    once<T extends keyof nodemod.EventCallbacks>(eventName: T, handler: nodemod.EventCallbacks[T]): this;
+    clearListeners(eventName?: keyof nodemod.EventCallbacks): this;
+    getListeners<T extends keyof nodemod.EventCallbacks>(eventName: T): EventListener<T>[];
+    private initializeEvents;
+    /**
+     * Waits for a specific event to occur and returns its parameters as a promise.
+     * Useful for async/await patterns with events.
+     *
+     * @param eventName - Name of the event to wait for
+     * @param timeout - Timeout in milliseconds (default: 10000)
+     * @returns Promise that resolves with event parameters or rejects on timeout
+     *
+     * @example
+     * ```typescript
+     * // Wait for player connection
+     * try {
+     *   const [entity, name] = await nodemodCore.events.waitFor('dllClientConnect', 30000);
+     *   console.log(`Player ${name} connected within 30 seconds`);
+     * } catch (error) {
+     *   console.log('No player connected within timeout');
+     * }
+     *
+     * // Wait for entity spawn with shorter timeout
+     * const [spawnedEntity] = await nodemodCore.events.waitFor('dllSpawn', 5000);
+     * ```
+     */
+    waitFor<T extends keyof nodemod.EventCallbacks>(eventName: T, timeout?: number): Promise<Parameters<nodemod.EventCallbacks[T]>>;
+    /**
+     * Adds an event listener that only executes when a predicate condition is met.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param predicate - Function that returns true if the handler should execute
+     * @param handler - Function to execute when event occurs and predicate is true
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Only handle commands from admins
+     * nodemodCore.events.filter('dllClientCommand',
+     *   (entity, command) => isAdmin(entity),
+     *   (entity, command) => handleAdminCommand(entity, command)
+     * );
+     *
+     * // Only handle player connections with specific names
+     * nodemodCore.events.filter('dllClientConnect',
+     *   (entity, name) => name.startsWith('VIP_'),
+     *   (entity, name) => grantVipAccess(entity)
+     * );
+     * ```
+     */
+    filter<T extends keyof nodemod.EventCallbacks>(eventName: T, predicate: EventPredicate<T>, handler: nodemod.EventCallbacks[T]): this;
+    map<T extends keyof nodemod.EventCallbacks>(eventName: T, transformer: EventTransformer<T>, newEventName?: keyof nodemod.EventCallbacks): this;
+    /**
+     * Adds a throttled event listener that limits execution to once per specified interval.
+     * Useful for performance optimization with high-frequency events.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param handler - Function to execute when event occurs
+     * @param delay - Minimum interval between executions in milliseconds (default: 1000)
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Throttle frame events to once per second
+     * nodemodCore.events.throttle('dllStartFrame', () => {
+     *   console.log('Frame update (max once per second)');
+     * }, 1000);
+     *
+     * // Throttle player movement tracking
+     * nodemodCore.events.throttle('dllClientCommand', (entity, command) => {
+     *   if (command.startsWith('+move')) {
+     *     updatePlayerPosition(entity);
+     *   }
+     * }, 500); // Max twice per second
+     * ```
+     */
+    throttle<T extends keyof nodemod.EventCallbacks>(eventName: T, handler: nodemod.EventCallbacks[T], delay?: number): this;
+    /**
+     * Adds a debounced event listener that delays execution until after the specified interval
+     * has passed since the last event occurrence. Useful for handling rapid successive events.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param handler - Function to execute when event occurs
+     * @param delay - Delay in milliseconds after last event before execution (default: 1000)
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Debounce player input to handle final command only
+     * nodemodCore.events.debounce('dllClientCommand', (entity, command) => {
+     *   if (command.startsWith('buy_')) {
+     *     processPurchase(entity, command);
+     *   }
+     * }, 300); // Wait 300ms after last buy command
+     *
+     * // Debounce entity spawning for batch processing
+     * nodemodCore.events.debounce('dllSpawn', () => {
+     *   console.log('Finished spawning entities');
+     *   optimizeMapEntities();
+     * }, 2000);
+     * ```
+     */
+    debounce<T extends keyof nodemod.EventCallbacks>(eventName: T, handler: nodemod.EventCallbacks[T], delay?: number): this;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/enhanced/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/enhanced/events.ts"],"names":[],"mappings":"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"}

package/dist/enhanced/events.js

@@ -0,0 +1,350 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Extend the nodemod namespace to include missing methods
+/**
+ * Enhanced event system providing advanced event handling capabilities on top of nodemod's native events.
+ * Features include priority-based execution, one-time listeners, event filtering, throttling, and debouncing.
+ *
+ * @example
+ * ```typescript
+ * // Basic event listening
+ * nodemodCore.events.on('dllClientConnect', (entity, name) => {
+ *   console.log(`${name} connected`);
+ * });
+ *
+ * // One-time event listener
+ * nodemodCore.events.once('dllSpawn', (entity) => {
+ *   console.log('First spawn event received');
+ * });
+ *
+ * // Priority-based event handling
+ * nodemodCore.events.on('dllClientCommand', handleCommand, { priority: 10 });
+ * nodemodCore.events.on('dllClientCommand', logCommand, { priority: 1 });
+ *
+ * // Event filtering
+ * nodemodCore.events.filter('dllClientConnect',
+ *   (entity, name) => name.startsWith('Admin'),
+ *   (entity, name) => console.log(`Admin ${name} connected`)
+ * );
+ *
+ * // Throttled events (max once per second)
+ * nodemodCore.events.throttle('dllStartFrame', frameHandler, 1000);
+ * ```
+ */
+class NodemodEvents {
+    /** Map of active event listeners organized by event name */
+    eventListeners = new Map();
+    /**
+     * Creates a new NodemodEvents instance and initializes enhanced event handlers.
+     */
+    constructor() {
+        this.initializeEvents();
+    }
+    /**
+     * Adds an event listener with enhanced options like priority and one-time execution.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param handler - Function to execute when event occurs
+     * @param options - Additional options for the listener
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Basic event listener
+     * nodemodCore.events.on('dllClientConnect', (entity, name) => {
+     *   console.log(`${name} joined the server`);
+     * });
+     *
+     * // High-priority listener (executes first)
+     * nodemodCore.events.on('dllClientCommand', (entity, command) => {
+     *   console.log('Processing command:', command);
+     * }, { priority: 100 });
+     *
+     * // One-time listener
+     * nodemodCore.events.on('dllSpawn', (entity) => {
+     *   console.log('First entity spawned');
+     * }, { once: true });
+     * ```
+     */
+    on(eventName, handler, options = {}) {
+        const wrappedHandler = (options.once) ?
+            ((...args) => {
+                handler(...args);
+                this.off(eventName, wrappedHandler);
+            }) : handler;
+        if (!this.eventListeners.has(eventName)) {
+            this.eventListeners.set(eventName, []);
+        }
+        this.eventListeners.get(eventName).push({
+            handler: wrappedHandler,
+            original: handler,
+            priority: options.priority || 0
+        });
+        // Sort by priority (higher priority first)
+        this.eventListeners.get(eventName).sort((a, b) => b.priority - a.priority);
+        nodemod.on(eventName, wrappedHandler);
+        return this;
+    }
+    // Remove event listener
+    off(eventName, handler) {
+        if (!this.eventListeners.has(eventName))
+            return this;
+        const listeners = this.eventListeners.get(eventName);
+        const index = listeners.findIndex(l => l.original === handler || l.handler === handler);
+        if (index !== -1) {
+            nodemod.removeListener(eventName, listeners[index].handler);
+            listeners.splice(index, 1);
+            if (listeners.length === 0) {
+                this.eventListeners.delete(eventName);
+            }
+        }
+        return this;
+    }
+    /**
+     * Adds a one-time event listener that automatically removes itself after first execution.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param handler - Function to execute when event occurs
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Listen for first player connection only
+     * nodemodCore.events.once('dllClientConnect', (entity, name) => {
+     *   console.log(`First player ${name} connected - starting game logic`);
+     * });
+     *
+     * // Wait for map change
+     * nodemodCore.events.once('dllSpawn', () => {
+     *   console.log('Map fully loaded');
+     * });
+     * ```
+     */
+    once(eventName, handler) {
+        return this.on(eventName, handler, { once: true });
+    }
+    // Clear all listeners for an event
+    clearListeners(eventName) {
+        if (eventName) {
+            nodemod.clearListeners(eventName);
+            this.eventListeners.delete(eventName);
+        }
+        else {
+            // Clear all listeners
+            for (const [event] of this.eventListeners) {
+                nodemod.clearListeners(event);
+            }
+            this.eventListeners.clear();
+        }
+        return this;
+    }
+    // Get list of active event listeners
+    getListeners(eventName) {
+        return this.eventListeners.get(eventName) || [];
+    }
+    // Initialize commonly used event handlers with utilities
+    initializeEvents() {
+        // Player connection events with enhanced data
+        this.on('dllClientConnect', (entity, name, address, rejectReason) => {
+            const playerId = nodemod.eng.indexOfEdict(entity);
+            const playerInfo = {
+                entity,
+                id: playerId,
+                name: name,
+                address: address,
+                steamId: nodemod.eng.getPlayerAuthId(entity),
+                userId: nodemod.eng.getPlayerUserId(entity)
+            };
+            // Custom event - not calling nodemod functions
+        });
+        this.on('dllClientDisconnect', (entity) => {
+            const playerId = nodemod.eng.indexOfEdict(entity);
+            const playerInfo = {
+                entity,
+                id: playerId,
+                name: entity.netname,
+                steamId: nodemod.eng.getPlayerAuthId(entity)
+            };
+            // Custom event - not calling nodemod functions
+        });
+        // Enhanced spawn event
+        this.on('dllSpawn', (entity) => {
+            if (entity.netname) {
+                // Player spawn
+                const playerSpawnInfo = {
+                    entity,
+                    id: nodemod.eng.indexOfEdict(entity),
+                    name: entity.netname,
+                    className: entity.classname
+                };
+                // Custom event - not calling nodemod functions
+            }
+            else {
+                // Entity spawn
+                const entitySpawnInfo = {
+                    entity,
+                    id: nodemod.eng.indexOfEdict(entity),
+                    className: entity.classname
+                };
+                // Custom event - not calling nodemod functions
+            }
+        });
+        // Frame timing events
+        this.on('dllStartFrame', () => {
+            const frameInfo = {
+                time: nodemod.time,
+                mapname: nodemod.mapname,
+                playerCount: nodemod.players.length
+            };
+            // Custom event - not calling nodemod functions
+        });
+    }
+    // Custom emit removed - only using nodemod events
+    // Event helper methods
+    /**
+     * Waits for a specific event to occur and returns its parameters as a promise.
+     * Useful for async/await patterns with events.
+     *
+     * @param eventName - Name of the event to wait for
+     * @param timeout - Timeout in milliseconds (default: 10000)
+     * @returns Promise that resolves with event parameters or rejects on timeout
+     *
+     * @example
+     * ```typescript
+     * // Wait for player connection
+     * try {
+     *   const [entity, name] = await nodemodCore.events.waitFor('dllClientConnect', 30000);
+     *   console.log(`Player ${name} connected within 30 seconds`);
+     * } catch (error) {
+     *   console.log('No player connected within timeout');
+     * }
+     *
+     * // Wait for entity spawn with shorter timeout
+     * const [spawnedEntity] = await nodemodCore.events.waitFor('dllSpawn', 5000);
+     * ```
+     */
+    waitFor(eventName, timeout = 10000) {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                this.off(eventName, handler);
+                reject(new Error(`Event ${eventName} timeout after ${timeout}ms`));
+            }, timeout);
+            const handler = ((...args) => {
+                clearTimeout(timeoutId);
+                resolve(args);
+            });
+            this.once(eventName, handler);
+        });
+    }
+    /**
+     * Adds an event listener that only executes when a predicate condition is met.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param predicate - Function that returns true if the handler should execute
+     * @param handler - Function to execute when event occurs and predicate is true
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Only handle commands from admins
+     * nodemodCore.events.filter('dllClientCommand',
+     *   (entity, command) => isAdmin(entity),
+     *   (entity, command) => handleAdminCommand(entity, command)
+     * );
+     *
+     * // Only handle player connections with specific names
+     * nodemodCore.events.filter('dllClientConnect',
+     *   (entity, name) => name.startsWith('VIP_'),
+     *   (entity, name) => grantVipAccess(entity)
+     * );
+     * ```
+     */
+    filter(eventName, predicate, handler) {
+        const wrappedHandler = function (...args) {
+            if (predicate(...args)) {
+                // @ts-ignore - TypeScript can't guarantee spread matches exact signature but it's safe here
+                return handler(...args);
+            }
+        };
+        return this.on(eventName, wrappedHandler);
+    }
+    // Event mapping/transformation
+    map(eventName, transformer, newEventName) {
+        return this.on(eventName, ((...args) => {
+            const transformed = transformer(...args);
+            // Note: mapping to custom events not supported in strict mode
+        }));
+    }
+    /**
+     * Adds a throttled event listener that limits execution to once per specified interval.
+     * Useful for performance optimization with high-frequency events.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param handler - Function to execute when event occurs
+     * @param delay - Minimum interval between executions in milliseconds (default: 1000)
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Throttle frame events to once per second
+     * nodemodCore.events.throttle('dllStartFrame', () => {
+     *   console.log('Frame update (max once per second)');
+     * }, 1000);
+     *
+     * // Throttle player movement tracking
+     * nodemodCore.events.throttle('dllClientCommand', (entity, command) => {
+     *   if (command.startsWith('+move')) {
+     *     updatePlayerPosition(entity);
+     *   }
+     * }, 500); // Max twice per second
+     * ```
+     */
+    throttle(eventName, handler, delay = 1000) {
+        let lastCall = 0;
+        const wrappedHandler = function (...args) {
+            const now = Date.now();
+            if (now - lastCall >= delay) {
+                lastCall = now;
+                // @ts-ignore - TypeScript can't guarantee spread matches exact signature but it's safe here
+                return handler(...args);
+            }
+        };
+        return this.on(eventName, wrappedHandler);
+    }
+    /**
+     * Adds a debounced event listener that delays execution until after the specified interval
+     * has passed since the last event occurrence. Useful for handling rapid successive events.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param handler - Function to execute when event occurs
+     * @param delay - Delay in milliseconds after last event before execution (default: 1000)
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Debounce player input to handle final command only
+     * nodemodCore.events.debounce('dllClientCommand', (entity, command) => {
+     *   if (command.startsWith('buy_')) {
+     *     processPurchase(entity, command);
+     *   }
+     * }, 300); // Wait 300ms after last buy command
+     *
+     * // Debounce entity spawning for batch processing
+     * nodemodCore.events.debounce('dllSpawn', () => {
+     *   console.log('Finished spawning entities');
+     *   optimizeMapEntities();
+     * }, 2000);
+     * ```
+     */
+    debounce(eventName, handler, delay = 1000) {
+        let timeoutId;
+        const wrappedHandler = function (...args) {
+            clearTimeout(timeoutId);
+            // @ts-ignore - TypeScript can't guarantee spread matches exact signature but it's safe here
+            timeoutId = setTimeout(() => handler(...args), delay);
+        };
+        return this.on(eventName, wrappedHandler);
+    }
+}
+exports.default = NodemodEvents;
+//# sourceMappingURL=events.js.map

package/dist/enhanced/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/enhanced/events.ts"],"names":[],"mappings":"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"}