WebSocket Event Type Guards: Narrowing Union Types

wsClient.on('formattedMessage', (data) => {
  // data: WsFormattedMessage (broad union)
  if (isWsFormattedKline(data)) {
    // data: WsMessageKlineFormatted (narrow — all kline fields available)
    console.log(data.kline.close); // ✅ typed as number
  }
});

import {
  isWsFormattedKline,
  type WsFormattedMessage,
  type WsMessageKlineFormatted,
} from 'binance';

function handleMessage(data: WsFormattedMessage) {
  if (isWsFormattedKline(data)) {
    // TypeScript now knows: data is WsMessageKlineFormatted
    const { symbol, kline } = data;
    console.log(symbol, kline.open, kline.close, kline.isFinal);
  }
}

import {
  WebsocketClient,
  isWsFormattedKline,
  isWsAggTradeFormatted,
  isWsFormattedTrade,
  isWsFormatted24hrTicker,
  isWsFormattedRollingWindowTickerArray,
  isWsFormattedMarkPriceUpdateEvent,
  isWsFormattedMarkPriceUpdateArray,
  isWsFormattedForceOrder,
  isWsPartialBookDepthEventFormatted,
  isWsDiffBookDepthEventFormatted,
  isWsFormattedUserDataEvent,
  isWsFormattedSpotUserDataExecutionReport,
  isWsFormattedSpotBalanceUpdate,
  isWsFormattedFuturesUserDataAccountUpdate,
  isWsFormattedFuturesUserDataTradeUpdateEvent,
  isWsFormattedFuturesUserDataMarginCall,
  isWsFormattedFuturesAlgoUpdateEvent,
  isWsFormattedFuturesUserDataListenKeyExpired,
} from 'binance';

const wsClient = new WebsocketClient({
  api_key: 'YOUR_API_KEY',
  api_secret: 'YOUR_API_SECRET',
  beautify: true,
});

wsClient.on('formattedMessage', (data) => {
  // --- Market data events ---

  if (isWsFormattedKline(data)) {
    const { symbol, kline } = data;
    console.log(`[Kline] ${symbol} ${kline.interval}: O=${kline.open} H=${kline.high} L=${kline.low} C=${kline.close} V=${kline.volume} final=${kline.final}`);
    return;
  }

  if (isWsAggTradeFormatted(data)) {
    console.log(`[AggTrade] ${data.symbol} price=${data.price} qty=${data.quantity} maker=${data.maker}`);
    return;
  }

  if (isWsFormattedTrade(data)) {
    console.log(`[Trade] ${data.symbol} price=${data.price} qty=${data.quantity}`);
    return;
  }

  if (isWsFormatted24hrTicker(data)) {
    console.log(`[24hrTicker] ${data.symbol} close=${data.closePrice} change=${data.priceChangePercent}%`);
    return;
  }

  if (isWsFormattedRollingWindowTickerArray(data)) {
    for (const ticker of data) {
      console.log(`[RollingTicker] ${ticker.symbol} ${ticker.eventType}`);
    }
    return;
  }

  if (isWsFormattedMarkPriceUpdateEvent(data)) {
    console.log(`[MarkPrice] ${data.symbol} markPrice=${data.markPrice} fundingRate=${data.fundingRate}`);
    return;
  }

  if (isWsFormattedMarkPriceUpdateArray(data)) {
    for (const mp of data) {
      console.log(`[MarkPriceArray] ${mp.symbol} markPrice=${mp.markPrice}`);
    }
    return;
  }

  if (isWsFormattedForceOrder(data)) {
    const { liquidationOrder } = data;
    console.log(`[Liquidation] ${liquidationOrder.symbol} side=${liquidationOrder.side} qty=${liquidationOrder.originalQuantity}`);
    return;
  }

  if (isWsPartialBookDepthEventFormatted(data)) {
    console.log(`[PartialDepth] ${data.symbol} bids=${data.bids.length} asks=${data.asks.length}`);
    return;
  }

  if (isWsDiffBookDepthEventFormatted(data)) {
    console.log(`[DiffDepth] ${data.symbol} finalUpdateId=${data.finalUpdateId}`);
    return;
  }

  // --- User data events (also available via formattedUserDataMessage) ---

  if (isWsFormattedUserDataEvent(data)) {
    if (isWsFormattedSpotUserDataExecutionReport(data)) {
      console.log(`[Spot Order] ${data.symbol} ${data.side} ${data.orderStatus} orderId=${data.orderId}`);
      return;
    }

    if (isWsFormattedSpotBalanceUpdate(data)) {
      console.log(`[Balance Update] asset=${data.asset} delta=${data.balanceDelta}`);
      return;
    }

    if (isWsFormattedFuturesUserDataAccountUpdate(data)) {
      console.log(`[Futures Account Update] reason=${data.updateData.updateType}`);
      return;
    }

    if (isWsFormattedFuturesUserDataTradeUpdateEvent(data)) {
      const { order } = data;
      console.log(`[Futures Order Update] ${order.symbol} status=${order.orderStatus} side=${order.side}`);
      return;
    }

    if (isWsFormattedFuturesUserDataMarginCall(data)) {
      console.log(`[Margin Call] positions at risk: ${data.positions.length}`);
      return;
    }

    if (isWsFormattedFuturesAlgoUpdateEvent(data)) {
      console.log(`[Algo Update] algoId=${data.algoOrder.algoId} status=${data.algoOrder.algoStatus}`);
      return;
    }

    if (isWsFormattedFuturesUserDataListenKeyExpired(data)) {
      console.warn('[Listen Key Expired] reconnecting user data stream...');
      return;
    }
  }
});

// Subscribe to some streams
wsClient.subscribeKlines('BTCUSDT', '1m', 'spot');
wsClient.subscribeMarkPrice('BTCUSDT', 'usdm');
wsClient.subscribeUsdFuturesUserDataStream();