feat: add LavalinkNode class and NodeLink event/health types.

Author: Tomato6966

src/structures/Node.ts

@@ -21,7 +21,7 @@ import type { NodeManager } from "./NodeManager";
 import type {
     BaseNodeStats, LavalinkInfo, LavalinkNodeOptions, LyricsResult, ModifyRequest, NodeLinkConnectionMetrics, NodeStats, SponsorBlockSegment
 } from "./Types/Node";
-import { NodeLinkEventPayload, NodeLinkEventTypes, HealthStatusThreshold, HealthStatusKeys, HealthPerformanceKeys, NodeMetricSummary } from "./Types/NodeLink";
+import { NodeLinkEventPayload, NodeLinkEventTypes, HealthStatusThreshold, HealthStatusKeys, HealthPerformanceKeys, NodeMetricSummary, HealthStatusObject, HealthStatusThresholdOptions } from "./Types/NodeLink";
 /**
  * Lavalink Node creator class
  */
@@ -181,14 +181,6 @@ export class LavalinkNode {
             ...options
         };
 
-        // Allow custom health/capacity thresholds via options.healthThresholds
-        this.healthThresholds = options.healthThresholds || {
-            cpu: { excellent: 0.3, good: 0.5, fair: 0.7, poor: 0.85 },
-            memory: { excellent: 60, good: 75, fair: 85, poor: 95 },
-            ping: { excellent: 50, good: 100, fair: 200, poor: 300 },
-            frameDeficit: { overload: 100, critical: 500 }
-        };
-
         this.NodeManager = manager;
         this.validate();
         if (this.options.secure && this.options.port !== 443) throw new SyntaxError("If secure is true, then the port must be 443");
@@ -933,25 +925,29 @@ export class LavalinkNode {
         return await this.request(`/info`) as LavalinkInfo;
     }
 
-
+    /**
+     * Returns the metric summary of the node
+     * @returns the metric summary of the node
+     */
     public nodeMetricSummary(): NodeMetricSummary {
         if (!this.connected || !this.isAlive) return { systemLoad: 0, cpuLoad: 0, memoryUsage: 0, players: 0, playingPlayers: 0, uptime: 0, ping: 0, frameDeficit: 0 }
-        const cpuLoad = this.stats.cpu.lavalinkLoad;
-        const systemLoad = this.stats.cpu.systemLoad;
         const _memoryUsed = this.stats.memory.used;
         const _memoryAllocated = this.stats.memory.allocated;
-        const memoryUsage = _memoryAllocated > 0 ? (_memoryUsed / _memoryAllocated) * 100 : 0;
-        const players = this.stats.players;
-        const playingPlayers = this.stats.playingPlayers;
-        const frameDeficit = this.stats.frameStats?.deficit || 0;
-        const ping = this.heartBeatPing;
-        const uptime = this.stats.uptime;
-        return { systemLoad, cpuLoad, memoryUsage, players, playingPlayers, uptime, ping, frameDeficit }
+        return {
+            systemLoad: this.stats.cpu.systemLoad,
+            cpuLoad: this.stats.cpu.lavalinkLoad,
+            memoryUsage: _memoryAllocated > 0 ? (_memoryUsed / _memoryAllocated) * 100 : 0,
+            players: this.stats.players,
+            playingPlayers: this.stats.playingPlayers,
+            uptime: this.stats.uptime,
+            ping: this.heartBeatPing,
+            frameDeficit: this.stats.frameStats?.deficit || 0
+        }
     }
     /**
      * Get the node's health status with performance assessment.
      * @returns Object containing health status, performance rating, load balancing info, and recommendations
-     * 
+     *
      * @example
      * ```ts
      * const health = node.getHealthStatus();
@@ -966,31 +962,13 @@ export class LavalinkNode {
      * }
      * ```
      */
-    public getHealthStatus(thresholds?: { cpu: Partial<HealthStatusThreshold>, memory: Partial<HealthStatusThreshold>, ping: Partial<HealthStatusThreshold> }): {
-        status: HealthStatusKeys;
-        performance: HealthPerformanceKeys;
-        isOverloaded: boolean;
-        needsRestart: boolean;
-        penaltyScore: number;
-        estimatedRemainingCapacity: number;
-        recommendations: string[];
-        metrics: {
-            cpuLoad: number;
-            memoryUsage: number;
-            players: number;
-            playingPlayers: number;
-            uptime: number;
-            ping: number;
-            frameDeficit: number;
-        };
-    } {
+    public getHealthStatus(thresholds?: HealthStatusThresholdOptions): HealthStatusObject {
         const cpuThresholds: HealthStatusThreshold = { excellent: 0.3, good: 0.5, fair: 0.7, poor: 0.85, ...thresholds?.cpu };
         const memoryThresholds: HealthStatusThreshold = { excellent: 60, good: 75, fair: 85, poor: 95, ...thresholds?.memory };
         const pingThresholds: HealthStatusThreshold = { excellent: 50, good: 100, fair: 200, poor: 300, ...thresholds?.ping };
         const recommendations: string[] = [];
         const metrics = this.nodeMetricSummary();
-        const { systemLoad, cpuLoad, memoryUsage, players, playingPlayers, uptime, ping, frameDeficit } = metrics;
-        
+
         // Check if node is offline
         if (!this.connected || !this.isAlive) {
             return {
@@ -1000,32 +978,32 @@ export class LavalinkNode {
                 needsRestart: true,
                 penaltyScore: 999999, // Maximum penalty for offline nodes
                 estimatedRemainingCapacity: 0,
-                recommendations: [ RecommendationsStrings.nodeOffline, RecommendationsStrings.checkConnectivity ],
+                recommendations: [RecommendationsStrings.nodeOffline, RecommendationsStrings.checkConnectivity],
                 metrics
             };
         }
 
 
         // Assess CPU performance
         let cpuScore = 0;
-        if (cpuLoad < cpuThresholds.excellent) cpuScore = 4;
-        else if (cpuLoad < cpuThresholds.good) cpuScore = 3;
-        else if (cpuLoad < cpuThresholds.fair) cpuScore = 2;
-        else if (cpuLoad < cpuThresholds.poor) cpuScore = 1;
+        if (metrics.cpuLoad < cpuThresholds.excellent) cpuScore = 4;
+        else if (metrics.cpuLoad < cpuThresholds.good) cpuScore = 3;
+        else if (metrics.cpuLoad < cpuThresholds.fair) cpuScore = 2;
+        else if (metrics.cpuLoad < cpuThresholds.poor) cpuScore = 1;
 
         // Assess memory performance
         let memoryScore = 0;
-        if (memoryUsage < memoryThresholds.excellent) memoryScore = 4;
-        else if (memoryUsage < memoryThresholds.good) memoryScore = 3;
-        else if (memoryUsage < memoryThresholds.fair) memoryScore = 2;
-        else if (memoryUsage < memoryThresholds.poor) memoryScore = 1;
+        if (metrics.memoryUsage < memoryThresholds.excellent) memoryScore = 4;
+        else if (metrics.memoryUsage < memoryThresholds.good) memoryScore = 3;
+        else if (metrics.memoryUsage < memoryThresholds.fair) memoryScore = 2;
+        else if (metrics.memoryUsage < memoryThresholds.poor) memoryScore = 1;
 
         // Assess ping performance
         let pingScore = 0;
-        if (ping < pingThresholds.excellent) pingScore = 4;
-        else if (ping < pingThresholds.good) pingScore = 3;
-        else if (ping < pingThresholds.fair) pingScore = 2;
-        else if (ping < pingThresholds.poor) pingScore = 1;
+        if (metrics.ping < pingThresholds.excellent) pingScore = 4;
+        else if (metrics.ping < pingThresholds.good) pingScore = 3;
+        else if (metrics.ping < pingThresholds.fair) pingScore = 2;
+        else if (metrics.ping < pingThresholds.poor) pingScore = 1;
 
         // Overall performance rating (average of scores)
         const avgScore = (cpuScore + memoryScore + pingScore) / 3;
@@ -1035,36 +1013,36 @@ export class LavalinkNode {
         else if (avgScore >= 1.5) performance = "fair";
 
         // Check if overloaded
-        const isOverloaded = cpuLoad > cpuThresholds.fair || memoryUsage > memoryThresholds.fair || frameDeficit > 100;
-        const isCritical = cpuLoad > cpuThresholds.poor || memoryUsage > memoryThresholds.poor || frameDeficit > 500;
+        const isOverloaded = metrics.cpuLoad > cpuThresholds.fair || metrics.memoryUsage > memoryThresholds.fair || metrics.frameDeficit > 100;
+        const isCritical = metrics.cpuLoad > cpuThresholds.poor || metrics.memoryUsage > memoryThresholds.poor || metrics.frameDeficit > 500;
         // Determine status
         const status: HealthStatusKeys = isCritical ? "critical" : isOverloaded ? "degraded" : "healthy";
 
         // Check if restart is needed
-        const needsRestart = status === "critical" || 
-                             (isOverloaded && memoryUsage > 90) ||
-                             frameDeficit > 1000 ||
-                             (this.reconnectionAttemptCount > 0 && this.reconnectionAttemptCount >= this.options.retryAmount / 2);
+        const needsRestart = status === "critical" ||
+            (isOverloaded && metrics.memoryUsage > 90) ||
+            metrics.frameDeficit > 1000 ||
+            (this.reconnectionAttemptCount > 0 && this.reconnectionAttemptCount >= this.options.retryAmount / 2);
 
         // Generate recommendations
-        if (cpuLoad > cpuThresholds.fair) recommendations.push(RecommendationsStrings.highCPULoad(cpuLoad));
-        if (systemLoad > 0.8) recommendations.push(RecommendationsStrings.highSystemLoad(systemLoad));
-        if (memoryUsage > memoryThresholds.fair) recommendations.push(RecommendationsStrings.highMemoryUsage(memoryUsage));
-        if (frameDeficit > 100) recommendations.push(RecommendationsStrings.frameDeficit(frameDeficit));
-        if (ping > pingThresholds.fair) recommendations.push(RecommendationsStrings.highLatency(ping));
+        if (metrics.cpuLoad > cpuThresholds.fair) recommendations.push(RecommendationsStrings.highCPULoad(metrics.cpuLoad));
+        if (metrics.systemLoad > 0.8) recommendations.push(RecommendationsStrings.highSystemLoad(metrics.systemLoad));
+        if (metrics.memoryUsage > memoryThresholds.fair) recommendations.push(RecommendationsStrings.highMemoryUsage(metrics.memoryUsage));
+        if (metrics.frameDeficit > 100) recommendations.push(RecommendationsStrings.frameDeficit(metrics.frameDeficit));
+        if (metrics.ping > pingThresholds.fair) recommendations.push(RecommendationsStrings.highLatency(metrics.ping));
         if (needsRestart) recommendations.push(RecommendationsStrings.nodeRestart);
-        if (players > 500) recommendations.push(RecommendationsStrings.highPlayercount(players));
+        if (metrics.players > 500) recommendations.push(RecommendationsStrings.highPlayercount(metrics.players));
 
         // Calculate penalty score for load balancing (lower is better)
         // Based on Lavalink's penalty system but customized for health
         const nullFrames = this.stats.frameStats?.nulled || 0;
-        const penaltyScore = players // Player count penalty (each player adds base penalty)
-            + Math.pow(cpuLoad * 100, 2) // CPU penalty (exponential - heavily penalize high CPU)
-            + Math.pow(memoryUsage, 1.5) // Memory penalty (exponential - heavily penalize high memory)
-            + ping * 2 // Latency penalty
-            + frameDeficit * 10 // Frame deficit penalty (critical for audio quality)
+        let penaltyScore = metrics.players // Player count penalty (each player adds base penalty)
+            + Math.pow(metrics.cpuLoad * 100, 2) // CPU penalty (exponential - heavily penalize high CPU)
+            + Math.pow(metrics.memoryUsage, 1.5) // Memory penalty (exponential - heavily penalize high memory)
+            + metrics.ping * 2 // Latency penalty
+            + metrics.frameDeficit * 10 // Frame deficit penalty (critical for audio quality)
             + nullFrames * 5; // Null frame penalty (if available)
-        
+
         // Status penalties
         if (status === "critical") penaltyScore += 10000;
         else if (status === "degraded") penaltyScore += 5000;
@@ -1076,19 +1054,19 @@ export class LavalinkNode {
 
         // Estimate remaining capacity
         let estimatedRemainingCapacity = 0;
-        
+
         // Base capacity estimation on current resource usage
         // Assume a healthy node can handle ~100 players at 50% CPU, ~200 at 70% CPU
-        if (status !== "critical" && status !== "offline") {
-            const cpuCapacity = players === 0
+        if (status !== "critical") {
+            const cpuCapacity = metrics.players === 0
                 ? 200
-                : cpuLoad > 0
-                    ? Math.max(0, Math.floor((cpuThresholds.fair - cpuLoad) / cpuLoad * players))
+                : metrics.cpuLoad > 0
+                    ? Math.max(0, Math.floor((cpuThresholds.fair - metrics.cpuLoad) / metrics.cpuLoad * metrics.players))
                     : 200;
-            const memoryCapacity = players === 0
+            const memoryCapacity = metrics.players === 0
                 ? 200
-                : memoryUsage > 0
-                    ? Math.max(0, Math.floor((memoryThresholds.fair - memoryUsage) / memoryUsage * players))
+                : metrics.memoryUsage > 0
+                    ? Math.max(0, Math.floor((memoryThresholds.fair - metrics.memoryUsage) / metrics.memoryUsage * metrics.players))
                     : 200;
 
             // Use the more conservative estimate, capped at a reasonable maximum
@@ -1364,7 +1342,7 @@ export class LavalinkNode {
         if (this.options.enablePingOnStatsCheck) this.heartBeat();
 
         if (this.heartBeatInterval) clearInterval(this.heartBeatInterval);
-        
+
         if (this.options.heartBeatInterval > 0) {
             // everytime a pong happens, set this.isAlive to true
             this.socket.on("pong", () => {

src/structures/Types/NodeLink.ts

@@ -98,6 +98,7 @@ export type NodeLinkEventPayload<T extends NodeLinkEventTypes> =
     never;
 
 export type HealthStatusThreshold = { excellent: number, good: number, fair: number, poor: number }
+export type HealthStatusThresholdOptions = { cpu: Partial<HealthStatusThreshold>, memory: Partial<HealthStatusThreshold>, ping: Partial<HealthStatusThreshold> };
 export type NodeMetricSummary = {
     cpuLoad: number;
     systemLoad: number;
@@ -108,6 +109,24 @@ export type NodeMetricSummary = {
     ping: number;
     frameDeficit: number;
 }
+export type HealthStatusObject = {
+    status: HealthStatusKeys;
+    performance: HealthPerformanceKeys;
+    isOverloaded: boolean;
+    needsRestart: boolean;
+    penaltyScore: number;
+    estimatedRemainingCapacity: number;
+    recommendations: string[];
+    metrics: {
+        cpuLoad: number;
+        memoryUsage: number;
+        players: number;
+        playingPlayers: number;
+        uptime: number;
+        ping: number;
+        frameDeficit: number;
+    };
+}
 
 export type HealthPerformanceKeys = "excellent" | "good" | "fair" | "poor";
-export type HealthStatusKeys = "healthy" | "degraded" | "critical" | "offline";
+export type HealthStatusKeys = "healthy" | "degraded" | "critical" | "offline";