From 40657859ca52874abd9ca15e0d0e5569fd63e565 Mon Sep 17 00:00:00 2001
From: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Date: Wed, 6 Mar 2019 16:58:53 +0200
Subject: [PATCH] doc: add caveat and tradeoff example to readline

PR-URL: https://github.com/nodejs/node/pull/26472
Refs: https://github.com/nodejs/node/pull/23916
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
---
 doc/api/readline.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/doc/api/readline.md b/doc/api/readline.md
index 3d00e4ec64351d..7250588f943f24 100644
--- 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