doc: add caveat and tradeoff example to readline

vsemozhetbyt · BethGriggs · commit 40657859ca52 · 2019-04-16T22:55:16.000+01:00
PR-URL: #26472 Refs: #23916 Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
diff --git a/doc/api/readline.md b/doc/api/readline.md
@@ -534,6 +534,34 @@ rl.on('line', (line) => {
 });
 ```
 
+Currently, `for`-`await`-`of` loop can be a bit slower. If `async` / `await`
+flow and speed are both essential, a mixed approach can be applied:
+
+```js
+const { once } = require('events');
+const { createReadStream } = require('fs');
+const { createInterface } = require('readline');
+
+(async function processLineByLine() {
+  try {
+    const rl = createInterface({
+      input: createReadStream('big-file.txt'),
+      crlfDelay: Infinity
+    });
+
+    rl.on('line', (line) => {
+      // Process the line.
+    });
+
+    await once(rl, 'close');
+
+    console.log('File processed.');
+  } catch (err) {
+    console.error(err);
+  }
+})();
+```
+
 [`'SIGCONT'`]: readline.html#readline_event_sigcont
 [`'SIGTSTP'`]: readline.html#readline_event_sigtstp
 [`process.stdin`]: process.html#process_process_stdin
