peek-readable

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 WebStreamByobReader 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 a modern browser or Node.js ≥ 18 engine.

For TypeScript CommonJs backward compatibility, you can use load-esm.

Usage

Installation

npm install --save peek-readable

API Documentation

Both StreamReader and WebStreamByobReader 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(buffer: Uint8Array, offset: number, length: number): Promise<number>

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<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:

• 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<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);;
  // 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);
    // 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';

function closeNodeStream(stream: ReadStream): Promise<void> {
  return new Promise<void>((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);
  }


})();

Licence

This project is licensed under the MIT License. Feel free to use, modify, and distribute as needed.

Similar packages

Other packages similar to peek-readable

buffer-peek-stream

Similar to peek-readable, buffer-peek-stream allows peeking into streams without consuming the data. It compares by offering a similar API but is specifically tailored for Node.js streams, potentially offering optimizations for stream handling.