peek-readable - npm Package Compare versions

Comparing version 5.1.4 to 5.2.0

lib/AbstractStreamReader.d.ts

 export interface IStreamReader {
+    /**
+     * Peak ahead (peek) from stream. Subsequent read or peeks will return the same data.
+     * @param uint8Array - Uint8Array (or Buffer) to store data read from stream in
+     * @param offset - Offset target
+     * @param length - Number of bytes to read
+     * @returns Number of bytes peeked
+     */
     peek(uint8Array: Uint8Array, offset: number, length: number): Promise<number>;
-    read(buffer: Uint8Array, offset: number, length: number): Promise<number>;
+    /**
+     * Read from stream the stream.
+     * @param uint8Array - Uint8Array (or Buffer) to store data read from stream in
+     * @param offset - Offset target
+     * @param length - Number of bytes to read
+     * @returns Number of bytes peeked
+     */
+    read(uint8Array: Uint8Array, offset: number, length: number): Promise<number>;
+    /**
+     * Abort active asynchronous operation before it has completed.
+     */
+    abort(): Promise<void>;
 }
@@ -16,9 +34,2 @@ export declare abstract class AbstractStreamReader implements IStreamReader {
     protected peekQueue: Uint8Array[];
-    /**
-     * Read ahead (peek) from stream. Subsequent read or peeks will return the same data
-     * @param uint8Array - Uint8Array (or Buffer) to store data read from stream in
-     * @param offset - Offset target
-     * @param length - Number of bytes to read
-     * @returns Number of bytes peeked
-     */
     peek(uint8Array: Uint8Array, offset: number, length: number): Promise<number>;
@@ -36,2 +47,3 @@ read(buffer: Uint8Array, offset: number, length: number): Promise<number>;
     protected abstract readFromStream(buffer: Uint8Array, offset: number, length: number): Promise<number>;
+    abstract abort(): Promise<void>;
 }

lib/AbstractStreamReader.js

@@ -15,9 +15,2 @@ import { EndOfStreamError } from "./EndOfStreamError.js";
     }
-    /**
-     * Read ahead (peek) from stream. Subsequent read or peeks will return the same data
-     * @param uint8Array - Uint8Array (or Buffer) to store data read from stream in
-     * @param offset - Offset target
-     * @param length - Number of bytes to read
-     * @returns Number of bytes peeked
-     */
     async peek(uint8Array, offset, length) {
@@ -24,0 +17,0 @@ const bytesRead = await this.read(uint8Array, offset, length);

lib/StreamReader.d.ts

@@ -29,2 +29,3 @@ import type { Readable } from 'node:stream';
     private reject;
+    abort(): Promise<void>;
 }

lib/StreamReader.js

@@ -76,2 +76,5 @@ import { EndOfStreamError } from './EndOfStreamError.js';
     }
+    async abort() {
+        this.s.destroy();
+    }
 }

lib/WebStreamReader.d.ts

@@ -11,4 +11,6 @@ import type { ReadableStream as NodeReadableStream } from 'node:stream/web';
     private reader;
+    private abortController;
     constructor(stream: AnyWebByteStream);
     protected readFromStream(buffer: Uint8Array, offset: number, length: number): Promise<number>;
+    abort(): Promise<void>;
 }

lib/WebStreamReader.js

@@ -11,2 +11,3 @@ import { EndOfStreamError } from './EndOfStreamError.js';
         super();
+        this.abortController = new AbortController();
         this.reader = stream.getReader({ mode: 'byob' });
@@ -28,2 +29,5 @@ }
     }
+    abort() {
+        return this.reader.cancel();
+    }
 }

package.json

 {
   "name": "peek-readable",
-  "version": "5.1.4",
+  "version": "5.2.0",
   "description": "Read and peek from a readable stream",
@@ -14,3 +14,3 @@ "author": {
   "scripts": {
-    "clean": "'del-cli' 'lib/**/*.js' 'lib/**/*.js.map' 'lib/**/*.d.ts' 'test/**/*.js' 'test/**/*.js.map' 'coverage' '.nyc_output'",
+    "clean": "del-cli 'lib/**/*.js' 'lib/**/*.js.map' 'lib/**/*.d.ts' 'test/**/*.js' 'test/**/*.js.map' 'coverage' '.nyc_output'",
     "build": "npm run clean && npm run compile",
@@ -47,3 +47,4 @@ "compile-src": "tsc -p lib",
     "@biomejs/biome": "1.8.3",
-    "@types/chai": "^4.3.17",
+    "@types/chai": "^4.3.19",
+    "@types/chai-as-promised": "^8.0.0",
     "@types/mocha": "^10.0.7",
@@ -53,2 +54,3 @@ "@types/node": "^22.1.0",
     "chai": "^5.1.1",
+    "chai-as-promised": "^8.0.0",
     "del-cli": "^5.1.0",
@@ -55,0 +57,0 @@ "mocha": "^10.7.0",

README.md

@@ -12,6 +12,17 @@ [![Node.js CI](https://github.com/Borewit/peek-readable/actions/workflows/nodejs-ci.yml/badge.svg?branch=master)](https://github.com/Borewit/peek-readable/actions/workflows/nodejs-ci.yml)
 
-Allows to read and peek from a [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams) 
+Allows to read and peek from a [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams)
 
-Note that [peek-readable](https://github.com/Borewit/peek-readable) was formally released as [then-read-stream](https://github.com/Borewit/peek-readable).
+This module is used by [strtok3](https://github.com/Borewit/strtok3)
 
+The `peek-readable` contains one class: `StreamReader`, which reads from a [stream.Readable](https://nodejs.org/api/stream.html#stream_class_stream_readable).
+
+- Class `StreamReader` is used to read from Node.js [stream.Readable](https://nodejs.org/api/stream.html#stream_class_stream_readable).
+- Class `WebStreamReader` is used to read from [ReadableStream<Uint8Array>](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
+
+## Compatibility
+
+Module: version 5 migrated from [CommonJS](https://en.wikipedia.org/wiki/CommonJS) to [pure ECMAScript Module (ESM)](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+JavaScript is compliant with [ECMAScript 2019 (ES10)](https://en.wikipedia.org/wiki/ECMAScript#10th_Edition_%E2%80%93_ECMAScript_2019).
+Requires Node.js ≥ 14.16 engine.
+
 ## Usage
@@ -25,10 +36,56 @@
 
-The `peek-readable` contains one class: `StreamReader`, which reads from a [stream.Readable](https://nodejs.org/api/stream.html#stream_class_stream_readable).
+## API Documentation
 
-### Compatibility
+Both `StreamReader` and `WebStreamReader` implement the [IStreamReader interface](#istreamreader-interface).
 
-Module: version 5 migrated from [CommonJS](https://en.wikipedia.org/wiki/CommonJS) to [pure ECMAScript Module (ESM)](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
-JavaScript is compliant with [ECMAScript 2019 (ES10)](https://en.wikipedia.org/wiki/ECMAScript#10th_Edition_%E2%80%93_ECMAScript_2019).
-Requires Node.js ≥ 14.16 engine.
+### `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.
+
+```ts  
+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
+```ts  
+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.
+
+```ts  
+abort(): Promise<void>
+```
+
 ## Examples
@@ -71,3 +128,3 @@
 
-With peek you can read ahead:
+With `peek` you can read ahead:
 ```js
@@ -74,0 +131,0 @@ import fs from 'node:fs';

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

20628

increased by16.36%

Lines of code

312

increased by5.05%

Number of lines in readme file

151

increased by60.64%

Worsened metrics

Dev dependency count

15

increased by15.38%

No dependency changes