Node Management

This guide covers node selection strategies, health checks, and operations like decode and REST calls.

Select Nodes

getLeastUsed() picks among the connected nodes and throws a NodeManagerError when there are none — it never returns undefined.

import { NodeSortTypes } from 'hoshimi';
import type { Hoshimi } from 'hoshimi';

declare const manager: Hoshimi;

const byPenalties = manager.nodeManager.getLeastUsed(); // default
const byMemory = manager.nodeManager.getLeastUsed(NodeSortTypes.Memory);
const custom = manager.nodeManager.getLeastUsed((node) => node.stats?.playingPlayers ?? 0);

console.log(`Using node: ${byPenalties.id}`);
console.log(`Ready: ${byPenalties.ready}`);
console.log(`Penalties: ${byPenalties.penalties}`);
console.log(byMemory.id, custom.id);

Sort strategies: Penalties (default), Players, PlayingPlayers, Cpu, SystemLoad, LavalinkLoad, Memory — or any function returning a number, where lowest wins. Penalties combine the player count with CPU load and frame deficits.

Moving players between nodes

player.move() re-creates the player on another node, keeping position, volume and filters. It refuses the move when the target lacks a source manager the queue depends on, so a Spotify queue never lands on a node that cannot play it.

import type { Hoshimi, Player } from 'hoshimi';

declare const manager: Hoshimi;
declare const player: Player;

await player.move(manager.nodeManager.getLeastUsed());

Set nodeOptions.moveOptions.move to have Hoshimi do this automatically for every player of a node that disconnects, picking the target with moveOptions.filterBy.

Decode Tracks

Decode Lavalink track data to extract metadata.

import type { Node } from 'hoshimi';

declare const node: Node;

const single = await node.decode.single('QAAAyAIA...', 'user-id');
const many = await node.decode.multiple(['QAAAyAIA...', 'QAAByAIA...'], 'user-id');

console.log(single.info.title);
console.log(many.length);

REST Operations

Access low-level REST endpoints for advanced use cases.

import type { Node } from 'hoshimi';

declare const node: Node;

const players = await node.rest.getPlayers();
console.log(`Active players: ${players.length}`);

Staying connected

Each socket runs a ping/pong heartbeat: if a ping goes unanswered within nodeOptions.heartbeatOptions.interval (30s by default), the socket is terminated and the normal reconnect path takes over. Set it to 0 to disable.

A dropped node retries retryAmount times, retryDelay apart, then destroys itself and emits NodeError. sessionOptions.resumable keeps the node's Lavalink session alive for timeout seconds across a socket drop; byLibrary is the complementary fallback for when the node returns on a fresh session, replaying the players Hoshimi still holds in memory. They stack — they are not alternatives.

For the full resume story — Lavalink's own session resume, byLibrary, a custom resumeFn, and rebuilding queues from storage — see the Resume sessions after a restart recipe.

Best Practices

• Prefer getLeastUsed() for default load balancing, and catch NodeManagerError if no node may be up.
• Always check node.ready before forcing node-specific operations.
• Use node.rest only for low-level operations; prefer manager/player abstractions for typical flows.
• node.isNodelink() tells you the node is a fork, which skips plugin validation.