// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license. /// /// declare namespace Deno { export {}; // stop default export type behavior /** **UNSTABLE**: New API, yet to be vetted. * * Retrieve the process umask. If `mask` is provided, sets the process umask. * This call always returns what the umask was before the call. * * ```ts * console.log(Deno.umask()); // e.g. 18 (0o022) * const prevUmaskValue = Deno.umask(0o077); // e.g. 18 (0o022) * console.log(Deno.umask()); // e.g. 63 (0o077) * ``` * * This API is under consideration to determine if permissions are required to * call it. * * *Note*: This API is not implemented on Windows * * @category File System */ export function umask(mask?: number): number; /** **UNSTABLE**: New API, yet to be vetted. * * All plain number types for interfacing with foreign functions. * * @category FFI */ type NativeNumberType = | "u8" | "i8" | "u16" | "i16" | "u32" | "i32" | "f32" | "f64"; /** **UNSTABLE**: New API, yet to be vetted. * * All BigInt number types for interfacing with foreign functions. * * @category FFI */ type NativeBigIntType = | "u64" | "i64" | "usize" | "isize"; /** **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 supported types for interfacing with foreign functions. * * @category FFI */ export type NativeType = | NativeNumberType | NativeBigIntType | NativeBooleanType | NativePointerType | NativeBufferType | NativeFunctionType; /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ export type NativeResultType = NativeType | NativeVoidType; /** **UNSTABLE**: New API, yet to be vetted. * * A utility type conversion for foreign symbol parameters and unsafe callback * return types. * * @category FFI */ type ToNativeTypeMap = & Record & Record & Record & Record & Record & Record; /** **UNSTABLE**: New API, yet to be vetted. * * Type conversion for foreign symbol parameters and unsafe callback return * types. * * @category FFI */ type ToNativeType = ToNativeTypeMap[T]; /** **UNSTABLE**: New API, yet to be vetted. * * A utility type for conversion for unsafe callback return types. * * @category FFI */ type ToNativeResultTypeMap = ToNativeTypeMap & Record; /** **UNSTABLE**: New API, yet to be vetted. * * Type conversion for unsafe callback return types. * * @category FFI */ type ToNativeResultType = ToNativeResultTypeMap[T]; /** **UNSTABLE**: New API, yet to be vetted. * * A utility type for conversion of parameter types of foreign functions. * * @category FFI */ type ToNativeParameterTypes = // [(T[number])[]] extends [T] ? ToNativeType[] : [readonly (T[number])[]] extends [T] ? readonly ToNativeType[] : T extends readonly [...NativeType[]] ? { [K in keyof T]: ToNativeType; } : never; /** **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 = & Record & Record & Record & Record & Record & Record; /** **UNSTABLE**: New API, yet to be vetted. * * Type conversion for foreign symbol return types and unsafe callback * parameters. * * @category FFI */ type FromNativeType = FromNativeTypeMap[T]; /** **UNSTABLE**: New API, yet to be vetted. * * A utility type for conversion for foreign symbol return types. * * @category FFI */ type FromNativeResultTypeMap = & FromNativeTypeMap & Record; /** **UNSTABLE**: New API, yet to be vetted. * * Type conversion for foreign symbol return types. * * @category FFI */ type FromNativeResultType = FromNativeResultTypeMap[T]; /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ type FromNativeParameterTypes< T extends readonly NativeType[], > = // [(T[number])[]] extends [T] ? FromNativeType[] : [readonly (T[number])[]] extends [T] ? readonly FromNativeType[] : T extends readonly [...NativeType[]] ? { [K in keyof T]: FromNativeType; } : never; /** **UNSTABLE**: New API, yet to be vetted. * * The interface for a foreign function as defined by its parameter and result * types. * * @category FFI */ export interface ForeignFunction< Parameters extends readonly NativeType[] = readonly NativeType[], Result extends NativeResultType = NativeResultType, NonBlocking extends boolean = boolean, > { /** 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`. */ nonblocking?: NonBlocking; /** When `true`, function calls can safely callback into JavaScript or * trigger a garbage collection event. * * Default is `false`. */ callback?: boolean; } /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ export interface ForeignStatic { /** Name of the symbol, defaults to the key name in symbols object. */ name?: string; /** The type of the foreign static value. */ type: Type; } /** **UNSTABLE**: New API, yet to be vetted. * * A foreign library interface descriptor. * * @category FFI */ export interface ForeignLibraryInterface { [name: string]: ForeignFunction | ForeignStatic; } /** **UNSTABLE**: New API, yet to be vetted. * * A utility type that infers a foreign symbol. * * @category FFI */ type StaticForeignSymbol = T extends ForeignFunction ? FromForeignFunction : T extends ForeignStatic ? FromNativeType : never; /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ type FromForeignFunction = T["parameters"] extends readonly [] ? () => StaticForeignSymbolReturnType : ( ...args: ToNativeParameterTypes ) => StaticForeignSymbolReturnType; /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ type StaticForeignSymbolReturnType = ConditionalAsync>; /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ type ConditionalAsync = IsAsync extends true ? Promise : T; /** **UNSTABLE**: New API, yet to be vetted. * * A utility type that infers a foreign library interface. * * @category FFI */ type StaticForeignLibraryInterface = { [K in keyof T]: StaticForeignSymbol; }; /** **UNSTABLE**: New API, yet to be vetted. * * Pointer type depends on the architecture and actual pointer value. * * 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 */ export type PointerValue = number | bigint; /** **UNSTABLE**: New API, yet to be vetted. * * An unsafe pointer to a memory location for passing and returning pointers * to and from the FFI. * * @category FFI */ export class UnsafePointer { /** 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 follows the standard built in interface * {@linkcode DataView} for accessing the underlying types at an memory * location (numbers, strings and raw bytes). * * @category FFI */ export class UnsafePointerView { constructor(pointer: PointerValue); pointer: PointerValue; /** 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. */ getUint8(offset?: number): number; /** 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. */ getUint16(offset?: number): number; /** 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. */ getUint32(offset?: number): number; /** 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. */ getBigUint64(offset?: number): PointerValue; /** 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. */ getFloat32(offset?: number): number; /** 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. */ getCString(offset?: number): string; /** 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. */ getArrayBuffer(byteLength: number, offset?: number): ArrayBuffer; /** 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. */ 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. */ static copyInto( pointer: PointerValue, destination: BufferSource, offset?: number, ): void; } /** **UNSTABLE**: New API, yet to be vetted. * * An unsafe pointer to a function, for calling functions that are not present * as symbols. * * @category FFI */ export class UnsafeFnPointer { /** 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; } /** **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< Parameters extends readonly NativeType[] = readonly NativeType[], Result extends NativeResultType = NativeResultType, > = Parameters extends readonly [] ? () => ToNativeResultType : ( ...args: FromNativeParameterTypes ) => ToNativeResultType; /** **UNSTABLE**: New API, yet to be vetted. * * 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 referenced via `ref()` and dereferenced via * `deref()` to stop Deno's process from exiting. * * @category FFI */ export class UnsafeCallback< Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition, > { constructor( definition: Definition, callback: UnsafeCallbackFunction< Definition["parameters"], Definition["result"] >, ); /** 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. * * 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. * * 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 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. */ close(): void; } /** **UNSTABLE**: New API, yet to be vetted. * * A dynamic library resource. Use {@linkcode Deno.dlopen} to load a dynamic * library and return this interface. * * @category FFI */ export interface DynamicLibrary { /** All of the registered library along with functions for calling them. */ symbols: StaticForeignLibraryInterface; /** 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 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( filename: string | URL, symbols: S, ): DynamicLibrary; /** **UNSTABLE**: New API, yet to be vetted. * * These are unstable options which can be used with {@linkcode Deno.run}. * * @category Sub Process */ 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( opt: T, ): Process; /** **UNSTABLE**: New API, yet to be vetted. * * 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"); * const client = Deno.createHttpClient({ caCerts: [ caCert ] }); * const req = await fetch("https://myserver.com", { client }); * ``` * * @category Fetch API */ 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 {@linkcode Deno.HttpClient}. * * @category Fetch API */ export interface CreateHttpClientOptions { /** A list of root certificates that will be used in addition to the * default root certificates to verify the peer's certificate. * * Must be in PEM format. */ caCerts?: string[]; /** A HTTP proxy to use for new connections. */ proxy?: Proxy; /** PEM formatted client certificate chain. */ certChain?: string; /** PEM formatted (RSA or PKCS8) private key of client certificate. */ privateKey?: string; } /** **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 {@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"); * const client = Deno.createHttpClient({ caCerts: [ caCert ] }); * const response = await fetch("https://myserver.com", { client }); * ``` * * ```ts * const client = Deno.createHttpClient({ * proxy: { url: "http://myproxy.com:8080" } * }); * const response = await fetch("https://myserver.com", { client }); * ``` * * @category Fetch API */ export function createHttpClient( options: CreateHttpClientOptions, ): HttpClient; /** **UNSTABLE**: New API, yet to be vetted. * * A generic transport listener for message-oriented protocols. * * @category Network */ export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> { /** 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 via the connection. The method resolves * with the number of bytes sent. */ send(p: Uint8Array, addr: Addr): Promise; /** Close closes the socket. Any pending message promises will be rejected * with errors. */ close(): void; /** Return the address of the instance. */ readonly addr: Addr; [Symbol.asyncIterator](): AsyncIterableIterator<[Uint8Array, Addr]>; } /** * @category Network */ export interface TcpListenOptions extends ListenOptions { /** When `true` the SO_REUSEPORT flag will be set on the listener. This * allows multiple processes to listen on the same address and port. * * On Linux this will cause the kernel to distribute incoming connections * across the different processes that are listening on the same address and * port. * * This flag is only supported on Linux. It is silently ignored on other * platforms. Defaults to `false`. */ reusePort?: boolean; } /** **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. */ 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`. */ reuseAddress?: boolean; } /** **UNSTABLE**: New API, yet to be vetted. * * Listen announces on the local transport address. * * ```ts * const listener = Deno.listen({ path: "/foo/bar.sock", transport: "unix" }) * ``` * * Requires `allow-read` and `allow-write` permission. * * @tags allow-read, allow-write * @category Network */ export function listen( options: UnixListenOptions & { transport: "unix" }, ): Listener; /** **UNSTABLE**: New API, yet to be vetted. * * Listen announces on the local transport address. * * ```ts * const listener1 = Deno.listenDatagram({ * port: 80, * transport: "udp" * }); * const listener2 = Deno.listenDatagram({ * hostname: "golang.org", * port: 80, * transport: "udp" * }); * ``` * * Requires `allow-net` permission. * * @tags allow-net * @category Network */ export function listenDatagram( options: UdpListenOptions & { transport: "udp" }, ): DatagramConn; /** **UNSTABLE**: New API, yet to be vetted. * * Listen announces on the local transport address. * * ```ts * const listener = Deno.listenDatagram({ * path: "/foo/bar.sock", * transport: "unixpacket" * }); * ``` * * Requires `allow-read` and `allow-write` permission. * * @tags allow-read, allow-write * @category Network */ export function listenDatagram( options: UnixListenOptions & { transport: "unixpacket" }, ): DatagramConn; /** **UNSTABLE**: New API, yet to be vetted. * * @category Network */ export interface UnixConnectOptions { transport: "unix"; path: string; } /** **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: ConnectOptions): Promise; /** **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; /** **UNSTABLE**: New API, yet to be vetted. * * @category Network */ export interface ConnectTlsOptions { /** **UNSTABLE**: New API, yet to be vetted. * * PEM formatted client certificate chain. */ certChain?: string; /** **UNSTABLE**: New API, yet to be vetted. * * PEM formatted (RSA or PKCS8) private key of client certificate. */ privateKey?: string; /** **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 * TLS handshake. */ alpnProtocols?: string[]; } /** **UNSTABLE**: New API, yet to be vetted. * * @category Network */ export interface TlsHandshakeInfo { /** **UNSTABLE**: New API, yet to be vetted. * * Contains the ALPN protocol selected during negotiation with the server. * If no ALPN protocol selected, returns `null`. */ alpnProtocol: string | null; } /** **UNSTABLE**: New API, yet to be vetted. * * @category Network */ export interface TlsConn extends Conn { /** **UNSTABLE**: New API, yet to be vetted. * * Runs the client or server handshake protocol to completion if that has * not happened yet. Calling this method is optional; the TLS handshake * will be completed automatically as soon as data is sent or received. */ handshake(): Promise; } /** **UNSTABLE**: New API, yet to be vetted. * * Create a TLS connection with an attached client certificate. * * ```ts * const conn = await Deno.connectTls({ * hostname: "deno.land", * port: 443, * certChain: "---- BEGIN CERTIFICATE ----\n ...", * privateKey: "---- BEGIN PRIVATE KEY ----\n ...", * }); * ``` * * Requires `allow-net` permission. * * @tags allow-net * @category Network */ export function connectTls(options: ConnectTlsOptions): Promise; /** **UNSTABLE**: New API, yet to be vetted. * * @category Network */ export interface ListenTlsOptions { /** **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 * TLS handshake. */ alpnProtocols?: string[]; } /** **UNSTABLE**: New API, yet to be vetted. * * @category Network */ export interface StartTlsOptions { /** **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 * TLS handshake. */ alpnProtocols?: string[]; } /** @category Network */ export interface Listener extends AsyncIterable { /** **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. * This method is only meaningful after `.unref()` is called. */ ref(): void; /** **UNSTABLE**: New API, yet to be vetted. * * Make the listener not block the event loop from finishing. */ unref(): void; } /** **UNSTABLE**: New API, yet to be vetted. * * Acquire an advisory file-system lock for the provided file. `exclusive` * defaults to `false`. * * @category File System */ export function flock(rid: number, exclusive?: boolean): Promise; /** **UNSTABLE**: New API, yet to be vetted. * * Acquire an advisory file-system lock synchronously for the provided file. * `exclusive` defaults to `false`. * * @category File System */ export function flockSync(rid: number, exclusive?: boolean): void; /** **UNSTABLE**: New API, yet to be vetted. * * Release an advisory file-system lock for the provided file. * * @category File System */ export function funlock(rid: number): Promise; /** **UNSTABLE**: New API, yet to be vetted. * * Release an advisory file-system lock for the provided file synchronously. * * @category File System */ export function funlockSync(rid: number): void; /** **UNSTABLE**: New API, yet to be vetted. * * A handler for HTTP requests. Consumes a request and returns a response. * * If a handler throws, the server calling the handler will assume the impact * of the error is isolated to the individual request. It will catch the error * and if necessary will close the underlying connection. * * @category HTTP Server */ export type ServeHandler = (request: Request) => Response | Promise; /** **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 { /** An {@linkcode AbortSignal} to close the server and all connections. */ signal?: AbortSignal; /** Sets `SO_REUSEPORT` on POSIX systems. */ reusePort?: boolean; /** The handler to invoke when route handlers throw an error. */ onError?: (error: unknown) => Response | Promise; /** 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 { /** Server private key in PEM format */ cert: string; /** Cert chain in PEM format */ key: string; } /** **UNSTABLE**: New API, yet to be vetted. * * @category HTTP Server */ export interface ServeInit { /** The handler to invoke to process each incoming request. */ handler: ServeHandler; } /** **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://:/` 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( handler: ServeHandler, options?: ServeOptions | ServeTlsOptions, ): Promise; /** **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://:/` 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; /** **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://:/` 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; /** **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. * {@linkcode WebSocket}). * * The returned promise returns underlying connection and first packet * received. The promise shouldn't be awaited before responding to the * `request`, otherwise event loop might deadlock. * * ```ts * function handler(req: Request): Response { * Deno.upgradeHttp(req).then(([conn, firstPacket]) => { * // ... * }); * return new Response(null, { status: 101 }); * } * ``` * * This method can only be called on requests originating the * {@linkcode Deno.serveHttp} server. * * @category HTTP Server */ export function upgradeHttp( request: Request, ): Promise<[Deno.Conn, Uint8Array]>; /** **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. * {@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 * {@linkcode Deno.serve} server. * * @category HTTP Server */ export function upgradeHttpRaw(request: Request): [Deno.Conn, Uint8Array]; /** **UNSTABLE**: New API, yet to be vetted. * * @deprecated Use the Deno.Command API instead. * * Options which can be set when calling {@linkcode Deno.spawn}, * {@linkcode Deno.spawnSync}, and {@linkcode Deno.spawnChild}. * * @category Sub Process */ export interface SpawnOptions { /** Arguments to pass to the process. */ args?: string[]; /** * The working directory of the process. * * 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 `env` variables are present, as the OS may * set environmental variables for processes. */ clearEnv?: boolean; /** Environmental variables to pass to the subprocess. */ env?: Record; /** * 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 {@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; /** How `stdin` of the spawned process should be handled. * * Defaults to `"null"`. */ stdin?: "piped" | "inherit" | "null"; /** How `stdout` of the spawned process should be handled. * * Defaults to `"piped"`. */ stdout?: "piped" | "inherit" | "null"; /** 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`. */ windowsRawArguments?: boolean; } /** **UNSTABLE**: New API, yet to be vetted. * * @deprecated Use the Deno.Command API instead. * * Spawns a child process. * * 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` {@linkcode WritableStream} * needs to be closed manually. * * ```ts * const child = Deno.spawnChild(Deno.execPath(), { * args: [ * "eval", * "console.log('Hello World')", * ], * stdin: "piped", * }); * * // open a file and pipe the subprocess output to it. * child.stdout.pipeTo(Deno.openSync("output").writable); * * // manually close stdin * child.stdin.close(); * const status = await child.status; * ``` * * @category Sub Process */ export function spawnChild( command: string | URL, options?: SpawnOptions, ): Child; /** **UNSTABLE**: New API, yet to be vetted. * * @deprecated Use the Deno.Command API instead. * * The interface for handling a child process returned from * {@linkcode Deno.spawnChild}. * * @category Sub Process */ export class Child { get stdin(): WritableStream; get stdout(): ReadableStream; get stderr(): ReadableStream; readonly pid: number; /** Get the status of the child. */ readonly status: Promise; /** Waits for the child to exit completely, returning all its output and * status. */ output(): Promise; /** 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. * * @deprecated Use the Deno.Command API instead. * * 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 * corresponding field on `SpawnOutput` will throw a `TypeError`. * * ```ts * const { code, stdout, stderr } = await Deno.spawn(Deno.execPath(), { * args: [ * "eval", * "console.log('hello'); console.error('world')", * ], * }); * console.assert(code === 0); * console.assert("hello\n" === new TextDecoder().decode(stdout)); * console.assert("world\n" === new TextDecoder().decode(stderr)); * ``` * * @category Sub Process */ export function spawn( command: string | URL, options?: SpawnOptions, ): Promise; /** **UNSTABLE**: New API, yet to be vetted. * * @deprecated Use the Deno.Command API instead. * * 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 * corresponding field on `SpawnOutput` will throw a `TypeError`. * * ```ts * const { code, stdout, stderr } = Deno.spawnSync(Deno.execPath(), { * args: [ * "eval", * "console.log('hello'); console.error('world')", * ], * }); * console.assert(code === 0); * console.assert("hello\n" === new TextDecoder().decode(stdout)); * console.assert("world\n" === new TextDecoder().decode(stderr)); * ``` * * @category Sub Process */ export function spawnSync( command: string | URL, options?: SpawnOptions, ): SpawnOutput; /** **UNSTABLE**: New API, yet to be vetted. * * @deprecated Use the Deno.Command API instead. * * @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. * * @deprecated Use the Deno.Command API instead. * * 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 { /** 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. * * Create a child process. * * If any stdio options are not set to `"piped"`, accessing the corresponding * field on the `Command` or its `CommandOutput` will throw a `TypeError`. * * If `stdin` is set to `"piped"`, the `stdin` {@linkcode WritableStream} * needs to be closed manually. * * ```ts * const command = new Deno.Command(Deno.execPath(), { * args: [ * "eval", * "console.log('Hello World')", * ], * stdin: "piped", * }); * command.spawn(); * * // open a file and pipe the subprocess output to it. * command.stdout.pipeTo(Deno.openSync("output").writable); * * // manually close stdin * command.stdin.close(); * const status = await command.status; * ``` * * ```ts * const command = new Deno.Command(Deno.execPath(), { * args: [ * "eval", * "console.log('hello'); console.error('world')", * ], * }); * const { code, stdout, stderr } = await command.output(); * console.assert(code === 0); * console.assert("hello\n" === new TextDecoder().decode(stdout)); * console.assert("world\n" === new TextDecoder().decode(stderr)); * ``` * * ```ts * const command = new Deno.Command(Deno.execPath(), { * args: [ * "eval", * "console.log('hello'); console.error('world')", * ], * }); * const { code, stdout, stderr } = command.outputSync(); * console.assert(code === 0); * console.assert("hello\n" === new TextDecoder().decode(stdout)); * console.assert("world\n" === new TextDecoder().decode(stderr)); * ``` * * @category Sub Process */ export class Command { get stdin(): WritableStream; get stdout(): ReadableStream; get stderr(): ReadableStream; readonly pid: number; /** Get the status of the child process. */ readonly status: Promise; constructor(command: string | URL, options?: CommandOptions); /** * Executes the {@linkcode Deno.Command}, waiting for it to finish and * collecting all of its output. * If `spawn()` was called, calling this function will collect the remaining * output. * * Will throw an error if `stdin: "piped"` is set. * * If options `stdout` or `stderr` are not set to `"piped"`, accessing the * corresponding field on {@linkcode Deno.CommandOutput} will throw a `TypeError`. */ output(): Promise; /** * Synchronously executes the {@linkcode Deno.Command}, waiting for it to * finish and collecting all of its output. * * Will throw an error if `stdin: "piped"` is set. * * If options `stdout` or `stderr` are not set to `"piped"`, accessing the * corresponding field on {@linkcode Deno.CommandOutput} will throw a `TypeError`. */ outputSync(): CommandOutput; /** * Spawns a streamable subprocess, allowing to use the other methods. */ spawn(): void; /** 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. * * Options which can be set when calling {@linkcode Deno.command}. * * @category Sub Process */ export interface CommandOptions { /** Arguments to pass to the process. */ args?: string[]; /** * The working directory of the process. * * 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 `env` variables are present, as the OS may * set environmental variables for processes. */ clearEnv?: boolean; /** Environmental variables to pass to the subprocess. */ env?: Record; /** * 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 {@linkcode AbortSignal} that allows closing the process using the * corresponding {@linkcode AbortController} by sending the process a * SIGTERM signal. * * Ignored by {@linkcode Command.outputSync}. */ signal?: AbortSignal; /** How `stdin` of the spawned process should be handled. * * Defaults to `"null"`. */ stdin?: "piped" | "inherit" | "null"; /** How `stdout` of the spawned process should be handled. * * Defaults to `"piped"`. */ stdout?: "piped" | "inherit" | "null"; /** 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`. */ windowsRawArguments?: boolean; } /** **UNSTABLE**: New API, yet to be vetted. * * @category Sub Process */ export interface CommandStatus { /** 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. */ signal: Signal | null; } /** **UNSTABLE**: New API, yet to be vetted. * * The interface returned from calling {@linkcode Command.output} or * {@linkcode Command.outputSync} which represents the result of spawning the * child process. * * @category Sub Process */ export interface CommandOutput extends CommandStatus { /** The buffered output from the child process' `stdout`. */ readonly stdout: Uint8Array; /** The buffered output from the child process' `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 */ declare function fetch( input: Request | URL | string, init?: RequestInit & { client: Deno.HttpClient }, ): Promise; /** **UNSTABLE**: New API, yet to be vetted. * * @category Web Workers */ declare interface WorkerOptions { /** **UNSTABLE**: New API, yet to be vetted. * * 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 * - 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: * * ```ts * // mod.ts * const worker = new Worker( * new URL("deno_worker.ts", import.meta.url).href, { * type: "module", * deno: { * permissions: { * read: true, * }, * }, * } * ); * ``` */ deno?: { /** Set to `"none"` to disable all the permissions in the worker. */ permissions?: Deno.PermissionOptions; }; } /** **UNSTABLE**: New API, yet to be vetted. * * @category Web Sockets */ declare interface WebSocketStreamOptions { protocols?: string[]; signal?: AbortSignal; headers?: HeadersInit; } /** **UNSTABLE**: New API, yet to be vetted. * * @category Web Sockets */ declare interface WebSocketConnection { readable: ReadableStream; writable: WritableStream; extensions: string; protocol: string; } /** **UNSTABLE**: New API, yet to be vetted. * * @category Web Sockets */ declare interface WebSocketCloseInfo { code?: number; reason?: string; } /** **UNSTABLE**: New API, yet to be vetted. * * @tags allow-net * @category Web Sockets */ declare class WebSocketStream { constructor(url: string, options?: WebSocketStreamOptions); url: string; connection: Promise; closed: Promise; close(closeInfo?: WebSocketCloseInfo): void; }