Merge pull request #1589 from ably/1424-document-MessagePack-platform…

…-default [SDK-3816] Document platform-specific nature of `useBinaryProtocol` default
ably · Jan 25, 2024 · f463647 · f463647
2 parents 3336b66 + 89bd9ce
commit f463647
Show file tree

Hide file tree

Showing 4 changed files with 8 additions and 4 deletions.
diff --git a/ably.d.ts b/ably.d.ts
@@ -472,9 +472,9 @@ declare namespace Types {
     tlsPort?: number;
 
     /**
-     * When `true`, the more efficient MsgPack binary encoding is used. When `false`, JSON text encoding is used. The default is `true`.
+     * When `true`, the more efficient MsgPack binary encoding is used. When `false`, JSON text encoding is used. The default is `true` for Node.js, and `false` for all other platforms.
      *
-     * @defaultValue `true`
+     * @defaultValue `true` for Node.js, `false` for all other platforms
      */
     useBinaryProtocol?: boolean;
 

diff --git a/src/platform/nativescript/config.js b/src/platform/nativescript/config.js
@@ -32,7 +32,7 @@ var Config = {
   createHmac: null,
   msgpack: msgpack,
   supportsBinary: typeof TextDecoder !== 'undefined' && TextDecoder,
-  preferBinary: false,
+  preferBinary: false, // Motivation as on web; see `preferBinary` comment there.
   ArrayBuffer: ArrayBuffer,
   atob: null,
   nextTick: function (f) {

diff --git a/src/platform/react-native/config.ts b/src/platform/react-native/config.ts
@@ -16,7 +16,7 @@ const Platform: IPlatformConfig = {
   createHmac: null,
   msgpack: msgpack,
   supportsBinary: !!(typeof TextDecoder !== 'undefined' && TextDecoder),
-  preferBinary: false,
+  preferBinary: false, // Motivation as on web; see `preferBinary` comment there.
   ArrayBuffer: typeof ArrayBuffer !== 'undefined' && ArrayBuffer,
   atob: global.atob,
   nextTick: function (f: Function) {

diff --git a/src/platform/web/config.ts b/src/platform/web/config.ts
@@ -41,6 +41,10 @@ const Config: IPlatformConfig = {
   createHmac: null,
   msgpack: msgpack,
   supportsBinary: !!globalObject.TextDecoder,
+  /* Per Paddy (https://ably-real-time.slack.com/archives/CURL4U2FP/p1705674537763479) web intentionally prefers JSON to MessagePack:
+   *
+   * > browsers' support for binary types in general was historically poor, and JSON transport performance is significantly better in a browser than msgpack. In modern browsers then binary is supported consistently, but I'd still expect that JSON encode/decode performance is dramatically better than msgpack in a browser.
+   */
   preferBinary: false,
   ArrayBuffer: globalObject.ArrayBuffer,
   atob: globalObject.atob,