diff --git a/doc/api/fs.md b/doc/api/fs.md index edb6656fad2c41..86c4b0fe6b978b 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -3126,6 +3126,28 @@ system requests but rather the internal buffering `fs.readFile` performs. the call to `fs.readFile()` with the same file descriptor, would give `'World'`, rather than `'Hello World'`. +### Performance Considerations + +The `fs.readFile()` method asynchronously reads the contents of a file into +memory one chunk at a time, allowing the event loop to turn between each chunk. +This allows the read operation to have less impact on other activity that may +be using the underlying libuv thread pool but means that it will take longer +to read a complete file into memory. + +The additional read overhead can vary broadly on different systems and depends +on the type of file being read. If the file type is not a regular file (a pipe +for instance) and Node.js is unable to determine an actual file size, each read +operation will load on 64kb of data. For regular files, each read will process +512kb of data. + +For applications that require as-fast-as-possible reading of file contents, it +is better to use `fs.read()` directly and for application code to manage +reading the full contents of the file itself. + +The Node.js GitHub issue [#25741][] provides more information and a detailed +analysis on the performance of `fs.readFile()` for multiple file sizes in +different Node.js versions. + ## `fs.readFileSync(path[, options])`