lavalink-client 2.3.1 → 2.3.3

package/dist/esm/structures/Types/Manager.d.ts

@@ -1,3 +1,4 @@
+import type { DebugEvents } from "../Constants";
 import type { Player } from "../Player";
 import type { LavalinkNodeOptions } from "./Node";
 import type { DestroyReasonsType, PlayerJson } from "./Player";
@@ -100,6 +101,19 @@ export interface LavalinkManagerEvents {
      * @event Manager#trackError
      */
     "ChaptersLoaded": (player: Player, track: Track | UnresolvedTrack | null, payload: SponsorBlockChaptersLoaded) => void;
+    /**
+     * Lavalink-Client Debug Event
+     * Emitted for several erros, and logs within lavalink-client, if managerOptions.advancedOptions.enableDebugEvents is true
+     * Useful for debugging the lavalink-client
+     *
+     * @event Manager#debug
+     */
+    "debug": (eventKey: DebugEvents, eventData: {
+        message: string;
+        state: "log" | "warn" | "error";
+        error?: Error | string;
+        functionLayer: string;
+    }) => void;
 }
 /**
  * The Bot client Options needed for the manager
@@ -131,6 +145,15 @@ export interface ManagerPlayerOptions {
         /** Instantly destroy player (overrides autoReconnect) | Don't provide == disable feature*/
         destroyPlayer?: boolean;
     };
+    /** Minimum time to play the song before autoPlayFunction is executed (prevents error spamming) Set to 0 to disable it @default 10000 */
+    minAutoPlayMs?: number;
+    /** Allows you to declare how many tracks are allowed to error/stuck within a time-frame before player is destroyed @default "{threshold: 35000, maxAmount: 3 }" */
+    maxErrorsPerTime?: {
+        /** The threshold time to count errors (recommended is 35s) */
+        threshold: number;
+        /** The max amount of errors within the threshold time which are allowed before destroying the player (when errors > maxAmount -> player.destroy()) */
+        maxAmount: number;
+    };
     onEmptyQueue?: {
         /** Get's executed onEmptyQueue -> You can do any track queue previous transformations, if you add a track to the queue -> it will play it, if not queueEnd will execute! */
         autoPlayFunction?: (player: Player, lastPlayedTrack: Track) => Promise<void>;
@@ -166,6 +189,8 @@ export interface ManagerOptions {
     advancedOptions?: {
         /** Max duration for that the filter fix duration works (in ms) - default is 8mins */
         maxFilterFixDuration?: number;
+        /** Enable Debug event */
+        enableDebugEvents?: boolean;
         /** optional */
         debugOptions?: {
             /** For logging custom searches */

package/dist/esm/structures/Types/Queue.d.ts

@@ -28,7 +28,7 @@ export interface QueueChangesWatcher {
     /** get a Value (MUST RETURN UNPARSED!) */
     tracksAdd: (guildId: string, tracks: (Track | UnresolvedTrack)[], position: number, oldStoredQueue: StoredQueue, newStoredQueue: StoredQueue) => void;
     /** Set a value inside a guildId (MUST BE UNPARSED) */
-    tracksRemoved: (guildId: string, tracks: (Track | UnresolvedTrack)[], position: number, oldStoredQueue: StoredQueue, newStoredQueue: StoredQueue) => void;
+    tracksRemoved: (guildId: string, tracks: (Track | UnresolvedTrack)[], position: number | number[], oldStoredQueue: StoredQueue, newStoredQueue: StoredQueue) => void;
     /** Set a value inside a guildId (MUST BE UNPARSED) */
     shuffled: (guildId: string, oldStoredQueue: StoredQueue, newStoredQueue: StoredQueue) => void;
 }

package/dist/esm/structures/Utils.js

@@ -1,5 +1,6 @@
 import { URL } from "node:url";
 import { isRegExp } from "node:util/types";
+import { DebugEvents } from "./Constants";
 import { DefaultSources, LavalinkPlugins, SourceLinksRegexes } from "./LavalinkManagerStatics";
 export const TrackSymbol = Symbol("LC-Track");
 export const UnresolvedTrackSymbol = Symbol("LC-Track-Unresolved");
@@ -71,6 +72,14 @@ export class ManagerUtils {
             return r;
         }
         catch (error) {
+            if (this.LavalinkManager?.options?.advancedOptions?.enableDebugEvents) {
+                this.LavalinkManager?.emit("debug", DebugEvents.BuildTrackError, {
+                    error: error,
+                    functionLayer: "ManagerUtils > buildTrack()",
+                    message: "Error while building track",
+                    state: "error",
+                });
+            }
             throw new RangeError(`Argument "data" is not a valid track: ${error.message}`);
         }
     }
@@ -129,7 +138,14 @@ export class ManagerUtils {
                 : requester;
         }
         catch (e) {
-            console.error("errored while transforming requester:", e);
+            if (this.LavalinkManager?.options?.advancedOptions?.enableDebugEvents) {
+                this.LavalinkManager?.emit("debug", DebugEvents.TransformRequesterFunctionFailed, {
+                    error: e,
+                    functionLayer: "ManagerUtils > getTransformedRequester()",
+                    message: "Your custom transformRequesterFunction failed to execute, please check your function for errors.",
+                    state: "error",
+                });
+            }
             return requester;
         }
     }
@@ -195,62 +211,96 @@ export class ManagerUtils {
         return typeof data === "object" && !("info" in data) && typeof data.title === "string";
     }
     async getClosestTrack(data, player) {
-        return getClosestTrack(data, player);
+        try {
+            return getClosestTrack(data, player);
+        }
+        catch (e) {
+            if (this.LavalinkManager?.options?.advancedOptions?.enableDebugEvents) {
+                this.LavalinkManager?.emit("debug", DebugEvents.GetClosestTrackFailed, {
+                    error: e,
+                    functionLayer: "ManagerUtils > getClosestTrack()",
+                    message: "Failed to resolve track because the getClosestTrack function failed.",
+                    state: "error",
+                });
+            }
+            throw e;
+        }
     }
     validateQueryString(node, queryString, sourceString) {
         if (!node.info)
             throw new Error("No Lavalink Node was provided");
         if (!node.info.sourceManagers?.length)
             throw new Error("Lavalink Node, has no sourceManagers enabled");
+        if (!queryString.trim().length)
+            throw new Error(`Query string is empty, please provide a valid query string.`);
         if (sourceString === "speak" && queryString.length > 100)
-            // checks for blacklisted links / domains / queries
-            if (this.LavalinkManager.options?.linksBlacklist?.length > 0 && this.LavalinkManager.options?.linksBlacklist.some(v => (typeof v === "string" && (queryString.toLowerCase().includes(v.toLowerCase()) || v.toLowerCase().includes(queryString.toLowerCase()))) || isRegExp(v) && v.test(queryString))) {
+            throw new Error(`Query is speak, which is limited to 100 characters.`);
+        // checks for blacklisted links / domains / queries
+        if (this.LavalinkManager.options?.linksBlacklist?.length > 0) {
+            if (this.LavalinkManager.options?.advancedOptions?.enableDebugEvents) {
+                this.LavalinkManager.emit("debug", DebugEvents.ValidatingBlacklistLinks, {
+                    state: "log",
+                    message: `Validating Query against LavalinkManager.options.linksBlacklist, query: "${queryString}"`,
+                    functionLayer: "(LavalinkNode > node | player) > search() > validateQueryString()",
+                });
+            }
+            if (this.LavalinkManager.options?.linksBlacklist.some(v => (typeof v === "string" && (queryString.toLowerCase().includes(v.toLowerCase()) || v.toLowerCase().includes(queryString.toLowerCase()))) || isRegExp(v) && v.test(queryString))) {
                 throw new Error(`Query string contains a link / word which is blacklisted.`);
             }
+        }
         if (!/^https?:\/\//.test(queryString))
             return;
         else if (this.LavalinkManager.options?.linksAllowed === false)
             throw new Error("Using links to make a request is not allowed.");
         // checks for if the query is whitelisted (should only work for links, so it skips the check for no link queries)
-        if (this.LavalinkManager.options?.linksWhitelist?.length > 0 && !this.LavalinkManager.options?.linksWhitelist.some(v => (typeof v === "string" && (queryString.toLowerCase().includes(v.toLowerCase()) || v.toLowerCase().includes(queryString.toLowerCase()))) || isRegExp(v) && v.test(queryString))) {
-            throw new Error(`Query string contains a link / word which isn't whitelisted.`);
+        if (this.LavalinkManager.options?.linksWhitelist?.length > 0) {
+            if (this.LavalinkManager.options?.advancedOptions?.enableDebugEvents) {
+                this.LavalinkManager.emit("debug", DebugEvents.ValidatingWhitelistLinks, {
+                    state: "log",
+                    message: `Link was provided to the Query, validating against LavalinkManager.options.linksWhitelist, query: "${queryString}"`,
+                    functionLayer: "(LavalinkNode > node | player) > search() > validateQueryString()",
+                });
+            }
+            if (!this.LavalinkManager.options?.linksWhitelist.some(v => (typeof v === "string" && (queryString.toLowerCase().includes(v.toLowerCase()) || v.toLowerCase().includes(queryString.toLowerCase()))) || isRegExp(v) && v.test(queryString))) {
+                throw new Error(`Query string contains a link / word which isn't whitelisted.`);
+            }
         }
         // missing links: beam.pro local getyarn.io clypit pornhub reddit ocreamix soundgasm
         if ((SourceLinksRegexes.YoutubeMusicRegex.test(queryString) || SourceLinksRegexes.YoutubeRegex.test(queryString)) && !node.info?.sourceManagers?.includes("youtube")) {
-            throw new Error("Lavalink Node has not 'youtube' enabled");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'youtube' enabled");
         }
         if ((SourceLinksRegexes.SoundCloudMobileRegex.test(queryString) || SourceLinksRegexes.SoundCloudRegex.test(queryString)) && !node.info?.sourceManagers?.includes("soundcloud")) {
-            throw new Error("Lavalink Node has not 'soundcloud' enabled");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'soundcloud' enabled");
         }
         if (SourceLinksRegexes.bandcamp.test(queryString) && !node.info?.sourceManagers?.includes("bandcamp")) {
-            throw new Error("Lavalink Node has not 'bandcamp' enabled (introduced with lavaplayer 2.2.0 or lavalink 4.0.6)");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'bandcamp' enabled (introduced with lavaplayer 2.2.0 or lavalink 4.0.6)");
         }
         if (SourceLinksRegexes.TwitchTv.test(queryString) && !node.info?.sourceManagers?.includes("twitch")) {
-            throw new Error("Lavalink Node has not 'twitch' enabled");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'twitch' enabled");
         }
         if (SourceLinksRegexes.vimeo.test(queryString) && !node.info?.sourceManagers?.includes("vimeo")) {
-            throw new Error("Lavalink Node has not 'vimeo' enabled");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'vimeo' enabled");
         }
         if (SourceLinksRegexes.tiktok.test(queryString) && !node.info?.sourceManagers?.includes("tiktok")) {
-            throw new Error("Lavalink Node has not 'tiktok' enabled");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'tiktok' enabled");
         }
         if (SourceLinksRegexes.mixcloud.test(queryString) && !node.info?.sourceManagers?.includes("mixcloud")) {
-            throw new Error("Lavalink Node has not 'mixcloud' enabled");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'mixcloud' enabled");
         }
         if (SourceLinksRegexes.AllSpotifyRegex.test(queryString) && !node.info?.sourceManagers?.includes("spotify")) {
-            throw new Error("Lavalink Node has not 'spotify' enabled");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'spotify' enabled");
         }
         if (SourceLinksRegexes.appleMusic.test(queryString) && !node.info?.sourceManagers?.includes("applemusic")) {
-            throw new Error("Lavalink Node has not 'applemusic' enabled");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'applemusic' enabled");
         }
         if (SourceLinksRegexes.AllDeezerRegex.test(queryString) && !node.info?.sourceManagers?.includes("deezer")) {
-            throw new Error("Lavalink Node has not 'deezer' enabled");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'deezer' enabled");
         }
         if (SourceLinksRegexes.AllDeezerRegex.test(queryString) && node.info?.sourceManagers?.includes("deezer") && !node.info?.sourceManagers?.includes("http")) {
-            throw new Error("Lavalink Node has not 'http' enabled, which is required to have 'deezer' to work");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'http' enabled, which is required to have 'deezer' to work");
         }
         if (SourceLinksRegexes.musicYandex.test(queryString) && !node.info?.sourceManagers?.includes("yandexmusic")) {
-            throw new Error("Lavalink Node has not 'yandexmusic' enabled");
+            throw new Error("Query / Link Provided for this Source but Lavalink Node has not 'yandexmusic' enabled");
         }
         return;
     }

package/dist/types/structures/Constants.d.ts

@@ -1,4 +1,45 @@
 import type { AudioOutputs, ChannelMixFilter, EQBand } from "./Types/Filters";
+export declare enum DebugEvents {
+    SetSponsorBlock = "SetSponsorBlock",
+    DeleteSponsorBlock = "DeleteSponsorBlock",
+    TrackEndReplaced = "TrackEndReplaced",
+    AutoplayNoSongsAdded = "AutoplayNoSongsAdded",
+    AutoplayThresholdSpamLimiter = "AutoplayThresholdSpamLimiter",
+    TriggerQueueEmptyInterval = "TriggerQueueEmptyInterval",
+    QueueEnded = "QueueEnded",
+    TrackStartNewSongsOnly = "TrackStartNewSongsOnly",
+    TrackStartNoTrack = "TrackStartNoTrack",
+    ResumingFetchingError = "ResumingFetchingError",
+    PlayerUpdateNoPlayer = "PlayerUpdateNoPlayer",
+    PlayerUpdateFilterFixApply = "PlayerUpdateFilterFixApply",
+    PlayerUpdateSuccess = "PlayerUpdateSuccess",
+    HeartBeatTriggered = "HeartBeatTriggered",
+    NoSocketOnDestroy = "NoSocketOnDestroy",
+    SocketTerminateHeartBeatTimeout = "SocketTerminateHeartBeatTimeout",
+    TryingConnectWhileConnected = "TryingConnectWhileConnected",
+    LavaSearchNothingFound = "LavaSearchNothingFound",
+    SearchNothingFound = "SearchNothingFound",
+    ValidatingBlacklistLinks = "ValidatingBlacklistLinks",
+    ValidatingWhitelistLinks = "ValidatingWhitelistLinks",
+    TrackErrorMaxTracksErroredPerTime = "TrackErrorMaxTracksErroredPerTime",
+    TrackStuckMaxTracksErroredPerTime = "TrackStuckMaxTracksErroredPerTime",
+    PlayerDestroyingSomewhereElse = "PlayerDestroyingSomewhereElse",
+    PlayerCreateNodeNotFound = "PlayerCreateNodeNotFound",
+    PlayerPlayQueueEmptyTimeoutClear = "PlayerPlayQueueEmptyTimeoutClear",
+    PlayerPlayWithTrackReplace = "PlayerPlayWithTrackReplace",
+    PlayerPlayUnresolvedTrack = "PlayerPlayUnresolvedTrack",
+    PlayerPlayUnresolvedTrackFailed = "PlayerPlayUnresolvedTrackFailed",
+    PlayerVolumeAsFilter = "PlayerVolumeAsFilter",
+    BandcampSearchLokalEngine = "BandcampSearchLokalEngine",
+    PlayerChangeNode = "PlayerChangeNode",
+    BuildTrackError = "BuildTrackError",
+    TransformRequesterFunctionFailed = "TransformRequesterFunctionFailed",
+    GetClosestTrackFailed = "GetClosestTrackFailed",
+    PlayerDeleteInsteadOfDestroy = "PlayerDeleteInsteadOfDestroy",
+    FailedToConnectToNodes = "FailedToConnectToNodes",
+    NoAudioDebug = "NoAudioDebug",
+    PlayerAutoReconnect = "PlayerAutoReconnect"
+}
 export declare enum DestroyReasons {
     QueueEmpty = "QueueEmpty",
     NodeDestroy = "NodeDestroy",
@@ -9,7 +50,9 @@ export declare enum DestroyReasons {
     PlayerReconnectFail = "PlayerReconnectFail",
     ChannelDeleted = "ChannelDeleted",
     DisconnectAllNodes = "DisconnectAllNodes",
-    ReconnectAllNodes = "ReconnectAllNodes"
+    ReconnectAllNodes = "ReconnectAllNodes",
+    TrackErrorMaxTracksErroredPerTime = "TrackErrorMaxTracksErroredPerTime",
+    TrackStuckMaxTracksErroredPerTime = "TrackStuckMaxTracksErroredPerTime"
 }
 export declare const validSponsorBlocks: string[];
 /**  The audio Outputs Data map declaration */

package/dist/types/structures/Player.d.ts

@@ -134,7 +134,6 @@ export declare class Player {
      * @param repeatMode
      */
     setRepeatMode(repeatMode: RepeatMode): Promise<this>;
-    1: any;
     /**
      * Skip the current song, or a specific amount of songs
      * @param amount provide the index of the next track to skip to

package/dist/types/structures/Types/Manager.d.ts

@@ -1,3 +1,4 @@
+import type { DebugEvents } from "../Constants";
 import type { Player } from "../Player";
 import type { LavalinkNodeOptions } from "./Node";
 import type { DestroyReasonsType, PlayerJson } from "./Player";
@@ -100,6 +101,19 @@ export interface LavalinkManagerEvents {
      * @event Manager#trackError
      */
     "ChaptersLoaded": (player: Player, track: Track | UnresolvedTrack | null, payload: SponsorBlockChaptersLoaded) => void;
+    /**
+     * Lavalink-Client Debug Event
+     * Emitted for several erros, and logs within lavalink-client, if managerOptions.advancedOptions.enableDebugEvents is true
+     * Useful for debugging the lavalink-client
+     *
+     * @event Manager#debug
+     */
+    "debug": (eventKey: DebugEvents, eventData: {
+        message: string;
+        state: "log" | "warn" | "error";
+        error?: Error | string;
+        functionLayer: string;
+    }) => void;
 }
 /**
  * The Bot client Options needed for the manager
@@ -131,6 +145,15 @@ export interface ManagerPlayerOptions {
         /** Instantly destroy player (overrides autoReconnect) | Don't provide == disable feature*/
         destroyPlayer?: boolean;
     };
+    /** Minimum time to play the song before autoPlayFunction is executed (prevents error spamming) Set to 0 to disable it @default 10000 */
+    minAutoPlayMs?: number;
+    /** Allows you to declare how many tracks are allowed to error/stuck within a time-frame before player is destroyed @default "{threshold: 35000, maxAmount: 3 }" */
+    maxErrorsPerTime?: {
+        /** The threshold time to count errors (recommended is 35s) */
+        threshold: number;
+        /** The max amount of errors within the threshold time which are allowed before destroying the player (when errors > maxAmount -> player.destroy()) */
+        maxAmount: number;
+    };
     onEmptyQueue?: {
         /** Get's executed onEmptyQueue -> You can do any track queue previous transformations, if you add a track to the queue -> it will play it, if not queueEnd will execute! */
         autoPlayFunction?: (player: Player, lastPlayedTrack: Track) => Promise<void>;
@@ -166,6 +189,8 @@ export interface ManagerOptions {
     advancedOptions?: {
         /** Max duration for that the filter fix duration works (in ms) - default is 8mins */
         maxFilterFixDuration?: number;
+        /** Enable Debug event */
+        enableDebugEvents?: boolean;
         /** optional */
         debugOptions?: {
             /** For logging custom searches */

package/dist/types/structures/Types/Queue.d.ts

@@ -28,7 +28,7 @@ export interface QueueChangesWatcher {
     /** get a Value (MUST RETURN UNPARSED!) */
     tracksAdd: (guildId: string, tracks: (Track | UnresolvedTrack)[], position: number, oldStoredQueue: StoredQueue, newStoredQueue: StoredQueue) => void;
     /** Set a value inside a guildId (MUST BE UNPARSED) */
-    tracksRemoved: (guildId: string, tracks: (Track | UnresolvedTrack)[], position: number, oldStoredQueue: StoredQueue, newStoredQueue: StoredQueue) => void;
+    tracksRemoved: (guildId: string, tracks: (Track | UnresolvedTrack)[], position: number | number[], oldStoredQueue: StoredQueue, newStoredQueue: StoredQueue) => void;
     /** Set a value inside a guildId (MUST BE UNPARSED) */
     shuffled: (guildId: string, oldStoredQueue: StoredQueue, newStoredQueue: StoredQueue) => void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lavalink-client",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "description": "Easy, flexible and feature-rich lavalink@v4 Client. Both for Beginners and Proficients.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",