foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-12-22 07:14:47 -05:00
Code Issues Packages 1 Wiki Activity

Revert "docs: remove unstable messages" (#15886)

Browse source
This commit is contained in:
Luca Casonato 2022-09-15 14:09:23 +02:00 committed by GitHub
parent 606a6d7861
commit 516a1da467
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 126 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

173
cli/dts/lib.deno.unstable.d.ts vendored
View file

@ -191,7 +191,9 @@ declare namespace Deno {
fn: () => void | Promise<void>, fn: () => void | Promise<void>,
): void; ): void;
/** This API is under consideration to determine if permissions are required to call it. /**
* **UNSTABLE**: New API, yet to be vetted. This API is under consideration to
* determine if permissions are required to call it.
* *
* Retrieve the process umask. If `mask` is provided, sets the process umask. * Retrieve the process umask. If `mask` is provided, sets the process umask.
* This call always returns what the umask was before the call. * This call always returns what the umask was before the call.
@ -208,7 +210,9 @@ declare namespace Deno {
*/ */
export function umask(mask?: number): number; export function umask(mask?: number): number;
/** Gets the size of the console as columns/rows. /** **UNSTABLE**: New API, yet to be vetted.
*
* Gets the size of the console as columns/rows.
* *
* ```ts * ```ts
* const { columns, rows } = Deno.consoleSize(Deno.stdout.rid); * const { columns, rows } = Deno.consoleSize(Deno.stdout.rid);
@ -223,7 +227,7 @@ declare namespace Deno {
rows: number; rows: number;
}; };
/** There are questions around which permission this needs. And /** **Unstable** There are questions around which permission this needs. And
* maybe should be renamed (loadAverage?) * maybe should be renamed (loadAverage?)
* *
* Returns an array containing the 1, 5, and 15 minute load averages. The * Returns an array containing the 1, 5, and 15 minute load averages. The
@ -243,7 +247,7 @@ declare namespace Deno {
*/ */
export function loadavg(): number[]; export function loadavg(): number[];
/** Under consideration to possibly move to /** **Unstable** new API. yet to be vetted. Under consideration to possibly move to
* Deno.build or Deno.versions and if it should depend sys-info, which may not * Deno.build or Deno.versions and if it should depend sys-info, which may not
* be desireable. * be desireable.
* *
@ -260,7 +264,9 @@ declare namespace Deno {
*/ */
export function osRelease(): string; export function osRelease(): string;
/** Displays the total amount of free and used physical and swap memory in the /** **Unstable** new API. yet to be vetted.
*
* Displays the total amount of free and used physical and swap memory in the
* system, as well as the buffers and caches used by the kernel. * system, as well as the buffers and caches used by the kernel.
* *
* This is similar to the `free` command in Linux * This is similar to the `free` command in Linux
@ -319,7 +325,9 @@ declare namespace Deno {
mac: string; mac: string;
} }
/** Returns an array of the network interface informations. /** **Unstable** new API. yet to be vetted.
*
* Returns an array of the network interface informations.
* *
* ```ts * ```ts
* console.log(Deno.networkInterfaces()); * console.log(Deno.networkInterfaces());
@ -332,7 +340,9 @@ declare namespace Deno {
*/ */
export function networkInterfaces(): NetworkInterfaceInfo[]; export function networkInterfaces(): NetworkInterfaceInfo[];
/** Returns the user id of the process on POSIX platforms. Returns null on windows. /** **Unstable** new API. yet to be vetted.
*
* Returns the user id of the process on POSIX platforms. Returns null on windows.
* *
* ```ts * ```ts
* console.log(Deno.getUid()); * console.log(Deno.getUid());
@ -345,7 +355,9 @@ declare namespace Deno {
*/ */
export function getUid(): number | null; export function getUid(): number | null;
/** Returns the group id of the process on POSIX platforms. Returns null on windows. /** **Unstable** new API. yet to be vetted.
*
* Returns the group id of the process on POSIX platforms. Returns null on windows.
* *
* ```ts * ```ts
* console.log(Deno.getGid()); * console.log(Deno.getGid());
@ -581,7 +593,9 @@ declare namespace Deno {
*/ */
export type PointerValue = number | bigint; export type PointerValue = number | bigint;
/** An unsafe pointer to a memory location for passing and returning pointers /** **UNSTABLE**: Unsafe and new API, beware!
*
* An unsafe pointer to a memory location for passing and returning pointers
* to and from the FFI. * to and from the FFI.
* *
* @category FFI * @category FFI
@ -593,7 +607,9 @@ declare namespace Deno {
static of(value: Deno.UnsafeCallback | TypedArray): PointerValue; static of(value: Deno.UnsafeCallback | TypedArray): PointerValue;
} }
/** An unsafe pointer view to a memory location as specified by the `pointer` /** **UNSTABLE**: Unsafe and new API, beware!
*
* An unsafe pointer view to a memory location as specified by the `pointer`
* value. The `UnsafePointerView` API mimics the standard built in interface * value. The `UnsafePointerView` API mimics the standard built in interface
* `DataView` for accessing the underlying types at an memory location * `DataView` for accessing the underlying types at an memory location
* (numbers, strings and raw bytes). * (numbers, strings and raw bytes).
@ -649,7 +665,10 @@ declare namespace Deno {
): void; ): void;
} }
/** An unsafe pointer to a function, for calling functions that are not /**
* **UNSTABLE**: Unsafe and new API, beware!
*
* An unsafe pointer to a function, for calling functions that are not
* present as symbols. * present as symbols.
* *
* @category FFI * @category FFI
@ -680,7 +699,10 @@ declare namespace Deno {
...args: FromNativeParameterTypes<Parameters> ...args: FromNativeParameterTypes<Parameters>
) => ToNativeResultType<Result>; ) => ToNativeResultType<Result>;
/** An unsafe function pointer for passing JavaScript functions /**
* **UNSTABLE**: Unsafe and new API, beware!
*
* An unsafe function pointer for passing JavaScript functions
* as C function pointers to ffi calls. * as C function pointers to ffi calls.
* *
* The function pointer remains valid until the `close()` method is called. * The function pointer remains valid until the `close()` method is called.
@ -746,7 +768,9 @@ declare namespace Deno {
close(): void; close(): void;
} }
/** Opens a dynamic library and registers symbols /** **UNSTABLE**: Unsafe and new API, beware!
*
* Opens a dynamic library and registers symbols
* *
* @category FFI * @category FFI
*/ */
@ -760,7 +784,9 @@ declare namespace Deno {
cbreak: boolean; cbreak: boolean;
}; };
/** Set TTY to be under raw mode or not. In raw mode, characters are read and /** **UNSTABLE**: new API, yet to be vetted
*
* Set TTY to be under raw mode or not. In raw mode, characters are read and
* returned as is, without being processed. All special processing of * returned as is, without being processed. All special processing of
* characters by the terminal is disabled, including echoing input characters. * characters by the terminal is disabled, including echoing input characters.
* Reading from a TTY device in raw mode is faster than reading from a TTY * Reading from a TTY device in raw mode is faster than reading from a TTY
@ -782,7 +808,7 @@ declare namespace Deno {
options?: SetRawOptions, options?: SetRawOptions,
): void; ): void;
/** Needs investigation into high precision time. /** **UNSTABLE**: needs investigation into high precision time.
* *
* Synchronously changes the access (`atime`) and modification (`mtime`) times * Synchronously changes the access (`atime`) and modification (`mtime`) times
* of a file system object referenced by `path`. Given times are either in * of a file system object referenced by `path`. Given times are either in
@ -803,7 +829,7 @@ declare namespace Deno {
mtime: number | Date, mtime: number | Date,
): void; ): void;
/** Needs investigation into high precision time. /** **UNSTABLE**: needs investigation into high precision time.
* *
* Changes the access (`atime`) and modification (`mtime`) times of a file * Changes the access (`atime`) and modification (`mtime`) times of a file
* system object referenced by `path`. Given times are either in seconds * system object referenced by `path`. Given times are either in seconds
@ -837,7 +863,8 @@ declare namespace Deno {
}, },
>(opt: T): Process<T>; >(opt: T): Process<T>;
/** Additional consideration is still necessary around the permissions required. /** **UNSTABLE**: New API, yet to be vetted. Additional consideration is still
* necessary around the permissions required.
* *
* Get the `hostname` of the machine the Deno process is running on. * Get the `hostname` of the machine the Deno process is running on.
* *
@ -852,7 +879,8 @@ declare namespace Deno {
*/ */
export function hostname(): string; export function hostname(): string;
/** A custom HttpClient for use with `fetch`. /** **UNSTABLE**: New API, yet to be vetted.
* A custom HttpClient for use with `fetch`.
* *
* ```ts * ```ts
* const caCert = await Deno.readTextFile("./ca.pem"); * const caCert = await Deno.readTextFile("./ca.pem");
@ -867,7 +895,8 @@ declare namespace Deno {
close(): void; close(): void;
} }
/** The options used when creating a [HttpClient]. /** **UNSTABLE**: New API, yet to be vetted.
* The options used when creating a [HttpClient].
* *
* @category Fetch API * @category Fetch API
*/ */
@ -897,7 +926,8 @@ declare namespace Deno {
password: string; password: string;
} }
/** Create a custom HttpClient for to use with `fetch`. /** **UNSTABLE**: New API, yet to be vetted.
* Create a custom HttpClient for to use with `fetch`.
* *
* ```ts * ```ts
* const caCert = await Deno.readTextFile("./ca.pem"); * const caCert = await Deno.readTextFile("./ca.pem");
@ -916,7 +946,7 @@ declare namespace Deno {
options: CreateHttpClientOptions, options: CreateHttpClientOptions,
): HttpClient; ): HttpClient;
/** Needs investigation into high precision time. /** **UNSTABLE**: needs investigation into high precision time.
* *
* Synchronously changes the access (`atime`) and modification (`mtime`) times * Synchronously changes the access (`atime`) and modification (`mtime`) times
* of a file stream resource referenced by `rid`. Given times are either in * of a file stream resource referenced by `rid`. Given times are either in
@ -935,7 +965,7 @@ declare namespace Deno {
mtime: number | Date, mtime: number | Date,
): void; ): void;
/** Needs investigation into high precision time. /** **UNSTABLE**: needs investigation into high precision time.
* *
* Changes the access (`atime`) and modification (`mtime`) times of a file * Changes the access (`atime`) and modification (`mtime`) times of a file
* stream resource referenced by `rid`. Given times are either in seconds * stream resource referenced by `rid`. Given times are either in seconds
@ -954,16 +984,24 @@ declare namespace Deno {
mtime: number | Date, mtime: number | Date,
): Promise<void>; ): Promise<void>;
/** A generic transport listener for message-oriented protocols. /** **UNSTABLE**: new API, yet to be vetted.
*
* A generic transport listener for message-oriented protocols.
* *
* @category Network * @category Network
*/ */
export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> { export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> {
/** Waits for and resolves to the next message to the `UDPConn`. */ /** **UNSTABLE**: new API, yet to be vetted.
*
* Waits for and resolves to the next message to the `UDPConn`. */
receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>; receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>;
/** Sends a message to the target. */ /** UNSTABLE: new API, yet to be vetted.
*
* Sends a message to the target. */
send(p: Uint8Array, addr: Addr): Promise<number>; send(p: Uint8Array, addr: Addr): Promise<number>;
/** Close closes the socket. Any pending message promises will be rejected /** UNSTABLE: new API, yet to be vetted.
*
* Close closes the socket. Any pending message promises will be rejected
* with errors. */ * with errors. */
close(): void; close(): void;
/** Return the address of the `UDPConn`. */ /** Return the address of the `UDPConn`. */
@ -977,7 +1015,8 @@ declare namespace Deno {
path: string; path: string;
} }
/** /** **UNSTABLE**: new API, yet to be vetted.
*
* Listen announces on the local transport address. * Listen announces on the local transport address.
* *
* ```ts * ```ts
@ -993,7 +1032,9 @@ declare namespace Deno {
options: UnixListenOptions & { transport: "unix" }, options: UnixListenOptions & { transport: "unix" },
): Listener; ): Listener;
/** Listen announces on the local transport address. /** **UNSTABLE**: new API, yet to be vetted
*
* Listen announces on the local transport address.
* *
* ```ts * ```ts
* const listener1 = Deno.listenDatagram({ * const listener1 = Deno.listenDatagram({
@ -1016,7 +1057,9 @@ declare namespace Deno {
options: ListenOptions & { transport: "udp" }, options: ListenOptions & { transport: "udp" },
): DatagramConn; ): DatagramConn;
/** Listen announces on the local transport address. /** **UNSTABLE**: new API, yet to be vetted
*
* Listen announces on the local transport address.
* *
* ```ts * ```ts
* const listener = Deno.listenDatagram({ * const listener = Deno.listenDatagram({
@ -1040,7 +1083,8 @@ declare namespace Deno {
path: string; path: string;
} }
/** The TCP transport is considered stable. /** **UNSTABLE**: The unix socket transport is unstable as a new API yet to
* be vetted. The TCP transport is considered stable.
* *
* Connects to the hostname (default is "127.0.0.1") and port on the named * Connects to the hostname (default is "127.0.0.1") and port on the named
* transport (default is "tcp"), and resolves to the connection (`Conn`). * transport (default is "tcp"), and resolves to the connection (`Conn`).
@ -1071,7 +1115,9 @@ declare namespace Deno {
certChain?: string; certChain?: string;
/** PEM formatted (RSA or PKCS8) private key of client certificate. */ /** PEM formatted (RSA or PKCS8) private key of client certificate. */
privateKey?: string; privateKey?: string;
/** Application-Layer Protocol Negotiation (ALPN) protocols supported by /** **UNSTABLE**: new API, yet to be vetted.
*
* Application-Layer Protocol Negotiation (ALPN) protocols supported by
* the client. If not specified, no ALPN extension will be included in the * the client. If not specified, no ALPN extension will be included in the
* TLS handshake. * TLS handshake.
*/ */
@ -1080,7 +1126,9 @@ declare namespace Deno {
/** @category Network */ /** @category Network */
export interface TlsHandshakeInfo { export interface TlsHandshakeInfo {
/** Contains the ALPN protocol selected during negotiation with the server. /** **UNSTABLE**: new API, yet to be vetted.
*
* Contains the ALPN protocol selected during negotiation with the server.
* If no ALPN protocol selected, returns `null`. * If no ALPN protocol selected, returns `null`.
*/ */
alpnProtocol: string | null; alpnProtocol: string | null;
@ -1094,7 +1142,9 @@ declare namespace Deno {
handshake(): Promise<TlsHandshakeInfo>; handshake(): Promise<TlsHandshakeInfo>;
} }
/** Create a TLS connection with an attached client certificate. /** **UNSTABLE** New API, yet to be vetted.
*
* Create a TLS connection with an attached client certificate.
* *
* ```ts * ```ts
* const conn = await Deno.connectTls({ * const conn = await Deno.connectTls({
@ -1114,7 +1164,9 @@ declare namespace Deno {
/** @category Network */ /** @category Network */
export interface ListenTlsOptions { export interface ListenTlsOptions {
/** Application-Layer Protocol Negotiation (ALPN) protocols to announce to /** **UNSTABLE**: new API, yet to be vetted.
*
* Application-Layer Protocol Negotiation (ALPN) protocols to announce to
* the client. If not specified, no ALPN extension will be included in the * the client. If not specified, no ALPN extension will be included in the
* TLS handshake. * TLS handshake.
*/ */
@ -1123,7 +1175,9 @@ declare namespace Deno {
/** @category Network */ /** @category Network */
export interface StartTlsOptions { export interface StartTlsOptions {
/** Application-Layer Protocol Negotiation (ALPN) protocols to announce to /** **UNSTABLE**: new API, yet to be vetted.
*
* Application-Layer Protocol Negotiation (ALPN) protocols to announce to
* the client. If not specified, no ALPN extension will be included in the * the client. If not specified, no ALPN extension will be included in the
* TLS handshake. * TLS handshake.
*/ */
@ -1132,49 +1186,66 @@ declare namespace Deno {
/** @category Network */ /** @category Network */
export interface Listener extends AsyncIterable<Conn> { export interface Listener extends AsyncIterable<Conn> {
/** Make the listener block the event loop from finishing. /** **UNSTABLE**: new API, yet to be vetted.
*
* Make the listener block the event loop from finishing.
* *
* Note: the listener blocks the event loop from finishing by default. * Note: the listener blocks the event loop from finishing by default.
* This method is only meaningful after `.unref()` is called. * This method is only meaningful after `.unref()` is called.
*/ */
ref(): void; ref(): void;
/** Make the listener not block the event loop from finishing. */ /** **UNSTABLE**: new API, yet to be vetted.
*
* Make the listener not block the event loop from finishing.
*/
unref(): void; unref(): void;
} }
/** Acquire an advisory file-system lock for the provided file. `exclusive` /** **UNSTABLE**: New API should be tested first.
*
* Acquire an advisory file-system lock for the provided file. `exclusive`
* defaults to `false`. * defaults to `false`.
* *
* @category File System * @category File System
*/ */
export function flock(rid: number, exclusive?: boolean): Promise<void>; export function flock(rid: number, exclusive?: boolean): Promise<void>;
/** Acquire an advisory file-system lock for the provided file. `exclusive` /** **UNSTABLE**: New API should be tested first.
*
* Acquire an advisory file-system lock for the provided file. `exclusive`
* defaults to `false`. * defaults to `false`.
* *
* @category File System * @category File System
*/ */
export function flockSync(rid: number, exclusive?: boolean): void; export function flockSync(rid: number, exclusive?: boolean): void;
/** Release an advisory file-system lock for the provided file. /** **UNSTABLE**: New API should be tested first.
*
* Release an advisory file-system lock for the provided file.
* *
* @category File System * @category File System
*/ */
export function funlock(rid: number): Promise<void>; export function funlock(rid: number): Promise<void>;
/** Release an advisory file-system lock for the provided file. /** **UNSTABLE**: New API should be tested first.
*
* Release an advisory file-system lock for the provided file.
* *
* @category File System * @category File System
*/ */
export function funlockSync(rid: number): void; export function funlockSync(rid: number): void;
/** Make the timer of the given id blocking the event loop from finishing. /** **UNSTABLE**: new API, yet to be vetted.
*
* Make the timer of the given id blocking the event loop from finishing.
* *
* @category Timers * @category Timers
*/ */
export function refTimer(id: number): void; export function refTimer(id: number): void;
/** Make the timer of the given id not blocking the event loop from finishing. /** **UNSTABLE**: new API, yet to be vetted.
*
* Make the timer of the given id not blocking the event loop from finishing.
* *
* @category Timers * @category Timers
*/ */
@ -1224,7 +1295,9 @@ declare namespace Deno {
handler: ServeHandler; handler: ServeHandler;
} }
/** Serves HTTP requests with the given handler. /** **UNSTABLE**: new API, yet to be vetted.
*
* Serves HTTP requests with the given handler.
* *
* You can specify an object with a port and hostname option, which is the * You can specify an object with a port and hostname option, which is the
* address to listen on. The default is port 9000 on hostname "127.0.0.1". * address to listen on. The default is port 9000 on hostname "127.0.0.1".
@ -1293,7 +1366,9 @@ declare namespace Deno {
options: ServeInit & (ServeOptions | ServeTlsOptions), options: ServeInit & (ServeOptions | ServeTlsOptions),
): Promise<void>; ): Promise<void>;
/** Allows "hijacking" the connection that the request is associated with. /** **UNSTABLE**: new API, yet to be vetted.
*
* Allows "hijacking" the connection that the request is associated with.
* This can be used to implement protocols that build on top of HTTP (eg. * This can be used to implement protocols that build on top of HTTP (eg.
* WebSockets). * WebSockets).
* *
@ -1319,7 +1394,9 @@ declare namespace Deno {
request: Request, request: Request,
): Promise<[Deno.Conn, Uint8Array]>; ): Promise<[Deno.Conn, Uint8Array]>;
/** Allows "hijacking" the connection that the request is associated with. /** **UNSTABLE**: new API, yet to be vetted.
*
* Allows "hijacking" the connection that the request is associated with.
* This can be used to implement protocols that build on top of HTTP (eg. * This can be used to implement protocols that build on top of HTTP (eg.
* WebSockets). * WebSockets).
@ -1504,7 +1581,9 @@ declare function fetch(
/** @category Web Workers */ /** @category Web Workers */
declare interface WorkerOptions { declare interface WorkerOptions {
/** Configure permissions options to change the level of access the worker will /** UNSTABLE: New API.
*
* Configure permissions options to change the level of access the worker will
* have. By default it will have no permissions. Note that the permissions * have. By default it will have no permissions. Note that the permissions
* of a worker can't be extended beyond its parent's permissions reach. * of a worker can't be extended beyond its parent's permissions reach.
* - "inherit" will take the permissions of the thread the worker is created in * - "inherit" will take the permissions of the thread the worker is created in