From 517b2ee2d334a37a0d3778bf78e1130c10e208f9 Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Mon, 4 Dec 2023 13:36:49 +1100 Subject: [PATCH 1/2] chore(streams): complete documentation --- streams/buffer.ts | 19 +++++++++++---- streams/byte_slice_stream.ts | 5 +++- streams/copy.ts | 5 ++-- streams/delimiter_stream.ts | 8 +++---- streams/early_zip_readable_streams.ts | 11 +++++++++ streams/iterate_reader.ts | 16 ++++++++----- streams/limited_bytes_transform_stream.ts | 13 +++++++---- streams/limited_transform_stream.ts | 9 ++++++-- streams/merge_readable_streams.ts | 11 +++++++++ streams/read_all.ts | 20 +++++++++------- streams/readable_stream_from_reader.ts | 15 ++++++++---- streams/reader_from_iterable.ts | 28 +++++++++++------------ streams/reader_from_stream_reader.ts | 6 ++--- streams/text_delimiter_stream.ts | 5 +++- streams/text_line_stream.ts | 3 +++ streams/to_array_buffer.ts | 15 ++++++++++++ streams/to_blob.ts | 12 ++++++++++ streams/to_json.ts | 15 +++++++++++- streams/to_text.ts | 14 +++++++++++- streams/to_transform_stream.ts | 3 ++- streams/writable_stream_from_writer.ts | 10 +++++--- streams/write_all.ts | 14 ++++++++---- streams/writer_from_stream_writer.ts | 6 ++--- streams/zip_readable_streams.ts | 20 ++++++++++++---- 24 files changed, 211 insertions(+), 72 deletions(-) diff --git a/streams/buffer.ts b/streams/buffer.ts index b76377c8cbb3..a84f452b06df 100644 --- a/streams/buffer.ts +++ b/streams/buffer.ts @@ -41,19 +41,25 @@ export class Buffer { }, autoAllocateChunkSize: DEFAULT_CHUNK_SIZE, }); - get readable() { + + /** Getter returning the instance's {@linkcode ReadableStream}. */ + get readable(): ReadableStream { return this.#readable; } + #writable = new WritableStream({ write: (chunk) => { const m = this.#grow(chunk.byteLength); copy(chunk, this.#buf, m); }, }); - get writable() { + + /** Getter returning the instance's {@linkcode WritableStream}. */ + get writable(): WritableStream { return this.#writable; } + /** Constructs a new instance. */ constructor(ab?: ArrayBufferLike | ArrayLike) { this.#buf = ab === undefined ? new Uint8Array(0) : new Uint8Array(ab); } @@ -87,10 +93,12 @@ export class Buffer { return this.#buf.buffer.byteLength; } - /** Discards all but the first `n` unread bytes from the buffer but + /** + * Discards all but the first `n` unread bytes from the buffer but * continues to use the same allocated storage. It throws if `n` is - * negative or greater than the length of the buffer. */ - truncate(n: number) { + * negative or greater than the length of the buffer. + */ + truncate(n: number): void { if (n === 0) { this.reset(); return; @@ -101,6 +109,7 @@ export class Buffer { this.#reslice(this.#off + n); } + /** Resets to an empty buffer. */ reset() { this.#reslice(0); this.#off = 0; diff --git a/streams/byte_slice_stream.ts b/streams/byte_slice_stream.ts index d94c79c4b81f..994d580d0647 100644 --- a/streams/byte_slice_stream.ts +++ b/streams/byte_slice_stream.ts @@ -4,11 +4,13 @@ import { assert } from "../assert/assert.ts"; /** - * A transform stream that only transforms from the zero-indexed `start` and `end` bytes (both inclusive). + * A transform stream that only transforms from the zero-indexed `start` and + * `end` bytes (both inclusive). * * @example * ```ts * import { ByteSliceStream } from "https://deno.land/std@$STD_VERSION/streams/byte_slice_stream.ts"; + * * const response = await fetch("https://example.com"); * const rangedStream = response.body! * .pipeThrough(new ByteSliceStream(3, 8)); @@ -18,6 +20,7 @@ export class ByteSliceStream extends TransformStream { #offsetStart = 0; #offsetEnd = 0; + /** Constructs a new instance. */ constructor(start = 0, end = Infinity) { super({ start: () => { diff --git a/streams/copy.ts b/streams/copy.ts index e78e4cb7393a..f04415a4dff5 100644 --- a/streams/copy.ts +++ b/streams/copy.ts @@ -5,8 +5,6 @@ import { DEFAULT_BUFFER_SIZE } from "./_common.ts"; import type { Reader, Writer } from "../io/types.d.ts"; /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream.pipeTo} instead. - * * Copies from `src` to `dst` until either EOF (`null`) is read from `src` or * an error occurs. It resolves to the number of bytes copied or rejects with * the first error encountered while copying. @@ -23,6 +21,9 @@ import type { Reader, Writer } from "../io/types.d.ts"; * @param src The source to copy from * @param dst The destination to copy to * @param options Can be used to tune size of the buffer. Default size is 32kB + * + * @deprecated (will be removed after 1.0.0) Use + * {@linkcode ReadableStream.pipeTo} instead. */ export async function copy( src: Reader, diff --git a/streams/delimiter_stream.ts b/streams/delimiter_stream.ts index 2f311e6e8ecb..c598d2494940 100644 --- a/streams/delimiter_stream.ts +++ b/streams/delimiter_stream.ts @@ -4,7 +4,7 @@ import { concat } from "../bytes/concat.ts"; import { createLPS } from "./_common.ts"; -/** Disposition of the delimiter. */ +/** Disposition of the delimiter for {@linkcode DelimiterStreamOptions}. */ export type DelimiterDisposition = /** Include delimiter in the found chunk. */ | "suffix" @@ -14,6 +14,7 @@ export type DelimiterDisposition = | "discard" // delimiter discarded ; +/** Options for {@linkcode DelimiterStream}. */ export interface DelimiterStreamOptions { /** Disposition of the delimiter. */ disposition?: DelimiterDisposition; @@ -46,10 +47,6 @@ export interface DelimiterStreamOptions { * ) * .pipeThrough(new TextDecoderStream()); * ``` - * - * @param delimiter Delimiter byte sequence - * @param options Options for the transform stream - * @returns Transform stream */ export class DelimiterStream extends TransformStream { #bufs: Uint8Array[] = []; @@ -58,6 +55,7 @@ export class DelimiterStream extends TransformStream { #delimLPS: Uint8Array | null; #disp: DelimiterDisposition; + /** Constructs a new instance. */ constructor( delimiter: Uint8Array, options?: DelimiterStreamOptions, diff --git a/streams/early_zip_readable_streams.ts b/streams/early_zip_readable_streams.ts index fd27a52b99ca..86f97c61d89b 100644 --- a/streams/early_zip_readable_streams.ts +++ b/streams/early_zip_readable_streams.ts @@ -5,6 +5,17 @@ * Merge multiple streams into a single one, taking order into account, and each stream * will wait for a chunk to enqueue before the next stream can append another chunk. * If a stream ends before other ones, the others will be cancelled. + * + * @example + * ```ts + * import { earlyZipReadableStreams } from "https://deno.land/std@$STD_VERSION/streams/early_zip_readable_streams.ts"; + * + * const stream1 = ReadableStream.from(["1", "2", "3"]); + * const stream2 = ReadableStream.from(["a", "b", "c"]); + * const zippedStream = earlyZipReadableStreams(stream1, stream2); + * + * await Array.fromAsync(zippedStream); // ["1", "a", "2", "b", "3", "c"]; + * ``` */ export function earlyZipReadableStreams( ...streams: ReadableStream[] diff --git a/streams/iterate_reader.ts b/streams/iterate_reader.ts index fa97fb22d33f..87fc9358106e 100644 --- a/streams/iterate_reader.ts +++ b/streams/iterate_reader.ts @@ -4,11 +4,12 @@ import { DEFAULT_BUFFER_SIZE } from "./_common.ts"; import type { Reader, ReaderSync } from "../io/types.d.ts"; +export type { Reader, ReaderSync }; + /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} instead. - * - * Turns a Reader, `r`, into an async iterator. + * Turns a {@linkcode Reader}, `r`, into an async iterator. * + * @example * ```ts * import { iterateReader } from "https://deno.land/std@$STD_VERSION/streams/iterate_reader.ts"; * @@ -22,6 +23,7 @@ import type { Reader, ReaderSync } from "../io/types.d.ts"; * Second argument can be used to tune size of a buffer. * Default size of the buffer is 32kB. * + * @example * ```ts * import { iterateReader } from "https://deno.land/std@$STD_VERSION/streams/iterate_reader.ts"; * @@ -34,6 +36,8 @@ import type { Reader, ReaderSync } from "../io/types.d.ts"; * } * f.close(); * ``` + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} instead. */ export async function* iterateReader( r: Reader, @@ -54,9 +58,7 @@ export async function* iterateReader( } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} instead. - * - * Turns a ReaderSync, `r`, into an iterator. + * Turns a {@linkcode ReaderSync}, `r`, into an iterator. * * ```ts * import { iterateReaderSync } from "https://deno.land/std@$STD_VERSION/streams/iterate_reader.ts"; @@ -88,6 +90,8 @@ export async function* iterateReader( * a view on that buffer on each iteration. It is therefore caller's * responsibility to copy contents of the buffer if needed; otherwise the * next iteration will overwrite contents of previously returned chunk. + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} instead. */ export function* iterateReaderSync( r: ReaderSync, diff --git a/streams/limited_bytes_transform_stream.ts b/streams/limited_bytes_transform_stream.ts index 6835efbcf8f2..52f7ecef23b9 100644 --- a/streams/limited_bytes_transform_stream.ts +++ b/streams/limited_bytes_transform_stream.ts @@ -1,15 +1,18 @@ // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. -/** A TransformStream that will only read & enqueue `size` amount of bytes. - * This operation is chunk based and not BYOB based, - * and as such will read more than needed. +/** + * A {@linkcode TransformStream} that will only read & enqueue `size` amount of + * bytes. This operation is chunk based and not BYOB based, and as such will + * read more than needed. * - * if options.error is set, then instead of terminating the stream, + * If `options.error` is set, then instead of terminating the stream, * an error will be thrown. * + * @example * ```ts * import { LimitedBytesTransformStream } from "https://deno.land/std@$STD_VERSION/streams/limited_bytes_transform_stream.ts"; + * * const res = await fetch("https://example.com"); * const parts = res.body! * .pipeThrough(new LimitedBytesTransformStream(512 * 1024)); @@ -18,6 +21,8 @@ export class LimitedBytesTransformStream extends TransformStream { #read = 0; + + /** Constructs a new instance. */ constructor(size: number, options: { error?: boolean } = {}) { super({ transform: (chunk, controller) => { diff --git a/streams/limited_transform_stream.ts b/streams/limited_transform_stream.ts index a85303def14b..0e633bec47dd 100644 --- a/streams/limited_transform_stream.ts +++ b/streams/limited_transform_stream.ts @@ -1,11 +1,14 @@ // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. -/** A TransformStream that will only read & enqueue `size` amount of chunks. +/** + * A {@linkcode TransformStream} that will only read & enqueue `size` amount of + * chunks. * - * if options.error is set, then instead of terminating the stream, + * If `options.error` is set, then instead of terminating the stream, * an error will be thrown. * + * @example * ```ts * import { LimitedTransformStream } from "https://deno.land/std@$STD_VERSION/streams/limited_transform_stream.ts"; * const res = await fetch("https://example.com"); @@ -14,6 +17,8 @@ */ export class LimitedTransformStream extends TransformStream { #read = 0; + + /** Constructs a new {@linkcode LimitedTransformStream} instance. */ constructor(size: number, options: { error?: boolean } = {}) { super({ transform: (chunk, controller) => { diff --git a/streams/merge_readable_streams.ts b/streams/merge_readable_streams.ts index 0d8cc557988f..c183d71c478b 100644 --- a/streams/merge_readable_streams.ts +++ b/streams/merge_readable_streams.ts @@ -4,6 +4,17 @@ * Merge multiple streams into a single one, not taking order into account. * If a stream ends before other ones, the other will continue adding data, * and the finished one will not add any more data. + * + * @example + * ```ts + * import { mergeReadableStreams } from "https://deno.land/std@$STD_VERSION/streams/merge_readable_streams.ts"; + * + * const stream1 = ReadableStream.from(["1", "2", "3"]); + * const stream2 = ReadableStream.from(["a", "b", "c"]); + * + * // ["2", "c", "a", "b", "3", "1"] + * await Array.fromAsync(mergeReadableStreams(stream1, stream2)); + * ``` */ export function mergeReadableStreams( ...streams: ReadableStream[] diff --git a/streams/read_all.ts b/streams/read_all.ts index 4a07d8a4d6d5..993fbcc81e8a 100644 --- a/streams/read_all.ts +++ b/streams/read_all.ts @@ -5,11 +5,10 @@ import { Buffer } from "../io/buffer.ts"; import type { Reader, ReaderSync } from "../io/types.d.ts"; /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} and {@linkcode import("./to_array_buffer.ts").toArrayBuffer} instead. - * - * Read Reader `r` until EOF (`null`) and resolve to the content as - * Uint8Array`. + * Read {@linkcode Reader} `r` until EOF (`null`) and resolve to the content as + * {@linkcode Uint8Array}. * + * @example * ```ts * import { Buffer } from "https://deno.land/std@$STD_VERSION/io/buffer.ts"; * import { readAll } from "https://deno.land/std@$STD_VERSION/streams/read_all.ts"; @@ -28,6 +27,9 @@ import type { Reader, ReaderSync } from "../io/types.d.ts"; * const reader = new Buffer(myData.buffer); * const bufferContent = await readAll(reader); * ``` + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} + * and {@linkcode toArrayBuffer} instead. */ export async function readAll(r: Reader): Promise { const buf = new Buffer(); @@ -36,11 +38,10 @@ export async function readAll(r: Reader): Promise { } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} and {@linkcode import("./to_array_buffer.ts").toArrayBuffer} instead. - * - * Synchronously reads Reader `r` until EOF (`null`) and returns the content - * as `Uint8Array`. + * Synchronously reads {@linkcode Reader} `r` until EOF (`null`) and returns + * the content as {@linkcode Uint8Array}. * + * @example * ```ts * import { Buffer } from "https://deno.land/std@$STD_VERSION/io/buffer.ts"; * import { readAllSync } from "https://deno.land/std@$STD_VERSION/streams/read_all.ts"; @@ -59,6 +60,9 @@ export async function readAll(r: Reader): Promise { * const reader = new Buffer(myData.buffer); * const bufferContent = readAllSync(reader); * ``` + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} and + * {@linkcode toArrayBuffer} instead. */ export function readAllSync(r: ReaderSync): Uint8Array { const buf = new Buffer(); diff --git a/streams/readable_stream_from_reader.ts b/streams/readable_stream_from_reader.ts index dba8ebdae830..54a65724c74c 100644 --- a/streams/readable_stream_from_reader.ts +++ b/streams/readable_stream_from_reader.ts @@ -3,6 +3,7 @@ import { DEFAULT_CHUNK_SIZE } from "./_common.ts"; import type { Closer, Reader } from "../io/types.d.ts"; +export type { Closer }; function isCloser(value: unknown): value is Closer { return typeof value === "object" && value !== null && value !== undefined && @@ -11,7 +12,12 @@ function isCloser(value: unknown): value is Closer { typeof (value as Record)["close"] === "function"; } -/** @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} directly instead. */ +/** + * Options for {@linkcode readableStreamFromReader}. + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} + * directly instead. + */ export interface ReadableStreamFromReaderOptions { /** If the `reader` is also a `Closer`, automatically close the `reader` * when `EOF` is encountered, or a read error occurs. @@ -29,9 +35,8 @@ export interface ReadableStreamFromReaderOptions { } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} directly instead. - * - * Create a `ReadableStream` from a `Reader`. + * Create a {@linkcode ReadableStream} of {@linkcode Uint8Array}s from a + * {@linkcode Reader}. * * When the pull algorithm is called on the stream, a chunk from the reader * will be read. When `null` is returned from the reader, the stream will be @@ -45,6 +50,8 @@ export interface ReadableStreamFromReaderOptions { * const file = await Deno.open("./file.txt", { read: true }); * const fileStream = readableStreamFromReader(file); * ``` + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream} directly instead. */ export function readableStreamFromReader( reader: Reader | (Reader & Closer), diff --git a/streams/reader_from_iterable.ts b/streams/reader_from_iterable.ts index 2d7c88197b38..58ea252c12ff 100644 --- a/streams/reader_from_iterable.ts +++ b/streams/reader_from_iterable.ts @@ -6,24 +6,24 @@ import { writeAll } from "./write_all.ts"; import { Reader } from "../io/types.d.ts"; /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream.from} instead. - * - * Create a `Reader` from an iterable of `Uint8Array`s. + * Create a {@linkcode Reader} from an iterable of {@linkcode Uint8Array}s. * * ```ts - * import { readerFromIterable } from "https://deno.land/std@$STD_VERSION/streams/reader_from_iterable.ts"; - * import { copy } from "https://deno.land/std@$STD_VERSION/streams/copy.ts"; + * import { readerFromIterable } from "https://deno.land/std@$STD_VERSION/streams/reader_from_iterable.ts"; + * import { copy } from "https://deno.land/std@$STD_VERSION/streams/copy.ts"; * - * const file = await Deno.open("metrics.txt", { write: true }); - * const reader = readerFromIterable((async function* () { - * while (true) { - * await new Promise((r) => setTimeout(r, 1000)); - * const message = `data: ${JSON.stringify(Deno.metrics())}\n\n`; - * yield new TextEncoder().encode(message); - * } - * })()); - * await copy(reader, file); + * const file = await Deno.open("metrics.txt", { write: true }); + * const reader = readerFromIterable((async function* () { + * while (true) { + * await new Promise((r) => setTimeout(r, 1000)); + * const message = `data: ${JSON.stringify(Deno.metrics())}\n\n`; + * yield new TextEncoder().encode(message); + * } + * })()); + * await copy(reader, file); * ``` + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStream.from} instead. */ export function readerFromIterable( iterable: Iterable | AsyncIterable, diff --git a/streams/reader_from_stream_reader.ts b/streams/reader_from_stream_reader.ts index 1c2628f59986..f5fbce75ab60 100644 --- a/streams/reader_from_stream_reader.ts +++ b/streams/reader_from_stream_reader.ts @@ -6,9 +6,7 @@ import { writeAll } from "./write_all.ts"; import type { Reader } from "../io/types.d.ts"; /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStreamDefaultReader} directly. - * - * Create a `Reader` from a `ReadableStreamDefaultReader`. + * Create a {@linkcode Reader} from a {@linkcode ReadableStreamDefaultReader}. * * @example * ```ts @@ -22,6 +20,8 @@ import type { Reader } from "../io/types.d.ts"; * await copy(reader, file); * file.close(); * ``` + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode ReadableStreamDefaultReader} directly. */ export function readerFromStreamReader( streamReader: ReadableStreamDefaultReader, diff --git a/streams/text_delimiter_stream.ts b/streams/text_delimiter_stream.ts index f02abb51d49a..bd50ff110c0b 100644 --- a/streams/text_delimiter_stream.ts +++ b/streams/text_delimiter_stream.ts @@ -8,8 +8,10 @@ import type { DelimiterStreamOptions, } from "./delimiter_stream.ts"; -/** Transform a stream into a stream where each chunk is divided by a given delimiter. +/** + * Transform a stream into a stream where each chunk is divided by a given delimiter. * + * @example * ```ts * import { TextDelimiterStream } from "https://deno.land/std@$STD_VERSION/streams/text_delimiter_stream.ts"; * const res = await fetch("https://example.com"); @@ -26,6 +28,7 @@ export class TextDelimiterStream extends TransformStream { #delimLPS: Uint8Array; #disp: DelimiterDisposition; + /** Constructs a {@linkcode TextDelimiterStream} instance. */ constructor(delimiter: string, options?: DelimiterStreamOptions) { super({ transform: (chunk, controller) => { diff --git a/streams/text_line_stream.ts b/streams/text_line_stream.ts index c2eb2fce8300..31901b610c3a 100644 --- a/streams/text_line_stream.ts +++ b/streams/text_line_stream.ts @@ -1,6 +1,7 @@ // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. +/** Options for {@linkcode TextLineStream}. */ export interface TextLineStreamOptions { /** * Allow splitting by `\r`. @@ -17,6 +18,7 @@ export interface TextLineStreamOptions { * @example * ```ts * import { TextLineStream } from "https://deno.land/std@$STD_VERSION/streams/text_line_stream.ts"; + * * const res = await fetch("https://example.com"); * const lines = res.body! * .pipeThrough(new TextDecoderStream()) @@ -26,6 +28,7 @@ export interface TextLineStreamOptions { export class TextLineStream extends TransformStream { #currentLine = ""; + /** Constructs a {@linkcode TextLineStream} instance. */ constructor(options: TextLineStreamOptions = { allowCR: false }) { super({ transform: (chars, controller) => { diff --git a/streams/to_array_buffer.ts b/streams/to_array_buffer.ts index 9fcb5354f71d..f0484b657da5 100644 --- a/streams/to_array_buffer.ts +++ b/streams/to_array_buffer.ts @@ -3,6 +3,21 @@ import { concat } from "../bytes/concat.ts"; +/** + * Converts a {@linkcode ReadableStream} of {@linkcode Uint8Array}s to an + * {@linkcode ArrayBuffer}. Works the same as{@linkcode Response.arrayBuffer}. + * + * @example + * ```ts + * import { toArrayBuffer } from "https://deno.land/std@$STD_VERSION/streams/to_array_buffer.ts"; + * + * const stream = ReadableStream.from([ + * new Uint8Array([1, 2]), + * new Uint8Array([3, 4]), + * ]); + * await toArrayBuffer(stream); // ArrayBuffer { [Uint8Contents]: <01 02 03 04>, byteLength: 4 } + * ``` + */ export async function toArrayBuffer( readableStream: ReadableStream, ): Promise { diff --git a/streams/to_blob.ts b/streams/to_blob.ts index 33a9f996a550..f550b2b3002b 100644 --- a/streams/to_blob.ts +++ b/streams/to_blob.ts @@ -1,6 +1,18 @@ // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. +/** + * Converts a {@linkcode ReadableStream} of strings or {@linkcode Uint8Array}s + * to a {@linkcode Blob}. Works the same as {@linkcode Response.blob}. + * + * @example + * ```ts + * import { toBlob } from "https://deno.land/std@$STD_VERSION/streams/to_blob.ts"; + * + * const stream = ReadableStream.from([new Uint8Array(1), new Uint8Array(2)]); + * await toBlob(stream); // Blob { size: 3, type: "" } + * ``` + */ export async function toBlob( readableStream: ReadableStream, ): Promise { diff --git a/streams/to_json.ts b/streams/to_json.ts index 27d83146d6bc..049239b82f70 100644 --- a/streams/to_json.ts +++ b/streams/to_json.ts @@ -3,8 +3,21 @@ import { toText } from "./to_text.ts"; +/** + * Converts a JSON-formatted {@linkcode ReadableSteam} of strings or + * {@linkcode Uint8Array}s to an object. Works the same as + * {@linkcode Response.json}. + * + * @example + * ```ts + * import { toJson } from "https://deno.land/std@$STD_VERSION/streams/to_json.ts"; + * + * const stream = ReadableStream.from([JSON.stringify({ hello: "world" })]); + * await toJson(stream); // { hello: "world" } + * ``` + */ export function toJson( - readableStream: ReadableStream, + readableStream: ReadableStream, ): Promise { return toText(readableStream).then(JSON.parse); } diff --git a/streams/to_text.ts b/streams/to_text.ts index 52cf0c7c92bc..8734f4298bb7 100644 --- a/streams/to_text.ts +++ b/streams/to_text.ts @@ -3,8 +3,20 @@ const textDecoder = new TextDecoder(); +/** + * Converts a {@linkcode ReadableSteam} of strings or {@linkcode Uint8Array}s + * to a single string. Works the same as {@linkcode Response.text}. + * + * @example + * ```ts + * import { toText } from "https://deno.land/std@$STD_VERSION/streams/to_text.ts"; + * + * const stream = ReadableStream.from(["Hello, ", "world!"]); + * await toText(stream); // "Hello, world!" + * ``` + */ export async function toText( - readableStream: ReadableStream, + readableStream: ReadableStream, ): Promise { const reader = readableStream.getReader(); let result = ""; diff --git a/streams/to_transform_stream.ts b/streams/to_transform_stream.ts index f5a5d35d2fc3..e911289fec99 100644 --- a/streams/to_transform_stream.ts +++ b/streams/to_transform_stream.ts @@ -2,8 +2,9 @@ // This module is browser compatible. /** - * Convert the generator function into a TransformStream. + * Convert the generator function into a {@linkcode TransformStream}. * + * @example * ```ts * import { toTransformStream } from "https://deno.land/std@$STD_VERSION/streams/to_transform_stream.ts"; * diff --git a/streams/writable_stream_from_writer.ts b/streams/writable_stream_from_writer.ts index 6151c929a07c..30d186d90700 100644 --- a/streams/writable_stream_from_writer.ts +++ b/streams/writable_stream_from_writer.ts @@ -11,7 +11,11 @@ function isCloser(value: unknown): value is Closer { typeof (value as Record)["close"] === "function"; } -/** @deprecated (will be removed after 1.0.0) Use {@linkcode WritableStream} directly. */ +/** + * Options for {@linkcode writableStreamFromWriter}. + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode WritableStream} directly. + */ export interface WritableStreamFromWriterOptions { /** * If the `writer` is also a `Closer`, automatically close the `writer` @@ -23,9 +27,9 @@ export interface WritableStreamFromWriterOptions { } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode WritableStream} directly. + * Create a {@linkcode WritableStream} from a {@linkcode Writer}. * - * Create a `WritableStream` from a `Writer`. + * @deprecated (will be removed after 1.0.0) Use {@linkcode WritableStream} directly. */ export function writableStreamFromWriter( writer: Writer, diff --git a/streams/write_all.ts b/streams/write_all.ts index e13c43010305..2bf57f416f20 100644 --- a/streams/write_all.ts +++ b/streams/write_all.ts @@ -2,12 +2,12 @@ // This module is browser compatible. import type { Writer, WriterSync } from "../io/types.d.ts"; +export type { Writer, WriterSync }; /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode WritableStream}, {@linkcode ReadableStream.from} and {@linkcode ReadableStream.pipeTo} instead. - * * Write all the content of the array buffer (`arr`) to the writer (`w`). * + * @example * ```ts * import { Buffer } from "https://deno.land/std@$STD_VERSION/io/buffer.ts"; * import { writeAll } from "https://deno.land/std@$STD_VERSION/streams/write_all.ts"; @@ -28,6 +28,10 @@ import type { Writer, WriterSync } from "../io/types.d.ts"; * await writeAll(writer, contentBytes); * console.log(writer.bytes().length); // 11 * ``` + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode WritableStream}, + * {@linkcode ReadableStream.from} and {@linkcode ReadableStream.pipeTo} + * instead. */ export async function writeAll(w: Writer, arr: Uint8Array) { let nwritten = 0; @@ -37,8 +41,6 @@ export async function writeAll(w: Writer, arr: Uint8Array) { } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode WritableStream}, {@linkcode ReadableStream.from} and {@linkcode ReadableStream.pipeTo} instead. - * * Synchronously write all the content of the array buffer (`arr`) to the * writer (`w`). * @@ -62,6 +64,10 @@ export async function writeAll(w: Writer, arr: Uint8Array) { * writeAllSync(writer, contentBytes); * console.log(writer.bytes().length); // 11 * ``` + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode WritableStream}, + * {@linkcode ReadableStream.from} and {@linkcode ReadableStream.pipeTo} + * instead. */ export function writeAllSync(w: WriterSync, arr: Uint8Array) { let nwritten = 0; diff --git a/streams/writer_from_stream_writer.ts b/streams/writer_from_stream_writer.ts index b964228e810c..fd09acbd3028 100644 --- a/streams/writer_from_stream_writer.ts +++ b/streams/writer_from_stream_writer.ts @@ -4,9 +4,7 @@ import type { Writer } from "../io/types.d.ts"; /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode WritableStreamDefaultWriter} directly. - * - * Create a `Writer` from a `WritableStreamDefaultWriter`. + * Create a {@linkcode Writer} from a {@linkcode WritableStreamDefaultWriter}. * * @example * ```ts @@ -24,6 +22,8 @@ import type { Writer } from "../io/types.d.ts"; * await copy(file, writer); * file.close(); * ``` + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode WritableStreamDefaultWriter} directly. */ export function writerFromStreamWriter( streamWriter: WritableStreamDefaultWriter, diff --git a/streams/zip_readable_streams.ts b/streams/zip_readable_streams.ts index f7fb4b057959..8db22b417de4 100644 --- a/streams/zip_readable_streams.ts +++ b/streams/zip_readable_streams.ts @@ -2,10 +2,22 @@ // This module is browser compatible. /** - * Merge multiple streams into a single one, taking order into account, and each stream - * will wait for a chunk to enqueue before the next stream can append another chunk. - * If a stream ends before other ones, the others will continue adding data in order, - * and the finished one will not add any more data. + * Merge multiple streams into a single one, taking order into account, and + * each stream will wait for a chunk to enqueue before the next stream can + * append another chunk. If a stream ends before other ones, the others will + * continue adding data in order, and the finished one will not add any more + * data. + * + * @example + * ```ts + * import { zipReadableStreams } from "https://deno.land/std@$STD_VERSION/streams/zip_readable_streams.ts"; + * + * const stream1 = ReadableStream.from(["1", "2", "3"]); + * const stream2 = ReadableStream.from(["a", "b", "c"]); + * const zippedStream = zipReadableStreams(stream1, stream2); + * + * await Array.fromAsync(zippedStream); // ["1", "a", "2", "b", "3", "c"]; + * ``` */ export function zipReadableStreams( ...streams: ReadableStream[] From 942138531dd5c16d292cf5862d330112be5b3da3 Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Mon, 4 Dec 2023 17:10:08 +1100 Subject: [PATCH 2/2] tweaks --- streams/limited_transform_stream.ts | 2 +- streams/text_delimiter_stream.ts | 2 +- streams/text_line_stream.ts | 2 +- streams/to_json.ts | 2 +- streams/to_text.ts | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/streams/limited_transform_stream.ts b/streams/limited_transform_stream.ts index 0e633bec47dd..d256c54dea6d 100644 --- a/streams/limited_transform_stream.ts +++ b/streams/limited_transform_stream.ts @@ -18,7 +18,7 @@ export class LimitedTransformStream extends TransformStream { #read = 0; - /** Constructs a new {@linkcode LimitedTransformStream} instance. */ + /** Constructs a new instance. */ constructor(size: number, options: { error?: boolean } = {}) { super({ transform: (chunk, controller) => { diff --git a/streams/text_delimiter_stream.ts b/streams/text_delimiter_stream.ts index bd50ff110c0b..6bac11d21274 100644 --- a/streams/text_delimiter_stream.ts +++ b/streams/text_delimiter_stream.ts @@ -28,7 +28,7 @@ export class TextDelimiterStream extends TransformStream { #delimLPS: Uint8Array; #disp: DelimiterDisposition; - /** Constructs a {@linkcode TextDelimiterStream} instance. */ + /** Constructs a new instance. */ constructor(delimiter: string, options?: DelimiterStreamOptions) { super({ transform: (chunk, controller) => { diff --git a/streams/text_line_stream.ts b/streams/text_line_stream.ts index 31901b610c3a..f12f57aab339 100644 --- a/streams/text_line_stream.ts +++ b/streams/text_line_stream.ts @@ -28,7 +28,7 @@ export interface TextLineStreamOptions { export class TextLineStream extends TransformStream { #currentLine = ""; - /** Constructs a {@linkcode TextLineStream} instance. */ + /** Constructs a new instance. */ constructor(options: TextLineStreamOptions = { allowCR: false }) { super({ transform: (chars, controller) => { diff --git a/streams/to_json.ts b/streams/to_json.ts index 049239b82f70..42b71831ed24 100644 --- a/streams/to_json.ts +++ b/streams/to_json.ts @@ -17,7 +17,7 @@ import { toText } from "./to_text.ts"; * ``` */ export function toJson( - readableStream: ReadableStream, + readableStream: ReadableStream, ): Promise { return toText(readableStream).then(JSON.parse); } diff --git a/streams/to_text.ts b/streams/to_text.ts index 8734f4298bb7..f0fb62d1da36 100644 --- a/streams/to_text.ts +++ b/streams/to_text.ts @@ -16,7 +16,7 @@ const textDecoder = new TextDecoder(); * ``` */ export async function toText( - readableStream: ReadableStream, + readableStream: ReadableStream, ): Promise { const reader = readableStream.getReader(); let result = "";