Incremental file processing
Process large files without loading their complete contents into memory.
Node.js · Function
createReadStream
Creates a readable stream for a file, allowing data to be consumed incrementally. Options can select encoding, byte ranges, buffering, and file-descriptor behavior.
- Since
- v0.1.31
How it works
createReadStream() constructs a readable file stream rather than loading the whole file at once. The path identifies the file unless an existing file descriptor is supplied; options control flags, encoding, descriptor ownership, permissions, byte bounds, and buffering.
Syntax
fs.createReadStream(path[, options])Parameters
| Name | Type | Description |
|---|---|---|
path | string | Buffer | URL | integer | File path, URL, or file descriptor source used to open the stream. |
options | string | Object | Optional configuration including flags, encoding, fd, mode, autoClose, start, end, and highWaterMark. |
Returns
A new fs.ReadStream object.
Key points
- The API was introduced in Node.js v0.1.31.
- The function creates and returns a readable stream for the file.
- Use start and end to stream a selected byte range rather than the complete file.
- An existing descriptor without a start position continues from its current offset.
Common mistakes
- When using byte ranges, both boundaries are included and indexing begins at zero.
- Supplying fd makes the path ineffective, so ensure the descriptor refers to the intended file.
- Disabling automatic closure transfers responsibility for closing the descriptor to your code.
Example: Read a file incrementally
import { createReadStream } from 'node:fs';
const stream = createReadStream('package.json', { encoding: 'utf8' });
for await (const chunk of stream) {
process.stdout.write(chunk);
}Reads package.json incrementally as UTF-8 text and writes each chunk to standard output.
When to use it
Streaming file delivery
Serve downloads or other response bodies while data arrives in chunks.
Partial byte-range reads
Inspect or transform only a selected region of a file.
Interview questions
QWhat does createReadStream() return and why use it?
It returns a ReadStream that exposes file data through Node.js readable-stream behavior. Data can be consumed incrementally, avoiding the need to buffer the entire file in memory.
Follow-up: How would you read only a byte interval? Pass start and end in the options object; the endpoints are inclusive and zero-based.
QWhat are the main inputs to createReadStream()?
The path identifies the file, while options can configure flags, encoding, an existing file descriptor, mode, automatic closure, byte range, and highWaterMark. If fd is supplied, the stream uses that descriptor instead of opening path.
Follow-up: What happens to the open event with an existing descriptor? The documentation states that no open event is emitted when fd is specified.
QHow do byte ranges and file descriptors affect reading?
The default range reads the file as a stream, and start/end restrict reading to an inclusive byte range. With an existing fd and no start, reading proceeds from the descriptor's current position.
Follow-up: What should be considered when setting autoClose to false? The caller must arrange descriptor cleanup, including after errors.
Related
fs.ReadStreamfs.createWriteStreamfs.openstream.Readable