Merge pull request #590 from tiagosiebler/customParser1

feat(v3.1.0, #588): introduce custom JSON parser hook & small refinements

Author: tiagosiebler

README.md

@@ -428,6 +428,51 @@ wsClient.subscribeUsdFuturesUserDataStream();
 
 See [websocket-client.ts](./src/websocket-client.ts) for further information. Also see [ws-userdata.ts](./examples/ws-userdata.ts) for user data examples.
 
+#### Preserving large integers in WebSocket messages
+
+By default, messages are parsed using `JSON.parse`, which cannot precisely represent integers larger than `Number.MAX_SAFE_INTEGER`.
+If you need to preserve large integers (e.g., order IDs), provide a custom parser via `customParseJSONFn`.
+
+Example using RegEx below, although alternatives are possible too if desired. For more exampes check [ws-custom-parser.ts](./examples/WebSockets/ws-custom-parser.ts) in the examples folder:
+
+```ts
+import { WebsocketClient } from 'binance';
+
+/**
+ * ETHUSDT in futures can have unusually large orderId values, sent as numbers. See this thread for more details:
+ * https://github.com/tiagosiebler/binance/issues/208
+ *
+ * If this is a problem for you, you can set a custom JSON parsing alternative using the customParseJSONFn hook injected into the WebsocketClient's constructor, as below:
+ */
+const ws = new WebsocketClient({
+  // Default behaviour, if you don't include this:
+  // customParseJSONFn: (rawEvent) => {
+  //   return JSON.parse(rawEvent);
+  // },
+
+  // Or, pre-process the raw event using RegEx, before using the same workflow:
+  customParseJSONFn: (rawEvent) => {
+    return JSON.parse(
+      rawEvent.replace(/"orderId":\s*(\d+)/g, '"orderId":"$1"'),
+    );
+  },
+
+  // Or, use a 3rd party library such as json-bigint:
+  // customParseJSONFn: (rawEvent) => {
+  //   return JSONbig({ storeAsString: true }).parse(rawEvent);
+  // },
+});
+
+ws.on('message', (msg) => {
+  console.log(msg);
+});
+
+// If you prefer native BigInt, beware JSON.stringify will throw on BigInt values.
+// Use a custom replacer or JSONbig.stringify if you need to log/serialize:
+// const replacer = (_k: string, v: unknown) => typeof v === 'bigint' ? v.toString() : v;
+// console.log(JSON.stringify(msg, replacer));
+```
+
 ### WebSocket API
 
 Some of the product groups available on Binance also support sending requests (commands) over an active WebSocket connection. This is called the WebSocket API.

examples/WebSockets/ws-custom-parser.ts

@@ -0,0 +1,41 @@
+// Optional, for 3rd scenario below:
+// Import 3rd party library for parsing big number types in JSON
+// import JSONbig from 'json-bigint';
+
+import { WebsocketClient } from '../../src';
+
+// Demonstrates using a custom JSON parser for incoming WS messages to preserve big integers
+
+/**
+ * ETHUSDT in futures can have unusually large orderId values, sent as numbers. See this thread for more details:
+ * https://github.com/tiagosiebler/binance/issues/208
+ *
+ * If this is a problem for you, you can set a custom JSON parsing alternative using the customParseJSONFn hook injected into the WebsocketClient's constructor, as below:
+ */
+const ws = new WebsocketClient({
+  // Default behaviour, if you don't include this:
+  // customParseJSONFn: (rawEvent) => {
+  //   return JSON.parse(rawEvent);
+  // },
+  // Or, pre-process the raw event using RegEx, before using the same workflow:
+  customParseJSONFn: (rawEvent) => {
+    return JSON.parse(
+      rawEvent.replace(/"orderId":\s*(\d+)/g, '"orderId":"$1"'),
+    );
+  },
+  // Or, use a 3rd party library such as json-bigint:
+  // customParseJSONFn: (rawEvent) => {
+  //   return JSONbig({ storeAsString: true }).parse(rawEvent);
+  // },
+});
+
+ws.on('open', ({ wsKey }) => {
+  console.log('ws connected', wsKey);
+});
+
+ws.on('message', (msg) => {
+  console.log('msg:', msg);
+});
+
+// Subscribe to a couple of topics
+ws.subscribe(['btcusdt@trade', '!ticker@arr'], 'main');

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "binance",
-  "version": "3.0.9",
+  "version": "3.1.0",
   "description": "Professional Node.js & JavaScript SDK for Binance REST APIs & WebSockets, with TypeScript & end-to-end tests.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package.json

@@ -178,6 +178,12 @@ export interface WSClientConfigurableOptions {
    * Look in the examples folder for a demonstration on using node's createHmac instead.
    */
   customSignMessageFn?: (message: string, secret: string) => Promise<string>;
+
+  /**
+   * Optional custom JSON parser used for incoming WS messages.
+   * Defaults to JSON.parse.
+   */
+  customParseJSONFn?: (raw: string) => object;
 }
 
 /**

src/types/websockets/ws-general.ts

@@ -4,6 +4,7 @@ import WebSocket from 'isomorphic-ws';
 import { WsRequestOperationBinance } from '../../types/websockets/ws-api';
 import {
   WebsocketClientOptions,
+  WSClientConfigurableOptions,
   WsMarket,
   WsTopic,
 } from '../../types/websockets/ws-general';
@@ -623,14 +624,20 @@ export function resolveWsKeyForLegacyMarket(
     }
   }
 }
-export function parseRawWsMessageLegacy(event: any) {
+export function parseRawWsMessageLegacy(
+  event: any,
+  options: WSClientConfigurableOptions,
+) {
   if (typeof event === 'string') {
-    const parsedEvent = JSON.parse(event);
+    const parsedEvent =
+      typeof options.customParseJSONFn === 'function'
+        ? options.customParseJSONFn(event)
+        : JSON.parse(event);
 
     // WS events are wrapped into "data"
     if (parsedEvent.data) {
       if (typeof parsedEvent.data === 'string') {
-        return parseRawWsMessageLegacy(parsedEvent.data);
+        return parseRawWsMessageLegacy(parsedEvent.data, options);
       }
 
       return parsedEvent.data;
@@ -645,7 +652,7 @@ export function parseRawWsMessageLegacy(event: any) {
     return parsedEvent;
   }
   if (event?.data) {
-    return parseRawWsMessageLegacy(event.data);
+    return parseRawWsMessageLegacy(event.data, options);
   }
   return event;
 }
@@ -655,10 +662,13 @@ export function parseRawWsMessageLegacy(event: any) {
  *
  * Any mapping or additonal handling should not be done here.
  */
-export function parseRawWsMessage(event: any): any {
+export function parseRawWsMessage(
+  event: any,
+  options: WSClientConfigurableOptions,
+): any {
   // WS MessageLike->data (contains JSON as a string)
   if (event?.data) {
-    return parseRawWsMessage(event.data);
+    return parseRawWsMessage(event.data, options);
   }
 
   if (typeof event === 'string') {
@@ -668,8 +678,11 @@ export function parseRawWsMessage(event: any): any {
     // - user data, via ws api (Without listen key)
     // - ws api responses
 
-    const parsedEvent = JSON.parse(event);
+    if (typeof options.customParseJSONFn === 'function') {
+      return options.customParseJSONFn(event);
+    }
 
+    const parsedEvent = JSON.parse(event);
     return parsedEvent;
   }
 

src/util/websockets/websocket-util.ts

@@ -331,7 +331,7 @@ export class WebsocketClientV1 extends EventEmitter {
     try {
       this.clearPongTimer(wsKey);
 
-      const msg = parseRawWsMessageLegacy(event);
+      const msg = parseRawWsMessageLegacy(event, this.options);
 
       // Edge case where raw event does not include event type, detect using wsKey and mutate msg.e
       const eventType = parseEventTypeFromMessage(wsKey as any, msg);

src/websocket-client-legacy.ts

@@ -780,7 +780,7 @@ export class WebsocketClient extends BaseWebsocketClient<
        * Extract event from JSON
        *
        */
-      const parsedEvent = parseRawWsMessage(event);
+      const parsedEvent = parseRawWsMessage(event, this.options);
 
       /**
        *