doc: note caveats in process message serialization

The message sent using process.send() goes through JSON
serialization and parsing, which could lead to surprising behaviors.
This commit elaborate a bit more on this and add a link to
the notes about these caveats in the ECMAScript specification.

PR-URL: nodejs/node#12963
Refs: nodejs/node#12497
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Vse Mozhet Byt <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>

doc/api/child_process.md

@@ -891,6 +891,10 @@ added: v0.5.9
 The `'message'` event is triggered when a child process uses [`process.send()`][]
 to send messages.
 
+*Note*: The message goes through JSON serialization and parsing. The resulting
+message might not be the same as what is originally sent. See notes in
+[the `JSON.stringify()` specification][`JSON.stringify` spec].
+
 ### subprocess.channel
 <!-- YAML
 added: v7.1.0
@@ -1050,6 +1054,10 @@ be used to send messages to the child process. When the child process is a
 Node.js instance, these messages can be received via the
 [`process.on('message')`][] event.
 
+*Note*: The message goes through JSON serialization and parsing. The resulting
+message might not be the same as what is originally sent. See notes in
+[the `JSON.stringify()` specification][`JSON.stringify` spec].
+
 For example, in the parent script:
 
 ```js
@@ -1060,6 +1068,7 @@ n.on('message', (m) => {
   console.log('PARENT got message:', m);
 });
 
+// Causes the child to print: CHILD got message: { hello: 'world' }
 n.send({ hello: 'world' });
 ```
 
@@ -1070,7 +1079,8 @@ process.on('message', (m) => {
   console.log('CHILD got message:', m);
 });
 
-process.send({ foo: 'bar' });
+// Causes the parent to print: PARENT got message: { foo: 'bar', baz: null }
+process.send({ foo: 'bar', baz: NaN });
 ```
 
 Child Node.js processes will have a [`process.send()`][] method of their own that
@@ -1201,9 +1211,6 @@ It is also recommended that any `'message'` handlers in the child process
 verify that `socket` exists, as the connection may have been closed during the
 time it takes to send the connection to the child.
 
-*Note*: This function uses [`JSON.stringify()`][] internally to serialize the
-`message`.
-
 ### subprocess.stderr
 <!-- YAML
 added: v0.1.90
@@ -1319,6 +1326,7 @@ unavailable.
 [`ChildProcess`]: #child_process_child_process
 [`Error`]: errors.html#errors_class_error
 [`EventEmitter`]: events.html#events_class_eventemitter
+[`JSON.stringify` spec]: https://tc39.github.io/ecma262/#sec-json.stringify
 [`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
 [`subprocess.connected`]: #child_process_subprocess_connected
 [`subprocess.disconnect()`]: #child_process_subprocess_disconnect

doc/api/process.md

@@ -90,10 +90,13 @@ message sent by a parent process using [`childprocess.send()`][] is received by
 the child process.
 
 The listener callback is invoked with the following arguments:
-* `message` {Object} a parsed JSON object or primitive value
+* `message` {Object} a parsed JSON object or primitive value.
 * `sendHandle` {Handle object} a [`net.Socket`][] or [`net.Server`][] object, or
   undefined.
 
+*Note*: The message goes through JSON serialization and parsing. The resulting
+message might not be the same as what is originally sent. See notes in
+[the `JSON.stringify()` specification][`JSON.stringify` spec].
 
 ### Event: 'rejectionHandled'
 <!-- YAML
@@ -1472,8 +1475,9 @@ used to send messages to the parent process. Messages will be received as a
 If Node.js was not spawned with an IPC channel, `process.send()` will be
 `undefined`.
 
-*Note*: This function uses [`JSON.stringify()`][] internally to serialize the
-`message`.
+*Note*: The message goes through JSON serialization and parsing. The resulting
+message might not be the same as what is originally sent. See notes in
+[the `JSON.stringify()` specification][`JSON.stringify` spec].
 
 ## process.setegid(id)
 <!-- YAML
@@ -1877,6 +1881,7 @@ cases:
 [`ChildProcess`]: child_process.html#child_process_class_childprocess
 [`Error`]: errors.html#errors_class_error
 [`EventEmitter`]: events.html#events_class_eventemitter
+[`JSON.stringify` spec]: https://tc39.github.io/ecma262/#sec-json.stringify
 [`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
 [`console.error()`]: console.html#console_console_error_data_args
 [`console.log()`]: console.html#console_console_log_data_args