foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-11-28 16:20:57 -05:00
Code Issues Packages 1 Wiki Activity

BREAKING(io): remove Deno.{Reader,Writer}[Sync] and Deno.Closer (#25524)

Browse source
This commit is contained in:
Asher Gomez 2024-09-10 07:07:12 +10:00 committed by GitHub
parent 04a9cc95ac
commit aadcf3346c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 197 additions and 185 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

321
cli/tsc/dts/lib.deno.ns.d.ts vendored
View file

@ -1657,141 +1657,6 @@ declare namespace Deno {
End = 2, 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<number | null>;
}
/**
* 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<number>;
}
/**
* 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 * An abstract interface which when implemented provides an interface to seek
* within an open file/resource asynchronously. * within an open file/resource asynchronously.
@ -1975,16 +1840,7 @@ declare namespace Deno {
* *
* @category File System * @category File System
*/ */
export class FsFile export class FsFile implements Seeker, SeekerSync, Disposable {
implements
Reader,
ReaderSync,
Writer,
WriterSync,
Seeker,
SeekerSync,
Closer,
Disposable {
/** /**
* The resource ID associated with the file instance. The resource ID * The resource ID associated with the file instance. The resource ID
* should be considered an opaque reference to resource. * should be considered an opaque reference to resource.
@ -2417,9 +2273,12 @@ declare namespace Deno {
} }
/** A reference to `stdin` which can be used to read directly from `stdin`. /** 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 * It implements the Deno specific
* {@linkcode ReadableStream} interface. * {@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 * ### Reading chunks from the readable stream
* *
@ -2433,7 +2292,57 @@ declare namespace Deno {
* *
* @category I/O * @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<number | null>;
/** 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`. */ /** A readable stream interface to `stdin`. */
readonly readable: ReadableStream<Uint8Array>; readonly readable: ReadableStream<Uint8Array>;
/** /**
@ -2463,8 +2372,10 @@ declare namespace Deno {
isTerminal(): boolean; isTerminal(): boolean;
}; };
/** A reference to `stdout` which can be used to write directly to `stdout`. /** A reference to `stdout` which can be used to write directly to `stdout`.
* It implements the Deno specific {@linkcode Writer}, {@linkcode WriterSync}, * It implements the Deno specific
* and {@linkcode Closer} interfaces as well as provides a * {@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. * {@linkcode WritableStream} interface.
* *
* These are low level constructs, and the {@linkcode console} interface is a * These are low level constructs, and the {@linkcode console} interface is a
@ -2472,7 +2383,44 @@ declare namespace Deno {
* *
* @category I/O * @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<number>;
/** 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`. */ /** A writable stream interface to `stdout`. */
readonly writable: WritableStream<Uint8Array>; readonly writable: WritableStream<Uint8Array>;
/** /**
@ -2488,8 +2436,10 @@ declare namespace Deno {
isTerminal(): boolean; isTerminal(): boolean;
}; };
/** A reference to `stderr` which can be used to write directly to `stderr`. /** A reference to `stderr` which can be used to write directly to `stderr`.
* It implements the Deno specific {@linkcode Writer}, {@linkcode WriterSync}, * It implements the Deno specific
* and {@linkcode Closer} interfaces as well as provides a * {@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. * {@linkcode WritableStream} interface.
* *
* These are low level constructs, and the {@linkcode console} interface is a * These are low level constructs, and the {@linkcode console} interface is a
@ -2497,7 +2447,44 @@ declare namespace Deno {
* *
* @category I/O * @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<number>;
/** 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`. */ /** A writable stream interface to `stderr`. */
readonly writable: WritableStream<Uint8Array>; readonly writable: WritableStream<Uint8Array>;
/** /**
@ -2580,30 +2567,6 @@ declare namespace Deno {
signal?: AbortSignal; 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<Uint8Array>;
/**
* 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 * Options which can be set when using {@linkcode Deno.mkdir} and
* {@linkcode Deno.mkdirSync}. * {@linkcode Deno.mkdirSync}.

53
ext/net/lib.deno_net.d.ts vendored
View file

@ -77,8 +77,57 @@ declare namespace Deno {
export type UnixListener = Listener<UnixConn, UnixAddr>; export type UnixListener = Listener<UnixConn, UnixAddr>;
/** @category Network */ /** @category Network */
export interface Conn<A extends Addr = Addr> export interface Conn<A extends Addr = Addr> extends Disposable {
extends Reader, Writer, Closer, 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<number | null>;
/** 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<number>;
/** 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. */ /** The local address of the connection. */
readonly localAddr: A; readonly localAddr: A;
/** The remote address of the connection. */ /** The remote address of the connection. */

4
tests/unit/http_test.ts
View file

@ -3,7 +3,7 @@
// deno-lint-ignore-file no-deprecated-deno-api // 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 { TextProtoReader } from "../testdata/run/textproto.ts";
import { import {
assert, assert,
@ -2770,7 +2770,7 @@ Deno.test("proxy with fetch", async () => {
httpConn!.close(); 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 // Based on https://tools.ietf.org/html/rfc2616#section-19.4.6
const tp = new TextProtoReader(r); const tp = new TextProtoReader(r);
let finished = false; let finished = false;

4
tests/unit/serve_test.ts
View file

@ -3,7 +3,7 @@
// deno-lint-ignore-file no-console // deno-lint-ignore-file no-console
import { assertMatch, assertRejects } from "@std/assert"; 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 { TextProtoReader } from "../testdata/run/textproto.ts";
import { import {
assert, 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 // Based on https://tools.ietf.org/html/rfc2616#section-19.4.6
const tp = new TextProtoReader(r); const tp = new TextProtoReader(r);
let finished = false; let finished = false;