BREAKING(streams): deprecate APIs based on legacy Reader/Writer interfaces (#3640)

streams/copy.ts

@@ -4,7 +4,10 @@
 import { DEFAULT_BUFFER_SIZE } from "./_common.ts";
 import type { Reader, Writer } from "../types.d.ts";
 
-/** Copies from `src` to `dst` until either EOF (`null`) is read from `src` or
+/**
+ * @deprecated (will be removed after 1.0.0) Use ReadableStream and WritableStream for inputs and outputs, and call `input.pipeTo(output)` 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.
  *

streams/iterate_reader.ts

@@ -4,7 +4,10 @@
 import { DEFAULT_BUFFER_SIZE } from "./_common.ts";
 import type { Reader, ReaderSync } from "../types.d.ts";
 
-/** Turns a Reader, `r`, into an async iterator.
+/**
+ * @deprecated (will be removed after 1.0.0) Use ReadableStream instead.
+ *
+ * Turns a Reader, `r`, into an async iterator.
  *
  * ```ts
  * import { iterateReader } from "https://deno.land/std@$STD_VERSION/streams/iterate_reader.ts";
@@ -50,7 +53,10 @@ export async function* iterateReader(
   }
 }
 
-/** Turns a ReaderSync, `r`, into an iterator.
+/**
+ * @deprecated (will be removed after 1.0.0) Use ReadableStream instead.
+ *
+ * Turns a ReaderSync, `r`, into an iterator.
  *
  * ```ts
  * import { iterateReaderSync } from "https://deno.land/std@$STD_VERSION/streams/iterate_reader.ts";

streams/read_all.ts

@@ -4,7 +4,10 @@
 import { Buffer } from "../io/buffer.ts";
 import type { Reader, ReaderSync } from "../types.d.ts";
 
-/** Read Reader `r` until EOF (`null`) and resolve to the content as
+/**
+ * @deprecated (will be removed after 1.0.0) Use ReadableStream and toArrayBuffer instead.
+ *
+ * Read Reader `r` until EOF (`null`) and resolve to the content as
  * Uint8Array`.
  *
  * ```ts
@@ -32,7 +35,10 @@ export async function readAll(r: Reader): Promise<Uint8Array> {
   return buf.bytes();
 }
 
-/** Synchronously reads Reader `r` until EOF (`null`) and returns the content
+/**
+ * @deprecated (will be removed after 1.0.0) Use ReadableStream and toArrayBuffer instead.
+ *
+ * Synchronously reads Reader `r` until EOF (`null`) and returns the content
  * as `Uint8Array`.
  *
  * ```ts

streams/readable_stream_from_reader.ts

@@ -11,6 +11,7 @@ function isCloser(value: unknown): value is Closer {
     typeof (value as Record<string, any>)["close"] === "function";
 }
 
+/** @deprecated (will be removed after 1.0.0) Use ReadableStream directly. */
 export interface ReadableStreamFromReaderOptions {
   /** If the `reader` is also a `Closer`, automatically close the `reader`
    * when `EOF` is encountered, or a read error occurs.
@@ -28,6 +29,8 @@ export interface ReadableStreamFromReaderOptions {
 }
 
 /**
+ * @deprecated (will be removed after 1.0.0) Use ReadableStream directly.
+ *
  * Create a `ReadableStream<Uint8Array>` from a `Reader`.
  *
  * When the pull algorithm is called on the stream, a chunk from the reader

streams/reader_from_iterable.ts

@@ -5,7 +5,10 @@ import { Buffer } from "../io/buffer.ts";
 import { writeAll } from "./write_all.ts";
 import { Reader } from "../types.d.ts";
 
-/** Create a `Reader` from an iterable of `Uint8Array`s.
+/**
+ * @deprecated (will be removed after 1.0.0) Convert to ReadableStream using ReadableStream.from instead.
+ *
+ * Create a `Reader` from an iterable of `Uint8Array`s.
  *
  * ```ts
  *      import { readerFromIterable } from "https://deno.land/std@$STD_VERSION/streams/reader_from_iterable.ts";

streams/reader_from_stream_reader.ts

@@ -6,6 +6,8 @@ import { writeAll } from "./write_all.ts";
 import type { Reader } from "../types.d.ts";
 
 /**
+ * @deprecated (will be removed after 1.0.0) Use ReadableStreamDefaultReader directly.
+ *
  * Create a `Reader` from a `ReadableStreamDefaultReader`.
  *
  * @example

streams/writable_stream_from_writer.ts

@@ -11,6 +11,7 @@ function isCloser(value: unknown): value is Closer {
     typeof (value as Record<string, any>)["close"] === "function";
 }
 
+/** @deprecated (will be removed after 1.0.0) Use WritableStream directly. */
 export interface WritableStreamFromWriterOptions {
   /**
    * If the `writer` is also a `Closer`, automatically close the `writer`
@@ -21,7 +22,11 @@ export interface WritableStreamFromWriterOptions {
   autoClose?: boolean;
 }
 
-/** Create a `WritableStream` from a `Writer`. */
+/**
+ * @deprecated (will be removed after 1.0.0) Use WritableStream directly.
+ *
+ * Create a `WritableStream` from a `Writer`.
+ */
 export function writableStreamFromWriter(
   writer: Writer,
   options: WritableStreamFromWriterOptions = {},

streams/write_all.ts

@@ -3,7 +3,10 @@
 
 import type { Writer, WriterSync } from "../types.d.ts";
 
-/** Write all the content of the array buffer (`arr`) to the writer (`w`).
+/**
+ * @deprecated (will be removed after 1.0.0) Use WritableStream, ReadableStream.from, and pipeTo() instead.
+ *
+ * Write all the content of the array buffer (`arr`) to the writer (`w`).
  *
  * ```ts
  * import { Buffer } from "https://deno.land/std@$STD_VERSION/io/buffer.ts";
@@ -33,7 +36,10 @@ export async function writeAll(w: Writer, arr: Uint8Array) {
   }
 }
 
-/** Synchronously write all the content of the array buffer (`arr`) to the
+/**
+ * @deprecated (will be removed after 1.0.0) Use WritableStream, ReadableStream.from, and pipeTo() instead.
+ *
+ * Synchronously write all the content of the array buffer (`arr`) to the
  * writer (`w`).
  *
  * ```ts

streams/writer_from_stream_writer.ts

@@ -3,7 +3,10 @@
 
 import type { Writer } from "../types.d.ts";
 
-/** Create a `Writer` from a `WritableStreamDefaultWriter`.
+/**
+ * @deprecated (will be removed after 1.0.0) Use WritableStreamDefaultWriter directly.
+ *
+ * Create a `Writer` from a `WritableStreamDefaultWriter`.
  *
  * @example
  * ```ts