@ciphore/radiocli 0.2.4 → 0.2.6

package/dist/providers/radio-browser.js

@@ -1,6 +1,9 @@
 import { resolveSrv } from 'node:dns/promises';
+import { randomUUID } from 'node:crypto';
+import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
 import { z } from 'zod';
 import { ProviderCache } from './cache.js';
+import { abortable, DiscoverySessions } from './discovery-session.js';
 import { userAgent } from '../version.js';
 import { safeExternalHttpUrl, safeMediaTarget, sanitizeTerminalText } from '../safety.js';
 import { allowsDirectDnsFallback, fetchHttpsWithSystemResolver, networkPolicy, withExternalResponse } from '../platform/network.js';
@@ -48,6 +51,7 @@ const locationSchema = z
 })
     .passthrough();
 const geoAtlasLimit = 100_000;
+const geoAtlasMaxBytes = 32 * 1024 * 1024;
 const geoAtlasMaxAgeMs = 6 * 60 * 60 * 1000;
 // The atlas is much larger than ordinary directory responses. Give each live,
 // discovered server enough time to connect, download, and parse up to 100k rows
@@ -58,6 +62,7 @@ const mirrorDiscoveryTimeoutMs = 750;
 const radioBrowserService = '_api._tcp.radio-browser.info';
 const radioBrowserApiSuffix = '.api.radio-browser.info';
 const nameResolutionErrorCodes = new Set(['EAI_AGAIN', 'ENOTFOUND', 'ESERVFAIL', 'ETIMEOUT', 'EREFUSED']);
+const maxDiscoveryRoundsPerPage = 4;
 const defaultRuntime = {};
 class ProviderUnavailableError extends Error {
     constructor(message, cause) {
@@ -76,9 +81,12 @@ export class RadioBrowserProvider {
     baseUrls;
     discoverMirrors;
     activeBaseUrl;
-    geoAtlasPromise = null;
+    geoAtlas = null;
+    geoAtlasLoad = null;
     geoAtlasLoadedAt = 0;
     mirrorDiscoveryPromise = null;
+    discovery = new DiscoverySessions(state => state.bytes + state.seen.size * 128 + 1024);
+    pendingRequests = new Map();
     constructor(baseUrls = undefined, cache = new ProviderCache(), runtime = defaultRuntime) {
         this.cache = cache;
         this.runtime = runtime;
@@ -106,16 +114,16 @@ export class RadioBrowserProvider {
             .sort((a, b) => b.stationCount - a.stationCount || a.name.localeCompare(b.name))
             .slice(0, limit);
     }
-    async popular(limit = 80) {
+    async popular(limit = 80, options = {}) {
         const rows = await this.request('/json/stations/search', {
             hidebroken: 'true',
             limit: String(limit),
             order: 'clickcount',
             reverse: 'true'
-        }, { maxAgeMs: 15 * 60 * 1000 });
+        }, { maxAgeMs: 15 * 60 * 1000, signal: options.signal });
         return this.normalizeStations(rows);
     }
-    async byCountry(countryCode, limit = 100, offset = 0) {
+    async byCountry(countryCode, limit = 100, offset = 0, options = {}) {
         const rows = await this.request('/json/stations/search', {
             countrycode: countryCode.toUpperCase(),
             hidebroken: 'true',
@@ -123,17 +131,115 @@ export class RadioBrowserProvider {
             offset: String(Math.max(0, offset)),
             order: 'clickcount',
             reverse: 'true'
-        }, { maxAgeMs: 30 * 60 * 1000 });
+        }, { maxAgeMs: 30 * 60 * 1000, signal: options.signal });
         return this.normalizeStations(rows);
     }
+    byCountryPage(countryCode, options = {}) {
+        const limit = pageLimit(options.limit, 100);
+        const country = countryCode.trim().toUpperCase();
+        return this.discovery.page(JSON.stringify(['country', country, limit]), options.cursor, () => ({
+            query: country, tokens: [], filters: {}, sources: [discoverySource('country', { countrycode: country })],
+            buffer: [], seen: new Set(), initialized: true, country: true, bytes: 0
+        }), state => this.discoveryPage(state, limit, options.signal), options.signal);
+    }
+    searchPage(query, options = {}) {
+        const trimmed = query.trim();
+        const limit = pageLimit(options.limit, trimmed ? 60 : 80);
+        const filters = searchFilters(options);
+        return this.discovery.page(JSON.stringify(['search', trimmed, filters, limit]), options.cursor, () => ({
+            query: trimmed, tokens: trimmed.split(/\s+/).filter(token => token.length > 2).slice(0, 4), filters,
+            sources: trimmed ? [discoverySource('name', { name: trimmed }), discoverySource('tag', { tag: trimmed })] : [discoverySource('popular', {})],
+            buffer: [], seen: new Set(), initialized: !trimmed, country: false, bytes: 0
+        }), state => this.discoveryPage(state, limit, options.signal), options.signal);
+    }
+    async discoveryPage(state, limit, signal) {
+        signal?.throwIfAborted();
+        let successfulRequests = 0;
+        let requestError;
+        const load = async (sources) => {
+            const results = await Promise.allSettled(sources.map(source => this.request('/json/stations/search', {
+                hidebroken: 'true', limit: String(limit), offset: String(source.consumed), order: 'clickcount', reverse: 'true',
+                ...searchFilterParams(state.filters), ...source.params
+            }, { maxAgeMs: state.country ? 30 * 60 * 1000 : 10 * 60 * 1000, signal })));
+            signal?.throwIfAborted();
+            let rawCount = 0;
+            for (const [index, result] of results.entries()) {
+                const source = sources[index];
+                if (result.status === 'rejected' || !Array.isArray(result.value)) {
+                    requestError = result.status === 'rejected' ? result.reason : new Error('Radio Browser returned an invalid station list.');
+                    source.status = 'unavailable';
+                    source.message = requestError instanceof Error ? requestError.message : String(requestError);
+                    continue;
+                }
+                successfulRequests += 1;
+                const rows = result.value;
+                source.status = 'available';
+                source.message = undefined;
+                source.consumed += rows.length;
+                source.exhausted = rows.length < limit;
+                rawCount += rows.length;
+                for (const station of this.normalizeStations(rows)) {
+                    const key = `${station.provider}:${station.id}`;
+                    if (state.seen.has(key))
+                        continue;
+                    state.seen.add(key);
+                    state.bytes += key.length * 2;
+                    if (filterStations([station], state.filters).length === 0)
+                        continue;
+                    state.buffer.push(station);
+                    state.bytes += JSON.stringify(station).length * 2;
+                }
+            }
+            return rawCount;
+        };
+        for (let round = 0; state.buffer.length < limit && round < maxDiscoveryRoundsPerPage; round += 1) {
+            const pending = state.sources.filter(source => !source.exhausted);
+            if (!pending.length)
+                break;
+            let rawCount = await load(pending);
+            if (!state.initialized) {
+                // Preserve the first-page broadening policy and relevance score. Each
+                // activated source subsequently keeps its own raw offset.
+                if (rawCount < Math.min(12, limit)) {
+                    const secondary = [discoverySource('country', { country: state.query }), discoverySource('language', { language: state.query })];
+                    state.sources.push(...secondary);
+                    rawCount += await load(secondary);
+                }
+                if (rawCount === 0 && state.tokens.length > 1) {
+                    const tokenSources = state.tokens.slice(0, 3).flatMap((token, index) => [
+                        discoverySource(`token-${index}-name`, { name: token }), discoverySource(`token-${index}-tag`, { tag: token })
+                    ]);
+                    state.sources.push(...tokenSources);
+                    await load(tokenSources);
+                }
+                state.initialized = true;
+            }
+            if (!state.country)
+                state.buffer.sort((left, right) => scoreStation(right, state.query, state.tokens) - scoreStation(left, state.query, state.tokens));
+            // Failures remain retryable on the next cursor; do not spend four full
+            // network deadlines retrying an unavailable source in a single call.
+            if (state.sources.some(source => source.status === 'unavailable'))
+                break;
+        }
+        if (!state.buffer.length && !successfulRequests && requestError)
+            throw requestError;
+        const items = state.buffer.splice(0, limit);
+        state.bytes -= items.reduce((sum, station) => sum + JSON.stringify(station).length * 2, 0);
+        return {
+            items,
+            exhausted: state.buffer.length === 0 && state.sources.every(source => source.exhausted),
+            sources: state.sources.map(({ params: _params, ...source }) => source)
+        };
+    }
     async byId(id) {
         const rows = await this.request(`/json/stations/byuuid/${encodeURIComponent(id)}`, {}, { maxAgeMs: 10 * 60 * 1000 });
         return this.normalizeStations(rows)[0] ?? null;
     }
     async search(query, options = {}) {
+        options.signal?.throwIfAborted();
         const trimmed = query.trim();
         if (!trimmed) {
-            return this.popular(options.limit ?? 80);
+            return this.popular(options.limit ?? 80, { signal: options.signal });
         }
         const limit = options.limit ?? 60;
         const offset = Math.max(0, options.offset ?? 0);
@@ -147,28 +253,32 @@ export class RadioBrowserProvider {
             reverse: 'true',
             ...(options.codec ? { codec: options.codec } : {}),
             ...(options.language ? { language: options.language } : {}),
-            ...(options.countryCode ? { countrycode: options.countryCode.toUpperCase() } : {})
+            ...(options.countryCode ? { countrycode: options.countryCode.toUpperCase() } : {}),
+            ...(options.minBitrate ? { bitrateMin: String(options.minBitrate) } : {})
         };
         const primary = await Promise.allSettled([
-            this.request('/json/stations/search', { ...baseParams, name: trimmed }, { maxAgeMs: 10 * 60 * 1000 }),
-            this.request('/json/stations/search', { ...baseParams, tag: trimmed }, { maxAgeMs: 10 * 60 * 1000 })
+            this.request('/json/stations/search', { ...baseParams, name: trimmed }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal }),
+            this.request('/json/stations/search', { ...baseParams, tag: trimmed }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal })
         ]);
+        options.signal?.throwIfAborted();
         let attempts = [...primary];
         let rows = fulfilledRows(primary);
         if (rows.length < Math.min(12, limit + offset)) {
             const secondary = await Promise.allSettled([
-                this.request('/json/stations/search', { ...baseParams, country: trimmed }, { maxAgeMs: 10 * 60 * 1000 }),
-                this.request('/json/stations/search', { ...baseParams, language: trimmed }, { maxAgeMs: 10 * 60 * 1000 })
+                this.request('/json/stations/search', { ...baseParams, country: trimmed }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal }),
+                this.request('/json/stations/search', { ...baseParams, language: trimmed }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal })
             ]);
+            options.signal?.throwIfAborted();
             attempts = [...attempts, ...secondary];
             rows.push(...fulfilledRows(secondary));
         }
         const tokens = trimmed.split(/\s+/).filter(token => token.length > 2).slice(0, 4);
         if (rows.length === 0 && tokens.length > 1) {
             const tokenResults = await Promise.allSettled(tokens.slice(0, 3).flatMap(token => [
-                this.request('/json/stations/search', { ...baseParams, name: token, limit: '25' }, { maxAgeMs: 10 * 60 * 1000 }),
-                this.request('/json/stations/search', { ...baseParams, tag: token, limit: '25' }, { maxAgeMs: 10 * 60 * 1000 })
+                this.request('/json/stations/search', { ...baseParams, name: token, limit: '25' }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal }),
+                this.request('/json/stations/search', { ...baseParams, tag: token, limit: '25' }, { maxAgeMs: 10 * 60 * 1000, signal: options.signal })
             ]));
+            options.signal?.throwIfAborted();
             attempts.push(...tokenResults);
             rows = fulfilledRows(tokenResults);
         }
@@ -181,11 +291,13 @@ export class RadioBrowserProvider {
             .sort((a, b) => scoreStation(b, trimmed, tokens) - scoreStation(a, trimmed, tokens))
             .slice(offset, offset + limit);
     }
-    async nearby(location, limit = 80) {
-        const stations = await this.geotaggedAtlas();
-        return nearestStations(stations, location, limit);
+    async nearby(location, limit = 80, options = {}) {
+        options.signal?.throwIfAborted();
+        const stations = await this.geotaggedAtlas(options.signal);
+        return nearestStations(stations, location, limit, options.signal);
     }
-    async resolve(station) {
+    async resolve(station, options = {}) {
+        options.signal?.throwIfAborted();
         if (station.provider !== this.id) {
             const streamUrl = station.streamUrl ? safeMediaTarget(station.streamUrl) : null;
             if (!streamUrl) {
@@ -196,13 +308,14 @@ export class RadioBrowserProvider {
         try {
             // Click URLs can rotate and the endpoint records directory engagement, so
             // do not reuse a day-old resolution from the general provider cache.
-            const result = clickResolveSchema.parse(await this.request(`/json/url/${encodeURIComponent(station.id)}`, {}, { timeoutMs: 6000 }));
+            const result = clickResolveSchema.parse(await this.request(`/json/url/${encodeURIComponent(station.id)}`, {}, { timeoutMs: 6000, signal: options.signal }));
             const resolvedUrl = result.url ? safeMediaTarget(result.url) : null;
             if (result.ok && resolvedUrl) {
                 return { url: resolvedUrl, name: sanitizeTerminalText(result.name) ?? station.name };
             }
         }
         catch {
+            options.signal?.throwIfAborted();
             // A directory outage should not discard a validated URL already supplied
             // with the station row.
         }
@@ -227,11 +340,12 @@ export class RadioBrowserProvider {
             return false;
         }
     }
-    async detectLocation() {
+    async detectLocation(options = {}) {
+        options.signal?.throwIfAborted();
         try {
             return await withExternalResponse('https://ipapi.co/json/', {
                 timeoutMs: 5000,
-                init: { headers: { 'User-Agent': userAgent() } }
+                init: { headers: { 'User-Agent': userAgent() }, signal: options.signal }
             }, async (response) => {
                 if (!response.ok)
                     return null;
@@ -250,6 +364,7 @@ export class RadioBrowserProvider {
             });
         }
         catch {
+            options.signal?.throwIfAborted();
             return null;
         }
     }
@@ -282,22 +397,43 @@ export class RadioBrowserProvider {
             lastCheckedOk: row.lastcheckok === 1 || row.lastcheckok === true
         }));
     }
-    async geotaggedAtlas() {
+    async geotaggedAtlas(signal) {
+        signal?.throwIfAborted();
         const atlasExpired = this.geoAtlasLoadedAt > 0 && Date.now() - this.geoAtlasLoadedAt > geoAtlasMaxAgeMs;
-        if (!this.geoAtlasPromise || atlasExpired) {
-            this.geoAtlasPromise = this.loadGeotaggedAtlas()
-                .then(stations => {
+        if (this.geoAtlas && !atlasExpired)
+            return this.geoAtlas;
+        let load = this.geoAtlasLoad;
+        if (!load) {
+            const controller = new AbortController();
+            load = { controller, subscribers: 0, settled: false, promise: Promise.resolve([]) };
+            const created = load;
+            this.geoAtlasLoad = created;
+            created.promise = this.loadGeotaggedAtlas(controller.signal).then(stations => {
+                controller.signal.throwIfAborted();
+                this.geoAtlas = stations;
                 this.geoAtlasLoadedAt = Date.now();
                 return stations;
             })
-                .catch(error => {
-                this.geoAtlasPromise = null;
-                throw error;
+                .finally(() => {
+                created.settled = true;
+                if (this.geoAtlasLoad === created)
+                    this.geoAtlasLoad = null;
             });
         }
-        return this.geoAtlasPromise;
+        load.subscribers += 1;
+        try {
+            return await abortable(load.promise, signal);
+        }
+        finally {
+            load.subscribers -= 1;
+            if (load.subscribers === 0 && !load.settled) {
+                if (this.geoAtlasLoad === load)
+                    this.geoAtlasLoad = null;
+                load.controller.abort();
+            }
+        }
     }
-    async loadGeotaggedAtlas() {
+    async loadGeotaggedAtlas(signal) {
         const rows = await this.request('/json/stations/search', {
             hidebroken: 'true',
             has_geo_info: 'true',
@@ -307,21 +443,83 @@ export class RadioBrowserProvider {
             maxAgeMs: geoAtlasMaxAgeMs,
             timeoutMs: geoAtlasTotalTimeoutMs,
             attemptTimeoutMs: geoAtlasAttemptTimeoutMs,
-            cacheOnly: networkPolicy().lowBandwidth
+            cacheOnly: networkPolicy().lowBandwidth,
+            signal
         });
-        return dedupeStations(this.normalizeStations(rows)).filter(hasValidCoordinates);
+        signal?.throwIfAborted();
+        if (!Array.isArray(rows) || rows.length > geoAtlasLimit)
+            throw new Error('Radio Browser atlas exceeded the supported row limit or returned an invalid response.');
+        // Normalize the full atlas in bounded chunks so keyboard and playback
+        // events can run between batches. Preserve the original row/dedup order.
+        const stations = [];
+        const seen = new Set();
+        let retainedBytes = 0;
+        const chunkSize = 250;
+        for (let offset = 0; offset < rows.length; offset += chunkSize) {
+            signal?.throwIfAborted();
+            for (const station of this.normalizeStations(rows.slice(offset, offset + chunkSize))) {
+                const key = `${station.provider}:${station.id}`;
+                // Dedupe before validating coordinates, matching ordinary normalization.
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                if (hasValidCoordinates(station)) {
+                    retainedBytes += JSON.stringify(station).length * 2 + 128;
+                    if (retainedBytes > geoAtlasMaxBytes)
+                        throw new Error('Radio Browser atlas exceeded the local memory budget. Use country or search discovery.');
+                    stations.push(station);
+                }
+            }
+            if (offset + chunkSize < rows.length)
+                await yieldToEventLoop();
+        }
+        return stations;
     }
     async request(path, params = {}, options = {}) {
+        options.signal?.throwIfAborted();
+        // Cacheable reads share work, but click/vote endpoints keep their effects.
+        // Cancellation belongs to each subscriber, never to cache identity.
+        const key = JSON.stringify([buildCacheKey(path, params), options.maxAgeMs, options.timeoutMs, options.attemptTimeoutMs, options.cacheOnly,
+            options.maxAgeMs ? undefined : randomUUID()]);
+        let pending = this.pendingRequests.get(key);
+        if (!pending) {
+            if (this.pendingRequests.size >= 64)
+                throw new ProviderUnavailableError('Radio Browser is busy. Retry after the current directory requests finish.');
+            const controller = new AbortController();
+            const operation = { controller, subscribers: 0, promise: Promise.resolve(undefined) };
+            operation.promise = this.performRequest(path, params, { ...options, signal: controller.signal }).finally(() => {
+                if (this.pendingRequests.get(key) === operation)
+                    this.pendingRequests.delete(key);
+            });
+            pending = operation;
+            this.pendingRequests.set(key, pending);
+        }
+        pending.subscribers += 1;
+        try {
+            return await abortable(pending.promise, options.signal);
+        }
+        finally {
+            pending.subscribers -= 1;
+            if (pending.subscribers === 0 && this.pendingRequests.get(key) === pending) {
+                this.pendingRequests.delete(key);
+                pending.controller.abort(new DOMException('Directory request has no active callers.', 'AbortError'));
+            }
+        }
+    }
+    async performRequest(path, params, options) {
+        options.signal?.throwIfAborted();
         const cacheKey = buildCacheKey(path, params);
         if (options.maxAgeMs) {
-            const cached = this.cache.get(cacheKey, options.maxAgeMs);
+            const cached = await abortable(this.cache.getAsync(cacheKey, options.maxAgeMs), options.signal);
+            options.signal?.throwIfAborted();
             if (cached) {
                 return cached;
             }
         }
         const policy = networkPolicy();
         if (policy.offline || options.cacheOnly) {
-            const stale = options.maxAgeMs ? this.cache.getStale(cacheKey) : null;
+            const stale = options.maxAgeMs ? await abortable(this.cache.getStaleAsync(cacheKey), options.signal) : null;
+            options.signal?.throwIfAborted();
             if (stale !== null)
                 return stale;
             throw new ProviderUnavailableError(policy.offline
@@ -334,6 +532,7 @@ export class RadioBrowserProvider {
         const mirrors = preferActiveMirror(this.baseUrls, this.activeBaseUrl);
         let discoveryAttempted = !this.discoverMirrors;
         for (let mirrorIndex = 0; mirrorIndex < mirrors.length; mirrorIndex += 1) {
+            options.signal?.throwIfAborted();
             const baseUrl = mirrors[mirrorIndex];
             const remainingMs = deadline - Date.now();
             if (remainingMs <= 0) {
@@ -347,13 +546,15 @@ export class RadioBrowserProvider {
                 const mirrorsLeft = mirrors.length - mirrorIndex + (discoveryAttempted ? 0 : 1);
                 const fairShareTimeoutMs = Math.max(1, Math.floor(remainingMs / mirrorsLeft));
                 const attemptTimeoutMs = Math.max(1, Math.min(remainingMs, options.attemptTimeoutMs ?? fairShareTimeoutMs));
-                const value = await fetchJsonWithTimeout(url, attemptTimeoutMs, this.runtime);
+                const value = await fetchJsonWithTimeout(url, attemptTimeoutMs, this.runtime, options.signal);
+                options.signal?.throwIfAborted();
                 this.activeBaseUrl = baseUrl;
                 if (options.maxAgeMs) {
                     try {
-                        this.cache.set(cacheKey, value);
+                        await abortable(this.cache.setAsync(cacheKey, value), options.signal);
                     }
                     catch {
+                        options.signal?.throwIfAborted();
                         // A read-only or full cache directory must not turn live data into
                         // an apparent provider outage.
                     }
@@ -361,19 +562,21 @@ export class RadioBrowserProvider {
                 return value;
             }
             catch (error) {
+                options.signal?.throwIfAborted();
                 lastError = error instanceof Error ? error : new Error(String(error));
             }
             if (!discoveryAttempted && mirrorIndex === mirrors.length - 1) {
                 discoveryAttempted = true;
                 const discoveryBudgetMs = Math.min(mirrorDiscoveryTimeoutMs, Math.max(1, deadline - Date.now()));
-                const discovered = await this.loadDiscoveredMirrors(discoveryBudgetMs);
+                const discovered = await abortable(this.loadDiscoveredMirrors(discoveryBudgetMs), options.signal);
                 for (const baseUrl of discovered) {
                     if (!mirrors.includes(baseUrl))
                         mirrors.push(baseUrl);
                 }
             }
         }
-        const stale = this.cache.getStale(cacheKey);
+        const stale = await abortable(this.cache.getStaleAsync(cacheKey), options.signal);
+        options.signal?.throwIfAborted();
         if (stale) {
             return stale;
         }
@@ -421,9 +624,10 @@ function buildCacheKey(path, params) {
     const pairs = Object.entries(params).sort(([a], [b]) => a.localeCompare(b));
     return `${path}?${new URLSearchParams(pairs).toString()}`;
 }
-async function fetchJsonWithTimeout(url, timeoutMs, runtime) {
+async function fetchJsonWithTimeout(url, timeoutMs, runtime, signal) {
     const startedAt = Date.now();
     const init = {
+        signal,
         headers: {
             'User-Agent': userAgent(' (+https://radio-browser.info)'),
             Accept: 'application/json'
@@ -439,6 +643,7 @@ async function fetchJsonWithTimeout(url, timeoutMs, runtime) {
         return await withExternalResponse(url, { timeoutMs, init }, consume);
     }
     catch (error) {
+        signal?.throwIfAborted();
         const remainingMs = timeoutMs - (Date.now() - startedAt);
         if (remainingMs <= 0 ||
             !isNameResolutionError(error) ||
@@ -505,7 +710,7 @@ function settleWithin(promise, timeoutMs, fallback) {
         });
     });
 }
-export function dedupeStations(stations) {
+function dedupeStations(stations) {
     const seen = new Set();
     const deduped = [];
     for (const station of stations) {
@@ -557,12 +762,17 @@ function compareNearbyStations(a, b) {
     }
     return a.name.localeCompare(b.name);
 }
-function nearestStations(stations, location, limit) {
+async function nearestStations(stations, location, limit, signal) {
     const nearest = [];
     const boundedLimit = Math.max(0, Math.floor(limit));
     if (boundedLimit === 0)
         return nearest;
-    for (const station of stations) {
+    for (let index = 0; index < stations.length; index += 1) {
+        if (index > 0 && index % 500 === 0)
+            await yieldToEventLoop();
+        if (index % 500 === 0)
+            signal?.throwIfAborted();
+        const station = stations[index];
         if (!hasValidCoordinates(station))
             continue;
         const candidate = {
@@ -623,6 +833,27 @@ function scoreStation(station, query, tokens) {
     const exactScore = searchable.includes(loweredQuery) ? 12 : 0;
     return exactScore + tokenScore + Math.log10((station.clickCount ?? 0) + 1);
 }
+function discoverySource(source, params) {
+    return { provider: 'radio-browser', source, consumed: 0, exhausted: false, status: 'available', params };
+}
+function pageLimit(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1 || value > 1000)
+        throw new Error('Discovery page size must be between 1 and 1000.');
+    return value;
+}
+function searchFilters(options) {
+    return { codec: options.codec, language: options.language, countryCode: options.countryCode?.toUpperCase(), minBitrate: options.minBitrate };
+}
+function searchFilterParams(options) {
+    return {
+        ...(options.codec ? { codec: options.codec } : {}),
+        ...(options.language ? { language: options.language } : {}),
+        ...(options.countryCode ? { countrycode: options.countryCode.toUpperCase() } : {}),
+        ...(options.minBitrate ? { bitrateMin: String(options.minBitrate) } : {})
+    };
+}
 function filterStations(stations, options) {
     return stations.filter(station => {
         if (options.minBitrate && (station.bitrate ?? 0) < options.minBitrate) {

package/dist/providers/radio-garden.js

@@ -42,11 +42,12 @@ export class RadioGardenProvider {
         }
     }
     async search(query, options = {}) {
+        options.signal?.throwIfAborted();
         const url = new URL(`${this.baseUrl}/search`);
         url.searchParams.set('q', query);
         const parsed = await withExternalResponse(url, {
             timeoutMs: 9000,
-            init: { headers: { 'User-Agent': 'radiocli/0.1', Accept: 'application/json' } }
+            init: { headers: { 'User-Agent': 'radiocli/0.1', Accept: 'application/json' }, signal: options.signal }
         }, async (response) => {
             if (!response.ok)
                 throw new Error(`${this.label} search failed: ${response.status} ${response.statusText}`);
@@ -68,7 +69,8 @@ export class RadioGardenProvider {
         })
             .slice(0, options.limit ?? 30);
     }
-    async resolve(station) {
+    async resolve(station, options = {}) {
+        options.signal?.throwIfAborted();
         if (station.streamUrl) {
             return { url: station.streamUrl, name: station.name };
         }