diff options
Diffstat (limited to 'cli/dts')
| -rw-r--r-- | cli/dts/lib.deno.ns.d.ts | 713 | ||||
| -rw-r--r-- | cli/dts/lib.deno.unstable.d.ts | 852 |
2 files changed, 1219 insertions, 346 deletions
diff --git a/cli/dts/lib.deno.ns.d.ts b/cli/dts/lib.deno.ns.d.ts index 1d72e1438..22f0409fe 100644 --- a/cli/dts/lib.deno.ns.d.ts +++ b/cli/dts/lib.deno.ns.d.ts @@ -3669,25 +3669,60 @@ declare namespace Deno { */ export type PermissionState = "granted" | "denied" | "prompt"; - /** @category Permissions */ + /** The permission descriptor for the `allow-run` permission, which controls + * access to what sub-processes can be executed by Deno. The option `command` + * allows scoping the permission to a specific executable. + * + * **Warning, in practice, `allow-run` is effectively the same as `allow-all` + * in the sense that malicious code could execute any arbitrary code on the + * host.** + * + * @category Permissions */ export interface RunPermissionDescriptor { name: "run"; + /** The `allow-run` permission can be scoped to a specific executable, + * which would be relative to the start-up CWD of the Deno CLI. */ command?: string | URL; } - /** @category Permissions */ + /** The permission descriptor for the `allow-read` permissions, which controls + * access to reading resources from the local host. The option `path` allows + * scoping the permission to a specific path (and if the path is a directory + * any sub paths). + * + * Permission granted under `allow-read` only allows runtime code to attempt + * to read, the underlying operating system may apply additional permissions. + * + * @category Permissions */ export interface ReadPermissionDescriptor { name: "read"; + /** The `allow-read` permission can be scoped to a specific path (and if + * the path is a directory, any sub paths). */ path?: string | URL; } - /** @category Permissions */ + /** The permission descriptor for the `allow-write` permissions, which + * controls access to writing to resources from the local host. The option + * `path` allow scoping the permission to a specific path (and if the path is + * a directory any sub paths). + * + * Permission granted under `allow-write` only allows runtime code to attempt + * to write, the underlying operating system may apply additional permissions. + * + * @category Permissions */ export interface WritePermissionDescriptor { name: "write"; + /** The `allow-write` permission can be scoped to a specific path (and if + * the path is a directory, any sub paths). */ path?: string | URL; } - /** @category Permissions */ + /** The permission descriptor for the `allow-net` permissions, which controls + * access to opening network ports and connecting to remote hosts via the + * network. The option `host` allows scoping the permission for outbound + * connection to a specific host and port. + * + * @category Permissions */ export interface NetPermissionDescriptor { name: "net"; /** Optional host string of the form `"<hostname>[:<port>]"`. Examples: @@ -3698,15 +3733,28 @@ declare namespace Deno { host?: string; } - /** @category Permissions */ + /** The permission descriptor for the `allow-env` permissions, which controls + * access to being able to read and write to the process environment variables + * as well as access other information about the environment. The option + * `variable` allows scoping the permission to a specific environment + * variable. + * + * @category Permissions */ export interface EnvPermissionDescriptor { name: "env"; + /** Optional environment variable name (e.g. `PATH`). */ variable?: string; } - /** @category Permissions */ + /** The permission descriptor for the `allow-sys` permissions, which controls + * access to sensitive host system information, which malicious code might + * attempt to exploit. The option `kind` allows scoping the permission to a + * specific piece of information. + * + * @category Permissions */ export interface SysPermissionDescriptor { name: "sys"; + /** The specific information to scope the permission to. */ kind?: | "loadavg" | "hostname" @@ -3717,13 +3765,26 @@ declare namespace Deno { | "getGid"; } - /** @category Permissions */ + /** The permission descriptor for the `allow-ffi` permissions, which controls + * access to loading _foreign_ code and interfacing with it via the + * [Foreign Function Interface API](https://deno.land/manual/runtime/ffi_api) + * available in Deno. The option `path` allows scoping the permission to a + * specific path on the host. + * + * @category Permissions */ export interface FfiPermissionDescriptor { name: "ffi"; + /** Optional path on the local host to scope the permission to. */ path?: string | URL; } - /** @category Permissions */ + /** The permission descriptor for the `allow-hrtime` permission, which + * controls if the runtime code has access to high resolution time. High + * resolution time is consider sensitive information, because it can be used + * by malicious code to gain information about the host that it might + * otherwise have access to. + * + * @category Permissions */ export interface HrtimePermissionDescriptor { name: "hrtime"; } @@ -3731,6 +3792,9 @@ declare namespace Deno { /** Permission descriptors which define a permission and can be queried, * requested, or revoked. * + * View the specifics of the individual descriptors for more information about + * each permission kind. + * * @category Permissions */ export type PermissionDescriptor = @@ -3743,12 +3807,18 @@ declare namespace Deno { | FfiPermissionDescriptor | HrtimePermissionDescriptor; - /** @category Permissions */ + /** The interface which defines what event types are supported by + * {@linkcode PermissionStatus} instances. + * + * @category Permissions */ export interface PermissionStatusEventMap { "change": Event; } - /** @category Permissions */ + /** An {@linkcode EventTarget} returned from the {@linkcode Deno.permissions} + * API which can provide updates to any state changes of the permission. + * + * @category Permissions */ export class PermissionStatus extends EventTarget { // deno-lint-ignore no-explicit-any onchange: ((this: PermissionStatus, ev: Event) => any) | null; @@ -3781,10 +3851,35 @@ declare namespace Deno { ): void; } - /** @category Permissions */ + /** + * Deno's permission management API. + * + * The class which provides the interface for the {@linkcode Deno.permissions} + * global instance and is based on the web platform + * [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API), + * though some proposed parts of the API which are useful in a server side + * runtime context were removed or abandoned in the web platform specification + * which is why it was chosen to locate it in the {@linkcode Deno} namespace + * instead. + * + * By default, if the `stdin`/`stdout` is TTY for the Deno CLI (meaning it can + * send and receive text), then the CLI will prompt the user to grant + * permission when an un-granted permission is requested. This behavior can + * be changed by using the `--no-prompt` command at startup. When prompting + * the CLI will request the narrowest permission possible, potentially making + * it annoying to the user. The permissions APIs allow the code author to + * request a wider set of permissions at one time in order to provide a better + * user experience. + * + * @category Permissions */ export class Permissions { /** Resolves to the current status of a permission. * + * Note, if the permission is already granted, `request()` will not prompt + * the user again, therefore `query()` is only necessary if you are going + * to react differently existing permissions without wanting to modify them + * or prompt the user to modify them. + * * ```ts * const status = await Deno.permissions.query({ name: "read", path: "/etc" }); * console.log(status.state); @@ -3805,6 +3900,9 @@ declare namespace Deno { /** Requests the permission, and resolves to the state of the permission. * + * If the permission is already granted, the user will not be prompted to + * grant the permission again. + * * ```ts * const status = await Deno.permissions.request({ name: "env" }); * if (status.state === "granted") { @@ -3819,48 +3917,127 @@ declare namespace Deno { /** Deno's permission management API. * + * It is a singleton instance of the {@linkcode Permissions} object and is + * based on the web platform + * [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API), + * though some proposed parts of the API which are useful in a server side + * runtime context were removed or abandoned in the web platform specification + * which is why it was chosen to locate it in the {@linkcode Deno} namespace + * instead. + * + * By default, if the `stdin`/`stdout` is TTY for the Deno CLI (meaning it can + * send and receive text), then the CLI will prompt the user to grant + * permission when an un-granted permission is requested. This behavior can + * be changed by using the `--no-prompt` command at startup. When prompting + * the CLI will request the narrowest permission possible, potentially making + * it annoying to the user. The permissions APIs allow the code author to + * request a wider set of permissions at one time in order to provide a better + * user experience. + * + * Requesting already granted permissions will not prompt the user and will + * return that the permission was granted. + * + * ### Querying + * + * ```ts + * const status = await Deno.permissions.query({ name: "read", path: "/etc" }); + * console.log(status.state); + * ``` + * + * ### Revoking + * + * ```ts + * import { assert } from "https://deno.land/std/testing/asserts.ts"; + * + * const status = await Deno.permissions.revoke({ name: "run" }); + * assert(status.state !== "granted") + * ``` + * + * ### Requesting + * + * ```ts + * const status = await Deno.permissions.request({ name: "env" }); + * if (status.state === "granted") { + * console.log("'env' permission is granted."); + * } else { + * console.log("'env' permission is denied."); + * } + * ``` + * * @category Permissions */ export const permissions: Permissions; - /** Build related information. + /** Information related to the build of the current Deno runtime. + * + * Users are discouraged from code branching based on this information, as + * assumptions about what is available in what build environment might change + * over time. Developers should specifically sniff out the features they + * intend to use. + * + * The intended use for the information is for logging and debugging purposes. * * @category Runtime Environment */ export const build: { - /** The LLVM target triple */ + /** The [LLVM](https://llvm.org/) target triple, which is the combination + * of `${arch}-${vendor}-${os}` and represent the specific build target that + * the current runtime was built for. */ target: string; - /** Instruction set architecture */ + /** Instruction set architecture that the Deno CLI was built for. */ arch: "x86_64" | "aarch64"; - /** Operating system */ + /** The operating system that the Deno CLI was built for. `"darwin"` is + * also known as OSX or MacOS. */ os: "darwin" | "linux" | "windows"; - /** Computer vendor */ + /** The computer vendor that the Deno CLI was built for. */ vendor: string; - /** Optional environment */ + /** Optional environment flags that were set for this build of Deno CLI. */ env?: string; }; - /** Version related information. + /** Version information related to the current Deno CLI runtime environment. + * + * Users are discouraged from code branching based on this information, as + * assumptions about what is available in what build environment might change + * over time. Developers should specifically sniff out the features they + * intend to use. + * + * The intended use for the information is for logging and debugging purposes. * * @category Runtime Environment */ export const version: { - /** Deno's version. For example: `"1.0.0"` */ + /** Deno CLI's version. For example: `"1.26.0"`. */ deno: string; - /** The V8 version used by Deno. For example: `"8.0.0.0"` */ + /** The V8 version used by Deno. For example: `"10.7.100.0"`. + * + * V8 is the underlying JavaScript runtime platform that Deno is built on + * top of. */ v8: string; - /** The TypeScript version used by Deno. For example: `"4.0.0"` */ + /** The TypeScript version used by Deno. For example: `"4.8.3"`. + * + * A version of the TypeScript type checker and language server is built-in + * to the Deno CLI. */ typescript: string; }; - /** Returns the script arguments to the program. If for example we run a - * program: + /** Returns the script arguments to the program. + * + * Give the following command line invocation of Deno: * + * ```sh * deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd + * ``` * * Then `Deno.args` will contain: * + * ``` * [ "/etc/passwd" ] + * ``` + * + * If you are looking for a structured way to parse arguments, there is the + * [`std/flags`](https://deno.land/std/flags) module as part of the Deno + * standard library. * * @category Runtime Environment */ @@ -3878,25 +4055,34 @@ declare namespace Deno { */ export const customInspect: unique symbol; - /** The URL of the entrypoint module entered from the command-line. + /** The URL of the entrypoint module entered from the command-line. It + * requires read permission to the CWD. + * + * Also see {@linkcode ImportMeta} for other related information. * + * @tags allow-read * @category Runtime Environment */ export const mainModule: string; - /** @category File System */ - export type SymlinkOptions = { + /** Options that can be used with {@linkcode symlink} and + * {@linkcode symlinkSync}. + * + * @category File System */ + export interface SymlinkOptions { + /** If the symbolic link should be either a file or directory. This option + * only applies to Windows and is ignored on other operating systems. */ type: "file" | "dir"; - }; + } /** * Creates `newpath` as a symbolic link to `oldpath`. * - * The options.type parameter can be set to `file` or `dir`. This argument is only - * available on Windows and ignored on other platforms. + * The `options.type` parameter can be set to `"file"` or `"dir"`. This + * argument is only available on Windows and ignored on other platforms. * * ```ts - * Deno.symlinkSync("old/name", "new/name"); + * await Deno.symlink("old/name", "new/name"); * ``` * * Requires full `allow-read` and `allow-write` permissions. @@ -3904,20 +4090,20 @@ declare namespace Deno { * @tags allow-read, allow-write * @category File System */ - export function symlinkSync( + export function symlink( oldpath: string | URL, newpath: string | URL, options?: SymlinkOptions, - ): void; + ): Promise<void>; /** * Creates `newpath` as a symbolic link to `oldpath`. * - * The options.type parameter can be set to `file` or `dir`. This argument is only - * available on Windows and ignored on other platforms. + * The `options.type` parameter can be set to `"file"` or `"dir"`. This + * argument is only available on Windows and ignored on other platforms. * * ```ts - * await Deno.symlink("old/name", "new/name"); + * Deno.symlinkSync("old/name", "new/name"); * ``` * * Requires full `allow-read` and `allow-write` permissions. @@ -3925,71 +4111,94 @@ declare namespace Deno { * @tags allow-read, allow-write * @category File System */ - export function symlink( + export function symlinkSync( oldpath: string | URL, newpath: string | URL, options?: SymlinkOptions, - ): Promise<void>; + ): void; /** - * Synchronously truncates or extends the specified file stream, to reach the - * specified `len`. + * Truncates or extends the specified file stream, to reach the specified + * `len`. * - * If `len` is not specified then the entire file contents are truncated as if len was set to 0. + * If `len` is not specified then the entire file contents are truncated as if + * `len` was set to `0`. * - * if the file previously was larger than this new length, the extra data is lost. + * If the file previously was larger than this new length, the extra data is + * lost. * - * if the file previously was shorter, it is extended, and the extended part reads as null bytes ('\0'). + * If the file previously was shorter, it is extended, and the extended part + * reads as null bytes ('\0'). + * + * ### Truncate the entire file * * ```ts - * // truncate the entire file - * const file = Deno.openSync("my_file.txt", { read: true, write: true, truncate: true, create: true }); - * Deno.ftruncateSync(file.rid); + * const file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true } + * ); + * await Deno.ftruncate(file.rid); * ``` * + * ### Truncate part of the file + * * ```ts - * // truncate part of the file - * const file = Deno.openSync("my_file.txt", { read: true, write: true, create: true }); - * Deno.writeSync(file.rid, new TextEncoder().encode("Hello World")); - * Deno.ftruncateSync(file.rid, 7); - * Deno.seekSync(file.rid, 0, Deno.SeekMode.Start); + * const file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true } + * ); + * await Deno.write(file.rid, new TextEncoder().encode("Hello World")); + * await Deno.ftruncate(file.rid, 7); * const data = new Uint8Array(32); - * Deno.readSync(file.rid, data); + * await Deno.read(file.rid, data); * console.log(new TextDecoder().decode(data)); // Hello W * ``` * * @category File System */ - export function ftruncateSync(rid: number, len?: number): void; + export function ftruncate(rid: number, len?: number): Promise<void>; /** - * Truncates or extends the specified file stream, to reach the specified `len`. + * Synchronously truncates or extends the specified file stream, to reach the + * specified `len`. * - * If `len` is not specified then the entire file contents are truncated as if len was set to 0. + * If `len` is not specified then the entire file contents are truncated as if + * `len` was set to `0`. * - * If the file previously was larger than this new length, the extra data is lost. + * If the file previously was larger than this new length, the extra data is + * lost. * - * If the file previously was shorter, it is extended, and the extended part reads as null bytes ('\0'). + * If the file previously was shorter, it is extended, and the extended part + * reads as null bytes ('\0'). + * + * ### Truncate the entire file * * ```ts - * // truncate the entire file - * const file = await Deno.open("my_file.txt", { read: true, write: true, create: true }); - * await Deno.ftruncate(file.rid); + * const file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, truncate: true, create: true } + * ); + * Deno.ftruncateSync(file.rid); * ``` * + * ### Truncate part of the file + * * ```ts - * // truncate part of the file - * const file = await Deno.open("my_file.txt", { read: true, write: true, create: true }); - * await Deno.write(file.rid, new TextEncoder().encode("Hello World")); - * await Deno.ftruncate(file.rid, 7); + * const file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, create: true } + * ); + * Deno.writeSync(file.rid, new TextEncoder().encode("Hello World")); + * Deno.ftruncateSync(file.rid, 7); + * Deno.seekSync(file.rid, 0, Deno.SeekMode.Start); * const data = new Uint8Array(32); - * await Deno.read(file.rid, data); + * Deno.readSync(file.rid, data); * console.log(new TextDecoder().decode(data)); // Hello W * ``` * * @category File System */ - export function ftruncate(rid: number, len?: number): Promise<void>; + export function ftruncateSync(rid: number, len?: number): void; /** * Synchronously changes the access (`atime`) and modification (`mtime`) times @@ -4028,32 +4237,35 @@ declare namespace Deno { ): Promise<void>; /** - * Synchronously returns a `Deno.FileInfo` for the given file stream. + * Returns a `Deno.FileInfo` for the given file stream. * * ```ts * import { assert } from "https://deno.land/std/testing/asserts.ts"; - * const file = Deno.openSync("file.txt", { read: true }); - * const fileInfo = Deno.fstatSync(file.rid); + * + * const file = await Deno.open("file.txt", { read: true }); + * const fileInfo = await Deno.fstat(file.rid); * assert(fileInfo.isFile); * ``` * * @category File System */ - export function fstatSync(rid: number): FileInfo; + export function fstat(rid: number): Promise<FileInfo>; /** - * Returns a `Deno.FileInfo` for the given file stream. + * Synchronously returns a {@linkcode Deno.FileInfo} for the given file + * stream. * * ```ts * import { assert } from "https://deno.land/std/testing/asserts.ts"; - * const file = await Deno.open("file.txt", { read: true }); - * const fileInfo = await Deno.fstat(file.rid); + * + * const file = Deno.openSync("file.txt", { read: true }); + * const fileInfo = Deno.fstatSync(file.rid); * assert(fileInfo.isFile); * ``` * * @category File System */ - export function fstat(rid: number): Promise<FileInfo>; + export function fstatSync(rid: number): FileInfo; /** * Synchronously changes the access (`atime`) and modification (`mtime`) times @@ -4095,22 +4307,52 @@ declare namespace Deno { mtime: number | Date, ): Promise<void>; - /** @category HTTP Server */ + /** The event yielded from an {@linkcode HttpConn} which represents an HTTP + * request from a remote client. + * + * @category HTTP Server */ export interface RequestEvent { + /** The request from the client in the form of the web platform + * {@linkcode Request}. */ readonly request: Request; - respondWith(r: Response | Promise<Response>): Promise<void>; + /** The method to be used to respond to the event. The response needs to + * either be an instance of {@linkcode Response} or a promise that resolves + * with an instance of `Response`. + * + * When the response is successfully processed then the promise returned + * will be resolved. If there are any issues with sending the response, + * the promise will be rejected. */ + respondWith(r: Response | PromiseLike<Response>): Promise<void>; } - /** @category HTTP Server */ + /** The async iterable that is returned from {@linkcode Deno.serveHttp} which + * yields up {@linkcode RequestEvent} events, representing individual + * requests on the HTTP server connection. + * + * @category HTTP Server */ export interface HttpConn extends AsyncIterable<RequestEvent> { + /** The resource ID associated with this connection. Generally users do not + * need to be aware of this identifier. */ readonly rid: number; + /** An alternative to the async iterable interface which provides promises + * which resolve with either a {@linkcode RequestEvent} when there is + * another request or `null` when the client has closed the connection. */ nextRequest(): Promise<RequestEvent | null>; + /** Initiate a server side closure of the connection, indicating to the + * client that you refuse to accept any more requests on this connection. + * + * Typically the client closes the connection, which will result in the + * async iterable terminating or the `nextRequest()` method returning + * `null`. */ close(): void; } /** - * Services HTTP requests given a TCP or TLS socket. + * Provides an interface to handle HTTP request and responses over TCP or TLS + * connections. The method returns an {@linkcode HttpConn} which yields up + * {@linkcode RequestEvent} events, which utilize the web platform standard + * {@linkcode Request} and {@linkcode Response} objects to handle the request. * * ```ts * const conn = Deno.listen({ port: 80 }); @@ -4121,10 +4363,7 @@ declare namespace Deno { * } * ``` * - * If `httpConn.nextRequest()` encounters an error or returns `null` - * then the underlying HttpConn resource is closed automatically. - * - * Alternatively, you can also use the Async Iterator approach: + * Alternatively, you can also use the async iterator approach: * * ```ts * async function handleHttp(conn: Deno.Conn) { @@ -4138,10 +4377,18 @@ declare namespace Deno { * } * ``` * - * Note that this function *consumes* the given connection passed to it, thus the - * original connection will be unusable after calling this. Additionally, you - * need to ensure that the connection is not being used elsewhere when calling - * this function in order for the connection to be consumed properly. + * If `httpConn.nextRequest()` encounters an error or returns `null` then the + * underlying {@linkcode HttpConn} resource is closed automatically. + * + * Also see the experimental Flash HTTP server {@linkcode Deno.serve} which + * provides a ground up rewrite of handling of HTTP requests and responses + * within the Deno CLI. + * + * Note that this function *consumes* the given connection passed to it, thus + * the original connection will be unusable after calling this. Additionally, + * you need to ensure that the connection is not being used elsewhere when + * calling this function in order for the connection to be consumed properly. + * * For instance, if there is a `Promise` that is waiting for read operation on * the connection to complete, it is considered that the connection is being * used elsewhere. In such a case, this function will fail. @@ -4150,31 +4397,45 @@ declare namespace Deno { */ export function serveHttp(conn: Conn): HttpConn; - /** @category Web Sockets */ + /** The object that is returned from a {@linkcode Deno.upgradeWebSocket} + * request. + * + * @category Web Sockets */ export interface WebSocketUpgrade { + /** The response object that represents the HTTP response to the client, + * which should be used to the {@linkcode RequestEvent} `.respondWith()` for + * the upgrade to be successful. */ response: Response; + /** The {@linkcode WebSocket} interface to communicate to the client via a + * web socket. */ socket: WebSocket; } - /** @category Web Sockets */ + /** Options which can be set when performing a + * {@linkcode Deno.upgradeWebSocket} upgrade of a {@linkcode Request} + * + * @category Web Sockets */ export interface UpgradeWebSocketOptions { + /** Sets the `.protocol` property on the client side web socket to the + * value provided here, which should be one of the strings specified in the + * `protocols` parameter when requesting the web socket. This is intended + * for clients and servers to specify sub-protocols to use to communicate to + * each other. */ protocol?: string; - /** - * If the client does not respond to this frame with a + /** If the client does not respond to this frame with a * `pong` within the timeout specified, the connection is deemed * unhealthy and is closed. The `close` and `error` event will be emitted. * - * The default is 120 seconds. Set to 0 to disable timeouts. - */ + * The default is 120 seconds. Set to `0` to disable timeouts. */ idleTimeout?: number; } /** - * Used to upgrade an incoming HTTP request to a WebSocket. + * Upgrade an incoming HTTP request to a WebSocket. * - * Given a request, returns a pair of WebSocket and Response. The original - * request must be responded to with the returned response for the websocket - * upgrade to be successful. + * Given a {@linkcode Request}, returns a pair of {@linkcode WebSocket} and + * {@linkcode Response} instances. The original request must be responded to + * with the returned response for the websocket upgrade to be successful. * * ```ts * const conn = Deno.listen({ port: 80 }); @@ -4199,7 +4460,7 @@ declare namespace Deno { * completed, upgrading fails. * * This operation does not yet consume the request or open the websocket. This - * only happens once the returned response has been passed to `respondWith`. + * only happens once the returned response has been passed to `respondWith()`. * * @category Web Sockets */ @@ -4208,11 +4469,16 @@ declare namespace Deno { options?: UpgradeWebSocketOptions, ): WebSocketUpgrade; - /** Send a signal to process under given `pid`. + /** Send a signal to process under given `pid`. The value and meaning of the + * `signal` to the process is operating system and process dependant. + * {@linkcode Signal} provides the most common signals. + * + * The term `kill` is adopted from the UNIX-like command line command `kill` + * which also signals processes. * * If `pid` is negative, the signal will be sent to the process group - * identified by `pid`. An error will be thrown if a negative - * `pid` is used on Windows. + * identified by `pid`. An error will be thrown if a negative `pid` is used on + * Windows. * * ```ts * const p = Deno.run({ @@ -4227,9 +4493,11 @@ declare namespace Deno { * @tags allow-run * @category Sub Process */ - export function kill(pid: number, signo: Signal): void; + export function kill(pid: number, signal: Signal): void; - /** The type of the resource record. + /** The type of the resource record to resolve via DNS using + * {@linkcode Deno.resolveDns}. + * * Only the listed types are supported currently. * * @category Network @@ -4248,45 +4516,62 @@ declare namespace Deno { | "SRV" | "TXT"; - /** @category Network */ + /** + * Options which can be set when using {@linkcode Deno.resolveDns}. + * + * @category Network */ export interface ResolveDnsOptions { /** The name server to be used for lookups. - * If not specified, defaults to the system configuration e.g. `/etc/resolv.conf` on Unix. */ + * + * If not specified, defaults to the system configuration. For example + * `/etc/resolv.conf` on Unix-like systems. */ nameServer?: { - /** The IP address of the name server */ + /** The IP address of the name server. */ ipAddr: string; /** The port number the query will be sent to. - * If not specified, defaults to 53. */ + * + * If not specified, defaults to `53`. */ port?: number; }; } - /** If `resolveDns` is called with "CAA" record type specified, it will return - * an array of this interface. + /** If {@linkcode Deno.resolveDns} is called with `"CAA"` record type + * specified, it will resolve with an array of objects with this interface. * * @category Network */ export interface CAARecord { + /** If `true`, indicates that the corresponding property tag **must** be + * understood if the semantics of the CAA record are to be correctly + * interpreted by an issuer. + * + * Issuers **must not** issue certificates for a domain if the relevant CAA + * Resource Record set contains unknown property tags that have `critical` + * set. */ critical: boolean; + /** An string that represents the identifier of the property represented by + * the record. */ tag: string; + /** The value associated with the tag. */ value: string; } - /** If `resolveDns` is called with "MX" record type specified, it will return - * an array of this interface. + /** If {@linkcode Deno.resolveDns} is called with `"MX"` record type + * specified, it will return an array of objects with this interface. * - * @category Network - */ + * @category Network */ export interface MXRecord { + /** A priority value, which is a relative value compared to the other + * preferences of MX records for the domain. */ preference: number; + /** The server that mail should be delivered to. */ exchange: string; } - /** If `resolveDns` is called with "NAPTR" record type specified, it will - * return an array of this interface. + /** If {@linkcode Deno.resolveDns} is called with `"NAPTR"` record type + * specified, it will return an array of objects with this interface. * - * @category Network - */ + * @category Network */ export interface NAPTRRecord { order: number; preference: number; @@ -4296,11 +4581,10 @@ declare namespace Deno { replacement: string; } - /** If `resolveDns` is called with "SOA" record type specified, it will return - * an array of this interface. + /** If {@linkcode Deno.resolveDns} is called with `"SOA"` record type + * specified, it will return an array of objects with this interface. * - * @category Network - */ + * @category Network */ export interface SOARecord { mname: string; rname: string; @@ -4311,8 +4595,8 @@ declare namespace Deno { minimum: number; } - /** If `resolveDns` is called with "SRV" record type specified, it will return - * an array of this interface. + /** If {@linkcode Deno.resolveDns} is called with `"SRV"` record type + * specified, it will return an array of objects with this interface. * * @category Network */ @@ -4323,49 +4607,210 @@ declare namespace Deno { target: string; } - /** @category Network */ + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ export function resolveDns( query: string, recordType: "A" | "AAAA" | "ANAME" | "CNAME" | "NS" | "PTR", options?: ResolveDnsOptions, ): Promise<string[]>; - /** @category Network */ + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ export function resolveDns( query: string, recordType: "CAA", options?: ResolveDnsOptions, ): Promise<CAARecord[]>; - /** @category Network */ + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ export function resolveDns( query: string, recordType: "MX", options?: ResolveDnsOptions, ): Promise<MXRecord[]>; - /** @category Network */ + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ export function resolveDns( query: string, recordType: "NAPTR", options?: ResolveDnsOptions, ): Promise<NAPTRRecord[]>; - /** @category Network */ + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ export function resolveDns( query: string, recordType: "SOA", options?: ResolveDnsOptions, ): Promise<SOARecord[]>; - /** @category Network */ + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ export function resolveDns( query: string, recordType: "SRV", options?: ResolveDnsOptions, ): Promise<SRVRecord[]>; - /** @category Network */ + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ export function resolveDns( query: string, recordType: "TXT", @@ -4373,11 +4818,15 @@ declare namespace Deno { ): Promise<string[][]>; /** - * Performs DNS resolution against the given query, returning resolved records. + * Performs DNS resolution against the given query, returning resolved + * records. + * * Fails in the cases such as: - * - the query is in invalid format - * - the options have an invalid parameter, e.g. `nameServer.port` is beyond the range of 16-bit unsigned integer - * - timed out + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. * * ```ts * const a = await Deno.resolveDns("example.com", "A"); diff --git a/cli/dts/lib.deno.unstable.d.ts b/cli/dts/lib.deno.unstable.d.ts index ba6d03c7e..cde76d4d8 100644 --- a/cli/dts/lib.deno.unstable.d.ts +++ b/cli/dts/lib.deno.unstable.d.ts @@ -8,28 +8,38 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * The interface for defining a benchmark test using {@linkcode Deno.bench}. + * * @category Testing */ export interface BenchDefinition { + /** The test function which will be benchmarked. */ fn: () => void | Promise<void>; + /** The name of the test, which will be used in displaying the results. */ name: string; + /** If truthy, the benchmark test will be ignored/skipped. */ ignore?: boolean; /** Group name for the benchmark. - * Grouped benchmarks produce a time summary */ + * + * Grouped benchmarks produce a group time summary, where the difference + * in performance between each test of the group is compared. */ group?: string; - /** Benchmark should be used as the baseline for other benchmarks - * If there are multiple baselines in a group, the first one is used as the baseline */ + /** Benchmark should be used as the baseline for other benchmarks. + * + * If there are multiple baselines in a group, the first one is used as the + * baseline. */ baseline?: boolean; /** If at least one bench has `only` set to true, only run benches that have - * `only` set to true and fail the bench suite. */ + * `only` set to `true` and fail the bench suite. */ only?: boolean; /** Ensure the bench case does not prematurely cause the process to exit, - * for example via a call to `Deno.exit`. Defaults to true. */ + * for example via a call to {@linkcode Deno.exit}. Defaults to `true`. */ sanitizeExit?: boolean; - /** Specifies the permissions that should be used to run the bench. - * Set this to "inherit" to keep the calling thread's permissions. - * Set this to "none" to revoke all permissions. + * + * Set this to `"inherit"` to keep the calling thread's permissions. + * + * Set this to `"none"` to revoke all permissions. * * Defaults to "inherit". */ @@ -38,15 +48,18 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * * Deno.bench({ * name: "example test", - * fn(): void { + * fn() { * assertEquals("world", "world"); * }, * }); @@ -54,7 +67,7 @@ declare namespace Deno { * Deno.bench({ * name: "example ignored test", * ignore: Deno.build.os === "windows", - * fn(): void { + * fn() { * // This test is ignored only on Windows machines * }, * }); @@ -75,18 +88,20 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * - * Deno.bench("My test description", (): void => { + * Deno.bench("My test description", () => { * assertEquals("hello", "hello"); * }); * - * Deno.bench("My async test description", async (): Promise<void> => { + * Deno.bench("My async test description", async () => { * const decoder = new TextDecoder("utf-8"); * const data = await Deno.readFile("hello_world.txt"); * assertEquals(decoder.decode(data), "Hello world"); @@ -102,18 +117,20 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. Declared function must have a name. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * - * Deno.bench(function myTestName(): void { + * Deno.bench(function myTestName() { * assertEquals("hello", "hello"); * }); * - * Deno.bench(async function myOtherTestName(): Promise<void> { + * Deno.bench(async function myOtherTestName() { * const decoder = new TextDecoder("utf-8"); * const data = await Deno.readFile("hello_world.txt"); * assertEquals(decoder.decode(data), "Hello world"); @@ -126,22 +143,32 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * - * Deno.bench("My test description", { permissions: { read: true } }, (): void => { - * assertEquals("hello", "hello"); - * }); + * Deno.bench( + * "My test description", + * { permissions: { read: true } }, + * () => { + * assertEquals("hello", "hello"); + * } + * ); * - * Deno.bench("My async test description", { permissions: { read: false } }, async (): Promise<void> => { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }); + * Deno.bench( + * "My async test description", + * { permissions: { read: false } }, + * async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); * ``` * * @category Testing @@ -154,22 +181,30 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * - * Deno.bench({ name: "My test description", permissions: { read: true } }, (): void => { - * assertEquals("hello", "hello"); - * }); + * Deno.bench( + * { name: "My test description", permissions: { read: true } }, + * () => { + * assertEquals("hello", "hello"); + * } + * ); * - * Deno.bench({ name: "My async test description", permissions: { read: false } }, async (): Promise<void> => { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }); + * Deno.bench( + * { name: "My async test description", permissions: { read: false } }, + * async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); * ``` * * @category Testing @@ -181,22 +216,30 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. Declared function must have a name. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * - * Deno.bench({ permissions: { read: true } }, function myTestName(): void { - * assertEquals("hello", "hello"); - * }); + * Deno.bench( + * { permissions: { read: true } }, + * function myTestName() { + * assertEquals("hello", "hello"); + * } + * ); * - * Deno.bench({ permissions: { read: false } }, async function myOtherTestName(): Promise<void> { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }); + * Deno.bench( + * { permissions: { read: false } }, + * async function myOtherTestName() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); * ``` * * @category Testing @@ -220,7 +263,7 @@ declare namespace Deno { * This API is under consideration to determine if permissions are required to * call it. * - * NOTE: This API is not implemented on Windows + * *Note*: This API is not implemented on Windows * * @category File System */ @@ -246,49 +289,52 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * Information returned from a call to {@linkcode Deno.systemMemoryInfo}. + * * @category Runtime Environment */ export interface SystemMemoryInfo { - /** Total installed memory */ + /** Total installed memory in bytes. */ total: number; - /** Unused memory */ + /** Unused memory in bytes. */ free: number; - /** Estimation of how much memory is available for starting new - * applications, without swapping. Unlike the data provided by the cache or + /** Estimation of how much memory, in bytes, is available for starting new + * applications, without swapping. Unlike the data provided by the cache or * free fields, this field takes into account page cache and also that not - * all reclaimable memory slabs will be reclaimed due to items being in use + * all reclaimable memory will be reclaimed due to items being in use. */ available: number; - /** Memory used by kernel buffers */ + /** Memory used by kernel buffers. */ buffers: number; - /** Memory used by the page cache and slabs */ + /** Memory used by the page cache and slabs. */ cached: number; - /** Total swap memory */ + /** Total swap memory. */ swapTotal: number; - /** Unused swap memory */ + /** Unused swap memory. */ swapFree: number; } /** **UNSTABLE**: New API, yet to be vetted. * - * The information of the network interface. + * The information for a network interface returned from a call to + * {@linkcode Deno.networkInterfaces}. * * @category Network */ export interface NetworkInterfaceInfo { - /** The network interface name */ + /** The network interface name. */ name: string; - /** The IP protocol version */ + /** The IP protocol version. */ family: "IPv4" | "IPv6"; - /** The IP address */ + /** The IP address bound to the interface. */ address: string; - /** The netmask */ + /** The netmask applied to the interface. */ netmask: string; - /** The IPv6 scope id or null */ + /** The IPv6 scope id or `null`. */ scopeid: number | null; - /** The CIDR range */ + /** The CIDR range. */ cidr: string; - /** The MAC address */ + /** The MAC address. */ mac: string; } @@ -309,7 +355,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Returns the user id of the process on POSIX platforms. Returns null on Windows. + * Returns the user id of the Deno process on POSIX platforms. Returns `null` + * on Windows. * * ```ts * console.log(Deno.getUid()); @@ -324,7 +371,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Returns the group id of the process on POSIX platforms. Returns null on windows. + * Returns the group id of the process on POSIX platforms. Returns `null` on + * Windows. * * ```ts * console.log(Deno.getGid()); @@ -367,37 +415,47 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * The native boolean type for interfacing to foreign functions. + * * @category FFI */ type NativeBooleanType = "bool"; /** **UNSTABLE**: New API, yet to be vetted. * + * The native pointer type for interfacing to foreign functions. + * * @category FFI */ type NativePointerType = "pointer"; /** **UNSTABLE**: New API, yet to be vetted. * + * The native buffer type for interfacing to foreign functions. + * * @category FFI */ type NativeBufferType = "buffer"; /** **UNSTABLE**: New API, yet to be vetted. * + * The native function type for interfacing with foreign functions. + * * @category FFI */ type NativeFunctionType = "function"; /** **UNSTABLE**: New API, yet to be vetted. * + * The native void type for interfacing with foreign functions. + * * @category FFI */ type NativeVoidType = "void"; /** **UNSTABLE**: New API, yet to be vetted. * - * All possible types for interfacing with foreign functions. + * All supported types for interfacing with foreign functions. * * @category FFI */ @@ -417,6 +475,9 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * A utility type conversion for foreign symbol parameters and unsafe callback + * return types. + * * @category FFI */ type ToNativeTypeMap = @@ -438,6 +499,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * A utility type for conversion for unsafe callback return types. + * * @category FFI */ type ToNativeResultTypeMap = ToNativeTypeMap & Record<NativeVoidType, void>; @@ -453,6 +516,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * A utility type for conversion of parameter types of foreign functions. + * * @category FFI */ type ToNativeParameterTypes<T extends readonly NativeType[]> = @@ -467,6 +532,9 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * A utility type for conversion of foreign symbol return types and unsafe + * callback parameters. + * * @category FFI */ type FromNativeTypeMap = @@ -488,6 +556,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * A utility type for conversion for foreign symbol return types. + * * @category FFI */ type FromNativeResultTypeMap = @@ -521,7 +591,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * A foreign function as defined by its parameter and result types. + * The interface for a foreign function as defined by its parameter and result + * types. * * @category FFI */ @@ -530,13 +601,21 @@ declare namespace Deno { Result extends NativeResultType = NativeResultType, NonBlocking extends boolean = boolean, > { - /** Name of the symbol, defaults to the key name in symbols object. */ + /** Name of the symbol. + * + * Defaults to the key name in symbols object. */ name?: string; + /** The parameters of the foreign function. */ parameters: Parameters; + /** The result (return value) of the foreign function. */ result: Result; - /** When true, function calls will run on a dedicated blocking thread and will return a Promise resolving to the `result`. */ + /** When `true`, function calls will run on a dedicated blocking thread and + * will return a `Promise` resolving to the `result`. */ nonblocking?: NonBlocking; - /** When true, function calls can safely callback into JS or trigger a GC event. Default is `false`. */ + /** When `true`, function calls can safely callback into JavaScript or + * trigger a garbage collection event. + * + * Default is `false`. */ callback?: boolean; } @@ -547,6 +626,7 @@ declare namespace Deno { export interface ForeignStatic<Type extends NativeType = NativeType> { /** Name of the symbol, defaults to the key name in symbols object. */ name?: string; + /** The type of the foreign static value. */ type: Type; } @@ -562,7 +642,7 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Infers a foreign symbol. + * A utility type that infers a foreign symbol. * * @category FFI */ @@ -597,7 +677,7 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Infers a foreign library interface. + * A utility type that infers a foreign library interface. * * @category FFI */ @@ -609,9 +689,9 @@ declare namespace Deno { * * Pointer type depends on the architecture and actual pointer value. * - * On a 32 bit system all pointer values are plain numbers. On a 64 bit - * system pointer values are represented as numbers if the value is below - * `Number.MAX_SAFE_INTEGER`. + * On a 32 bit host system all pointer values are plain numbers. On a 64 bit + * host system pointer values are represented as numbers if the value is below + * `Number.MAX_SAFE_INTEGER`, otherwise they are provided as bigints. * * @category FFI */ @@ -625,18 +705,16 @@ declare namespace Deno { * @category FFI */ export class UnsafePointer { - /** - * Return the direct memory pointer to the typed array in memory - */ + /** Return the direct memory pointer to the typed array in memory. */ static of(value: Deno.UnsafeCallback | BufferSource): PointerValue; } /** **UNSTABLE**: New API, yet to be vetted. * * An unsafe pointer view to a memory location as specified by the `pointer` - * value. The `UnsafePointerView` API mimics the standard built in interface - * `DataView` for accessing the underlying types at an memory location - * (numbers, strings and raw bytes). + * value. The `UnsafePointerView` API follows the standard built in interface + * {@linkcode DataView} for accessing the underlying types at an memory + * location (numbers, strings and raw bytes). * * @category FFI */ @@ -647,41 +725,63 @@ declare namespace Deno { /** Gets a boolean at the specified byte offset from the pointer. */ getBool(offset?: number): boolean; - /** Gets an unsigned 8-bit integer at the specified byte offset from the pointer. */ + /** Gets an unsigned 8-bit integer at the specified byte offset from the + * pointer. */ getUint8(offset?: number): number; - /** Gets a signed 8-bit integer at the specified byte offset from the pointer. */ + /** Gets a signed 8-bit integer at the specified byte offset from the + * pointer. */ getInt8(offset?: number): number; - /** Gets an unsigned 16-bit integer at the specified byte offset from the pointer. */ + /** Gets an unsigned 16-bit integer at the specified byte offset from the + * pointer. */ getUint16(offset?: number): number; - /** Gets a signed 16-bit integer at the specified byte offset from the pointer. */ + /** Gets a signed 16-bit integer at the specified byte offset from the + * pointer. */ getInt16(offset?: number): number; - /** Gets an unsigned 32-bit integer at the specified byte offset from the pointer. */ + /** Gets an unsigned 32-bit integer at the specified byte offset from the + * pointer. */ getUint32(offset?: number): number; - /** Gets a signed 32-bit integer at the specified byte offset from the pointer. */ + /** Gets a signed 32-bit integer at the specified byte offset from the + * pointer. */ getInt32(offset?: number): number; - /** Gets an unsigned 64-bit integer at the specified byte offset from the pointer. */ + /** Gets an unsigned 64-bit integer at the specified byte offset from the + * pointer. */ getBigUint64(offset?: number): PointerValue; - /** Gets a signed 64-bit integer at the specified byte offset from the pointer. */ + /** Gets a signed 64-bit integer at the specified byte offset from the + * pointer. */ getBigInt64(offset?: number): PointerValue; - /** Gets a signed 32-bit float at the specified byte offset from the pointer. */ + /** Gets a signed 32-bit float at the specified byte offset from the + * pointer. */ getFloat32(offset?: number): number; - /** Gets a signed 64-bit float at the specified byte offset from the pointer. */ + /** Gets a signed 64-bit float at the specified byte offset from the + * pointer. */ getFloat64(offset?: number): number; - /** Gets a C string (null terminated string) at the specified byte offset from the pointer. */ + /** Gets a C string (`null` terminated string) at the specified byte offset + * from the pointer. */ getCString(offset?: number): string; - /** Gets a C string (null terminated string) at the specified byte offset from the specified pointer. */ + /** Gets a C string (`null` terminated string) at the specified byte offset + * from the specified pointer. */ static getCString(pointer: PointerValue, offset?: number): string; - /** Gets an ArrayBuffer of length `byteLength` at the specified byte offset from the pointer. */ + /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte + * offset from the pointer. */ getArrayBuffer(byteLength: number, offset?: number): ArrayBuffer; - /** Gets an ArrayBuffer of length `byteLength` at the specified byte offset from the specified pointer. */ + /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte + * offset from the specified pointer. */ static getArrayBuffer( pointer: PointerValue, byteLength: number, offset?: number, ): ArrayBuffer; - /** Copies the memory of the pointer into a typed array. Length is determined from the typed array's `byteLength`. Also takes optional byte offset from the pointer. */ + /** Copies the memory of the pointer into a typed array. + * + * Length is determined from the typed array's `byteLength`. + * + * Also takes optional byte offset from the pointer. */ copyInto(destination: BufferSource, offset?: number): void; - /** Copies the memory of the specified pointer into a typed array. Length is determined from the typed array's `byteLength`. Also takes optional byte offset from the pointer. */ + /** Copies the memory of the specified pointer into a typed array. + * + * Length is determined from the typed array's `byteLength`. + * + * Also takes optional byte offset from the pointer. */ static copyInto( pointer: PointerValue, destination: BufferSource, @@ -691,34 +791,43 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * An unsafe pointer to a function, for calling functions that are not - * present as symbols. + * An unsafe pointer to a function, for calling functions that are not present + * as symbols. * * @category FFI */ export class UnsafeFnPointer<Fn extends ForeignFunction> { + /** The pointer to the function. */ pointer: PointerValue; + /** The definition of the function. */ definition: Fn; constructor(pointer: PointerValue, definition: Fn); + /** Call the foreign function. */ call: FromForeignFunction<Fn>; } /** **UNSTABLE**: New API, yet to be vetted. * + * Definition of a unsafe callback function. + * * @category FFI */ export interface UnsafeCallbackDefinition< Parameters extends readonly NativeType[] = readonly NativeType[], Result extends NativeResultType = NativeResultType, > { + /** The parameters of the callbacks. */ parameters: Parameters; + /** The current result of the callback. */ result: Result; } /** **UNSTABLE**: New API, yet to be vetted. * + * An unsafe callback function. + * * @category FFI */ type UnsafeCallbackFunction< @@ -730,13 +839,13 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * An unsafe function pointer for passing JavaScript functions - * as C function pointers to ffi calls. + * An unsafe function pointer for passing JavaScript functions as C function + * pointers to foreign function calls. * * The function pointer remains valid until the `close()` method is called. * - * The callback can be explicitly ref'ed and deref'ed to stop Deno's - * process from exiting. + * The callback can be explicitly referenced via `ref()` and dereferenced via + * `deref()` to stop Deno's process from exiting. * * @category FFI */ @@ -751,35 +860,39 @@ declare namespace Deno { >, ); + /** The pointer to the unsafe callback. */ pointer: PointerValue; + /** The definition of the unsafe callback. */ definition: Definition; + /** The callback function. */ callback: UnsafeCallbackFunction< Definition["parameters"], Definition["result"] >; /** - * Adds one to this callback's reference counting and returns the - * new reference count. + * Adds one to this callback's reference counting and returns the new + * reference count. * - * If the callback's reference count becomes non-zero, it will keep - * Deno's process from exiting. + * If the callback's reference count is non-zero, it will keep Deno's + * process from exiting. */ ref(): number; /** - * Removes one from this callback's reference counting and returns - * the new reference count. + * Removes one from this callback's reference counting and returns the new + * reference count. * - * If the callback's reference counter becomes zero, it will no longer - * keep Deno's process from exiting. + * If the callback's reference counter is zero, it will no longer keep + * Deno's process from exiting. */ unref(): number; /** - * Removes the C function pointer associated with the UnsafeCallback. - * Continuing to use the instance after calling this object will lead to errors - * and crashes. + * Removes the C function pointer associated with this instance. + * + * Continuing to use the instance after calling this object will lead to + * errors and crashes. * * Calling this method will also immediately set the callback's reference * counting to zero and it will no longer keep Deno's process from exiting. @@ -789,20 +902,70 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * A dynamic library resource + * A dynamic library resource. Use {@linkcode Deno.dlopen} to load a dynamic + * library and return this interface. * * @category FFI */ export interface DynamicLibrary<S extends ForeignLibraryInterface> { - /** All of the registered library along with functions for calling them */ + /** All of the registered library along with functions for calling them. */ symbols: StaticForeignLibraryInterface<S>; + /** Removes the pointers associated with the library symbols. + * + * Continuing to use symbols that are part of the library will lead to + * errors and crashes. + * + * Calling this method will also immediately set any references to zero and + * will no longer keep Deno's process from exiting. + */ close(): void; } /** **UNSTABLE**: New API, yet to be vetted. * - * Opens a dynamic library and registers symbols + * Opens an external dynamic library and registers symbols, making foreign + * functions available to be called. + * + * Requires `allow-ffi` permission. Loading foreign dynamic libraries can in + * theory bypass all of the sandbox permissions. While it is a separate + * permission users should acknowledge in practice that is effectively the + * same as running with the `allow-all` permission. * + * An example, given a C library which exports a foreign function named + * `add()`: + * + * ```ts + * // Determine library extension based on + * // your OS. + * let libSuffix = ""; + * switch (Deno.build.os) { + * case "windows": + * libSuffix = "dll"; + * break; + * case "darwin": + * libSuffix = "dylib"; + * break; + * default: + * libSuffix = "so"; + * break; + * } + * + * const libName = `./libadd.${libSuffix}`; + * // Open library and define exported symbols + * const dylib = Deno.dlopen( + * libName, + * { + * "add": { parameters: ["isize", "isize"], result: "isize" }, + * } as const, + * ); + * + * // Call the symbol `add` + * const result = dylib.symbols.add(35, 34); // 69 + * + * console.log(`Result from external addition of 35 and 34: ${result}`); + * ``` + * + * @tags allow-ffi * @category FFI */ export function dlopen<S extends ForeignLibraryInterface>( @@ -812,23 +975,76 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * These are unstable options which can be used with {@linkcode Deno.run}. + */ + interface UnstableRunOptions extends RunOptions { + /** If `true`, clears the environment variables before executing the + * sub-process. Defaults to `false`. */ + clearEnv?: boolean; + /** For POSIX systems, sets the group ID for the sub process. */ + gid?: number; + /** For POSIX systems, sets the user ID for the sub process. */ + uid?: number; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`, + * an array of program arguments, the first of which is the binary. + * + * ```ts + * const p = Deno.run({ + * cmd: ["curl", "https://example.com"], + * }); + * const status = await p.status(); + * ``` + * + * Subprocess uses same working directory as parent process unless `opt.cwd` + * is specified. + * + * Environmental variables from parent process can be cleared using `opt.clearEnv`. + * Doesn't guarantee that only `opt.env` variables are present, + * as the OS may set environmental variables for processes. + * + * Environmental variables for subprocess can be specified using `opt.env` + * mapping. + * + * `opt.uid` sets the child process’s user ID. This translates to a setuid call + * in the child process. Failure in the setuid call will cause the spawn to fail. + * + * `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process. + * This has the same semantics as the uid field. + * + * By default subprocess inherits stdio of parent process. To change + * this this, `opt.stdin`, `opt.stdout`, and `opt.stderr` can be set + * independently to a resource ID (_rid_) of an open file, `"inherit"`, + * `"piped"`, or `"null"`: + * + * - _number_: the resource ID of an open file/resource. This allows you to + * read or write to a file. + * - `"inherit"`: The default if unspecified. The subprocess inherits from the + * parent. + * - `"piped"`: A new pipe should be arranged to connect the parent and child + * sub-process. + * - `"null"`: This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + * + * Details of the spawned process are returned as an instance of + * {@linkcode Deno.Process}. + * + * Requires `allow-run` permission. + * + * @tags allow-run * @category Sub Process */ - export function run< - T extends RunOptions & { - clearEnv?: boolean; - gid?: number; - uid?: number; - } = RunOptions & { - clearEnv?: boolean; - gid?: number; - uid?: number; - }, - >(opt: T): Process<T>; + export function run<T extends UnstableRunOptions = UnstableRunOptions>( + opt: T, + ): Process<T>; /** **UNSTABLE**: New API, yet to be vetted. * - * A custom HttpClient for use with `fetch`. + * A custom `HttpClient` for use with {@linkcode fetch} function. This is + * designed to allow custom certificates or proxies to be used with `fetch()`. * * ```ts * const caCert = await Deno.readTextFile("./ca.pem"); @@ -838,14 +1054,16 @@ declare namespace Deno { * * @category Fetch API */ - export class HttpClient { + export interface HttpClient { + /** The resource ID associated with the client. */ rid: number; + /** Close the HTTP client. */ close(): void; } /** **UNSTABLE**: New API, yet to be vetted. * - * The options used when creating a [HttpClient]. + * The options used when creating a {@linkcode Deno.HttpClient}. * * @category Fetch API */ @@ -865,25 +1083,37 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * The definition of a proxy when specifying + * {@linkcode Deno.CreateHttpClientOptions}. + * * @category Fetch API */ export interface Proxy { + /** The string URL of the proxy server to use. */ url: string; + /** The basic auth credentials to be used against the proxy server. */ basicAuth?: BasicAuth; } /** **UNSTABLE**: New API, yet to be vetted. * + * Basic authentication credentials to be used with a {@linkcode Deno.Proxy} + * server when specifying {@linkcode Deno.CreateHttpClientOptions}. + * * @category Fetch API */ export interface BasicAuth { + /** The username to be used against the proxy server. */ username: string; + /** The password to be used against the proxy server. */ password: string; } /** **UNSTABLE**: New API, yet to be vetted. * - * Create a custom HttpClient for to use with `fetch`. + * Create a custom HttpClient for to use with {@linkcode fetch}. This is an + * extension of the web platform Fetch API which allows Deno to use custom + * TLS certificates and connect via a proxy while using `fetch()`. * * ```ts * const caCert = await Deno.readTextFile("./ca.pem"); @@ -892,7 +1122,9 @@ declare namespace Deno { * ``` * * ```ts - * const client = Deno.createHttpClient({ proxy: { url: "http://myproxy.com:8080" } }); + * const client = Deno.createHttpClient({ + * proxy: { url: "http://myproxy.com:8080" } + * }); * const response = await fetch("https://myserver.com", { client }); * ``` * @@ -909,35 +1141,48 @@ declare namespace Deno { * @category Network */ export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> { - /** Waits for and resolves to the next message to the `UDPConn`. */ + /** Waits for and resolves to the next message to the instance. + * + * Messages are received in the format of a tuple containing the data array + * and the address information. + */ receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>; - /** Sends a message to the target. */ + /** Sends a message to the target via the connection. The method resolves + * with the number of bytes sent. */ send(p: Uint8Array, addr: Addr): Promise<number>; /** Close closes the socket. Any pending message promises will be rejected * with errors. */ close(): void; - /** Return the address of the `UDPConn`. */ + /** Return the address of the instance. */ readonly addr: Addr; [Symbol.asyncIterator](): AsyncIterableIterator<[Uint8Array, Addr]>; } /** **UNSTABLE**: New API, yet to be vetted. * + * Unstable options which can be set when opening a Unix listener via + * {@linkcode Deno.listen} or {@linkcode Deno.listenDatagram}. + * * @category Network */ export interface UnixListenOptions { - /** A Path to the Unix Socket. */ + /** A path to the Unix Socket. */ path: string; } /** **UNSTABLE**: New API, yet to be vetted. * + * Unstable options which can be set when opening a datagram listener via + * {@linkcode Deno.listenDatagram}. + * * @category Network */ export interface UdpListenOptions extends ListenOptions { /** When `true` the specified address will be reused, even if another * process has already bound a socket on it. This effectively steals the - * socket from the listener. Defaults to `false`. */ + * socket from the listener. + * + * Defaults to `false`. */ reuseAddress?: boolean; } @@ -1030,12 +1275,26 @@ declare namespace Deno { * @tags allow-net, allow-read * @category Network */ - export function connect( - options: ConnectOptions, - ): Promise<TcpConn>; - export function connect( - options: UnixConnectOptions, - ): Promise<UnixConn>; + export function connect(options: ConnectOptions): Promise<TcpConn>; + /** **UNSTABLE**: New API, yet to be vetted. + * + * 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`). + * + * ```ts + * const conn1 = await Deno.connect({ port: 80 }); + * const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 }); + * const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 }); + * const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" }); + * const conn5 = await Deno.connect({ path: "/foo/bar.sock", transport: "unix" }); + * ``` + * + * Requires `allow-net` permission for "tcp" and `allow-read` for "unix". + * + * @tags allow-net, allow-read + * @category Network + */ + export function connect(options: UnixConnectOptions): Promise<UnixConn>; /** **UNSTABLE**: New API, yet to be vetted. * @@ -1164,8 +1423,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Acquire an advisory file-system lock for the provided file. `exclusive` - * defaults to `false`. + * Acquire an advisory file-system lock synchronously for the provided file. + * `exclusive` defaults to `false`. * * @category File System */ @@ -1181,7 +1440,7 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Release an advisory file-system lock for the provided file. + * Release an advisory file-system lock for the provided file synchronously. * * @category File System */ @@ -1201,24 +1460,28 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * Options which can be set when calling {@linkcode Deno.serve}. + * * @category HTTP Server */ export interface ServeOptions extends Partial<Deno.ListenOptions> { - /** An AbortSignal to close the server and all connections. */ + /** An {@linkcode AbortSignal} to close the server and all connections. */ signal?: AbortSignal; - /** Sets SO_REUSEPORT on Linux. */ + /** Sets `SO_REUSEPORT` on POSIX systems. */ reusePort?: boolean; /** The handler to invoke when route handlers throw an error. */ onError?: (error: unknown) => Response | Promise<Response>; - /** The callback which is called when the server started listening */ + /** The callback which is called when the server starts listening. */ onListen?: (params: { hostname: string; port: number }) => void; } /** **UNSTABLE**: New API, yet to be vetted. * + * Additional options which are used when opening a TLS (HTTPS) server. + * * @category HTTP Server */ export interface ServeTlsOptions extends ServeOptions { @@ -1243,25 +1506,25 @@ declare namespace Deno { * Serves HTTP requests with the given handler. * * 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"`. * - * The below example serves with the port 9000. + * The below example serves with the port `9000`. * * ```ts * Deno.serve((_req) => new Response("Hello, world")); * ``` * * You can change the address to listen on using the `hostname` and `port` - * options. The below example serves on port 3000. + * options. The below example serves on port `3000`. * * ```ts * Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world")); * ``` * - * You can stop the server with an AbortSignal. The abort signal needs to be - * passed as the `signal` option in the options bag. The server aborts when - * the abort signal is aborted. To wait for the server to close, await the - * promise returned from the `Deno.serve` API. + * You can stop the server with an {@linkcode AbortSignal}. The abort signal + * needs to be passed as the `signal` option in the options bag. The server + * aborts when the abort signal is aborted. To wait for the server to close, + * await the promise returned from the `Deno.serve` API. * * ```ts * const ac = new AbortController(); @@ -1273,9 +1536,9 @@ declare namespace Deno { * ac.abort(); * ``` * - * By default `Deno.serve` prints the message `Listening on http://<hostname>:<port>/` - * on start up. If you like to change this behaviour, you can specify a custom - * `onListen` callback. + * By default `Deno.serve` prints the message + * `Listening on http://<hostname>:<port>/` on listening. If you like to + * change this behavior, you can specify a custom `onListen` callback. * * ```ts * Deno.serve({ @@ -1301,19 +1564,137 @@ declare namespace Deno { handler: ServeHandler, options?: ServeOptions | ServeTlsOptions, ): Promise<void>; + /** **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 + * address to listen on. The default is port `9000` on hostname `"127.0.0.1"`. + * + * The below example serves with the port `9000`. + * + * ```ts + * Deno.serve((_req) => new Response("Hello, world")); + * ``` + * + * You can change the address to listen on using the `hostname` and `port` + * options. The below example serves on port `3000`. + * + * ```ts + * Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world")); + * ``` + * + * You can stop the server with an {@linkcode AbortSignal}. The abort signal + * needs to be passed as the `signal` option in the options bag. The server + * aborts when the abort signal is aborted. To wait for the server to close, + * await the promise returned from the `Deno.serve` API. + * + * ```ts + * const ac = new AbortController(); + * + * Deno.serve({ signal: ac.signal }, (_req) => new Response("Hello, world")) + * .then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * By default `Deno.serve` prints the message + * `Listening on http://<hostname>:<port>/` on listening. If you like to + * change this behavior, you can specify a custom `onListen` callback. + * + * ```ts + * Deno.serve({ + * onListen({ port, hostname }) { + * console.log(`Server started at http://${hostname}:${port}`); + * // ... more info specific to your server .. + * }, + * handler: (_req) => new Response("Hello, world"), + * }); + * ``` + * + * To enable TLS you must specify the `key` and `cert` options. + * + * ```ts + * const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"; + * const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"; + * Deno.serve({ cert, key }, (_req) => new Response("Hello, world")); + * ``` + * + * @category HTTP Server + */ export function serve( options: ServeOptions | ServeTlsOptions, handler: ServeHandler, ): Promise<void>; + /** **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 + * address to listen on. The default is port `9000` on hostname `"127.0.0.1"`. + * + * The below example serves with the port `9000`. + * + * ```ts + * Deno.serve((_req) => new Response("Hello, world")); + * ``` + * + * You can change the address to listen on using the `hostname` and `port` + * options. The below example serves on port `3000`. + * + * ```ts + * Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world")); + * ``` + * + * You can stop the server with an {@linkcode AbortSignal}. The abort signal + * needs to be passed as the `signal` option in the options bag. The server + * aborts when the abort signal is aborted. To wait for the server to close, + * await the promise returned from the `Deno.serve` API. + * + * ```ts + * const ac = new AbortController(); + * + * Deno.serve({ signal: ac.signal }, (_req) => new Response("Hello, world")) + * .then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * By default `Deno.serve` prints the message + * `Listening on http://<hostname>:<port>/` on listening. If you like to + * change this behavior, you can specify a custom `onListen` callback. + * + * ```ts + * Deno.serve({ + * onListen({ port, hostname }) { + * console.log(`Server started at http://${hostname}:${port}`); + * // ... more info specific to your server .. + * }, + * handler: (_req) => new Response("Hello, world"), + * }); + * ``` + * + * To enable TLS you must specify the `key` and `cert` options. + * + * ```ts + * const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"; + * const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"; + * Deno.serve({ cert, key }, (_req) => new Response("Hello, world")); + * ``` + * + * @category HTTP Server + */ export function serve( options: ServeInit & (ServeOptions | ServeTlsOptions), ): Promise<void>; /** **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. - * WebSockets). + * Allows "hijacking" the connection that the request is associated with. This + * can be used to implement protocols that build on top of HTTP (eg. + * {@linkcode WebSocket}). * * The returned promise returns underlying connection and first packet * received. The promise shouldn't be awaited before responding to the @@ -1328,8 +1709,8 @@ declare namespace Deno { * } * ``` * - * This method can only be called on requests originating the `Deno.serveHttp` - * server. + * This method can only be called on requests originating the + * {@linkcode Deno.serveHttp} server. * * @category HTTP Server */ @@ -1341,15 +1722,16 @@ declare namespace Deno { * * Allows "hijacking" the connection that the request is associated with. * This can be used to implement protocols that build on top of HTTP (eg. - * WebSockets). - - * Unlike `Deno.upgradeHttp` this function does not require that you respond - * to the request with a `Response` object. Instead this function returns - * the underlying connection and first packet received immediately, and then - * the caller is responsible for writing the response to the connection. + * {@linkcode WebSocket}). + * + * Unlike {@linkcode Deno.upgradeHttp} this function does not require that you + * respond to the request with a {@linkcode Response} object. Instead this + * function returns the underlying connection and first packet received + * immediately, and then the caller is responsible for writing the response to + * the connection. * - * This method can only be called on requests originating the `Deno.serve` - * server. + * This method can only be called on requests originating the + * {@linkcode Deno.serve} server. * * @category HTTP Server */ @@ -1357,6 +1739,9 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * Options which can be set when calling {@linkcode Deno.spawn}, + * {@linkcode Deno.spawnSync}, and {@linkcode Deno.spawnChild}. + * * @category Sub Process */ export interface SpawnOptions { @@ -1364,40 +1749,50 @@ declare namespace Deno { args?: string[]; /** * The working directory of the process. - * If not specified, the cwd of the parent process is used. + * + * If not specified, the `cwd` of the parent process is used. */ cwd?: string | URL; /** * Clear environmental variables from parent process. - * Doesn't guarantee that only `opt.env` variables are present, - * as the OS may set environmental variables for processes. + * + * Doesn't guarantee that only `env` variables are present, as the OS may + * set environmental variables for processes. */ clearEnv?: boolean; /** Environmental variables to pass to the subprocess. */ env?: Record<string, string>; /** - * Sets the child process’s user ID. This translates to a setuid call - * in the child process. Failure in the setuid call will cause the spawn to fail. + * Sets the child process’s user ID. This translates to a setuid call in the + * child process. Failure in the set uid call will cause the spawn to fail. */ uid?: number; /** Similar to `uid`, but sets the group ID of the child process. */ gid?: number; /** - * An AbortSignal that allows closing the process using the corresponding - * AbortController by sending the process a SIGTERM signal. - * Not supported in spawnSync. + * An {@linkcode AbortSignal} that allows closing the process using the + * corresponding {@linkcode AbortController} by sending the process a + * SIGTERM signal. + * + * Not supported in {@linkcode Deno.spawnSync}. */ signal?: AbortSignal; - /** Defaults to "null". */ + /** How `stdin` of the spawned process should be handled. + * + * Defaults to `"null"`. */ stdin?: "piped" | "inherit" | "null"; - /** Defaults to "piped". */ + /** How `stdout` of the spawned process should be handled. + * + * Defaults to `"piped"`. */ stdout?: "piped" | "inherit" | "null"; - /** Defaults to "piped". */ + /** How `stderr` of the spawned process should be handled. + * + * Defaults to "piped". */ stderr?: "piped" | "inherit" | "null"; /** Skips quoting and escaping of the arguments on windows. This option - * is ignored on non-windows platforms. Defaults to "false". */ + * is ignored on non-windows platforms. Defaults to `false`. */ windowsRawArguments?: boolean; } @@ -1408,8 +1803,8 @@ declare namespace Deno { * If any stdio options are not set to `"piped"`, accessing the corresponding * field on the `Child` or its `SpawnOutput` will throw a `TypeError`. * - * If stdin is set to `"piped"`, the stdin WritableStream needs to be closed - * manually. + * If `stdin` is set to `"piped"`, the `stdin` {@linkcode WritableStream} + * needs to be closed manually. * * ```ts * const child = Deno.spawnChild(Deno.execPath(), { @@ -1437,6 +1832,9 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * The interface for handling a child process returned from + * {@linkcode Deno.spawnChild}. + * * @category Sub Process */ export class Child { @@ -1447,19 +1845,26 @@ declare namespace Deno { /** Get the status of the child. */ readonly status: Promise<ChildStatus>; - /** Waits for the child to exit completely, returning all its output and status. */ + /** Waits for the child to exit completely, returning all its output and + * status. */ output(): Promise<SpawnOutput>; - /** Kills the process with given Signal. Defaults to SIGTERM. */ + /** Kills the process with given {@linkcode Deno.Signal}. Defaults to + * `"SIGTERM"`. */ kill(signo?: Signal): void; + /** Ensure that the status of the child process prevents the Deno process + * from exiting. */ ref(): void; + /** Ensure that the status of the child process does not block the Deno + * process from exiting. */ unref(): void; } /** **UNSTABLE**: New API, yet to be vetted. * - * Executes a subprocess, waiting for it to finish and - * collecting all of its output. + * Executes a subprocess, waiting for it to finish and collecting all of its + * output. + * * Will throw an error if `stdin: "piped"` is passed. * * If options `stdout` or `stderr` are not set to `"piped"`, accessing the @@ -1488,6 +1893,7 @@ declare namespace Deno { * * Synchronously executes a subprocess, waiting for it to finish and * collecting all of its output. + * * Will throw an error if `stdin: "piped"` is passed. * * If options `stdout` or `stderr` are not set to `"piped"`, accessing the @@ -1517,23 +1923,38 @@ declare namespace Deno { * @category Sub Process */ export interface ChildStatus { + /** If the child process exits with a 0 status code, `success` will be set + * to `true`, otherwise `false`. */ success: boolean; + /** The exit code of the child process. */ code: number; + /** The signal associated with the child process, present if + * {@linkcode Deno.spawn} was called. */ signal: Signal | null; } /** **UNSTABLE**: New API, yet to be vetted. * + * The interface returned from calling {@linkcode Deno.spawn} or + * {@linkcode Deno.spawnSync} which represents the result of spawning the + * child process. + * * @category Sub Process */ export interface SpawnOutput extends ChildStatus { - get stdout(): Uint8Array; - get stderr(): Uint8Array; + /** The buffered output from the child processes `stdout`. */ + readonly stdout: Uint8Array; + /** The buffered output from the child processes `stderr`. */ + readonly stderr: Uint8Array; } } /** **UNSTABLE**: New API, yet to be vetted. * + * The [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) + * which also supports setting a {@linkcode Deno.HttpClient} which provides a + * way to connect via proxies and use custom TLS certificates. + * * @tags allow-net, allow-read * @category Fetch API */ @@ -1552,10 +1973,13 @@ declare interface WorkerOptions { * Configure permissions options to change the level of access the worker will * 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. - * - "inherit" will take the permissions of the thread the worker is created in - * - "none" will use the default behavior and have no permission - * - You can provide a list of routes relative to the file the worker - * is created in to limit the access of the worker (read/write permissions only) + * + * - `"inherit"` will take the permissions of the thread the worker is created + * in. + * - `"none"` will use the default behavior and have no permission + * - A list of routes can be provided that are relative to the file the worker + * is created in to limit the access of the worker (read/write permissions + * only) * * Example: * |