Read and peek from a readable stream
npm install peek-readable
peek-readable contains one class: StreamReader, which reads from a stream.Readable.
StreamReader is used to read from Node.js stream.Readable.
WebStreamByobReader is used to read from ReadableStreamshell script
npm install --save peek-readable
`
API Documentation
Both StreamReader and WebStreamByobReader implement the IStreamReader interface.
$3
The IStreamReader interface defines the contract for a stream reader,
which provides methods to read and peek data from a stream into a Uint8Array buffer.
The methods are asynchronous and return a promise that resolves with the number of bytes read.
#### Methods
##### peek function
This method allows you to inspect data from the stream without advancing the read pointer.
It reads data into the provided Uint8Array at a specified offset but does not modify the stream's internal position,
allowing you to look ahead in the stream.
`ts
peek(buffer: Uint8Array, offset: number, length: number): Promise
`
Parameters:
- buffer: Uint8Array: The buffer into which the data will be peeked.
This is where the peeked data will be stored.
- maybeBeLess: If true, the buffer maybe partially filled.
Returns Promise:
A promise that resolves with the number of bytes actually peeked into the buffer.
This number may be less than the requested length if the end of the stream is reached.
##### read function
`ts
read(buffer: Uint8Array, offset: number, length: number): Promise
`
Parameters:
- buffer: Uint8Array: The buffer into which the data will be read.
This is where the read data will be stored.
- maybeBeLess: If true, the buffer maybe partially filled.
Returns Promise:
A promise that resolves with the number of bytes actually read into the buffer.
This number may be less than the requested length if the end of the stream is reached.
##### abort function
Abort active asynchronous operation (read or peak) before it has completed.
`ts
abort(): Promise
`
Examples
In the following example we read the first 16 bytes from a stream and store them in our buffer.
Source code of examples can be found here.
`js
import fs from 'node:fs';
import { StreamReader } from 'peek-readable';
(async () => {
const readable = fs.createReadStream('JPEG_example_JPG_RIP_001.jpg');
const streamReader = new StreamReader(readable);
const uint8Array = new Uint8Array(16);
const bytesRead = await streamReader.read(uint8Array);;
// buffer contains 16 bytes, if the end-of-stream has not been reached
})();
`
End-of-stream detection:
`js
(async () => {
const fileReadStream = fs.createReadStream('JPEG_example_JPG_RIP_001.jpg');
const streamReader = new StreamReader(fileReadStream);
const buffer = Buffer.alloc(16); // or use: new Uint8Array(16);
try {
await streamReader.read(buffer);
// buffer contains 16 bytes, if the end-of-stream has not been reached
} catch(error) {
if (error instanceof EndOfStreamError) {
console.log('End-of-stream reached');
}
}
})();
`
With peek you can read ahead:
`js
import fs from 'node:fs';
import { StreamReader } from 'peek-readable';
function closeNodeStream(stream: ReadStream): Promise {
return new Promise((resolve, reject) => {
stream.close(err => {
if(err)
reject(err);
else
resolve();
});
})
}
(async () => {
const fileReadStream = fs.createReadStream('JPEG_example_JPG_RIP_001.jpg');
try {
const streamReader = new StreamReader(fileReadStream);
try {
const buffer = Buffer.alloc(20);
let bytesRead = await streamReader.peek(buffer.subarray(0, 3));
if (bytesRead === 3 && buffer[0] === 0xFF && buffer[1] === 0xD8 && buffer[2] === 0xFF) {
console.log('This is a JPEG file');
} else {
throw Error('Expected a JPEG file');
}
bytesRead = await streamReader.read(buffer); // Read JPEG header
if (bytesRead === 20) {
console.log('Got the JPEG header');
} else {
throw Error('Failed to read JPEG header');
}
} finally {
await streamReader.close(); // Release fileReadStream
}
} finally {
await closeNodeStream(fileReadStream);
}
})();
``