// 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. * * @category Testing */ export interface BenchDefinition { fn: () => void | Promise; name: string; ignore?: boolean; /** Group name for the benchmark. * Grouped benchmarks produce a time summary */ 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 */ 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?: boolean; /** Ensure the bench case does not prematurely cause the process to exit, * for example via a call to `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. * * Defaults to "inherit". */ permissions?: Deno.PermissionOptions; } /** **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. * ```ts * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; * * Deno.bench({ * name: "example test", * fn(): void { * assertEquals("world", "world"); * }, * }); * * Deno.bench({ * name: "example ignored test", * ignore: Deno.build.os === "windows", * fn(): void { * // This test is ignored only on Windows machines * }, * }); * * Deno.bench({ * name: "example async test", * async fn() { * const decoder = new TextDecoder("utf-8"); * const data = await Deno.readFile("hello_world.txt"); * assertEquals(decoder.decode(data), "Hello world"); * } * }); * ``` * * @category Testing */ export function bench(t: BenchDefinition): void; /** **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. * * ```ts * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; * * Deno.bench("My test description", (): void => { * assertEquals("hello", "hello"); * }); * * Deno.bench("My async test description", async (): Promise => { * const decoder = new TextDecoder("utf-8"); * const data = await Deno.readFile("hello_world.txt"); * assertEquals(decoder.decode(data), "Hello world"); * }); * ``` * * @category Testing */ export function bench( name: string, fn: () => void | Promise, ): void; /** **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. * * ```ts * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; * * Deno.bench(function myTestName(): void { * assertEquals("hello", "hello"); * }); * * Deno.bench(async function myOtherTestName(): Promise { * const decoder = new TextDecoder("utf-8"); * const data = await Deno.readFile("hello_world.txt"); * assertEquals(decoder.decode(data), "Hello world"); * }); * ``` * * @category Testing */ export function bench(fn: () => void | Promise): void; /** **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. * * ```ts * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; * * Deno.bench("My test description", { permissions: { read: true } }, (): void => { * assertEquals("hello", "hello"); * }); * * Deno.bench("My async test description", { permissions: { read: false } }, async (): Promise => { * const decoder = new TextDecoder("utf-8"); * const data = await Deno.readFile("hello_world.txt"); * assertEquals(decoder.decode(data), "Hello world"); * }); * ``` * * @category Testing */ export function bench( name: string, options: Omit, fn: () => void | Promise, ): void; /** **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. * * ```ts * import {assert, fail, 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 async test description", permissions: { read: false } }, async (): Promise => { * const decoder = new TextDecoder("utf-8"); * const data = await Deno.readFile("hello_world.txt"); * assertEquals(decoder.decode(data), "Hello world"); * }); * ``` * * @category Testing */ export function bench( options: Omit, fn: () => void | Promise, ): void; /** **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. * * ```ts * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; * * Deno.bench({ permissions: { read: true } }, function myTestName(): void { * assertEquals("hello", "hello"); * }); * * Deno.bench({ permissions: { read: false } }, async function myOtherTestName(): Promise { * const decoder = new TextDecoder("utf-8"); * const data = await Deno.readFile("hello_world.txt"); * assertEquals(decoder.decode(data), "Hello world"); * }); * ``` * * @category Testing */ export function bench( options: Omit, fn: () => void | Promise, ): void; /** **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. * * Gets the size of the console as columns/rows. * * ```ts * const { columns, rows } = Deno.consoleSize(Deno.stdout.rid); * ``` * * @category I/O */ export function consoleSize( rid: number, ): { columns: number; rows: number; }; /** **UNSTABLE**: New API, yet to be vetted. * * Returns an array containing the 1, 5, and 15 minute load averages. The * load average is a measure of CPU and IO utilization of the last one, five, * and 15 minute periods expressed as a fractional number. Zero means there * is no load. On Windows, the three values are always the same and represent * the current load, not the 1, 5 and 15 minute load averages. * * ```ts * console.log(Deno.loadavg()); // e.g. [ 0.71, 0.44, 0.44 ] * ``` * * Requires `allow-sys` permission. * There are questions around which permission this needs. And maybe should be * renamed (loadAverage?). * * @tags allow-sys * @category Observability */ export function loadavg(): number[]; /** **UNSTABLE**: New API, yet to be vetted. * * Returns the release version of the Operating System. * * ```ts * console.log(Deno.osRelease()); * ``` * * Requires `allow-sys` permission. * Under consideration to possibly move to Deno.build or Deno.versions and if * it should depend sys-info, which may not be desirable. * * @tags allow-sys * @category Runtime Environment */ export function osRelease(): string; /** **UNSTABLE**: New API, yet to be vetted. * * Displays the total amount of free and used physical and swap memory in the * system, as well as the buffers and caches used by the kernel. * * This is similar to the `free` command in Linux * * ```ts * console.log(Deno.systemMemoryInfo()); * ``` * * Requires `allow-sys` permission. * * @tags allow-sys * @category Runtime Environment */ export function systemMemoryInfo(): SystemMemoryInfo; /** **UNSTABLE**: New API, yet to be vetted. * * @category Runtime Environment */ export interface SystemMemoryInfo { /** Total installed memory */ total: number; /** Unused memory */ free: number; /** Estimation of how much memory 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 */ available: number; /** Memory used by kernel buffers */ buffers: number; /** Memory used by the page cache and slabs */ cached: number; /** Total swap memory */ swapTotal: number; /** Unused swap memory */ swapFree: number; } /** **UNSTABLE**: New API, yet to be vetted. * * The information of the network interface. * * @category Network */ export interface NetworkInterfaceInfo { /** The network interface name */ name: string; /** The IP protocol version */ family: "IPv4" | "IPv6"; /** The IP address */ address: string; /** The netmask */ netmask: string; /** The IPv6 scope id or null */ scopeid: number | null; /** The CIDR range */ cidr: string; /** The MAC address */ mac: string; } /** **UNSTABLE**: New API, yet to be vetted. * * Returns an array of the network interface information. * * ```ts * console.log(Deno.networkInterfaces()); * ``` * * Requires `allow-sys` permission. * * @tags allow-sys * @category Network */ export function networkInterfaces(): NetworkInterfaceInfo[]; /** **UNSTABLE**: New API, yet to be vetted. * * Returns the user id of the process on POSIX platforms. Returns null on Windows. * * ```ts * console.log(Deno.getUid()); * ``` * * Requires `allow-sys` permission. * * @tags allow-sys * @category Runtime Environment */ export function getUid(): number | null; /** **UNSTABLE**: New API, yet to be vetted. * * Returns the group id of the process on POSIX platforms. Returns null on windows. * * ```ts * console.log(Deno.getGid()); * ``` * * Requires `allow-sys` permission. * * @tags allow-sys * @category Runtime Environment */ export function getGid(): number | null; /** **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. * * @category FFI */ type NativeBooleanType = "bool"; /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ type NativePointerType = "pointer"; /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ type NativeBufferType = "buffer"; /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ type NativeFunctionType = "function"; /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ type NativeVoidType = "void"; /** **UNSTABLE**: New API, yet to be vetted. * * All possible 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. * * @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. * * @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. * * @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. * * @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. * * @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. * * 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; parameters: Parameters; 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 JS or trigger a GC 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; 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. * * 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. * * Infers a foreign library interface. * * @category FFI */ type StaticForeignLibraryInterface = { [K in keyof T]: StaticForeignSymbol; }; /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ type TypedArray = | Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Uint8ClampedArray | Float32Array | Float64Array | BigInt64Array | BigUint64Array; /** **UNSTABLE**: New API, yet to be vetted. * * 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`. * * @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 | TypedArray): 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). * * @category FFI */ export class UnsafePointerView { constructor(pointer: bigint); pointer: bigint; /** 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: TypedArray, 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: TypedArray, 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 { pointer: bigint; definition: Fn; constructor(pointer: bigint, definition: Fn); call: FromForeignFunction; } /** **UNSTABLE**: New API, yet to be vetted. * * @category FFI */ export interface UnsafeCallbackDefinition< Parameters extends readonly NativeType[] = readonly NativeType[], Result extends NativeResultType = NativeResultType, > { parameters: Parameters; result: Result; } /** **UNSTABLE**: New API, yet to be vetted. * * @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 ffi 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. * * @category FFI */ export class UnsafeCallback< Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition, > { constructor( definition: Definition, callback: UnsafeCallbackFunction< Definition["parameters"], Definition["result"] >, ); pointer: bigint; definition: Definition; 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 becomes 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 becomes 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. * * 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 * * @category FFI */ export interface DynamicLibrary { /** All of the registered library along with functions for calling them */ symbols: StaticForeignLibraryInterface; close(): void; } /** **UNSTABLE**: New API, yet to be vetted. * * Opens a dynamic library and registers symbols * * @category FFI */ export function dlopen( filename: string | URL, symbols: S, ): DynamicLibrary; /** **UNSTABLE**: needs investigation into high precision time. * * Synchronously changes the access (`atime`) and modification (`mtime`) times * of a file system object referenced by `path`. Given times are either in * seconds (UNIX epoch time) or as `Date` objects. * * ```ts * Deno.utimeSync("myfile.txt", 1556495550, new Date()); * ``` * * Requires `allow-write` permission. * Needs investigation into high precision time. * * @tags allow-write * @category File System */ export function utimeSync( path: string | URL, atime: number | Date, mtime: number | Date, ): void; /** **UNSTABLE**: New API, yet to be vetted. * * Changes the access (`atime`) and modification (`mtime`) times of a file * system object referenced by `path`. Given times are either in seconds * (UNIX epoch time) or as `Date` objects. * * ```ts * await Deno.utime("myfile.txt", 1556495550, new Date()); * ``` * * Requires `allow-write` permission. * Needs investigation into high precision time. * * @tags allow-write * @category File System */ export function utime( path: string | URL, atime: number | Date, mtime: number | Date, ): Promise; /** **UNSTABLE**: New API, yet to be vetted. * * @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; /** **UNSTABLE**: New API, yet to be vetted. * * A custom HttpClient for use 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 class HttpClient { rid: number; close(): void; } /** **UNSTABLE**: New API, yet to be vetted. * * The options used when creating a [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. * * @category Fetch API */ export interface Proxy { url: string; basicAuth?: BasicAuth; } /** **UNSTABLE**: New API, yet to be vetted. * * @category Fetch API */ export interface BasicAuth { username: string; password: string; } /** **UNSTABLE**: New API, yet to be vetted. * * Create a custom HttpClient for to use with `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. * * Synchronously changes the access (`atime`) and modification (`mtime`) times * of a file stream resource referenced by `rid`. Given times are either in * seconds (UNIX epoch time) or as `Date` objects. * * ```ts * const file = Deno.openSync("file.txt", { create: true, write: true }); * Deno.futimeSync(file.rid, 1556495550, new Date()); * ``` * * Needs investigation into high precision time. * * @category File System */ export function futimeSync( rid: number, atime: number | Date, mtime: number | Date, ): void; /** **UNSTABLE**: New API, yet to be vetted. * * Changes the access (`atime`) and modification (`mtime`) times of a file * stream resource referenced by `rid`. Given times are either in seconds * (UNIX epoch time) or as `Date` objects. * * ```ts * const file = await Deno.open("file.txt", { create: true, write: true }); * await Deno.futime(file.rid, 1556495550, new Date()); * ``` * * Needs investigation into high precision time. * * @category File System */ export function futime( rid: number, atime: number | Date, mtime: number | Date, ): Promise; /** **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 `UDPConn`. */ receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>; /** Sends a message to the target. */ 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 `UDPConn`. */ readonly addr: Addr; [Symbol.asyncIterator](): AsyncIterableIterator<[Uint8Array, Addr]>; } /** **UNSTABLE**: New API, yet to be vetted. * * @category Network */ export interface UnixListenOptions { /** A Path to the Unix Socket. */ path: string; } /** **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: ListenOptions & { 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; 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 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. * * @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. * * @category HTTP Server */ export interface ServeOptions extends Partial { /** An AbortSignal to close the server and all connections. */ signal?: AbortSignal; /** Sets SO_REUSEPORT on Linux. */ 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 started listening */ onListen?: (params: { hostname: string; port: number }) => void; } /** **UNSTABLE**: New API, yet to be vetted. * * @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 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 start up. If you like to change this behaviour, 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; export function serve( options: ServeOptions | ServeTlsOptions, handler: ServeHandler, ): Promise; 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. * WebSockets). * * 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 `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. * 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. * * This method can only be called on requests originating the `Deno.serve` * server. * * @category HTTP Server */ export function upgradeHttpRaw(request: Request): [Deno.Conn, Uint8Array]; /** **UNSTABLE**: New API, yet to be vetted. * * @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 `opt.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 setuid 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. */ signal?: AbortSignal; /** Defaults to "null". */ stdin?: "piped" | "inherit" | "null"; /** Defaults to "piped". */ stdout?: "piped" | "inherit" | "null"; /** Defaults to "piped". */ stderr?: "piped" | "inherit" | "null"; } /** **UNSTABLE**: New API, yet to be vetted. * * 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 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. * * @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 Signal. Defaults to SIGTERM. */ kill(signo?: Signal): void; ref(): void; unref(): void; } /** **UNSTABLE**: New API, yet to be vetted. * * 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. * * 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. * * @category Sub Process */ export interface ChildStatus { success: boolean; code: number; signal: Signal | null; } /** **UNSTABLE**: New API, yet to be vetted. * * @category Sub Process */ export interface SpawnOutput extends ChildStatus { get stdout(): Uint8Array; get stderr(): Uint8Array; } } /** **UNSTABLE**: New API, yet to be vetted. * * @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 * - 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) * * 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; }