mirror of
https://github.com/denoland/deno.git
synced 2024-12-22 15:24:46 -05:00
1764 lines
51 KiB
TypeScript
Vendored
1764 lines
51 KiB
TypeScript
Vendored
// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
|
||
|
||
/// <reference no-default-lib="true" />
|
||
/// <reference lib="deno.ns" />
|
||
|
||
declare namespace Deno {
|
||
export {}; // stop default export type behavior
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category Testing
|
||
*/
|
||
export interface BenchDefinition {
|
||
fn: () => void | Promise<void>;
|
||
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<void> => {
|
||
* 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>,
|
||
): 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<void> {
|
||
* 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>): 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<void> => {
|
||
* 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<BenchDefinition, "fn" | "name">,
|
||
fn: () => void | Promise<void>,
|
||
): 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<void> => {
|
||
* 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<BenchDefinition, "fn">,
|
||
fn: () => void | Promise<void>,
|
||
): 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<void> {
|
||
* 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<BenchDefinition, "fn" | "name">,
|
||
fn: () => void | Promise<void>,
|
||
): 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<NativeNumberType, number>
|
||
& Record<NativeBigIntType, PointerValue>
|
||
& Record<NativeBooleanType, boolean>
|
||
& Record<NativePointerType, PointerValue | null>
|
||
& Record<NativeFunctionType, PointerValue | null>
|
||
& Record<NativeBufferType, TypedArray | null>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Type conversion for foreign symbol parameters and unsafe callback return
|
||
* types.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type ToNativeType<T extends NativeType = NativeType> = ToNativeTypeMap[T];
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type ToNativeResultTypeMap = ToNativeTypeMap & Record<NativeVoidType, void>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Type conversion for unsafe callback return types.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type ToNativeResultType<T extends NativeResultType = NativeResultType> =
|
||
ToNativeResultTypeMap[T];
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type ToNativeParameterTypes<T extends readonly NativeType[]> =
|
||
//
|
||
[(T[number])[]] extends [T] ? ToNativeType<T[number]>[]
|
||
: [readonly (T[number])[]] extends [T]
|
||
? readonly ToNativeType<T[number]>[]
|
||
: T extends readonly [...NativeType[]] ? {
|
||
[K in keyof T]: ToNativeType<T[K]>;
|
||
}
|
||
: never;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromNativeTypeMap =
|
||
& Record<NativeNumberType, number>
|
||
& Record<NativeBigIntType, PointerValue>
|
||
& Record<NativeBooleanType, boolean>
|
||
& Record<NativePointerType, PointerValue>
|
||
& Record<NativeBufferType, PointerValue>
|
||
& Record<NativeFunctionType, PointerValue>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Type conversion for foreign symbol return types and unsafe callback
|
||
* parameters.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromNativeType<T extends NativeType = NativeType> = FromNativeTypeMap[T];
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromNativeResultTypeMap =
|
||
& FromNativeTypeMap
|
||
& Record<NativeVoidType, void>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Type conversion for foreign symbol return types.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromNativeResultType<T extends NativeResultType = NativeResultType> =
|
||
FromNativeResultTypeMap[T];
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromNativeParameterTypes<
|
||
T extends readonly NativeType[],
|
||
> =
|
||
//
|
||
[(T[number])[]] extends [T] ? FromNativeType<T[number]>[]
|
||
: [readonly (T[number])[]] extends [T]
|
||
? readonly FromNativeType<T[number]>[]
|
||
: T extends readonly [...NativeType[]] ? {
|
||
[K in keyof T]: FromNativeType<T[K]>;
|
||
}
|
||
: 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<Type extends NativeType = NativeType> {
|
||
/** 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 | ForeignStatic> =
|
||
T extends ForeignFunction ? FromForeignFunction<T>
|
||
: T extends ForeignStatic ? FromNativeType<T["type"]>
|
||
: never;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type FromForeignFunction<T extends ForeignFunction> = T["parameters"] extends
|
||
readonly [] ? () => StaticForeignSymbolReturnType<T>
|
||
: (
|
||
...args: ToNativeParameterTypes<T["parameters"]>
|
||
) => StaticForeignSymbolReturnType<T>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type StaticForeignSymbolReturnType<T extends ForeignFunction> =
|
||
ConditionalAsync<T["nonblocking"], FromNativeResultType<T["result"]>>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type ConditionalAsync<IsAsync extends boolean | undefined, T> =
|
||
IsAsync extends true ? Promise<T> : T;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Infers a foreign library interface.
|
||
*
|
||
* @category FFI
|
||
*/
|
||
type StaticForeignLibraryInterface<T extends ForeignLibraryInterface> = {
|
||
[K in keyof T]: StaticForeignSymbol<T[K]>;
|
||
};
|
||
|
||
/** **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<Fn extends ForeignFunction> {
|
||
pointer: bigint;
|
||
definition: Fn;
|
||
|
||
constructor(pointer: bigint, definition: Fn);
|
||
|
||
call: FromForeignFunction<Fn>;
|
||
}
|
||
|
||
/** **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<Result> : (
|
||
...args: FromNativeParameterTypes<Parameters>
|
||
) => ToNativeResultType<Result>;
|
||
|
||
/** **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.
|
||
*
|
||
* If the callback's reference count becomes non-zero, it will keep
|
||
* Deno's process from exiting.
|
||
*/
|
||
ref(): void;
|
||
|
||
/**
|
||
* Removes one from this callback's reference counting.
|
||
*
|
||
* If the callback's reference counter becomes zero, it will no longer
|
||
* keep Deno's process from exiting.
|
||
*/
|
||
unref(): void;
|
||
|
||
/**
|
||
* 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<S extends ForeignLibraryInterface> {
|
||
/** All of the registered library along with functions for calling them */
|
||
symbols: StaticForeignLibraryInterface<S>;
|
||
close(): void;
|
||
}
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Opens a dynamic library and registers symbols
|
||
*
|
||
* @category FFI
|
||
*/
|
||
export function dlopen<S extends ForeignLibraryInterface>(
|
||
filename: string | URL,
|
||
symbols: S,
|
||
): DynamicLibrary<S>;
|
||
|
||
/** **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<void>;
|
||
|
||
/** **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<T>;
|
||
|
||
/** **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<void>;
|
||
|
||
/** **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<number>;
|
||
/** 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<TcpConn>;
|
||
export function connect(
|
||
options: UnixConnectOptions,
|
||
): Promise<UnixConn>;
|
||
|
||
/** **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<TlsHandshakeInfo>;
|
||
}
|
||
|
||
/** **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<TlsConn>;
|
||
|
||
/** **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<Conn> {
|
||
/** **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<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 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<void>;
|
||
|
||
/** **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<Response>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* @category HTTP Server
|
||
*/
|
||
export interface ServeOptions extends Partial<Deno.ListenOptions> {
|
||
/** 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<Response>;
|
||
|
||
/** 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://<hostname>:<port>/`
|
||
* 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<void>;
|
||
export function serve(
|
||
options: ServeOptions | ServeTlsOptions,
|
||
handler: ServeHandler,
|
||
): Promise<void>;
|
||
export function serve(
|
||
options: ServeInit & (ServeOptions | ServeTlsOptions),
|
||
): Promise<void>;
|
||
|
||
/** **UNSTABLE**: New API, yet to be vetted.
|
||
*
|
||
* Allows "hijacking" the connection that the request is associated with.
|
||
* This can be used to implement protocols that build on top of HTTP (eg.
|
||
* WebSockets).
|
||
*
|
||
* 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<string, string>;
|
||
/**
|
||
* Sets the child process’s user ID. This translates to a setuid call
|
||
* in the child process. Failure in the setuid call will cause the spawn to fail.
|
||
*/
|
||
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<Uint8Array>;
|
||
get stdout(): ReadableStream<Uint8Array>;
|
||
get stderr(): ReadableStream<Uint8Array>;
|
||
readonly pid: number;
|
||
/** Get the status of the child. */
|
||
readonly status: Promise<ChildStatus>;
|
||
|
||
/** Waits for the child to exit completely, returning all its output and status. */
|
||
output(): Promise<SpawnOutput>;
|
||
/** Kills the process with given Signal. Defaults to SIGTERM. */
|
||
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<SpawnOutput>;
|
||
|
||
/** **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<Response>;
|
||
|
||
/** **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<string | Uint8Array>;
|
||
writable: WritableStream<string | Uint8Array>;
|
||
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<WebSocketConnection>;
|
||
closed: Promise<WebSocketCloseInfo>;
|
||
close(closeInfo?: WebSocketCloseInfo): void;
|
||
}
|