@stella_project/stellalib 1.0.0

package/dist/Structures/Manager.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * StellaLib — Copyright (c) 2026 AntonyZ, x2sadddDM, SynX, Astel (OSL-3.0)
+ * Derived from LithiumX — Copyright (c) 2025 Anantix Network (MIT)
+ * See LICENSE and THIRD-PARTY-NOTICES.md for full license details.
+ */
+import type { NodeOptions, PlayerOptions, TrackData, VoicePacket, VoiceServer, VoiceStateUpdate, SearchPlatform, SearchQuery, SearchResult, ManagerOptions, ManagerEvents } from "./Types";
+import type { StellaNode } from "./Node";
+import type { StellaPlayer } from "./Player";
+import { LRUCache } from "./LRUCache";
+import { TypedEmitter } from "tiny-typed-emitter";
+/**
+ * The main hub for interacting with Lavalink using StellaLib.
+ */
+declare class StellaManager extends TypedEmitter<ManagerEvents> {
+    static readonly DEFAULT_SOURCES: Record<SearchPlatform, string>;
+    /** The map of players. */
+    readonly players: Map<string, StellaPlayer>;
+    /** The map of nodes. */
+    readonly nodes: Map<string, StellaNode>;
+    /** The options that were set. */
+    readonly options: ManagerOptions;
+    private initiated;
+    /** The search result LRU cache (bounded, TTL-based). */
+    caches: LRUCache<string, SearchResult>;
+    /** Whether the manager is shutting down. */
+    private shuttingDown;
+    /** Returns the nodes sorted by least CPU load. */
+    get leastLoadNode(): Map<string, StellaNode>;
+    /** Returns the nodes sorted by least amount of players. */
+    private get leastPlayersNode();
+    /** Returns the node with the lowest penalty score (best performance). */
+    get leastPenaltyNode(): StellaNode | undefined;
+    /** Returns a node based on priority. */
+    private get priorityNode();
+    /** Returns the best node to use based on configuration. */
+    get useableNodes(): StellaNode;
+    /**
+     * Initiates the Manager class.
+     * @param options
+     */
+    constructor(options: ManagerOptions);
+    /**
+     * Initiates the Manager.
+     * @param clientId
+     */
+    init(clientId?: string): this;
+    /**
+     * Searches the enabled sources based off the URL or the `source` property.
+     * @param query
+     * @param requester The user who requested the search.
+     */
+    search(query: string | SearchQuery, requester?: string): Promise<SearchResult>;
+    /**
+     * Returns the available source managers and plugins on a connected node.
+     * Useful for checking which search platforms the Lavalink server supports.
+     */
+    getAvailableSources(): Promise<{
+        sourceManagers: string[];
+        plugins: {
+            name: string;
+            version: string;
+        }[];
+    }>;
+    /**
+     * Decodes the base64 encoded tracks and returns a TrackData array.
+     * @param tracks
+     */
+    decodeTracks(tracks: string[]): Promise<TrackData[]>;
+    /**
+     * Decodes the base64 encoded track and returns a TrackData.
+     * @param track
+     */
+    decodeTrack(track: string): Promise<TrackData>;
+    /**
+     * Creates a player or returns one if it already exists.
+     * @param options
+     */
+    create(options: PlayerOptions): StellaPlayer;
+    /**
+     * Returns a player or undefined if it does not exist.
+     * @param guild
+     */
+    get(guild: string): StellaPlayer | undefined;
+    /**
+     * Destroys a player if it exists.
+     * @param guild
+     */
+    destroy(guild: string): void;
+    /**
+     * Creates a node or returns one if it already exists.
+     * @param options
+     */
+    createNode(options: NodeOptions): StellaNode;
+    /**
+     * Destroys a node if it exists.
+     * @param identifier
+     */
+    destroyNode(identifier: string): void;
+    /**
+     * Sends voice data to the Lavalink server.
+     * Handles both VOICE_STATE_UPDATE and VOICE_SERVER_UPDATE from Discord.
+     * Includes channelId in voice state to satisfy Lavalink v4 requirements.
+     * @param data
+     */
+    updateVoiceState(data: VoicePacket | VoiceServer | VoiceStateUpdate): Promise<void>;
+    /**
+     * Gracefully shuts down the Manager: persists sessions, closes all nodes, and cleans up.
+     * Call this before your bot exits to enable seamless session resume on restart.
+     *
+     * Usage:
+     * ```ts
+     * process.on("SIGINT", async () => {
+     *   await manager.shutdown();
+     *   process.exit(0);
+     * });
+     * ```
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Returns memory and performance statistics for monitoring.
+     */
+    getStats(): {
+        nodes: {
+            identifier: string;
+            connected: boolean;
+            players: number;
+            playingPlayers: number;
+            penalties: number;
+            uptime: number;
+            memory: {
+                used: number;
+                free: number;
+                allocated: number;
+            };
+            restRequests: number;
+            restFailed: number;
+        }[];
+        totalPlayers: number;
+        totalPlayingPlayers: number;
+        cacheSize: number;
+        cacheMemoryEstimate: number;
+    };
+}
+export { StellaManager };
+//# sourceMappingURL=Manager.d.ts.map

package/dist/Structures/Manager.d.ts.map

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

package/dist/Structures/Manager.js

@@ -0,0 +1,503 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StellaManager = void 0;
+const Utils_1 = require("./Utils");
+const LRUCache_1 = require("./LRUCache");
+const tiny_typed_emitter_1 = require("tiny-typed-emitter");
+const ManagerCheck_1 = __importDefault(require("../Utils/ManagerCheck"));
+/**
+ * The main hub for interacting with Lavalink using StellaLib.
+ */
+class StellaManager extends tiny_typed_emitter_1.TypedEmitter {
+    static DEFAULT_SOURCES = {
+        "youtube music": "ytmsearch",
+        youtube: "ytsearch",
+        spotify: "spsearch",
+        jiosaavn: "jssearch",
+        soundcloud: "scsearch",
+        deezer: "dzsearch",
+        tidal: "tdsearch",
+        applemusic: "amsearch",
+        bandcamp: "bcsearch",
+    };
+    /** The map of players. */
+    players = new Map();
+    /** The map of nodes. */
+    nodes = new Map();
+    /** The options that were set. */
+    options;
+    initiated = false;
+    /** The search result LRU cache (bounded, TTL-based). */
+    caches;
+    /** Whether the manager is shutting down. */
+    shuttingDown = false;
+    /** Returns the nodes sorted by least CPU load. */
+    get leastLoadNode() {
+        const sorted = [...this.nodes.entries()]
+            .filter(([, node]) => node.connected)
+            .sort(([, a], [, b]) => {
+            const aload = a.stats.cpu
+                ? (a.stats.cpu.lavalinkLoad / a.stats.cpu.cores) * 100
+                : 0;
+            const bload = b.stats.cpu
+                ? (b.stats.cpu.lavalinkLoad / b.stats.cpu.cores) * 100
+                : 0;
+            return aload - bload;
+        });
+        return new Map(sorted);
+    }
+    /** Returns the nodes sorted by least amount of players. */
+    get leastPlayersNode() {
+        const sorted = [...this.nodes.entries()]
+            .filter(([, node]) => node.connected)
+            .sort(([, a], [, b]) => a.stats.players - b.stats.players);
+        return new Map(sorted);
+    }
+    /** Returns the node with the lowest penalty score (best performance). */
+    get leastPenaltyNode() {
+        const connected = [...this.nodes.values()].filter((n) => n.connected);
+        if (!connected.length)
+            return undefined;
+        return connected.reduce((best, node) => node.penalties < best.penalties ? node : best);
+    }
+    /** Returns a node based on priority. */
+    get priorityNode() {
+        const filteredNodes = [...this.nodes.values()].filter((node) => node.connected && (node.options.priority ?? 0) > 0);
+        const totalWeight = filteredNodes.reduce((total, node) => total + (node.options.priority ?? 0), 0);
+        const weightedNodes = filteredNodes.map((node) => ({
+            node,
+            weight: (node.options.priority ?? 0) / totalWeight,
+        }));
+        const randomNumber = Math.random();
+        let cumulativeWeight = 0;
+        for (const { node, weight } of weightedNodes) {
+            cumulativeWeight += weight;
+            if (randomNumber <= cumulativeWeight)
+                return node;
+        }
+        return this.leastPenaltyNode;
+    }
+    /** Returns the best node to use based on configuration. */
+    get useableNodes() {
+        if (this.options.usePriority)
+            return this.priorityNode;
+        switch (this.options.useNode) {
+            case "leastLoad":
+                return this.leastLoadNode.values().next().value;
+            case "leastPlayers":
+                return this.leastPlayersNode.values().next().value;
+            default:
+                // Default: use penalty-based selection (best overall)
+                return this.leastPenaltyNode ?? this.leastLoadNode.values().next().value;
+        }
+    }
+    /**
+     * Initiates the Manager class.
+     * @param options
+     */
+    constructor(options) {
+        super();
+        (0, ManagerCheck_1.default)(options);
+        Utils_1.Structure.get("Player").init(this);
+        Utils_1.Structure.get("Node").init(this);
+        Utils_1.TrackUtils.init(this);
+        if (options.trackPartial) {
+            Utils_1.TrackUtils.setTrackPartial(options.trackPartial);
+            delete options.trackPartial;
+        }
+        this.options = {
+            plugins: [],
+            nodes: [
+                {
+                    identifier: "default",
+                    host: "localhost",
+                    resumeStatus: true,
+                    resumeTimeout: 60,
+                },
+            ],
+            shards: 1,
+            autoPlay: true,
+            usePriority: false,
+            clientName: "StellaLib/0.0.1 (https://github.com/Roki-Stella-Projects/StellaLib)",
+            defaultSearchPlatform: "youtube",
+            useNode: "leastPlayers",
+            caches: { enabled: false, time: 0, maxSize: 200 },
+            ...options,
+        };
+        // Initialize LRU cache for search results
+        const cacheOpts = this.options.caches;
+        this.caches = new LRUCache_1.LRUCache(cacheOpts?.maxSize ?? 200, cacheOpts?.enabled ? (cacheOpts.time || 0) : 0);
+        if (this.options.plugins) {
+            for (const [index, plugin] of this.options.plugins.entries()) {
+                if (!(plugin instanceof Utils_1.Plugin))
+                    throw new RangeError(`Plugin at index ${index} does not extend Plugin.`);
+                plugin.load(this);
+            }
+        }
+        if (this.options.nodes) {
+            for (const nodeOptions of this.options.nodes) {
+                const node = new (Utils_1.Structure.get("Node"))(nodeOptions);
+                this.nodes.set(node.options.identifier, node);
+            }
+        }
+        // Periodic LRU cache pruning (removes expired entries)
+        if (cacheOpts?.enabled && cacheOpts.time > 0) {
+            setInterval(() => {
+                const pruned = this.caches.prune();
+                if (pruned > 0) {
+                    this.emit("Debug", `[Cache] Pruned ${pruned} expired entries (${this.caches.size} remaining)`);
+                }
+            }, Math.max(cacheOpts.time, 30000));
+        }
+    }
+    /**
+     * Initiates the Manager.
+     * @param clientId
+     */
+    init(clientId) {
+        if (this.initiated)
+            return this;
+        if (typeof clientId !== "undefined")
+            this.options.clientId = clientId;
+        if (typeof this.options.clientId !== "string")
+            throw new Error('"clientId" set is not type of "string"');
+        if (!this.options.clientId)
+            throw new Error('"clientId" is not set. Pass it in Manager#init() or as an option in the constructor.');
+        for (const node of this.nodes.values()) {
+            Promise.resolve(node.connect()).catch((err) => {
+                this.emit("NodeError", node, err);
+            });
+        }
+        this.initiated = true;
+        this.emit("Debug", "[Manager] Initialized");
+        return this;
+    }
+    /**
+     * Searches the enabled sources based off the URL or the `source` property.
+     * @param query
+     * @param requester The user who requested the search.
+     */
+    async search(query, requester) {
+        const node = this.useableNodes;
+        if (!node)
+            throw new Error("No available nodes.");
+        if (this.options.caches?.enabled && typeof query === "string") {
+            const cached = this.caches.get(query);
+            if (cached)
+                return cached;
+        }
+        const _query = typeof query === "string" ? { query } : query;
+        const rawQuery = _query.query;
+        const isURL = /^https?:\/\//.test(rawQuery);
+        // Build the list of platforms to try: primary + fallbacks
+        const primarySource = (_query.source ?? this.options.defaultSearchPlatform ?? "youtube");
+        const platformsToTry = [primarySource];
+        if (!isURL && this.options.searchFallback?.length) {
+            for (const fb of this.options.searchFallback) {
+                if (fb !== primarySource)
+                    platformsToTry.push(fb);
+            }
+        }
+        let lastError = null;
+        for (const platform of platformsToTry) {
+            const prefix = StellaManager.DEFAULT_SOURCES[platform] ?? platform;
+            const search = isURL ? rawQuery : `${prefix}:${rawQuery}`;
+            try {
+                const res = await node.rest.loadTracks(search);
+                if (!res)
+                    continue;
+                // If empty or error, try next fallback
+                if (res.loadType === "empty" || res.loadType === "error") {
+                    if (platformsToTry.length > 1) {
+                        this.emit("Debug", `[Search] "${platform}" returned ${res.loadType} for "${rawQuery}", trying next fallback...`);
+                    }
+                    continue;
+                }
+                let searchData = [];
+                let playlistData;
+                switch (res.loadType) {
+                    case "search":
+                        searchData = res.data;
+                        break;
+                    case "track":
+                        searchData = [res.data];
+                        break;
+                    case "playlist":
+                        playlistData = res.data;
+                        break;
+                }
+                const tracks = searchData.map((track) => Utils_1.TrackUtils.build(track, requester));
+                let playlist;
+                if (res.loadType === "playlist" && playlistData) {
+                    playlist = {
+                        name: playlistData.info.name,
+                        tracks: playlistData.tracks.map((track) => Utils_1.TrackUtils.build(track, requester)),
+                        duration: playlistData.tracks.reduce((acc, cur) => acc + (cur.info.length || 0), 0),
+                    };
+                }
+                const result = {
+                    loadType: res.loadType,
+                    tracks,
+                    playlist,
+                };
+                if (this.options.replaceYouTubeCredentials) {
+                    let tracksToReplace = [];
+                    if (result.loadType === "playlist" && result.playlist) {
+                        tracksToReplace = result.playlist.tracks;
+                    }
+                    else {
+                        tracksToReplace = result.tracks;
+                    }
+                    for (const track of tracksToReplace) {
+                        if (isYouTubeURL(track.uri)) {
+                            track.author = track.author.replace("- Topic", "").trim();
+                            track.title = track.title.replace("Topic -", "").trim();
+                        }
+                        if (track.title.includes("-")) {
+                            const [author, title] = track.title
+                                .split("-")
+                                .map((str) => str.trim());
+                            track.author = author;
+                            track.title = title;
+                        }
+                    }
+                }
+                if (this.options.caches?.enabled) {
+                    this.caches.set(search, result);
+                }
+                if (platform !== primarySource) {
+                    this.emit("Debug", `[Search] Found results via fallback "${platform}" for "${rawQuery}"`);
+                }
+                return result;
+            }
+            catch (err) {
+                lastError = err;
+                this.emit("Debug", `[Search] Error on "${platform}" for "${rawQuery}": ${err.message}`);
+            }
+        }
+        // All platforms exhausted — return empty result
+        return {
+            loadType: "empty",
+            tracks: [],
+            playlist: undefined,
+        };
+        function isYouTubeURL(uri) {
+            return uri?.includes("youtube.com") || uri?.includes("youtu.be");
+        }
+    }
+    /**
+     * Returns the available source managers and plugins on a connected node.
+     * Useful for checking which search platforms the Lavalink server supports.
+     */
+    async getAvailableSources() {
+        const node = this.useableNodes;
+        if (!node)
+            throw new Error("No available nodes.");
+        if (!node.info) {
+            await node.fetchInfo();
+        }
+        return {
+            sourceManagers: node.info?.sourceManagers ?? [],
+            plugins: node.info?.plugins ?? [],
+        };
+    }
+    /**
+     * Decodes the base64 encoded tracks and returns a TrackData array.
+     * @param tracks
+     */
+    async decodeTracks(tracks) {
+        const node = this.nodes.values().next().value;
+        if (!node)
+            throw new Error("No available nodes.");
+        const res = await node.rest.decodeTracks(tracks);
+        if (!res)
+            throw new Error("No data returned from query.");
+        return res;
+    }
+    /**
+     * Decodes the base64 encoded track and returns a TrackData.
+     * @param track
+     */
+    async decodeTrack(track) {
+        const res = await this.decodeTracks([track]);
+        return res[0];
+    }
+    /**
+     * Creates a player or returns one if it already exists.
+     * @param options
+     */
+    create(options) {
+        if (this.players.has(options.guild)) {
+            return this.players.get(options.guild);
+        }
+        return new (Utils_1.Structure.get("Player"))(options);
+    }
+    /**
+     * Returns a player or undefined if it does not exist.
+     * @param guild
+     */
+    get(guild) {
+        return this.players.get(guild);
+    }
+    /**
+     * Destroys a player if it exists.
+     * @param guild
+     */
+    destroy(guild) {
+        this.players.delete(guild);
+    }
+    /**
+     * Creates a node or returns one if it already exists.
+     * @param options
+     */
+    createNode(options) {
+        if (this.nodes.has(options.identifier || options.host)) {
+            return this.nodes.get(options.identifier || options.host);
+        }
+        return new (Utils_1.Structure.get("Node"))(options);
+    }
+    /**
+     * Destroys a node if it exists.
+     * @param identifier
+     */
+    destroyNode(identifier) {
+        const node = this.nodes.get(identifier);
+        if (!node)
+            return;
+        node.destroy();
+        this.nodes.delete(identifier);
+    }
+    /**
+     * Sends voice data to the Lavalink server.
+     * Handles both VOICE_STATE_UPDATE and VOICE_SERVER_UPDATE from Discord.
+     * Includes channelId in voice state to satisfy Lavalink v4 requirements.
+     * @param data
+     */
+    async updateVoiceState(data) {
+        if ("t" in data &&
+            !["VOICE_STATE_UPDATE", "VOICE_SERVER_UPDATE"].includes(data.t))
+            return;
+        const update = "d" in data ? data.d : data;
+        if (!update || (!("token" in update) && !("session_id" in update)))
+            return;
+        const player = this.players.get(update.guild_id ?? update.guild_id);
+        if (!player)
+            return;
+        // VOICE_SERVER_UPDATE — contains token & endpoint
+        if ("token" in update) {
+            player.voiceState.event = update;
+            const { sessionId, event: { token, endpoint }, } = player.voiceState;
+            // Include channelId in voice state (required by Lavalink v4)
+            await player.node.rest
+                .updatePlayer({
+                guildId: player.guild,
+                data: {
+                    voice: {
+                        token,
+                        endpoint,
+                        sessionId: sessionId,
+                        channelId: player.voiceChannel ?? undefined,
+                    },
+                },
+            })
+                .then(() => {
+                player.resolveVoiceReady();
+                this.emit("Debug", `[Player:${player.guild}] Voice state flushed to Lavalink`);
+            })
+                .catch((err) => {
+                this.emit("NodeError", player.node, err instanceof Error ? err : new Error(String(err)));
+            });
+            return;
+        }
+        // VOICE_STATE_UPDATE — contains session_id & channel_id
+        const voiceUpdate = update;
+        if (voiceUpdate.user_id !== this.options.clientId)
+            return;
+        if (voiceUpdate.channel_id) {
+            if (player.voiceChannel !== voiceUpdate.channel_id) {
+                this.emit("PlayerMove", player, player.voiceChannel, voiceUpdate.channel_id);
+            }
+            player.voiceState.sessionId = voiceUpdate.session_id;
+            player.voiceState.channelId = voiceUpdate.channel_id;
+            player.voiceChannel = voiceUpdate.channel_id;
+            return;
+        }
+        // Channel is null — user disconnected
+        this.emit("PlayerDisconnect", player, player.voiceChannel);
+        player.voiceChannel = null;
+        player.voiceState = Object.assign({
+            op: "voiceUpdate",
+            guildId: player.guild,
+        });
+        player.destroy();
+    }
+    /**
+     * Gracefully shuts down the Manager: persists sessions, closes all nodes, and cleans up.
+     * Call this before your bot exits to enable seamless session resume on restart.
+     *
+     * Usage:
+     * ```ts
+     * process.on("SIGINT", async () => {
+     *   await manager.shutdown();
+     *   process.exit(0);
+     * });
+     * ```
+     */
+    async shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        this.emit("Debug", "[Manager] Graceful shutdown initiated...");
+        // Gracefully close all nodes (persists session IDs for resume)
+        const closePromises = [];
+        for (const node of this.nodes.values()) {
+            closePromises.push(node.gracefulClose());
+        }
+        await Promise.allSettled(closePromises);
+        // Flush session store if it supports it
+        const store = this.options.sessionStore;
+        if (store && "destroy" in store && typeof store.destroy === "function") {
+            try {
+                store.destroy();
+            }
+            catch {
+                // Ignore
+            }
+        }
+        // Clear caches
+        this.caches.clear();
+        this.emit("Debug", `[Manager] Shutdown complete. ${this.nodes.size} nodes closed, sessions persisted.`);
+    }
+    /**
+     * Returns memory and performance statistics for monitoring.
+     */
+    getStats() {
+        const nodes = [...this.nodes.values()].map((node) => ({
+            identifier: node.options.identifier,
+            connected: node.connected,
+            players: node.stats.players,
+            playingPlayers: node.stats.playingPlayers,
+            penalties: node.penalties,
+            uptime: node.uptime,
+            memory: {
+                used: node.stats.memory.used,
+                free: node.stats.memory.free,
+                allocated: node.stats.memory.allocated,
+            },
+            restRequests: node.rest.requestCount,
+            restFailed: node.rest.failedCount,
+        }));
+        return {
+            nodes,
+            totalPlayers: this.players.size,
+            totalPlayingPlayers: [...this.players.values()].filter((p) => p.playing).length,
+            cacheSize: this.caches.size,
+            cacheMemoryEstimate: this.caches.memoryEstimate,
+        };
+    }
+}
+exports.StellaManager = StellaManager;
+//# sourceMappingURL=Manager.js.map