lavalink-client 2.7.7 → 2.7.8

package/README.md

@@ -32,6 +32,7 @@
 - ✨ **Flexible Queue Stores:** Use the default in-memory store or bring your own (Redis, databases, etc.) to sync queues across multiple processes.
 - 🎶 **Unresolved Tracks:** Supports unresolved track objects, fetching full data only when a track is about to play, saving API requests and resources.
 - 🎚️ **Built-in Filters & EQ:** Easy-to-use management for audio filters and equalizers.
+- 🔍 **Advanced Queue Filtering:** Search and filter tracks in the queue by title, author, duration, and more with powerful query options.
 - ⚙️ **Advanced Player Options:** Fine-tune player behavior for disconnects, empty queues, volume handling, and more.
 - 🛡️ **Lavalink-Side Validation:** Ensures you only use filters, plugins, and sources that your Lavalink node actually supports.
 - 🔒 **Client-Side Validation:** Whitelist and blacklist URLs or domains to prevent unwanted requests and protect your bot.

package/dist/index.d.mts

@@ -704,6 +704,77 @@ declare class Queue {
          * @returns {number}
          */
         totalDuration: () => number;
+        /**
+         * Find tracks in the queue matching specific criteria.
+         * **This method DOES NOT MUTATE the queue** - it returns a new array without modifying the original queue.
+         * @param predicate Function to test each track, or an object with criteria to match
+         * @returns Array of matching tracks with their indexes
+         *
+         * @example
+         * ```ts
+         * // Find by author
+         * const artistTracks = player.queue.utils.filterTracks({ author: "Artist Name" });
+         *
+         * // Find by duration range (5-10 minutes)
+         * const longTracks = player.queue.utils.filterTracks({ duration: { min: 300000, max: 600000 } });
+         *
+         * // Find by title (partial match)
+         * const titleMatches = player.queue.utils.filterTracks({ title: "Never Gonna" });
+         *
+         * // Custom predicate
+         * const customFilter = player.queue.utils.filterTracks(track => track.info.isStream);
+         * ```
+         */
+        filterTracks: (predicate: ((track: Track | UnresolvedTrack, index: number) => boolean) | {
+            title?: string;
+            author?: string;
+            duration?: number | {
+                min?: number;
+                max?: number;
+            };
+            uri?: string;
+            identifier?: string;
+            sourceName?: string;
+            isStream?: boolean;
+            isSeekable?: boolean;
+        }) => Array<{
+            track: Track | UnresolvedTrack;
+            index: number;
+        }>;
+        /**
+         * Find a single track in the queue matching specific criteria.
+         * **This method DOES NOT MUTATE the queue** - it searches without modifying the original queue.
+         * @param predicate Function to test each track, or an object with criteria to match
+         * @returns First matching track with its index, or null if not found
+         *
+         * @example
+         * ```ts
+         * // Find first track by author
+         * const track = player.queue.utils.findTrack({ author: "Artist Name" });
+         * if (track) {
+         *   console.log(`Found at index ${track.index}: ${track.track.info.title}`);
+         * }
+         *
+         * // Find with custom predicate
+         * const liveStream = player.queue.utils.findTrack(track => track.info.isStream);
+         * ```
+         */
+        findTrack: (predicate: ((track: Track | UnresolvedTrack, index: number) => boolean) | {
+            title?: string;
+            author?: string;
+            duration?: number | {
+                min?: number;
+                max?: number;
+            };
+            uri?: string;
+            identifier?: string;
+            sourceName?: string;
+            isStream?: boolean;
+            isSeekable?: boolean;
+        }) => {
+            track: Track | UnresolvedTrack;
+            index: number;
+        } | null;
     };
     /**
      * Shuffles the current Queue, then saves it
@@ -773,6 +844,126 @@ declare class Queue {
      * ```
      */
     shiftPrevious(): Promise<Track>;
+    /**
+     * Find tracks in the queue matching specific criteria.
+     * **This method DOES NOT MUTATE the queue** - it returns a new array without modifying the original queue.
+     * @deprecated Use `player.queue.utils.filterTracks()` instead.
+     * @param predicate Function to test each track, or an object with criteria to match
+     * @returns Array of matching tracks with their indexes
+     *
+     * @example
+     * ```ts
+     * // Use the new method instead:
+     * const artistTracks = player.queue.utils.filterTracks({ author: "Artist Name" });
+     * ```
+     */
+    filter(predicate: ((track: Track | UnresolvedTrack, index: number) => boolean) | {
+        title?: string;
+        author?: string;
+        duration?: number | {
+            min?: number;
+            max?: number;
+        };
+        uri?: string;
+        identifier?: string;
+        sourceName?: string;
+        isStream?: boolean;
+        isSeekable?: boolean;
+    }): Array<{
+        track: Track | UnresolvedTrack;
+        index: number;
+    }>;
+    /**
+     * Find a single track in the queue matching specific criteria.
+     * **This method DOES NOT MUTATE the queue** - it searches without modifying the original queue.
+     * @deprecated Use `player.queue.utils.findTrack()` instead.
+     * @param predicate Function to test each track, or an object with criteria to match
+     * @returns First matching track with its index, or null if not found
+     *
+     * @example
+     * ```ts
+     * // Use the new method instead:
+     * const track = player.queue.utils.findTrack({ author: "Artist Name" });
+     * ```
+     */
+    find(predicate: ((track: Track | UnresolvedTrack, index: number) => boolean) | {
+        title?: string;
+        author?: string;
+        duration?: number | {
+            min?: number;
+            max?: number;
+        };
+        uri?: string;
+        identifier?: string;
+        sourceName?: string;
+        isStream?: boolean;
+        isSeekable?: boolean;
+    }): {
+        track: Track | UnresolvedTrack;
+        index: number;
+    } | null;
+    /**
+     * Sort the queue tracks by a specific property.
+     * **⚠️ This method MUTATES the queue** - it modifies the original queue in place.
+     * @param sortBy Property to sort by or custom comparator function
+     * @param order Sort order: 'asc' or 'desc' (default: 'asc')
+     * @returns The queue instance for chaining
+     *
+     * @example
+     * ```ts
+     * // Sort by duration (shortest first)
+     * await player.queue.sortBy("duration", "asc");
+     *
+     * // Sort by title alphabetically (Z-A)
+     * await player.queue.sortBy("title", "desc");
+     *
+     * // Custom sorting
+     * await player.queue.sortBy((a, b) => {
+     *   return a.info.title.localeCompare(b.info.title);
+     * });
+     * ```
+     */
+    sortBy(sortBy: "duration" | "title" | "author" | ((a: Track | UnresolvedTrack, b: Track | UnresolvedTrack) => number), order?: "asc" | "desc"): Promise<this>;
+    /**
+     * Get a sorted copy of the queue tracks without modifying the original queue.
+     * **This method DOES NOT MUTATE the queue** - it returns a new sorted array, similar to `Array.toSorted()`.
+     * @param sortBy Property to sort by or custom comparator function
+     * @param order Sort order: 'asc' or 'desc' (default: 'asc')
+     * @returns A new sorted array of tracks (does not modify the queue)
+     *
+     * @example
+     * ```ts
+     * // Get sorted copy by duration (shortest first)
+     * const sortedTracks = player.queue.toSortedBy("duration", "asc");
+     * // Original queue remains unchanged
+     *
+     * // Get sorted copy by title alphabetically (Z-A)
+     * const sortedByTitle = player.queue.toSortedBy("title", "desc");
+     *
+     * // Custom sorting
+     * const customSorted = player.queue.toSortedBy((a, b) => {
+     *   return a.info.title.localeCompare(b.info.title);
+     * });
+     * ```
+     */
+    toSortedBy(sortBy: "duration" | "title" | "author" | ((a: Track | UnresolvedTrack, b: Track | UnresolvedTrack) => number), order?: "asc" | "desc"): (Track | UnresolvedTrack)[];
+    /**
+     * Get a range of tracks from the queue.
+     * **This method DOES NOT MUTATE the queue** - it returns a new array slice, similar to `Array.slice()`.
+     * @param start Start index (inclusive)
+     * @param end End index (exclusive)
+     * @returns Array of tracks in the specified range
+     *
+     * @example
+     * ```ts
+     * // Get tracks 5-15
+     * const tracks = player.queue.getTracks(5, 15);
+     *
+     * // Get first 10 tracks
+     * const firstTen = player.queue.getTracks(0, 10);
+     * ```
+     */
+    getTracks(start: number, end?: number): (Track | UnresolvedTrack)[];
 }
 
 declare class Player {
@@ -3031,6 +3222,13 @@ interface LavalinkManagerEvents<CustomPlayerT extends Player = Player> {
      * @event Manager#playerDisconnect
      */
     "playerDisconnect": (player: CustomPlayerT, voiceChannelId: string) => void;
+    /**
+     * Emitted when a Player automatically reconnects after a disconnect.
+     * This event is triggered when the player successfully reconnects to the voice channel
+     * and resumes playback after being disconnected (requires onDisconnect.autoReconnect to be enabled).
+     * @event Manager#playerReconnect
+     */
+    "playerReconnect": (player: CustomPlayerT, voiceChannelId: string) => void;
     /**
      * Emitted when a Node-Socket got closed for a specific Player.
      * Usually emits when the audio websocket to discord is closed, This can happen for various reasons (normal and abnormal), e.g. when using an expired voice server update. 4xxx codes are usually bad.

package/dist/index.d.ts

@@ -704,6 +704,77 @@ declare class Queue {
          * @returns {number}
          */
         totalDuration: () => number;
+        /**
+         * Find tracks in the queue matching specific criteria.
+         * **This method DOES NOT MUTATE the queue** - it returns a new array without modifying the original queue.
+         * @param predicate Function to test each track, or an object with criteria to match
+         * @returns Array of matching tracks with their indexes
+         *
+         * @example
+         * ```ts
+         * // Find by author
+         * const artistTracks = player.queue.utils.filterTracks({ author: "Artist Name" });
+         *
+         * // Find by duration range (5-10 minutes)
+         * const longTracks = player.queue.utils.filterTracks({ duration: { min: 300000, max: 600000 } });
+         *
+         * // Find by title (partial match)
+         * const titleMatches = player.queue.utils.filterTracks({ title: "Never Gonna" });
+         *
+         * // Custom predicate
+         * const customFilter = player.queue.utils.filterTracks(track => track.info.isStream);
+         * ```
+         */
+        filterTracks: (predicate: ((track: Track | UnresolvedTrack, index: number) => boolean) | {
+            title?: string;
+            author?: string;
+            duration?: number | {
+                min?: number;
+                max?: number;
+            };
+            uri?: string;
+            identifier?: string;
+            sourceName?: string;
+            isStream?: boolean;
+            isSeekable?: boolean;
+        }) => Array<{
+            track: Track | UnresolvedTrack;
+            index: number;
+        }>;
+        /**
+         * Find a single track in the queue matching specific criteria.
+         * **This method DOES NOT MUTATE the queue** - it searches without modifying the original queue.
+         * @param predicate Function to test each track, or an object with criteria to match
+         * @returns First matching track with its index, or null if not found
+         *
+         * @example
+         * ```ts
+         * // Find first track by author
+         * const track = player.queue.utils.findTrack({ author: "Artist Name" });
+         * if (track) {
+         *   console.log(`Found at index ${track.index}: ${track.track.info.title}`);
+         * }
+         *
+         * // Find with custom predicate
+         * const liveStream = player.queue.utils.findTrack(track => track.info.isStream);
+         * ```
+         */
+        findTrack: (predicate: ((track: Track | UnresolvedTrack, index: number) => boolean) | {
+            title?: string;
+            author?: string;
+            duration?: number | {
+                min?: number;
+                max?: number;
+            };
+            uri?: string;
+            identifier?: string;
+            sourceName?: string;
+            isStream?: boolean;
+            isSeekable?: boolean;
+        }) => {
+            track: Track | UnresolvedTrack;
+            index: number;
+        } | null;
     };
     /**
      * Shuffles the current Queue, then saves it
@@ -773,6 +844,126 @@ declare class Queue {
      * ```
      */
     shiftPrevious(): Promise<Track>;
+    /**
+     * Find tracks in the queue matching specific criteria.
+     * **This method DOES NOT MUTATE the queue** - it returns a new array without modifying the original queue.
+     * @deprecated Use `player.queue.utils.filterTracks()` instead.
+     * @param predicate Function to test each track, or an object with criteria to match
+     * @returns Array of matching tracks with their indexes
+     *
+     * @example
+     * ```ts
+     * // Use the new method instead:
+     * const artistTracks = player.queue.utils.filterTracks({ author: "Artist Name" });
+     * ```
+     */
+    filter(predicate: ((track: Track | UnresolvedTrack, index: number) => boolean) | {
+        title?: string;
+        author?: string;
+        duration?: number | {
+            min?: number;
+            max?: number;
+        };
+        uri?: string;
+        identifier?: string;
+        sourceName?: string;
+        isStream?: boolean;
+        isSeekable?: boolean;
+    }): Array<{
+        track: Track | UnresolvedTrack;
+        index: number;
+    }>;
+    /**
+     * Find a single track in the queue matching specific criteria.
+     * **This method DOES NOT MUTATE the queue** - it searches without modifying the original queue.
+     * @deprecated Use `player.queue.utils.findTrack()` instead.
+     * @param predicate Function to test each track, or an object with criteria to match
+     * @returns First matching track with its index, or null if not found
+     *
+     * @example
+     * ```ts
+     * // Use the new method instead:
+     * const track = player.queue.utils.findTrack({ author: "Artist Name" });
+     * ```
+     */
+    find(predicate: ((track: Track | UnresolvedTrack, index: number) => boolean) | {
+        title?: string;
+        author?: string;
+        duration?: number | {
+            min?: number;
+            max?: number;
+        };
+        uri?: string;
+        identifier?: string;
+        sourceName?: string;
+        isStream?: boolean;
+        isSeekable?: boolean;
+    }): {
+        track: Track | UnresolvedTrack;
+        index: number;
+    } | null;
+    /**
+     * Sort the queue tracks by a specific property.
+     * **⚠️ This method MUTATES the queue** - it modifies the original queue in place.
+     * @param sortBy Property to sort by or custom comparator function
+     * @param order Sort order: 'asc' or 'desc' (default: 'asc')
+     * @returns The queue instance for chaining
+     *
+     * @example
+     * ```ts
+     * // Sort by duration (shortest first)
+     * await player.queue.sortBy("duration", "asc");
+     *
+     * // Sort by title alphabetically (Z-A)
+     * await player.queue.sortBy("title", "desc");
+     *
+     * // Custom sorting
+     * await player.queue.sortBy((a, b) => {
+     *   return a.info.title.localeCompare(b.info.title);
+     * });
+     * ```
+     */
+    sortBy(sortBy: "duration" | "title" | "author" | ((a: Track | UnresolvedTrack, b: Track | UnresolvedTrack) => number), order?: "asc" | "desc"): Promise<this>;
+    /**
+     * Get a sorted copy of the queue tracks without modifying the original queue.
+     * **This method DOES NOT MUTATE the queue** - it returns a new sorted array, similar to `Array.toSorted()`.
+     * @param sortBy Property to sort by or custom comparator function
+     * @param order Sort order: 'asc' or 'desc' (default: 'asc')
+     * @returns A new sorted array of tracks (does not modify the queue)
+     *
+     * @example
+     * ```ts
+     * // Get sorted copy by duration (shortest first)
+     * const sortedTracks = player.queue.toSortedBy("duration", "asc");
+     * // Original queue remains unchanged
+     *
+     * // Get sorted copy by title alphabetically (Z-A)
+     * const sortedByTitle = player.queue.toSortedBy("title", "desc");
+     *
+     * // Custom sorting
+     * const customSorted = player.queue.toSortedBy((a, b) => {
+     *   return a.info.title.localeCompare(b.info.title);
+     * });
+     * ```
+     */
+    toSortedBy(sortBy: "duration" | "title" | "author" | ((a: Track | UnresolvedTrack, b: Track | UnresolvedTrack) => number), order?: "asc" | "desc"): (Track | UnresolvedTrack)[];
+    /**
+     * Get a range of tracks from the queue.
+     * **This method DOES NOT MUTATE the queue** - it returns a new array slice, similar to `Array.slice()`.
+     * @param start Start index (inclusive)
+     * @param end End index (exclusive)
+     * @returns Array of tracks in the specified range
+     *
+     * @example
+     * ```ts
+     * // Get tracks 5-15
+     * const tracks = player.queue.getTracks(5, 15);
+     *
+     * // Get first 10 tracks
+     * const firstTen = player.queue.getTracks(0, 10);
+     * ```
+     */
+    getTracks(start: number, end?: number): (Track | UnresolvedTrack)[];
 }
 
 declare class Player {
@@ -3031,6 +3222,13 @@ interface LavalinkManagerEvents<CustomPlayerT extends Player = Player> {
      * @event Manager#playerDisconnect
      */
     "playerDisconnect": (player: CustomPlayerT, voiceChannelId: string) => void;
+    /**
+     * Emitted when a Player automatically reconnects after a disconnect.
+     * This event is triggered when the player successfully reconnects to the voice channel
+     * and resumes playback after being disconnected (requires onDisconnect.autoReconnect to be enabled).
+     * @event Manager#playerReconnect
+     */
+    "playerReconnect": (player: CustomPlayerT, voiceChannelId: string) => void;
     /**
      * Emitted when a Node-Socket got closed for a specific Player.
      * Usually emits when the audio websocket to discord is closed, This can happen for various reasons (normal and abnormal), e.g. when using an expired voice server update. 4xxx codes are usually bad.

package/dist/index.js

@@ -1433,7 +1433,6 @@ var LavalinkNode = class {
       functionLayer: "LavalinkNode > nodeEvent > stats > heartBeat()"
     });
     this.resetAckTimeouts(false, true);
-    if (this.pingTimeout) clearTimeout(this.pingTimeout);
     this.pingTimeout = setTimeout(() => {
       this.pingTimeout = null;
       if (!this.socket) {
@@ -1958,9 +1957,10 @@ var LavalinkNode = class {
     }, this.options.retryDelay || 1e3);
   }
   get reconnectionAttemptCount() {
+    if (!Array.isArray(this.reconnectAttempts)) this.reconnectAttempts = [];
     const maxAllowedTimestan = this.options.retryTimespan || -1;
     if (maxAllowedTimestan <= 0) return this.reconnectAttempts.length;
-    return this.reconnectAttempts.filter((timestamp) => Date.now() - timestamp <= maxAllowedTimestan).length;
+    return this.reconnectAttempts?.filter((timestamp) => Date.now() - timestamp <= maxAllowedTimestan).length || 0;
   }
   /**
    * Private Utility function to execute the reconnection
@@ -1973,6 +1973,7 @@ var LavalinkNode = class {
       this.destroy("NodeReconnectFail" /* NodeReconnectFail */);
       return;
     }
+    if (!Array.isArray(this.reconnectAttempts)) this.reconnectAttempts = [];
     this.reconnectAttempts.push(Date.now());
     this.reconnectionState = "RECONNECTING" /* RECONNECTING */;
     this.NodeManager.emit("reconnecting", this);
@@ -3817,6 +3818,87 @@ var Queue = class {
      */
     totalDuration: () => {
       return this.tracks.reduce((acc, cur) => acc + (cur.info.duration || 0), this.current?.info.duration || 0);
+    },
+    /**
+     * Find tracks in the queue matching specific criteria.
+     * **This method DOES NOT MUTATE the queue** - it returns a new array without modifying the original queue.
+     * @param predicate Function to test each track, or an object with criteria to match
+     * @returns Array of matching tracks with their indexes
+     * 
+     * @example
+     * ```ts
+     * // Find by author
+     * const artistTracks = player.queue.utils.filterTracks({ author: "Artist Name" });
+     * 
+     * // Find by duration range (5-10 minutes)
+     * const longTracks = player.queue.utils.filterTracks({ duration: { min: 300000, max: 600000 } });
+     * 
+     * // Find by title (partial match)
+     * const titleMatches = player.queue.utils.filterTracks({ title: "Never Gonna" });
+     * 
+     * // Custom predicate
+     * const customFilter = player.queue.utils.filterTracks(track => track.info.isStream);
+     * ```
+     */
+    filterTracks: (predicate) => {
+      if (typeof predicate === "function") {
+        return this.tracks.map((track, index) => ({ track, index })).filter(({ track, index }) => predicate(track, index));
+      }
+      return this.tracks.map((track, index) => ({ track, index })).filter(({ track }) => {
+        if (predicate.title && !track.info?.title?.toLowerCase().includes(predicate.title.toLowerCase())) {
+          return false;
+        }
+        if (predicate.author && !track.info?.author?.toLowerCase().includes(predicate.author.toLowerCase())) {
+          return false;
+        }
+        if (predicate.duration !== void 0) {
+          const duration = track.info?.duration || 0;
+          if (typeof predicate.duration === "number") {
+            if (duration !== predicate.duration) return false;
+          } else {
+            if (predicate.duration.min !== void 0 && duration < predicate.duration.min) return false;
+            if (predicate.duration.max !== void 0 && duration > predicate.duration.max) return false;
+          }
+        }
+        if (predicate.uri && track.info?.uri !== predicate.uri) {
+          return false;
+        }
+        if (predicate.identifier && track.info?.identifier !== predicate.identifier) {
+          return false;
+        }
+        if (predicate.sourceName && track.info?.sourceName?.toLowerCase() !== predicate.sourceName.toLowerCase()) {
+          return false;
+        }
+        if (predicate.isStream !== void 0 && track.info?.isStream !== predicate.isStream) {
+          return false;
+        }
+        if (predicate.isSeekable !== void 0 && track.info?.isSeekable !== predicate.isSeekable) {
+          return false;
+        }
+        return true;
+      });
+    },
+    /**
+     * Find a single track in the queue matching specific criteria.
+     * **This method DOES NOT MUTATE the queue** - it searches without modifying the original queue.
+     * @param predicate Function to test each track, or an object with criteria to match
+     * @returns First matching track with its index, or null if not found
+     * 
+     * @example
+     * ```ts
+     * // Find first track by author
+     * const track = player.queue.utils.findTrack({ author: "Artist Name" });
+     * if (track) {
+     *   console.log(`Found at index ${track.index}: ${track.track.info.title}`);
+     * }
+     * 
+     * // Find with custom predicate
+     * const liveStream = player.queue.utils.findTrack(track => track.info.isStream);
+     * ```
+     */
+    findTrack: (predicate) => {
+      const results = this.utils.filterTracks(predicate);
+      return results.length > 0 ? results[0] : null;
     }
   };
   /**
@@ -3998,6 +4080,149 @@ var Queue = class {
     if (removed) await this.utils.save();
     return removed ?? null;
   }
+  /**
+   * Find tracks in the queue matching specific criteria.
+   * **This method DOES NOT MUTATE the queue** - it returns a new array without modifying the original queue.
+   * @deprecated Use `player.queue.utils.filterTracks()` instead.
+   * @param predicate Function to test each track, or an object with criteria to match
+   * @returns Array of matching tracks with their indexes
+   * 
+   * @example
+   * ```ts
+   * // Use the new method instead:
+   * const artistTracks = player.queue.utils.filterTracks({ author: "Artist Name" });
+   * ```
+   */
+  filter(predicate) {
+    return this.utils.filterTracks(predicate);
+  }
+  /**
+   * Find a single track in the queue matching specific criteria.
+   * **This method DOES NOT MUTATE the queue** - it searches without modifying the original queue.
+   * @deprecated Use `player.queue.utils.findTrack()` instead.
+   * @param predicate Function to test each track, or an object with criteria to match
+   * @returns First matching track with its index, or null if not found
+   * 
+   * @example
+   * ```ts
+   * // Use the new method instead:
+   * const track = player.queue.utils.findTrack({ author: "Artist Name" });
+   * ```
+   */
+  find(predicate) {
+    return this.utils.findTrack(predicate);
+  }
+  /**
+   * Sort the queue tracks by a specific property.
+   * **⚠️ This method MUTATES the queue** - it modifies the original queue in place.
+   * @param sortBy Property to sort by or custom comparator function
+   * @param order Sort order: 'asc' or 'desc' (default: 'asc')
+   * @returns The queue instance for chaining
+   * 
+   * @example
+   * ```ts
+   * // Sort by duration (shortest first)
+   * await player.queue.sortBy("duration", "asc");
+   * 
+   * // Sort by title alphabetically (Z-A)
+   * await player.queue.sortBy("title", "desc");
+   * 
+   * // Custom sorting
+   * await player.queue.sortBy((a, b) => {
+   *   return a.info.title.localeCompare(b.info.title);
+   * });
+   * ```
+   */
+  async sortBy(sortBy, order = "asc") {
+    const oldStored = typeof this.queueChanges?.tracksAdd === "function" ? this.utils.toJSON() : null;
+    if (typeof sortBy === "function") {
+      this.tracks.sort(sortBy);
+    } else {
+      this.tracks.sort((a, b) => {
+        let comparison = 0;
+        switch (sortBy) {
+          case "duration":
+            comparison = (a.info?.duration || 0) - (b.info?.duration || 0);
+            break;
+          case "title":
+            comparison = (a.info?.title || "").localeCompare(b.info?.title || "");
+            break;
+          case "author":
+            comparison = (a.info?.author || "").localeCompare(b.info?.author || "");
+            break;
+          default:
+            return 0;
+        }
+        return order === "desc" ? -comparison : comparison;
+      });
+    }
+    await this.utils.save();
+    return this;
+  }
+  /**
+   * Get a sorted copy of the queue tracks without modifying the original queue.
+   * **This method DOES NOT MUTATE the queue** - it returns a new sorted array, similar to `Array.toSorted()`.
+   * @param sortBy Property to sort by or custom comparator function
+   * @param order Sort order: 'asc' or 'desc' (default: 'asc')
+   * @returns A new sorted array of tracks (does not modify the queue)
+   * 
+   * @example
+   * ```ts
+   * // Get sorted copy by duration (shortest first)
+   * const sortedTracks = player.queue.toSortedBy("duration", "asc");
+   * // Original queue remains unchanged
+   * 
+   * // Get sorted copy by title alphabetically (Z-A)
+   * const sortedByTitle = player.queue.toSortedBy("title", "desc");
+   * 
+   * // Custom sorting
+   * const customSorted = player.queue.toSortedBy((a, b) => {
+   *   return a.info.title.localeCompare(b.info.title);
+   * });
+   * ```
+   */
+  toSortedBy(sortBy, order = "asc") {
+    const tracksCopy = [...this.tracks];
+    if (typeof sortBy === "function") {
+      return tracksCopy.sort(sortBy);
+    }
+    return tracksCopy.sort((a, b) => {
+      let comparison = 0;
+      switch (sortBy) {
+        case "duration":
+          comparison = (a.info?.duration || 0) - (b.info?.duration || 0);
+          break;
+        case "title":
+          comparison = (a.info?.title || "").localeCompare(b.info?.title || "");
+          break;
+        case "author":
+          comparison = (a.info?.author || "").localeCompare(b.info?.author || "");
+          break;
+        default:
+          return 0;
+      }
+      return order === "desc" ? -comparison : comparison;
+    });
+  }
+  /**
+   * Get a range of tracks from the queue.
+   * **This method DOES NOT MUTATE the queue** - it returns a new array slice, similar to `Array.slice()`.
+   * @param start Start index (inclusive)
+   * @param end End index (exclusive)
+   * @returns Array of tracks in the specified range
+   * 
+   * @example
+   * ```ts
+   * // Get tracks 5-15
+   * const tracks = player.queue.getTracks(5, 15);
+   * 
+   * // Get first 10 tracks
+   * const firstTen = player.queue.getTracks(0, 10);
+   * ```
+   */
+  getTracks(start, end) {
+    return this.tracks.slice(start, end);
+  }
 };
 
 // src/structures/Player.ts
@@ -5262,6 +5487,7 @@ var LavalinkManager = class extends import_events2.EventEmitter {
             });
             if (!autoReconnectOnlyWithTracks || autoReconnectOnlyWithTracks && (player.queue.current || player.queue.tracks.length)) {
               await player.connect();
+              this.emit("playerReconnect", player, player.voiceChannelId);
             }
             if (player.queue.current) {
               return void await player.play({ position: previousPosition, paused: previousPaused, clientTrack: player.queue.current });

package/dist/index.mjs

@@ -1372,7 +1372,6 @@ var LavalinkNode = class {
       functionLayer: "LavalinkNode > nodeEvent > stats > heartBeat()"
     });
     this.resetAckTimeouts(false, true);
-    if (this.pingTimeout) clearTimeout(this.pingTimeout);
     this.pingTimeout = setTimeout(() => {
       this.pingTimeout = null;
       if (!this.socket) {
@@ -1897,9 +1896,10 @@ var LavalinkNode = class {
     }, this.options.retryDelay || 1e3);
   }
   get reconnectionAttemptCount() {
+    if (!Array.isArray(this.reconnectAttempts)) this.reconnectAttempts = [];
     const maxAllowedTimestan = this.options.retryTimespan || -1;
     if (maxAllowedTimestan <= 0) return this.reconnectAttempts.length;
-    return this.reconnectAttempts.filter((timestamp) => Date.now() - timestamp <= maxAllowedTimestan).length;
+    return this.reconnectAttempts?.filter((timestamp) => Date.now() - timestamp <= maxAllowedTimestan).length || 0;
   }
   /**
    * Private Utility function to execute the reconnection
@@ -1912,6 +1912,7 @@ var LavalinkNode = class {
       this.destroy("NodeReconnectFail" /* NodeReconnectFail */);
       return;
     }
+    if (!Array.isArray(this.reconnectAttempts)) this.reconnectAttempts = [];
     this.reconnectAttempts.push(Date.now());
     this.reconnectionState = "RECONNECTING" /* RECONNECTING */;
     this.NodeManager.emit("reconnecting", this);
@@ -3756,6 +3757,87 @@ var Queue = class {
      */
     totalDuration: () => {
       return this.tracks.reduce((acc, cur) => acc + (cur.info.duration || 0), this.current?.info.duration || 0);
+    },
+    /**
+     * Find tracks in the queue matching specific criteria.
+     * **This method DOES NOT MUTATE the queue** - it returns a new array without modifying the original queue.
+     * @param predicate Function to test each track, or an object with criteria to match
+     * @returns Array of matching tracks with their indexes
+     * 
+     * @example
+     * ```ts
+     * // Find by author
+     * const artistTracks = player.queue.utils.filterTracks({ author: "Artist Name" });
+     * 
+     * // Find by duration range (5-10 minutes)
+     * const longTracks = player.queue.utils.filterTracks({ duration: { min: 300000, max: 600000 } });
+     * 
+     * // Find by title (partial match)
+     * const titleMatches = player.queue.utils.filterTracks({ title: "Never Gonna" });
+     * 
+     * // Custom predicate
+     * const customFilter = player.queue.utils.filterTracks(track => track.info.isStream);
+     * ```
+     */
+    filterTracks: (predicate) => {
+      if (typeof predicate === "function") {
+        return this.tracks.map((track, index) => ({ track, index })).filter(({ track, index }) => predicate(track, index));
+      }
+      return this.tracks.map((track, index) => ({ track, index })).filter(({ track }) => {
+        if (predicate.title && !track.info?.title?.toLowerCase().includes(predicate.title.toLowerCase())) {
+          return false;
+        }
+        if (predicate.author && !track.info?.author?.toLowerCase().includes(predicate.author.toLowerCase())) {
+          return false;
+        }
+        if (predicate.duration !== void 0) {
+          const duration = track.info?.duration || 0;
+          if (typeof predicate.duration === "number") {
+            if (duration !== predicate.duration) return false;
+          } else {
+            if (predicate.duration.min !== void 0 && duration < predicate.duration.min) return false;
+            if (predicate.duration.max !== void 0 && duration > predicate.duration.max) return false;
+          }
+        }
+        if (predicate.uri && track.info?.uri !== predicate.uri) {
+          return false;
+        }
+        if (predicate.identifier && track.info?.identifier !== predicate.identifier) {
+          return false;
+        }
+        if (predicate.sourceName && track.info?.sourceName?.toLowerCase() !== predicate.sourceName.toLowerCase()) {
+          return false;
+        }
+        if (predicate.isStream !== void 0 && track.info?.isStream !== predicate.isStream) {
+          return false;
+        }
+        if (predicate.isSeekable !== void 0 && track.info?.isSeekable !== predicate.isSeekable) {
+          return false;
+        }
+        return true;
+      });
+    },
+    /**
+     * Find a single track in the queue matching specific criteria.
+     * **This method DOES NOT MUTATE the queue** - it searches without modifying the original queue.
+     * @param predicate Function to test each track, or an object with criteria to match
+     * @returns First matching track with its index, or null if not found
+     * 
+     * @example
+     * ```ts
+     * // Find first track by author
+     * const track = player.queue.utils.findTrack({ author: "Artist Name" });
+     * if (track) {
+     *   console.log(`Found at index ${track.index}: ${track.track.info.title}`);
+     * }
+     * 
+     * // Find with custom predicate
+     * const liveStream = player.queue.utils.findTrack(track => track.info.isStream);
+     * ```
+     */
+    findTrack: (predicate) => {
+      const results = this.utils.filterTracks(predicate);
+      return results.length > 0 ? results[0] : null;
     }
   };
   /**
@@ -3937,6 +4019,149 @@ var Queue = class {
     if (removed) await this.utils.save();
     return removed ?? null;
   }
+  /**
+   * Find tracks in the queue matching specific criteria.
+   * **This method DOES NOT MUTATE the queue** - it returns a new array without modifying the original queue.
+   * @deprecated Use `player.queue.utils.filterTracks()` instead.
+   * @param predicate Function to test each track, or an object with criteria to match
+   * @returns Array of matching tracks with their indexes
+   * 
+   * @example
+   * ```ts
+   * // Use the new method instead:
+   * const artistTracks = player.queue.utils.filterTracks({ author: "Artist Name" });
+   * ```
+   */
+  filter(predicate) {
+    return this.utils.filterTracks(predicate);
+  }
+  /**
+   * Find a single track in the queue matching specific criteria.
+   * **This method DOES NOT MUTATE the queue** - it searches without modifying the original queue.
+   * @deprecated Use `player.queue.utils.findTrack()` instead.
+   * @param predicate Function to test each track, or an object with criteria to match
+   * @returns First matching track with its index, or null if not found
+   * 
+   * @example
+   * ```ts
+   * // Use the new method instead:
+   * const track = player.queue.utils.findTrack({ author: "Artist Name" });
+   * ```
+   */
+  find(predicate) {
+    return this.utils.findTrack(predicate);
+  }
+  /**
+   * Sort the queue tracks by a specific property.
+   * **⚠️ This method MUTATES the queue** - it modifies the original queue in place.
+   * @param sortBy Property to sort by or custom comparator function
+   * @param order Sort order: 'asc' or 'desc' (default: 'asc')
+   * @returns The queue instance for chaining
+   * 
+   * @example
+   * ```ts
+   * // Sort by duration (shortest first)
+   * await player.queue.sortBy("duration", "asc");
+   * 
+   * // Sort by title alphabetically (Z-A)
+   * await player.queue.sortBy("title", "desc");
+   * 
+   * // Custom sorting
+   * await player.queue.sortBy((a, b) => {
+   *   return a.info.title.localeCompare(b.info.title);
+   * });
+   * ```
+   */
+  async sortBy(sortBy, order = "asc") {
+    const oldStored = typeof this.queueChanges?.tracksAdd === "function" ? this.utils.toJSON() : null;
+    if (typeof sortBy === "function") {
+      this.tracks.sort(sortBy);
+    } else {
+      this.tracks.sort((a, b) => {
+        let comparison = 0;
+        switch (sortBy) {
+          case "duration":
+            comparison = (a.info?.duration || 0) - (b.info?.duration || 0);
+            break;
+          case "title":
+            comparison = (a.info?.title || "").localeCompare(b.info?.title || "");
+            break;
+          case "author":
+            comparison = (a.info?.author || "").localeCompare(b.info?.author || "");
+            break;
+          default:
+            return 0;
+        }
+        return order === "desc" ? -comparison : comparison;
+      });
+    }
+    await this.utils.save();
+    return this;
+  }
+  /**
+   * Get a sorted copy of the queue tracks without modifying the original queue.
+   * **This method DOES NOT MUTATE the queue** - it returns a new sorted array, similar to `Array.toSorted()`.
+   * @param sortBy Property to sort by or custom comparator function
+   * @param order Sort order: 'asc' or 'desc' (default: 'asc')
+   * @returns A new sorted array of tracks (does not modify the queue)
+   * 
+   * @example
+   * ```ts
+   * // Get sorted copy by duration (shortest first)
+   * const sortedTracks = player.queue.toSortedBy("duration", "asc");
+   * // Original queue remains unchanged
+   * 
+   * // Get sorted copy by title alphabetically (Z-A)
+   * const sortedByTitle = player.queue.toSortedBy("title", "desc");
+   * 
+   * // Custom sorting
+   * const customSorted = player.queue.toSortedBy((a, b) => {
+   *   return a.info.title.localeCompare(b.info.title);
+   * });
+   * ```
+   */
+  toSortedBy(sortBy, order = "asc") {
+    const tracksCopy = [...this.tracks];
+    if (typeof sortBy === "function") {
+      return tracksCopy.sort(sortBy);
+    }
+    return tracksCopy.sort((a, b) => {
+      let comparison = 0;
+      switch (sortBy) {
+        case "duration":
+          comparison = (a.info?.duration || 0) - (b.info?.duration || 0);
+          break;
+        case "title":
+          comparison = (a.info?.title || "").localeCompare(b.info?.title || "");
+          break;
+        case "author":
+          comparison = (a.info?.author || "").localeCompare(b.info?.author || "");
+          break;
+        default:
+          return 0;
+      }
+      return order === "desc" ? -comparison : comparison;
+    });
+  }
+  /**
+   * Get a range of tracks from the queue.
+   * **This method DOES NOT MUTATE the queue** - it returns a new array slice, similar to `Array.slice()`.
+   * @param start Start index (inclusive)
+   * @param end End index (exclusive)
+   * @returns Array of tracks in the specified range
+   * 
+   * @example
+   * ```ts
+   * // Get tracks 5-15
+   * const tracks = player.queue.getTracks(5, 15);
+   * 
+   * // Get first 10 tracks
+   * const firstTen = player.queue.getTracks(0, 10);
+   * ```
+   */
+  getTracks(start, end) {
+    return this.tracks.slice(start, end);
+  }
 };
 
 // src/structures/Player.ts
@@ -5201,6 +5426,7 @@ var LavalinkManager = class extends EventEmitter2 {
             });
             if (!autoReconnectOnlyWithTracks || autoReconnectOnlyWithTracks && (player.queue.current || player.queue.tracks.length)) {
               await player.connect();
+              this.emit("playerReconnect", player, player.voiceChannelId);
             }
             if (player.queue.current) {
               return void await player.play({ position: previousPosition, paused: previousPaused, clientTrack: player.queue.current });

package/package.json

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