Deno/std
1
0
Fork 0
mirror of https://github.com/denoland/std.git synced 2024-11-21 20:50:22 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

docs(streams): address documentation issues (#5480)

Browse Source
This commit is contained in:
Asher Gomez 2024-07-19 09:05:16 +10:00 committed by GitHub
parent fd3e286d10
commit 350544e370
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 118 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
streams/limited_bytes_transform_stream.ts
View File

@ -73,7 +73,11 @@ export interface LimitedBytesTransformStreamOptions {
* );
* ```
*
* @example error: true
* @example Throw error when the total byte length of the chunks exceeds the
* specified size
*
* To do so, set `options.error` to `true`.
*
* ```ts
* import { LimitedBytesTransformStream } from "@std/streams/limited-bytes-transform-stream";
* import { assertRejects } from "@std/assert";
@ -98,18 +102,75 @@ export class LimitedBytesTransformStream
* @param size A size limit in bytes.
* @param options Options for the stream.
*
* @example size = 42
* ```ts no-assert
* @example `size` is equal to the total byte length of the chunks
* ```ts
* import { LimitedBytesTransformStream } from "@std/streams/limited-bytes-transform-stream";
* import { assertEquals } from "@std/assert";
*
* const limitedBytesTransformStream = new LimitedBytesTransformStream(42);
* const stream = ReadableStream.from(["1234", "5678"]);
* const transformed = stream.pipeThrough(new TextEncoderStream()).pipeThrough(
* new LimitedBytesTransformStream(8),
* ).pipeThrough(new TextDecoderStream());
*
* assertEquals(
* await Array.fromAsync(transformed),
* ["1234", "5678"],
* );
* ```
*
* @example size = 42, error = true
* ```ts no-assert
* @example `size` is less than the total byte length of the chunks, and at the
* boundary of the chunks
* ```ts
* import { LimitedBytesTransformStream } from "@std/streams/limited-bytes-transform-stream";
* import { assertEquals } from "@std/assert";
*
* const limitedBytesTransformStream = new LimitedBytesTransformStream(42, { error: true });
* const stream = ReadableStream.from(["1234", "5678"]);
* const transformed = stream.pipeThrough(new TextEncoderStream()).pipeThrough(
* // `4` is the boundary of the chunks
* new LimitedBytesTransformStream(4),
* ).pipeThrough(new TextDecoderStream());
*
* assertEquals(
* await Array.fromAsync(transformed),
* // The first chunk was read, but the second chunk was not
* ["1234"],
* );
* ```
*
* @example `size` is less than the total byte length of the chunks, and not at
* the boundary of the chunks
* ```ts
* import { LimitedBytesTransformStream } from "@std/streams/limited-bytes-transform-stream";
* import { assertEquals } from "@std/assert";
*
* const stream = ReadableStream.from(["1234", "5678"]);
* const transformed = stream.pipeThrough(new TextEncoderStream()).pipeThrough(
* // `5` is not the boundary of the chunks
* new LimitedBytesTransformStream(5),
* ).pipeThrough(new TextDecoderStream());
*
* assertEquals(
* await Array.fromAsync(transformed),
* // The second chunk was not read because it would exceed the specified size
* ["1234"],
* );
* ```
*
* @example Throw error when the total byte length of the chunks exceeds the
* specified size
*
* ```ts
* import { LimitedBytesTransformStream } from "@std/streams/limited-bytes-transform-stream";
* import { assertRejects } from "@std/assert";
*
* const stream = ReadableStream.from(["1234", "5678"]);
* const transformed = stream.pipeThrough(new TextEncoderStream()).pipeThrough(
* new LimitedBytesTransformStream(5, { error: true }),
* ).pipeThrough(new TextDecoderStream());
*
* await assertRejects(async () => {
* await Array.fromAsync(transformed);
* }, RangeError);
* ```
*/
constructor(

57
streams/limited_transform_stream.ts
View File

@ -56,7 +56,11 @@ export interface LimitedTransformStreamOptions {
* );
* ```
*
* @example error: true
* @example Throw a {@linkcode RangeError} when the total number of chunks is
* about to exceed the specified limit
*
* Do this by setting `options.error` to `true`.
*
* ```ts
* import { LimitedTransformStream } from "@std/streams/limited-transform-stream";
* import { assertRejects } from "@std/assert";
@ -80,18 +84,57 @@ export class LimitedTransformStream<T> extends TransformStream<T, T> {
* @param size The maximum number of chunks to read.
* @param options Options for the stream.
*
* @example size = 42
* ```ts no-assert
* @example `size` is equal to the total number of chunks
* ```ts
* import { LimitedTransformStream } from "@std/streams/limited-transform-stream";
* import { assertEquals } from "@std/assert";
*
* const limitedTransformStream = new LimitedTransformStream(42);
* const stream = ReadableStream.from(["1234", "5678"]);
* const transformed = stream.pipeThrough(
* new LimitedTransformStream(2),
* );
*
* // All chunks were read
* assertEquals(
* await Array.fromAsync(transformed),
* ["1234", "5678"],
* );
* ```
*
* @example size = 42, error = true
* ```ts no-assert
* @example `size` is less than the total number of chunks
* ```ts
* import { LimitedTransformStream } from "@std/streams/limited-transform-stream";
* import { assertEquals } from "@std/assert";
*
* const limitedTransformStream = new LimitedTransformStream(42, { error: true });
* const stream = ReadableStream.from(["1234", "5678"]);
* const transformed = stream.pipeThrough(
* new LimitedTransformStream(1),
* );
*
* // Only the first chunk was read
* assertEquals(
* await Array.fromAsync(transformed),
* ["1234"],
* );
* ```
*
* @example Throw a {@linkcode RangeError} when the total number of chunks is
* about to exceed the specified limit
*
* Do this by setting `options.error` to `true`.
*
* ```ts
* import { LimitedTransformStream } from "@std/streams/limited-transform-stream";
* import { assertRejects } from "@std/assert";
*
* const stream = ReadableStream.from(["1234", "5678"]);
* const transformed = stream.pipeThrough(
* new LimitedTransformStream(1, { error: true }),
* );
*
* await assertRejects(async () => {
* await Array.fromAsync(transformed);
* }, RangeError);
* ```
*/
constructor(