diff --git a/cli/js/lib.deno.ns.d.ts b/cli/js/lib.deno.ns.d.ts index 710d33de6fe23d..0bd176a9f8e23e 100644 --- a/cli/js/lib.deno.ns.d.ts +++ b/cli/js/lib.deno.ns.d.ts @@ -7,7 +7,9 @@ declare namespace Deno { /** The current process id of the runtime. */ export let pid: number; - /** Reflects the NO_COLOR environment variable: https://no-color.org/ */ + /** Reflects the NO_COLOR environment variable. + * + * See: https://no-color.org/ */ export let noColor: boolean; export type TestFunction = () => void | Promise; @@ -17,32 +19,50 @@ declare namespace Deno { name: string; } + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module, or explicitly + * when `Deno.runTests` is used */ export function test(t: TestDefinition): void; + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module, or explicitly + * when `Deno.runTests` is used */ export function test(fn: TestFunction): void; + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module, or explicitly + * when `Deno.runTests` is used */ export function test(name: string, fn: TestFunction): void; export interface RunTestsOptions { + /** If `true`, Deno will exit upon a failure after logging that failure to + * the console. Defaults to `false`. */ exitOnFail?: boolean; + /** Provide a regular expression of which only tests that match the regular + * expression are run. */ only?: RegExp; + /** Provide a regular expression of which tests that match the regular + * expression are skipped. */ skip?: RegExp; + /** Disable logging of the results. Defaults to `false`. */ disableLog?: boolean; } + /** Run any tests which have been registered. Always resolves + * asynchronously. */ export function runTests(opts?: RunTestsOptions): Promise; - /** Get the loadavg. Requires the `--allow-env` flag. + /** Get the `loadavg`. Requires the `allow-env` permission. * * console.log(Deno.loadavg()); */ export function loadavg(): number[]; - /** Get the hostname. Requires the `--allow-env` flag. + /** Get the `hostname`. Requires the `allow-env` permission. * * console.log(Deno.hostname()); */ export function hostname(): string; - /** Get the OS release. Requires the `--allow-env` flag. + /** Get the OS release. Requires the `allow-env` permission. * * console.log(Deno.osRelease()); */ @@ -52,32 +72,35 @@ declare namespace Deno { export function exit(code?: number): never; /** Returns a snapshot of the environment variables at invocation. Mutating a - * property in the object will set that variable in the environment for - * the process. The environment object will only accept `string`s - * as values. + * property in the object will set that variable in the environment for the + * process. The environment object will only accept `string`s as values. * * const myEnv = Deno.env(); * console.log(myEnv.SHELL); * myEnv.TEST_VAR = "HELLO"; * const newEnv = Deno.env(); * console.log(myEnv.TEST_VAR == newEnv.TEST_VAR); + * + * Requires the `allow-env` permission. */ export function env(): { [index: string]: string; }; - /** Returns the value of an environment variable at invocation. - * If the variable is not present, `undefined` will be returned. + /** Returns the value of an environment variable at invocation. If the + * variable is not present, `undefined` will be returned. * * const myEnv = Deno.env(); * console.log(myEnv.SHELL); * myEnv.TEST_VAR = "HELLO"; * const newEnv = Deno.env(); * console.log(myEnv.TEST_VAR == newEnv.TEST_VAR); + * + * Requires the `allow-env` permission. */ export function env(key: string): string | undefined; - /** UNSTABLE */ + /** **UNSTABLE** */ export type DirKind = | "home" | "cache" @@ -97,18 +120,20 @@ declare namespace Deno { // TODO(ry) markdown in jsdoc broken https://deno.land/typedoc/index.html#dir /** - * UNSTABLE: Might rename method dir and type alias DirKind. + * **UNSTABLE**: Might rename method `dir` and type alias `DirKind`. * * Returns the user and platform specific directories. - * Requires the `--allow-env` flag. - * Returns null if there is no applicable directory or if any other error + * + * Requires the `allow-env` permission. + * + * Returns `null` if there is no applicable directory or if any other error * occurs. * - * Argument values: "home", "cache", "config", "executable", "data", - * "data_local", "audio", "desktop", "document", "download", "font", "picture", - * "public", "template", "video" + * Argument values: `"home"`, `"cache"`, `"config"`, `"executable"`, `"data"`, + * `"data_local"`, `"audio"`, `"desktop"`, `"document"`, `"download"`, + * `"font"`, `"picture"`, `"public"`, `"template"`, `"video"` * - * "cache" + * `"cache"` * * |Platform | Value | Example | * | ------- | ----------------------------------- | ---------------------------- | @@ -116,7 +141,7 @@ declare namespace Deno { * | macOS | `$HOME`/Library/Caches | /Users/Alice/Library/Caches | * | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local | * - * "config" + * `"config"` * * |Platform | Value | Example | * | ------- | ------------------------------------- | -------------------------------- | @@ -124,7 +149,7 @@ declare namespace Deno { * | macOS | `$HOME`/Library/Preferences | /Users/Alice/Library/Preferences | * | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming | * - * "executable" + * `"executable"` * * |Platform | Value | Example | * | ------- | --------------------------------------------------------------- | -----------------------| @@ -132,7 +157,7 @@ declare namespace Deno { * | macOS | - | - | * | Windows | - | - | * - * "data" + * `"data"` * * |Platform | Value | Example | * | ------- | ---------------------------------------- | ---------------------------------------- | @@ -140,7 +165,7 @@ declare namespace Deno { * | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support | * | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming | * - * "data_local" + * `"data_local"` * * |Platform | Value | Example | * | ------- | ---------------------------------------- | ---------------------------------------- | @@ -148,7 +173,7 @@ declare namespace Deno { * | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support | * | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local | * - * "audio" + * `"audio"` * * |Platform | Value | Example | * | ------- | ------------------ | -------------------- | @@ -156,7 +181,7 @@ declare namespace Deno { * | macOS | `$HOME`/Music | /Users/Alice/Music | * | Windows | `{FOLDERID_Music}` | C:\Users\Alice\Music | * - * "desktop" + * `"desktop"` * * |Platform | Value | Example | * | ------- | -------------------- | ---------------------- | @@ -164,7 +189,7 @@ declare namespace Deno { * | macOS | `$HOME`/Desktop | /Users/Alice/Desktop | * | Windows | `{FOLDERID_Desktop}` | C:\Users\Alice\Desktop | * - * "document" + * `"document"` * * |Platform | Value | Example | * | ------- | ---------------------- | ------------------------ | @@ -172,7 +197,7 @@ declare namespace Deno { * | macOS | `$HOME`/Documents | /Users/Alice/Documents | * | Windows | `{FOLDERID_Documents}` | C:\Users\Alice\Documents | * - * "download" + * `"download"` * * |Platform | Value | Example | * | ------- | ---------------------- | ------------------------ | @@ -180,7 +205,7 @@ declare namespace Deno { * | macOS | `$HOME`/Downloads | /Users/Alice/Downloads | * | Windows | `{FOLDERID_Downloads}` | C:\Users\Alice\Downloads | * - * "font" + * `"font"` * * |Platform | Value | Example | * | ------- | ---------------------------------------------------- | ------------------------------ | @@ -188,7 +213,7 @@ declare namespace Deno { * | macOS | `$HOME/Library/Fonts` | /Users/Alice/Library/Fonts | * | Windows | – | – | * - * "picture" + * `"picture"` * * |Platform | Value | Example | * | ------- | --------------------- | ----------------------- | @@ -196,7 +221,7 @@ declare namespace Deno { * | macOS | `$HOME`/Pictures | /Users/Alice/Pictures | * | Windows | `{FOLDERID_Pictures}` | C:\Users\Alice\Pictures | * - * "public" + * `"public"` * * |Platform | Value | Example | * | ------- | --------------------- | ------------------- | @@ -204,7 +229,7 @@ declare namespace Deno { * | macOS | `$HOME`/Public | /Users/Alice/Public | * | Windows | `{FOLDERID_Public}` | C:\Users\Public | * - * "template" + * `"template"` * * |Platform | Value | Example | * | ------- | ---------------------- | ---------------------------------------------------------- | @@ -212,151 +237,198 @@ declare namespace Deno { * | macOS | – | – | * | Windows | `{FOLDERID_Templates}` | C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Templates | * - * "video" + * `"video"` * * |Platform | Value | Example | * | ------- | ------------------- | --------------------- | * | Linux | `XDG_VIDEOS_DIR` | /home/alice/Videos | * | macOS | `$HOME`/Movies | /Users/Alice/Movies | * | Windows | `{FOLDERID_Videos}` | C:\Users\Alice\Videos | + * */ export function dir(kind: DirKind): string | null; /** * Returns the path to the current deno executable. - * Requires the `--allow-env` flag. + * + * Requires the `allow-env` permission. */ export function execPath(): string; /** - * UNSTABLE: maybe needs permissions. + * **UNSTABLE**: maybe needs permissions. + * + * Return a string representing the current working directory. + * + * If the current directory can be reached via multiple paths (due to symbolic + * links), `cwd()` may return any one of them. * - * `cwd()` Return a string representing the current working directory. - * If the current directory can be reached via multiple paths - * (due to symbolic links), `cwd()` may return - * any one of them. - * throws `NotFound` exception if directory not available + * Throws `Deno.errors.NotFound` if directory not available. */ export function cwd(): string; /** - * UNSTABLE: maybe needs permissions. + * **UNSTABLE**: maybe needs permissions. * - * `chdir()` Change the current working directory to path. - * throws `NotFound` exception if directory not available + * Change the current working directory to path. + * + * Throws `Deno.errors.NotFound` if directory not available. */ export function chdir(directory: string): void; - /** UNSTABLE: might move to Deno.symbols */ + /** **UNSTABLE**: might move to `Deno.symbols`. */ export const EOF: unique symbol; - - /** UNSTABLE: might move to Deno.symbols */ export type EOF = typeof EOF; - /** UNSTABLE: maybe remove "SEEK_" prefix. Maybe capitalization wrong. */ + /** **UNSTABLE**: might remove `"SEEK_"` prefix. Might not use all-caps. */ export enum SeekMode { SEEK_START = 0, SEEK_CURRENT = 1, SEEK_END = 2 } - /** UNSTABLE: Make Reader into iterator of some sort */ + /** **UNSTABLE**: might make `Reader` into iterator of some sort. */ export interface Reader { - /** Reads up to p.byteLength bytes into `p`. It resolves to the number - * of bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error encountered. - * Even if `read()` returns `n` < `p.byteLength`, it may use all of `p` as - * scratch space during the call. If some data is available but not - * `p.byteLength` bytes, `read()` conventionally returns what is available - * instead of waiting for more. + /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number + * of bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error + * encountered. Even if `read()` returns `n` < `p.byteLength`, it may use + * all of `p` as scratch space during the call. If some data is available + * but not `p.byteLength` bytes, `read()` conventionally returns what is + * available instead of waiting for more. * - * When `read()` encounters end-of-file condition, it returns EOF symbol. + * When `read()` encounters end-of-file condition, it returns `Deno.EOF` + * symbol. * * When `read()` encounters an error, it rejects with an error. * * Callers should always process the `n` > `0` bytes returned before - * considering the EOF. Doing so correctly handles I/O errors that happen + * considering the `EOF`. Doing so correctly handles I/O errors that happen * after reading some bytes and also both of the allowed EOF behaviors. * - * Implementations must not retain `p`. + * Implementations should not retain a reference to `p`. */ read(p: Uint8Array): Promise; } + export interface SyncReader { + /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number + * of bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error + * encountered. Even if `read()` returns `n` < `p.byteLength`, it may use + * all of `p` as scratch space during the call. If some data is available + * but not `p.byteLength` bytes, `read()` conventionally returns what is + * available instead of waiting for more. + * + * When `readSync()` encounters end-of-file condition, it returns `Deno.EOF` + * symbol. + * + * When `readSync()` encounters an error, it throws with an error. + * + * Callers should always process the `n` > `0` bytes returned before + * considering the `EOF`. Doing so correctly handles I/O errors that happen + * after reading some bytes and also both of the allowed EOF behaviors. + * + * Implementations should not retain a reference to `p`. + */ readSync(p: Uint8Array): number | EOF; } export interface Writer { /** Writes `p.byteLength` bytes from `p` to the underlying data - * stream. It resolves to the number of bytes written from `p` (`0` <= `n` <= - * `p.byteLength`) and any error encountered that caused the write to stop - * early. `write()` must return a non-null error if it returns `n` < - * `p.byteLength`. write() must not modify the slice data, even temporarily. + * stream. It resolves with the number of bytes written from `p` (`0` <= `n` + * <= `p.byteLength`) or reject with the error encountered that caused the + * write to stop early. `write()` must reject with a non-null error if it + * returns `n` < `p.byteLength`. `write()` must not modify the slice data, + * even temporarily. * - * Implementations must not retain `p`. + * Implementations should not retain a reference to `p`. */ write(p: Uint8Array): Promise; } + export interface SyncWriter { + /** Writes `p.byteLength` bytes from `p` to the underlying data + * stream. It returns the number of bytes written from `p` (`0` <= `n` + * <= `p.byteLength`) and any error encountered that caused the write to + * stop early. `writeSync()` must throw a non-null error if it returns `n` < + * `p.byteLength`. `writeSync()` must not modify the slice data, even + * temporarily. + * + * Implementations should not retain a reference to `p`. + */ writeSync(p: Uint8Array): number; } + export interface Closer { close(): void; } + export interface Seeker { /** Seek sets the offset for the next `read()` or `write()` to offset, - * interpreted according to `whence`: `SeekStart` means relative to the start - * of the file, `SeekCurrent` means relative to the current offset, and - * `SeekEnd` means relative to the end. Seek returns the new offset relative - * to the start of the file and an error, if any. + * interpreted according to `whence`: `SeekStart` means relative to the + * start of the file, `SeekCurrent` means relative to the current offset, + * and `SeekEnd` means relative to the end. Seek returns the new offset + * relative to the start of the file and an error, if any. * * Seeking to an offset before the start of the file is an error. Seeking to - * any positive offset is legal, but the behavior of subsequent I/O operations - * on the underlying object is implementation-dependent. + * any positive offset is legal, but the behavior of subsequent I/O + * operations on the underlying object is implementation-dependent. */ seek(offset: number, whence: SeekMode): Promise; } + export interface SyncSeeker { + /** Seek sets the offset for the next `readSync()` or `writeSync()` to + * offset, interpreted according to `whence`: `SeekStart` means relative to + * the start of the file, `SeekCurrent` means relative to the current + * offset, and `SeekEnd` means relative to the end. Seek returns the new + * offset relative to the start of the file and an error, if any. + * + * Seeking to an offset before the start of the file is an error. Seeking to + * any positive offset is legal, but the behavior of subsequent I/O + * operations on the underlying object is implementation-dependent. + */ seekSync(offset: number, whence: SeekMode): void; } + export interface ReadCloser extends Reader, Closer {} export interface WriteCloser extends Writer, Closer {} export interface ReadSeeker extends Reader, Seeker {} export interface WriteSeeker extends Writer, Seeker {} export interface ReadWriteCloser extends Reader, Writer, Closer {} export interface ReadWriteSeeker extends Reader, Writer, Seeker {} - /** Copies from `src` to `dst` until either `EOF` is reached on `src` - * or an error occurs. It returns the number of bytes copied and the first - * error encountered while copying, if any. + + /** Copies from `src` to `dst` until either `EOF` is reached on `src` or an + * error occurs. It returns the number of bytes copied and the first error + * encountered while copying, if any. * * Because `copy()` is defined to read from `src` until `EOF`, it does not * treat an `EOF` from `read()` as an error to be reported. */ export function copy(dst: Writer, src: Reader): Promise; + /** Turns `r` into async iterator. * * for await (const chunk of toAsyncIterator(reader)) { - * console.log(chunk) + * console.log(chunk); * } */ export function toAsyncIterator(r: Reader): AsyncIterableIterator; // @url js/files.d.ts - /** Open a file and return an instance of the `File` object - * synchronously. + /** Open a file and return an instance of the `File` object synchronously. * - * const file = Deno.openSYNC("/foo/bar.txt", { read: true, write: true }); + * const file = Deno.openSync("/foo/bar.txt", { read: true, write: true }); * - * Requires allow-read or allow-write or both depending on mode. + * Requires `allow-read` and `allow-write` permissions depending on mode. */ export function openSync(filename: string, options?: OpenOptions): File; - /** Open a file and return an instance of the `File` object - * synchronously. + /** Open a file and return an instance of the `File` object synchronously. * * const file = Deno.openSync("/foo/bar.txt", "r"); * - * Requires allow-read or allow-write or both depending on mode. + * Requires `allow-read` and `allow-write` permissions depending on mode. */ export function openSync(filename: string, mode?: OpenMode): File; @@ -364,32 +436,33 @@ declare namespace Deno { * * const file = await Deno.open("/foo/bar.txt", { read: true, write: true }); * - * Requires allow-read or allow-write or both depending on mode. + * Requires `allow-read` and `allow-write` permissions depending on mode. */ export function open(filename: string, options?: OpenOptions): Promise; - /** Open a file and return an instance of the `File` object. + /** Open a file and resolves with an instance of `Deno.File`. * * const file = await Deno.open("/foo/bar.txt, "w+"); * - * Requires allow-read or allow-write or both depending on mode. + * Requires `allow-read` and `allow-write` permissions depending on mode. */ export function open(filename: string, mode?: OpenMode): Promise; /** Creates a file if none exists or truncates an existing file and returns - * an instance of the `File` object synchronously. + * an instance of `Deno.File`. * * const file = Deno.createSync("/foo/bar.txt"); * - * Requires allow-read and allow-write. + * Requires `allow-read` and `allow-write` permissions. */ export function createSync(filename: string): File; + /** Creates a file if none exists or truncates an existing file and returns - * an instance of the `File` object. + * an instance of `Deno.File`. * * const file = await Deno.create("/foo/bar.txt"); * - * Requires allow-read and allow-write. + * Requires `allow-read` and `allow-write` permissions. */ export function create(filename: string): Promise; @@ -483,194 +556,200 @@ declare namespace Deno { close(): void; } - /** An instance of `File` for stdin. */ + /** An instance of `Deno.File` for `stdin`. */ export const stdin: File; - /** An instance of `File` for stdout. */ + /** An instance of `Deno.File` for `stdout`. */ export const stdout: File; - /** An instance of `File` for stderr. */ + /** An instance of `Deno.File` for `stderr`. */ export const stderr: File; export interface OpenOptions { - /** Sets the option for read access. This option, when true, will indicate that the file should be read-able if opened. */ + /** Sets the option for read access. + * + * This option, when `true`, will indicate that the file should be readable + * if opened. */ read?: boolean; /** Sets the option for write access. - * This option, when true, will indicate that the file should be write-able if opened. - * If the file already exists, any write calls on it will overwrite its contents, without truncating it. - */ + * + * This option, when `true`, will indicate that the file should be + * writeable if opened. + * + * If the file already exists, any write calls on it will overwrite + * its contents, without truncating it. */ write?: boolean; - /* Sets the option for creating a new file. - * This option indicates whether a new file will be created if the file does not yet already exist. - * In order for the file to be created, write or append access must be used. - */ + /** Sets the option for creating a new file. + * + * This option indicates whether a new file will be created if the file does + * not yet already exist. + * + * In order for the file to be created, write or append access must be + * used. */ create?: 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 for truncate to work. - */ + * + * 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 for truncate to work. */ truncate?: boolean; - /**Sets the option for the append mode. - * This option, when true, means that writes will append to a file instead of overwriting previous contents. - * Note that setting { write: true, append: true } has the same effect as setting only { append: true }. - */ + /** Sets the option for the append mode. + * + * This option, when `true`, means that writes will append to a file instead + * of overwriting previous contents. + * + * Note that setting `{ write: true, append: true }` has the same effect as + * setting only `{ append: true }`. */ append?: boolean; /** Sets the option to always create a new file. - * This option indicates whether a new file will be created. No file is allowed to exist at the target location, also no (dangling) symlink. - * If { createNew: true } is set, create and truncate are ignored. - */ + * + * This option indicates whether a new file will be created. No file is + * allowed to exist at the target location, also no (dangling) symlink. + * + * If `{ createNew: true }` is set, `create` and `truncate` value are + * ignored. */ createNew?: boolean; } - export type OpenMode = - /** Read-only. Default. Starts at beginning of file. */ - | "r" - /** Read-write. Start at beginning of file. */ - | "r+" - /** Write-only. Opens and truncates existing file or creates new one for - * writing only. - */ - | "w" - /** Read-write. Opens and truncates existing file or creates new one for - * writing and reading. - */ - | "w+" - /** Write-only. Opens existing file or creates new one. Each write appends - * content to the end of file. - */ - | "a" - /** Read-write. Behaves like "a" and allows to read from file. */ - | "a+" - /** Write-only. Exclusive create - creates new file only if one doesn't exist - * already. - */ - | "x" - /** Read-write. Behaves like `x` and allows to read from file. */ - | "x+"; + /** A set of string literals which specify the open mode of a file. + * + * |Value |Description | + * |------|--------------------------------------------------------------------------------------------------| + * |`"r"` |Read-only. Default. Starts at beginning of file. | + * |`"r+"`|Read-write. Start at beginning of file. | + * |`"w"` |Write-only. Opens and truncates existing file or creates new one for writing only. | + * |`"w+"`|Read-write. Opens and truncates existing file or creates new one for writing and reading. | + * |`"a"` |Write-only. Opens existing file or creates new one. Each write appends content to the end of file.| + * |`"a+"`|Read-write. Behaves like `"a"` and allows to read from file. | + * |`"x"` |Write-only. Exclusive create - creates new file only if one doesn't exist already. | + * |`"x+"`|Read-write. Behaves like `x` and allows reading from file. | + */ + export type OpenMode = "r" | "r+" | "w" | "w+" | "a" | "a+" | "x" | "x+"; // @url js/tty.d.ts - /** UNSTABLE: newly added API + /** **UNSTABLE**: newly added API * - * Check if a given resource is TTY - */ + * Check if a given resource is TTY. */ export function isatty(rid: number): boolean; - /** UNSTABLE: newly added API + /** **UNSTABLE**: newly added API * - * Set TTY to be under raw mode or not. - */ + * Set TTY to be under raw mode or not. */ export function setRaw(rid: number, mode: boolean): void; // @url js/buffer.d.ts - /** A Buffer is a variable-sized buffer of bytes with read() and write() - * methods. Based on https://golang.org/pkg/bytes/#Buffer - */ + /** A variable-sized buffer of bytes with `read()` and `write()` methods. + * + * Based on [Go Buffer](https://golang.org/pkg/bytes/#Buffer). */ export class Buffer implements Reader, SyncReader, Writer, SyncWriter { private buf; private off; + private _tryGrowByReslice; + private _reslice; + private _grow; + constructor(ab?: ArrayBuffer); - /** bytes() returns a slice holding the unread portion of the buffer. + /** Returns a slice holding the unread portion of the buffer. + * * The slice is valid for use only until the next buffer modification (that - * is, only until the next call to a method like read(), write(), reset(), or - * truncate()). The slice aliases the buffer content at least until the next - * buffer modification, so immediate changes to the slice will affect the - * result of future reads. - */ + * is, only until the next call to a method like `read()`, `write()`, + * `reset()`, or `truncate()`). The slice aliases the buffer content at + * least until the next buffer modification, so immediate changes to the + * slice will affect the result of future reads. */ bytes(): Uint8Array; - /** toString() returns the contents of the unread portion of the buffer - * as a string. Warning - if multibyte characters are present when data is - * flowing through the buffer, this method may result in incorrect strings - * due to a character being split. - */ + /** Returns the contents of the unread portion of the buffer as a `string`. + * + * **Warning**: if multibyte characters are present when data is flowing + * through the buffer, this method may result in incorrect strings due to a + * character being split. */ toString(): string; - /** empty() returns whether the unread portion of the buffer is empty. */ + /** Returns whether the unread portion of the buffer is empty. */ empty(): boolean; - /** length is a getter that returns the number of bytes of the unread - * portion of the buffer - */ + /** A read only number of bytes of the unread portion of the buffer. */ readonly length: number; - /** Returns the capacity of the buffer's underlying byte slice, that is, - * the total space allocated for the buffer's data. - */ + /** The read only capacity of the buffer's underlying byte slice, that is, + * the total space allocated for the buffer's data. */ readonly capacity: number; - /** truncate() discards all but the first n unread bytes from the buffer but - * continues to use the same allocated storage. It throws if n is negative or - * greater than the length of the buffer. - */ + /** Discards all but the first `n` unread bytes from the buffer but + * continues to use the same allocated storage. It throws if `n` is + * negative or greater than the length of the buffer. */ truncate(n: number): void; - /** reset() resets the buffer to be empty, but it retains the underlying - * storage for use by future writes. reset() is the same as truncate(0) - */ + /** Resets the buffer to be empty, but it retains the underlying storage for + * use by future writes. `.reset()` is the same as `.truncate(0)`. */ reset(): void; - /** _tryGrowByReslice() is a version of grow for the fast-case - * where the internal buffer only needs to be resliced. It returns the index - * where bytes should be written and whether it succeeded. - * It returns -1 if a reslice was not needed. - */ - private _tryGrowByReslice; - private _reslice; - /** readSync() reads the next len(p) bytes from the buffer or until the buffer - * is drained. The return value n is the number of bytes read. If the - * buffer has no data to return, eof in the response will be true. - */ + /** Reads the next `p.length` bytes from the buffer or until the buffer is + * drained. Returns the number of bytes read. If the buffer has no data to + * return, the return is `Deno.EOF`. */ readSync(p: Uint8Array): number | EOF; + /** Reads the next `p.length` bytes from the buffer or until the buffer is + * drained. Resolves with the number of bytes read. If the buffer has no + * data to return, resolves with `Deno.EOF`. */ read(p: Uint8Array): Promise; writeSync(p: Uint8Array): number; write(p: Uint8Array): Promise; - /** _grow() grows the buffer to guarantee space for n more bytes. - * It returns the index where bytes should be written. - * If the buffer can't grow it will throw with Error. - */ - private _grow; - /** grow() grows the buffer's capacity, if necessary, to guarantee space for - * another n bytes. After grow(n), at least n bytes can be written to the - * buffer without another allocation. If n is negative, grow() will panic. If - * the buffer can't grow it will throw Error. - * Based on https://golang.org/pkg/bytes/#Buffer.Grow - */ + /** Grows the buffer's capacity, if necessary, to guarantee space for + * another `n` bytes. After `.grow(n)`, at least `n` bytes can be written to + * the buffer without another allocation. If `n` is negative, `.grow()` will + * throw. If the buffer can't grow it will throw an error. + * + * Based on Go Lang's + * [Buffer.Grow](https://golang.org/pkg/bytes/#Buffer.Grow). */ grow(n: number): void; - /** readFrom() reads data from r until EOF and appends it to the buffer, - * growing the buffer as needed. It returns the number of bytes read. If the - * buffer becomes too large, readFrom will panic with Error. - * Based on https://golang.org/pkg/bytes/#Buffer.ReadFrom - */ + /** Reads data from `r` until `Deno.EOF` and appends it to the buffer, + * growing the buffer as needed. It resolves with the number of bytes read. + * If the buffer becomes too large, `.readFrom()` will reject with an error. + * + * Based on Go Lang's + * [Buffer.ReadFrom](https://golang.org/pkg/bytes/#Buffer.ReadFrom). */ readFrom(r: Reader): Promise; - /** Sync version of `readFrom` - */ + /** Reads data from `r` until `Deno.EOF` and appends it to the buffer, + * growing the buffer as needed. It returns the number of bytes read. If the + * buffer becomes too large, `.readFromSync()` will throw an error. + * + * Based on Go Lang's + * [Buffer.ReadFrom](https://golang.org/pkg/bytes/#Buffer.ReadFrom). */ readFromSync(r: SyncReader): number; } - /** Read `r` until EOF and return the content as `Uint8Array` */ + /** Read `r` until `Deno.EOF` and resolves with the content as + * `Uint8Array`. */ export function readAll(r: Reader): Promise; - /** Read synchronously `r` until EOF and return the content as `Uint8Array` */ + /** Read `r` until `Deno.EOF` and returns the content as `Uint8Array`. */ export function readAllSync(r: SyncReader): Uint8Array; - /** Write all the content of `arr` to `w` */ + /** Write all the content of `arr` to `w`. */ export function writeAll(w: Writer, arr: Uint8Array): Promise; - /** Write synchronously all the content of `arr` to `w` */ + /** Write synchronously all the content of `arr` to `w`. */ export function writeAllSync(w: SyncWriter, arr: Uint8Array): void; export interface MkdirOption { + /** If set to `true`, nested directories will be created (also known as + * `mkdir -p`) */ recursive?: boolean; + /** Sets permission bits (before `umask`) on Linux/Mac OS and does nothing + * on Windows */ mode?: number; } /** Creates a new directory with the specified path synchronously. - * If `recursive` is set to true, nested directories will be created (also known - * as "mkdir -p"). - * `mode` sets permission bits (before umask) on UNIX and does nothing on - * Windows. + * + * If `recursive` is set to `true`, nested directories will be created (also + * known as `mkdir -p`). + * + * `mode` sets permission bits (before `umask`) on Linux/Mac OS and does + * nothing on Windows. * * Deno.mkdirSync("new_dir"); * Deno.mkdirSync("nested/directories", { recursive: true }); * - * Requires allow-write. + * Requires `allow-write` permission. */ export function mkdirSync(path: string, options?: MkdirOption): void; - /** Deprecated */ + /** @deprecated */ export function mkdirSync( path: string, recursive?: boolean, @@ -678,19 +757,21 @@ declare namespace Deno { ): void; /** Creates a new directory with the specified path. - * If `recursive` is set to true, nested directories will be created (also known - * as "mkdir -p"). - * `mode` sets permission bits (before umask) on UNIX and does nothing on - * Windows. + * + * If `recursive` is set to `true`, nested directories will be created (also + * known as `mkdir -p`). + * + * `mode` sets permission bits (before `umask`) on Linux/Mac OS and does + * nothing on Windows. * * await Deno.mkdir("new_dir"); * await Deno.mkdir("nested/directories", { recursive: true }); * - * Requires allow-write. + * Requires `allow-write` permission. */ export function mkdir(path: string, options?: MkdirOption): Promise; - /** Deprecated */ + /** @deprecated */ export function mkdir( path: string, recursive?: boolean, @@ -705,49 +786,73 @@ declare namespace Deno { suffix?: string; } - /** makeTempDirSync is the synchronous version of `makeTempDir`. + /** Creates a new temporary directory in the directory `dir`, its name + * beginning with `prefix` and ending with `suffix`. + * + * It returns the full path to the newly created directory. + * + * If `dir` is unspecified, it uses the default directory for temporary files. + * Multiple programs calling simultaneously will not choose the same + * directory. It is the caller's responsibility to remove the directory + * when no longer needed. * * const tempDirName0 = Deno.makeTempDirSync(); * const tempDirName1 = Deno.makeTempDirSync({ prefix: 'my_temp' }); * - * Requires allow-write. + * Requires `allow-write` permission. */ // TODO(ry) Doesn't check permissions. export function makeTempDirSync(options?: MakeTempOptions): string; - /** makeTempDir creates a new temporary directory in the directory `dir`, its - * name beginning with `prefix` and ending with `suffix`. - * It returns the full path to the newly created directory. - * If `dir` is unspecified, tempDir uses the default directory for temporary - * files. Multiple programs calling tempDir simultaneously will not choose the - * same directory. It is the caller's responsibility to remove the directory + /** Creates a new temporary directory in the directory `dir`, its name + * beginning with `prefix` and ending with `suffix`. + * + * It resolves with the full path to the newly created directory. + * + * If `dir` is unspecified, it uses the default directory for temporary files. + * Multiple programs calling simultaneously will not choose the same + * directory. It is the caller's responsibility to remove the directory * when no longer needed. * * const tempDirName0 = await Deno.makeTempDir(); * const tempDirName1 = await Deno.makeTempDir({ prefix: 'my_temp' }); * - * Requires allow-write. + * Requires `allow-write` permission. */ // TODO(ry) Doesn't check permissions. export function makeTempDir(options?: MakeTempOptions): Promise; - /** makeTempFileSync is the synchronous version of `makeTempFile`. + /** Creates a new temporary file in the directory `dir`, its name beginning + * with `prefix` and ending with `suffix`. + * + * It resolves with the full path to the newly created file. + * + * If `dir` is unspecified, it uses the default directory for temporary files. + * Multiple programs calling simultaneously will not choose the same + * directory. It is the caller's responsibility to remove the file when no + * longer needed. * * const tempFileName0 = Deno.makeTempFileSync(); * const tempFileName1 = Deno.makeTempFileSync({ prefix: 'my_temp' }); + * + * Requires `allow-write` permission. */ export function makeTempFileSync(options?: MakeTempOptions): string; - /** makeTempFile creates a new temporary file in the directory `dir`, its - * name beginning with `prefix` and ending with `suffix`. - * It returns the full path to the newly created file. - * If `dir` is unspecified, tempFile uses the default directory for temporary - * files. Multiple programs calling tempFile simultaneously will not choose the - * same directory. It is the caller's responsibility to remove the file - * when no longer needed. + /** Creates a new temporary file in the directory `dir`, its name beginning + * with `prefix` and ending with `suffix`. + * + * It resolves with the full path to the newly created file. + * + * If `dir` is unspecified, it uses the default directory for temporary files. + * Multiple programs calling simultaneously will not choose the same + * directory. It is the caller's responsibility to remove the file when no + * longer needed. * * const tempFileName0 = await Deno.makeTempFile(); * const tempFileName1 = await Deno.makeTempFile({ prefix: 'my_temp' }); + * + * Requires `allow-write` permission. */ export function makeTempFile(options?: MakeTempOptions): Promise; @@ -756,22 +861,21 @@ declare namespace Deno { * * Deno.chmodSync("/path/to/file", 0o666); * - * Needs allow-write - */ + * Requires `allow-write` permission. */ export function chmodSync(path: string, mode: number): void; /** Changes the permission of a specific file/directory of specified path. * * await Deno.chmod("/path/to/file", 0o666); * - * Needs allow-write + * Requires `allow-write` permission. */ export function chmod(path: string, mode: number): Promise; - /** - * Change owner of a regular file or directory synchronously. Unix only at the moment. + /** Change owner of a regular file or directory synchronously. Linux/Mac OS + * only at the moment. * - * Needs allow-write permission. + * Requires `allow-write` permission. * * @param path path to the file * @param uid user id of the new owner @@ -779,10 +883,10 @@ declare namespace Deno { */ export function chownSync(path: string, uid: number, gid: number): void; - /** - * Change owner of a regular file or directory asynchronously. Unix only at the moment. + /** Change owner of a regular file or directory asynchronously. Linux/Mac OS + * only at the moment. * - * Needs allow-write permission. + * Requires `allow-write` permission. * * @param path path to the file * @param uid user id of the new owner @@ -790,15 +894,15 @@ declare namespace Deno { */ export function chown(path: string, uid: number, gid: number): Promise; - /** UNSTABLE: needs investigation into high precision time. + /** **UNSTABLE**: needs investigation into high precision time. * * Synchronously changes the access and modification times of a file system - * object referenced by `filename`. Given times are either in seconds - * (Unix epoch time) or as `Date` objects. + * object referenced by `filename`. Given times are either in seconds (UNIX + * epoch time) or as `Date` objects. * * Deno.utimeSync("myfile.txt", 1556495550, new Date()); * - * Requires allow-write. + * Requires `allow-write` permission. */ export function utimeSync( filename: string, @@ -806,47 +910,46 @@ declare namespace Deno { mtime: number | Date ): void; - /** UNSTABLE: needs investigation into high precision time. + /** **UNSTABLE**: needs investigation into high precision time. * * Changes the access and modification times of a file system object - * referenced by `filename`. Given times are either in seconds - * (Unix epoch time) or as `Date` objects. + * referenced by `filename`. Given times are either in seconds (UNIX epoch + * time) or as `Date` objects. * * await Deno.utime("myfile.txt", 1556495550, new Date()); * - * Requires allow-write. - */ + * Requires `allow-write` permission. */ export function utime( filename: string, atime: number | Date, mtime: number | Date ): Promise; - /** UNSTABLE: rename to RemoveOptions */ + /** **UNSTABLE**: rename to RemoveOptions */ export interface RemoveOption { recursive?: boolean; } - /** Removes the named file or directory synchronously. Would throw - * error if permission denied, not found, or directory not empty if `recursive` - * set to false. - * `recursive` is set to false by default. + /** Removes the named file or directory synchronously. Would throw an error if + * permission denied, not found, or directory not empty if `recursive` set to + * `false`. + * + * `recursive` defaults to `false`. * * Deno.removeSync("/path/to/dir/or/file", {recursive: false}); * - * Requires allow-write permission. - */ - + * Requires `allow-write` permission. */ export function removeSync(path: string, options?: RemoveOption): void; + /** Removes the named file or directory. Would throw error if * permission denied, not found, or directory not empty if `recursive` set * to false. - * `recursive` is set to false by default. + * + * `recursive` defaults to `false`. * * await Deno.remove("/path/to/dir/or/file", {recursive: false}); * - * Requires allow-write permission. - */ + * Requires `allow-write` permission. */ export function remove(path: string, options?: RemoveOption): Promise; /** Synchronously renames (moves) `oldpath` to `newpath`. If `newpath` already @@ -856,8 +959,7 @@ declare namespace Deno { * * Deno.renameSync("old/path", "new/path"); * - * Requires allow-read and allow-write. - */ + * Requires `allow-read` and `allow-write` permissions. */ export function renameSync(oldpath: string, newpath: string): void; /** Renames (moves) `oldpath` to `newpath`. If `newpath` already exists and is @@ -866,263 +968,237 @@ declare namespace Deno { * * await Deno.rename("old/path", "new/path"); * - * Requires allow-read and allow-write. - */ + * Requires `allow-read` and `allow-write`. */ export function rename(oldpath: string, newpath: string): Promise; // @url js/read_file.d.ts - /** Read the entire contents of a file synchronously. + /** Reads and returns the entire contents of a file. * * const decoder = new TextDecoder("utf-8"); * const data = Deno.readFileSync("hello.txt"); * console.log(decoder.decode(data)); * - * Requires allow-read. - */ + * Requires `allow-read` permission. */ export function readFileSync(filename: string): Uint8Array; - /** Read the entire contents of a file. + /** Reads and resolves with the entire contents of a file. * * const decoder = new TextDecoder("utf-8"); * const data = await Deno.readFile("hello.txt"); * console.log(decoder.decode(data)); * - * Requires allow-read. - */ + * Requires `allow-read` permission. */ export function readFile(filename: string): Promise; - /** UNSTABLE: 'len' maybe should be 'length' or 'size'. + /** **UNSTABLE**: `.len` maybe should be `.length` or `.size`. * - * A FileInfo describes a file and is returned by `stat`, `lstat`, - * `statSync`, `lstatSync`. + * A FileInfo describes a file and is returned by `stat`, `lstat`, `statSync`, + * `lstatSync`. */ export interface FileInfo { - /** UNSTABLE: 'len' maybe should be 'length' or 'size'. + /** **UNSTABLE**: `.len` maybe should be `.length` or `.size`. * * The size of the file, in bytes. */ len: number; /** The last modification time of the file. This corresponds to the `mtime` - * field from `stat` on Unix and `ftLastWriteTime` on Windows. This may not - * be available on all platforms. - */ + * field from `stat` on Linux/Mac OS and `ftLastWriteTime` on Windows. This + * may not be available on all platforms. */ modified: number | null; - /** The last access time of the file. This corresponds to the `atime` - * field from `stat` on Unix and `ftLastAccessTime` on Windows. This may not - * be available on all platforms. - */ + /** The last access time of the file. This corresponds to the `atime` field + * from `stat` on Linux/Mac OS and `ftLastAccessTime` on Windows. This may + * not be available on all platforms. */ accessed: number | null; /** The last access time of the file. This corresponds to the `birthtime` - * field from `stat` on Unix and `ftCreationTime` on Windows. This may not - * be available on all platforms. - */ + * field from `stat` on Linux/Mac OS and `ftCreationTime` on Windows. This + * may not be available on all platforms. */ created: number | null; /** The file or directory name. */ name: string | null; - /** ID of the device containing the file. Unix only. */ + /** ID of the device containing the file. + * + * _Linux/Mac OS only._ */ dev: number | null; - /** Inode number. Unix only. */ + /** Inode number. + * + * _Linux/Mac OS only._ */ ino: number | null; - /** UNSTABLE: Match behavior with Go on windows for mode. + /** **UNSTABLE**: Match behavior with Go on Windows for `mode`. * - * The underlying raw st_mode bits that contain the standard Unix permissions - * for this file/directory. - */ + * The underlying raw `st_mod`e bits that contain the standard Linux/Mac OS + * permissions for this file/directory. */ mode: number | null; - /** Number of hard links pointing to this file. Unix only. */ + /** Number of hard links pointing to this file. + * + * _Linux/Mac OS only._ */ nlink: number | null; - /** User ID of the owner of this file. Unix only. */ + /** User ID of the owner of this file. + * + * _Linux/Mac OS only._ */ uid: number | null; - /** User ID of the owner of this file. Unix only. */ + /** User ID of the owner of this file. + * + * _Linux/Mac OS only._ */ gid: number | null; - /** Device ID of this file. Unix only. */ + /** Device ID of this file. + * + * _Linux/Mac OS only._ */ rdev: number | null; - /** Blocksize for filesystem I/O. Unix only. */ + /** Blocksize for filesystem I/O. + * + * _Linux/Mac OS only._ */ blksize: number | null; - /** Number of blocks allocated to the file, in 512-byte units. Unix only. */ + /** Number of blocks allocated to the file, in 512-byte units. + * + * _Linux/Mac OS only._ */ blocks: number | null; /** Returns whether this is info for a regular file. This result is mutually - * exclusive to `FileInfo.isDirectory` and `FileInfo.isSymlink`. - */ + * exclusive to `FileInfo.isDirectory` and `FileInfo.isSymlink`. */ isFile(): boolean; /** Returns whether this is info for a regular directory. This result is - * mutually exclusive to `FileInfo.isFile` and `FileInfo.isSymlink`. - */ + * mutually exclusive to `FileInfo.isFile` and `FileInfo.isSymlink`. */ isDirectory(): boolean; /** Returns whether this is info for a symlink. This result is - * mutually exclusive to `FileInfo.isFile` and `FileInfo.isDirectory`. - */ + * mutually exclusive to `FileInfo.isFile` and `FileInfo.isDirectory`. */ isSymlink(): boolean; } // @url js/realpath.d.ts - /** Returns absolute normalized path with symbolic links resolved - * synchronously. + /** Returns absolute normalized path with, symbolic links resolved. * * const realPath = Deno.realpathSync("./some/path"); * - * Requires allow-read. - */ + * Requires `allow-read` permission. */ export function realpathSync(path: string): string; - /** Returns absolute normalized path with symbolic links resolved. + /** Resolves with the absolute normalized path, with symbolic links resolved. * * const realPath = await Deno.realpath("./some/path"); * - * Requires allow-read. - */ + * Requires `allow-read` permission. */ export function realpath(path: string): Promise; - /** UNSTABLE: Unstable rename to readdirSync. + /** **UNSTABLE**: Possibly rename to `readdirSync()`. * - * Reads the directory given by path and returns a list of file info - * synchronously. + * Reads the directory given by path and returns an array of `Deno.FileInfo`. * * const files = Deno.readDirSync("/"); * - * Requires allow-read. - */ + * Requires `allow-read` permission. */ export function readDirSync(path: string): FileInfo[]; - /** UNSTABLE: Unstable rename to readdir. Maybe need to return AsyncIterable. + /** UNSTABLE: Possibly rename to `.readdir()`. Maybe need to return an + * `AsyncIterable`. * - * Reads the directory given by path and returns a list of file info. + * Reads the directory given by path and resolves with an array of + * `Deno.FileInfo`. * * const files = await Deno.readDir("/"); * - * Requires allow-read. + * Requires `allow-read` permission. */ export function readDir(path: string): Promise; - /** Copies the contents of a file to another by name synchronously. + /** Copies the contents of a file to another by name. + * * Creates a new file if target does not exists, and if target exists, * overwrites original content of the target file. * - * It would also copy the permission of the original file - * to the destination. + * It will also copy the permissions of the original file to the destination. * * Deno.copyFileSync("from.txt", "to.txt"); * - * Needs allow-read and allow-write permissions. - */ + * Requires `allow-read` and `allow-write` permissions. */ export function copyFileSync(from: string, to: string): void; + /** Copies the contents of a file to another by name. * * Creates a new file if target does not exists, and if target exists, * overwrites original content of the target file. * - * It would also copy the permission of the original file - * to the destination. + * It will also copy the permissions of the original file to the destination. * * await Deno.copyFile("from.txt", "to.txt"); * - * Needs allow-read and allow-write permissions. - */ + * Requires `allow-read` and `allow-write` permissions. */ export function copyFile(from: string, to: string): Promise; // @url js/read_link.d.ts - /** Returns the destination of the named symbolic link synchronously. + /** Returns the destination of the named symbolic link. * * const targetPath = Deno.readlinkSync("symlink/path"); * - * Requires allow-read. - */ + * Requires `allow-read` permission. */ export function readlinkSync(name: string): string; - /** Returns the destination of the named symbolic link. + /** Resolves with the destination of the named symbolic link. * * const targetPath = await Deno.readlink("symlink/path"); * - * Requires allow-read. - */ + * Requires `allow-read` permission. */ export function readlink(name: string): Promise; - interface StatResponse { - isFile: boolean; - isSymlink: boolean; - len: number; - modified: number; - accessed: number; - created: number; - name: string | null; - dev: number; - ino: number; - mode: number; - nlink: number; - uid: number; - gid: number; - rdev: number; - blksize: number; - blocks: number; - } - /** Queries the file system for information on the path provided. If the given - * path is a symlink information about the symlink will be returned. + /** Resolves with the `FileInfo` for the `filename` provided. If the given + * `filename` is a symlink, information about the symlink will be returned. * * const fileInfo = await Deno.lstat("hello.txt"); * assert(fileInfo.isFile()); * - * Requires allow-read permission. - */ + * Requires `allow-read` permission. */ export function lstat(filename: string): Promise; - /** Queries the file system for information on the path provided synchronously. - * If the given path is a symlink information about the symlink will be - * returned. + /** Returns the `FileInfo` for the `filename` provided. If the given + * `filename` is a symlink, information about the symlink will be returned. * * const fileInfo = Deno.lstatSync("hello.txt"); * assert(fileInfo.isFile()); * - * Requires allow-read permission. - */ + * Requires `allow-read` permission. */ export function lstatSync(filename: string): FileInfo; - /** Queries the file system for information on the path provided. `stat` Will - * always follow symlinks. + /** Resolves with the `FileInfo` for the `filename` provided. Will always + * resolve and follow symlinks. * * const fileInfo = await Deno.stat("hello.txt"); * assert(fileInfo.isFile()); * - * Requires allow-read permission. - */ + * Requires `allow-read` permission. */ export function stat(filename: string): Promise; - /** Queries the file system for information on the path provided synchronously. - * `statSync` Will always follow symlinks. + + /** Returns the `FileInfo` for the `filename` provided. Will always resolve + * and follow symlinks. * * const fileInfo = Deno.statSync("hello.txt"); * assert(fileInfo.isFile()); * - * Requires allow-read permission. - */ + * Requires `allow-read` permission. */ export function statSync(filename: string): FileInfo; - /** Synchronously creates `newname` as a hard link to `oldname`. + /** Creates `newname` as a hard link to `oldname`. * * Deno.linkSync("old/name", "new/name"); * - * Requires allow-read and allow-write permissions. - */ + * Requires `allow-read` and `allow-write` permissions. */ export function linkSync(oldname: string, newname: string): void; /** Creates `newname` as a hard link to `oldname`. * * await Deno.link("old/name", "new/name"); * - * Requires allow-read and allow-write permissions. - */ + * Requires `allow-read` and `allow-write` permissions. */ export function link(oldname: string, newname: string): Promise; - /** UNSTABLE type argument may be changed to "dir" | "file" + /** **UNSTABLE**: `type` argument type may be changed to `"dir" | "file"`. * - * Synchronously creates `newname` as a symbolic link to `oldname`. The type - * argument can be set to `dir` or `file` and is only available on Windows - * (ignored on other platforms). + * Creates `newname` as a symbolic link to `oldname`. The type argument can be + * set to `dir` or `file`. Is only available on Windows and ignored on other + * platforms. * * Deno.symlinkSync("old/name", "new/name"); * - * Requires allow-read and allow-write permissions. - */ + * Requires `allow-read` and `allow-write` permissions. */ export function symlinkSync( oldname: string, newname: string, @@ -1132,37 +1208,35 @@ declare namespace Deno { /** UNSTABLE type argument may be changed to "dir" | "file" * * Creates `newname` as a symbolic link to `oldname`. The type argument can be - * set to `dir` or `file` and is only available on Windows (ignored on other - * platforms). + * set to `dir` or `file`. Is only available on Windows and ignored on other + * platforms. * * await Deno.symlink("old/name", "new/name"); * - * Requires allow-read and allow-write permissions. - */ + * Requires `allow-read` and `allow-write` permissions. */ export function symlink( oldname: string, newname: string, type?: string ): Promise; - /** Options for writing to a file. - * `perm` would change the file's permission if set. - * `create` decides if the file should be created if not exists (default: true) - * `append` decides if the file should be appended (default: false) - */ + /** Options for writing to a file. */ export interface WriteFileOptions { + /** Change the file's permissions. */ perm?: number; + /** Create the file if it does not exist. Defaults to `true`. */ create?: boolean; + /** Append to the file. Defaults to `false`. */ append?: boolean; } - /** Write a new file, with given filename and data synchronously. + /** Write a new file, with given `filename` and `data`. * * const encoder = new TextEncoder(); * const data = encoder.encode("Hello world\n"); * Deno.writeFileSync("hello.txt", data); * - * Requires allow-write and allow-read if create is false. + * Requires `allow-write` and `allow-read` permissions if create is `false`. */ export function writeFileSync( filename: string, @@ -1170,13 +1244,13 @@ declare namespace Deno { options?: WriteFileOptions ): void; - /** Write a new file, with given filename and data. + /** Write a new file, with given `filename` and `data`. * * const encoder = new TextEncoder(); * const data = encoder.encode("Hello world\n"); * await Deno.writeFile("hello.txt", data); * - * Requires allow-write and allow-read if create is false. + * Requires `allow-write` and `allow-read` permissions if create is `false`. */ export function writeFile( filename: string, @@ -1184,7 +1258,7 @@ declare namespace Deno { options?: WriteFileOptions ): Promise; - /** UNSTABLE: Should not have same name as window.location type. */ + /** **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`. */ @@ -1195,16 +1269,16 @@ declare namespace Deno { column: number; } - /** UNSTABLE: new API, not yet vetted. + /** UNSTABLE: new API, yet to be vetted. * - * Given a current location in a module, lookup the source location and - * return it. + * 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. + * 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. * * **Note:** `line` and `column` are 1 indexed, which matches display * expectations, but is not typical of most index numbers in Deno. @@ -1221,70 +1295,33 @@ declare namespace Deno { */ export function applySourceMap(location: Location): Location; - /* eslint-disable @typescript-eslint/no-unused-vars */ - namespace errors { - class NotFound extends Error { - constructor(msg: string); - } - class PermissionDenied extends Error { - constructor(msg: string); - } - class ConnectionRefused extends Error { - constructor(msg: string); - } - class ConnectionReset extends Error { - constructor(msg: string); - } - class ConnectionAborted extends Error { - constructor(msg: string); - } - class NotConnected extends Error { - constructor(msg: string); - } - class AddrInUse extends Error { - constructor(msg: string); - } - class AddrNotAvailable extends Error { - constructor(msg: string); - } - class BrokenPipe extends Error { - constructor(msg: string); - } - class AlreadyExists extends Error { - constructor(msg: string); - } - class InvalidData extends Error { - constructor(msg: string); - } - class TimedOut extends Error { - constructor(msg: string); - } - class Interrupted extends Error { - constructor(msg: string); - } - class WriteZero extends Error { - constructor(msg: string); - } - class Other extends Error { - constructor(msg: string); - } - class UnexpectedEof extends Error { - constructor(msg: string); - } - class BadResource extends Error { - constructor(msg: string); - } - class Http extends Error { - constructor(msg: string); - } - } - /* eslint-enable @typescript-eslint/no-unused-vars */ + /** A set of error constructors that are raised by Deno APIs. */ + export const errors: { + NotFound: ErrorConstructor; + PermissionDenied: ErrorConstructor; + ConnectionRefused: ErrorConstructor; + ConnectionReset: ErrorConstructor; + ConnectionAborted: ErrorConstructor; + NotConnected: ErrorConstructor; + AddrInUse: ErrorConstructor; + AddrNotAvailable: ErrorConstructor; + BrokenPipe: ErrorConstructor; + AlreadyExists: ErrorConstructor; + InvalidData: ErrorConstructor; + TimedOut: ErrorConstructor; + Interrupted: ErrorConstructor; + WriteZero: ErrorConstructor; + Other: ErrorConstructor; + UnexpectedEof: ErrorConstructor; + BadResource: ErrorConstructor; + Http: ErrorConstructor; + }; - /** UNSTABLE: potentially want names to overlap more with browser. + /** **UNSTABLE**: potentially want names to overlap more with browser. * - * Permissions as granted by the caller - * See: https://w3c.github.io/permissions/#permission-registry - */ + * The permissions as granted by the caller. + * + * See: https://w3c.github.io/permissions/#permission-registry */ export type PermissionName = | "run" | "read" @@ -1293,29 +1330,42 @@ declare namespace Deno { | "env" | "plugin" | "hrtime"; - /** https://w3c.github.io/permissions/#status-of-a-permission */ + + /** The current status of the permission. + * + * See: https://w3c.github.io/permissions/#status-of-a-permission */ export type PermissionState = "granted" | "denied" | "prompt"; + interface RunPermissionDescriptor { name: "run"; } + interface ReadWritePermissionDescriptor { name: "read" | "write"; path?: string; } + interface NetPermissionDescriptor { name: "net"; url?: string; } + interface EnvPermissionDescriptor { name: "env"; } + interface PluginPermissionDescriptor { name: "plugin"; } + interface HrtimePermissionDescriptor { name: "hrtime"; } - /** See: https://w3c.github.io/permissions/#permission-descriptor */ + + /** Permission descriptors which define a permission which can be queried, + * requested, or revoked. + * + * See: https://w3c.github.io/permissions/#permission-descriptor */ type PermissionDescriptor = | RunPermissionDescriptor | ReadWritePermissionDescriptor @@ -1325,19 +1375,24 @@ declare namespace Deno { | HrtimePermissionDescriptor; export class Permissions { - /** Queries the permission. + /** Resolves with the current status of a permission. + * * const status = await Deno.permissions.query({ name: "read", path: "/etc" }); * if (status.state === "granted") { * data = await Deno.readFile("/etc/passwd"); * } */ - query(d: PermissionDescriptor): Promise; - /** Revokes the permission. + query(desc: PermissionDescriptor): Promise; + + /** Revokes a permission, and resolves with the state of the permission. + * * const status = await Deno.permissions.revoke({ name: "run" }); * assert(status.state !== "granted") */ - revoke(d: PermissionDescriptor): Promise; - /** Requests the permission. + revoke(desc: PermissionDescriptor): Promise; + + /** Requests the permission, and resolves with the state of the permission. + * * const status = await Deno.permissions.request({ name: "env" }); * if (status.state === "granted") { * console.log(Deno.homeDir()); @@ -1347,31 +1402,28 @@ declare namespace Deno { */ request(desc: PermissionDescriptor): Promise; } - /** UNSTABLE: maybe move to navigator.permissions to match web API. */ + + /** **UNSTABLE**: maybe move to `navigator.permissions` to match web API. */ export const permissions: Permissions; - /** https://w3c.github.io/permissions/#permissionstatus */ + /** see: https://w3c.github.io/permissions/#permissionstatus */ export class PermissionStatus { state: PermissionState; constructor(state: PermissionState); } - /** Truncates or extends the specified file synchronously, updating the size of - * this file to become size. + /** Truncates or extends the specified `name`, to reach the specified `len`. * * Deno.truncateSync("hello.txt", 10); * - * Requires allow-write. - */ + * Requires `allow-write` permission. */ export function truncateSync(name: string, len?: number): void; - /** - * Truncates or extends the specified file, updating the size of this file to - * become size. + + /** Truncates or extends the specified `name`, to reach the specified `len`. * * await Deno.truncate("hello.txt", 10); * - * Requires allow-write. - */ + * Requires `allow-write` permission. */ export function truncate(name: string, len?: number): Promise; export interface AsyncHandler { @@ -1392,16 +1444,16 @@ declare namespace Deno { }; } - /** UNSTABLE: New API, not yet vetted. + /** **UNSTABLE**: new API, yet to be vetted. * * Open and initalize a plugin. - * Requires the `--allow-plugin` flag. * * const plugin = Deno.openPlugin("./path/to/some/plugin.so"); * const some_op = plugin.ops.some_op; * const response = some_op.dispatch(new Uint8Array([1,2,3,4])); * console.log(`Response from plugin ${response}`); - */ + * + * Requires the `allow-plugin` permission. */ export function openPlugin(filename: string): Plugin; export type Transport = "tcp" | "udp"; @@ -1413,22 +1465,24 @@ declare namespace Deno { } export interface UDPAddr { + port: number; transport?: Transport; hostname?: string; - port: number; } - /** UNSTABLE: Maybe remove ShutdownMode entirely. */ + /** **UNSTABLE**: Maybe remove `ShutdownMode` entirely. + * + * Corresponds to `SHUT_RD`, `SHUT_WR`, `SHUT_RDWR` on POSIX-like systems. + * + * See: http://man7.org/linux/man-pages/man2/shutdown.2.html */ export enum ShutdownMode { - // See http://man7.org/linux/man-pages/man2/shutdown.2.html - // Corresponding to SHUT_RD, SHUT_WR, SHUT_RDWR Read = 0, Write, ReadWrite // TODO(ry) panics on ReadWrite. } - /** UNSTABLE: Maybe should remove how parameter maybe remove ShutdownMode - * entirely. + /** **UNSTABLE**: Maybe should remove `how` parameter maybe remove + * `ShutdownMode` entirely. * * Shutdown socket send and receive operations. * @@ -1440,166 +1494,169 @@ declare namespace Deno { */ export function shutdown(rid: number, how: ShutdownMode): void; - /** UNSTABLE: new API - * Waits for the next message to the passed rid and writes it on the passed buffer. - * Returns the number of bytes written and the remote address. - */ + /** **UNSTABLE**: new API, yet to be vetted. + * + * Waits for the next message to the passed `rid` and writes it on the passed + * `Uint8Array`. + * + * Resolves with the number of bytes written and the remote address. */ export function recvfrom(rid: number, p: Uint8Array): Promise<[number, Addr]>; - /** UNSTABLE: new API - * A socket is a generic transport listener for message-oriented protocols - */ + /** **UNSTABLE**: new API, yet to be vetted. + * + * A generic transport listener for message-oriented protocols. */ export interface UDPConn extends AsyncIterator<[Uint8Array, Addr]> { - /** UNSTABLE: new API - * Waits for and resolves to the next message to the `Socket`. */ + /** **UNSTABLE**: new API, yet to be vetted. + * + * Waits for and resolves to the next message to the `UDPConn`. */ receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>; - - /** UNSTABLE: new API + /** UNSTABLE: new API, yet to be vetted. + * * Sends a message to the target. */ send(p: Uint8Array, addr: UDPAddr): Promise; - - /** UNSTABLE: new API + /** UNSTABLE: new API, yet to be vetted. + * * Close closes the socket. Any pending message promises will be rejected - * with errors. - */ + * with errors. */ close(): void; - - /** Return the address of the `Socket`. */ - addr: Addr; - + /** Return the address of the `UDPConn`. */ + readonly addr: Addr; [Symbol.asyncIterator](): AsyncIterator<[Uint8Array, Addr]>; } - /** A Listener is a generic network listener for stream-oriented protocols. */ + /** A generic network listener for stream-oriented protocols. */ export interface Listener extends AsyncIterator { /** Waits for and resolves to the next connection to the `Listener`. */ accept(): Promise; /** Close closes the listener. Any pending accept promises will be rejected - * with errors. - */ + * with errors. */ close(): void; /** Return the address of the `Listener`. */ - addr: Addr; + readonly addr: Addr; [Symbol.asyncIterator](): AsyncIterator; } export interface Conn extends Reader, Writer, Closer { - /** - * The local address of the connection. - */ - localAddr: Addr; - /** - * The remote address of the connection. - */ - remoteAddr: Addr; + /** The local address of the connection. */ + readonly localAddr: Addr; + /** The remote address of the connection. */ + readonly remoteAddr: Addr; /** The resource ID of the connection. */ - rid: number; + readonly rid: number; /** Shuts down (`shutdown(2)`) the reading side of the TCP connection. Most - * callers should just use `close()`. - */ + * callers should just use `close()`. */ closeRead(): void; /** Shuts down (`shutdown(2)`) the writing side of the TCP connection. Most - * callers should just use `close()`. - */ + * callers should just use `close()`. */ closeWrite(): void; } export interface ListenOptions { + /** The port to listen on. */ port: number; + /** A literal IP address or host name that can be resolved to an IP address. + * If not specified, defaults to `0.0.0.0`. */ hostname?: string; + /** Either `"tcp"` or `"udp"`. Defaults to `"tcp"`. + * + * In the future: `"tcp4"`, `"tcp6"`, `"udp4"`, `"udp6"`, `"ip"`, `"ip4"`, + * `"ip6"`, `"unix"`, `"unixgram"`, and `"unixpacket"`. */ transport?: Transport; } - /** UNSTABLE: new API + /** **UNSTABLE**: new API * * Listen announces on the local transport address. * - * Requires the allow-net permission. - * - * @param options - * @param options.port The port to connect to. (Required.) - * @param options.hostname A literal IP address or host name that can be - * resolved to an IP address. If not specified, defaults to 0.0.0.0 - * @param options.transport Defaults to "tcp". Later we plan to add "tcp4", - * "tcp6", "udp", "udp4", "udp6", "ip", "ip4", "ip6", "unix", "unixgram" and - * "unixpacket". - * - * Examples: + * Deno.listen({ port: 80 }) + * Deno.listen({ hostname: "192.0.2.1", port: 80 }) + * Deno.listen({ hostname: "[2001:db8::1]", port: 80 }); + * Deno.listen({ hostname: "golang.org", port: 80, transport: "tcp" }); * - * listen({ port: 80 }) - * listen({ hostname: "192.0.2.1", port: 80 }) - * listen({ hostname: "[2001:db8::1]", port: 80 }); - * listen({ hostname: "golang.org", port: 80, transport: "tcp" }) - */ + * Requires `allow-net` permission. */ export function listen( options: ListenOptions & { transport?: "tcp" } ): Listener; + /** **UNSTABLE**: new API + * + * Listen announces on the local transport address. + * + * Deno.listen({ port: 80 }) + * Deno.listen({ hostname: "192.0.2.1", port: 80 }) + * Deno.listen({ hostname: "[2001:db8::1]", port: 80 }); + * Deno.listen({ hostname: "golang.org", port: 80, transport: "tcp" }); + * + * Requires `allow-net` permission. */ export function listen( options: ListenOptions & { transport: "udp" } ): UDPConn; + /** **UNSTABLE**: new API + * + * Listen announces on the local transport address. + * + * Deno.listen({ port: 80 }) + * Deno.listen({ hostname: "192.0.2.1", port: 80 }) + * Deno.listen({ hostname: "[2001:db8::1]", port: 80 }); + * Deno.listen({ hostname: "golang.org", port: 80, transport: "tcp" }); + * + * Requires `allow-net` permission. */ export function listen(options: ListenOptions): Listener | UDPConn; - export interface ListenTLSOptions { - port: number; - hostname?: string; - transport?: Transport; + export interface ListenTLSOptions extends ListenOptions { + /** Server certificate file. */ certFile: string; + /** Server public key file. */ keyFile: string; } - /** Listen announces on the local transport address over TLS (transport layer security). - * - * @param options - * @param options.port The port to connect to. (Required.) - * @param options.hostname A literal IP address or host name that can be - * resolved to an IP address. If not specified, defaults to 0.0.0.0 - * @param options.certFile Server certificate file - * @param options.keyFile Server public key file + /** Listen announces on the local transport address over TLS (transport layer + * security). * - * Examples: + * Deno.listenTLS({ port: 443, certFile: "./my_server.crt", keyFile: "./my_server.key" }); * - * Deno.listenTLS({ port: 443, certFile: "./my_server.crt", keyFile: "./my_server.key" }) - */ + * Requires `allow-net` permission. */ export function listenTLS(options: ListenTLSOptions): Listener; export interface ConnectOptions { + /** The port to connect to. */ port: number; + /** A literal IP address or host name that can be resolved to an IP address. + * If not specified, defaults to `127.0.0.1`. */ hostname?: string; + /** Either `"tcp"` or `"udp"`. Defaults to `"tcp"`. + * + * In the future: `"tcp4"`, `"tcp6"`, `"udp4"`, `"udp6"`, `"ip"`, `"ip4"`, + * `"ip6"`, `"unix"`, `"unixgram"`, and `"unixpacket"`. */ transport?: Transport; } /** * Connects to the address on the named transport. * - * @param options - * @param options.port The port to connect to. (Required.) - * @param options.hostname A literal IP address or host name that can be - * resolved to an IP address. If not specified, defaults to 127.0.0.1 - * @param options.transport Defaults to "tcp". Later we plan to add "tcp4", - * "tcp6", "udp", "udp4", "udp6", "ip", "ip4", "ip6", "unix", "unixgram" and - * "unixpacket". - * - * Examples: + * 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" }) * - * connect({ port: 80 }) - * connect({ hostname: "192.0.2.1", port: 80 }) - * connect({ hostname: "[2001:db8::1]", port: 80 }); - * connect({ hostname: "golang.org", port: 80, transport: "tcp" }) - */ + * Requires `allow-net` permission. */ export function connect(options: ConnectOptions): Promise; export interface ConnectTLSOptions { + /** The port to connect to. */ port: number; + /** A literal IP address or host name that can be resolved to an IP address. + * If not specified, defaults to `127.0.0.1`. */ hostname?: string; + /** Server certificate file. */ certFile?: string; } - /** - * Establishes a secure connection over TLS (transport layer security). - */ + /** Establishes a secure connection over TLS (transport layer security). + * + * Requires `allow-net` permission. */ export function connectTLS(options: ConnectTLSOptions): Promise; - /** UNSTABLE: not sure if broken or not */ + /** **UNSTABLE**: not sure if broken or not */ export interface Metrics { opsDispatched: number; opsCompleted: number; @@ -1608,7 +1665,7 @@ declare namespace Deno { bytesReceived: number; } - /** UNSTABLE: potentially broken. + /** **UNSTABLE**: potentially broken. * * Receive metrics from the privileged side of Deno. * @@ -1625,28 +1682,26 @@ declare namespace Deno { */ export function metrics(): Metrics; - /** UNSTABLE: reconsider representation. */ + /** **UNSTABLE**: reconsider representation. */ interface ResourceMap { [rid: number]: string; } - /** UNSTABLE: reconsider return type. + /** **UNSTABLE**: reconsider return type. * * Returns a map of open _file like_ resource ids along with their string - * representation. - */ + * representations. */ export function resources(): ResourceMap; - /** UNSTABLE: new API. Needs docs. */ + /** **UNSTABLE**: new API. Needs docs. */ export interface FsEvent { kind: "any" | "access" | "create" | "modify" | "remove"; paths: string[]; } - /** UNSTABLE: new API. Needs docs. + /** **UNSTABLE**: new API. Needs docs. * - * recursive option is true by default. - */ + * Recursive option is `true` by default. */ export function fsEvents( paths: string | string[], options?: { recursive: boolean } @@ -1654,48 +1709,50 @@ declare namespace Deno { /** How to handle subprocess stdio. * - * "inherit" The default if unspecified. The child inherits from the + * `"inherit"` The default if unspecified. The child inherits from the * corresponding parent descriptor. * - * "piped" A new pipe should be arranged to connect the parent and child - * subprocesses. + * `"piped"` A new pipe should be arranged to connect the parent and child + * sub-processes. * - * "null" This stream will be ignored. This is the equivalent of attaching the - * stream to /dev/null. - */ + * `"null"` This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. */ type ProcessStdio = "inherit" | "piped" | "null"; - /** UNSTABLE: the signo parameter maybe shouldn't be number. + /** **UNSTABLE**: the `signo` argument maybe shouldn't be number. Should throw + * on Windows instead of silently succeeding. * - * Send a signal to process under given PID. Unix only at this moment. - * If pid is negative, the signal will be sent to the process group identified - * by -pid. + * Send a signal to process under given `pid`. Linux/Mac OS only currently. * - * Requires the `--allow-run` flag. + * If `pid` is negative, the signal will be sent to the process group + * identified by `pid`. * - * Currently no-op on Windows. TODO Should throw on windows instead of silently succeeding. - */ + * Currently no-op on Windows. + * + * Requires `allow-run` permission. */ export function kill(pid: number, signo: number): void; - /** UNSTABLE: There are some issues to work out with respect to when and how - * the process should be closed. - */ + /** **UNSTABLE**: There are some issues to work out with respect to when and + * how the process should be closed. */ export class Process { readonly rid: number; readonly pid: number; readonly stdin?: WriteCloser; readonly stdout?: ReadCloser; readonly stderr?: ReadCloser; + /** Resolves with the current status of the process. */ status(): Promise; - /** Buffer the stdout and return it as Uint8Array after EOF. - * You must set stdout to "piped" when creating the process. - * This calls close() on stdout after its done. - */ + /** Buffer the stdout and return it as `Uint8Array` after `Deno.EOF`. + * + * You must set stdout to `"piped"` when creating the process. + * + * This calls `close()` on stdout after its done. */ output(): Promise; - /** Buffer the stderr and return it as Uint8Array after EOF. - * You must set stderr to "piped" when creating the process. - * This calls close() on stderr after its done. - */ + /** Buffer the stderr and return it as `Uint8Array` after `Deno.EOF`. + * + * You must set stderr to `"piped"` when creating the process. + * + * This calls `close()` on stderr after its done. */ stderrOutput(): Promise; close(): void; kill(signo: number): void; @@ -1707,10 +1764,11 @@ declare namespace Deno { signal?: number; } - /** UNSTABLE: Maybe rename args to argv to differentiate from Deno.args Note - * the first element needs to be a path to the binary. - */ + /** **UNSTABLE**: Maybe rename `args` to `argv` 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[]; cwd?: string; env?: { @@ -1721,8 +1779,7 @@ declare namespace Deno { stdin?: ProcessStdio | number; } - /** - * Spawns new subprocess. + /** Spawns new subprocess. * * Subprocess uses same working directory as parent process unless `opt.cwd` * is specified. @@ -1733,7 +1790,8 @@ declare namespace Deno { * By default subprocess inherits stdio of parent process. To change that * `opt.stdout`, `opt.stderr` and `opt.stdin` can be specified independently - * they can be set to either `ProcessStdio` or `rid` of open file. - */ + * + * Requires `allow-run` permission. */ export function run(opt: RunOptions): Process; enum LinuxSignal { @@ -1802,33 +1860,31 @@ declare namespace Deno { SIGUSR1 = 30, SIGUSR2 = 31 } - /** UNSTABLE: make platform independent. + + /** **UNSTABLE**: make platform independent. * - * Signals numbers. This is platform dependent. - */ + * Signals numbers. This is platform dependent. */ export const Signal: typeof MacOSSignal | typeof LinuxSignal; - /** UNSTABLE: rename to InspectOptions */ - type ConsoleOptions = Partial<{ - showHidden: boolean; - depth: number; - colors: boolean; - indentLevel: number; - }>; + /** **UNSTABLE**: rename to `InspectOptions`. */ + interface ConsoleOptions { + showHidden?: boolean; + depth?: number; + colors?: boolean; + indentLevel?: number; + } - /** UNSTABLE: ConsoleOptions rename to InspectOptions. Also the exact form of - * string output subject to change. + /** **UNSTABLE**: `ConsoleOptions` rename to `InspectOptions`. Also the exact + * form of string output subject to change. * - * `inspect()` converts input into string that has the same format - * as printed by `console.log(...)`; - */ + * Converts input into string that has the same format as printed by + * `console.log()`. */ export function inspect(value: unknown, options?: ConsoleOptions): string; export type OperatingSystem = "mac" | "win" | "linux"; export type Arch = "x64" | "arm64"; - /** Build related information */ interface BuildInfo { /** The CPU architecture. */ arch: Arch; @@ -1836,6 +1892,7 @@ declare namespace Deno { os: OperatingSystem; } + /** Build related information. */ export const build: BuildInfo; interface Version { @@ -1843,9 +1900,10 @@ declare namespace Deno { v8: string; typescript: string; } + /** Version related information. */ export const version: Version; - /** The log category for a diagnostic message */ + /** The log category for a diagnostic message. */ export enum DiagnosticCategory { Log = 0, Debug = 1, @@ -1865,39 +1923,28 @@ declare namespace Deno { export interface DiagnosticItem { /** A string message summarizing the diagnostic. */ message: string; - /** An ordered array of further diagnostics. */ messageChain?: DiagnosticMessageChain; - /** Information related to the diagnostic. This is present when there is a * suggestion or other additional diagnostic information */ relatedInformation?: DiagnosticItem[]; - - /** The text of the source line related to the diagnostic */ + /** The text of the source line related to the diagnostic. */ sourceLine?: string; - - /** The line number that is related to the diagnostic */ + /** The line number that is related to the diagnostic. */ lineNumber?: number; - - /** The name of the script resource related to the diagnostic */ + /** The name of the script resource related to the diagnostic. */ scriptResourceName?: string; - - /** The start position related to the diagnostic */ + /** The start position related to the diagnostic. */ startPosition?: number; - - /** The end position related to the diagnostic */ + /** The end position related to the diagnostic. */ endPosition?: number; - - /** The category of the diagnostic */ + /** The category of the diagnostic. */ category: DiagnosticCategory; - - /** A number identifier */ + /** A number identifier. */ code: number; - - /** The the start column of the sourceLine related to the diagnostic */ + /** The the start column of the sourceLine related to the diagnostic. */ startColumn?: number; - - /** The end column of the sourceLine related to the diagnostic */ + /** The end column of the sourceLine related to the diagnostic. */ endColumn?: number; } @@ -1906,123 +1953,95 @@ declare namespace Deno { items: DiagnosticItem[]; } - /** UNSTABLE: new API, yet to be vetted. + /** **UNSTABLE**: new API, yet to be vetted. * * Format an array of diagnostic items and return them as a single string. * @param items An array of diagnostic items to format */ export function formatDiagnostics(items: DiagnosticItem[]): string; - /** UNSTABLE: new API, yet to be vetted. + /** **UNSTABLE**: new API, yet to be vetted. * - * A specific subset TypeScript compiler options that can be supported by - * the Deno TypeScript compiler. - */ + * 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; - /** Allow default imports from modules with no default export. This does not * 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; - /** Parse in strict mode and emit `"use strict"` for each source file. * Defaults to `true`. */ alwaysStrict?: boolean; - /** Base directory to resolve non-relative module names. Defaults to * `undefined`. */ baseUrl?: string; - /** Report errors in `.js` files. Use in conjunction with `allowJs`. Defaults * to `false`. */ checkJs?: boolean; - /** Generates corresponding `.d.ts` file. Defaults to `false`. */ declaration?: boolean; - /** Output directory for generated declaration files. */ declarationDir?: string; - /** Generates a source map for each corresponding `.d.ts` file. Defaults to * `false`. */ declarationMap?: boolean; - /** Provide full support for iterables in `for..of`, spread and * destructuring when targeting ES5 or ES3. Defaults to `false`. */ downlevelIteration?: boolean; - /** Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. * Defaults to `false`. */ emitBOM?: boolean; - /** Only emit `.d.ts` declaration files. Defaults to `false`. */ emitDeclarationOnly?: boolean; - /** Emit design-type metadata for decorated declarations in source. See issue * [microsoft/TypeScript#2577](https://github.com/Microsoft/TypeScript/issues/2577) * for details. Defaults to `false`. */ emitDecoratorMetadata?: boolean; - /** Emit `__importStar` and `__importDefault` helpers for runtime babel * ecosystem compatibility and enable `allowSyntheticDefaultImports` for type * system compatibility. Defaults to `true`. */ esModuleInterop?: boolean; - /** Enables experimental support for ES decorators. Defaults to `false`. */ experimentalDecorators?: boolean; - /** Emit a single file with source maps instead of having a separate file. * Defaults to `false`. */ inlineSourceMap?: boolean; - /** Emit the source alongside the source maps within a single file; requires * `inlineSourceMap` or `sourceMap` to be set. Defaults to `false`. */ inlineSources?: boolean; - /** Perform additional checks to ensure that transpile only would be safe. * Defaults to `false`. */ isolatedModules?: boolean; - /** Support JSX in `.tsx` files: `"react"`, `"preserve"`, `"react-native"`. * Defaults to `"react"`. */ jsx?: "react" | "preserve" | "react-native"; - /** Specify the JSX factory function to use when targeting react JSX emit, * e.g. `React.createElement` or `h`. Defaults to `React.createElement`. */ jsxFactory?: string; - /** Resolve keyof to string valued property names only (no numbers or * symbols). Defaults to `false`. */ keyofStringsOnly?: string; - /** Emit class fields with ECMAScript-standard semantics. Defaults to `false`. * Does not apply to `"esnext"` target. */ useDefineForClassFields?: boolean; - /** List of library files to be included in the compilation. If omitted, * then the Deno main runtime libs are used. */ lib?: string[]; - /** The locale to use to show error messages. */ locale?: string; - /** Specifies the location where debugger should locate map files instead of * 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; - /** Specify the module format for the emitted code. Defaults to * `"esnext"`. */ module?: @@ -2034,115 +2053,88 @@ declare namespace Deno { | "es6" | "es2015" | "esnext"; - /** Do not generate custom helper functions like `__extends` in compiled * output. Defaults to `false`. */ noEmitHelpers?: boolean; - /** Report errors for fallthrough cases in switch statement. Defaults to * `false`. */ noFallthroughCasesInSwitch?: boolean; - /** Raise error on expressions and declarations with an implied any type. * Defaults to `true`. */ noImplicitAny?: boolean; - /** Report an error when not all code paths in function return a value. * Defaults to `false`. */ noImplicitReturns?: boolean; - /** Raise error on `this` expressions with an implied `any` type. Defaults to * `true`. */ noImplicitThis?: boolean; - /** Do not emit `"use strict"` directives in module output. Defaults to * `false`. */ noImplicitUseStrict?: boolean; - /** Do not add triple-slash references or module import targets to the list of * compiled files. Defaults to `false`. */ noResolve?: boolean; - /** Disable strict checking of generic signatures in function types. Defaults * to `false`. */ noStrictGenericChecks?: boolean; - /** Report errors on unused locals. Defaults to `false`. */ noUnusedLocals?: boolean; - /** Report errors on unused parameters. Defaults to `false`. */ noUnusedParameters?: boolean; - /** Redirect output structure to the directory. This only impacts * `Deno.compile` and only changes the emitted file names. Defaults to * `undefined`. */ outDir?: string; - /** List of path mapping entries for module names to locations relative to the * `baseUrl`. Defaults to `undefined`. */ paths?: Record; - /** Do not erase const enum declarations in generated code. Defaults to * `false`. */ preserveConstEnums?: boolean; - /** Remove all comments except copy-right header comments beginning with * `/*!`. Defaults to `true`. */ removeComments?: boolean; - /** Include modules imported with `.json` extension. Defaults to `true`. */ resolveJsonModule?: boolean; - /** Specifies the root directory of input files. Only use to control the * output directory structure with `outDir`. Defaults to `undefined`. */ rootDir?: string; - /** List of _root_ folders whose combined content represent the structure of * the project at runtime. Defaults to `undefined`. */ rootDirs?: string[]; - /** Generates corresponding `.map` file. Defaults to `false`. */ sourceMap?: boolean; - /** Specifies the location where debugger should locate TypeScript files * 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; - /** Enable all strict type checking options. Enabling `strict` enables * `noImplicitAny`, `noImplicitThis`, `alwaysStrict`, `strictBindCallApply`, * `strictNullChecks`, `strictFunctionTypes` and * `strictPropertyInitialization`. Defaults to `true`. */ strict?: boolean; - /** Enable stricter checking of the `bind`, `call`, and `apply` methods on * functions. Defaults to `true`. */ strictBindCallApply?: boolean; - /** Disable bivariant parameter checking for function types. Defaults to * `true`. */ strictFunctionTypes?: boolean; - /** Ensure non-undefined class properties are initialized in the constructor. * This option requires `strictNullChecks` be enabled in order to take effect. * Defaults to `true`. */ strictPropertyInitialization?: boolean; - /** In strict null checking mode, the `null` and `undefined` values are not in * 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; - /** Suppress excess property checks for object literals. Defaults to * `false`. */ suppressExcessPropertyErrors?: boolean; - /** Suppress `noImplicitAny` errors for indexing objects lacking index * signatures. */ suppressImplicitAnyIndexErrors?: boolean; - /** Specify ECMAScript target version. Defaults to `esnext`. */ target?: | "es3" @@ -2155,7 +2147,6 @@ declare namespace Deno { | "es2019" | "es2020" | "esnext"; - /** List of names of type definitions to include. Defaults to `undefined`. * * The type definitions are resolved according to the normal Deno resolution @@ -2174,17 +2165,16 @@ declare namespace Deno { types?: string[]; } - /** UNSTABLE: new API, yet to be vetted. + /** **UNSTABLE**: new API, yet to be vetted. * * The results of a transpile only command, where the `source` contains the - * emitted source, and `map` optionally contains the source map. - */ + * emitted source, and `map` optionally contains the source map. */ export interface TranspileOnlyResult { source: string; map?: string; } - /** UNSTABLE: new API, yet to be vetted. + /** **UNSTABLE**: new API, yet to be vetted. * * Takes a set of TypeScript sources and resolves with a map where the key was * the original file name provided in sources and the result contains the @@ -2210,7 +2200,7 @@ declare namespace Deno { options?: CompilerOptions ): Promise>; - /** UNSTABLE: new API, yet to be vetted. + /** **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 @@ -2245,7 +2235,7 @@ declare namespace Deno { options?: CompilerOptions ): Promise<[DiagnosticItem[] | undefined, Record]>; - /** UNSTABLE: new API, yet to be vetted. + /** **UNSTABLE**: new API, yet to be vetted. * * 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` @@ -2281,21 +2271,21 @@ declare namespace Deno { options?: CompilerOptions ): Promise<[DiagnosticItem[] | undefined, string]>; - /** Returns the script arguments to the program. If for example we run a program + /** Returns the script arguments to the program. If for example we run a + * program: * - * deno --allow-read https://deno.land/std/examples/cat.ts /etc/passwd + * deno --allow-read https://deno.land/std/examples/cat.ts /etc/passwd * - * Then Deno.args will contain just + * Then `Deno.args` will contain: * - * [ "/etc/passwd" ] + * [ "/etc/passwd" ] */ export const args: string[]; - /** UNSTABLE new API. + /** **UNSTABLE**: new API, yet to be vetted. * - * SignalStream represents the stream of signals, implements both - * AsyncIterator and PromiseLike - */ + * Represents the stream of signals, implements both `AsyncIterator` and + * `PromiseLike`. */ export class SignalStream implements AsyncIterableIterator, PromiseLike { constructor(signal: typeof Deno.Signal); @@ -2308,81 +2298,91 @@ declare namespace Deno { dispose(): void; } - /** UNSTABLE new API. + /** **UNSTABLE**: new API, yet to be vetted. * * Returns the stream of the given signal number. You can use it as an async * iterator. * - * for await (const _ of Deno.signal(Deno.Signal.SIGTERM)) { - * console.log("got SIGTERM!"); - * } + * for await (const _ of Deno.signal(Deno.Signal.SIGTERM)) { + * console.log("got SIGTERM!"); + * } * * You can also use it as a promise. In this case you can only receive the * first one. * - * await Deno.signal(Deno.Signal.SIGTERM); - * console.log("SIGTERM received!") + * await Deno.signal(Deno.Signal.SIGTERM); + * console.log("SIGTERM received!") * - * If you want to stop receiving the signals, you can use .dispose() method + * If you want to stop receiving the signals, you can use `.dispose()` method * of the signal stream object. * - * const sig = Deno.signal(Deno.Signal.SIGTERM); - * setTimeout(() => { sig.dispose(); }, 5000); - * for await (const _ of sig) { - * console.log("SIGTERM!") - * } + * const sig = Deno.signal(Deno.Signal.SIGTERM); + * setTimeout(() => { sig.dispose(); }, 5000); + * for await (const _ of sig) { + * console.log("SIGTERM!") + * } * - * The above for-await loop exits after 5 seconds when sig.dispose() is called. - */ + * The above for-await loop exits after 5 seconds when `sig.dispose()` is + * called. */ export function signal(signo: number): SignalStream; - /** UNSTABLE new API. */ + /** **UNSTABLE**: new API, yet to be vetted. */ export const signals: { /** Returns the stream of SIGALRM signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGALRM). */ + * + * This method is the shorthand for `Deno.signal(Deno.Signal.SIGALRM)`. */ alarm: () => SignalStream; /** Returns the stream of SIGCHLD signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGCHLD). */ + * + * This method is the shorthand for `Deno.signal(Deno.Signal.SIGCHLD)`. */ child: () => SignalStream; /** Returns the stream of SIGHUP signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGHUP). */ + * + * This method is the shorthand for `Deno.signal(Deno.Signal.SIGHUP)`. */ hungup: () => SignalStream; /** Returns the stream of SIGINT signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGINT). */ + * + * This method is the shorthand for `Deno.signal(Deno.Signal.SIGINT)`. */ interrupt: () => SignalStream; /** Returns the stream of SIGIO signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGIO). */ + * + * This method is the shorthand for `Deno.signal(Deno.Signal.SIGIO)`. */ io: () => SignalStream; /** Returns the stream of SIGPIPE signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGPIPE). */ + * + * This method is the shorthand for `Deno.signal(Deno.Signal.SIGPIPE)`. */ pipe: () => SignalStream; /** Returns the stream of SIGQUIT signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGQUIT). */ + * + * This method is the shorthand for `Deno.signal(Deno.Signal.SIGQUIT)`. */ quit: () => SignalStream; /** Returns the stream of SIGTERM signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGTERM). */ + * + * This method is the shorthand for `Deno.signal(Deno.Signal.SIGTERM)`. */ terminate: () => SignalStream; /** Returns the stream of SIGUSR1 signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGUSR1). */ + * + * This method is the shorthand for `Deno.signal(Deno.Signal.SIGUSR1)`. */ userDefined1: () => SignalStream; /** Returns the stream of SIGUSR2 signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGUSR2). */ + * + * This method is the shorthand for `Deno.signal(Deno.Signal.SIGUSR2)`. */ userDefined2: () => SignalStream; /** Returns the stream of SIGWINCH signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGWINCH). */ + * + * This method is the shorthand for `Deno.signal(Deno.Signal.SIGWINCH)`. */ windowChange: () => SignalStream; }; - /** UNSTABLE: new API. Maybe move EOF here. + /** **UNSTABLE**: new API. Maybe move `Deno.EOF` here. * - * Special Deno related symbols. - */ + * Special Deno related symbols. */ export const symbols: { /** Symbol to access exposed internal Deno API */ readonly internal: unique symbol; - /** A symbol which can be used as a key for a custom method which will be called - * when `Deno.inspect()` is called, or when the object is logged to the console. - */ + /** A symbol which can be used as a key for a custom method which will be + * called when `Deno.inspect()` is called, or when the object is logged to + * the console. */ readonly customInspect: unique symbol; // TODO(ry) move EOF here? }; diff --git a/cli/js/stat.ts b/cli/js/stat.ts index 1fd28e89304cb1..e742451fd8911a 100644 --- a/cli/js/stat.ts +++ b/cli/js/stat.ts @@ -2,6 +2,7 @@ import { sendSync, sendAsync } from "./dispatch_json.ts"; import { FileInfo, FileInfoImpl } from "./file_info.ts"; +/** @internal */ export interface StatResponse { isFile: boolean; isSymlink: boolean;