peek-readable

What is peek-readable?

The peek-readable npm package provides utilities for reading from streams and buffers without consuming the data, allowing you to 'peek' at the data before deciding how to process it. This is particularly useful in scenarios where the type of processing depends on the content of the data itself.

What are peek-readable's main functionalities?

Peeking data from a stream

This feature allows you to peek at the first few bytes of a stream to determine its content without consuming those bytes, enabling further processing based on the peeked data.

const {ReadableStreamPeeker} = require('peek-readable');
const fs = require('fs');

const stream = fs.createReadStream('example.txt');
const peeker = new ReadableStreamPeeker(stream);

peeker.peek(10).then(buffer => {
  console.log('Peeked data:', buffer.toString());
});

Peeking data from a buffer

This feature enables peeking at data within a buffer, which can be useful for preliminary checks before processing the entire buffer.

const {BufferPeeker} = require('peek-readable');

const buffer = Buffer.from('Hello, world!');
const peeker = new BufferPeeker(buffer);

const peekedData = peeker.peek(5);
console.log('Peeked data:', peekedData.toString());

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.

README

peek-readable

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

Allows to read and peek from a Readable Stream

Note that peek-readable was formally released as then-read-stream.

Usage

Installation

npm install --save peek-readable

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

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.

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');
  }
})();