fix(): isWsPartialBookDepthEventFormatted type guard event recognition

Author: tiagosiebler

examples/README.md

@@ -15,6 +15,33 @@ Samples that API credentials using `process.env.API_KEY_COM` can be spawned with
 APIKEY="apikeypastedhere" APISECRET="apisecretpastedhere" tsx examples/WebSockets/ws-userdata-listenkey.ts
 ```
 
+### WebSockets
+
+All examples relating to WebSockets can be found in the [examples/WebSockets](./WebSockets/) folder. High level summary of available examples:
+
+#### Consumers
+
+These are purely for receiving data from Binance's WebSockets (market data, account updates, etc).
+
+##### Market Data
+- ws-public.ts
+  - Demonstration on general usage of the WebSocket client to subscribe to / unsubscribe from one or more market data topics.
+- ws-public-spot-orderbook.ts
+-	ws-public-spot-trades.ts
+
+##### Account Data
+
+- ws-close.ts
+- ws-unsubscribe.ts
+- ws-proxy-socks.ts
+- ws-public-usdm-funding.ts
+- ws-userdata-testnet.ts
+-	ws-userdata-listenkey.ts
+- ws-userdata-connection-safety.ts
+- ws-userdata-wsapi.ts
+- ws-api-client.ts
+- ws-api-raw-promises.ts
+- deprecated-ws-public.ts
 
 ## REST USDM Examples
 

examples/WebSockets/ws-public-spot-orderbook.ts

@@ -1,8 +1,10 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/* eslint-disable no-unused-vars */
 import {
   DefaultLogger,
-  getContextFromWsKey,
   isWsPartialBookDepthEventFormatted,
   WebsocketClient,
+  WsMessagePartialBookDepthEventFormatted,
 } from '../../src/index';
 
 // or, with the npm package
@@ -27,18 +29,19 @@ import {
     logger,
   );
 
+  const topicsPartialBookDepths: string[] = [];
+
   /**
    * Simple example for receiving depth snapshots from spot orderbooks
    */
   wsClient.on('formattedMessage', (data) => {
     if (isWsPartialBookDepthEventFormatted(data)) {
-      const context = getContextFromWsKey(data.wsKey);
-
-      if (!context?.symbol) {
+      const [symbol] = data.streamName.split('@');
+      if (!symbol) {
         throw new Error('Failed to extract context from event?');
       }
 
-      console.log(`ws book event for "${context.symbol.toUpperCase()}"`, data);
+      console.log(`ws book event for "${symbol.toUpperCase()}"`, data);
       return;
     }
 
@@ -61,13 +64,27 @@ import {
     console.error('ws exception: ', data?.wsKey, data);
   });
 
-  // Request subscription to the following symbol trade events:
-  const symbols = ['BTCUSDT', 'ETHUSDT', 'BNBUSDT'];
-  // const symbols = ['BTCUSDT'];
+  // Request subscription to the following symbol events:
+  const symbols = ['BTCUSDT'];
+  // const symbols = ['BTCUSDT', 'ETHUSDT', 'BNBUSDT'];
 
   // Loop through symbols
   for (const symbol of symbols) {
     console.log('subscribing to trades for: ', symbol);
-    wsClient.subscribePartialBookDepths(symbol, 20, 1000, 'spot');
+    // The old way, convenient but unnecessary:
+    // wsClient.subscribePartialBookDepths(symbol, levels, 1000, 'spot');
+
+    // Manually build a topic matching the structure expected by binance:
+    // btcusdt@depth20@1000ms
+
+    const streamName = 'depth';
+    const levels = 20;
+    const updateMs = '@' + 1000 + 'ms';
+
+    const topic = `${symbol.toLowerCase()}@${streamName}${levels}${updateMs}`;
+    topicsPartialBookDepths.push(topic);
   }
+
+  // Request subscribe for these topics in the main product group (spot markets are under "main")
+  wsClient.subscribe(topicsPartialBookDepths, 'main');
 })();

src/types/websockets/ws-events-formatted.ts

@@ -172,7 +172,7 @@ export interface WsMessageBookTickerEventFormatted extends WsSharedBase {
 }
 
 export interface WsMessagePartialBookDepthEventFormatted extends WsSharedBase {
-  eventType: 'partialBookDepth';
+  eventType: 'partialBookDepth' | 'string';
   lastUpdateId: number;
   bids: OrderBookRowFormatted[];
   asks: OrderBookRowFormatted[];

src/types/websockets/ws-general.ts

@@ -36,6 +36,7 @@ export type WsMarket =
 export interface WsSharedBase {
   wsMarket: WsMarket;
   wsKey: WsKey;
+  streamName: string;
 }
 
 export interface WsResponse {
@@ -123,6 +124,11 @@ export interface WSClientConfigurableOptions {
 
   beautify?: boolean;
 
+  /**
+   * If true, log a warning if the beautifier is missing anything for an event
+   */
+  beautifyWarnIfMissing?: boolean;
+
   /**
    * Set to `true` to connect to Binance's testnet environment.
    *

src/util/beautifier-maps.ts

@@ -18,6 +18,19 @@ const rollingTickerEventMap = {
   n: 'totalTrades',
 };
 
+/**
+ * The beautifier map defines how specific properties are renamed into a more readable property name.
+ *
+ * At first, it's a simple key:value map. The key is the original property name (e.g. aggTrades or bookTickerEvent (for the top-level name of an event: ("bookTicker" + "Event"))).
+ *
+ * The values have different behaviours:
+ * - Value is an object, each child property is renamed to the value
+ *   e.g. aggTrades: { a: "aggTradeId" } -> aggTrades: { aggTradeId: value }
+ * - Value is a string, this points to another key in the map.
+ *   e.g. klineEvent: { k: "kline" } resolves to
+ *        klineEvent: { kline: { BEAUTIFIER_EVENT_MAP["kline"] } }
+ * - Value is an array, each element in that array is transformed into an object.
+ */
 export const BEAUTIFIER_EVENT_MAP = {
   aggTrades: {
     a: 'aggTradeId',

src/util/beautifier.ts

@@ -6,13 +6,14 @@ export interface BeautifierConfig {
 }
 
 export default class Beautifier {
-  private beautificationMap: Record<string, Record<string, any>>;
+  private beautificationMap: Record<string, Record<string, any> | string> =
+    BEAUTIFIER_EVENT_MAP;
 
   private floatKeys: string[];
 
   private floatKeysHashMap: Record<string, boolean>;
 
-  private config: BeautifierConfig | undefined;
+  private config: BeautifierConfig;
 
   constructor(config: BeautifierConfig) {
     this.config = config;
@@ -158,11 +159,14 @@ export default class Beautifier {
     this.floatKeys.forEach((keyName) => {
       this.floatKeysHashMap[keyName] = true;
     });
+  }
 
-    this.beautificationMap = BEAUTIFIER_EVENT_MAP;
+  setWarnIfMissing(value: boolean) {
+    this.config.warnKeyMissingInMap = value;
   }
 
   beautifyValueWithKey(key: string | number, val: unknown) {
+    // console.log('beautifier.beautifyValueWithKey()', { key, val });
     if (typeof val === 'string' && this.floatKeysHashMap[key] && val !== '') {
       const result = parseFloat(val);
       if (isNaN(result)) {
@@ -177,6 +181,7 @@ export default class Beautifier {
    * Beautify array or object, recurisvely
    */
   beautifyObjectValues(data: any | any[]) {
+    // console.log('beautifier.beautifyObjectValues()', { data });
     if (Array.isArray(data)) {
       return this.beautifyArrayValues(data);
     }
@@ -197,6 +202,7 @@ export default class Beautifier {
   }
 
   beautifyArrayValues(data: any[], parentKey?: string | number) {
+    // console.log('beautifier.beautifyArrayValues()', { data, parentKey });
     const beautifedArray: any[] = [];
     for (const [key, val] of data.entries()) {
       const type = typeof val;
@@ -212,7 +218,6 @@ export default class Beautifier {
   }
 
   beautify(data: any, key?: string | number) {
-    // console.log('beautify()', { key });
     if (typeof key !== 'string' && typeof key !== 'number') {
       console.warn(
         `beautify(object, ${key}) is not valid key - beautification failed `,
@@ -223,6 +228,7 @@ export default class Beautifier {
     }
 
     const knownBeautification = this.beautificationMap[key];
+    // console.log('beautify: ', { key, knownBeautification }, data);
     if (!knownBeautification) {
       const valueType = typeof data;
       const isPrimitive =
@@ -251,18 +257,21 @@ export default class Beautifier {
     }
 
     const newItem = {};
-    for (const key in data) {
-      const value = data[key];
+    for (const propertyKey in data) {
+      const value = data[propertyKey];
       const valueType = typeof value;
 
-      let newKey = knownBeautification[key] || key;
+      let newKey = knownBeautification[propertyKey] || propertyKey;
       if (Array.isArray(newKey)) {
         newKey = newKey[0];
       }
 
       if (!Array.isArray(value)) {
         if (valueType === 'object' && value !== null) {
-          newItem[newKey] = this.beautify(value, knownBeautification[key]);
+          newItem[newKey] = this.beautify(
+            value,
+            knownBeautification[propertyKey],
+          );
         } else {
           newItem[newKey] = this.beautifyValueWithKey(newKey, value);
         }
@@ -271,10 +280,43 @@ export default class Beautifier {
 
       const newArray: any[] = [];
       if (Array.isArray(this.beautificationMap[newKey])) {
+        // console.log('beautify().isArray(): ', {
+        //   newKey,
+        //   arrayFromMap: this.beautificationMap[newKey],
+        // });
         for (const elementValue of value) {
           const mappedBeautification =
-            this.beautificationMap[knownBeautification[key]];
+            this.beautificationMap[knownBeautification[propertyKey]];
+
+          // console.log('mapped meautification: ', {
+          //   knownBeautification: knownBeautification[propertyKey],
+          //   mappedBeautification,
+          //   key,
+          //   subKey: propertyKey,
+          //   newKey,
+          // });
+
+          if (!mappedBeautification) {
+            // console.warn(
+            //   `Beautifier(): found map for "${key}" but property with array ("${propertyKey}") is missing in map: `,
+            //   {
+            //     eventMapKey: key,
+            //     propertyKey: propertyKey,
+            //     elementValue,
+            //     knownBeautification,
+            //     value,
+            //     // beautfTest1: this.beautify(value, propertyKey),
+            //   },
+            // );
+            newArray.push(elementValue);
+
+            continue;
+          }
           const childMapping = mappedBeautification[0];
+          // const childMapping =
+          //   typeof mappedBeautification === 'string' // Pointer to another key
+          //     ? this.beautificationMap[mappedBeautification]
+          //     : mappedBeautification[0];
 
           if (typeof childMapping === 'object' && childMapping !== null) {
             const mappedResult = {};

src/util/typeGuards.ts

@@ -125,10 +125,23 @@ export function isWsAggTradeFormatted(
   return !Array.isArray(data) && data.eventType === 'aggTrade';
 }
 
+const partialBookDepthEventTypeMap = new Map()
+  // For dedicated connection
+  .set('partialBookDepth', true)
+  // For multiplex connection
+  .set('depth5@100ms', true)
+  .set('depth10@100ms', true)
+  .set('depth20@100ms', true)
+  .set('depth5@1000ms', true)
+  .set('depth10@1000ms', true)
+  .set('depth20@1000ms', true);
+
 export function isWsPartialBookDepthEventFormatted(
   data: WsFormattedMessage,
 ): data is WsMessagePartialBookDepthEventFormatted {
-  return !Array.isArray(data) && data.eventType === 'partialBookDepth';
+  return (
+    !Array.isArray(data) && partialBookDepthEventTypeMap.has(data.eventType)
+  );
 }
 
 /**

src/util/websockets/websocket-util.ts

@@ -614,6 +614,9 @@ interface WsContext {
   otherParams: undefined | string[];
 }
 
+/**
+ * @deprecated Only works for legacy WS client, where one connection exists per key
+ */
 export function getContextFromWsKey(legacyWsKey: any): WsContext {
   const [market, streamName, symbol, listenKey, wsKey, ...otherParams] =
     legacyWsKey.split('_');

src/websocket-client.ts

@@ -86,7 +86,7 @@ export class WebsocketClient extends BaseWebsocketClient<
   private restClientCache: RestClientCache = new RestClientCache();
 
   private beautifier: Beautifier = new Beautifier({
-    warnKeyMissingInMap: true,
+    warnKeyMissingInMap: false,
   });
 
   private userDataStreamManager: UserDataStreamManager;
@@ -97,6 +97,10 @@ export class WebsocketClient extends BaseWebsocketClient<
   constructor(options?: WSClientConfigurableOptions, logger?: DefaultLogger) {
     super(options, logger);
 
+    if (options?.beautifyWarnIfMissing) {
+      this.beautifier.setWarnIfMissing(options.beautifyWarnIfMissing);
+    }
+
     /**
      * Binance uses native WebSocket ping/pong frames, which cannot be directly used in
      * some environents (e.g. most browsers do not support sending raw ping/pong frames).