Is createreadstream asynchronous?

Question

https://nodejs.org/api/fs.html#fs_fs_createreadstream_path_options . I also have a general question .

Can I assume that unless otherwise stated in the documentation , any function mentioned is asynchronous?

Answer 1

Is createreadstream asynchronous?

Yes and no. This question is really more a matter of semantics than anything because it hides an asynchronous operation under a synchronous looking interface. fs.createReadStream() appears to have a synchronous interface. It does not return a promise or accept a callback to communicate back when it's done or to send back some results. So, it appears synchronous from the interface. And, we know from using it that there's nothing you have to wait for in order to start using the stream. So, you use it as if it was a synchronous interface.

Here's the signature for fs.createReadStream():

fs.createReadStream(path[, options])

And, in the options object, there is no callback option and no mention of a returned promise. This is not a typical asynchronous interface.

---

On the other hand if you look at the signature of fs.rename():

fs.rename(oldPath, newPath, callback)

You see that it takes a callback that is referred to in the doc as the "completion callback". This function is clearly asynchronous.

---

But, fs.createReadStream() does open a file and it opens that file asynchronously without blocking.

If you're wondering how fs.createReadStream() can be synchronous when it has to open a file asynchronously, that's because fs.createReadStream() has not yet opened the file when it returns.

In normal use of the stream, you can just start reading from the stream immediately. But, internally to the stream, if the file is not yet opened, it will wait until the file is done being opened before actually attempting to read from it. So, the process of opening the file is being hidden from the user of the stream (which is generally a good thing).

If you wanted to know when the file as actually done being opened, there is an open event on the stream. And, if there's an error opening the file, there will be an error event on the stream. So, if you want to get technical, you can say that fs.readStream() actually is an asynchronous operation and completion of the async operation is communicated via the open or error events.

let rstream = fs.createReadStream("temp.txt");
rstream.on('open', (fd) => {
    // file opened now
});
rstream.on('error', (err) => {
    // error on the stream
});

But, in normal usage of fs.createReadStream(), the programmer does not have to monitor the file open event because it is hidden from the user and handled automatically when the stream is read from next. When you create a read stream and immediately ask to read from it (which is an asynchronous interface), internally the stream object waits for the file to finish opening, then reads some bytes form it, waits for the file read to finish and then notifies completion of the read operation. So, they just combine the file open completion with the first read, saving the programmer an extra step of waiting for the file open to finish before issuing their first read operation.

So, technically fs.createReadStream() is an asynchronous operation that has completion events. But, because of the way it's been combined with reading from the file, you don't generally have to use it like it's asynchronous because it's asynchronous behavior is combined with the async reading from the file.