diff --git a/cli/js/lib.deno.ns.d.ts b/cli/js/lib.deno.ns.d.ts index bf10049..99e4001 100644 --- a/cli/js/lib.deno.ns.d.ts +++ b/cli/js/lib.deno.ns.d.ts @@ -17,6 +17,9 @@ declare namespace Deno { export interface TestDefinition { fn: TestFunction; name: string; + ignore?: boolean; + disableOpSanitizer?: boolean; + disableResourceSanitizer?: boolean; } /** Register a test which will be run when `deno test` is used on the command @@ -32,6 +35,71 @@ declare namespace Deno { * when `Deno.runTests` is used */ export function test(name: string, fn: TestFunction): void; + enum TestStatus { + Passed = "passed", + Failed = "failed", + Ignored = "ignored" + } + + interface TestResult { + name: string; + status: TestStatus; + duration?: number; + error?: Error; + } + + interface TestStats { + filtered: number; + ignored: number; + measured: number; + passed: number; + failed: number; + } + + export enum TestEvent { + Start = "start", + TestStart = "testStart", + TestEnd = "testEnd", + End = "end" + } + + interface TestEventStart { + kind: TestEvent.Start; + tests: number; + } + + interface TestEventTestStart { + kind: TestEvent.TestStart; + name: string; + } + + interface TestEventTestEnd { + kind: TestEvent.TestEnd; + result: TestResult; + } + + interface TestEventEnd { + kind: TestEvent.End; + stats: TestStats; + duration: number; + results: TestResult[]; + } + + interface TestReporter { + start(event: TestEventStart): Promise; + testStart(msg: TestEventTestStart): Promise; + testEnd(msg: TestEventTestEnd): Promise; + end(event: TestEventEnd): Promise; + } + + export class ConsoleTestReporter implements TestReporter { + constructor(); + start(event: TestEventStart): Promise; + testStart(msg: TestEventTestStart): Promise; + testEnd(msg: TestEventTestEnd): Promise; + end(event: TestEventEnd): Promise; + } + export interface RunTestsOptions { /** If `true`, Deno will exit with status code 1 if there was * test failure. Defaults to `true`. */ @@ -46,11 +114,19 @@ declare namespace Deno { skip?: string | RegExp; /** Disable logging of the results. Defaults to `false`. */ disableLog?: boolean; + /** Custom reporter class. If not provided uses console reporter. */ + reporter?: TestReporter; } /** Run any tests which have been registered. Always resolves * asynchronously. */ - export function runTests(opts?: RunTestsOptions): Promise; + export function runTests( + opts?: RunTestsOptions + ): Promise<{ + results: TestResult[]; + stats: TestStats; + duration: number; + }>; /** Get the `loadavg`. Requires `allow-env` permission. * @@ -264,8 +340,6 @@ declare namespace Deno { */ export function execPath(): string; - // @url js/dir.d.ts - /** * **UNSTABLE**: maybe needs permissions. * @@ -279,11 +353,18 @@ declare namespace Deno { export function cwd(): string; /** - * **UNSTABLE**: maybe needs permissions. + * **UNSTABLE**: Currently under evaluation to decide if explicit permission is + * required to change the current working directory. * * Change the current working directory to the specified path. * - * Throws `Deno.errors.NotFound` if directory not available. + * Deno.chdir("/home/userA"); + * Deno.chdir("../userB"); + * Deno.chdir("C:\\Program Files (x86)\\Java"); + * + * Throws `Deno.errors.NotFound` if directory not found. + * Throws `Deno.errors.PermissionDenied` if the user does not have access + * rights */ export function chdir(directory: string): void; @@ -299,8 +380,6 @@ declare namespace Deno { export const EOF: unique symbol; export type EOF = typeof EOF; - // @url js/io.d.ts - /** **UNSTABLE**: might remove `"SEEK_"` prefix. Might not use all-caps. */ export enum SeekMode { SEEK_START = 0, @@ -435,13 +514,11 @@ declare namespace Deno { */ export function toAsyncIterator(r: Reader): AsyncIterableIterator; - // @url js/files.d.ts - /** Synchronously open a file and return an instance of the `File` object. * * const file = Deno.openSync("/foo/bar.txt", { read: true, write: true }); * - * Requires `allow-read` and `allow-write` permissions depending on mode. + * Requires `allow-read` and `allow-write` permissions depending on openMode. */ export function openSync(path: string, options?: OpenOptions): File; @@ -449,15 +526,15 @@ declare namespace Deno { * * const file = Deno.openSync("/foo/bar.txt", "r"); * - * Requires `allow-read` and `allow-write` permissions depending on mode. + * Requires `allow-read` and `allow-write` permissions depending on openMode. */ - export function openSync(path: string, mode?: OpenMode): File; + export function openSync(path: string, openMode?: OpenMode): File; /** Open a file and resolve to an instance of the `File` object. * * const file = await Deno.open("/foo/bar.txt", { read: true, write: true }); * - * Requires `allow-read` and `allow-write` permissions depending on mode. + * Requires `allow-read` and `allow-write` permissions depending on openMode. */ export function open(path: string, options?: OpenOptions): Promise; @@ -465,9 +542,9 @@ declare namespace Deno { * * const file = await Deno.open("/foo/bar.txt, "w+"); * - * Requires `allow-read` and `allow-write` permissions depending on mode. + * Requires `allow-read` and `allow-write` permissions depending on openMode. */ - export function open(path: string, mode?: OpenMode): Promise; + export function open(path: string, openMode?: OpenMode): Promise; /** Creates a file if none exists or truncates an existing file and returns * an instance of `Deno.File`. @@ -553,7 +630,12 @@ declare namespace Deno { whence: SeekMode ): Promise; - /** Close the given resource ID. */ + /** Close the given resource ID (rid) which has been previously opened, such + * as via opening or creating a file. Closing a file when you are finished + * with it is important to avoid leaking resources. + * + * Deno.close(4); + */ export function close(rid: number): void; /** The Deno abstraction for reading and writing files. */ @@ -600,7 +682,7 @@ declare namespace Deno { append?: boolean; /** Sets the option for truncating a previous file. If a file is * successfully opened with this option set it will truncate the file to `0` - * length if it already exists. The file must be opened with write access + * size if it already exists. The file must be opened with write access * for truncate to work. */ truncate?: boolean; /** Sets the option to allow creating a new file, if one doesn't already @@ -612,9 +694,13 @@ declare namespace Deno { * access to be used. When createNew is set to `true`, create and truncate * are ignored. */ createNew?: boolean; + /** Permissions to use if creating the file (defaults to `0o666`, before + * the process's umask). + * Ignored on Windows. */ + mode?: number; } - /** A set of string literals which specify the open mode of a file. + /** A set of string literals which specify how to open a file. * * |Value |Description | * |------|--------------------------------------------------------------------------------------------------| @@ -629,8 +715,6 @@ declare namespace Deno { */ export type OpenMode = "r" | "r+" | "w" | "w+" | "a" | "a+" | "x" | "x+"; - // @url js/tty.d.ts - /** **UNSTABLE**: newly added API * * Check if a given resource is TTY. */ @@ -641,8 +725,6 @@ declare namespace Deno { * Set TTY to be under raw mode or not. */ export function setRaw(rid: number, mode: boolean): void; - // @url js/buffer.d.ts - /** A variable-sized buffer of bytes with `read()` and `write()` methods. * * Based on [Go Buffer](https://golang.org/pkg/bytes/#Buffer). */ @@ -729,8 +811,6 @@ declare namespace Deno { /** Synchronously write all the content of `arr` to `w`. */ export function writeAllSync(w: SyncWriter, arr: Uint8Array): void; - // @url js/mkdir.d.ts - export interface MkdirOptions { /** Defaults to `false`. If set to `true`, means that any intermediate * directories will also be created (as with the shell command `mkdir -p`). @@ -774,8 +854,6 @@ declare namespace Deno { mode?: number ): Promise; - // @url js/make_temp.d.ts - export interface MakeTempOptions { /** Directory where the temporary directory should be created (defaults to * the env variable TMPDIR, or the system's default, usually /tmp). */ @@ -854,13 +932,15 @@ declare namespace Deno { * Requires `allow-write` permission. */ export function makeTempFile(options?: MakeTempOptions): Promise; - // @url js/chmod.d.ts - /** Synchronously changes the permission of a specific file/directory of * specified path. Ignores the process's umask. * * Deno.chmodSync("/path/to/file", 0o666); * + * For a full description, see [chmod](#chmod) + * + * NOTE: This API currently throws on Windows + * * Requires `allow-write` permission. */ export function chmodSync(path: string, mode: number): void; @@ -869,35 +949,59 @@ declare namespace Deno { * * await Deno.chmod("/path/to/file", 0o666); * + * The mode is a sequence of 3 octal numbers. The first/left-most number + * specifies the permissions for the owner. The second number specifies the + * permissions for the group. The last/right-most number specifies the + * permissions for others. For example, with a mode of 0o764, the owner (7) can + * read/write/execute, the group (6) can read/write and everyone else (4) can + * read only. + * + * | Number | Description | + * | ------ | ----------- | + * | 7 | read, write, and execute | + * | 6 | read and write | + * | 5 | read and execute | + * | 4 | read only | + * | 3 | write and execute | + * | 2 | write only | + * | 1 | execute only | + * | 0 | no permission | + * + * NOTE: This API currently throws on Windows + * * Requires `allow-write` permission. */ export function chmod(path: string, mode: number): Promise; - // @url js/chown.d.ts - - /** Synchronously change owner of a regular file or directory. Linux/Mac OS - * only at the moment. + /** Synchronously change owner of a regular file or directory. This functionality + * is not available on Windows. + * + * Deno.chownSync('myFile.txt', 1000, 1002); * * Requires `allow-write` permission. * + * Throws Error (not implemented) if executed on Windows + * * @param path path to the file - * @param uid user id of the new owner - * @param gid group id of the new owner + * @param uid user id (UID) of the new owner + * @param gid group id (GID) of the new owner */ export function chownSync(path: string, uid: number, gid: number): void; - /** Change owner of a regular file or directory. Linux/Mac OS only at the - * moment. + /** Change owner of a regular file or directory. This functionality + * is not available on Windows. + * + * await Deno.chown('myFile.txt', 1000, 1002); * * Requires `allow-write` permission. * + * Throws Error (not implemented) if executed on Windows + * * @param path path to the file - * @param uid user id of the new owner - * @param gid group id of the new owner + * @param uid user id (UID) of the new owner + * @param gid group id (GID) of the new owner */ export function chown(path: string, uid: number, gid: number): Promise; - // @url js/utime.d.ts - /** **UNSTABLE**: needs investigation into high precision time. * * Synchronously changes the access and modification times of a file system @@ -928,8 +1032,6 @@ declare namespace Deno { mtime: number | Date ): Promise; - // @url js/remove.d.ts - export interface RemoveOptions { /** Defaults to `false`. If set to `true`, path will be removed even if * it's a non-empty directory. */ @@ -954,8 +1056,6 @@ declare namespace Deno { * Requires `allow-write` permission. */ export function remove(path: string, options?: RemoveOptions): Promise; - // @url js/rename.d.ts - /** Synchronously renames (moves) `oldpath` to `newpath`. If `newpath` already * exists and is not a directory, `renameSync()` replaces it. OS-specific * restrictions may apply when `oldpath` and `newpath` are in different @@ -975,8 +1075,6 @@ declare namespace Deno { * Requires `allow-read` and `allow-write`. */ export function rename(oldpath: string, newpath: string): Promise; - // @url js/read_file.d.ts - /** Reads and returns the entire contents of a file. * * const decoder = new TextDecoder("utf-8"); @@ -995,18 +1093,12 @@ declare namespace Deno { * Requires `allow-read` permission. */ export function readFile(path: string): Promise; - // @url js/file_info.d.ts - - /** UNSTABLE: 'len' maybe should be 'length' or 'size'. - * - * A FileInfo describes a file and is returned by `stat`, `lstat`, + /** A FileInfo describes a file and is returned by `stat`, `lstat`, * `statSync`, `lstatSync`. A list of FileInfo is returned by `readdir`, * `readdirSync`. */ export interface FileInfo { - /** **UNSTABLE**: `.len` maybe should be `.length` or `.size`. - * - * The size of the file, in bytes. */ - len: number; + /** The size of the file, in bytes. */ + size: number; /** The last modification time of the file. This corresponds to the `mtime` * field from `stat` on Linux/Mac OS and `ftLastWriteTime` on Windows. This * may not be available on all platforms. */ @@ -1069,8 +1161,6 @@ declare namespace Deno { isSymlink(): boolean; } - // @url js/realpath.d.ts - /** Returns absolute normalized path with, symbolic links resolved. * * const realPath = Deno.realpathSync("./some/path"); @@ -1085,8 +1175,6 @@ declare namespace Deno { * Requires `allow-read` permission. */ export function realpath(path: string): Promise; - // @url js/read_dir.d.ts - /** UNSTABLE: need to consider streaming case * * Synchronously reads the directory given by `path` and returns an array of @@ -1106,8 +1194,6 @@ declare namespace Deno { * Requires `allow-read` permission. */ export function readdir(path: string): Promise; - // @url js/copy_file.d.ts - /** Synchronously copies the contents and permissions of one file to another * specified path, by default creating a new file if needed, else overwriting. * Fails if target path is a directory or is unwritable. @@ -1128,8 +1214,6 @@ declare namespace Deno { * Requires `allow-write` permission on toPath. */ export function copyFile(fromPath: string, toPath: string): Promise; - // @url js/read_link.d.ts - /** Returns the destination of the named symbolic link. * * const targetPath = Deno.readlinkSync("symlink/path"); @@ -1144,8 +1228,6 @@ declare namespace Deno { * Requires `allow-read` permission. */ export function readlink(path: string): Promise; - // @url js/stat.d.ts - /** Resolves to a `Deno.FileInfo` for the specified `path`. If `path` is a * symlink, information for the symlink will be returned. * @@ -1182,27 +1264,23 @@ declare namespace Deno { * Requires `allow-read` permission. */ export function statSync(path: string): FileInfo; - // @url js/link.d.ts - - /** Creates `newname` as a hard link to `oldname`. + /** Creates `newpath` as a hard link to `oldpath`. * * Deno.linkSync("old/name", "new/name"); * * Requires `allow-read` and `allow-write` permissions. */ - export function linkSync(oldname: string, newname: string): void; + export function linkSync(oldpath: string, newpath: string): void; - /** Creates `newname` as a hard link to `oldname`. + /** Creates `newpath` as a hard link to `oldpath`. * * await Deno.link("old/name", "new/name"); * * Requires `allow-read` and `allow-write` permissions. */ - export function link(oldname: string, newname: string): Promise; - - // @url js/symlink.d.ts + export function link(oldpath: string, newpath: string): Promise; /** **UNSTABLE**: `type` argument type may be changed to `"dir" | "file"`. * - * Creates `newname` as a symbolic link to `oldname`. The type argument can be + * Creates `newpath` as a symbolic link to `oldpath`. The type argument can be * set to `dir` or `file`. Is only available on Windows and ignored on other * platforms. * @@ -1210,14 +1288,14 @@ declare namespace Deno { * * Requires `allow-read` and `allow-write` permissions. */ export function symlinkSync( - oldname: string, - newname: string, + oldpath: string, + newpath: string, type?: string ): void; /** **UNSTABLE**: `type` argument may be changed to "dir" | "file" * - * Creates `newname` as a symbolic link to `oldname`. The type argument can be + * Creates `newpath` as a symbolic link to `oldpath`. The type argument can be * set to `dir` or `file`. Is only available on Windows and ignored on other * platforms. * @@ -1225,13 +1303,11 @@ declare namespace Deno { * * Requires `allow-read` and `allow-write` permissions. */ export function symlink( - oldname: string, - newname: string, + oldpath: string, + newpath: string, type?: string ): Promise; - // @url js/write_file.d.ts - /** Options for writing to a file. */ export interface WriteFileOptions { /** Defaults to `false`. If set to `true`, will append to a file instead of @@ -1426,8 +1502,6 @@ declare namespace Deno { constructor(state: PermissionState); } - // @url js/truncate.d.ts - /** Synchronously truncates or extends the specified file, to reach the * specified `len`. * @@ -1648,12 +1722,13 @@ declare namespace Deno { } /** - * Connects to the address on the named transport. + * Connects to the hostname (default is "127.0.0.1") and port on the named + * transport (default is "tcp"). * - * Deno.connect({ port: 80 }) - * Deno.connect({ hostname: "192.0.2.1", port: 80 }) - * Deno.connect({ hostname: "[2001:db8::1]", port: 80 }); - * Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" }) + * 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" }) * * Requires `allow-net` permission. */ export function connect(options: ConnectOptions): Promise; @@ -1793,12 +1868,12 @@ declare namespace Deno { signal?: number; } - /** **UNSTABLE**: Maybe rename `args` to `argv` to differentiate from + /** **UNSTABLE**: `args` has been recently renamed to `cmd` to differentiate from * `Deno.args`. */ export interface RunOptions { /** Arguments to pass. Note, the first element needs to be a path to the * binary */ - args: string[]; + cmd: string[]; cwd?: string; env?: { [key: string]: string; @@ -2230,8 +2305,9 @@ declare namespace Deno { /** **UNSTABLE**: new API, yet to be vetted. * - * Takes a root module name, any optionally a record set of sources. Resolves - * with a compiled set of modules. If just a root name is provided, the modules + * Takes a root module name, and optionally a record set of sources. Resolves + * with a compiled set of modules and possibly diagnostics if the compiler + * encountered any issues. If just a root name is provided, the modules * will be resolved as if the root module had been passed on the command line. * * If sources are passed, all modules will be resolved out of this object, where @@ -2264,16 +2340,21 @@ declare namespace Deno { ): Promise<[DiagnosticItem[] | undefined, Record]>; /** **UNSTABLE**: new API, yet to be vetted. + * + * `bundle()` is part the compiler API. A full description of this functionality + * can be found in the [manual](https://deno.land/std/manual.md#denobundle). * * Takes a root module name, and optionally a record set of sources. Resolves - * with a single JavaScript string that is like the output of a `deno bundle` - * command. If just a root name is provided, the modules will be resolved as if - * the root module had been passed on the command line. + * with a single JavaScript string (and bundle diagnostics if issues arise with + * the bundling) that is like the output of a `deno bundle` command. If just + * a root name is provided, the modules will be resolved as if the root module + * had been passed on the command line. * * If sources are passed, all modules will be resolved out of this object, where * the key is the module name and the value is the content. The extension of the * module name will be used to determine the media type of the module. * + * //equivalent to "deno bundle foo.ts" from the command line * const [ maybeDiagnostics1, output1 ] = await Deno.bundle("foo.ts"); * * const [ maybeDiagnostics2, output2 ] = await Deno.bundle("/foo.ts", { diff --git a/cli/js/lib.deno.shared_globals.d.ts b/cli/js/lib.deno.shared_globals.d.ts index ea8bf08..1be54ad 100644 --- a/cli/js/lib.deno.shared_globals.d.ts +++ b/cli/js/lib.deno.shared_globals.d.ts @@ -291,8 +291,6 @@ declare interface ImportMeta { } declare namespace __domTypes { - // @url js/dom_types.d.ts - export type BufferSource = ArrayBufferView | ArrayBuffer; export type HeadersInit = | Headers @@ -872,8 +870,6 @@ declare namespace __domTypes { } declare namespace __blob { - // @url js/blob.d.ts - export const bytesSymbol: unique symbol; export const blobBytesWeakMap: WeakMap<__domTypes.Blob, Uint8Array>; export class DenoBlob implements __domTypes.Blob { @@ -890,8 +886,6 @@ declare namespace __blob { } declare namespace __console { - // @url js/console.d.ts - type ConsoleOptions = Partial<{ showHidden: boolean; depth: number; @@ -979,8 +973,6 @@ declare namespace __console { } declare namespace __event { - // @url js/event.d.ts - export const eventAttributes: WeakMap; export class EventInit implements __domTypes.EventInit { bubbles: boolean; @@ -1052,8 +1044,6 @@ declare namespace __event { } declare namespace __customEvent { - // @url js/custom_event.d.ts - export const customEventAttributes: WeakMap; export class CustomEventInit extends __event.EventInit implements __domTypes.CustomEventInit { @@ -1080,8 +1070,6 @@ declare namespace __customEvent { } declare namespace __eventTarget { - // @url js/event_target.d.ts - export class EventListenerOptions implements __domTypes.EventListenerOptions { _capture: boolean; constructor({ capture }?: { capture?: boolean | undefined }); @@ -1223,8 +1211,6 @@ declare namespace __io { } declare namespace __fetch { - // @url js/fetch.d.ts - class Body implements __domTypes.Body, __domTypes.ReadableStream, __io.ReadCloser { private rid; @@ -1285,8 +1271,6 @@ declare namespace __fetch { } declare namespace __textEncoding { - // @url js/text_encoding.d.ts - export function atob(s: string): string; /** Creates a base-64 ASCII string from the input string. */ export function btoa(s: string): string; @@ -1328,8 +1312,6 @@ declare namespace __textEncoding { } declare namespace __timers { - // @url js/timers.d.ts - export type Args = unknown[]; /** Sets a timer which executes a function once after the timer expires. */ export function setTimeout( @@ -1348,8 +1330,6 @@ declare namespace __timers { } declare namespace __urlSearchParams { - // @url js/url_search_params.d.ts - export class URLSearchParams { private params; private url; @@ -1455,7 +1435,6 @@ declare namespace __urlSearchParams { } declare namespace __url { - // @url js/url.d.ts export interface URL { hash: string; host: string; @@ -1482,7 +1461,6 @@ declare namespace __url { } declare namespace __workers { - // @url js/workers.d.ts export interface Worker { onerror?: (e: Event) => void; onmessage?: (e: { data: any }) => void; @@ -1509,8 +1487,6 @@ declare namespace __workers { } declare namespace __performanceUtil { - // @url js/performance.d.ts - export class Performance { /** Returns a current time from Deno's start in milliseconds. *