diff --git a/cli/tsc/dts/lib.deno.ns.d.ts b/cli/tsc/dts/lib.deno.ns.d.ts index 320e6f29b94b2a..07bfd4c777833b 100644 --- a/cli/tsc/dts/lib.deno.ns.d.ts +++ b/cli/tsc/dts/lib.deno.ns.d.ts @@ -1657,141 +1657,6 @@ declare namespace Deno { End = 2, } - /** - * An abstract interface which when implemented provides an interface to read - * bytes into an array buffer asynchronously. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O */ - export interface Reader { - /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number of - * bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error - * encountered. Even if `read()` resolves to `n` < `p.byteLength`, it may - * use all of `p` as scratch space during the call. If some data is - * available but not `p.byteLength` bytes, `read()` conventionally resolves - * to what is available instead of waiting for more. - * - * When `read()` encounters end-of-file condition, it resolves to EOF - * (`null`). - * - * When `read()` encounters an error, it rejects with an error. - * - * Callers should always process the `n` > `0` bytes returned before - * considering the EOF (`null`). Doing so correctly handles I/O errors that - * happen after reading some bytes and also both of the allowed EOF - * behaviors. - * - * Implementations should not retain a reference to `p`. - * - * Use - * {@linkcode https://jsr.io/@std/io/doc/iterate-reader/~/iterateReader | iterateReader} - * to turn {@linkcode Reader} into an {@linkcode AsyncIterator}. - */ - read(p: Uint8Array): Promise; - } - - /** - * An abstract interface which when implemented provides an interface to read - * bytes into an array buffer synchronously. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O */ - export interface ReaderSync { - /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number - * of bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error - * encountered. Even if `readSync()` returns `n` < `p.byteLength`, it may use - * all of `p` as scratch space during the call. If some data is available - * but not `p.byteLength` bytes, `readSync()` conventionally returns what is - * available instead of waiting for more. - * - * When `readSync()` encounters end-of-file condition, it returns EOF - * (`null`). - * - * When `readSync()` encounters an error, it throws with an error. - * - * Callers should always process the `n` > `0` bytes returned before - * considering the EOF (`null`). Doing so correctly handles I/O errors that - * happen after reading some bytes and also both of the allowed EOF - * behaviors. - * - * Implementations should not retain a reference to `p`. - * - * Use - * {@linkcode https://jsr.io/@std/io/doc/iterate-reader/~/iterateReaderSync | iterateReaderSync} - * to turn {@linkcode ReaderSync} into an {@linkcode Iterator}. - */ - readSync(p: Uint8Array): number | null; - } - - /** - * An abstract interface which when implemented provides an interface to write - * bytes from an array buffer to a file/resource asynchronously. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O */ - export interface Writer { - /** Writes `p.byteLength` bytes from `p` to the underlying data stream. It - * resolves to the number of bytes written from `p` (`0` <= `n` <= - * `p.byteLength`) or reject with the error encountered that caused the - * write to stop early. `write()` must reject with a non-null error if - * would resolve to `n` < `p.byteLength`. `write()` must not modify the - * slice data, even temporarily. - * - * This function is one of the lowest - * level APIs and most users should not work with this directly, but rather - * use {@linkcode https://jsr.io/@std/io/doc/write-all/~/writeAll | writeAll} - * instead. - * - * Implementations should not retain a reference to `p`. - */ - write(p: Uint8Array): Promise; - } - - /** - * An abstract interface which when implemented provides an interface to write - * bytes from an array buffer to a file/resource synchronously. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O */ - export interface WriterSync { - /** Writes `p.byteLength` bytes from `p` to the underlying data - * stream. It returns the number of bytes written from `p` (`0` <= `n` - * <= `p.byteLength`) and any error encountered that caused the write to - * stop early. `writeSync()` must throw a non-null error if it returns `n` < - * `p.byteLength`. `writeSync()` must not modify the slice data, even - * temporarily. - * - * Implementations should not retain a reference to `p`. - */ - writeSync(p: Uint8Array): number; - } - - /** - * An abstract interface which when implemented provides an interface to close - * files/resources that were previously opened. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O */ - export interface Closer { - /** Closes the resource, "freeing" the backing file/resource. */ - close(): void; - } - /** * An abstract interface which when implemented provides an interface to seek * within an open file/resource asynchronously. @@ -2009,16 +1874,7 @@ declare namespace Deno { * * @category File System */ - export class FsFile - implements - Reader, - ReaderSync, - Writer, - WriterSync, - Seeker, - SeekerSync, - Closer, - Disposable { + export class FsFile implements Seeker, SeekerSync, Disposable { /** * The resource ID associated with the file instance. The resource ID * should be considered an opaque reference to resource. @@ -2451,9 +2307,12 @@ declare namespace Deno { } /** A reference to `stdin` which can be used to read directly from `stdin`. - * It implements the Deno specific {@linkcode Reader}, {@linkcode ReaderSync}, - * and {@linkcode Closer} interfaces as well as provides a - * {@linkcode ReadableStream} interface. + * + * It implements the Deno specific + * {@linkcode https://jsr.io/@std/io/doc/types/~/Reader | Reader}, + * {@linkcode https://jsr.io/@std/io/doc/types/~/ReaderSync | ReaderSync}, + * and {@linkcode https://jsr.io/@std/io/doc/types/~/Closer | Closer} + * interfaces as well as provides a {@linkcode ReadableStream} interface. * * ### Reading chunks from the readable stream * @@ -2467,7 +2326,57 @@ declare namespace Deno { * * @category I/O */ - export const stdin: Reader & ReaderSync & Closer & { + export const stdin: { + /** Read the incoming data from `stdin` into an array buffer (`p`). + * + * Resolves to either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This + * does not indicate EOF. + * + * **It is not guaranteed that the full buffer will be read in a single + * call.** + * + * ```ts + * // If the text "hello world" is piped into the script: + * const buf = new Uint8Array(100); + * const numberOfBytesRead = await Deno.stdin.read(buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * ``` + * + * @category I/O + */ + read(p: Uint8Array): Promise; + /** Synchronously read from the incoming data from `stdin` into an array + * buffer (`p`). + * + * Returns either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This + * does not indicate EOF. + * + * **It is not guaranteed that the full buffer will be read in a single + * call.** + * + * ```ts + * // If the text "hello world" is piped into the script: + * const buf = new Uint8Array(100); + * const numberOfBytesRead = Deno.stdin.readSync(buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * ``` + * + * @category I/O + */ + readSync(p: Uint8Array): number | null; + /** Closes `stdin`, freeing the resource. + * + * ```ts + * Deno.stdin.close(); + * ``` + */ + close(): void; /** A readable stream interface to `stdin`. */ readonly readable: ReadableStream; /** @@ -2497,8 +2406,10 @@ declare namespace Deno { isTerminal(): boolean; }; /** A reference to `stdout` which can be used to write directly to `stdout`. - * It implements the Deno specific {@linkcode Writer}, {@linkcode WriterSync}, - * and {@linkcode Closer} interfaces as well as provides a + * It implements the Deno specific + * {@linkcode https://jsr.io/@std/io/doc/types/~/Writer | Writer}, + * {@linkcode https://jsr.io/@std/io/doc/types/~/WriterSync | WriterSync}, + * and {@linkcode https://jsr.io/@std/io/doc/types/~/Closer | Closer} interfaces as well as provides a * {@linkcode WritableStream} interface. * * These are low level constructs, and the {@linkcode console} interface is a @@ -2506,7 +2417,44 @@ declare namespace Deno { * * @category I/O */ - export const stdout: Writer & WriterSync & Closer & { + export const stdout: { + /** Write the contents of the array buffer (`p`) to `stdout`. + * + * Resolves to the number of bytes written. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * const bytesWritten = await Deno.stdout.write(data); // 11 + * ``` + * + * @category I/O + */ + write(p: Uint8Array): Promise; + /** Synchronously write the contents of the array buffer (`p`) to `stdout`. + * + * Returns the number of bytes written. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * const bytesWritten = Deno.stdout.writeSync(data); // 11 + * ``` + */ + writeSync(p: Uint8Array): number; + /** Closes `stdout`, freeing the resource. + * + * ```ts + * Deno.stdout.close(); + * ``` + */ + close(): void; /** A writable stream interface to `stdout`. */ readonly writable: WritableStream; /** @@ -2522,8 +2470,10 @@ declare namespace Deno { isTerminal(): boolean; }; /** A reference to `stderr` which can be used to write directly to `stderr`. - * It implements the Deno specific {@linkcode Writer}, {@linkcode WriterSync}, - * and {@linkcode Closer} interfaces as well as provides a + * It implements the Deno specific + * {@linkcode https://jsr.io/@std/io/doc/types/~/Writer | Writer}, + * {@linkcode https://jsr.io/@std/io/doc/types/~/WriterSync | WriterSync}, + * and {@linkcode https://jsr.io/@std/io/doc/types/~/Closer | Closer} interfaces as well as provides a * {@linkcode WritableStream} interface. * * These are low level constructs, and the {@linkcode console} interface is a @@ -2531,7 +2481,44 @@ declare namespace Deno { * * @category I/O */ - export const stderr: Writer & WriterSync & Closer & { + export const stderr: { + /** Write the contents of the array buffer (`p`) to `stderr`. + * + * Resolves to the number of bytes written. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * const bytesWritten = await Deno.stderr.write(data); // 11 + * ``` + * + * @category I/O + */ + write(p: Uint8Array): Promise; + /** Synchronously write the contents of the array buffer (`p`) to `stderr`. + * + * Returns the number of bytes written. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * const bytesWritten = Deno.stderr.writeSync(data); // 11 + * ``` + */ + writeSync(p: Uint8Array): number; + /** Closes `stderr`, freeing the resource. + * + * ```ts + * Deno.stderr.close(); + * ``` + */ + close(): void; /** A writable stream interface to `stderr`. */ readonly writable: WritableStream; /** @@ -2614,30 +2601,6 @@ declare namespace Deno { signal?: AbortSignal; } - /** - * Read Reader `r` until EOF (`null`) and resolve to the content as - * Uint8Array`. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function readAll(r: Reader): Promise; - - /** - * Synchronously reads Reader `r` until EOF (`null`) and returns the content - * as `Uint8Array`. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function readAllSync(r: ReaderSync): Uint8Array; - /** * Options which can be set when using {@linkcode Deno.mkdir} and * {@linkcode Deno.mkdirSync}. diff --git a/ext/net/lib.deno_net.d.ts b/ext/net/lib.deno_net.d.ts index f87f132ac25f95..b2ffffa27467ec 100644 --- a/ext/net/lib.deno_net.d.ts +++ b/ext/net/lib.deno_net.d.ts @@ -77,8 +77,57 @@ declare namespace Deno { export type UnixListener = Listener; /** @category Network */ - export interface Conn - extends Reader, Writer, Closer, Disposable { + export interface Conn extends Disposable { + /** Read the incoming data from the connection into an array buffer (`p`). + * + * Resolves to either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This + * does not indicate EOF. + * + * **It is not guaranteed that the full buffer will be read in a single + * call.** + * + * ```ts + * // If the text "hello world" is received by the client: + * const conn = await Deno.connect({ hostname: "example.com", port: 80 }); + * const buf = new Uint8Array(100); + * const numberOfBytesRead = await conn.read(buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * ``` + * + * @category I/O + */ + read(p: Uint8Array): Promise; + /** Write the contents of the array buffer (`p`) to the connection. + * + * Resolves to the number of bytes written. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const conn = await Deno.connect({ hostname: "example.com", port: 80 }); + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * const bytesWritten = await conn.write(data); // 11 + * ``` + * + * @category I/O + */ + write(p: Uint8Array): Promise; + /** Closes the connection, freeing the resource. + * + * ```ts + * const conn = await Deno.connect({ hostname: "example.com", port: 80 }); + * + * // ... + * + * conn.close(); + * ``` + */ + close(): void; /** The local address of the connection. */ readonly localAddr: A; /** The remote address of the connection. */ diff --git a/tests/unit/http_test.ts b/tests/unit/http_test.ts index 03b7e940567768..ea72806d3af4f7 100644 --- a/tests/unit/http_test.ts +++ b/tests/unit/http_test.ts @@ -3,7 +3,7 @@ // deno-lint-ignore-file no-deprecated-deno-api -import { Buffer, BufReader, BufWriter } from "@std/io"; +import { Buffer, BufReader, BufWriter, type Reader } from "@std/io"; import { TextProtoReader } from "../testdata/run/textproto.ts"; import { assert, @@ -2770,7 +2770,7 @@ Deno.test("proxy with fetch", async () => { httpConn!.close(); }); -function chunkedBodyReader(h: Headers, r: BufReader): Deno.Reader { +function chunkedBodyReader(h: Headers, r: BufReader): Reader { // Based on https://tools.ietf.org/html/rfc2616#section-19.4.6 const tp = new TextProtoReader(r); let finished = false; diff --git a/tests/unit/serve_test.ts b/tests/unit/serve_test.ts index 9d23f8df25257f..13f8ba867a9e89 100644 --- a/tests/unit/serve_test.ts +++ b/tests/unit/serve_test.ts @@ -3,7 +3,7 @@ // deno-lint-ignore-file no-console import { assertMatch, assertRejects } from "@std/assert"; -import { Buffer, BufReader, BufWriter } from "@std/io"; +import { Buffer, BufReader, BufWriter, type Reader } from "@std/io"; import { TextProtoReader } from "../testdata/run/textproto.ts"; import { assert, @@ -3774,7 +3774,7 @@ Deno.test( }, ); -function chunkedBodyReader(h: Headers, r: BufReader): Deno.Reader { +function chunkedBodyReader(h: Headers, r: BufReader): Reader { // Based on https://tools.ietf.org/html/rfc2616#section-19.4.6 const tp = new TextProtoReader(r); let finished = false;