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-03-11 17:07:02 -05:00
export interface BenchDefinition {
fn : ( ) = > void | Promise < void > ;
name : string ;
ignore? : boolean ;
/** Specify number of iterations benchmark should perform. Defaults to 1000. */
n? : number ;
/ * * S p e c i f y n u m b e r o f w a r m u p i t e r a t i o n s b e n c h m a r k s h o u l d p e r f o r m . D e f a u l t s
* to 1000 .
*
* These iterations are not measured . It allows the code to be optimized
* by JIT compiler before measuring its performance . * /
warmup? : number ;
/ * * 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 ;
}
/ * * R e g i s t e r a b e n c h w h i c h w i l l b e r u n w h e n ` d e n o b e n c h ` i s u s e d o n t h e c o m m a n d
* 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" ) ;
* }
* } ) ;
* ` ` `
* /
export function bench ( t : BenchDefinition ) : void ;
/ * * R e g i s t e r a b e n c h w h i c h w i l l b e r u n w h e n ` d e n o b e n c h ` i s u s e d o n t h e c o m m a n d
* 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" ) ;
* } ) ;
* ` ` `
* /
export function bench (
name : string ,
fn : ( ) = > void | Promise < void > ,
) : void ;
/ * * R e g i s t e r a b e n c h w h i c h w i l l b e r u n w h e n ` d e n o b e n c h ` i s u s e d o n t h e c o m m a n d
* 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" ) ;
* } ) ;
* ` ` `
* /
export function bench ( fn : ( ) = > void | Promise < void > ) : void ;
/ * * R e g i s t e r a b e n c h w h i c h w i l l b e r u n w h e n ` d e n o b e n c h ` i s u s e d o n t h e c o m m a n d
* 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" ) ;
* } ) ;
* ` ` `
* /
export function bench (
name : string ,
options : Omit < BenchDefinition , " fn " | " name " > ,
fn : ( ) = > void | Promise < void > ,
) : void ;
/ * * R e g i s t e r a b e n c h w h i c h w i l l b e r u n w h e n ` d e n o b e n c h ` i s u s e d o n t h e c o m m a n d
* 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" ) ;
* } ) ;
* ` ` `
* /
export function bench (
options : Omit < BenchDefinition , " fn " > ,
fn : ( ) = > void | Promise < void > ,
) : void ;
/ * * R e g i s t e r a b e n c h w h i c h w i l l b e r u n w h e n ` d e n o b e n c h ` i s u s e d o n t h e c o m m a n d
* 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" ) ;
* } ) ;
* ` ` `
* /
export function bench (
options : Omit < BenchDefinition , " fn " | " name " > ,
fn : ( ) = > void | Promise < void > ,
) : void ;
2020-04-30 11:23:40 -04:00
/ * *
* * * UNSTABLE * * : New API , yet to be vetted . This API is under consideration to
* determine if permissions are required to call it .
*
* 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
*
* NOTE : This API is not implemented on Windows
* /
export function umask ( mask? : number ) : number ;
2020-07-10 10:07:12 -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 .
*
* ` ` ` 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
* ` ` `
* /
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 ;
} ;
2020-06-03 13:46:09 -04:00
/ * * * * U n s t a b l e * * T h e r e a r e q u e s t i o n s a r o u n d w h i c h p e r m i s s i o n t h i s n e e d s . A n d
* maybe should be renamed ( loadAverage ? )
*
* 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
*
* Requires ` allow-env ` permission .
* /
export function loadavg ( ) : number [ ] ;
2020-06-03 13:46:09 -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 . U n d e r c o n s i d e r a t i o n t o p o s s i b l y m o v e t o
* Deno . build or Deno . versions and if it should depend sys - info , which may not
* be desireable .
*
* 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
*
* Requires ` allow-env ` permission .
* /
export function osRelease ( ) : string ;
2020-09-19 17:30:59 -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-09-10 04:38:17 -04:00
*
* 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 .
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 ( ) ) ;
* ` ` `
*
* Requires ` allow-env ` permission .
* /
export function systemMemoryInfo ( ) : SystemMemoryInfo ;
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 ;
/** Memory used by the page cache and slabs */
cached : number ;
/** Total swap memory */
swapTotal : number ;
/** Unused swap memory */
swapFree : number ;
}
2022-01-24 04:39:28 -05:00
/** The information of the network interface */
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 ;
}
/ * * * * 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 .
*
* Returns an array of the network interface informations .
*
* ` ` ` ts
* console . log ( Deno . networkInterfaces ( ) ) ;
* ` ` `
*
* Requires ` allow-env ` permission .
* /
export function networkInterfaces ( ) : NetworkInterfaceInfo [ ] ;
2022-01-31 00:44:19 -05: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 .
*
* Returns the user id of the process on POSIX platforms . Returns null on windows .
*
* ` ` ` ts
* console . log ( Deno . getUid ( ) ) ;
* ` ` `
*
* Requires ` allow-env ` permission .
* /
export function getUid ( ) : number | null ;
2022-01-24 04:39:28 -05:00
2021-08-06 17:28:10 -04:00
/** All possible types for interfacing with foreign functions */
export type NativeType =
| "void"
| "u8"
| "i8"
| "u16"
| "i16"
| "u32"
| "i32"
| "u64"
| "i64"
| "usize"
| "isize"
| "f32"
2021-12-15 09:41:49 -05:00
| "f64"
| "pointer" ;
2021-08-06 17:28:10 -04:00
/** A foreign function as defined by its parameter and result types */
2022-01-10 10:33:25 -05:00
export interface ForeignFunction <
Parameters extends readonly NativeType [ ] = readonly NativeType [ ] ,
Result extends NativeType = NativeType ,
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 ;
2021-08-06 17:28:10 -04:00
}
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 ;
type : Exclude < Type , " void " > ;
}
/** A foreign library interface descriptor */
export interface ForeignLibraryInterface {
[ name : string ] : ForeignFunction | ForeignStatic ;
2022-01-10 10:33:25 -05:00
}
/** All possible number types interfacing with foreign functions */
type StaticNativeNumberType = Exclude < NativeType , " void " | " pointer " > ;
/** Infers a foreign function return type */
type StaticForeignFunctionResult < T extends NativeType > = T extends "void"
? void
: T extends StaticNativeNumberType ? number
: T extends "pointer" ? UnsafePointer
: never ;
type StaticForeignFunctionParameter < T > = T extends "void" ? void
: T extends StaticNativeNumberType ? number
2022-01-11 04:31:52 -05:00
: T extends "pointer" ? Deno . UnsafePointer | Deno . TypedArray | null
2022-01-10 10:33:25 -05:00
: unknown ;
/** Infers a foreign function parameter list. */
type StaticForeignFunctionParameters < T extends readonly NativeType [ ] > = [
. . . {
[ K in keyof T ] : StaticForeignFunctionParameter < T [ K ] > ;
} ,
] ;
2022-02-18 07:21:19 -05:00
/** Infers a foreign symbol */
type StaticForeignSymbol < T extends ForeignFunction | ForeignStatic > =
T extends ForeignFunction ? (
. . . args : StaticForeignFunctionParameters < T [ " parameters " ] >
) = > ConditionalAsync <
T [ "nonblocking" ] ,
StaticForeignFunctionResult < T [ " result " ] >
>
: T extends ForeignStatic ? StaticForeignFunctionResult < T [ " type " ] >
: never ;
2022-01-10 10:33:25 -05:00
type ConditionalAsync < IsAsync extends boolean | undefined , T > =
IsAsync extends true ? Promise < T > : T ;
2022-02-18 07:21:19 -05:00
/** Infers a foreign library interface */
type StaticForeignLibraryInterface < T extends ForeignLibraryInterface > = {
[ K in keyof T ] : StaticForeignSymbol < T [ K ] > ;
2022-01-10 10:33:25 -05:00
} ;
2021-12-15 09:41:49 -05:00
type TypedArray =
| Int8Array
| Uint8Array
| Int16Array
| Uint16Array
| Int32Array
| Uint32Array
| Uint8ClampedArray
| Float32Array
| Float64Array
| BigInt64Array
| BigUint64Array ;
/ * * * * U N S T A B L E * * : U n s a f e a n d n e w A P I , b e w a r e !
*
* An unsafe pointer to a memory location for passing and returning pointers to and from the ffi
* /
export class UnsafePointer {
constructor ( value : bigint ) ;
value : bigint ;
/ * *
* Return the direct memory pointer to the typed array in memory
* /
static of ( typedArray : TypedArray ) : UnsafePointer ;
/ * *
* Returns the value of the pointer which is useful in certain scenarios .
* /
valueOf ( ) : bigint ;
}
/ * * * * U N S T A B L E * * : U n s a f e a n d n e w A P I , b e w a r e !
*
* 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 ) .
* /
export class UnsafePointerView {
constructor ( pointer : UnsafePointer ) ;
pointer : UnsafePointer ;
/** 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 ) : bigint ;
/** Gets a signed 64-bit integer at the specified byte offset from the pointer. */
getBigInt64 ( offset? : number ) : bigint ;
/** 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 an ArrayBuffer of length `byteLength` at the specified byte offset from the pointer. */
getArrayBuffer ( 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 offset from the pointer. */
copyInto ( destination : TypedArray , offset? : number ) : void ;
}
2022-01-12 06:38:26 -05:00
/ * *
* * * UNSTABLE * * : Unsafe and new API , beware !
*
* An unsafe pointer to a function , for calling functions that are not
* present as symbols .
* /
export class UnsafeFnPointer < Fn extends ForeignFunction > {
pointer : UnsafePointer ;
definition : Fn ;
constructor ( pointer : UnsafePointer , definition : Fn ) ;
call (
. . . args : StaticForeignFunctionParameters < Fn [ " parameters " ] >
) : ConditionalAsync <
Fn [ "nonblocking" ] ,
StaticForeignFunctionResult < Fn [ " result " ] >
> ;
}
2021-08-06 17:28:10 -04:00
/** A dynamic library resource */
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 ;
}
2021-12-15 09:41:49 -05:00
/ * * * * U N S T A B L E * * : U n s a f e a n d n e w A P I , b e w a r e !
2021-07-11 21:12:26 -04:00
*
2021-08-06 17:28:10 -04:00
* Opens a dynamic library and registers symbols
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
2020-04-30 11:23:40 -04:00
/** The log category for a diagnostic message. */
export enum DiagnosticCategory {
2020-09-12 05:53:57 -04:00
Warning = 0 ,
Error = 1 ,
Suggestion = 2 ,
Message = 3 ,
2020-04-30 11:23:40 -04:00
}
export interface DiagnosticMessageChain {
2021-08-24 11:53:38 -04:00
messageText : string ;
2020-04-30 11:23:40 -04:00
category : DiagnosticCategory ;
code : number ;
next? : DiagnosticMessageChain [ ] ;
}
2020-09-12 05:53:57 -04:00
export interface Diagnostic {
2020-04-30 11:23:40 -04:00
/** A string message summarizing the diagnostic. */
2020-09-12 05:53:57 -04:00
messageText? : string ;
2020-04-30 11:23:40 -04:00
/** An ordered array of further diagnostics. */
messageChain? : DiagnosticMessageChain ;
/ * * I n f o r m a t i o n r e l a t e d t o t h e d i a g n o s t i c . T h i s i s p r e s e n t w h e n t h e r e i s a
* suggestion or other additional diagnostic information * /
2020-09-12 05:53:57 -04:00
relatedInformation? : Diagnostic [ ] ;
2020-04-30 11:23:40 -04:00
/** The text of the source line related to the diagnostic. */
sourceLine? : string ;
2020-09-12 05:53:57 -04:00
source? : string ;
/** The start position of the error. Zero based index. */
start ? : {
line : number ;
character : number ;
} ;
/** The end position of the error. Zero based index. */
end ? : {
line : number ;
character : number ;
} ;
/** The filename of the resource related to the diagnostic message. */
fileName? : string ;
2020-04-30 11:23:40 -04:00
/** The category of the diagnostic. */
category : DiagnosticCategory ;
/** A number identifier. */
code : number ;
}
/ * * * * 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 .
*
* Format an array of diagnostic items and return them as a single string in a
2021-06-11 19:42:43 -04:00
* user friendly format . If there are no diagnostics then it will return an
* empty string .
2020-04-30 11:23:40 -04:00
*
2020-05-16 15:23:48 -04:00
* ` ` ` ts
2021-02-21 10:17:27 -05:00
* const { diagnostics } = await Deno . emit ( "file_with_compile_issues.ts" ) ;
2020-05-16 15:23:48 -04:00
* console . table ( diagnostics ) ; // Prints raw diagnostic data
* console . log ( Deno . formatDiagnostics ( diagnostics ) ) ; // User friendly output of diagnostics
2021-06-11 19:42:43 -04:00
* console . log ( Deno . formatDiagnostics ( [ ] ) ) ; // An empty string
2020-05-16 15:23:48 -04:00
* ` ` `
2020-04-30 11:23:40 -04:00
*
2020-09-12 05:53:57 -04:00
* @param diagnostics An array of diagnostic items to format
2020-04-30 11:23:40 -04:00
* /
2020-09-12 05:53:57 -04:00
export function formatDiagnostics ( diagnostics : Diagnostic [ ] ) : string ;
2020-04-30 11:23:40 -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 specific subset TypeScript compiler options that can be supported by the
* Deno TypeScript compiler . * /
export interface CompilerOptions {
/** Allow JavaScript files to be compiled. Defaults to `true`. */
allowJs? : boolean ;
/ * * A l l o w d e f a u l t i m p o r t s f r o m m o d u l e s w i t h n o d e f a u l t e x p o r t . T h i s d o e s n o t
* affect code emit , just typechecking . Defaults to ` false ` . * /
allowSyntheticDefaultImports? : boolean ;
/** Allow accessing UMD globals from modules. Defaults to `false`. */
allowUmdGlobalAccess? : boolean ;
/** Do not report errors on unreachable code. Defaults to `false`. */
allowUnreachableCode? : boolean ;
/** Do not report errors on unused labels. Defaults to `false` */
allowUnusedLabels? : boolean ;
/ * * P a r s e i n s t r i c t m o d e a n d e m i t ` " u s e s t r i c t " ` f o r e a c h s o u r c e f i l e .
* Defaults to ` true ` . * /
alwaysStrict? : boolean ;
/ * * B a s e d i r e c t o r y t o r e s o l v e n o n - r e l a t i v e m o d u l e n a m e s . D e f a u l t s t o
* ` undefined ` . * /
baseUrl? : string ;
2020-12-31 16:43:54 -05:00
/** The character set of the input files. Defaults to `"utf8"`. */
charset? : string ;
2020-04-30 11:23:40 -04:00
/ * * R e p o r t e r r o r s i n ` . j s ` f i l e s . U s e i n c o n j u n c t i o n w i t h ` a l l o w J s ` . D e f a u l t s
* to ` false ` . * /
checkJs? : boolean ;
/** Generates corresponding `.d.ts` file. Defaults to `false`. */
declaration? : boolean ;
/** Output directory for generated declaration files. */
declarationDir? : string ;
/ * * G e n e r a t e s a s o u r c e m a p f o r e a c h c o r r e s p o n d i n g ` . d . t s ` f i l e . D e f a u l t s t o
* ` false ` . * /
declarationMap? : boolean ;
/ * * P r o v i d e f u l l s u p p o r t f o r i t e r a b l e s i n ` f o r . . o f ` , s p r e a d a n d
* destructuring when targeting ES5 or ES3 . Defaults to ` false ` . * /
downlevelIteration? : boolean ;
/** Only emit `.d.ts` declaration files. Defaults to `false`. */
emitDeclarationOnly? : boolean ;
/ * * E m i t d e s i g n - t y p e m e t a d a t a f o r d e c o r a t e d d e c l a r a t i o n s i n s o u r c e . S e e i s s u e
* [ microsoft / TypeScript # 2577 ] ( https : //github.com/Microsoft/TypeScript/issues/2577)
* for details . Defaults to ` false ` . * /
emitDecoratorMetadata? : boolean ;
/ * * E m i t ` _ _ i m p o r t S t a r ` a n d ` _ _ i m p o r t D e f a u l t ` h e l p e r s f o r r u n t i m e b a b e l
* ecosystem compatibility and enable ` allowSyntheticDefaultImports ` for type
* system compatibility . Defaults to ` true ` . * /
esModuleInterop? : boolean ;
2020-11-01 21:51:56 -05:00
/** Enables experimental support for ES decorators. Defaults to `true`. */
2020-04-30 11:23:40 -04:00
experimentalDecorators? : boolean ;
2020-11-01 21:51:56 -05:00
/ * * I m p o r t e m i t h e l p e r s ( e . g . ` _ _ e x t e n d s ` , ` _ _ r e s t ` , e t c . . ) f r o m
* [ tslib ] ( https : //www.npmjs.com/package/tslib). */
importHelpers? : boolean ;
2020-11-09 14:50:33 -05:00
/ * * T h i s f l a g c o n t r o l s h o w ` i m p o r t ` w o r k s , t h e r e a r e 3 d i f f e r e n t o p t i o n s :
2020-12-28 18:05:29 -05:00
*
2020-11-09 14:50:33 -05:00
* - ` remove ` : The default behavior of dropping import statements which only
* reference types .
* - ` preserve ` : Preserves all ` import ` statements whose values or types are
* never used . This can cause imports / side - effects to be preserved .
* - ` error ` : This preserves all imports ( the same as the preserve option ) ,
* but will error when a value import is only used as a type . This might
* be useful if you want to ensure no values are being accidentally
* imported , but still make side - effect imports explicit .
2020-12-28 18:05:29 -05:00
*
2020-11-09 14:50:33 -05:00
* This flag works because you can use ` import type ` to explicitly create an
* ` import ` statement which should never be emitted into JavaScript . * /
importsNotUsedAsValues ? : "remove" | "preserve" | "error" ;
2020-04-30 11:23:40 -04:00
/ * * E m i t a s i n g l e f i l e w i t h s o u r c e m a p s i n s t e a d o f h a v i n g a s e p a r a t e f i l e .
* Defaults to ` false ` . * /
inlineSourceMap? : boolean ;
/ * * E m i t t h e s o u r c e a l o n g s i d e t h e s o u r c e m a p s w i t h i n a s i n g l e f i l e ; r e q u i r e s
* ` inlineSourceMap ` or ` sourceMap ` to be set . Defaults to ` false ` . * /
inlineSources? : boolean ;
2021-11-08 20:26:39 -05:00
/ * * S u p p o r t J S X i n ` . t s x ` f i l e s : ` " r e a c t " ` , ` " p r e s e r v e " ` , ` " r e a c t - n a t i v e " ` ,
* ` "react-jsx", ` "react-jsxdev" ` .
2020-04-30 11:23:40 -04:00
* Defaults to ` "react" ` . * /
2021-11-08 20:26:39 -05:00
jsx ? : "react" | "preserve" | "react-native" | "react-jsx" | "react-jsx-dev" ;
2020-04-30 11:23:40 -04:00
/ * * S p e c i f y t h e J S X f a c t o r y f u n c t i o n t o u s e w h e n t a r g e t i n g r e a c t J S X e m i t ,
* e . g . ` React.createElement ` or ` h ` . Defaults to ` React.createElement ` . * /
jsxFactory? : string ;
2020-11-01 21:51:56 -05:00
/ * * S p e c i f y t h e J S X f r a g m e n t f a c t o r y f u n c t i o n t o u s e w h e n t a r g e t i n g r e a c t
* JSX emit , e . g . ` Fragment ` . Defaults to ` React.Fragment ` . * /
jsxFragmentFactory? : string ;
2021-11-08 20:26:39 -05:00
/ * * D e c l a r e s t h e m o d u l e s p e c i f i e r t o b e u s e d f o r i m p o r t i n g t h e ` j s x ` a n d
* ` jsxs ` factory functions when using jsx as ` "react-jsx" ` or
* ` "react-jsxdev" ` . Defaults to ` "react" ` . * /
jsxImportSource? : string ;
2020-04-30 11:23:40 -04:00
/ * * R e s o l v e k e y o f t o s t r i n g v a l u e d p r o p e r t y n a m e s o n l y ( n o n u m b e r s o r
* symbols ) . Defaults to ` false ` . * /
keyofStringsOnly? : string ;
/ * * L i s t o f l i b r a r y f i l e s t o b e i n c l u d e d i n t h e c o m p i l a t i o n . I f o m i t t e d ,
* then the Deno main runtime libs are used . * /
lib? : string [ ] ;
/** The locale to use to show error messages. */
locale? : string ;
/ * * S p e c i f i e s t h e l o c a t i o n w h e r e d e b u g g e r s h o u l d l o c a t e m a p f i l e s i n s t e a d o f
* generated locations . Use this flag if the ` .map ` files will be located at
* run - time in a different location than the ` .js ` files . The location
* specified will be embedded in the source map to direct the debugger where
* the map files will be located . Defaults to ` undefined ` . * /
mapRoot? : string ;
/ * * S p e c i f y t h e m o d u l e f o r m a t f o r t h e e m i t t e d c o d e . D e f a u l t s t o
* ` "esnext" ` . * /
module ? :
| "none"
| "commonjs"
| "amd"
| "system"
| "umd"
| "es6"
| "es2015"
2021-06-21 07:47:09 -04:00
| "es2020"
2020-04-30 11:23:40 -04:00
| "esnext" ;
/ * * D o n o t g e n e r a t e c u s t o m h e l p e r f u n c t i o n s l i k e ` _ _ e x t e n d s ` i n c o m p i l e d
* output . Defaults to ` false ` . * /
noEmitHelpers? : boolean ;
/ * * R e p o r t e r r o r s f o r f a l l t h r o u g h c a s e s i n s w i t c h s t a t e m e n t . D e f a u l t s t o
* ` false ` . * /
noFallthroughCasesInSwitch? : boolean ;
/ * * R a i s e e r r o r o n e x p r e s s i o n s a n d d e c l a r a t i o n s w i t h a n i m p l i e d a n y t y p e .
* Defaults to ` true ` . * /
noImplicitAny? : boolean ;
/ * * R e p o r t a n e r r o r w h e n n o t a l l c o d e p a t h s i n f u n c t i o n r e t u r n a v a l u e .
* Defaults to ` false ` . * /
noImplicitReturns? : boolean ;
/ * * R a i s e e r r o r o n ` t h i s ` e x p r e s s i o n s w i t h a n i m p l i e d ` a n y ` t y p e . D e f a u l t s t o
* ` true ` . * /
noImplicitThis? : boolean ;
/ * * D o n o t e m i t ` " u s e s t r i c t " ` d i r e c t i v e s i n m o d u l e o u t p u t . D e f a u l t s t o
* ` false ` . * /
noImplicitUseStrict? : boolean ;
2020-12-31 16:43:54 -05:00
/ * * D o n o t i n c l u d e t h e d e f a u l t l i b r a r y f i l e ( ` l i b . d . t s ` ) . D e f a u l t s t o
* ` false ` . * /
noLib? : boolean ;
2020-04-30 11:23:40 -04:00
/ * * D o n o t a d d t r i p l e - s l a s h r e f e r e n c e s o r m o d u l e i m p o r t t a r g e t s t o t h e l i s t o f
* compiled files . Defaults to ` false ` . * /
noResolve? : boolean ;
/ * * D i s a b l e s t r i c t c h e c k i n g o f g e n e r i c s i g n a t u r e s i n f u n c t i o n t y p e s . D e f a u l t s
* to ` false ` . * /
noStrictGenericChecks? : boolean ;
2020-12-31 16:43:54 -05:00
/** Include 'undefined' in index signature results. Defaults to `false`. */
noUncheckedIndexedAccess? : boolean ;
2020-04-30 11:23:40 -04:00
/** Report errors on unused locals. Defaults to `false`. */
noUnusedLocals? : boolean ;
/** Report errors on unused parameters. Defaults to `false`. */
noUnusedParameters? : boolean ;
/ * * L i s t o f p a t h m a p p i n g e n t r i e s f o r m o d u l e n a m e s t o l o c a t i o n s r e l a t i v e t o t h e
* ` baseUrl ` . Defaults to ` undefined ` . * /
paths? : Record < string , string [ ] > ;
/ * * D o n o t e r a s e c o n s t e n u m d e c l a r a t i o n s i n g e n e r a t e d c o d e . D e f a u l t s t o
* ` false ` . * /
preserveConstEnums? : boolean ;
/ * * R e m o v e a l l c o m m e n t s e x c e p t c o p y - r i g h t h e a d e r c o m m e n t s b e g i n n i n g w i t h
* ` /*! ` . Defaults to ` true ` . * /
removeComments? : boolean ;
/ * * S p e c i f i e s t h e r o o t d i r e c t o r y o f i n p u t f i l e s . O n l y u s e t o c o n t r o l t h e
* output directory structure with ` outDir ` . Defaults to ` undefined ` . * /
rootDir? : string ;
/ * * L i s t o f _ r o o t _ f o l d e r s w h o s e c o m b i n e d c o n t e n t r e p r e s e n t t h e s t r u c t u r e o f
* the project at runtime . Defaults to ` undefined ` . * /
rootDirs? : string [ ] ;
/** Generates corresponding `.map` file. Defaults to `false`. */
sourceMap? : boolean ;
/ * * S p e c i f i e s t h e l o c a t i o n w h e r e d e b u g g e r s h o u l d l o c a t e T y p e S c r i p t f i l e s
* instead of source locations . Use this flag if the sources will be located
* at run - time in a different location than that at design - time . The location
* specified will be embedded in the sourceMap to direct the debugger where
* the source files will be located . Defaults to ` undefined ` . * /
sourceRoot? : string ;
2020-11-01 21:51:56 -05:00
/** Skip type checking of all declaration files (`*.d.ts`). */
skipLibCheck? : boolean ;
2020-04-30 11:23:40 -04:00
/ * * E n a b l e a l l s t r i c t t y p e c h e c k i n g o p t i o n s . E n a b l i n g ` s t r i c t ` e n a b l e s
* ` noImplicitAny ` , ` noImplicitThis ` , ` alwaysStrict ` , ` strictBindCallApply ` ,
* ` strictNullChecks ` , ` strictFunctionTypes ` and
* ` strictPropertyInitialization ` . Defaults to ` true ` . * /
strict? : boolean ;
/ * * E n a b l e s t r i c t e r c h e c k i n g o f t h e ` b i n d ` , ` c a l l ` , a n d ` a p p l y ` m e t h o d s o n
* functions . Defaults to ` true ` . * /
strictBindCallApply? : boolean ;
/ * * D i s a b l e b i v a r i a n t p a r a m e t e r c h e c k i n g f o r f u n c t i o n t y p e s . D e f a u l t s t o
* ` true ` . * /
strictFunctionTypes? : boolean ;
/ * * E n s u r e n o n - u n d e f i n e d c l a s s p r o p e r t i e s a r e i n i t i a l i z e d i n t h e c o n s t r u c t o r .
* This option requires ` strictNullChecks ` be enabled in order to take effect .
* Defaults to ` true ` . * /
strictPropertyInitialization? : boolean ;
/ * * I n s t r i c t n u l l c h e c k i n g m o d e , t h e ` n u l l ` a n d ` u n d e f i n e d ` v a l u e s a r e n o t i n
* the domain of every type and are only assignable to themselves and ` any `
* ( the one exception being that ` undefined ` is also assignable to ` void ` ) . * /
strictNullChecks? : boolean ;
/ * * S u p p r e s s e x c e s s p r o p e r t y c h e c k s f o r o b j e c t l i t e r a l s . D e f a u l t s t o
* ` false ` . * /
suppressExcessPropertyErrors? : boolean ;
/ * * S u p p r e s s ` n o I m p l i c i t A n y ` e r r o r s f o r i n d e x i n g o b j e c t s l a c k i n g i n d e x
* signatures . * /
suppressImplicitAnyIndexErrors? : boolean ;
/** Specify ECMAScript target version. Defaults to `esnext`. */
target ? :
| "es3"
| "es5"
| "es6"
| "es2015"
| "es2016"
| "es2017"
| "es2018"
| "es2019"
| "es2020"
| "esnext" ;
2021-06-21 17:18:32 -04:00
/ * * L i s t o f n a m e s o f t y p e d e f i n i t i o n s t o i n c l u d e w h e n t y p e c h e c k i n g .
* Defaults to ` undefined ` .
2020-04-30 11:23:40 -04:00
*
* The type definitions are resolved according to the normal Deno resolution
2021-06-21 17:18:32 -04:00
* irrespective of if sources are provided on the call . In addition , unlike
* passing the ` --config ` option on startup , there is no base to resolve
* relative specifiers , so the specifiers here have to be fully qualified
* URLs or paths . For example :
*
* ` ` ` ts
* Deno . emit ( "./a.ts" , {
* compilerOptions : {
* types : [
* "https://deno.land/x/pkg/types.d.ts" ,
* "/Users/me/pkg/types.d.ts" ,
* ]
* }
* } ) ;
* ` ` `
2020-04-30 11:23:40 -04:00
* /
types? : string [ ] ;
2020-11-01 21:51:56 -05:00
/ * * E m i t c l a s s f i e l d s w i t h E C M A S c r i p t - s t a n d a r d s e m a n t i c s . D e f a u l t s t o
* ` false ` . * /
useDefineForClassFields? : boolean ;
2020-04-30 11:23:40 -04:00
}
2020-12-31 16:43:54 -05:00
interface ImportMap {
imports : Record < string , string > ;
scopes? : Record < string , Record < string , string > > ;
2020-04-30 11:23:40 -04:00
}
2021-04-06 09:33:02 -04:00
/ * *
* * * UNSTABLE * * : new API , yet to be vetted .
*
* The options for ` Deno.emit() ` API .
* /
export interface EmitOptions {
2020-12-31 16:43:54 -05:00
/ * * I n d i c a t e t h a t t h e s o u r c e c o d e s h o u l d b e e m i t t e d t o a s i n g l e f i l e
2021-04-25 16:54:57 -04:00
* JavaScript bundle that is a single ES module ( ` "module" ` ) or a single
2021-12-13 07:26:03 -05:00
* file self contained script executed in an immediately invoked function
2021-04-25 16:54:57 -04:00
* when loaded ( ` "classic" ` ) . * /
bundle ? : "module" | "classic" ;
2020-12-31 16:43:54 -05:00
/ * * I f ` t r u e ` t h e n t h e s o u r c e s w i l l b e t y p e d c h e c k e d , r e t u r n i n g a n y
* diagnostic errors in the result . If ` false ` type checking will be
* skipped . Defaults to ` true ` .
2021-01-29 08:15:59 -05:00
*
2020-12-31 16:43:54 -05:00
* * Note * by default , only TypeScript will be type checked , just like on
* the command line . Use the ` compilerOptions ` options of ` checkJs ` to
* enable type checking of JavaScript . * /
check? : boolean ;
/ * * A s e t o f o p t i o n s t h a t a r e a l i g n e d t o T y p e S c r i p t c o m p i l e r o p t i o n s t h a t
* are supported by Deno . * /
compilerOptions? : CompilerOptions ;
/** An [import-map](https:/ / deno . land / manual / linking_to_external_code / import_maps # import - maps )
* which will be applied to the imports . * /
importMap? : ImportMap ;
/** An absolute path to an [import-map](https:/ / deno . land / manual / linking_to_external_code / import_maps # import - maps ) .
* Required to be specified if an ` importMap ` is specified to be able to
* determine resolution of relative paths . If a ` importMap ` is not
* specified , then it will assumed the file path points to an import map on
* disk and will be attempted to be loaded based on current runtime
* permissions .
* /
importMapPath? : string ;
/ * * A r e c o r d o f s o u r c e s t o u s e w h e n d o i n g t h e e m i t . I f p r o v i d e d , D e n o w i l l
* use these sources instead of trying to resolve the modules externally . * /
sources? : Record < string , string > ;
}
2020-04-30 11:23:40 -04:00
2021-04-06 09:33:02 -04:00
/ * *
* * * UNSTABLE * * : new API , yet to be vetted .
*
* The result of ` Deno.emit() ` API .
* /
export interface EmitResult {
2021-06-11 19:42:43 -04:00
/ * * D i a g n o s t i c m e s s a g e s r e t u r n e d f r o m t h e t y p e c h e c k e r ( ` t s c ` ) .
*
* Can be used with ` Deno.formatDiagnostics ` to display a user
* friendly string . * /
2020-12-31 16:43:54 -05:00
diagnostics : Diagnostic [ ] ;
/ * * A n y e m i t t e d f i l e s . I f b u n d l e d , t h e n t h e J a v a S c r i p t w i l l h a v e t h e
* key of ` deno:///bundle.js ` with an optional map ( based on
* ` compilerOptions ` ) in ` deno:///bundle.js.map ` . * /
files : Record < string , string > ;
/** An optional array of any compiler options that were ignored by Deno. */
ignoredOptions? : string [ ] ;
/ * * A n a r r a y o f i n t e r n a l s t a t i s t i c s r e l a t e d t o t h e e m i t , f o r d i a g n o s t i c
* purposes . * /
stats : Array < [ string , number ] > ;
}
2020-04-30 11:23:40 -04:00
2020-12-31 16:43:54 -05:00
/ * *
* * * UNSTABLE * * : new API , yet to be vetted .
2021-01-29 08:15:59 -05:00
*
2020-12-31 16:43:54 -05:00
* Similar to the command line functionality of ` deno run ` or ` deno cache ` ,
* ` Deno.emit() ` provides a way to provide Deno arbitrary JavaScript
* or TypeScript and have it return JavaScript based on the options and
* settings provided . The source code can either be provided or the modules
* can be fetched and resolved in line with the behavior of the command line .
2021-01-29 08:15:59 -05:00
*
2020-12-31 16:43:54 -05:00
* Requires ` allow-read ` and / or ` allow-net ` if sources are not provided .
2021-01-29 08:15:59 -05:00
*
2020-12-31 16:43:54 -05:00
* @param rootSpecifier The specifier that will be used as the entry point .
* If no sources are provided , then the specifier would
* be the same as if you typed it on the command line for
* ` deno run ` . If sources are provided , it should match
* one of the names of the sources .
* @param options A set of options to be used with the emit .
2021-06-11 19:42:43 -04:00
*
* @returns The result of the emit . If diagnostics are found , they can be used
* with ` Deno.formatDiagnostics ` to construct a user friendly string , which
* has the same format as CLI diagnostics .
2020-04-30 11:23:40 -04:00
* /
2020-12-31 16:43:54 -05:00
export function emit (
rootSpecifier : string | URL ,
options? : EmitOptions ,
) : Promise < EmitResult > ;
2020-04-30 11:23:40 -04:00
/** **UNSTABLE**: Should not have same name as `window.location` type. */
interface Location {
/** The full url for the module, e.g. `file:/ / some / file . ts ` or
* ` https://some/file.ts ` . * /
fileName : string ;
/** The line number in the file. It is assumed to be 1-indexed. */
lineNumber : number ;
/** The column number in the file. It is assumed to be 1-indexed. */
columnNumber : number ;
}
2020-06-03 13:46:09 -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
*
* Given a current location in a module , lookup the source location and return
* it .
*
* When Deno transpiles code , it keep source maps of the transpiled code . This
* function can be used to lookup the original location . This is
* automatically done when accessing the ` .stack ` of an error , or when an
* uncaught error is logged . This function can be used to perform the lookup
* for creating better error handling .
*
2021-05-12 09:14:48 -04:00
* * * Note : * * ` lineNumber ` and ` columnNumber ` are 1 indexed , which matches display
2020-04-30 11:23:40 -04:00
* expectations , but is not typical of most index numbers in Deno .
*
* An example :
*
2020-05-16 15:23:48 -04:00
* ` ` ` ts
2021-05-12 09:14:48 -04:00
* const origin = Deno . applySourceMap ( {
2020-05-16 15:23:48 -04:00
* fileName : "file://my/module.ts" ,
* lineNumber : 5 ,
* columnNumber : 15
* } ) ;
2021-05-12 09:14:48 -04:00
*
* console . log ( ` ${ origin . fileName } : ${ origin . lineNumber } : ${ origin . columnNumber } ` ) ;
2020-05-16 15:23:48 -04:00
* ` ` `
2020-04-30 11:23:40 -04:00
* /
export function applySourceMap ( location : Location ) : Location ;
2020-11-30 11:08:03 -05:00
export type SetRawOptions = {
cbreak : boolean ;
} ;
2020-04-30 11:23:40 -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
*
* Set TTY to be under raw mode or not . In raw mode , characters are read and
* returned as is , without being processed . All special processing of
* characters by the terminal is disabled , including echoing input characters .
* Reading from a TTY device in raw mode is faster than reading from a TTY
* device in canonical mode .
*
2020-11-30 11:08:03 -05:00
* The ` cbreak ` option can be used to indicate that characters that correspond
* to a signal should still be generated . When disabling raw mode , this option
* is ignored . This functionality currently only works on Linux and Mac OS .
*
2020-05-16 15:23:48 -04:00
* ` ` ` ts
2021-05-13 08:20:55 -04:00
* Deno . setRaw ( Deno . stdin . rid , true , { cbreak : true } ) ;
2020-05-16 15:23:48 -04:00
* ` ` `
2020-04-30 11:23:40 -04:00
* /
2020-11-30 11:08:03 -05:00
export function setRaw (
rid : number ,
mode : boolean ,
options? : SetRawOptions ,
) : void ;
2020-04-30 11:23:40 -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 .
*
* 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
*
* Requires ` allow-write ` permission . * /
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 ;
/ * * * * 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 .
*
* 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
*
* Requires ` allow-write ` permission . * /
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 > ;
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 > ;
2020-06-03 13:46:09 -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 d d i t i o n a l c o n s i d e r a t i o n i s s t i l l
* necessary around the permissions required .
*
* Get the ` hostname ` of the machine the Deno process is running on .
2020-05-09 12:44:35 -04:00
*
2020-05-16 15:23:48 -04:00
* ` ` ` ts
* console . log ( Deno . hostname ( ) ) ;
* ` ` `
2020-05-09 12:44:35 -04:00
*
* Requires ` allow-env ` permission .
* /
export function hostname ( ) : string ;
2020-06-10 23:00:29 -04:00
2020-08-05 14:44:03 -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 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 } ) ;
* ` ` `
* /
export class HttpClient {
rid : number ;
close ( ) : void ;
}
/ * * * * 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 options used when creating a [ HttpClient ] .
* /
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
}
export interface Proxy {
url : string ;
basicAuth? : BasicAuth ;
}
export interface BasicAuth {
username : string ;
password : string ;
2020-08-05 14:44:03 -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 .
* 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
* ` ` `
* /
export function createHttpClient (
options : CreateHttpClientOptions ,
) : HttpClient ;
2020-08-31 14:29:43 -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 .
*
* 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 ( ) ) ;
* ` ` `
* /
export function futimeSync (
rid : number ,
atime : number | Date ,
mtime : number | Date ,
) : void ;
/ * * * * 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 .
*
* 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 ( ) ) ;
* ` ` `
* /
export function futime (
rid : number ,
atime : number | Date ,
mtime : number | Date ,
) : Promise < void > ;
2020-10-15 21:06:31 -04:00
2022-01-26 04:23:45 -05: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-10-15 21:06:31 -04:00
*
* SleepSync puts the main thread to sleep synchronously for a given amount of
* time in milliseconds .
*
* ` ` ` ts
* Deno . sleepSync ( 10 ) ;
* ` ` `
* /
2021-04-24 18:48:43 -04:00
export function sleepSync ( millis : number ) : void ;
2021-02-21 13:20:31 -05:00
2021-08-31 05:25:15 -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 generic transport listener for message - oriented protocols . * /
export interface DatagramConn extends AsyncIterable < [ Uint8Array , Addr ] > {
/ * * * * 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 .
*
* Waits for and resolves to the next message to the ` UDPConn ` . * /
receive ( p? : Uint8Array ) : Promise < [ Uint8Array , Addr ] > ;
/ * * 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 .
*
* Sends a message to the target . * /
send ( p : Uint8Array , addr : Addr ) : Promise < number > ;
/ * * 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 .
*
* 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 ] > ;
}
export interface UnixListenOptions {
/** A Path to the Unix Socket. */
path : string ;
}
/ * * * * 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 .
*
* 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 . * /
export function listen (
options : UnixListenOptions & { transport : "unix" } ,
) : Listener ;
/ * * * * 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
*
* 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 . * /
export function listenDatagram (
options : ListenOptions & { transport : "udp" } ,
) : DatagramConn ;
/ * * * * 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
*
* 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 . * /
export function listenDatagram (
options : UnixListenOptions & { transport : "unixpacket" } ,
) : DatagramConn ;
export interface UnixConnectOptions {
transport : "unix" ;
path : string ;
}
/ * * * * U N S T A B L E * * : T h e u n i x s o c k e t t r a n s p o r t i s u n s t a b l e a s a n e w A P I y e t t o
* be vetted . The TCP transport is considered stable .
*
* 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" . * /
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
2021-09-30 03:26:15 -04:00
export interface ConnectTlsOptions {
2021-08-31 05:25:15 -04:00
/** PEM formatted client certificate chain. */
2021-09-30 03:26:15 -04:00
certChain? : string ;
2021-08-31 05:25:15 -04:00
/** PEM formatted (RSA or PKCS8) private key of client certificate. */
2021-09-30 03:26:15 -04:00
privateKey? : string ;
2021-11-26 13:59:53 -05: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 .
*
* 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 [ ] ;
}
export interface TlsHandshakeInfo {
/ * * * * 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 .
*
* Contains the ALPN protocol selected during negotiation with the server .
* If no ALPN protocol selected , returns ` null ` .
* /
alpnProtocol : string | null ;
}
export interface TlsConn extends Conn {
/ * * R u n s t h e c l i e n t o r s e r v e r h a n d s h a k e p r o t o c o l t o c o m p l e t i o n i f t h a t h a s
* 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 > ;
2021-08-31 05:25:15 -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-09-02 18:28:12 -04:00
*
* 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 .
* /
2021-10-26 16:27:47 -04:00
export function connectTls ( options : ConnectTlsOptions ) : Promise < TlsConn > ;
2021-08-31 05:25:15 -04:00
export interface ListenTlsOptions {
/ * * * * 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 .
*
* 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 [ ] ;
}
2021-09-19 08:46:54 -04:00
2021-11-26 13:59:53 -05:00
export interface StartTlsOptions {
/ * * * * 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 .
*
* 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 [ ] ;
}
2022-03-22 23:04:20 -04:00
export interface Listener extends AsyncIterable < Conn > {
/ * * * * 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 .
*
* 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 ;
/ * * * * 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 .
*
* Make the listener not block the event loop from finishing .
* /
unref ( ) : void ;
}
2021-09-19 08:46:54 -04:00
/ * * * * U N S T A B L E * * : N e w A P I s h o u l d b e t e s t e d f i r s t .
*
* Acquire an advisory file - system lock for the provided file . ` exclusive `
* defaults to ` false ` .
* /
export function flock ( rid : number , exclusive? : boolean ) : Promise < void > ;
/ * * * * U N S T A B L E * * : N e w A P I s h o u l d b e t e s t e d f i r s t .
*
* Acquire an advisory file - system lock for the provided file . ` exclusive `
* defaults to ` false ` .
* /
export function flockSync ( rid : number , exclusive? : boolean ) : void ;
/ * * * * U N S T A B L E * * : N e w A P I s h o u l d b e t e s t e d f i r s t .
*
* Release an advisory file - system lock for the provided file .
* /
export function funlock ( rid : number ) : Promise < void > ;
/ * * * * U N S T A B L E * * : N e w A P I s h o u l d b e t e s t e d f i r s t .
*
* Release an advisory file - system lock for the provided file .
* /
export function funlockSync ( rid : number ) : void ;
2021-12-09 03:00:55 -05: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 .
*
* Make the timer of the given id blocking the event loop from finishing
* /
export function refTimer ( id : number ) : void ;
/ * * * * 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 .
*
* Make the timer of the given id not blocking the event loop from finishing
* /
export function unrefTimer ( id : number ) : void ;
2022-03-16 09:54:18 -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 r .
*
* Allows to "hijack" a connection that the request is associated with .
* 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 .
* /
export function upgradeHttp (
request : Request ,
) : Promise < [ Deno . Conn , Uint8Array ] > ;
2020-04-30 11:23:40 -04:00
}
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
declare interface WorkerOptions {
/ * * U N S T A B L E : N e w A P I .
*
* Set deno . namespace to ` true ` to make ` Deno ` namespace and all of its
* methods available to the worker environment . Defaults to ` false ` .
*
2022-03-24 11:27:24 -04:00
* Configure permissions options to change the level of access the worker will
* 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 : {
* namespace : true ,
* permissions : {
* read : true ,
* } ,
* } ,
* }
* ) ;
* ` ` `
* /
// TODO(Soremwar)
// `deno: boolean` is kept for backwards compatibility with the previous
// worker options implementation. Remove for 2.0.
deno? : boolean | {
namespace ? : boolean ;
/** 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
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
}
declare interface WebSocketConnection {
readable : ReadableStream < string | Uint8Array > ;
writable : WritableStream < string | Uint8Array > ;
extensions : string ;
protocol : string ;
}
declare interface WebSocketCloseInfo {
code? : number ;
reason? : string ;
}
declare class WebSocketStream {
constructor ( url : string , options? : WebSocketStreamOptions ) ;
url : string ;
connection : Promise < WebSocketConnection > ;
closed : Promise < WebSocketCloseInfo > ;
close ( closeInfo? : WebSocketCloseInfo ) : void ;
}