fs: add FileHandle.prototype.readLines

aduh95 · aduh95 · commit 8940ae2e8f6b · 2022-04-29T17:55:10.000+02:00
diff --git a/doc/api/fs.md b/doc/api/fs.md
@@ -488,6 +488,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: [`readlinePromises.Interface`][]
+
+Convenient alias 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
@@ -7493,6 +7533,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
@@ -7539,6 +7580,7 @@ the file contents.
 [`fsPromises.utimes()`]: #fspromisesutimespath-atime-mtime
 [`inotify(7)`]: https://man7.org/linux/man-pages/man7/inotify.7.html
 [`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
+[`readlinePromises.Interface`]: readline.md#class-readlinepromisesinterface
 [`util.promisify()`]: util.md#utilpromisifyoriginal
 [bigints]: https://tc39.github.io/proposal-bigint
 [caveats]: #caveats
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
@@ -96,6 +96,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');
@@ -175,6 +176,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
@@ -111,6 +111,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
@@ -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();
+}
