feat(streams): new ExactReader

[BlackAsLight]

This pull request adds a new class to @std/streams that takes in a ReadableStream<Uint8Array> and returns a ReadableStreamBYOBReader that guarantees the buffer provided will always be fully filled when it resolves, with the exception of the last value returned.

This class is useful for if you want to consume the stream in changing but exact sizes. Say you want to consume the first byte then the next x bytes, etc.

import { ExactReader } from '@std/streams'
import { assertEquals } from '@std/assert'

const reader = new ExactReader((await Deno.open('./deno.json')).readable)
let x = await reader.read(1)
assertEquals(x.value!.length, 1)
reader.releaseLock()

[codecov]

Codecov Report

Attention: Patch coverage is 90.00000% with 6 lines in your changes missing coverage. Please review.

Project coverage is 96.26%. Comparing base (e07c32f) to head (cd7b013).

Files	Patch %	Lines
streams/exact_reader.ts	90.00%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5492      +/-   ##
==========================================
- Coverage   96.27%   96.26%   -0.01%     
==========================================
  Files         463      464       +1     
  Lines       37660    37720      +60     
  Branches     5556     5568      +12     
==========================================
+ Hits        36257    36311      +54     
- Misses       1361     1367       +6     
  Partials       42       42              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[kt3k]

I feel the same thing can be achieved by using min option of ReadableStreamBYOBReader.read

ref: denoland/deno#20849 and whatwg/streams#1145

const readable = (await Deno.open('./deno.json')).readable
const reader = readable.getReader({ mode: "byob" });
const u8 = new Uint8Array(1024);
const result = await reader.read(u8, { min: 1024 });
console.log(result.value.length)

[BlackAsLight]

I did not even know this was a thing. I can't find any info on a second argument for the read method on MDN

[BlackAsLight]

The MDN docs makes no mention of the second argument: https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader/read

But looking at the spec it lists, it does show a min argument: https://streams.spec.whatwg.org/#ref-for-byob-reader-read%E2%91%A2