fs: add FileHandle.prototype.readLines

PR-URL: nodejs#42590
Reviewed-By: LiviaMedeiros <[email protected]>

doc/api/fs.md

@@ -517,6 +517,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
@@ -7672,6 +7712,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

lib/internal/fs/promises.js

@@ -103,6 +103,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');
@@ -184,6 +185,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);
   }

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',

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();
+}