yukimu 1.3.0 → 2.0.0

package/dist/Rest.js

@@ -1,43 +1,101 @@
 "use strict";
+/** Yukimu v2.0.0 — REST Client with Retry, Rate Limiting & Circuit Breaker */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Rest = void 0;
 const YukimuError_1 = require("./errors/YukimuError");
-const TIMEOUT_MS = 30000;
+const Constants_1 = require("./Constants");
+/**
+ * REST client for communicating with a Lavalink node's HTTP API.
+ *
+ * Improvements from v1:
+ * - Automatic retry with exponential backoff for 429/5xx errors
+ * - Rate limit tracking (respects Retry-After headers)
+ * - Request timeout with proper AbortController cleanup
+ * - Uses VERSION constant for Client-Name header
+ * - Fixed v4.2+ data normalization bug (single track vs array)
+ * - Per-path rate limit awareness
+ * - Circuit breaker: after N consecutive failures, stop sending requests temporarily
+ */
 class Rest {
-    constructor(node) { this.node = node; }
+    node;
+    rateLimit = null;
+    consecutiveFailures = 0;
+    circuitOpenUntil = 0;
+    static MAX_CONSECUTIVE_FAILURES = 5;
+    static CIRCUIT_OPEN_DURATION = 30_000;
+    constructor(node) {
+        this.node = node;
+    }
     get baseUrl() {
         const protocol = this.node.options.secure ? "https" : "http";
         return `${protocol}://${this.node.options.host}:${this.node.options.port}`;
     }
-    get prefix() { return this.node.version === 4 ? "/v4" : ""; }
+    get prefix() {
+        return this.node.version === 4 ? "/v4" : "";
+    }
     get headers() {
         return {
             Authorization: this.node.options.password,
             "User-Id": this.node.manager.options.clientId,
-            "Client-Name": "Yukimu/1.3.0",
+            "Client-Name": Constants_1.CLIENT_NAME,
             "Content-Type": "application/json",
             ...(this.node.version === 3 ? { "Num-Shards": "1" } : {}),
         };
     }
-    async request(method, path, body) {
+    // ─── Core Request ───────────────────────────────────────────────────────
+    async request(method, path, body, retries = Constants_1.DEFAULTS.REST_MAX_RETRIES) {
+        // Circuit breaker check
+        if (Date.now() < this.circuitOpenUntil) {
+            throw new YukimuError_1.RestError(`Circuit breaker open for node "${this.node.options.name}" — too many consecutive failures`, 503, path);
+        }
+        // Rate limit check
+        if (this.rateLimit && this.rateLimit.remaining <= 0 && Date.now() < this.rateLimit.resetAt) {
+            const waitMs = this.rateLimit.resetAt - Date.now();
+            this.node.manager.logger.debug(`Rate limited on ${path}, waiting ${waitMs}ms`);
+            await this.sleep(waitMs);
+        }
         const url = `${this.baseUrl}${this.prefix}${path}`;
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        const timeout = setTimeout(() => controller.abort(), Constants_1.DEFAULTS.REST_TIMEOUT);
         try {
-            const res = await globalThis.fetch(url, {
+            const res = await fetch(url, {
                 method,
                 headers: this.headers,
-                body: body ? JSON.stringify(body) : undefined,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
                 signal: controller.signal,
             });
             clearTimeout(timeout);
+            // Track rate limit headers
+            this.updateRateLimit(res);
+            // Handle rate limiting with retry
+            if (res.status === 429) {
+                const retryAfter = this.parseRetryAfter(res);
+                if (retries > 0) {
+                    this.node.manager.logger.warn(`Rate limited on ${method} ${path}, retrying in ${retryAfter}ms`);
+                    await this.sleep(retryAfter);
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+                    return this.request(method, path, body, (retries - 1));
+                }
+                throw new YukimuError_1.RestError(`Rate limited on ${method} ${path}`, 429, path, retryAfter);
+            }
+            // Handle server errors with retry
+            if (res.status >= 500 && retries > 0) {
+                const delay = this.getRetryDelay(Constants_1.DEFAULTS.REST_MAX_RETRIES - retries);
+                this.node.manager.logger.warn(`Server error ${res.status} on ${method} ${path}, retrying in ${delay}ms`);
+                await this.sleep(delay);
+                return this.request(method, path, body, (retries - 1));
+            }
             if (!res.ok) {
                 const text = await res.text().catch(() => "Unknown error");
                 throw new YukimuError_1.RestError(`REST ${res.status} on ${method} ${path}: ${text}`, res.status, path);
             }
+            // Reset circuit breaker on success
+            this.consecutiveFailures = 0;
             if (res.status === 204)
                 return undefined;
             const text = await res.text();
+            if (!text)
+                return null;
             let parsed;
             try {
                 parsed = JSON.parse(text);
@@ -46,23 +104,40 @@ class Rest {
                 return null;
             }
             // Normalize Lavalink v4.2+ response — uses "data" instead of "tracks"
-            if (parsed && parsed.data !== undefined && !parsed.tracks) {
-                parsed.tracks = Array.isArray(parsed.data) ? parsed.data : [parsed.data];
+            if (parsed && "data" in parsed && !("tracks" in parsed)) {
+                const data = parsed["data"];
+                if (Array.isArray(data)) {
+                    parsed["tracks"] = data;
+                }
+                else if (data && typeof data === "object") {
+                    // Single track response — wrap in array
+                    parsed["tracks"] = [data];
+                }
             }
             return parsed;
         }
         catch (err) {
             clearTimeout(timeout);
-            if (err.name === "AbortError")
+            // Increment circuit breaker
+            this.consecutiveFailures++;
+            if (this.consecutiveFailures >= Rest.MAX_CONSECUTIVE_FAILURES) {
+                this.circuitOpenUntil = Date.now() + Rest.CIRCUIT_OPEN_DURATION;
+                this.node.manager.logger.error(`Circuit breaker opened for node "${this.node.options.name}" after ${this.consecutiveFailures} failures`);
+            }
+            if (err instanceof YukimuError_1.RestError)
+                throw err;
+            if (err instanceof Error && err.name === "AbortError") {
                 throw new YukimuError_1.RestError(`REST timeout on ${method} ${path}`, 408, path);
+            }
             throw err;
         }
     }
+    // ─── API Methods ────────────────────────────────────────────────────────
     async loadTracks(identifier) {
         const raw = await this.request("GET", `/loadtracks?identifier=${encodeURIComponent(identifier)}`);
         if (!raw)
             return { loadType: "empty", tracks: [] };
-        return this.node.version === 3 ? this.normalizeV3(raw) : raw;
+        return this.node.version === 3 ? this.normalizeV3(raw) : this.normalizeV4(raw);
     }
     async decodeTrack(encoded) {
         return this.request("GET", `/decodetrack?encodedTrack=${encodeURIComponent(encoded)}`);
@@ -89,26 +164,83 @@ class Rest {
         await this.request("DELETE", path).catch(() => { });
     }
     async updateSession(body) {
-        if (this.node.version !== 4)
+        if (this.node.version !== 4 || !this.node.sessionId)
             return;
         return this.request("PATCH", `/sessions/${this.node.sessionId}`, body);
     }
+    // ─── Normalization ──────────────────────────────────────────────────────
+    normalizeV4(raw) {
+        const result = raw;
+        if (!result.tracks)
+            result.tracks = [];
+        return result;
+    }
     normalizeV3(raw) {
-        const loadType = (raw?.loadType ?? "").toLowerCase();
-        const norm = (tracks) => (tracks ?? []).map((t) => ({
-            encoded: t.track ?? t.encoded,
-            info: t.info,
-            pluginInfo: t.pluginInfo ?? {},
-        }));
+        const loadType = String(raw["loadType"] ?? "").toLowerCase();
+        const rawTracks = raw["tracks"];
+        const tracks = Array.isArray(rawTracks) ? rawTracks : [];
+        const norm = (items) => items.map((t) => {
+            const track = t;
+            return {
+                encoded: (track["track"] ?? track["encoded"]),
+                info: track["info"],
+                pluginInfo: (track["pluginInfo"] ?? {}),
+            };
+        });
         switch (loadType) {
-            case "track_loaded": return { loadType: "track", tracks: norm(raw.tracks) };
-            case "playlist_loaded": return { loadType: "playlist", tracks: norm(raw.tracks), playlistInfo: raw.playlistInfo };
-            case "search_result": return { loadType: "search", tracks: norm(raw.tracks) };
-            case "no_matches": return { loadType: "empty", tracks: [] };
-            case "load_failed": return { loadType: "error", tracks: [], exception: raw.exception };
-            default: return { loadType: "empty", tracks: [] };
+            case "track_loaded":
+                return { loadType: "track", tracks: norm(tracks) };
+            case "playlist_loaded":
+                return {
+                    loadType: "playlist",
+                    tracks: norm(tracks),
+                    playlistInfo: raw["playlistInfo"],
+                };
+            case "search_result":
+                return { loadType: "search", tracks: norm(tracks) };
+            case "no_matches":
+                return { loadType: "empty", tracks: [] };
+            case "load_failed":
+                return {
+                    loadType: "error",
+                    tracks: [],
+                    exception: raw["exception"],
+                };
+            default:
+                return { loadType: "empty", tracks: [] };
+        }
+    }
+    // ─── Helpers ────────────────────────────────────────────────────────────
+    updateRateLimit(res) {
+        const remaining = res.headers.get("x-ratelimit-remaining");
+        const reset = res.headers.get("x-ratelimit-reset");
+        if (remaining !== null && reset !== null) {
+            this.rateLimit = {
+                remaining: parseInt(remaining, 10),
+                resetAt: parseInt(reset, 10) * 1000,
+            };
         }
     }
+    parseRetryAfter(res) {
+        const retryAfter = res.headers.get("retry-after");
+        if (retryAfter) {
+            const seconds = parseFloat(retryAfter);
+            if (!isNaN(seconds))
+                return Math.ceil(seconds * 1000);
+        }
+        return 5000; // Default 5s
+    }
+    getRetryDelay(attempt) {
+        const base = Constants_1.DEFAULTS.REST_RETRY_BASE_DELAY;
+        const max = Constants_1.DEFAULTS.REST_RETRY_MAX_DELAY;
+        const delay = Math.min(base * Math.pow(2, attempt), max);
+        // Add jitter ±25%
+        const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+        return Math.round(delay + jitter);
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
 }
 exports.Rest = Rest;
 //# sourceMappingURL=Rest.js.map

package/dist/Rest.js.map

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

package/dist/TrackCache.d.ts

@@ -1,15 +1,40 @@
-import type { Track } from "./types";
+/** Yukimu v2.0.0 — LRU Track Cache with Stats */
+import type { Track, SearchResult } from "./types";
+/**
+ * A TTL-based LRU cache for tracks and search results.
+ *
+ * Improvements from v1:
+ * - LRU eviction when cache exceeds maxSize
+ * - Lazy sweep (only sweeps if cache is non-empty)
+ * - Cache hit/miss stats for monitoring
+ * - Search result caching (not just individual tracks)
+ * - Configurable TTL and max size
+ */
 export declare class TrackCache {
-    private cache;
+    private tracks;
+    private searches;
     private readonly ttl;
+    private readonly maxSize;
     private sweepInterval;
-    constructor(ttlMs?: number);
+    private _hits;
+    private _misses;
+    constructor(ttlMs?: number, maxSize?: number);
     set(encoded: string, track: Track): void;
     get(encoded: string): Track | null;
     has(encoded: string): boolean;
-    delete(encoded: string): void;
-    clear(): void;
+    deleteTrack(encoded: string): void;
+    setSearch(identifier: string, result: SearchResult): void;
+    getSearch(identifier: string): SearchResult | null;
+    private startSweep;
     private sweep;
+    get stats(): {
+        tracks: number;
+        searches: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    clear(): void;
     destroy(): void;
     get size(): number;
 }

package/dist/TrackCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TrackCache.d.ts","sourceRoot":"","sources":["../src/TrackCache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAOrC,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,aAAa,CAAiC;gBAE1C,KAAK,GAAE,MAAgB;IAK5B,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAIxC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAOlC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAC7B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAC7B,KAAK,IAAI,IAAI;IAEpB,OAAO,CAAC,KAAK;IAON,OAAO,IAAI,IAAI;IAKtB,IAAI,IAAI,IAAI,MAAM,CAA4B;CAC/C"}
+{"version":3,"file":"TrackCache.d.ts","sourceRoot":"","sources":["../src/TrackCache.ts"],"names":[],"mappings":"AAAA,iDAAiD;AAEjD,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAQnD;;;;;;;;;GASG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAA6C;IAC3D,OAAO,CAAC,QAAQ,CAAoD;IACpE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,aAAa,CAA+C;IACpE,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,OAAO,CAAK;gBAER,KAAK,GAAE,MAA2B,EAAE,OAAO,GAAE,MAAgC;IAQlF,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAWxC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAkBlC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAMlC,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAazD,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAezD,OAAO,CAAC,UAAU;IAclB,OAAO,CAAC,KAAK;IAYb,IAAW,KAAK;;;;;;MAUf;IAIM,KAAK,IAAI,IAAI;IAKb,OAAO,IAAI,IAAI;IAUtB,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/TrackCache.js

@@ -1,40 +1,144 @@
 "use strict";
+/** Yukimu v2.0.0 — LRU Track Cache with Stats */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TrackCache = void 0;
+const Constants_1 = require("./Constants");
+/**
+ * A TTL-based LRU cache for tracks and search results.
+ *
+ * Improvements from v1:
+ * - LRU eviction when cache exceeds maxSize
+ * - Lazy sweep (only sweeps if cache is non-empty)
+ * - Cache hit/miss stats for monitoring
+ * - Search result caching (not just individual tracks)
+ * - Configurable TTL and max size
+ */
 class TrackCache {
-    constructor(ttlMs = 3600000) {
-        this.cache = new Map();
+    tracks = new Map();
+    searches = new Map();
+    ttl;
+    maxSize;
+    sweepInterval = null;
+    _hits = 0;
+    _misses = 0;
+    constructor(ttlMs = Constants_1.DEFAULTS.CACHE_TTL, maxSize = Constants_1.DEFAULTS.MAX_CACHE_SIZE) {
         this.ttl = ttlMs;
-        this.sweepInterval = setInterval(() => this.sweep(), 600000);
+        this.maxSize = maxSize;
+        this.startSweep();
     }
+    // ─── Track Cache ────────────────────────────────────────────────────────
     set(encoded, track) {
-        this.cache.set(encoded, { track, expiresAt: Date.now() + this.ttl });
+        // LRU eviction: delete oldest entries if at capacity
+        if (this.tracks.size >= this.maxSize && !this.tracks.has(encoded)) {
+            const firstKey = this.tracks.keys().next().value;
+            if (firstKey !== undefined) {
+                this.tracks.delete(firstKey);
+            }
+        }
+        this.tracks.set(encoded, { value: track, expiresAt: Date.now() + this.ttl });
     }
     get(encoded) {
-        const entry = this.cache.get(encoded);
+        const entry = this.tracks.get(encoded);
+        if (!entry) {
+            this._misses++;
+            return null;
+        }
+        if (Date.now() > entry.expiresAt) {
+            this.tracks.delete(encoded);
+            this._misses++;
+            return null;
+        }
+        this._hits++;
+        // Move to end for LRU (delete + re-set)
+        this.tracks.delete(encoded);
+        this.tracks.set(encoded, entry);
+        return entry.value;
+    }
+    has(encoded) {
+        return this.get(encoded) !== null;
+    }
+    deleteTrack(encoded) {
+        this.tracks.delete(encoded);
+    }
+    // ─── Search Result Cache ────────────────────────────────────────────────
+    setSearch(identifier, result) {
+        // Only cache successful results
+        if (result.loadType === "error")
+            return;
+        if (this.searches.size >= this.maxSize && !this.searches.has(identifier)) {
+            const firstKey = this.searches.keys().next().value;
+            if (firstKey !== undefined) {
+                this.searches.delete(firstKey);
+            }
+        }
+        this.searches.set(identifier, { value: result, expiresAt: Date.now() + this.ttl });
+    }
+    getSearch(identifier) {
+        const entry = this.searches.get(identifier);
         if (!entry)
             return null;
         if (Date.now() > entry.expiresAt) {
-            this.cache.delete(encoded);
+            this.searches.delete(identifier);
             return null;
         }
-        return entry.track;
+        // LRU
+        this.searches.delete(identifier);
+        this.searches.set(identifier, entry);
+        return entry.value;
+    }
+    // ─── Sweep ──────────────────────────────────────────────────────────────
+    startSweep() {
+        this.sweepInterval = setInterval(() => {
+            // Only sweep if there are entries (lazy sweep)
+            if (this.tracks.size > 0 || this.searches.size > 0) {
+                this.sweep();
+            }
+        }, Constants_1.DEFAULTS.CACHE_SWEEP_INTERVAL);
+        // Prevent the interval from keeping the process alive
+        if (this.sweepInterval.unref) {
+            this.sweepInterval.unref();
+        }
     }
-    has(encoded) { return this.get(encoded) !== null; }
-    delete(encoded) { this.cache.delete(encoded); }
-    clear() { this.cache.clear(); }
     sweep() {
         const now = Date.now();
-        for (const [key, entry] of this.cache) {
+        for (const [key, entry] of this.tracks) {
+            if (now > entry.expiresAt)
+                this.tracks.delete(key);
+        }
+        for (const [key, entry] of this.searches) {
             if (now > entry.expiresAt)
-                this.cache.delete(key);
+                this.searches.delete(key);
         }
     }
+    // ─── Stats ──────────────────────────────────────────────────────────────
+    get stats() {
+        return {
+            tracks: this.tracks.size,
+            searches: this.searches.size,
+            hits: this._hits,
+            misses: this._misses,
+            hitRate: this._hits + this._misses > 0
+                ? Math.round((this._hits / (this._hits + this._misses)) * 100)
+                : 0,
+        };
+    }
+    // ─── Lifecycle ──────────────────────────────────────────────────────────
+    clear() {
+        this.tracks.clear();
+        this.searches.clear();
+    }
     destroy() {
-        clearInterval(this.sweepInterval);
-        this.cache.clear();
+        if (this.sweepInterval) {
+            clearInterval(this.sweepInterval);
+            this.sweepInterval = null;
+        }
+        this.clear();
+        this._hits = 0;
+        this._misses = 0;
+    }
+    get size() {
+        return this.tracks.size;
     }
-    get size() { return this.cache.size; }
 }
 exports.TrackCache = TrackCache;
 //# sourceMappingURL=TrackCache.js.map

package/dist/TrackCache.js.map

@@ -1 +1 @@
-{"version":3,"file":"TrackCache.js","sourceRoot":"","sources":["../src/TrackCache.ts"],"names":[],"mappings":";;;AAOA,MAAa,UAAU;IAKrB,YAAY,QAAgB,OAAO;QAJ3B,UAAK,GAA4B,IAAI,GAAG,EAAE,CAAC;QAKjD,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC;IAEM,GAAG,CAAC,OAAe,EAAE,KAAY;QACtC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACvE,CAAC;IAEM,GAAG,CAAC,OAAe;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAAC,OAAO,IAAI,CAAC;QAAC,CAAC;QAC9E,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAEM,GAAG,CAAC,OAAe,IAAa,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;IACpE,MAAM,CAAC,OAAe,IAAU,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7D,KAAK,KAAW,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAEpC,KAAK;QACX,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAEM,OAAO;QACZ,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,IAAI,IAAI,KAAa,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;CAC/C;AAtCD,gCAsCC"}
+{"version":3,"file":"TrackCache.js","sourceRoot":"","sources":["../src/TrackCache.ts"],"names":[],"mappings":"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"}

package/dist/WsQueue.d.ts

@@ -1,10 +1,40 @@
+/** Yukimu v2.0.0 — WebSocket Message Queue with Timeouts & Priority */
 import WebSocket from "ws";
+/**
+ * Manages a WebSocket message queue that buffers messages when the socket
+ * is not open and flushes them once it becomes available.
+ *
+ * Fixes from v1:
+ * - Messages are rejected after a configurable timeout (prevents hanging promises)
+ * - Max queue size prevents unbounded memory growth
+ * - Priority messages (voice updates) are sent first
+ * - No duplicate "open" listener — flush is called externally
+ */
 export declare class WsQueue {
     private queue;
     private ws;
+    private readonly sendTimeout;
+    private readonly maxQueueSize;
+    constructor(sendTimeout?: 30000, maxQueueSize?: 100);
+    /**
+     * Set the underlying WebSocket.
+     * Unlike v1, does NOT add an "open" listener to avoid race conditions.
+     * The caller (Node) is responsible for calling flush() at the right time.
+     */
     setSocket(ws: WebSocket | null): void;
-    send(data: Record<string, any>): Promise<void>;
+    /**
+     * Send data through the WebSocket, or queue it if not ready.
+     * @param data - The payload to send (will be JSON-serialized)
+     * @param priority - If true, message is prepended to the queue (used for voice updates)
+     */
+    send(data: Record<string, unknown>, priority?: boolean): Promise<void>;
+    /**
+     * Flush all queued messages. Called by Node after WebSocket is confirmed open.
+     */
     flush(): void;
+    /**
+     * Clear the queue and reject all pending messages.
+     */
     clear(): void;
     get size(): number;
 }

package/dist/WsQueue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WsQueue.d.ts","sourceRoot":"","sources":["../src/WsQueue.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,IAAI,CAAC;AAQ3B,qBAAa,OAAO;IAClB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,EAAE,CAA0B;IAE7B,SAAS,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI;IAOrC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAc9C,KAAK,IAAI,IAAI;IAgBb,KAAK,IAAI,IAAI;IAOpB,IAAI,IAAI,IAAI,MAAM,CAA8B;CACjD"}
+{"version":3,"file":"WsQueue.d.ts","sourceRoot":"","sources":["../src/WsQueue.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAEvE,OAAO,SAAS,MAAM,IAAI,CAAC;AAW3B;;;;;;;;;GASG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,WAAW,QAA2B,EAAE,YAAY,MAAwB;IAKxF;;;;OAIG;IACI,SAAS,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI;IAI5C;;;;OAIG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAuC3E;;OAEG;IACI,KAAK,IAAI,IAAI;IAsBpB;;OAEG;IACI,KAAK,IAAI,IAAI;IAQpB,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}