@ciphore/radiocli 0.2.0 → 0.2.1

package/dist/player/player-controller.js

@@ -3,14 +3,14 @@ import { existsSync, unlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { Socket } from 'node:net';
 import { detectPlaybackBackends, ffplayLimitedControlsMessage, playbackBackendInstallHint, vlcLimitedControlsMessage } from './backend-install.js';
 import { resolveCommand } from './command.js';
 import { discoverAirPlayDevices } from './airplay-discovery.js';
 import { airPlaySenderHealth } from './airplay-sender-health.js';
 import { encodeWorkerStart, parseWorkerMessage, serializeWorkerMessage } from './airplay-worker-protocol.js';
+import { safeMediaTarget, sanitizeTerminalText } from '../safety.js';
+import { MpvIpcClient } from './mpv-ipc-client.js';
 const minAirPlayTuneTimeoutSeconds = 30;
-const mpvAudioStartFallbackMs = 1500;
 export class PlaybackOutputError extends Error {
     constructor(message) {
         super(message);
@@ -25,6 +25,7 @@ export class PlayerController {
     process = null;
     backend = null;
     ipcPath = null;
+    mpvIpcClient = null;
     metadataTimer = null;
     playbackStateTimer = null;
     state = { backend: 'none', state: 'idle', volume: 70, muted: false, ready: false };
@@ -42,8 +43,13 @@ export class PlayerController {
     currentAirPlayDevice = null;
     currentAirPlayDeviceId = null;
     pendingAirPlayPasscode = null;
-    nextMpvRequestId = 1;
     currentMpvMediaTitle = null;
+    metadataPollInFlight = false;
+    playbackStatePollInFlight = false;
+    pendingMpvVolume = null;
+    mpvVolumeFlush = null;
+    confirmedMpvVolume = 70;
+    mpvSessionId = 0;
     constructor(getSettings) {
         this.getSettings = getSettings;
     }
@@ -81,6 +87,11 @@ export class PlayerController {
         return this.detectedBackends();
     }
     async play(station, url) {
+        const target = safeMediaTarget(url);
+        if (!target) {
+            throw new Error(`Station ${station.name} returned an unsupported stream URL.`);
+        }
+        url = target;
         const backend = this.selectBackend();
         if (!backend) {
             await this.stop();
@@ -197,7 +208,12 @@ export class PlayerController {
             return unsupported;
         }
         if (this.backend === 'mpv') {
-            await this.sendMpv({ command: ['cycle', 'pause'] }).catch(() => undefined);
+            try {
+                await this.sendMpv({ command: ['cycle', 'pause'] });
+            }
+            catch {
+                return { ok: false, message: 'mpv did not acknowledge the pause command.' };
+            }
             const synced = await this.syncMpvPlaybackState();
             if (synced) {
                 return { ok: true };
@@ -213,22 +229,24 @@ export class PlayerController {
         });
         return { ok: true };
     }
-    async setVolume(volume) {
+    setVolume(volume) {
         const clamped = clampVolume(volume);
         const unsupported = this.unsupportedFfplayControl();
         if (unsupported) {
-            return unsupported;
+            return Promise.resolve(unsupported);
         }
         if (this.backend === 'mpv') {
-            await this.sendMpv({ command: ['set_property', 'volume', clamped] }).catch(() => undefined);
+            return this.queueMpvVolume(clamped);
         }
         else if (this.backend === 'airplay') {
-            this.sendAirPlayCommand({ type: 'setVolume', volume: clamped });
+            if (!this.sendAirPlayCommand({ type: 'setVolume', volume: clamped })) {
+                return Promise.resolve({ ok: false, message: 'The AirPlay worker is not available.' });
+            }
         }
         this.setState({ ...this.state, volume: clamped });
-        return { ok: true };
+        return Promise.resolve({ ok: true });
     }
-    async adjustVolume(delta) {
+    adjustVolume(delta) {
         return this.setVolume(this.state.volume + delta);
     }
     async toggleMute() {
@@ -238,15 +256,23 @@ export class PlayerController {
             return unsupported;
         }
         if (this.backend === 'mpv') {
-            await this.sendMpv({ command: ['set_property', 'mute', muted] }).catch(() => undefined);
+            try {
+                await this.sendMpv({ command: ['set_property', 'mute', muted] });
+            }
+            catch {
+                return { ok: false, message: 'mpv did not acknowledge the mute change.' };
+            }
         }
         else if (this.backend === 'airplay') {
-            this.sendAirPlayCommand({ type: 'setMuted', muted });
+            if (!this.sendAirPlayCommand({ type: 'setMuted', muted })) {
+                return { ok: false, message: 'The AirPlay worker is not available.' };
+            }
         }
         this.setState({ ...this.state, muted });
         return { ok: true };
     }
     async stop() {
+        const child = this.process;
         this.stopMpvPolling();
         this.rejectPendingAirPlayReady(new Error('AirPlay playback stopped.'));
         this.rejectPendingAirPlayRetune(new Error('AirPlay playback stopped.'));
@@ -260,10 +286,16 @@ export class PlayerController {
             this.pendingAirPlayPasscode = null;
             this.airPlaySessionEstablished = false;
         }
-        if (this.process && !this.process.killed) {
-            this.process.kill('SIGTERM');
+        if (child && child.exitCode == null && !child.killed) {
+            child.kill('SIGTERM');
+            if (!(await waitForChildExit(child, 1200)) && child.exitCode === null) {
+                child.kill('SIGKILL');
+                await waitForChildExit(child, 500);
+            }
+        }
+        if (this.process === child) {
+            this.process = null;
         }
-        this.process = null;
         this.cleanupIpc();
         this.setState({
             ...this.state,
@@ -335,11 +367,16 @@ export class PlayerController {
     }
     playWithMpv(url, initialTitle) {
         this.ipcPath = createMpvIpcPath();
+        this.mpvIpcClient = new MpvIpcClient(this.ipcPath);
+        this.mpvSessionId += 1;
+        this.confirmedMpvVolume = clampVolume(this.getSettings().volume);
+        this.pendingMpvVolume = null;
         this.currentMpvMediaTitle = cleanMediaTitle(initialTitle) ?? 'RadioCLI';
         this.process = spawn(resolveCommand('mpv') ?? 'mpv', [
             '--no-video',
             '--really-quiet',
             '--force-window=no',
+            ...(process.env.RADIOCLI_MPV_AUDIO_OUTPUT ? [`--ao=${process.env.RADIOCLI_MPV_AUDIO_OUTPUT}`] : []),
             `--force-media-title=${this.currentMpvMediaTitle}`,
             `--volume=${this.getSettings().volume}`,
             `--input-ipc-server=${this.ipcPath}`,
@@ -451,6 +488,7 @@ export class PlayerController {
         const workerPath = airPlayWorkerPath();
         const workerArgs = airPlayWorkerArgs(workerPath, encodeWorkerStart({
             streamUrl: url,
+            ffmpegPath: resolveCommand('ffmpeg') ?? 'ffmpeg',
             stationName,
             volume: this.getSettings().volume,
             muted: false,
@@ -585,6 +623,10 @@ export class PlayerController {
         if (!child) {
             return;
         }
+        // Local players can write diagnostics indefinitely. Drain both pipes so a
+        // full OS pipe buffer can never stall playback.
+        child.stdout.resume?.();
+        child.stderr.resume?.();
         child.on('error', error => {
             this.setState({
                 ...this.state,
@@ -619,6 +661,53 @@ export class PlayerController {
     sendMpv(payload) {
         return this.queryMpv(payload).then(() => undefined);
     }
+    queueMpvVolume(volume) {
+        this.pendingMpvVolume = volume;
+        this.setState({ ...this.state, volume });
+        if (this.mpvVolumeFlush) {
+            return this.mpvVolumeFlush;
+        }
+        const sessionId = this.mpvSessionId;
+        let trackedFlush;
+        trackedFlush = this.flushMpvVolume(sessionId).finally(() => {
+            if (this.mpvVolumeFlush === trackedFlush) {
+                this.mpvVolumeFlush = null;
+            }
+        });
+        this.mpvVolumeFlush = trackedFlush;
+        return trackedFlush;
+    }
+    async flushMpvVolume(sessionId) {
+        let lastError = null;
+        while (sessionId === this.mpvSessionId && this.backend === 'mpv' && this.pendingMpvVolume !== null) {
+            const target = this.pendingMpvVolume;
+            this.pendingMpvVolume = null;
+            try {
+                await this.sendMpv({ command: ['set_property', 'volume', target] });
+                if (sessionId !== this.mpvSessionId) {
+                    lastError = new Error('mpv playback session changed.');
+                    break;
+                }
+                this.confirmedMpvVolume = target;
+                lastError = null;
+            }
+            catch (error) {
+                lastError = error;
+                if (sessionId !== this.mpvSessionId) {
+                    break;
+                }
+                if (this.pendingMpvVolume === null) {
+                    if (this.state.volume === target) {
+                        this.setState({ ...this.state, volume: this.confirmedMpvVolume });
+                    }
+                    break;
+                }
+            }
+        }
+        return lastError
+            ? { ok: false, message: 'mpv did not acknowledge the volume change.' }
+            : { ok: true };
+    }
     sendAirPlayCommand(command) {
         if (this.backend === 'airplay' && this.process && !this.process.killed) {
             try {
@@ -662,72 +751,14 @@ export class PlayerController {
         rejecter?.(error);
     }
     queryMpv(payload) {
-        if (!this.ipcPath) {
+        if (!this.mpvIpcClient) {
             return Promise.resolve(null);
         }
-        return new Promise((resolve, reject) => {
-            const socket = new Socket();
-            let buffer = '';
-            let settled = false;
-            const requestId = this.nextMpvRequestId;
-            this.nextMpvRequestId = this.nextMpvRequestId >= Number.MAX_SAFE_INTEGER ? 1 : this.nextMpvRequestId + 1;
-            const requestPayload = attachMpvRequestId(payload, requestId);
-            const settle = (callback) => {
-                if (settled) {
-                    return;
-                }
-                settled = true;
-                clearTimeout(timeout);
-                socket.end();
-                callback();
-            };
-            const timeout = setTimeout(() => {
-                socket.destroy();
-                settle(() => reject(new Error('mpv IPC timed out.')));
-            }, 1000);
-            socket.once('error', error => {
-                settle(() => reject(error));
-            });
-            socket.on('data', chunk => {
-                buffer += chunk.toString('utf8');
-                let newlineIndex = buffer.indexOf('\n');
-                while (newlineIndex !== -1) {
-                    const line = buffer.slice(0, newlineIndex);
-                    buffer = buffer.slice(newlineIndex + 1);
-                    newlineIndex = buffer.indexOf('\n');
-                    if (!line.trim()) {
-                        continue;
-                    }
-                    try {
-                        const parsed = JSON.parse(line);
-                        if (parsed.request_id !== requestId) {
-                            continue;
-                        }
-                        if (parsed.error && parsed.error !== 'success') {
-                            settle(() => reject(new Error(`mpv IPC failed: ${parsed.error}`)));
-                        }
-                        else {
-                            settle(() => resolve(parsed.data ?? null));
-                        }
-                    }
-                    catch {
-                        settle(() => resolve(null));
-                    }
-                }
-            });
-            socket.connect(this.ipcPath, () => {
-                socket.write(`${JSON.stringify(requestPayload)}\n`, error => {
-                    if (error) {
-                        settle(() => reject(error));
-                    }
-                });
-            });
-        });
+        return this.mpvIpcClient.query(payload);
     }
     async waitForReady(backend) {
         const timeoutMs = this.getSettings().tuneTimeoutSeconds * 1000;
         const started = Date.now();
-        let mpvPathReadyAt = 0;
         while (Date.now() - started < timeoutMs) {
             if (!this.process) {
                 throw new Error('Player exited before the stream became ready.');
@@ -739,13 +770,9 @@ export class PlayerController {
             if (this.ipcPath) {
                 try {
                     await this.queryMpv({ command: ['get_property', 'path'] });
-                    mpvPathReadyAt = mpvPathReadyAt || Date.now();
                     if (await this.hasMpvAudioStarted()) {
                         return;
                     }
-                    if (Date.now() - mpvPathReadyAt >= mpvAudioStartFallbackMs) {
-                        return;
-                    }
                 }
                 catch {
                     // The IPC socket can exist briefly before accepting commands.
@@ -766,10 +793,12 @@ export class PlayerController {
     startMpvMetadataPolling() {
         this.stopMpvPolling();
         this.metadataTimer = setInterval(() => {
-            void this.pollMpvMetadata();
+            if (!this.metadataPollInFlight)
+                void this.pollMpvMetadata();
         }, 2500);
         this.playbackStateTimer = setInterval(() => {
-            void this.syncMpvPlaybackState();
+            if (!this.playbackStatePollInFlight)
+                void this.syncMpvPlaybackState();
         }, 500);
         void this.pollMpvMetadata();
         void this.syncMpvPlaybackState();
@@ -788,15 +817,21 @@ export class PlayerController {
         if (this.backend !== 'mpv' || !this.process) {
             return;
         }
-        const metadata = await this.queryMpv({ command: ['get_property', 'metadata'] }).catch(() => null);
-        const elapsed = await this.queryMpv({ command: ['get_property', 'time-pos'] }).catch(() => null);
-        if (typeof elapsed === 'number') {
-            this.setState({ ...this.state, elapsedSeconds: Math.floor(elapsed) });
+        this.metadataPollInFlight = true;
+        try {
+            const metadata = await this.queryMpv({ command: ['get_property', 'metadata'] }).catch(() => null);
+            const elapsed = await this.queryMpv({ command: ['get_property', 'time-pos'] }).catch(() => null);
+            if (typeof elapsed === 'number') {
+                this.setState({ ...this.state, elapsedSeconds: Math.floor(elapsed) });
+            }
+            const title = extractMpvTitle(metadata);
+            if (title) {
+                await this.setMpvMediaTitle(title);
+                this.emitMetadata({ title, raw: JSON.stringify(metadata), updatedAt: new Date().toISOString() });
+            }
         }
-        const title = extractMpvTitle(metadata);
-        if (title) {
-            await this.setMpvMediaTitle(title);
-            this.emitMetadata({ title, raw: JSON.stringify(metadata), updatedAt: new Date().toISOString() });
+        finally {
+            this.metadataPollInFlight = false;
         }
     }
     async setMpvMediaTitle(title) {
@@ -811,22 +846,40 @@ export class PlayerController {
         if (this.backend !== 'mpv' || !this.process || !this.state.ready) {
             return false;
         }
-        const paused = await this.queryMpv({ command: ['get_property', 'pause'] }).catch(() => null);
-        if (typeof paused !== 'boolean') {
+        if (this.playbackStatePollInFlight)
             return false;
+        this.playbackStatePollInFlight = true;
+        try {
+            const paused = await this.queryMpv({ command: ['get_property', 'pause'] }).catch(() => null);
+            if (typeof paused !== 'boolean') {
+                return false;
+            }
+            const state = paused ? 'paused' : 'playing';
+            if (this.state.state !== state) {
+                this.setState({ ...this.state, state });
+            }
+            return true;
         }
-        const state = paused ? 'paused' : 'playing';
-        if (this.state.state !== state) {
-            this.setState({ ...this.state, state });
+        finally {
+            this.playbackStatePollInFlight = false;
         }
-        return true;
     }
     emitMetadata(metadata) {
         for (const listener of this.metadataListeners) {
-            listener(metadata);
+            try {
+                listener(metadata);
+            }
+            catch {
+                // UI/storage listeners must not terminate the player polling loop.
+            }
         }
     }
     cleanupIpc() {
+        this.mpvSessionId += 1;
+        this.mpvIpcClient?.close();
+        this.mpvIpcClient = null;
+        this.pendingMpvVolume = null;
+        this.mpvVolumeFlush = null;
         if (this.ipcPath && !isWindowsNamedPipePath(this.ipcPath) && existsSync(this.ipcPath)) {
             try {
                 unlinkSync(this.ipcPath);
@@ -868,6 +921,25 @@ function isWindowsNamedPipePath(path) {
 function clampVolume(volume) {
     return Math.min(100, Math.max(0, Math.round(volume)));
 }
+function waitForChildExit(child, timeoutMs) {
+    if (child.exitCode === undefined) {
+        return Promise.resolve(true);
+    }
+    if (child.exitCode !== null) {
+        return Promise.resolve(true);
+    }
+    return new Promise(resolve => {
+        const onExit = () => {
+            clearTimeout(timeout);
+            resolve(true);
+        };
+        const timeout = setTimeout(() => {
+            child.off('exit', onExit);
+            resolve(false);
+        }, timeoutMs);
+        child.once('exit', onExit);
+    });
+}
 function delay(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -891,12 +963,6 @@ export function extractMpvTitle(metadata) {
     }
     return undefined;
 }
-function attachMpvRequestId(payload, requestId) {
-    if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
-        return { ...payload, request_id: requestId };
-    }
-    return { command: payload, request_id: requestId };
-}
 async function waitForStartupWindow(getProcess, ms) {
     const started = Date.now();
     while (Date.now() - started < ms) {
@@ -957,7 +1023,7 @@ function leadingMetadataPrefix(value) {
     return cleanMediaTitle(value.slice(0, firstFieldIndex).replace(/[-–—:;,]\s*$/, ''));
 }
 function cleanMediaTitle(value) {
-    const cleaned = value?.replace(/\s+/g, ' ').trim().replace(/^"+|"+$/g, '').trim();
+    const cleaned = sanitizeTerminalText(value)?.replace(/^"+|"+$/g, '').trim();
     return cleaned || undefined;
 }
 function stripIcyStreamTitleWrapper(value) {

package/dist/providers/cache.js

@@ -1,30 +1,34 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
+const maxCacheEntries = 256;
+const maxCacheBytes = 128 * 1024 * 1024;
 export class ProviderCache {
     filePath;
     cache;
+    writesSincePrune = 0;
     constructor(filePath = defaultProviderCachePath()) {
         this.filePath = filePath;
         this.cache = this.read();
     }
     get(key, maxAgeMs) {
-        const entry = this.cache.entries[key];
+        const entry = this.cache.entries[key] ?? this.readShard(key);
         if (!entry) {
             return null;
         }
         if (Date.now() - entry.createdAt > maxAgeMs) {
             return null;
         }
-        return structuredClone(entry.value);
+        return entry.value;
     }
-    getStale(key) {
-        const entry = this.cache.entries[key];
-        return entry ? structuredClone(entry.value) : null;
+    getStale(key, maxAgeMs = 30 * 24 * 60 * 60 * 1000) {
+        const entry = this.cache.entries[key] ?? this.readShard(key);
+        return entry && Date.now() - entry.createdAt <= maxAgeMs ? entry.value : null;
     }
     set(key, value) {
         this.cache.entries[key] = { createdAt: Date.now(), value };
-        this.write();
+        this.writeEntry(key, this.cache.entries[key]);
     }
     read() {
         if (!existsSync(this.filePath)) {
@@ -39,9 +43,63 @@ export class ProviderCache {
             return { version: 1, entries: {} };
         }
     }
-    write() {
-        mkdirSync(dirname(this.filePath), { recursive: true });
-        writeJsonAtomically(this.filePath, this.cache);
+    readShard(key) {
+        const path = join(this.shardDirectory(), `${createHash('sha256').update(key).digest('hex')}.json`);
+        if (!existsSync(path))
+            return undefined;
+        try {
+            const entry = JSON.parse(readFileSync(path, 'utf8'));
+            if (entry.version !== 1 || entry.key !== key || !Number.isFinite(entry.createdAt))
+                return undefined;
+            const cached = { createdAt: entry.createdAt, value: entry.value };
+            this.cache.entries[key] = cached;
+            return cached;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    writeEntry(key, entry) {
+        const directory = this.shardDirectory();
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const path = join(directory, `${createHash('sha256').update(key).digest('hex')}.json`);
+        writeJsonAtomically(path, { version: 1, key, ...entry });
+        this.writesSincePrune += 1;
+        if (this.writesSincePrune >= 16) {
+            this.writesSincePrune = 0;
+            this.pruneShards(directory);
+        }
+    }
+    pruneShards(directory) {
+        const files = readdirSync(directory)
+            .filter(name => name.endsWith('.json'))
+            .flatMap(name => {
+            try {
+                const path = join(directory, name);
+                const stat = statSync(path);
+                return [{ path, bytes: stat.size, modified: stat.mtimeMs }];
+            }
+            catch {
+                return [];
+            }
+        })
+            .sort((left, right) => right.modified - left.modified);
+        let totalBytes = files.reduce((total, file) => total + file.bytes, 0);
+        while (files.length > maxCacheEntries || totalBytes > maxCacheBytes) {
+            const file = files.pop();
+            if (!file)
+                break;
+            try {
+                unlinkSync(file.path);
+                totalBytes -= file.bytes;
+            }
+            catch {
+                // Cache eviction is best-effort.
+            }
+        }
+    }
+    shardDirectory() {
+        return `${this.filePath}.d`;
     }
 }
 function defaultProviderCachePath() {
@@ -57,7 +115,10 @@ function defaultProviderCachePath() {
 }
 function currentDefaultProviderCachePath() {
     if (process.platform === 'darwin') {
-        return join(homedir(), 'Library', 'Application Support', 'radiocli', 'radiocli-cache.json');
+        return join(homedir(), 'Library', 'Caches', 'radiocli', 'radiocli-cache.json');
+    }
+    if (process.platform === 'win32') {
+        return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'RadioCLI', 'radiocli-cache.json');
     }
     return join(process.env.XDG_CACHE_HOME ?? join(homedir(), '.cache'), 'radiocli', 'radiocli-cache.json');
 }
@@ -70,8 +131,11 @@ function legacyDefaultProviderCachePath() {
 function writeJsonAtomically(filePath, value) {
     const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
     try {
-        writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+        writeFileSync(tempPath, `${JSON.stringify(value)}\n`, { encoding: 'utf8', mode: 0o600 });
         renameSync(tempPath, filePath);
+        if (process.platform !== 'win32') {
+            chmodSync(filePath, 0o600);
+        }
     }
     catch (error) {
         rmSync(tempPath, { force: true });

package/dist/providers/provider-manager.js

@@ -23,13 +23,20 @@ export class ProviderManager {
         return this.radioBrowser.detectLocation();
     }
     async search(query, settings, options = {}) {
-        const radioBrowser = await this.radioBrowser.search(query, options);
-        if ((!settings.enableRadioGarden && !options.includeExperimental) || (options.offset ?? 0) > 0) {
-            return radioBrowser;
+        const includeGarden = (settings.enableRadioGarden || options.includeExperimental) && (options.offset ?? 0) === 0;
+        if (!includeGarden) {
+            return this.radioBrowser.search(query, options);
         }
-        const experimental = await Promise.allSettled([this.radioGarden.search(query, options)]);
-        const radioGarden = experimental.flatMap(result => (result.status === 'fulfilled' ? result.value : []));
-        return dedupeStations([...radioBrowser, ...radioGarden]).slice(0, options.limit ?? 80);
+        const [browserResult, gardenResult] = await Promise.allSettled([
+            this.radioBrowser.search(query, options),
+            this.radioGarden.search(query, options)
+        ]);
+        const radioBrowser = browserResult.status === 'fulfilled' ? browserResult.value : [];
+        const radioGarden = gardenResult.status === 'fulfilled' ? gardenResult.value : [];
+        if (radioBrowser.length === 0 && radioGarden.length === 0 && browserResult.status === 'rejected') {
+            throw browserResult.reason;
+        }
+        return dedupeStations(interleave(radioBrowser, radioGarden)).slice(0, options.limit ?? 80);
     }
     async resolve(station) {
         if (station.provider === 'radio-garden') {
@@ -51,3 +58,16 @@ export class ProviderManager {
         };
     }
 }
+function interleave(primary, secondary) {
+    const merged = [];
+    const length = Math.max(primary.length, secondary.length);
+    for (let index = 0; index < length; index += 1) {
+        const primaryStation = primary[index];
+        const secondaryStation = secondary[index];
+        if (primaryStation)
+            merged.push(primaryStation);
+        if (secondaryStation)
+            merged.push(secondaryStation);
+    }
+    return merged;
+}