feat: Support custom JSON message reviver and replacer (enisdenjo…

…#172) Co-authored-by: enisdenjo <badurinadenis@gmail.com>
ilijaNL · Apr 29, 2021 · 0a9894e · 0a9894e
1 parent 3dfa8db
commit 0a9894e
Show file tree

Hide file tree

Showing 9 changed files with 304 additions and 26 deletions.
diff --git a/docs/interfaces/client.clientoptions.md b/docs/interfaces/client.clientoptions.md
@@ -13,6 +13,8 @@ Configuration used for the GraphQL over WebSocket client.
 - [connectionParams](client.clientoptions.md#connectionparams)
 - [generateID](client.clientoptions.md#generateid)
 - [isFatalConnectionProblem](client.clientoptions.md#isfatalconnectionproblem)
+- [jsonMessageReplacer](client.clientoptions.md#jsonmessagereplacer)
+- [jsonMessageReviver](client.clientoptions.md#jsonmessagereviver)
 - [keepAlive](client.clientoptions.md#keepalive)
 - [lazy](client.clientoptions.md#lazy)
 - [on](client.clientoptions.md#on)
@@ -92,6 +94,26 @@ option.
 
 ___
 
+### jsonMessageReplacer
+
+• `Optional` **jsonMessageReplacer**: [*JSONMessageReplacer*](../modules/common.md#jsonmessagereplacer)
+
+An optional override for the JSON.stringify function used to serialize
+outgoing messages from this client. Useful for serializing custom
+datatypes out to the client.
+
+___
+
+### jsonMessageReviver
+
+• `Optional` **jsonMessageReviver**: [*JSONMessageReviver*](../modules/common.md#jsonmessagereviver)
+
+An optional override for the JSON.parse function used to hydrate
+incoming messages to this client. Useful for parsing custom datatypes
+out of the incoming JSON.
+
+___
+
 ### keepAlive
 
 • `Optional` **keepAlive**: *number*

diff --git a/docs/interfaces/server.serveroptions.md b/docs/interfaces/server.serveroptions.md
@@ -17,6 +17,8 @@
 - [connectionInitWaitTimeout](server.serveroptions.md#connectioninitwaittimeout)
 - [context](server.serveroptions.md#context)
 - [execute](server.serveroptions.md#execute)
+- [jsonMessageReplacer](server.serveroptions.md#jsonmessagereplacer)
+- [jsonMessageReviver](server.serveroptions.md#jsonmessagereviver)
 - [onClose](server.serveroptions.md#onclose)
 - [onComplete](server.serveroptions.md#oncomplete)
 - [onConnect](server.serveroptions.md#onconnect)
@@ -94,6 +96,26 @@ in the close event reason.
 
 ___
 
+### jsonMessageReplacer
+
+• `Optional` **jsonMessageReplacer**: [*JSONMessageReplacer*](../modules/common.md#jsonmessagereplacer)
+
+An optional override for the JSON.stringify function used to serialize
+outgoing messages to from server. Useful for serializing custom
+datatypes out to the client.
+
+___
+
+### jsonMessageReviver
+
+• `Optional` **jsonMessageReviver**: [*JSONMessageReviver*](../modules/common.md#jsonmessagereviver)
+
+An optional override for the JSON.parse function used to hydrate
+incoming messages to this server. Useful for parsing custom datatypes
+out of the incoming JSON.
+
+___
+
 ### onClose
 
 • `Optional` **onClose**: (`ctx`: [*Context*](server.context.md)<E\>, `code`: *number*, `reason`: *string*) => *void* \| *Promise*<void\>

diff --git a/docs/modules/client.md b/docs/modules/client.md
@@ -13,6 +13,8 @@
 - [ErrorMessage](client.md#errormessage)
 - [GRAPHQL\_TRANSPORT\_WS\_PROTOCOL](client.md#graphql_transport_ws_protocol)
 - [ID](client.md#id)
+- [JSONMessageReplacer](client.md#jsonmessagereplacer)
+- [JSONMessageReviver](client.md#jsonmessagereviver)
 - [Message](client.md#message)
 - [MessageType](client.md#messagetype)
 - [NextMessage](client.md#nextmessage)
@@ -259,6 +261,18 @@ Re-exports: [ID](common.md#id)
 
 ___
 
+### JSONMessageReplacer
+
+Re-exports: [JSONMessageReplacer](common.md#jsonmessagereplacer)
+
+___
+
+### JSONMessageReviver
+
+Re-exports: [JSONMessageReviver](common.md#jsonmessagereviver)
+
+___
+
 ### Message
 
 Re-exports: [Message](common.md#message)

diff --git a/docs/modules/common.md b/docs/modules/common.md
@@ -23,6 +23,8 @@
 ### Type aliases
 
 - [ID](common.md#id)
+- [JSONMessageReplacer](common.md#jsonmessagereplacer)
+- [JSONMessageReviver](common.md#jsonmessagereviver)
 - [Message](common.md#message)
 
 ### Variables
@@ -47,6 +49,58 @@ subscriptions established by the client.
 
 ___
 
+### JSONMessageReplacer
+
+Ƭ **JSONMessageReplacer**: (`this`: *any*, `key`: *string*, `value`: *any*) => *any*
+
+Function that allows customization of the produced JSON string
+for the elements of an outgoing `Message` object.
+
+Read more about using it:
+https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#the_replacer_parameter
+
+#### Type declaration:
+
+▸ (`this`: *any*, `key`: *string*, `value`: *any*): *any*
+
+#### Parameters:
+
+| Name | Type |
+| :------ | :------ |
+| `this` | *any* |
+| `key` | *string* |
+| `value` | *any* |
+
+**Returns:** *any*
+
+___
+
+### JSONMessageReviver
+
+Ƭ **JSONMessageReviver**: (`this`: *any*, `key`: *string*, `value`: *any*) => *any*
+
+Function for transforming values within a message during JSON parsing
+The values are produced by parsing the incoming raw JSON.
+
+Read more about using it:
+https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#using_the_reviver_parameter
+
+#### Type declaration:
+
+▸ (`this`: *any*, `key`: *string*, `value`: *any*): *any*
+
+#### Parameters:
+
+| Name | Type |
+| :------ | :------ |
+| `this` | *any* |
+| `key` | *string* |
+| `value` | *any* |
+
+**Returns:** *any*
+
+___
+
 ### Message
 
 Ƭ **Message**<T\>: T *extends* [*ConnectionAck*](../enums/common.messagetype.md#connectionack) ? [*ConnectionAckMessage*](../interfaces/common.connectionackmessage.md) : T *extends* [*ConnectionInit*](../enums/common.messagetype.md#connectioninit) ? [*ConnectionInitMessage*](../interfaces/common.connectioninitmessage.md) : T *extends* [*Subscribe*](../enums/common.messagetype.md#subscribe) ? [*SubscribeMessage*](../interfaces/common.subscribemessage.md) : T *extends* [*Next*](../enums/common.messagetype.md#next) ? [*NextMessage*](../interfaces/common.nextmessage.md) : T *extends* [*Error*](../enums/common.messagetype.md#error) ? [*ErrorMessage*](../interfaces/common.errormessage.md) : T *extends* [*Complete*](../enums/common.messagetype.md#complete) ? [*CompleteMessage*](../interfaces/common.completemessage.md) : *never*
@@ -85,7 +139,7 @@ ___
 
 ### parseMessage
 
-▸ **parseMessage**(`data`: *unknown*): [*Message*](common.md#message)
+▸ **parseMessage**(`data`: *unknown*, `reviver?`: [*JSONMessageReviver*](common.md#jsonmessagereviver)): [*Message*](common.md#message)
 
 Parses the raw websocket message data to a valid message.
 
@@ -94,14 +148,15 @@ Parses the raw websocket message data to a valid message.
 | Name | Type |
 | :------ | :------ |
 | `data` | *unknown* |
+| `reviver?` | [*JSONMessageReviver*](common.md#jsonmessagereviver) |
 
 **Returns:** [*Message*](common.md#message)
 
 ___
 
 ### stringifyMessage
 
-▸ **stringifyMessage**<T\>(`msg`: [*Message*](common.md#message)<T\>): *string*
+▸ **stringifyMessage**<T\>(`msg`: [*Message*](common.md#message)<T\>, `replacer?`: [*JSONMessageReplacer*](common.md#jsonmessagereplacer)): *string*
 
 Stringifies a valid message ready to be sent through the socket.
 
@@ -116,5 +171,6 @@ Stringifies a valid message ready to be sent through the socket.
 | Name | Type |
 | :------ | :------ |
 | `msg` | [*Message*](common.md#message)<T\> |
+| `replacer?` | [*JSONMessageReplacer*](common.md#jsonmessagereplacer) |
 
 **Returns:** *string*
diff --git a/src/client.ts b/src/client.ts
@@ -14,6 +14,8 @@ import {
   parseMessage,
   stringifyMessage,
   SubscribePayload,
+  JSONMessageReviver,
+  JSONMessageReplacer,
 } from './common';
 import { isObject } from './utils';
 
@@ -236,6 +238,18 @@ export interface ClientOptions {
    * Reference: https://gist.github.com/jed/982883
    */
   generateID?: () => ID;
+  /**
+   * An optional override for the JSON.parse function used to hydrate
+   * incoming messages to this client. Useful for parsing custom datatypes
+   * out of the incoming JSON.
+   */
+  jsonMessageReviver?: JSONMessageReviver;
+  /**
+   * An optional override for the JSON.stringify function used to serialize
+   * outgoing messages from this client. Useful for serializing custom
+   * datatypes out to the client.
+   */
+  jsonMessageReplacer?: JSONMessageReplacer;
 }
 
 /** @category Client */
@@ -298,6 +312,8 @@ export function createClient(options: ClientOptions): Client {
         return v.toString(16);
       });
     },
+    jsonMessageReplacer: replacer,
+    jsonMessageReviver: reviver,
   } = options;
 
   let ws;
@@ -412,13 +428,16 @@ export function createClient(options: ClientOptions): Client {
           socket.onopen = async () => {
             try {
               socket.send(
-                stringifyMessage<MessageType.ConnectionInit>({
-                  type: MessageType.ConnectionInit,
-                  payload:
-                    typeof connectionParams === 'function'
-                      ? await connectionParams()
-                      : connectionParams,
-                }),
+                stringifyMessage<MessageType.ConnectionInit>(
+                  {
+                    type: MessageType.ConnectionInit,
+                    payload:
+                      typeof connectionParams === 'function'
+                        ? await connectionParams()
+                        : connectionParams,
+                  },
+                  replacer,
+                ),
               );
             } catch (err) {
               socket.close(
@@ -431,7 +450,7 @@ export function createClient(options: ClientOptions): Client {
           let acknowledged = false;
           socket.onmessage = ({ data }) => {
             try {
-              const message = parseMessage(data);
+              const message = parseMessage(data, reviver);
               emitter.emit('message', message);
               if (acknowledged) return; // already connected and acknowledged
 
@@ -600,21 +619,27 @@ export function createClient(options: ClientOptions): Client {
             });
 
             socket.send(
-              stringifyMessage<MessageType.Subscribe>({
-                id,
-                type: MessageType.Subscribe,
-                payload,
-              }),
+              stringifyMessage<MessageType.Subscribe>(
+                {
+                  id,
+                  type: MessageType.Subscribe,
+                  payload,
+                },
+                replacer,
+              ),
             );
 
             releaser = () => {
               if (!done && socket.readyState === WebSocketImpl.OPEN)
                 // if not completed already and socket is open, send complete message to server on release
                 socket.send(
-                  stringifyMessage<MessageType.Complete>({
-                    id,
-                    type: MessageType.Complete,
-                  }),
+                  stringifyMessage<MessageType.Complete>(
+                    {
+                      id,
+                      type: MessageType.Complete,
+                    },
+                    replacer,
+                  ),
                 );
               locks--;
               done = true;

diff --git a/src/common.ts b/src/common.ts
@@ -190,35 +190,61 @@ export function isMessage(val: unknown): val is Message {
   return false;
 }
 
+/**
+ * Function for transforming values within a message during JSON parsing
+ * The values are produced by parsing the incoming raw JSON.
+ *
+ * Read more about using it:
+ * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#using_the_reviver_parameter
+ *
+ * @category Common
+ */
+export type JSONMessageReviver = (this: any, key: string, value: any) => any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
 /**
  * Parses the raw websocket message data to a valid message.
  *
  * @category Common
  */
-export function parseMessage(data: unknown): Message {
+export function parseMessage(
+  data: unknown,
+  reviver?: JSONMessageReviver,
+): Message {
   if (isMessage(data)) {
     return data;
   }
   if (typeof data !== 'string') {
     throw new Error('Message not parsable');
   }
-  const message = JSON.parse(data);
+  const message = JSON.parse(data, reviver);
   if (!isMessage(message)) {
     throw new Error('Invalid message');
   }
   return message;
 }
 
+/**
+ * Function that allows customization of the produced JSON string
+ * for the elements of an outgoing `Message` object.
+ *
+ * Read more about using it:
+ * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#the_replacer_parameter
+ *
+ * @category Common
+ */
+export type JSONMessageReplacer = (this: any, key: string, value: any) => any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
 /**
  * Stringifies a valid message ready to be sent through the socket.
  *
  * @category Common
  */
 export function stringifyMessage<T extends MessageType>(
   msg: Message<T>,
+  replacer?: JSONMessageReplacer,
 ): string {
   if (!isMessage(msg)) {
     throw new Error('Cannot stringify invalid message');
   }
-  return JSON.stringify(msg);
+  return JSON.stringify(msg, replacer);
 }