From 11d1c23fa03bfcb351caae715715bc30e01cdb59 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sun, 9 Oct 2022 19:16:40 -0500
Subject: [PATCH] fs: add `FileHandle.prototype.readLines`

PR-URL: https://github.com/nodejs/node/pull/42590
Reviewed-By: LiviaMedeiros <livia@cirno.name>
---
 doc/api/fs.md                                 | 41 +++++++++++++++++++
 lib/internal/fs/promises.js                   |  8 ++++
 test/parallel/test-bootstrap-modules.js       |  3 ++
 ...test-fs-promises-file-handle-readLines.mjs | 40 ++++++++++++++++++
 4 files changed, 92 insertions(+)
 create mode 100644 test/parallel/test-fs-promises-file-handle-readLines.mjs

diff --git a/doc/api/fs.md b/doc/api/fs.md
index b9d1f018450b6d..3e5ff52986163a 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -515,6 +515,46 @@ If one or more `filehandle.read()` calls are made on a file handle and then a
 position till the end of the file. It doesn't always read from the beginning
 of the file.
 
+#### `filehandle.readLines([options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `options` {Object}
+  * `encoding` {string} **Default:** `null`
+  * `autoClose` {boolean} **Default:** `true`
+  * `emitClose` {boolean} **Default:** `true`
+  * `start` {integer}
+  * `end` {integer} **Default:** `Infinity`
+  * `highWaterMark` {integer} **Default:** `64 * 1024`
+* Returns: {readline.InterfaceConstructor}
+
+Convenience method to create a `readline` interface and stream over the file.
+See [`filehandle.createReadStream()`][] for the options.
+
+```mjs
+import { open } from 'node:fs/promises';
+
+const file = await open('./some/file/to/read');
+
+for await (const line of file.readLines()) {
+  console.log(line);
+}
+```
+
+```cjs
+const { open } = require('node:fs/promises');
+
+(async () => {
+  const file = await open('./some/file/to/read');
+
+  for await (const line of file.readLines()) {
+    console.log(line);
+  }
+})();
+```
+
 #### `filehandle.readv(buffers[, position])`
 
 <!-- YAML
@@ -7635,6 +7675,7 @@ the file contents.
 [`ReadDirectoryChangesW`]: https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-readdirectorychangesw
 [`UV_THREADPOOL_SIZE`]: cli.md#uv_threadpool_sizesize
 [`event ports`]: https://illumos.org/man/port_create
+[`filehandle.createReadStream()`]: #filehandlecreatereadstreamoptions
 [`filehandle.createWriteStream()`]: #filehandlecreatewritestreamoptions
 [`filehandle.writeFile()`]: #filehandlewritefiledata-options
 [`fs.access()`]: #fsaccesspath-mode-callback
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 187eefe66098d2..eca3dc8adfae3b 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -102,6 +102,7 @@ const kUnref = Symbol('kUnref');
 const kLocked = Symbol('kLocked');
 
 const { kUsePromises } = binding;
+const { Interface } = require('internal/readline/interface');
 const {
   JSTransferable, kDeserialize, kTransfer, kTransferList
 } = require('internal/worker/js_transferable');
@@ -181,6 +182,13 @@ class FileHandle extends EventEmitterMixin(JSTransferable) {
     return fsCall(readFile, this, options);
   }
 
+  readLines(options = undefined) {
+    return new Interface({
+      input: this.createReadStream(options),
+      crlfDelay: Infinity,
+    });
+  }
+
   stat(options) {
     return fsCall(fstat, this, options);
   }
diff --git a/test/parallel/test-bootstrap-modules.js b/test/parallel/test-bootstrap-modules.js
index fecdd2902acc14..7f241bafc9cffd 100644
--- a/test/parallel/test-bootstrap-modules.js
+++ b/test/parallel/test-bootstrap-modules.js
@@ -114,6 +114,9 @@ const expectedModules = new Set([
   'NativeModule internal/process/warning',
   'NativeModule internal/promise_hooks',
   'NativeModule internal/querystring',
+  'NativeModule internal/readline/callbacks',
+  'NativeModule internal/readline/interface',
+  'NativeModule internal/readline/utils',
   'NativeModule internal/socketaddress',
   'NativeModule internal/source_map/source_map_cache',
   'NativeModule internal/stream_base_commons',
diff --git a/test/parallel/test-fs-promises-file-handle-readLines.mjs b/test/parallel/test-fs-promises-file-handle-readLines.mjs
new file mode 100644
index 00000000000000..f6bcd147f8cf31
--- /dev/null
+++ b/test/parallel/test-fs-promises-file-handle-readLines.mjs
@@ -0,0 +1,40 @@
+import '../common/index.mjs';
+import tmpdir from '../common/tmpdir.js';
+
+import assert from 'node:assert';
+import { open, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+tmpdir.refresh();
+
+const filePath = path.join(tmpdir.path, 'file.txt');
+
+await writeFile(filePath, '1\n\n2\n');
+
+let file;
+try {
+  file = await open(filePath);
+
+  let i = 0;
+  for await (const line of file.readLines()) {
+    switch (i++) {
+      case 0:
+        assert.strictEqual(line, '1');
+        break;
+
+      case 1:
+        assert.strictEqual(line, '');
+        break;
+
+      case 2:
+        assert.strictEqual(line, '2');
+        break;
+
+      default:
+        assert.fail();
+        break;
+    }
+  }
+} finally {
+  await file?.close();
+}