peek-readable

A promise based asynchronous stream reader, which makes reading from a stream easy.

Allows to read and peek from a Readable Stream

This module is used by strtok3

The peek-readable contains one class: StreamReader, which reads from a stream.Readable.

Class StreamReader is used to read from Node.js stream.Readable.
Class WebStreamReader is used to read from ReadableStream

Compatibility

Module: version 5 migrated from CommonJS to pure ECMAScript Module (ESM). JavaScript is compliant with ECMAScript 2019 (ES10). Requires Node.js ≥ 14.16 engine.

Usage

Installation

npm install --save peek-readable

API Documentation

Both StreamReader and WebStreamReader implement the IStreamReader interface.

`IStreamReader` Interface

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.

peek(uint8Array: Uint8Array, offset: number, length: number): Promise<number>

Parameters:

uint8Array: Uint8Array: The buffer into which the data will be peeked. This is where the peeked data will be stored.
offset: number: The offset in the Uint8Array where the peeked data should start being written.
length: number: The number of bytes to peek from the stream.

Returns Promise<number>: 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

read(buffer: Uint8Array, offset: number, length: number): Promise<number>

Parameters:

uint8Array: Uint8Array: The buffer into which the data will be read. This is where the read data will be stored.
offset: number: The offset in the Uint8Array where the read data should start being written.
length: number: The number of bytes to read from the stream.

Returns Promise<number>: 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.

abort(): Promise<void>

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.

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, 0, 16);;
  // buffer contains 16 bytes, if the end-of-stream has not been reached
})();

End-of-stream detection:

(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, 0, 16);
    // 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:

import fs from 'node:fs';
import { StreamReader } from 'peek-readable';

const fileReadStream = fs.createReadStream('JPEG_example_JPG_RIP_001.jpg');
const streamReader = new StreamReader(fileReadStream);
const buffer = Buffer.alloc(20);

(async () => {
  let bytesRead = await streamReader.peek(buffer, 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, 0, 20); // Read JPEG header
  if (bytesRead === 20) {
    console.log('Got the JPEG header');
  } else {
    throw Error('Failed to read JPEG header');
  }
})();

Borewit/peek-readable