feat: add jsonStrings option (#2642)

* feat: Add jsonStrings configuration

* feat: Add jsonStrings typings

* feat: Add jsonStrings to binary_parser

* feat: add comments

* feat: add documentation to known incompatibilities section

---------

Co-authored-by: ruben.morim <ruben.morim@sovos.com>

lib/connection_config.js

@@ -65,7 +65,8 @@ const validOptions = {
   idleTimeout: 1,
   Promise: 1,
   queueLimit: 1,
-  waitForConnections: 1
+  waitForConnections: 1,
+  jsonStrings: 1
 };
 
 class ConnectionConfig {
@@ -180,6 +181,7 @@ class ConnectionConfig {
     };
     this.connectAttributes = { ...defaultConnectAttributes, ...(options.connectAttributes || {})};
     this.maxPreparedStatements = options.maxPreparedStatements || 16000;
+    this.jsonStrings = options.jsonStrings || false;
   }
 
   static mergeFlags(default_flags, user_flags) {

lib/parsers/binary_parser.js

@@ -59,7 +59,7 @@ function readCodeFor(field, config, options, fieldNum) {
       // Since for JSON columns mysql always returns charset 63 (BINARY),
       // we have to handle it according to JSON specs and use "utf8",
       // see https://github.com/sidorares/node-mysql2/issues/409
-      return 'JSON.parse(packet.readLengthCodedString("utf8"));';
+      return config.jsonStrings ? 'packet.readLengthCodedString("utf8")' : 'JSON.parse(packet.readLengthCodedString("utf8"));';
     case Types.LONGLONG:
       if (!supportBigNumbers) {
         return unsigned

lib/parsers/text_parser.js

@@ -63,7 +63,7 @@ function readCodeFor(type, charset, encodingExpr, config, options) {
       // Since for JSON columns mysql always returns charset 63 (BINARY),
       // we have to handle it according to JSON specs and use "utf8",
       // see https://github.com/sidorares/node-mysql2/issues/409
-      return 'JSON.parse(packet.readLengthCodedString("utf8"))';
+      return config.jsonStrings ? 'packet.readLengthCodedString("utf8")' : 'JSON.parse(packet.readLengthCodedString("utf8"))';
     default:
       if (charset === Charsets.BINARY) {
         return 'packet.readLengthCodedBuffer()';

typings/mysql/lib/Connection.d.ts

@@ -326,6 +326,13 @@ export interface ConnectionOptions {
   authPlugins?: {
     [key: string]: AuthPlugin;
   };
+
+  /**
+   * Force JSON to be returned as string
+   *
+   * (Default: false)
+   */
+  jsonStrings?: boolean;
 }
 
 declare class Connection extends QueryableBase(ExecutableBase(EventEmitter)) {

website/docs/documentation/00-index.mdx

@@ -54,6 +54,14 @@ Please check these [examples](/docs/examples) for **MySQL2**.
 This option could lose precision on the number as Javascript Number is a Float!
 :::
 
+- By default, the `JSON` type is always returned parsed into an object. However, you can modify this behavior by specifying the following configuration:
+
+```js
+{
+  jsonStrings: true,
+}
+```
+
 <hr />
 
 ## Other Resources