2022-01-20 02:10:16 -05:00
// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
2020-04-30 11:23:40 -04:00
/// <reference no-default-lib="true" />
/// <reference lib="deno.ns" />
declare namespace Deno {
2022-07-04 01:41:52 -04:00
export { } ; // stop default export type behavior
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Testing
* /
2022-03-11 17:07:02 -05:00
export interface BenchDefinition {
fn : ( ) = > void | Promise < void > ;
name : string ;
ignore? : boolean ;
2022-04-20 15:06:39 -04:00
/ * * G r o u p n a m e f o r t h e b e n c h m a r k .
* Grouped benchmarks produce a time summary * /
group? : string ;
/ * * B e n c h m a r k s h o u l d b e u s e d a s t h e b a s e l i n e f o r o t h e r b e n c h m a r k s
* If there are multiple baselines in a group , the first one is used as the baseline * /
baseline? : boolean ;
2022-03-11 17:07:02 -05:00
/ * * I f a t l e a s t o n e b e n c h h a s ` o n l y ` s e t t o t r u e , o n l y r u n b e n c h e s t h a t h a v e
* ` only ` set to true and fail the bench suite . * /
only? : boolean ;
/ * * E n s u r e t h e b e n c h c a s e d o e s n o t p r e m a t u r e l y c a u s e t h e p r o c e s s t o e x i t ,
* for example via a call to ` Deno.exit ` . Defaults to true . * /
sanitizeExit? : boolean ;
/ * * S p e c i f i e s t h e p e r m i s s i o n s t h a t s h o u l d b e u s e d t o r u n t h e b e n c h .
* 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 ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Register a bench which will be run when ` deno bench ` is used on the command
2022-03-11 17:07:02 -05:00
* 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" ) ;
* }
* } ) ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category Testing
2022-03-11 17:07:02 -05:00
* /
export function bench ( t : BenchDefinition ) : void ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Register a bench which will be run when ` deno bench ` is used on the command
2022-03-11 17:07:02 -05:00
* 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" ) ;
* } ) ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category Testing
2022-03-11 17:07:02 -05:00
* /
export function bench (
name : string ,
fn : ( ) = > void | Promise < void > ,
) : void ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Register a bench which will be run when ` deno bench ` is used on the command
2022-03-11 17:07:02 -05:00
* 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" ) ;
* } ) ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category Testing
2022-03-11 17:07:02 -05:00
* /
export function bench ( fn : ( ) = > void | Promise < void > ) : void ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Register a bench which will be run when ` deno bench ` is used on the command
2022-03-11 17:07:02 -05:00
* 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" ) ;
* } ) ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category Testing
2022-03-11 17:07:02 -05:00
* /
export function bench (
name : string ,
options : Omit < BenchDefinition , " fn " | " name " > ,
fn : ( ) = > void | Promise < void > ,
) : void ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Register a bench which will be run when ` deno bench ` is used on the command
2022-03-11 17:07:02 -05:00
* 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" ) ;
* } ) ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category Testing
2022-03-11 17:07:02 -05:00
* /
export function bench (
options : Omit < BenchDefinition , " fn " > ,
fn : ( ) = > void | Promise < void > ,
) : void ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Register a bench which will be run when ` deno bench ` is used on the command
2022-03-11 17:07:02 -05:00
* 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" ) ;
* } ) ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category Testing
2022-03-11 17:07:02 -05:00
* /
export function bench (
options : Omit < BenchDefinition , " fn " | " name " > ,
fn : ( ) = > void | Promise < void > ,
) : void ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2020-04-30 11:23:40 -04:00
*
* Retrieve the process umask . If ` mask ` is provided , sets the process umask .
* This call always returns what the umask was before the call .
*
2020-05-16 15:23:48 -04:00
* ` ` ` ts
* console . log ( Deno . umask ( ) ) ; // e.g. 18 (0o022)
* const prevUmaskValue = Deno . umask ( 0 o077 ) ; // e.g. 18 (0o022)
* console . log ( Deno . umask ( ) ) ; // e.g. 63 (0o077)
* ` ` `
2020-04-30 11:23:40 -04:00
*
2022-09-15 10:37:35 -04:00
* This API is under consideration to determine if permissions are required to
* call it .
*
2020-04-30 11:23:40 -04:00
* NOTE : This API is not implemented on Windows
2022-08-16 23:12:24 -04:00
*
* @category File System
2020-04-30 11:23:40 -04:00
* /
export function umask ( mask? : number ) : number ;
2022-09-15 08:09:23 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Gets the size of the console as columns / rows .
2020-07-10 10:07:12 -04:00
*
* ` ` ` ts
2020-08-10 23:22:10 -04:00
* const { columns , rows } = Deno . consoleSize ( Deno . stdout . rid ) ;
2020-07-10 10:07:12 -04:00
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category I / O
2020-07-10 10:07:12 -04:00
* /
export function consoleSize (
2020-07-14 15:24:17 -04:00
rid : number ,
2020-07-10 10:07:12 -04:00
) : {
columns : number ;
rows : number ;
} ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2020-06-03 13:46:09 -04:00
*
* Returns an array containing the 1 , 5 , and 15 minute load averages . The
2020-04-30 11:23:40 -04:00
* 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 .
*
2020-05-16 15:23:48 -04:00
* ` ` ` ts
* console . log ( Deno . loadavg ( ) ) ; // e.g. [ 0.71, 0.44, 0.44 ]
* ` ` `
2020-04-30 11:23:40 -04:00
*
2022-09-28 08:46:50 -04:00
* Requires ` allow-sys ` permission .
2022-09-15 10:37:35 -04:00
* There are questions around which permission this needs . And maybe should be
* renamed ( loadAverage ? ) .
2022-08-16 23:12:24 -04:00
*
2022-09-28 08:46:50 -04:00
* @tags allow - sys
2022-08-16 23:12:24 -04:00
* @category Observability
2020-04-30 11:23:40 -04:00
* /
export function loadavg ( ) : number [ ] ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2020-06-03 13:46:09 -04:00
*
* Returns the release version of the Operating System .
2020-04-30 11:23:40 -04:00
*
2020-05-16 15:23:48 -04:00
* ` ` ` ts
* console . log ( Deno . osRelease ( ) ) ;
* ` ` `
2020-04-30 11:23:40 -04:00
*
2022-09-28 08:46:50 -04:00
* Requires ` allow-sys ` permission .
2022-09-15 10:37:35 -04:00
* Under consideration to possibly move to Deno . build or Deno . versions and if
* it should depend sys - info , which may not be desirable .
2022-08-16 23:12:24 -04:00
*
2022-09-28 08:46:50 -04:00
* @tags allow - sys
2022-08-16 23:12:24 -04:00
* @category Runtime Environment
2020-04-30 11:23:40 -04:00
* /
export function osRelease ( ) : string ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Displays the total amount of free and used physical and swap memory in the
2020-09-10 04:38:17 -04:00
* system , as well as the buffers and caches used by the kernel .
2020-09-19 17:30:59 -04:00
*
2020-09-10 04:38:17 -04:00
* This is similar to the ` free ` command in Linux
*
* ` ` ` ts
* console . log ( Deno . systemMemoryInfo ( ) ) ;
* ` ` `
*
2022-09-28 08:46:50 -04:00
* Requires ` allow-sys ` permission .
2022-08-16 23:12:24 -04:00
*
2022-09-28 08:46:50 -04:00
* @tags allow - sys
2022-08-16 23:12:24 -04:00
* @category Runtime Environment
2020-09-10 04:38:17 -04:00
* /
export function systemMemoryInfo ( ) : SystemMemoryInfo ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Runtime Environment
* /
2020-09-10 04:38:17 -04:00
export interface SystemMemoryInfo {
/** Total installed memory */
total : number ;
/** Unused memory */
free : number ;
/ * * E s t i m a t i o n o f h o w m u c h m e m o r y i s a v a i l a b l e f o r s t a r t i n g n e w
* 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 ;
2022-09-15 10:37:35 -04:00
/** Memory used by the page cache and slabs */
2020-09-10 04:38:17 -04:00
cached : number ;
/** Total swap memory */
swapTotal : number ;
/** Unused swap memory */
swapFree : number ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* The information of the network interface .
2022-08-16 23:12:24 -04:00
*
* @category Network
* /
2022-01-24 04:39:28 -05:00
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 ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
2022-09-15 10:37:35 -04:00
* Returns an array of the network interface information .
2022-01-24 04:39:28 -05:00
*
* ` ` ` ts
* console . log ( Deno . networkInterfaces ( ) ) ;
* ` ` `
*
2022-09-28 08:46:50 -04:00
* Requires ` allow-sys ` permission .
2022-08-16 23:12:24 -04:00
*
2022-09-28 08:46:50 -04:00
* @tags allow - sys
2022-08-16 23:12:24 -04:00
* @category Network
2022-01-24 04:39:28 -05:00
* /
export function networkInterfaces ( ) : NetworkInterfaceInfo [ ] ;
2022-01-31 00:44:19 -05:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
2022-09-15 10:37:35 -04:00
* Returns the user id of the process on POSIX platforms . Returns null on Windows .
2022-01-31 00:44:19 -05:00
*
* ` ` ` ts
* console . log ( Deno . getUid ( ) ) ;
* ` ` `
*
2022-09-28 08:46:50 -04:00
* Requires ` allow-sys ` permission .
2022-08-16 23:12:24 -04:00
*
2022-09-28 08:46:50 -04:00
* @tags allow - sys
2022-08-16 23:12:24 -04:00
* @category Runtime Environment
2022-01-31 00:44:19 -05:00
* /
export function getUid ( ) : number | null ;
2022-05-31 04:42:44 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Returns the group id of the process on POSIX platforms . Returns null on windows .
2022-05-31 04:42:44 -04:00
*
* ` ` ` ts
* console . log ( Deno . getGid ( ) ) ;
* ` ` `
*
2022-09-28 08:46:50 -04:00
* Requires ` allow-sys ` permission .
2022-08-16 23:12:24 -04:00
*
2022-09-28 08:46:50 -04:00
* @tags allow - sys
2022-08-16 23:12:24 -04:00
* @category Runtime Environment
2022-05-31 04:42:44 -04:00
* /
export function getGid ( ) : number | null ;
2022-01-24 04:39:28 -05:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* All plain number types for interfacing with foreign functions .
2022-08-16 23:12:24 -04:00
*
* @category FFI
* /
2022-06-20 22:50:33 -04:00
type NativeNumberType =
2021-08-06 17:28:10 -04:00
| "u8"
| "i8"
| "u16"
| "i16"
| "u32"
| "i32"
2022-06-20 22:50:33 -04:00
| "f32"
| "f64" ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* All BigInt number types for interfacing with foreign functions .
2022-08-16 23:12:24 -04:00
*
* @category FFI
* /
2022-06-20 22:50:33 -04:00
type NativeBigIntType =
2021-08-06 17:28:10 -04:00
| "u64"
| "i64"
| "usize"
2022-06-20 22:50:33 -04:00
| "isize" ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-09-04 23:26:52 -04:00
type NativeBooleanType = "bool" ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-20 22:50:33 -04:00
type NativePointerType = "pointer" ;
2021-08-06 17:28:10 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-08-22 23:46:43 -04:00
type NativeBufferType = "buffer" ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-20 22:50:33 -04:00
type NativeFunctionType = "function" ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-20 22:50:33 -04:00
type NativeVoidType = "void" ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* All possible types for interfacing with foreign functions .
2022-08-16 23:12:24 -04:00
*
* @category FFI
* /
2022-06-20 22:50:33 -04:00
export type NativeType =
| NativeNumberType
| NativeBigIntType
2022-09-04 23:26:52 -04:00
| NativeBooleanType
2022-06-20 22:50:33 -04:00
| NativePointerType
2022-08-22 23:46:43 -04:00
| NativeBufferType
2022-06-20 22:50:33 -04:00
| NativeFunctionType ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-20 22:50:33 -04:00
export type NativeResultType = NativeType | NativeVoidType ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-27 08:41:58 -04:00
type ToNativeTypeMap =
& Record < NativeNumberType , number >
2022-07-24 06:41:11 -04:00
& Record < NativeBigIntType , PointerValue >
2022-09-04 23:26:52 -04:00
& Record < NativeBooleanType , boolean >
2022-08-22 23:46:43 -04:00
& Record < NativePointerType , PointerValue | null >
& Record < NativeFunctionType , PointerValue | null >
2022-09-01 13:31:05 -04:00
& Record < NativeBufferType , TypedArray | null > ;
2022-06-27 08:41:58 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Type conversion for foreign symbol parameters and unsafe callback return
2022-08-16 23:12:24 -04:00
* types .
*
* @category FFI
* /
2022-06-27 08:41:58 -04:00
type ToNativeType < T extends NativeType = NativeType > = ToNativeTypeMap [ T ] ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-27 08:41:58 -04:00
type ToNativeResultTypeMap = ToNativeTypeMap & Record < NativeVoidType , void > ;
2022-06-20 22:50:33 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Type conversion for unsafe callback return types .
2022-08-16 23:12:24 -04:00
*
* @category FFI
* /
2022-06-20 22:50:33 -04:00
type ToNativeResultType < T extends NativeResultType = NativeResultType > =
2022-06-27 08:41:58 -04:00
ToNativeResultTypeMap [ T ] ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-27 08:41:58 -04:00
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 ] > ;
}
2022-06-20 22:50:33 -04:00
: never ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-27 08:41:58 -04:00
type FromNativeTypeMap =
& Record < NativeNumberType , number >
2022-07-24 06:41:11 -04:00
& Record < NativeBigIntType , PointerValue >
2022-09-04 23:26:52 -04:00
& Record < NativeBooleanType , boolean >
2022-07-24 06:41:11 -04:00
& Record < NativePointerType , PointerValue >
2022-08-22 23:46:43 -04:00
& Record < NativeBufferType , PointerValue >
2022-07-24 06:41:11 -04:00
& Record < NativeFunctionType , PointerValue > ;
2022-06-20 22:50:33 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Type conversion for foreign symbol return types and unsafe callback
2022-08-16 23:12:24 -04:00
* parameters .
*
* @category FFI
* /
2022-06-27 08:41:58 -04:00
type FromNativeType < T extends NativeType = NativeType > = FromNativeTypeMap [ T ] ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-27 08:41:58 -04:00
type FromNativeResultTypeMap =
& FromNativeTypeMap
& Record < NativeVoidType , void > ;
2022-06-20 22:50:33 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Type conversion for foreign symbol return types .
2022-08-16 23:12:24 -04:00
*
* @category FFI
* /
2022-06-20 22:50:33 -04:00
type FromNativeResultType < T extends NativeResultType = NativeResultType > =
2022-06-27 08:41:58 -04:00
FromNativeResultTypeMap [ T ] ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-27 08:41:58 -04:00
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 ] > ;
}
2022-06-20 22:50:33 -04:00
: never ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* A foreign function as defined by its parameter and result types .
2022-08-16 23:12:24 -04:00
*
* @category FFI
* /
2022-01-10 10:33:25 -05:00
export interface ForeignFunction <
2022-06-20 22:50:33 -04:00
Parameters extends readonly NativeType [ ] = readonly NativeType [ ] ,
Result extends NativeResultType = NativeResultType ,
2022-01-10 10:33:25 -05:00
NonBlocking extends boolean = boolean ,
> {
2022-01-11 01:21:16 -05:00
/** Name of the symbol, defaults to the key name in symbols object. */
name? : string ;
2022-01-10 10:33:25 -05:00
parameters : Parameters ;
result : Result ;
2021-10-11 09:09:11 -04:00
/** When true, function calls will run on a dedicated blocking thread and will return a Promise resolving to the `result`. */
2022-01-10 10:33:25 -05:00
nonblocking? : NonBlocking ;
2022-07-09 09:11:07 -04:00
/** When true, function calls can safely callback into JS or trigger a GC event. Default is `false`. */
callback? : boolean ;
2021-08-06 17:28:10 -04:00
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-02-18 07:21:19 -05:00
export interface ForeignStatic < Type extends NativeType = NativeType > {
/** Name of the symbol, defaults to the key name in symbols object. */
name? : string ;
2022-06-20 22:50:33 -04:00
type : Type ;
2022-02-18 07:21:19 -05:00
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* A foreign library interface descriptor .
2022-08-16 23:12:24 -04:00
*
* @category FFI
* /
2022-02-18 07:21:19 -05:00
export interface ForeignLibraryInterface {
[ name : string ] : ForeignFunction | ForeignStatic ;
2022-01-10 10:33:25 -05:00
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Infers a foreign symbol .
2022-08-16 23:12:24 -04:00
*
* @category FFI
* /
2022-02-18 07:21:19 -05:00
type StaticForeignSymbol < T extends ForeignFunction | ForeignStatic > =
2022-06-20 22:50:33 -04:00
T extends ForeignFunction ? FromForeignFunction < T >
: T extends ForeignStatic ? FromNativeType < T [ " type " ] >
2022-02-18 07:21:19 -05:00
: never ;
2022-01-10 10:33:25 -05:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-20 22:50:33 -04:00
type FromForeignFunction < T extends ForeignFunction > = T [ "parameters" ] extends
readonly [ ] ? ( ) = > StaticForeignSymbolReturnType < T >
: (
. . . args : ToNativeParameterTypes < T [ " parameters " ] >
) = > StaticForeignSymbolReturnType < T > ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-20 22:50:33 -04:00
type StaticForeignSymbolReturnType < T extends ForeignFunction > =
ConditionalAsync < T [ " nonblocking " ] , FromNativeResultType < T [ " result " ] > > ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-01-10 10:33:25 -05:00
type ConditionalAsync < IsAsync extends boolean | undefined , T > =
IsAsync extends true ? Promise < T > : T ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Infers a foreign library interface .
2022-08-16 23:12:24 -04:00
*
* @category FFI
* /
2022-02-18 07:21:19 -05:00
type StaticForeignLibraryInterface < T extends ForeignLibraryInterface > = {
[ K in keyof T ] : StaticForeignSymbol < T [ K ] > ;
2022-01-10 10:33:25 -05:00
} ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2021-12-15 09:41:49 -05:00
type TypedArray =
| Int8Array
| Uint8Array
| Int16Array
| Uint16Array
| Int32Array
| Uint32Array
| Uint8ClampedArray
| Float32Array
| Float64Array
| BigInt64Array
| BigUint64Array ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
2022-07-24 06:41:11 -04:00
* 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 ` .
2022-08-16 23:12:24 -04:00
*
* @category FFI
2022-07-24 06:41:11 -04:00
* /
export type PointerValue = number | bigint ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* An unsafe pointer to a memory location for passing and returning pointers
2022-08-16 23:12:24 -04:00
* to and from the FFI .
*
* @category FFI
2021-12-15 09:41:49 -05:00
* /
export class UnsafePointer {
/ * *
* Return the direct memory pointer to the typed array in memory
* /
2022-07-24 06:41:11 -04:00
static of ( value : Deno.UnsafeCallback | TypedArray ) : PointerValue ;
2021-12-15 09:41:49 -05:00
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* An unsafe pointer view to a memory location as specified by the ` pointer `
2021-12-15 09:41:49 -05:00
* 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 ) .
2022-08-16 23:12:24 -04:00
*
* @category FFI
2021-12-15 09:41:49 -05:00
* /
export class UnsafePointerView {
2022-06-20 09:38:10 -04:00
constructor ( pointer : bigint ) ;
2021-12-15 09:41:49 -05:00
2022-06-20 09:38:10 -04:00
pointer : bigint ;
2021-12-15 09:41:49 -05:00
2022-09-04 23:26:52 -04:00
/** Gets a boolean at the specified byte offset from the pointer. */
getBool ( offset? : number ) : boolean ;
2021-12-15 09:41:49 -05:00
/** 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. */
2022-07-24 06:41:11 -04:00
getBigUint64 ( offset? : number ) : PointerValue ;
2021-12-15 09:41:49 -05:00
/** Gets a signed 64-bit integer at the specified byte offset from the pointer. */
2022-07-24 06:41:11 -04:00
getBigInt64 ( offset? : number ) : PointerValue ;
2021-12-15 09:41:49 -05:00
/** 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 ;
2022-08-05 12:27:12 -04:00
/** Gets a C string (null terminated string) at the specified byte offset from the specified pointer. */
2022-09-01 13:31:05 -04:00
static getCString ( pointer : PointerValue , offset? : number ) : string ;
2021-12-15 09:41:49 -05:00
/** Gets an ArrayBuffer of length `byteLength` at the specified byte offset from the pointer. */
getArrayBuffer ( byteLength : number , offset? : number ) : ArrayBuffer ;
2022-08-05 12:27:12 -04:00
/** Gets an ArrayBuffer of length `byteLength` at the specified byte offset from the specified pointer. */
static getArrayBuffer (
2022-09-01 13:31:05 -04:00
pointer : PointerValue ,
2022-08-05 12:27:12 -04:00
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. */
2021-12-15 09:41:49 -05:00
copyInto ( destination : TypedArray , offset? : number ) : void ;
2022-08-05 12:27:12 -04:00
/** 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 (
2022-09-01 13:31:05 -04:00
pointer : PointerValue ,
2022-08-05 12:27:12 -04:00
destination : TypedArray ,
offset? : number ,
) : void ;
2021-12-15 09:41:49 -05:00
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* An unsafe pointer to a function , for calling functions that are not
2022-01-12 06:38:26 -05:00
* present as symbols .
2022-08-16 23:12:24 -04:00
*
* @category FFI
2022-01-12 06:38:26 -05:00
* /
export class UnsafeFnPointer < Fn extends ForeignFunction > {
2022-06-20 09:38:10 -04:00
pointer : bigint ;
2022-01-12 06:38:26 -05:00
definition : Fn ;
2022-06-20 09:38:10 -04:00
constructor ( pointer : bigint , definition : Fn ) ;
2022-01-12 06:38:26 -05:00
2022-06-20 22:50:33 -04:00
call : FromForeignFunction < Fn > ;
2022-01-12 06:38:26 -05:00
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-20 07:06:04 -04:00
export interface UnsafeCallbackDefinition <
Parameters extends readonly NativeType [ ] = readonly NativeType [ ] ,
2022-06-20 22:50:33 -04:00
Result extends NativeResultType = NativeResultType ,
2022-06-20 07:06:04 -04:00
> {
parameters : Parameters ;
result : Result ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category FFI
* /
2022-06-20 07:06:04 -04:00
type UnsafeCallbackFunction <
Parameters extends readonly NativeType [ ] = readonly NativeType [ ] ,
2022-06-20 22:50:33 -04:00
Result extends NativeResultType = NativeResultType ,
> = Parameters extends readonly [ ] ? ( ) = > ToNativeResultType < Result > : (
. . . args : FromNativeParameterTypes < Parameters >
) = > ToNativeResultType < Result > ;
2022-06-20 07:06:04 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* An unsafe function pointer for passing JavaScript functions
2022-06-20 07:06:04 -04:00
* as C function pointers to ffi calls .
*
* The function pointer remains valid until the ` close() ` method is called .
2022-06-28 05:23:36 -04:00
*
* The callback can be explicitly ref 'ed and deref' ed to stop Deno ' s
* process from exiting .
2022-08-16 23:12:24 -04:00
*
* @category FFI
2022-06-20 07:06:04 -04:00
* /
export class UnsafeCallback <
2022-06-20 22:50:33 -04:00
Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition ,
2022-06-20 07:06:04 -04:00
> {
constructor (
2022-06-20 22:50:33 -04:00
definition : Definition ,
callback : UnsafeCallbackFunction <
Definition [ "parameters" ] ,
Definition [ "result" ]
> ,
2022-06-20 07:06:04 -04:00
) ;
2022-06-20 09:38:10 -04:00
pointer : bigint ;
2022-06-20 22:50:33 -04:00
definition : Definition ;
callback : UnsafeCallbackFunction <
Definition [ "parameters" ] ,
Definition [ "result" ]
> ;
2022-06-20 07:06:04 -04:00
2022-06-28 05:23:36 -04:00
/ * *
2022-10-15 09:49:46 -04:00
* Adds one to this callback ' s reference counting and returns the
* new reference count .
2022-06-28 05:23:36 -04:00
*
* If the callback ' s reference count becomes non - zero , it will keep
* Deno ' s process from exiting .
* /
2022-10-15 09:49:46 -04:00
ref ( ) : number ;
2022-06-28 05:23:36 -04:00
/ * *
2022-10-15 09:49:46 -04:00
* Removes one from this callback ' s reference counting and returns
* the new reference count .
2022-06-28 05:23:36 -04:00
*
* If the callback ' s reference counter becomes zero , it will no longer
* keep Deno ' s process from exiting .
* /
2022-10-15 09:49:46 -04:00
unref ( ) : number ;
2022-06-28 05:23:36 -04:00
/ * *
* 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 .
* /
2022-06-20 07:06:04 -04:00
close ( ) : void ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
2022-09-07 20:47:47 -04:00
* A dynamic library resource
*
* @category FFI
* /
2022-02-18 07:21:19 -05:00
export interface DynamicLibrary < S extends ForeignLibraryInterface > {
/** All of the registered library along with functions for calling them */
symbols : StaticForeignLibraryInterface < S > ;
2021-08-06 17:28:10 -04:00
close ( ) : void ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Opens a dynamic library and registers symbols
2022-08-16 23:12:24 -04:00
*
* @category FFI
2021-07-11 21:12:26 -04:00
* /
2022-02-18 07:21:19 -05:00
export function dlopen < S extends ForeignLibraryInterface > (
2021-08-24 09:09:00 -04:00
filename : string | URL ,
2021-08-06 17:28:10 -04:00
symbols : S ,
) : DynamicLibrary < S > ;
2021-07-11 21:12:26 -04:00
2022-09-28 09:03:56 -04:00
/ * * * * U N S T A B L E * * : n e e d s i n v e s t i g a t i o n i n t o h i g h p r e c i s i o n t i m e .
2020-04-30 11:23:40 -04:00
*
* 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 .
*
2020-05-16 15:23:48 -04:00
* ` ` ` ts
* Deno . utimeSync ( "myfile.txt" , 1556495550 , new Date ( ) ) ;
* ` ` `
2020-04-30 11:23:40 -04:00
*
2022-08-16 23:12:24 -04:00
* Requires ` allow-write ` permission .
2022-09-15 10:37:35 -04:00
* Needs investigation into high precision time .
2022-08-16 23:12:24 -04:00
*
2022-08-22 20:57:01 -04:00
* @tags allow - write
2022-08-16 23:12:24 -04:00
* @category File System
* /
2020-04-30 11:23:40 -04:00
export function utimeSync (
2021-05-31 14:05:57 -04:00
path : string | URL ,
2020-04-30 11:23:40 -04:00
atime : number | Date ,
2020-07-14 15:24:17 -04:00
mtime : number | Date ,
2020-04-30 11:23:40 -04:00
) : void ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2020-04-30 11:23:40 -04:00
*
* 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 .
*
2020-05-16 15:23:48 -04:00
* ` ` ` ts
* await Deno . utime ( "myfile.txt" , 1556495550 , new Date ( ) ) ;
* ` ` `
2020-04-30 11:23:40 -04:00
*
2022-08-16 23:12:24 -04:00
* Requires ` allow-write ` permission .
2022-09-15 10:37:35 -04:00
* Needs investigation into high precision time .
2022-08-16 23:12:24 -04:00
*
2022-08-22 20:57:01 -04:00
* @tags allow - write
2022-08-16 23:12:24 -04:00
* @category File System
* /
2020-04-30 11:23:40 -04:00
export function utime (
2021-05-31 14:05:57 -04:00
path : string | URL ,
2020-04-30 11:23:40 -04:00
atime : number | Date ,
2020-07-14 15:24:17 -04:00
mtime : number | Date ,
2020-04-30 11:23:40 -04:00
) : Promise < void > ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Sub Process
* /
2021-08-04 15:47:43 -04:00
export function run <
T extends RunOptions & {
clearEnv? : boolean ;
2021-09-13 13:26:23 -04:00
gid? : number ;
uid? : number ;
2021-08-04 15:47:43 -04:00
} = RunOptions & {
clearEnv? : boolean ;
2021-09-13 13:26:23 -04:00
gid? : number ;
uid? : number ;
2021-08-04 15:47:43 -04:00
} ,
> ( opt : T ) : Process < T > ;
2022-09-15 08:09:23 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 10:37:35 -04:00
*
2022-09-15 08:09:23 -04:00
* A custom HttpClient for use with ` fetch ` .
2020-08-10 16:41:51 -04:00
*
2020-08-05 14:44:03 -04:00
* ` ` ` ts
2021-09-30 03:26:15 -04:00
* const caCert = await Deno . readTextFile ( "./ca.pem" ) ;
* const client = Deno . createHttpClient ( { caCerts : [ caCert ] } ) ;
2020-08-05 14:44:03 -04:00
* const req = await fetch ( "https://myserver.com" , { client } ) ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category Fetch API
2020-08-05 14:44:03 -04:00
* /
export class HttpClient {
rid : number ;
close ( ) : void ;
}
2022-09-15 08:09:23 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 10:37:35 -04:00
*
2022-09-15 08:09:23 -04:00
* The options used when creating a [ HttpClient ] .
2022-08-16 23:12:24 -04:00
*
* @category Fetch API
2020-08-05 14:44:03 -04:00
* /
2021-04-09 20:41:59 -04:00
export interface CreateHttpClientOptions {
2021-09-30 03:26:15 -04:00
/ * * A l i s t o f r o o t c e r t i f i c a t e s t h a t w i l l b e u s e d i n a d d i t i o n t o t h e
* default root certificates to verify the peer ' s certificate .
*
* Must be in PEM format . * /
caCerts? : string [ ] ;
/** A HTTP proxy to use for new connections. */
2021-06-21 23:21:57 -04:00
proxy? : Proxy ;
2021-09-30 03:26:15 -04:00
/** PEM formatted client certificate chain. */
2021-08-25 08:25:12 -04:00
certChain? : string ;
2021-09-30 03:26:15 -04:00
/** PEM formatted (RSA or PKCS8) private key of client certificate. */
2021-08-25 08:25:12 -04:00
privateKey? : string ;
2021-06-21 23:21:57 -04:00
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Fetch API
* /
2021-06-21 23:21:57 -04:00
export interface Proxy {
url : string ;
basicAuth? : BasicAuth ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Fetch API
* /
2021-06-21 23:21:57 -04:00
export interface BasicAuth {
username : string ;
password : string ;
2020-08-05 14:44:03 -04:00
}
2022-09-15 08:09:23 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 10:37:35 -04:00
*
2022-09-15 08:09:23 -04:00
* Create a custom HttpClient for to use with ` fetch ` .
2020-08-10 16:41:51 -04:00
*
2020-08-05 14:44:03 -04:00
* ` ` ` ts
2021-09-30 03:26:15 -04:00
* const caCert = await Deno . readTextFile ( "./ca.pem" ) ;
* const client = Deno . createHttpClient ( { caCerts : [ caCert ] } ) ;
2021-06-21 23:21:57 -04:00
* 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 } ) ;
2020-08-05 14:44:03 -04:00
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category Fetch API
2020-08-05 14:44:03 -04:00
* /
export function createHttpClient (
options : CreateHttpClientOptions ,
) : HttpClient ;
2020-08-31 14:29:43 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2020-08-31 14:29:43 -04:00
*
* 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
2021-04-01 17:53:31 -04:00
* const file = Deno . openSync ( "file.txt" , { create : true , write : true } ) ;
2020-08-31 14:29:43 -04:00
* Deno . futimeSync ( file . rid , 1556495550 , new Date ( ) ) ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
2022-09-15 10:37:35 -04:00
* Needs investigation into high precision time .
*
2022-08-16 23:12:24 -04:00
* @category File System
2020-08-31 14:29:43 -04:00
* /
export function futimeSync (
rid : number ,
atime : number | Date ,
mtime : number | Date ,
) : void ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2020-08-31 14:29:43 -04:00
*
* 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
2021-04-01 17:53:31 -04:00
* const file = await Deno . open ( "file.txt" , { create : true , write : true } ) ;
2020-08-31 14:29:43 -04:00
* await Deno . futime ( file . rid , 1556495550 , new Date ( ) ) ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
2022-09-15 10:37:35 -04:00
* Needs investigation into high precision time .
*
2022-08-16 23:12:24 -04:00
* @category File System
2020-08-31 14:29:43 -04:00
* /
export function futime (
rid : number ,
atime : number | Date ,
mtime : number | Date ,
) : Promise < void > ;
2020-10-15 21:06:31 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* A generic transport listener for message - oriented protocols .
2022-08-16 23:12:24 -04:00
*
* @category Network
* /
2021-08-31 05:25:15 -04:00
export interface DatagramConn extends AsyncIterable < [ Uint8Array , Addr ] > {
2022-09-15 10:37:35 -04:00
/** Waits for and resolves to the next message to the `UDPConn`. */
2021-08-31 05:25:15 -04:00
receive ( p? : Uint8Array ) : Promise < [ Uint8Array , Addr ] > ;
2022-09-15 10:37:35 -04:00
/** Sends a message to the target. */
2021-08-31 05:25:15 -04:00
send ( p : Uint8Array , addr : Addr ) : Promise < number > ;
2022-09-15 10:37:35 -04:00
/ * * C l o s e c l o s e s t h e s o c k e t . A n y p e n d i n g m e s s a g e p r o m i s e s w i l l b e r e j e c t e d
2021-08-31 05:25:15 -04:00
* with errors . * /
close ( ) : void ;
/** Return the address of the `UDPConn`. */
readonly addr : Addr ;
[ Symbol . asyncIterator ] ( ) : AsyncIterableIterator < [ Uint8Array , Addr ] > ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Network
* /
2021-08-31 05:25:15 -04:00
export interface UnixListenOptions {
/** A Path to the Unix Socket. */
path : string ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
2021-08-31 05:25:15 -04:00
* Listen announces on the local transport address .
*
* ` ` ` ts
* const listener = Deno . listen ( { path : "/foo/bar.sock" , transport : "unix" } )
* ` ` `
*
2022-08-16 23:12:24 -04:00
* Requires ` allow-read ` and ` allow-write ` permission .
*
2022-08-22 20:57:01 -04:00
* @tags allow - read , allow - write
2022-08-16 23:12:24 -04:00
* @category Network
* /
2021-08-31 05:25:15 -04:00
export function listen (
options : UnixListenOptions & { transport : "unix" } ,
) : Listener ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Listen announces on the local transport address .
2021-08-31 05:25:15 -04:00
*
* ` ` ` ts
* const listener1 = Deno . listenDatagram ( {
* port : 80 ,
* transport : "udp"
* } ) ;
* const listener2 = Deno . listenDatagram ( {
* hostname : "golang.org" ,
* port : 80 ,
* transport : "udp"
* } ) ;
* ` ` `
*
2022-08-16 23:12:24 -04:00
* Requires ` allow-net ` permission .
*
2022-08-22 20:57:01 -04:00
* @tags allow - net
2022-08-16 23:12:24 -04:00
* @category Network
* /
2021-08-31 05:25:15 -04:00
export function listenDatagram (
options : ListenOptions & { transport : "udp" } ,
) : DatagramConn ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Listen announces on the local transport address .
2021-08-31 05:25:15 -04:00
*
* ` ` ` ts
* const listener = Deno . listenDatagram ( {
* path : "/foo/bar.sock" ,
* transport : "unixpacket"
* } ) ;
* ` ` `
*
2022-08-16 23:12:24 -04:00
* Requires ` allow-read ` and ` allow-write ` permission .
*
2022-08-22 20:57:01 -04:00
* @tags allow - read , allow - write
2022-08-16 23:12:24 -04:00
* @category Network
* /
2021-08-31 05:25:15 -04:00
export function listenDatagram (
options : UnixListenOptions & { transport : "unixpacket" } ,
) : DatagramConn ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Network
* /
2021-08-31 05:25:15 -04:00
export interface UnixConnectOptions {
transport : "unix" ;
path : string ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2021-08-31 05:25:15 -04:00
*
* 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" } ) ;
* ` ` `
*
2022-08-16 23:12:24 -04:00
* Requires ` allow-net ` permission for "tcp" and ` allow-read ` for "unix" .
*
2022-08-22 20:57:01 -04:00
* @tags allow - net , allow - read
2022-08-16 23:12:24 -04:00
* @category Network
* /
2021-08-31 05:25:15 -04:00
export function connect (
2022-02-27 09:18:30 -05:00
options : ConnectOptions ,
) : Promise < TcpConn > ;
export function connect (
options : UnixConnectOptions ,
2022-03-04 14:33:13 -05:00
) : Promise < UnixConn > ;
2021-08-31 05:25:15 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Network
* /
2021-09-30 03:26:15 -04:00
export interface ConnectTlsOptions {
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* PEM formatted client certificate chain .
* /
2021-09-30 03:26:15 -04:00
certChain? : string ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* PEM formatted ( RSA or PKCS8 ) private key of client certificate .
* /
2021-09-30 03:26:15 -04:00
privateKey? : string ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Application - Layer Protocol Negotiation ( ALPN ) protocols supported by
2021-11-26 13:59:53 -05:00
* the client . If not specified , no ALPN extension will be included in the
* TLS handshake .
* /
alpnProtocols? : string [ ] ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Network
* /
2021-11-26 13:59:53 -05:00
export interface TlsHandshakeInfo {
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Contains the ALPN protocol selected during negotiation with the server .
2021-11-26 13:59:53 -05:00
* If no ALPN protocol selected , returns ` null ` .
* /
alpnProtocol : string | null ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Network
* /
2021-11-26 13:59:53 -05:00
export interface TlsConn extends Conn {
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* Runs the client or server handshake protocol to completion if that has
2021-11-26 13:59:53 -05:00
* not happened yet . Calling this method is optional ; the TLS handshake
2022-09-15 10:37:35 -04:00
* will be completed automatically as soon as data is sent or received .
* /
2021-11-26 13:59:53 -05:00
handshake ( ) : Promise < TlsHandshakeInfo > ;
2021-08-31 05:25:15 -04:00
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Create a TLS connection with an attached client certificate .
2021-09-02 18:28:12 -04:00
*
* ` ` ` ts
* const conn = await Deno . connectTls ( {
* hostname : "deno.land" ,
* port : 443 ,
* certChain : "---- BEGIN CERTIFICATE ----\n ..." ,
* privateKey : "---- BEGIN PRIVATE KEY ----\n ..." ,
* } ) ;
* ` ` `
*
* Requires ` allow-net ` permission .
2022-08-16 23:12:24 -04:00
*
2022-08-22 20:57:01 -04:00
* @tags allow - net
2022-08-16 23:12:24 -04:00
* @category Network
2021-09-02 18:28:12 -04:00
* /
2021-10-26 16:27:47 -04:00
export function connectTls ( options : ConnectTlsOptions ) : Promise < TlsConn > ;
2021-08-31 05:25:15 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Network
* /
2021-08-31 05:25:15 -04:00
export interface ListenTlsOptions {
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Application - Layer Protocol Negotiation ( ALPN ) protocols to announce to
2021-08-31 05:25:15 -04:00
* the client . If not specified , no ALPN extension will be included in the
* TLS handshake .
* /
alpnProtocols? : string [ ] ;
}
2021-09-19 08:46:54 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Network
* /
2021-11-26 13:59:53 -05:00
export interface StartTlsOptions {
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Application - Layer Protocol Negotiation ( ALPN ) protocols to announce to
2021-11-26 13:59:53 -05:00
* the client . If not specified , no ALPN extension will be included in the
* TLS handshake .
* /
alpnProtocols? : string [ ] ;
}
2022-08-16 23:12:24 -04:00
/** @category Network */
2022-03-22 23:04:20 -04:00
export interface Listener extends AsyncIterable < Conn > {
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Make the listener block the event loop from finishing .
2022-03-22 23:04:20 -04:00
*
* Note : the listener blocks the event loop from finishing by default .
* This method is only meaningful after ` .unref() ` is called .
* /
ref ( ) : void ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Make the listener not block the event loop from finishing .
* /
2022-03-22 23:04:20 -04:00
unref ( ) : void ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Acquire an advisory file - system lock for the provided file . ` exclusive `
2021-09-19 08:46:54 -04:00
* defaults to ` false ` .
2022-08-16 23:12:24 -04:00
*
* @category File System
2021-09-19 08:46:54 -04:00
* /
export function flock ( rid : number , exclusive? : boolean ) : Promise < void > ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Acquire an advisory file - system lock for the provided file . ` exclusive `
2021-09-19 08:46:54 -04:00
* defaults to ` false ` .
2022-08-16 23:12:24 -04:00
*
* @category File System
2021-09-19 08:46:54 -04:00
* /
export function flockSync ( rid : number , exclusive? : boolean ) : void ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Release an advisory file - system lock for the provided file .
2022-08-16 23:12:24 -04:00
*
* @category File System
2021-09-19 08:46:54 -04:00
* /
export function funlock ( rid : number ) : Promise < void > ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Release an advisory file - system lock for the provided file .
2022-08-16 23:12:24 -04:00
*
* @category File System
2021-09-19 08:46:54 -04:00
* /
export function funlockSync ( rid : number ) : void ;
2021-12-09 03:00:55 -05:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
2022-08-23 18:08:56 -04:00
* 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 .
*
2022-08-18 08:05:02 -04:00
* @category HTTP Server
* /
2022-08-23 18:08:56 -04:00
export type ServeHandler = ( request : Request ) = > Response | Promise < Response > ;
2022-08-19 08:36:01 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
2022-08-23 18:08:56 -04:00
* @category HTTP Server
* /
export interface ServeOptions extends Partial < Deno.ListenOptions > {
2022-08-18 08:05:02 -04:00
/** An AbortSignal to close the server and all connections. */
signal? : AbortSignal ;
2022-09-28 13:46:29 -04:00
/** Sets SO_REUSEPORT on Linux. */
reusePort? : boolean ;
2022-08-18 08:05:02 -04:00
/** 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 ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
2022-08-18 08:05:02 -04:00
* @category HTTP Server
* /
2022-08-23 18:08:56 -04:00
export interface ServeTlsOptions extends ServeOptions {
2022-08-18 08:05:02 -04:00
/** Server private key in PEM format */
cert : string ;
/** Cert chain in PEM format */
key : string ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
2022-08-23 18:08:56 -04:00
* @category HTTP Server
* /
export interface ServeInit {
/** The handler to invoke to process each incoming request. */
handler : ServeHandler ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Serves HTTP requests with the given handler .
2022-08-18 08:05:02 -04:00
*
* 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
2022-08-23 18:08:56 -04:00
* Deno . serve ( ( _req ) = > new Response ( "Hello, world" ) ) ;
2022-08-18 08:05:02 -04:00
* ` ` `
*
2022-08-23 18:08:56 -04:00
* You can change the address to listen on using the ` hostname ` and ` port `
* options . The below example serves on port 3000 .
2022-08-18 08:05:02 -04:00
*
* ` ` ` ts
2022-08-23 18:08:56 -04:00
* Deno . serve ( { port : 3000 } , ( _req ) = > new Response ( "Hello, world" ) ) ;
2022-08-19 08:36:01 -04:00
* ` ` `
*
2022-08-23 18:08:56 -04:00
* 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 .
2022-08-19 08:36:01 -04:00
*
* ` ` ` ts
* const ac = new AbortController ( ) ;
*
2022-08-23 18:08:56 -04:00
* Deno . serve ( { signal : ac.signal } , ( _req ) = > new Response ( "Hello, world" ) )
* . then ( ( ) = > console . log ( "Server closed" ) ) ;
2022-08-19 08:36:01 -04:00
*
* console . log ( "Closing server..." ) ;
* ac . abort ( ) ;
2022-08-18 08:05:02 -04:00
* ` ` `
*
2022-08-23 18:08:56 -04:00
* 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 .
2022-08-18 08:05:02 -04:00
*
* ` ` ` ts
2022-08-19 08:36:01 -04:00
* Deno . serve ( {
2022-08-18 08:05:02 -04:00
* onListen ( { port , hostname } ) {
* console . log ( ` Server started at http:// ${ hostname } : ${ port } ` ) ;
* // ... more info specific to your server ..
* } ,
2022-08-23 18:08:56 -04:00
* handler : ( _req ) = > new Response ( "Hello, world" ) ,
2022-08-18 08:05:02 -04:00
* } ) ;
* ` ` `
*
2022-08-23 18:08:56 -04:00
* To enable TLS you must specify the ` key ` and ` cert ` options .
2022-08-18 08:05:02 -04:00
*
* ` ` ` ts
* const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n" ;
* const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n" ;
2022-08-23 18:08:56 -04:00
* Deno . serve ( { cert , key } , ( _req ) = > new Response ( "Hello, world" ) ) ;
2022-08-27 15:20:25 -04:00
* ` ` `
2022-08-18 08:05:02 -04:00
*
* @category HTTP Server
* /
2022-08-19 08:36:01 -04:00
export function serve (
2022-08-23 18:08:56 -04:00
handler : ServeHandler ,
options? : ServeOptions | ServeTlsOptions ,
) : Promise < void > ;
export function serve (
options : ServeOptions | ServeTlsOptions ,
handler : ServeHandler ,
) : Promise < void > ;
export function serve (
options : ServeInit & ( ServeOptions | ServeTlsOptions ) ,
2022-08-18 08:05:02 -04:00
) : Promise < void > ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Allows "hijacking" the connection that the request is associated with .
2022-08-24 08:10:57 -04:00
* This can be used to implement protocols that build on top of HTTP ( eg .
2022-03-16 09:54:18 -04:00
* 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 .
2022-08-16 23:12:24 -04:00
*
2022-08-24 08:10:57 -04:00
* ` ` ` 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 .
*
2022-08-16 23:12:24 -04:00
* @category HTTP Server
2022-03-16 09:54:18 -04:00
* /
export function upgradeHttp (
request : Request ,
2022-08-24 08:10:57 -04:00
) : Promise < [ Deno . Conn , Uint8Array ] > ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Allows "hijacking" the connection that the request is associated with .
2022-08-24 08:10:57 -04:00
* 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 ] ;
2022-04-20 18:20:33 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Sub Process
* /
2022-04-20 18:20:33 -04:00
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 ;
2022-05-11 01:59:39 -04:00
/ * *
* An AbortSignal that allows closing the process using the corresponding
* AbortController by sending the process a SIGTERM signal .
2022-09-14 02:37:05 -04:00
* Not supported in spawnSync .
2022-05-11 01:59:39 -04:00
* /
signal? : AbortSignal ;
2022-04-20 18:20:33 -04:00
/** Defaults to "null". */
stdin ? : "piped" | "inherit" | "null" ;
/** Defaults to "piped". */
stdout ? : "piped" | "inherit" | "null" ;
/** Defaults to "piped". */
stderr ? : "piped" | "inherit" | "null" ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
2022-04-20 18:20:33 -04:00
* Spawns a child process .
*
2022-07-18 09:16:12 -04:00
* 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 .
2022-04-20 18:20:33 -04:00
*
* ` ` ` 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 ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category Sub Process
2022-04-20 18:20:33 -04:00
* /
2022-07-18 09:16:12 -04:00
export function spawnChild (
2022-04-20 18:20:33 -04:00
command : string | URL ,
2022-07-18 09:16:12 -04:00
options? : SpawnOptions ,
) : Child ;
2022-04-20 18:20:33 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Sub Process
* /
2022-07-18 09:16:12 -04:00
export class Child {
get stdin ( ) : WritableStream < Uint8Array > ;
get stdout ( ) : ReadableStream < Uint8Array > ;
get stderr ( ) : ReadableStream < Uint8Array > ;
2022-04-20 18:20:33 -04:00
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. */
2022-07-18 09:16:12 -04:00
output ( ) : Promise < SpawnOutput > ;
2022-05-19 08:05:57 -04:00
/** Kills the process with given Signal. Defaults to SIGTERM. */
kill ( signo? : Signal ) : void ;
2022-07-18 16:24:35 -04:00
ref ( ) : void ;
unref ( ) : void ;
2022-04-20 18:20:33 -04:00
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
2022-04-20 18:20:33 -04:00
* Executes a subprocess , waiting for it to finish and
* collecting all of its output .
2022-04-24 11:21:22 -04:00
* Will throw an error if ` stdin: "piped" ` is passed .
2022-04-20 18:20:33 -04:00
*
2022-07-18 09:16:12 -04:00
* If options ` stdout ` or ` stderr ` are not set to ` "piped" ` , accessing the
* corresponding field on ` SpawnOutput ` will throw a ` TypeError ` .
*
2022-04-20 18:20:33 -04:00
* ` ` ` ts
2022-07-18 09:16:12 -04:00
* const { code , stdout , stderr } = await Deno . spawn ( Deno . execPath ( ) , {
2022-04-20 18:20:33 -04:00
* args : [
* "eval" ,
* "console.log('hello'); console.error('world')" ,
* ] ,
* } ) ;
2022-07-18 09:16:12 -04:00
* console . assert ( code === 0 ) ;
2022-04-20 18:20:33 -04:00
* console . assert ( "hello\n" === new TextDecoder ( ) . decode ( stdout ) ) ;
* console . assert ( "world\n" === new TextDecoder ( ) . decode ( stderr ) ) ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category Sub Process
2022-04-20 18:20:33 -04:00
* /
2022-07-18 09:16:12 -04:00
export function spawn (
2022-04-20 18:20:33 -04:00
command : string | URL ,
2022-07-18 09:16:12 -04:00
options? : SpawnOptions ,
) : Promise < SpawnOutput > ;
2022-04-20 18:20:33 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
2022-04-20 18:20:33 -04:00
* Synchronously executes a subprocess , waiting for it to finish and
* collecting all of its output .
2022-04-24 11:21:22 -04:00
* Will throw an error if ` stdin: "piped" ` is passed .
2022-04-20 18:20:33 -04:00
*
2022-07-18 09:16:12 -04:00
* If options ` stdout ` or ` stderr ` are not set to ` "piped" ` , accessing the
* corresponding field on ` SpawnOutput ` will throw a ` TypeError ` .
*
2022-04-21 08:36:57 -04:00
* ` ` ` ts
2022-07-18 09:16:12 -04:00
* const { code , stdout , stderr } = Deno . spawnSync ( Deno . execPath ( ) , {
2022-04-20 18:20:33 -04:00
* args : [
* "eval" ,
* "console.log('hello'); console.error('world')" ,
* ] ,
* } ) ;
2022-07-18 09:16:12 -04:00
* console . assert ( code === 0 ) ;
2022-04-20 18:20:33 -04:00
* console . assert ( "hello\n" === new TextDecoder ( ) . decode ( stdout ) ) ;
* console . assert ( "world\n" === new TextDecoder ( ) . decode ( stderr ) ) ;
* ` ` `
2022-08-16 23:12:24 -04:00
*
* @category Sub Process
2022-04-20 18:20:33 -04:00
* /
2022-07-18 09:16:12 -04:00
export function spawnSync (
2022-04-20 18:20:33 -04:00
command : string | URL ,
2022-07-18 09:16:12 -04:00
options? : SpawnOptions ,
) : SpawnOutput ;
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Sub Process
* /
2022-07-18 09:16:12 -04:00
export interface ChildStatus {
success : boolean ;
code : number ;
signal : Signal | null ;
}
2022-04-20 18:20:33 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Sub Process
* /
2022-07-18 09:16:12 -04:00
export interface SpawnOutput extends ChildStatus {
get stdout ( ) : Uint8Array ;
get stderr ( ) : Uint8Array ;
2022-04-20 18:20:33 -04:00
}
2020-04-30 11:23:40 -04:00
}
2020-08-05 14:44:03 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
2022-08-22 20:57:01 -04:00
* @tags allow - net , allow - read
* @category Fetch API
* /
2020-08-05 14:44:03 -04:00
declare function fetch (
input : Request | URL | string ,
init? : RequestInit & { client : Deno.HttpClient } ,
) : Promise < Response > ;
2021-01-29 08:15:59 -05:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Web Workers
* /
2021-01-29 08:15:59 -05:00
declare interface WorkerOptions {
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
2022-09-15 08:09:23 -04:00
*
* Configure permissions options to change the level of access the worker will
2022-03-24 11:27:24 -04:00
* have . By default it will have no permissions . Note that the permissions
2021-01-29 08:15:59 -05:00
* 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
2022-03-24 11:27:24 -04:00
* - "none" will use the default behavior and have no permission
2021-01-29 08:15:59 -05:00
* - 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 ,
* } ,
* } ,
* }
* ) ;
* ` ` `
* /
2022-05-17 16:27:17 -04:00
deno ? : {
2021-01-29 08:15:59 -05:00
/** Set to `"none"` to disable all the permissions in the worker. */
2022-03-10 19:35:33 -05:00
permissions? : Deno.PermissionOptions ;
2021-01-29 08:15:59 -05:00
} ;
}
2021-08-09 18:28:17 -04:00
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Web Sockets
* /
2021-08-09 18:28:17 -04:00
declare interface WebSocketStreamOptions {
protocols? : string [ ] ;
signal? : AbortSignal ;
2022-01-05 11:41:44 -05:00
headers? : HeadersInit ;
2021-08-09 18:28:17 -04:00
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Web Sockets
* /
2021-08-09 18:28:17 -04:00
declare interface WebSocketConnection {
readable : ReadableStream < string | Uint8Array > ;
writable : WritableStream < string | Uint8Array > ;
extensions : string ;
protocol : string ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
* @category Web Sockets
* /
2021-08-09 18:28:17 -04:00
declare interface WebSocketCloseInfo {
code? : number ;
reason? : string ;
}
2022-09-15 10:37:35 -04:00
/ * * * * U N S T A B L E * * : N e w A P I , y e t t o b e v e t t e d .
*
2022-08-22 20:57:01 -04:00
* @tags allow - net
* @category Web Sockets
* /
2021-08-09 18:28:17 -04:00
declare class WebSocketStream {
constructor ( url : string , options? : WebSocketStreamOptions ) ;
url : string ;
connection : Promise < WebSocketConnection > ;
closed : Promise < WebSocketCloseInfo > ;
close ( closeInfo? : WebSocketCloseInfo ) : void ;
}