lavalink-client 2.1.3 → 2.1.5

package/dist/esm/structures/LavalinkManager.js

@@ -1,14 +1,24 @@
 import { EventEmitter } from "events";
-import { DefaultSources, SourceLinksRegexes } from "./LavalinkManagerStatics";
 import { NodeManager } from "./NodeManager";
 import { DestroyReasons, Player } from "./Player";
 import { DefaultQueueStore } from "./Queue";
 import { ManagerUtils, MiniMap } from "./Utils";
 export class LavalinkManager extends EventEmitter {
-    static DefaultSources = DefaultSources;
-    static SourceLinksRegexes = SourceLinksRegexes;
+    /** The Options of LavalinkManager (changeable) */
+    options;
+    /** LavalinkManager's NodeManager to manage all Nodes */
+    nodeManager;
+    /** LavalinkManager's Utils Class */
+    utils;
+    /** Wether the manager was initiated or not */
     initiated = false;
+    /** All Players stored in a MiniMap */
     players = new MiniMap();
+    /**
+     * Applies the options provided by the User
+     * @param options
+     * @returns
+     */
     applyOptions(options) {
         this.options = {
             client: {
@@ -56,6 +66,10 @@ export class LavalinkManager extends EventEmitter {
         };
         return;
     }
+    /**
+     * Validates the current manager's options
+     * @param options
+     */
     validateOptions(options) {
         if (typeof options?.sendToShard !== "function")
             throw new SyntaxError("ManagerOption.sendToShard was not provided, which is required!");
@@ -86,6 +100,64 @@ export class LavalinkManager extends EventEmitter {
         if (typeof options?.queueOptions?.maxPreviousTracks !== "number" || options?.queueOptions?.maxPreviousTracks < 0)
             options.queueOptions.maxPreviousTracks = 25;
     }
+    /**
+     * Create the Lavalink Manager
+     * @param options
+     *
+     * @example
+     * ```ts
+     * //const client = new Client({...}); // create your BOT Client (e.g. via discord.js)
+     * client.lavalink = new LavalinkManager({
+     *   nodes: [
+     *     {
+     *       authorization: "yourverystrongpassword",
+     *       host: "localhost",
+     *       port: 2333,
+     *       id: "testnode"
+     *     },
+     *     sendToShard(guildId, payload) => client.guilds.cache.get(guildId)?.shard?.send(payload),
+     *     client: {
+     *       id: process.env.CLIENT_ID,
+     *       username: "TESTBOT"
+     *     },
+     *     // optional Options:
+     *     autoSkip: true,
+     *     playerOptions: {
+     *       applyVolumeAsFilter: false,
+     *       clientBasedPositionUpdateInterval: 150,
+     *       defaultSearchPlatform: "ytmsearch",
+     *       volumeDecrementer: 0.75,
+     *       //requesterTransformer: YourRequesterTransformerFunction,
+     *       onDisconnect: {
+     *         autoReconnect: true,
+     *         destroyPlayer: false
+     *       },
+     *       onEmptyQueue: {
+     *         destroyAfterMs: 30_000,
+     *         //autoPlayFunction: YourAutoplayFunction,
+     *       },
+     *       useUnresolvedData: true
+     *     },
+     *     queueOptions: {
+     *       maxPreviousTracks: 25,
+     *       //queueStore: yourCustomQueueStoreManagerClass,
+     *       //queueChangesWatcher: yourCustomQueueChangesWatcherClass
+     *     },
+     *     linksBlacklist: [],
+     *     linksWhitelist: [],
+     *     advancedOptions: {
+     *       debugOptions: {
+     *         noAudio: false,
+     *         playerDestroy: {
+     *           dontThrowError: false,
+     *           debugLogs: false
+     *         }
+     *       }
+     *     }
+     *   ]
+     * })
+     * ```
+     */
     constructor(options) {
         super();
         if (!options)
@@ -97,6 +169,47 @@ export class LavalinkManager extends EventEmitter {
         // create classes
         this.nodeManager = new NodeManager(this);
     }
+    /**
+     * Get a Player from Lava
+     * @param guildId The guildId of the player
+     *
+     * @example
+     * ```ts
+     * const player = client.lavalink.getPlayer(interaction.guildId);
+     * ```
+     * A quicker and easier way than doing:
+     * ```ts
+     * const player = client.lavalink.players.get(interaction.guildId);
+     * ```
+     * @returns
+     */
+    getPlayer(guildId) {
+        return this.players.get(guildId);
+    }
+    /**
+     * Create a Music-Player. If a player exists, then it returns it before creating a new one
+     * @param options
+     * @returns
+     *
+     * @example
+     * ```ts
+     * const player = client.lavalink.createPlayer({
+     *   guildId: interaction.guildId,
+     *   voiceChannelId: interaction.member.voice.channelId,
+     *   // everything below is optional
+     *   textChannelId: interaction.channelId,
+     *   volume: 100,
+     *   selfDeaf: true,
+     *   selfMute: false,
+     *   instaUpdateFiltersFix: true,
+     *   applyVolumeAsFilter: false
+     *   //only needed if you want to autopick node by region (configured by you)
+     *   // vcRegion: interaction.member.voice.rtcRegion,
+     *   // provide a specific node
+     *   // node: client.lavalink.nodeManager.leastUsedNodes("memory")[0]
+     * });
+     * ```
+     */
     createPlayer(options) {
         const oldPlayer = this.getPlayer(options?.guildId);
         if (oldPlayer)
@@ -105,15 +218,29 @@ export class LavalinkManager extends EventEmitter {
         this.players.set(newPlayer.guildId, newPlayer);
         return newPlayer;
     }
-    getPlayer(guildId) {
-        return this.players.get(guildId);
-    }
+    /**
+     * Destroy a player with optional destroy reason and disconnect it from the voice channel
+     * @param guildId
+     * @param destroyReason
+     * @returns
+     *
+     * @example
+     * ```ts
+     * client.lavalink.destroyPlayer(interaction.guildId, "forcefully destroyed the player");
+     * // recommend to do it on the player tho: player.destroy("forcefully destroyed the player");
+     * ```
+     */
     destroyPlayer(guildId, destroyReason) {
         const oldPlayer = this.getPlayer(guildId);
         if (!oldPlayer)
             return;
         return oldPlayer.destroy(destroyReason);
     }
+    /**
+     * Delete's a player from the cache without destroying it on lavalink (only works when it's disconnected)
+     * @param guildId
+     * @returns
+     */
     deletePlayer(guildId) {
         const oldPlayer = this.getPlayer(guildId);
         if (!oldPlayer)
@@ -127,12 +254,27 @@ export class LavalinkManager extends EventEmitter {
         }
         return this.players.delete(guildId);
     }
+    /**
+     * Checks wether the the lib is useable based on if any node is connected
+     */
     get useable() {
         return this.nodeManager.nodes.filter(v => v.connected).size > 0;
     }
     /**
-     * Initiates the Manager.
+     * Initiates the Manager, creates all nodes and connects all of them
      * @param clientData
+     *
+     * @example
+     *
+     * ```ts
+     * // on the bot ready event
+     * client.on("ready", () => {
+     *   client.lavalink.init({
+     *     id: client.user.id,
+     *     username: client.user.username
+     *   });
+     * });
+     * ```
      */
     async init(clientData) {
         if (this.initiated)
@@ -162,7 +304,18 @@ export class LavalinkManager extends EventEmitter {
     }
     /**
      * Sends voice data to the Lavalink server.
+     * ! Without this the library won't work
      * @param data
+     *
+     * @example
+     *
+     * ```ts
+     * // on the bot "raw" event
+     * client.on("raw", (d) => {
+     *   // required in order to send audio updates and register channel deletion etc.
+     *   client.lavalink.sendRawData(d)
+     * })
+     * ```
      */
     async sendRawData(data) {
         if (!this.initiated) {

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

@@ -84,7 +84,7 @@ export interface LavalinkPlayOptions extends BasePlayOptions {
 export interface PlayOptions extends LavalinkPlayOptions {
     /** Whether to not replace the track if a play payload is sent. */
     noReplace?: boolean;
-    /** Which Track to play | don't provide, if it should pick from the Queue */
+    /** Adds track on queue and skips to it */
     clientTrack?: Track | UnresolvedTrack;
 }
 export interface Player {
@@ -172,7 +172,7 @@ export declare class Player {
      * @param query Query for your data
      * @param requestUser
      */
-    search(query: SearchQuery, requestUser: unknown): Promise<import("./Utils").UnresolvedSearchResult | import("./Utils").SearchResult>;
+    search(query: SearchQuery, requestUser: unknown): Promise<import("./Utils").SearchResult | import("./Utils").UnresolvedSearchResult>;
     /**
      * Pause the player
      */
@@ -195,7 +195,7 @@ export declare class Player {
      * Skip the current song, or a specific amount of songs
      * @param amount provide the index of the next track to skip to
      */
-    skip(skipTo?: number, throwError?: boolean): Promise<any>;
+    skip(skipTo?: number, throwError?: boolean): any;
     /**
      * Clears the queue and stops playing. Does not destroy the Player and not leave the channel
      * @returns

package/dist/esm/structures/Player.js

@@ -124,6 +124,7 @@ export class Player {
             clearTimeout(this.get("internal_queueempty"));
             this.set("internal_queueempty", undefined);
         }
+        let replaced = false;
         // if clientTrack provided, play it
         if (options?.clientTrack && (this.LavalinkManager.utils.isTrack(options?.clientTrack) || this.LavalinkManager.utils.isUnresolvedTrack(options.clientTrack))) {
             if (this.LavalinkManager.utils.isUnresolvedTrack(options.clientTrack))
@@ -131,16 +132,18 @@ export class Player {
             if (typeof options.track.userData === "object")
                 options.clientTrack.userData = { ...(options?.clientTrack.userData || {}), ...(options.track.userData || {}) };
             await this.queue.add(options?.clientTrack, 0);
-            await queueTrackEnd(this);
+            return await this.skip();
         }
         else if (options?.track?.encoded) {
             // handle play encoded options manually // TODO let it resolve by lavalink!
             const track = await this.node.decode.singleTrack(options.track?.encoded, options.track?.requester || this.queue?.current?.requester || this.queue.previous?.[0]?.requester || this.queue.tracks?.[0]?.requester || this.LavalinkManager.options.client);
             if (typeof options.track.userData === "object")
                 track.userData = { ...(track.userData || {}), ...(options.track.userData || {}) };
-            if (track)
+            if (track) {
+                replaced = true;
                 this.queue.add(track, 0);
-            await queueTrackEnd(this);
+                await queueTrackEnd(this);
+            }
         }
         else if (options?.track?.identifier) {
             // handle play identifier options manually // TODO let it resolve by lavalink!
@@ -149,9 +152,11 @@ export class Player {
             }, options?.track?.identifier || this.queue?.current?.requester || this.queue.previous?.[0]?.requester || this.queue.tracks?.[0]?.requester || this.LavalinkManager.options.client);
             if (typeof options.track.userData === "object")
                 res.tracks[0].userData = { ...(res.tracks[0].userData || {}), ...(options.track.userData || {}) };
-            if (res.tracks[0])
+            if (res.tracks[0]) {
+                replaced = true;
                 this.queue.add(res.tracks[0], 0);
-            await queueTrackEnd(this);
+                await queueTrackEnd(this);
+            }
         }
         if (!this.queue.current && this.queue.tracks.length)
             await queueTrackEnd(this);
@@ -208,7 +213,7 @@ export class Player {
         const now = performance.now();
         await this.node.updatePlayer({
             guildId: this.guildId,
-            noReplace: options?.noReplace ?? false,
+            noReplace: replaced ? replaced : (options?.noReplace ?? false),
             playerOptions: finalOptions,
         });
         this.ping.lavalink = Math.round((performance.now() - now) / 10) / 100;
@@ -464,6 +469,7 @@ export class Player {
                 paused: data.paused,
                 filters: { ...data.filters, equalizer: data.equalizer },
                 voice: this.voice,
+                track: this.queue.current ?? undefined
                 // track: this.queue.current,
             },
         });

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

@@ -61,27 +61,27 @@ export declare class FilterManager {
      */
     setRate(rate?: number): Promise<boolean>;
     /**
-     * Enabels / Disables the rotation effect, (Optional: provide your Own Data)
+     * Enables / Disables the rotation effect, (Optional: provide your Own Data)
      * @param rotationHz
      * @returns
      */
     toggleRotation(rotationHz?: number): Promise<boolean>;
     /**
-     * Enabels / Disables the Vibrato effect, (Optional: provide your Own Data)
+     * Enables / Disables the Vibrato effect, (Optional: provide your Own Data)
      * @param frequency
      * @param depth
      * @returns
      */
     toggleVibrato(frequency?: number, depth?: number): Promise<boolean>;
     /**
-     * Enabels / Disables the Tremolo effect, (Optional: provide your Own Data)
+     * Enables / Disables the Tremolo effect, (Optional: provide your Own Data)
      * @param frequency
      * @param depth
      * @returns
      */
     toggleTremolo(frequency?: number, depth?: number): Promise<boolean>;
     /**
-     * Enabels / Disables the LowPass effect, (Optional: provide your Own Data)
+     * Enables / Disables the LowPass effect, (Optional: provide your Own Data)
      * @param smoothing
      * @returns
      */
@@ -94,14 +94,14 @@ export declare class FilterManager {
     };
     lavalinkFilterPlugin: {
         /**
-         * Enabels / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
+         * Enables / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
          * @param delay
          * @param decay
          * @returns
          */
         toggleEcho: (delay?: number, decay?: number) => Promise<boolean>;
         /**
-         * Enabels / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
+         * Enables / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
          * @param delays
          * @param gains
          * @returns
@@ -109,7 +109,7 @@ export declare class FilterManager {
         toggleReverb: (delays?: number[], gains?: number[]) => Promise<boolean>;
     };
     /**
-     * Enables / Disabels a Nightcore-like filter Effect. Disables/Overwrides both: custom and Vaporwave Filter
+     * Enables / Disables a Nightcore-like filter Effect. Disables/Overrides both: custom and Vaporwave Filter
      * @param speed
      * @param pitch
      * @param rate
@@ -117,7 +117,7 @@ export declare class FilterManager {
      */
     toggleNightcore(speed?: number, pitch?: number, rate?: number): Promise<boolean>;
     /**
-     * Enables / Disabels a Vaporwave-like filter Effect. Disables/Overwrides both: custom and nightcore Filter
+     * Enables / Disables a Vaporwave-like filter Effect. Disables/Overrides both: custom and nightcore Filter
      * @param speed
      * @param pitch
      * @param rate

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

@@ -6,10 +6,6 @@ import { DestroyReasonsType, Player, PlayerJson, PlayerOptions } from "./Player"
 import { ManagerQueueOptions } from "./Queue";
 import { Track, UnresolvedTrack } from "./Track";
 import { ChannelDeletePacket, GuildShardPayload, ManagerUtils, MiniMap, SearchPlatform, SponsorBlockChaptersLoaded, SponsorBlockChapterStarted, SponsorBlockSegmentSkipped, SponsorBlockSegmentsLoaded, TrackEndEvent, TrackExceptionEvent, TrackStartEvent, TrackStuckEvent, VoicePacket, VoiceServer, VoiceState, WebSocketClosedEvent } from "./Utils";
-export interface LavalinkManager {
-    nodeManager: NodeManager;
-    utils: ManagerUtils;
-}
 export interface BotClientOptions {
     /** Bot Client Id */
     id: string;
@@ -168,31 +164,186 @@ interface LavalinkManagerEvents {
     "ChaptersLoaded": (player: Player, track: Track | UnresolvedTrack, payload: SponsorBlockChaptersLoaded) => void;
 }
 export interface LavalinkManager {
-    options: ManagerOptions;
+    /** @private */
     on<U extends keyof LavalinkManagerEvents>(event: U, listener: LavalinkManagerEvents[U]): this;
+    /** @private */
     emit<U extends keyof LavalinkManagerEvents>(event: U, ...args: Parameters<LavalinkManagerEvents[U]>): boolean;
 }
 export declare class LavalinkManager extends EventEmitter {
-    static DefaultSources: Record<SearchPlatform, import("./Utils").LavalinkSearchPlatform | import("./Utils").ClientCustomSearchPlatformUtils>;
-    static SourceLinksRegexes: Record<import("./Utils").SourcesRegex, RegExp>;
+    /** The Options of LavalinkManager (changeable) */
+    options: ManagerOptions;
+    /** LavalinkManager's NodeManager to manage all Nodes */
+    nodeManager: NodeManager;
+    /** LavalinkManager's Utils Class */
+    utils: ManagerUtils;
+    /** Wether the manager was initiated or not */
     initiated: boolean;
+    /** All Players stored in a MiniMap */
     readonly players: MiniMap<string, Player>;
+    /**
+     * Applies the options provided by the User
+     * @param options
+     * @returns
+     */
     private applyOptions;
+    /**
+     * Validates the current manager's options
+     * @param options
+     */
     private validateOptions;
+    /**
+     * Create the Lavalink Manager
+     * @param options
+     *
+     * @example
+     * ```ts
+     * //const client = new Client({...}); // create your BOT Client (e.g. via discord.js)
+     * client.lavalink = new LavalinkManager({
+     *   nodes: [
+     *     {
+     *       authorization: "yourverystrongpassword",
+     *       host: "localhost",
+     *       port: 2333,
+     *       id: "testnode"
+     *     },
+     *     sendToShard(guildId, payload) => client.guilds.cache.get(guildId)?.shard?.send(payload),
+     *     client: {
+     *       id: process.env.CLIENT_ID,
+     *       username: "TESTBOT"
+     *     },
+     *     // optional Options:
+     *     autoSkip: true,
+     *     playerOptions: {
+     *       applyVolumeAsFilter: false,
+     *       clientBasedPositionUpdateInterval: 150,
+     *       defaultSearchPlatform: "ytmsearch",
+     *       volumeDecrementer: 0.75,
+     *       //requesterTransformer: YourRequesterTransformerFunction,
+     *       onDisconnect: {
+     *         autoReconnect: true,
+     *         destroyPlayer: false
+     *       },
+     *       onEmptyQueue: {
+     *         destroyAfterMs: 30_000,
+     *         //autoPlayFunction: YourAutoplayFunction,
+     *       },
+     *       useUnresolvedData: true
+     *     },
+     *     queueOptions: {
+     *       maxPreviousTracks: 25,
+     *       //queueStore: yourCustomQueueStoreManagerClass,
+     *       //queueChangesWatcher: yourCustomQueueChangesWatcherClass
+     *     },
+     *     linksBlacklist: [],
+     *     linksWhitelist: [],
+     *     advancedOptions: {
+     *       debugOptions: {
+     *         noAudio: false,
+     *         playerDestroy: {
+     *           dontThrowError: false,
+     *           debugLogs: false
+     *         }
+     *       }
+     *     }
+     *   ]
+     * })
+     * ```
+     */
     constructor(options: ManagerOptions);
-    createPlayer(options: PlayerOptions): Player;
+    /**
+     * Get a Player from Lava
+     * @param guildId The guildId of the player
+     *
+     * @example
+     * ```ts
+     * const player = client.lavalink.getPlayer(interaction.guildId);
+     * ```
+     * A quicker and easier way than doing:
+     * ```ts
+     * const player = client.lavalink.players.get(interaction.guildId);
+     * ```
+     * @returns
+     */
     getPlayer(guildId: string): Player;
+    /**
+     * Create a Music-Player. If a player exists, then it returns it before creating a new one
+     * @param options
+     * @returns
+     *
+     * @example
+     * ```ts
+     * const player = client.lavalink.createPlayer({
+     *   guildId: interaction.guildId,
+     *   voiceChannelId: interaction.member.voice.channelId,
+     *   // everything below is optional
+     *   textChannelId: interaction.channelId,
+     *   volume: 100,
+     *   selfDeaf: true,
+     *   selfMute: false,
+     *   instaUpdateFiltersFix: true,
+     *   applyVolumeAsFilter: false
+     *   //only needed if you want to autopick node by region (configured by you)
+     *   // vcRegion: interaction.member.voice.rtcRegion,
+     *   // provide a specific node
+     *   // node: client.lavalink.nodeManager.leastUsedNodes("memory")[0]
+     * });
+     * ```
+     */
+    createPlayer(options: PlayerOptions): Player;
+    /**
+     * Destroy a player with optional destroy reason and disconnect it from the voice channel
+     * @param guildId
+     * @param destroyReason
+     * @returns
+     *
+     * @example
+     * ```ts
+     * client.lavalink.destroyPlayer(interaction.guildId, "forcefully destroyed the player");
+     * // recommend to do it on the player tho: player.destroy("forcefully destroyed the player");
+     * ```
+     */
     destroyPlayer(guildId: string, destroyReason?: string): Promise<Player>;
+    /**
+     * Delete's a player from the cache without destroying it on lavalink (only works when it's disconnected)
+     * @param guildId
+     * @returns
+     */
     deletePlayer(guildId: string): boolean;
+    /**
+     * Checks wether the the lib is useable based on if any node is connected
+     */
     get useable(): boolean;
     /**
-     * Initiates the Manager.
+     * Initiates the Manager, creates all nodes and connects all of them
      * @param clientData
+     *
+     * @example
+     *
+     * ```ts
+     * // on the bot ready event
+     * client.on("ready", () => {
+     *   client.lavalink.init({
+     *     id: client.user.id,
+     *     username: client.user.username
+     *   });
+     * });
+     * ```
      */
     init(clientData: BotClientOptions): Promise<this>;
     /**
      * Sends voice data to the Lavalink server.
+     * ! Without this the library won't work
      * @param data
+     *
+     * @example
+     *
+     * ```ts
+     * // on the bot "raw" event
+     * client.on("raw", (d) => {
+     *   // required in order to send audio updates and register channel deletion etc.
+     *   client.lavalink.sendRawData(d)
+     * })
+     * ```
      */
     sendRawData(data: VoicePacket | VoiceServer | VoiceState | ChannelDeletePacket): Promise<void>;
 }

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

@@ -84,7 +84,7 @@ export interface LavalinkPlayOptions extends BasePlayOptions {
 export interface PlayOptions extends LavalinkPlayOptions {
     /** Whether to not replace the track if a play payload is sent. */
     noReplace?: boolean;
-    /** Which Track to play | don't provide, if it should pick from the Queue */
+    /** Adds track on queue and skips to it */
     clientTrack?: Track | UnresolvedTrack;
 }
 export interface Player {
@@ -172,7 +172,7 @@ export declare class Player {
      * @param query Query for your data
      * @param requestUser
      */
-    search(query: SearchQuery, requestUser: unknown): Promise<import("./Utils").UnresolvedSearchResult | import("./Utils").SearchResult>;
+    search(query: SearchQuery, requestUser: unknown): Promise<import("./Utils").SearchResult | import("./Utils").UnresolvedSearchResult>;
     /**
      * Pause the player
      */
@@ -195,7 +195,7 @@ export declare class Player {
      * Skip the current song, or a specific amount of songs
      * @param amount provide the index of the next track to skip to
      */
-    skip(skipTo?: number, throwError?: boolean): Promise<any>;
+    skip(skipTo?: number, throwError?: boolean): any;
     /**
      * Clears the queue and stops playing. Does not destroy the Player and not leave the channel
      * @returns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lavalink-client",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "description": "Easy, flexible and feature-rich lavalink@v4 Client. Both for Beginners and Proficients.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -14,7 +14,8 @@
     "lint": "eslint .",
     "lint:fix": "eslint --fix 'src/**/*.{ts}'",
     "format": "prettier --write src/**/*.ts --config ./.prettierrc.js",
-    "test": "node -v"
+    "test": "node -v",
+    "docs": "npx typedoc"
   },
   "publishConfig": {
     "access": "public"
@@ -54,6 +55,8 @@
     "eslint": "^8.47.0",
     "ts-loader": "^9.4.4",
     "tslib": "^2.6.1",
+    "typedoc": "^0.25.4",
+    "typedoc-theme-hierarchy": "^4.1.2",
     "typescript": "^5.1.6"
   },
   "dependencies": {