diff options
Diffstat (limited to 'cli/dts/lib.deno.ns.d.ts')
| -rw-r--r-- | cli/dts/lib.deno.ns.d.ts | 2028 |
1 files changed, 2028 insertions, 0 deletions
diff --git a/cli/dts/lib.deno.ns.d.ts b/cli/dts/lib.deno.ns.d.ts new file mode 100644 index 000000000..962179381 --- /dev/null +++ b/cli/dts/lib.deno.ns.d.ts @@ -0,0 +1,2028 @@ +// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. + +/// <reference no-default-lib="true" /> +/// <reference lib="esnext" /> + +/** Deno provides extra properties on `import.meta`. These are included here + * to ensure that these are still available when using the Deno namepsace in + * conjunction with other type libs, like `dom`. */ +declare interface ImportMeta { + /** A string representation of the fully qualified module URL. */ + url: string; + + /** A flag that indicates if the current module is the main module that was + * called when starting the program under Deno. + * + * ```ts + * if (import.meta.main) { + * // this was loaded as the main module, maybe do some bootstrapping + * } + * ``` + */ + main: boolean; +} + +/** Deno supports user timing Level 3 (see: https://w3c.github.io/user-timing) + * which is not widely supported yet in other runtimes. These types are here + * so that these features are still available when using the Deno namespace + * in conjunction with other type libs, like `dom`. */ +declare interface Performance { + /** Stores a timestamp with the associated name (a "mark"). */ + mark(markName: string, options?: PerformanceMarkOptions): PerformanceMark; + + /** Stores the `DOMHighResTimeStamp` duration between two marks along with the + * associated name (a "measure"). */ + measure( + measureName: string, + options?: PerformanceMeasureOptions, + ): PerformanceMeasure; +} + +declare interface PerformanceMarkOptions { + /** Metadata to be included in the mark. */ + // eslint-disable-next-line @typescript-eslint/no-explicit-any + detail?: any; + + /** Timestamp to be used as the mark time. */ + startTime?: number; +} + +declare interface PerformanceMeasureOptions { + /** Metadata to be included in the measure. */ + // eslint-disable-next-line @typescript-eslint/no-explicit-any + detail?: any; + + /** Timestamp to be used as the start time or string to be used as start + * mark.*/ + start?: string | number; + + /** Duration between the start and end times. */ + duration?: number; + + /** Timestamp to be used as the end time or string to be used as end mark. */ + end?: string | number; +} + +declare namespace Deno { + /** 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; + UnexpectedEof: ErrorConstructor; + BadResource: ErrorConstructor; + Http: ErrorConstructor; + Busy: ErrorConstructor; + }; + + /** The current process id of the runtime. */ + export const pid: number; + + /** Reflects the `NO_COLOR` environment variable. + * + * See: https://no-color.org/ */ + export const noColor: boolean; + + export interface TestDefinition { + fn: () => void | Promise<void>; + name: string; + ignore?: boolean; + /** If at lease one test has `only` set to true, only run tests that have + * `only` set to true and fail the test suite. */ + only?: boolean; + /** Check that the number of async completed ops after the test is the same + * as number of dispatched ops. Defaults to true.*/ + sanitizeOps?: boolean; + /** Ensure the test case does not "leak" resources - ie. the resource table + * after the test has exactly the same contents as before the test. Defaults + * to true. */ + sanitizeResources?: boolean; + } + + /** 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. + * `fn` can be async if required. + * ```ts + * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * + * Deno.test({ + * name: "example test", + * fn(): void { + * assertEquals("world", "world"); + * }, + * }); + * + * Deno.test({ + * name: "example ignored test", + * ignore: Deno.build.os === "windows", + * fn(): void { + * // This test is ignored only on Windows machines + * }, + * }); + * + * Deno.test({ + * name: "example async test", + * async fn() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * }); + * ``` + */ + export function 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. + * `fn` can be async if required. + * + * ```ts + * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * + * Deno.test("My test description", ():void => { + * assertEquals("hello", "hello"); + * }); + * + * Deno.test("My async test description", async ():Promise<void> => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }); + * ``` + * */ + export function test(name: string, fn: () => void | Promise<void>): void; + + /** Exit the Deno process with optional exit code. If no exit code is supplied + * then Deno will exit with return code of 0. + * + * ```ts + * Deno.exit(5); + * ``` + */ + export function exit(code?: number): never; + + export const env: { + /** Retrieve the value of an environment variable. Returns undefined if that + * key doesn't exist. + * + * ```ts + * console.log(Deno.env.get("HOME")); // e.g. outputs "/home/alice" + * console.log(Deno.env.get("MADE_UP_VAR")); // outputs "Undefined" + * ``` + * Requires `allow-env` permission. */ + get(key: string): string | undefined; + + /** Set the value of an environment variable. + * + * ```ts + * Deno.env.set("SOME_VAR", "Value")); + * Deno.env.get("SOME_VAR"); // outputs "Value" + * ``` + * + * Requires `allow-env` permission. */ + set(key: string, value: string): void; + + /** Delete the value of an environment variable. + * + * ```ts + * Deno.env.set("SOME_VAR", "Value")); + * Deno.env.delete("SOME_VAR"); // outputs "Undefined" + * ``` + * + * Requires `allow-env` permission. */ + delete(key: string): void; + + /** Returns a snapshot of the environment variables at invocation. + * + * ```ts + * Deno.env.set("TEST_VAR", "A"); + * const myEnv = Deno.env.toObject(); + * console.log(myEnv.SHELL); + * Deno.env.set("TEST_VAR", "B"); + * console.log(myEnv.TEST_VAR); // outputs "A" + * ``` + * + * Requires `allow-env` permission. */ + toObject(): { [index: string]: string }; + }; + + /** + * Returns the path to the current deno executable. + * + * ```ts + * console.log(Deno.execPath()); // e.g. "/home/alice/.local/bin/deno" + * ``` + * + * Requires `allow-read` permission. + */ + export function execPath(): string; + + /** + * Change the current working directory to the specified path. + * + * ```ts + * Deno.chdir("/home/userA"); + * Deno.chdir("../userB"); + * Deno.chdir("C:\\Program Files (x86)\\Java"); + * ``` + * + * Throws `Deno.errors.NotFound` if directory not found. + * Throws `Deno.errors.PermissionDenied` if the user does not have access + * rights + * + * Requires --allow-read. + */ + export function chdir(directory: string): void; + + /** + * 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. + * + * ```ts + * const currentWorkingDirectory = Deno.cwd(); + * ``` + * + * Throws `Deno.errors.NotFound` if directory not available. + * + * Requires --allow-read + */ + export function cwd(): string; + + export enum SeekMode { + Start = 0, + Current = 1, + End = 2, + } + + 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()` resolves to `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 resolves + * to what is available instead of waiting for more. + * + * When `read()` encounters end-of-file condition, it resolves to EOF + * (`null`). + * + * When `read()` encounters an error, it rejects with an error. + * + * Callers should always process the `n` > `0` bytes returned before + * considering the EOF (`null`). 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`. + * + * Use Deno.iter() to turn a Reader into an AsyncIterator. + */ + read(p: Uint8Array): Promise<number | null>; + } + + export interface ReaderSync { + /** 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 EOF + * (`null`). + * + * When `readSync()` encounters an error, it throws with an error. + * + * Callers should always process the `n` > `0` bytes returned before + * considering the EOF (`null`). 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`. + * + * Use Deno.iterSync() to turn a ReaderSync into an Iterator. + */ + readSync(p: Uint8Array): number | null; + } + + 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`) or reject with the error encountered that caused the + * write to stop early. `write()` must reject with a non-null error if + * would resolve to `n` < `p.byteLength`. `write()` must not modify the + * slice data, even temporarily. + * + * Implementations should not retain a reference to `p`. + */ + write(p: Uint8Array): Promise<number>; + } + + export interface WriterSync { + /** 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`: `Start` means relative to the + * start of the file, `Current` means relative to the current offset, + * and `End` means relative to the end. Seek resolves to the new offset + * relative to the start of the file. + * + * 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. + * It returns the number of cursor position. + */ + seek(offset: number, whence: SeekMode): Promise<number>; + } + + export interface SeekerSync { + /** Seek sets the offset for the next `readSync()` or `writeSync()` to + * offset, interpreted according to `whence`: `Start` means relative + * to the start of the file, `Current` means relative to the current + * offset, and `End` means relative to the end. + * + * 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): number; + } + + /** Copies from `src` to `dst` until either EOF (`null`) is read from `src` or + * an error occurs. It resolves to the number of bytes copied or rejects with + * the first error encountered while copying. + * + * ```ts + * const source = await Deno.open("my_file.txt"); + * const buffer = new Deno.Buffer() + * const bytesCopied1 = await Deno.copy(source, Deno.stdout); + * const bytesCopied2 = await Deno.copy(source, buffer); + * ``` + * + * @param src The source to copy from + * @param dst The destination to copy to + * @param options Can be used to tune size of the buffer. Default size is 32kB + */ + export function copy( + src: Reader, + dst: Writer, + options?: { + bufSize?: number; + }, + ): Promise<number>; + + /** Turns a Reader, `r`, into an async iterator. + * + * ```ts + * let f = await Deno.open("/etc/passwd"); + * for await (const chunk of Deno.iter(f)) { + * console.log(chunk); + * } + * f.close(); + * ``` + * + * Second argument can be used to tune size of a buffer. + * Default size of the buffer is 32kB. + * + * ```ts + * let f = await Deno.open("/etc/passwd"); + * const iter = Deno.iter(f, { + * bufSize: 1024 * 1024 + * }); + * for await (const chunk of iter) { + * console.log(chunk); + * } + * f.close(); + * ``` + * + * Iterator uses an internal buffer of fixed size for efficiency; it returns + * a view on that buffer on each iteration. It is therefore caller's + * responsibility to copy contents of the buffer if needed; otherwise the + * next iteration will overwrite contents of previously returned chunk. + */ + export function iter( + r: Reader, + options?: { + bufSize?: number; + }, + ): AsyncIterableIterator<Uint8Array>; + + /** Turns a ReaderSync, `r`, into an iterator. + * + * ```ts + * let f = Deno.openSync("/etc/passwd"); + * for (const chunk of Deno.iterSync(f)) { + * console.log(chunk); + * } + * f.close(); + * ``` + * + * Second argument can be used to tune size of a buffer. + * Default size of the buffer is 32kB. + * + * ```ts + * let f = await Deno.open("/etc/passwd"); + * const iter = Deno.iterSync(f, { + * bufSize: 1024 * 1024 + * }); + * for (const chunk of iter) { + * console.log(chunk); + * } + * f.close(); + * ``` + * + * Iterator uses an internal buffer of fixed size for efficiency; it returns + * a view on that buffer on each iteration. It is therefore caller's + * responsibility to copy contents of the buffer if needed; otherwise the + * next iteration will overwrite contents of previously returned chunk. + */ + export function iterSync( + r: ReaderSync, + options?: { + bufSize?: number; + }, + ): IterableIterator<Uint8Array>; + + /** Synchronously open a file and return an instance of `Deno.File`. The + * file does not need to previously exist if using the `create` or `createNew` + * open options. It is the callers responsibility to close the file when finished + * with it. + * + * ```ts + * const file = Deno.openSync("/foo/bar.txt", { read: true, write: true }); + * // Do work with file + * Deno.close(file.rid); + * ``` + * + * Requires `allow-read` and/or `allow-write` permissions depending on options. + */ + export function openSync(path: string | URL, options?: OpenOptions): File; + + /** Open a file and resolve to an instance of `Deno.File`. The + * file does not need to previously exist if using the `create` or `createNew` + * open options. It is the callers responsibility to close the file when finished + * with it. + * + * ```ts + * const file = await Deno.open("/foo/bar.txt", { read: true, write: true }); + * // Do work with file + * Deno.close(file.rid); + * ``` + * + * Requires `allow-read` and/or `allow-write` permissions depending on options. + */ + export function open( + path: string | URL, + options?: OpenOptions, + ): Promise<File>; + + /** Creates a file if none exists or truncates an existing file and returns + * an instance of `Deno.File`. + * + * ```ts + * const file = Deno.createSync("/foo/bar.txt"); + * ``` + * + * Requires `allow-read` and `allow-write` permissions. + */ + export function createSync(path: string | URL): File; + + /** Creates a file if none exists or truncates an existing file and resolves to + * an instance of `Deno.File`. + * + * ```ts + * const file = await Deno.create("/foo/bar.txt"); + * ``` + * + * Requires `allow-read` and `allow-write` permissions. + */ + export function create(path: string | URL): Promise<File>; + + /** Synchronously read from a resource ID (`rid`) into an array buffer (`buffer`). + * + * Returns either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This does + * not indicate EOF. + * + * This function is one of the lowest level APIs and most users should not + * work with this directly, but rather use Deno.readAllSync() instead. + * + * **It is not guaranteed that the full buffer will be read in a single call.** + * + * ```ts + * // if "/foo/bar.txt" contains the text "hello world": + * const file = Deno.openSync("/foo/bar.txt"); + * const buf = new Uint8Array(100); + * const numberOfBytesRead = Deno.readSync(file.rid, buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * Deno.close(file.rid); + * ``` + */ + export function readSync(rid: number, buffer: Uint8Array): number | null; + + /** Read from a resource ID (`rid`) into an array buffer (`buffer`). + * + * Resolves to either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This does + * not indicate EOF. + * + * This function is one of the lowest level APIs and most users should not + * work with this directly, but rather use Deno.readAll() instead. + * + * **It is not guaranteed that the full buffer will be read in a single call.** + * + * ```ts + * // if "/foo/bar.txt" contains the text "hello world": + * const file = await Deno.open("/foo/bar.txt"); + * const buf = new Uint8Array(100); + * const numberOfBytesRead = await Deno.read(file.rid, buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * Deno.close(file.rid); + * ``` + */ + export function read(rid: number, buffer: Uint8Array): Promise<number | null>; + + /** Synchronously write to the resource ID (`rid`) the contents of the array + * buffer (`data`). + * + * Returns the number of bytes written. This function is one of the lowest + * level APIs and most users should not work with this directly, but rather use + * Deno.writeAllSync() instead. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * const file = Deno.openSync("/foo/bar.txt", {write: true}); + * const bytesWritten = Deno.writeSync(file.rid, data); // 11 + * Deno.close(file.rid); + * ``` + */ + export function writeSync(rid: number, data: Uint8Array): number; + + /** Write to the resource ID (`rid`) the contents of the array buffer (`data`). + * + * Resolves to the number of bytes written. This function is one of the lowest + * level APIs and most users should not work with this directly, but rather use + * Deno.writeAll() instead. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * const file = await Deno.open("/foo/bar.txt", { write: true }); + * const bytesWritten = await Deno.write(file.rid, data); // 11 + * Deno.close(file.rid); + * ``` + */ + export function write(rid: number, data: Uint8Array): Promise<number>; + + /** Synchronously seek a resource ID (`rid`) to the given `offset` under mode + * given by `whence`. The new position within the resource (bytes from the + * start) is returned. + * + * ```ts + * const file = Deno.openSync('hello.txt', {read: true, write: true, truncate: true, create: true}); + * Deno.writeSync(file.rid, new TextEncoder().encode("Hello world")); + * // advance cursor 6 bytes + * const cursorPosition = Deno.seekSync(file.rid, 6, Deno.SeekMode.Start); + * console.log(cursorPosition); // 6 + * const buf = new Uint8Array(100); + * file.readSync(buf); + * console.log(new TextDecoder().decode(buf)); // "world" + * ``` + * + * The seek modes work as follows: + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * // Seek 6 bytes from the start of the file + * console.log(Deno.seekSync(file.rid, 6, Deno.SeekMode.Start)); // "6" + * // Seek 2 more bytes from the current position + * console.log(Deno.seekSync(file.rid, 2, Deno.SeekMode.Current)); // "8" + * // Seek backwards 2 bytes from the end of the file + * console.log(Deno.seekSync(file.rid, -2, Deno.SeekMode.End)); // "9" (e.g. 11-2) + * ``` + */ + export function seekSync( + rid: number, + offset: number, + whence: SeekMode, + ): number; + + /** Seek a resource ID (`rid`) to the given `offset` under mode given by `whence`. + * The call resolves to the new position within the resource (bytes from the start). + * + * ```ts + * const file = await Deno.open('hello.txt', {read: true, write: true, truncate: true, create: true}); + * await Deno.write(file.rid, new TextEncoder().encode("Hello world")); + * // advance cursor 6 bytes + * const cursorPosition = await Deno.seek(file.rid, 6, Deno.SeekMode.Start); + * console.log(cursorPosition); // 6 + * const buf = new Uint8Array(100); + * await file.read(buf); + * console.log(new TextDecoder().decode(buf)); // "world" + * ``` + * + * The seek modes work as follows: + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * // Seek 6 bytes from the start of the file + * console.log(await Deno.seek(file.rid, 6, Deno.SeekMode.Start)); // "6" + * // Seek 2 more bytes from the current position + * console.log(await Deno.seek(file.rid, 2, Deno.SeekMode.Current)); // "8" + * // Seek backwards 2 bytes from the end of the file + * console.log(await Deno.seek(file.rid, -2, Deno.SeekMode.End)); // "9" (e.g. 11-2) + * ``` + */ + export function seek( + rid: number, + offset: number, + whence: SeekMode, + ): Promise<number>; + + /** Close the given resource ID (rid) which has been previously opened, such + * as via opening or creating a file. Closing a file when you are finished + * with it is important to avoid leaking resources. + * + * ```ts + * const file = await Deno.open("my_file.txt"); + * // do work with "file" object + * Deno.close(file.rid); + * ```` + */ + export function close(rid: number): void; + + /** The Deno abstraction for reading and writing files. */ + export class File + implements + Reader, + ReaderSync, + Writer, + WriterSync, + Seeker, + SeekerSync, + Closer { + readonly rid: number; + constructor(rid: number); + write(p: Uint8Array): Promise<number>; + writeSync(p: Uint8Array): number; + read(p: Uint8Array): Promise<number | null>; + readSync(p: Uint8Array): number | null; + seek(offset: number, whence: SeekMode): Promise<number>; + seekSync(offset: number, whence: SeekMode): number; + close(): void; + } + + /** A handle for `stdin`. */ + export const stdin: Reader & ReaderSync & Closer & { rid: number }; + /** A handle for `stdout`. */ + export const stdout: Writer & WriterSync & Closer & { rid: number }; + /** A handle for `stderr`. */ + export const stderr: Writer & WriterSync & Closer & { rid: number }; + + export interface OpenOptions { + /** Sets the option for read access. This option, when `true`, means that the + * file should be read-able if opened. */ + read?: boolean; + /** Sets the option for write access. This option, when `true`, means that + * the file should be write-able if opened. If the file already exists, + * any write calls on it will overwrite its contents, by default without + * truncating it. */ + write?: 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 }`. */ + append?: boolean; + /** Sets the option for truncating a previous file. If a file is + * successfully opened with this option set it will truncate the file to `0` + * size if it already exists. The file must be opened with write access + * for truncate to work. */ + truncate?: boolean; + /** Sets the option to allow creating a new file, if one doesn't already + * exist at the specified path. Requires write or append access to be + * used. */ + create?: boolean; + /** Defaults to `false`. If set to `true`, no file, directory, or symlink is + * allowed to exist at the target location. Requires write or append + * access to be used. When createNew is set to `true`, create and truncate + * are ignored. */ + createNew?: boolean; + /** Permissions to use if creating the file (defaults to `0o666`, before + * the process's umask). + * Ignored on Windows. */ + mode?: number; + } + + /** + * + * Check if a given resource id (`rid`) is a TTY. + * + * ```ts + * // This example is system and context specific + * const nonTTYRid = Deno.openSync("my_file.txt").rid; + * const ttyRid = Deno.openSync("/dev/tty6").rid; + * console.log(Deno.isatty(nonTTYRid)); // false + * console.log(Deno.isatty(ttyRid)); // true + * Deno.close(nonTTYRid); + * Deno.close(ttyRid); + * ``` + */ + export function isatty(rid: number): boolean; + + /** A variable-sized buffer of bytes with `read()` and `write()` methods. + * + * Deno.Buffer is almost always used with some I/O like files and sockets. It + * allows one to buffer up a download from a socket. Buffer grows and shrinks + * as necessary. + * + * Deno.Buffer is NOT the same thing as Node's Buffer. Node's Buffer was + * created in 2009 before JavaScript had the concept of ArrayBuffers. It's + * simply a non-standard ArrayBuffer. + * + * ArrayBuffer is a fixed memory allocation. Deno.Buffer is implemented on top + * of ArrayBuffer. + * + * Based on [Go Buffer](https://golang.org/pkg/bytes/#Buffer). */ + export class Buffer implements Reader, ReaderSync, Writer, WriterSync { + constructor(ab?: ArrayBuffer); + /** 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()`). If `options.copy` is false 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. + * @param options Defaults to `{ copy: true }` + */ + bytes(options?: { copy?: boolean }): Uint8Array; + /** Returns whether the unread portion of the buffer is empty. */ + empty(): boolean; + /** A read only number of bytes of the unread portion of the buffer. */ + readonly length: number; + /** 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; + /** 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; + /** 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; + /** 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 EOF (`null`). */ + readSync(p: Uint8Array): number | null; + /** Reads the next `p.length` bytes from the buffer or until the buffer is + * drained. Resolves to the number of bytes read. If the buffer has no + * data to return, resolves to EOF (`null`). + * + * NOTE: This methods reads bytes sychronously; it's provided for + * compatibility with `Reader` interfaces. + */ + read(p: Uint8Array): Promise<number | null>; + writeSync(p: Uint8Array): number; + /** NOTE: This methods writes bytes sychronously; it's provided for + * compatibility with `Writer` interface. */ + write(p: Uint8Array): Promise<number>; + /** 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; + /** Reads data from `r` until EOF (`null`) and appends it to the buffer, + * growing the buffer as needed. It resolves to 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<number>; + /** Reads data from `r` until EOF (`null`) 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: ReaderSync): number; + } + + /** Read Reader `r` until EOF (`null`) and resolve to the content as + * Uint8Array`. + * + * ```ts + * // Example from stdin + * const stdinContent = await Deno.readAll(Deno.stdin); + * + * // Example from file + * const file = await Deno.open("my_file.txt", {read: true}); + * const myFileContent = await Deno.readAll(file); + * Deno.close(file.rid); + * + * // Example from buffer + * const myData = new Uint8Array(100); + * // ... fill myData array with data + * const reader = new Deno.Buffer(myData.buffer as ArrayBuffer); + * const bufferContent = await Deno.readAll(reader); + * ``` + */ + export function readAll(r: Reader): Promise<Uint8Array>; + + /** Synchronously reads Reader `r` until EOF (`null`) and returns the content + * as `Uint8Array`. + * + * ```ts + * // Example from stdin + * const stdinContent = Deno.readAllSync(Deno.stdin); + * + * // Example from file + * const file = Deno.openSync("my_file.txt", {read: true}); + * const myFileContent = Deno.readAllSync(file); + * Deno.close(file.rid); + * + * // Example from buffer + * const myData = new Uint8Array(100); + * // ... fill myData array with data + * const reader = new Deno.Buffer(myData.buffer as ArrayBuffer); + * const bufferContent = Deno.readAllSync(reader); + * ``` + */ + export function readAllSync(r: ReaderSync): Uint8Array; + + /** Write all the content of the array buffer (`arr`) to the writer (`w`). + * + * ```ts + * // Example writing to stdout + * const contentBytes = new TextEncoder().encode("Hello World"); + * await Deno.writeAll(Deno.stdout, contentBytes); + * + * // Example writing to file + * const contentBytes = new TextEncoder().encode("Hello World"); + * const file = await Deno.open('test.file', {write: true}); + * await Deno.writeAll(file, contentBytes); + * Deno.close(file.rid); + * + * // Example writing to buffer + * const contentBytes = new TextEncoder().encode("Hello World"); + * const writer = new Deno.Buffer(); + * await Deno.writeAll(writer, contentBytes); + * console.log(writer.bytes().length); // 11 + * ``` + */ + export function writeAll(w: Writer, arr: Uint8Array): Promise<void>; + + /** Synchronously write all the content of the array buffer (`arr`) to the + * writer (`w`). + * + * ```ts + * // Example writing to stdout + * const contentBytes = new TextEncoder().encode("Hello World"); + * Deno.writeAllSync(Deno.stdout, contentBytes); + * + * // Example writing to file + * const contentBytes = new TextEncoder().encode("Hello World"); + * const file = Deno.openSync('test.file', {write: true}); + * Deno.writeAllSync(file, contentBytes); + * Deno.close(file.rid); + * + * // Example writing to buffer + * const contentBytes = new TextEncoder().encode("Hello World"); + * const writer = new Deno.Buffer(); + * Deno.writeAllSync(writer, contentBytes); + * console.log(writer.bytes().length); // 11 + * ``` + */ + export function writeAllSync(w: WriterSync, arr: Uint8Array): void; + + export interface MkdirOptions { + /** Defaults to `false`. If set to `true`, means that any intermediate + * directories will also be created (as with the shell command `mkdir -p`). + * Intermediate directories are created with the same permissions. + * When recursive is set to `true`, succeeds silently (without changing any + * permissions) if a directory already exists at the path, or if the path + * is a symlink to an existing directory. */ + recursive?: boolean; + /** Permissions to use when creating the directory (defaults to `0o777`, + * before the process's umask). + * Ignored on Windows. */ + mode?: number; + } + + /** Synchronously creates a new directory with the specified path. + * + * ```ts + * Deno.mkdirSync("new_dir"); + * Deno.mkdirSync("nested/directories", { recursive: true }); + * Deno.mkdirSync("restricted_access_dir", { mode: 0o700 }); + * ``` + * + * Defaults to throwing error if the directory already exists. + * + * Requires `allow-write` permission. */ + export function mkdirSync(path: string | URL, options?: MkdirOptions): void; + + /** Creates a new directory with the specified path. + * + * ```ts + * await Deno.mkdir("new_dir"); + * await Deno.mkdir("nested/directories", { recursive: true }); + * await Deno.mkdir("restricted_access_dir", { mode: 0o700 }); + * ``` + * + * Defaults to throwing error if the directory already exists. + * + * Requires `allow-write` permission. */ + export function mkdir( + path: string | URL, + options?: MkdirOptions, + ): Promise<void>; + + export interface MakeTempOptions { + /** Directory where the temporary directory should be created (defaults to + * the env variable TMPDIR, or the system's default, usually /tmp). + * + * Note that if the passed `dir` is relative, the path returned by + * makeTempFile() and makeTempDir() will also be relative. Be mindful of + * this when changing working directory. */ + dir?: string; + /** String that should precede the random portion of the temporary + * directory's name. */ + prefix?: string; + /** String that should follow the random portion of the temporary + * directory's name. */ + suffix?: string; + } + + /** Synchronously creates a new temporary directory in the default directory + * for temporary files (see also `Deno.dir("temp")`), unless `dir` is specified. + * Other optional options include prefixing and suffixing the directory name + * with `prefix` and `suffix` respectively. + * + * The full path to the newly created directory is returned. + * + * Multiple programs calling this function simultaneously will create different + * directories. It is the caller's responsibility to remove the directory when + * no longer needed. + * + * ```ts + * const tempDirName0 = Deno.makeTempDirSync(); // e.g. /tmp/2894ea76 + * const tempDirName1 = Deno.makeTempDirSync({ prefix: 'my_temp' }); // e.g. /tmp/my_temp339c944d + * ``` + * + * Requires `allow-write` permission. */ + // TODO(ry) Doesn't check permissions. + export function makeTempDirSync(options?: MakeTempOptions): string; + + /** Creates a new temporary directory in the default directory for temporary + * files (see also `Deno.dir("temp")`), unless `dir` is specified. Other + * optional options include prefixing and suffixing the directory name with + * `prefix` and `suffix` respectively. + * + * This call resolves to the full path to the newly created directory. + * + * Multiple programs calling this function simultaneously will create different + * directories. It is the caller's responsibility to remove the directory when + * no longer needed. + * + * ```ts + * const tempDirName0 = await Deno.makeTempDir(); // e.g. /tmp/2894ea76 + * const tempDirName1 = await Deno.makeTempDir({ prefix: 'my_temp' }); // e.g. /tmp/my_temp339c944d + * ``` + * + * Requires `allow-write` permission. */ + // TODO(ry) Doesn't check permissions. + export function makeTempDir(options?: MakeTempOptions): Promise<string>; + + /** Synchronously creates a new temporary file in the default directory for + * temporary files (see also `Deno.dir("temp")`), unless `dir` is specified. + * Other optional options include prefixing and suffixing the directory name + * with `prefix` and `suffix` respectively. + * + * The full path to the newly created file is returned. + * + * Multiple programs calling this function simultaneously will create different + * files. It is the caller's responsibility to remove the file when no longer + * needed. + * + * ```ts + * const tempFileName0 = Deno.makeTempFileSync(); // e.g. /tmp/419e0bf2 + * const tempFileName1 = Deno.makeTempFileSync({ prefix: 'my_temp' }); // e.g. /tmp/my_temp754d3098 + * ``` + * + * Requires `allow-write` permission. */ + export function makeTempFileSync(options?: MakeTempOptions): string; + + /** Creates a new temporary file in the default directory for temporary + * files (see also `Deno.dir("temp")`), unless `dir` is specified. Other + * optional options include prefixing and suffixing the directory name with + * `prefix` and `suffix` respectively. + * + * This call resolves to the full path to the newly created file. + * + * Multiple programs calling this function simultaneously will create different + * files. It is the caller's responsibility to remove the file when no longer + * needed. + * + * ```ts + * const tmpFileName0 = await Deno.makeTempFile(); // e.g. /tmp/419e0bf2 + * const tmpFileName1 = await Deno.makeTempFile({ prefix: 'my_temp' }); // e.g. /tmp/my_temp754d3098 + * ``` + * + * Requires `allow-write` permission. */ + export function makeTempFile(options?: MakeTempOptions): Promise<string>; + + /** Synchronously changes the permission of a specific file/directory of + * specified path. Ignores the process's umask. + * + * ```ts + * Deno.chmodSync("/path/to/file", 0o666); + * ``` + * + * For a full description, see [chmod](#chmod) + * + * NOTE: This API currently throws on Windows + * + * Requires `allow-write` permission. */ + export function chmodSync(path: string | URL, mode: number): void; + + /** Changes the permission of a specific file/directory of specified path. + * Ignores the process's umask. + * + * ```ts + * await Deno.chmod("/path/to/file", 0o666); + * ``` + * + * The mode is a sequence of 3 octal numbers. The first/left-most number + * specifies the permissions for the owner. The second number specifies the + * permissions for the group. The last/right-most number specifies the + * permissions for others. For example, with a mode of 0o764, the owner (7) can + * read/write/execute, the group (6) can read/write and everyone else (4) can + * read only. + * + * | Number | Description | + * | ------ | ----------- | + * | 7 | read, write, and execute | + * | 6 | read and write | + * | 5 | read and execute | + * | 4 | read only | + * | 3 | write and execute | + * | 2 | write only | + * | 1 | execute only | + * | 0 | no permission | + * + * NOTE: This API currently throws on Windows + * + * Requires `allow-write` permission. */ + export function chmod(path: string | URL, mode: number): Promise<void>; + + /** Synchronously change owner of a regular file or directory. This functionality + * is not available on Windows. + * + * ```ts + * Deno.chownSync("myFile.txt", 1000, 1002); + * ``` + * + * Requires `allow-write` permission. + * + * Throws Error (not implemented) if executed on Windows + * + * @param path path to the file + * @param uid user id (UID) of the new owner, or `null` for no change + * @param gid group id (GID) of the new owner, or `null` for no change + */ + export function chownSync( + path: string | URL, + uid: number | null, + gid: number | null, + ): void; + + /** Change owner of a regular file or directory. This functionality + * is not available on Windows. + * + * ```ts + * await Deno.chown("myFile.txt", 1000, 1002); + * ``` + * + * Requires `allow-write` permission. + * + * Throws Error (not implemented) if executed on Windows + * + * @param path path to the file + * @param uid user id (UID) of the new owner, or `null` for no change + * @param gid group id (GID) of the new owner, or `null` for no change + */ + export function chown( + path: string | URL, + uid: number | null, + gid: number | null, + ): Promise<void>; + + export interface RemoveOptions { + /** Defaults to `false`. If set to `true`, path will be removed even if + * it's a non-empty directory. */ + recursive?: boolean; + } + + /** Synchronously removes the named file or directory. + * + * ```ts + * Deno.removeSync("/path/to/empty_dir/or/file"); + * Deno.removeSync("/path/to/populated_dir/or/file", { recursive: true }); + * ``` + * + * Throws error if permission denied, path not found, or path is a non-empty + * directory and the `recursive` option isn't set to `true`. + * + * Requires `allow-write` permission. */ + export function removeSync(path: string | URL, options?: RemoveOptions): void; + + /** Removes the named file or directory. + * + * ```ts + * await Deno.remove("/path/to/empty_dir/or/file"); + * await Deno.remove("/path/to/populated_dir/or/file", { recursive: true }); + * ``` + * + * Throws error if permission denied, path not found, or path is a non-empty + * directory and the `recursive` option isn't set to `true`. + * + * Requires `allow-write` permission. */ + export function remove( + path: string | URL, + options?: RemoveOptions, + ): Promise<void>; + + /** Synchronously renames (moves) `oldpath` to `newpath`. Paths may be files or + * directories. If `newpath` already exists and is not a directory, + * `renameSync()` replaces it. OS-specific restrictions may apply when + * `oldpath` and `newpath` are in different directories. + * + * ```ts + * Deno.renameSync("old/path", "new/path"); + * ``` + * + * On Unix, this operation does not follow symlinks at either path. + * + * It varies between platforms when the operation throws errors, and if so what + * they are. It's always an error to rename anything to a non-empty directory. + * + * Requires `allow-read` and `allow-write` permissions. */ + export function renameSync(oldpath: string, newpath: string): void; + + /** Renames (moves) `oldpath` to `newpath`. Paths may be files or directories. + * If `newpath` already exists and is not a directory, `rename()` replaces it. + * OS-specific restrictions may apply when `oldpath` and `newpath` are in + * different directories. + * + * ```ts + * await Deno.rename("old/path", "new/path"); + * ``` + * + * On Unix, this operation does not follow symlinks at either path. + * + * It varies between platforms when the operation throws errors, and if so what + * they are. It's always an error to rename anything to a non-empty directory. + * + * Requires `allow-read` and `allow-write` permission. */ + export function rename(oldpath: string, newpath: string): Promise<void>; + + /** Synchronously reads and returns the entire contents of a file as utf8 encoded string + * encoded string. Reading a directory returns an empty string. + * + * ```ts + * const data = Deno.readTextFileSync("hello.txt"); + * console.log(data); + * ``` + * + * Requires `allow-read` permission. */ + export function readTextFileSync(path: string | URL): string; + + /** Asynchronously reads and returns the entire contents of a file as a utf8 + * encoded string. Reading a directory returns an empty data array. + * + * ```ts + * const data = await Deno.readTextFile("hello.txt"); + * console.log(data); + * ``` + * + * Requires `allow-read` permission. */ + export function readTextFile(path: string | URL): Promise<string>; + + /** Synchronously reads and returns the entire contents of a file as an array + * of bytes. `TextDecoder` can be used to transform the bytes to string if + * required. Reading a directory returns an empty data array. + * + * ```ts + * const decoder = new TextDecoder("utf-8"); + * const data = Deno.readFileSync("hello.txt"); + * console.log(decoder.decode(data)); + * ``` + * + * Requires `allow-read` permission. */ + export function readFileSync(path: string | URL): Uint8Array; + + /** Reads and resolves to the entire contents of a file as an array of bytes. + * `TextDecoder` can be used to transform the bytes to string if required. + * Reading a directory returns an empty data array. + * + * ```ts + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello.txt"); + * console.log(decoder.decode(data)); + * ``` + * + * Requires `allow-read` permission. */ + export function readFile(path: string | URL): Promise<Uint8Array>; + + /** A FileInfo describes a file and is returned by `stat`, `lstat`, + * `statSync`, `lstatSync`. */ + export interface FileInfo { + /** True if this is info for a regular file. Mutually exclusive to + * `FileInfo.isDirectory` and `FileInfo.isSymlink`. */ + isFile: boolean; + /** True if this is info for a regular directory. Mutually exclusive to + * `FileInfo.isFile` and `FileInfo.isSymlink`. */ + isDirectory: boolean; + /** True if this is info for a symlink. Mutually exclusive to + * `FileInfo.isFile` and `FileInfo.isDirectory`. */ + isSymlink: boolean; + /** The size of the file, in bytes. */ + size: number; + /** The last modification time of the file. This corresponds to the `mtime` + * field from `stat` on Linux/Mac OS and `ftLastWriteTime` on Windows. This + * may not be available on all platforms. */ + mtime: Date | 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. */ + atime: Date | null; + /** The creation time of the file. This corresponds to the `birthtime` + * field from `stat` on Mac/BSD and `ftCreationTime` on Windows. This may + * not be available on all platforms. */ + birthtime: Date | null; + /** ID of the device containing the file. + * + * _Linux/Mac OS only._ */ + dev: number | null; + /** Inode number. + * + * _Linux/Mac OS only._ */ + ino: number | null; + /** **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. */ + mode: number | null; + /** Number of hard links pointing to this file. + * + * _Linux/Mac OS only._ */ + nlink: number | null; + /** User ID of the owner of this file. + * + * _Linux/Mac OS only._ */ + uid: number | null; + /** Group ID of the owner of this file. + * + * _Linux/Mac OS only._ */ + gid: number | null; + /** Device ID of this file. + * + * _Linux/Mac OS only._ */ + rdev: number | null; + /** Blocksize for filesystem I/O. + * + * _Linux/Mac OS only._ */ + blksize: number | null; + /** Number of blocks allocated to the file, in 512-byte units. + * + * _Linux/Mac OS only._ */ + blocks: number | null; + } + + /** Returns absolute normalized path, with symbolic links resolved. + * + * ```ts + * // e.g. given /home/alice/file.txt and current directory /home/alice + * Deno.symlinkSync("file.txt", "symlink_file.txt"); + * const realPath = Deno.realPathSync("./file.txt"); + * const realSymLinkPath = Deno.realPathSync("./symlink_file.txt"); + * console.log(realPath); // outputs "/home/alice/file.txt" + * console.log(realSymLinkPath); // outputs "/home/alice/file.txt" + * ``` + * + * Requires `allow-read` permission for the target path. + * Also requires `allow-read` permission for the CWD if the target path is + * relative.*/ + export function realPathSync(path: string): string; + + /** Resolves to the absolute normalized path, with symbolic links resolved. + * + * ```ts + * // e.g. given /home/alice/file.txt and current directory /home/alice + * await Deno.symlink("file.txt", "symlink_file.txt"); + * const realPath = await Deno.realPath("./file.txt"); + * const realSymLinkPath = await Deno.realPath("./symlink_file.txt"); + * console.log(realPath); // outputs "/home/alice/file.txt" + * console.log(realSymLinkPath); // outputs "/home/alice/file.txt" + * ``` + * + * Requires `allow-read` permission for the target path. + * Also requires `allow-read` permission for the CWD if the target path is + * relative.*/ + export function realPath(path: string): Promise<string>; + + export interface DirEntry { + name: string; + isFile: boolean; + isDirectory: boolean; + isSymlink: boolean; + } + + /** Synchronously reads the directory given by `path` and returns an iterable + * of `Deno.DirEntry`. + * + * ```ts + * for (const dirEntry of Deno.readDirSync("/")) { + * console.log(dirEntry.name); + * } + * ``` + * + * Throws error if `path` is not a directory. + * + * Requires `allow-read` permission. */ + export function readDirSync(path: string | URL): Iterable<DirEntry>; + + /** Reads the directory given by `path` and returns an async iterable of + * `Deno.DirEntry`. + * + * ```ts + * for await (const dirEntry of Deno.readDir("/")) { + * console.log(dirEntry.name); + * } + * ``` + * + * Throws error if `path` is not a directory. + * + * Requires `allow-read` permission. */ + export function readDir(path: string | URL): AsyncIterable<DirEntry>; + + /** Synchronously copies the contents and permissions of one file to another + * specified path, by default creating a new file if needed, else overwriting. + * Fails if target path is a directory or is unwritable. + * + * ```ts + * Deno.copyFileSync("from.txt", "to.txt"); + * ``` + * + * Requires `allow-read` permission on fromPath. + * Requires `allow-write` permission on toPath. */ + export function copyFileSync( + fromPath: string | URL, + toPath: string | URL, + ): void; + + /** Copies the contents and permissions of one file to another specified path, + * by default creating a new file if needed, else overwriting. Fails if target + * path is a directory or is unwritable. + * + * ```ts + * await Deno.copyFile("from.txt", "to.txt"); + * ``` + * + * Requires `allow-read` permission on fromPath. + * Requires `allow-write` permission on toPath. */ + export function copyFile( + fromPath: string | URL, + toPath: string | URL, + ): Promise<void>; + + /** Returns the full path destination of the named symbolic link. + * + * ```ts + * Deno.symlinkSync("./test.txt", "./test_link.txt"); + * const target = Deno.readLinkSync("./test_link.txt"); // full path of ./test.txt + * ``` + * + * Throws TypeError if called with a hard link + * + * Requires `allow-read` permission. */ + export function readLinkSync(path: string): string; + + /** Resolves to the full path destination of the named symbolic link. + * + * ```ts + * await Deno.symlink("./test.txt", "./test_link.txt"); + * const target = await Deno.readLink("./test_link.txt"); // full path of ./test.txt + * ``` + * + * Throws TypeError if called with a hard link + * + * Requires `allow-read` permission. */ + export function readLink(path: string): Promise<string>; + + /** Resolves to a `Deno.FileInfo` for the specified `path`. If `path` is a + * symlink, information for the symlink will be returned instead of what it + * points to. + * + * ```ts + * import { assert } from "https://deno.land/std/testing/asserts.ts"; + * const fileInfo = await Deno.lstat("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. */ + export function lstat(path: string | URL): Promise<FileInfo>; + + /** Synchronously returns a `Deno.FileInfo` for the specified `path`. If + * `path` is a symlink, information for the symlink will be returned instead of + * what it points to.. + * + * ```ts + * const fileInfo = Deno.lstatSync("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. */ + export function lstatSync(path: string | URL): FileInfo; + + /** Resolves to a `Deno.FileInfo` for the specified `path`. Will always + * follow symlinks. + * + * ```ts + * import { assert } from "https://deno.land/std/testing/asserts.ts"; + * const fileInfo = await Deno.stat("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. */ + export function stat(path: string | URL): Promise<FileInfo>; + + /** Synchronously returns a `Deno.FileInfo` for the specified `path`. Will + * always follow symlinks. + * + * ```ts + * import { assert } from "https://deno.land/std/testing/asserts.ts"; + * const fileInfo = Deno.statSync("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. */ + export function statSync(path: string | URL): FileInfo; + + /** Options for writing to a file. */ + export interface WriteFileOptions { + /** Defaults to `false`. If set to `true`, will append to a file instead of + * overwriting previous contents. */ + append?: boolean; + /** Sets the option to allow creating a new file, if one doesn't already + * exist at the specified path (defaults to `true`). */ + create?: boolean; + /** Permissions always applied to file. */ + mode?: number; + } + + /** Synchronously write `data` to the given `path`, by default creating a new + * file if needed, else overwriting. + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world\n"); + * Deno.writeFileSync("hello1.txt", data); // overwrite "hello1.txt" or create it + * Deno.writeFileSync("hello2.txt", data, {create: false}); // only works if "hello2.txt" exists + * Deno.writeFileSync("hello3.txt", data, {mode: 0o777}); // set permissions on new file + * Deno.writeFileSync("hello4.txt", data, {append: true}); // add data to the end of the file + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is + * `false`. + */ + export function writeFileSync( + path: string | URL, + data: Uint8Array, + options?: WriteFileOptions, + ): void; + + /** Write `data` to the given `path`, by default creating a new file if needed, + * else overwriting. + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world\n"); + * await Deno.writeFile("hello1.txt", data); // overwrite "hello1.txt" or create it + * await Deno.writeFile("hello2.txt", data, {create: false}); // only works if "hello2.txt" exists + * await Deno.writeFile("hello3.txt", data, {mode: 0o777}); // set permissions on new file + * await Deno.writeFile("hello4.txt", data, {append: true}); // add data to the end of the file + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is `false`. + */ + export function writeFile( + path: string | URL, + data: Uint8Array, + options?: WriteFileOptions, + ): Promise<void>; + + /** Synchronously write string `data` to the given `path`, by default creating a new file if needed, + * else overwriting. + * + * ```ts + * await Deno.writeTextFileSync("hello1.txt", "Hello world\n"); // overwrite "hello1.txt" or create it + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is `false`. + */ + export function writeTextFileSync( + path: string | URL, + data: string, + options?: WriteFileOptions, + ): void; + + /** Asynchronously write string `data` to the given `path`, by default creating a new file if needed, + * else overwriting. + * + * ```ts + * await Deno.writeTextFile("hello1.txt", "Hello world\n"); // overwrite "hello1.txt" or create it + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is `false`. + */ + export function writeTextFile( + path: string | URL, + data: string, + options?: WriteFileOptions, + ): Promise<void>; + + /** Synchronously truncates or extends the specified file, to reach the + * specified `len`. If `len` is not specified then the entire file contents + * are truncated. + * + * ```ts + * // truncate the entire file + * Deno.truncateSync("my_file.txt"); + * + * // truncate part of the file + * const file = Deno.makeTempFileSync(); + * Deno.writeFileSync(file, new TextEncoder().encode("Hello World")); + * Deno.truncateSync(file, 7); + * const data = Deno.readFileSync(file); + * console.log(new TextDecoder().decode(data)); + * ``` + * + * Requires `allow-write` permission. */ + export function truncateSync(name: string, len?: number): void; + + /** Truncates or extends the specified file, to reach the specified `len`. If + * `len` is not specified then the entire file contents are truncated. + * + * ```ts + * // truncate the entire file + * await Deno.truncate("my_file.txt"); + * + * // truncate part of the file + * const file = await Deno.makeTempFile(); + * await Deno.writeFile(file, new TextEncoder().encode("Hello World")); + * await Deno.truncate(file, 7); + * const data = await Deno.readFile(file); + * console.log(new TextDecoder().decode(data)); // "Hello W" + * ``` + * + * Requires `allow-write` permission. */ + export function truncate(name: string, len?: number): Promise<void>; + + export interface NetAddr { + transport: "tcp" | "udp"; + hostname: string; + port: number; + } + + export interface UnixAddr { + transport: "unix" | "unixpacket"; + path: string; + } + + export type Addr = NetAddr | UnixAddr; + + /** A generic network listener for stream-oriented protocols. */ + export interface Listener extends AsyncIterable<Conn> { + /** Waits for and resolves to the next connection to the `Listener`. */ + accept(): Promise<Conn>; + /** Close closes the listener. Any pending accept promises will be rejected + * with errors. */ + close(): void; + /** Return the address of the `Listener`. */ + readonly addr: Addr; + + /** Return the rid of the `Listener`. */ + readonly rid: number; + + [Symbol.asyncIterator](): AsyncIterableIterator<Conn>; + } + + export interface Conn extends Reader, Writer, Closer { + /** The local address of the connection. */ + readonly localAddr: Addr; + /** The remote address of the connection. */ + readonly remoteAddr: Addr; + /** The resource ID of the connection. */ + readonly rid: number; + /** Shuts down (`shutdown(2)`) the writing side of the TCP connection. Most + * callers should just use `close()`. + * + * **Unstable** because of lack of testing and because Deno.shutdown is also + * unstable. + * */ + 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; + } + + /** Listen announces on the local transport address. + * + * ```ts + * const listener1 = Deno.listen({ port: 80 }) + * const listener2 = Deno.listen({ hostname: "192.0.2.1", port: 80 }) + * const listener3 = Deno.listen({ hostname: "[2001:db8::1]", port: 80 }); + * const listener4 = Deno.listen({ hostname: "golang.org", port: 80, transport: "tcp" }); + * ``` + * + * Requires `allow-net` permission. */ + export function listen( + options: ListenOptions & { transport?: "tcp" }, + ): Listener; + + export interface ListenTlsOptions extends ListenOptions { + /** Server certificate file. */ + certFile: string; + /** Server public key file. */ + keyFile: string; + + transport?: "tcp"; + } + + /** Listen announces on the local transport address over TLS (transport layer + * security). + * + * ```ts + * const lstnr = Deno.listenTls({ port: 443, certFile: "./server.crt", keyFile: "./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; + transport?: "tcp"; + } + + /** + * Connects to the hostname (default is "127.0.0.1") and port on the named + * transport (default is "tcp"), and resolves to the connection (`Conn`). + * + * ```ts + * const conn1 = await Deno.connect({ port: 80 }); + * const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 }); + * const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 }); + * const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" }); + * ``` + * + * Requires `allow-net` permission for "tcp". */ + export function connect(options: ConnectOptions): Promise<Conn>; + + 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) using + * an optional cert file, hostname (default is "127.0.0.1") and port. The + * cert file is optional and if not included Mozilla's root certificates will + * be used (see also https://github.com/ctz/webpki-roots for specifics) + * + * ```ts + * const conn1 = await Deno.connectTls({ port: 80 }); + * const conn2 = await Deno.connectTls({ certFile: "./certs/my_custom_root_CA.pem", hostname: "192.0.2.1", port: 80 }); + * const conn3 = await Deno.connectTls({ hostname: "[2001:db8::1]", port: 80 }); + * const conn4 = await Deno.connectTls({ certFile: "./certs/my_custom_root_CA.pem", hostname: "golang.org", port: 80}); + * ``` + * + * Requires `allow-net` permission. + */ + export function connectTls(options: ConnectTlsOptions): Promise<Conn>; + + export interface Metrics { + opsDispatched: number; + opsDispatchedSync: number; + opsDispatchedAsync: number; + opsDispatchedAsyncUnref: number; + opsCompleted: number; + opsCompletedSync: number; + opsCompletedAsync: number; + opsCompletedAsyncUnref: number; + bytesSentControl: number; + bytesSentData: number; + bytesReceived: number; + } + + /** Receive metrics from the privileged side of Deno. This is primarily used + * in the development of Deno. 'Ops', also called 'bindings', are the go-between + * between Deno JavaScript and Deno Rust. + * + * > console.table(Deno.metrics()) + * ┌─────────────────────────┬────────┐ + * │ (index) │ Values │ + * ├─────────────────────────┼────────┤ + * │ opsDispatched │ 3 │ + * │ opsDispatchedSync │ 2 │ + * │ opsDispatchedAsync │ 1 │ + * │ opsDispatchedAsyncUnref │ 0 │ + * │ opsCompleted │ 3 │ + * │ opsCompletedSync │ 2 │ + * │ opsCompletedAsync │ 1 │ + * │ opsCompletedAsyncUnref │ 0 │ + * │ bytesSentControl │ 73 │ + * │ bytesSentData │ 0 │ + * │ bytesReceived │ 375 │ + * └─────────────────────────┴────────┘ + */ + export function metrics(): Metrics; + + interface ResourceMap { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + [rid: number]: any; + } + + /** Returns a map of open resource ids (rid) along with their string + * representations. This is an internal API and as such resource + * representation has `any` type; that means it can change any time. + * + * ```ts + * console.log(Deno.resources()); + * // { 0: "stdin", 1: "stdout", 2: "stderr" } + * Deno.openSync('../test.file'); + * console.log(Deno.resources()); + * // { 0: "stdin", 1: "stdout", 2: "stderr", 3: "fsFile" } + * ``` + */ + export function resources(): ResourceMap; + + export interface FsEvent { + kind: "any" | "access" | "create" | "modify" | "remove"; + paths: string[]; + } + + /** Watch for file system events against one or more `paths`, which can be files + * or directories. These paths must exist already. One user action (e.g. + * `touch test.file`) can generate multiple file system events. Likewise, + * one user action can result in multiple file paths in one event (e.g. `mv + * old_name.txt new_name.txt`). Recursive option is `true` by default and, + * for directories, will watch the specified directory and all sub directories. + * Note that the exact ordering of the events can vary between operating systems. + * + * ```ts + * const watcher = Deno.watchFs("/"); + * for await (const event of watcher) { + * console.log(">>>> event", event); + * // { kind: "create", paths: [ "/foo.txt" ] } + * } + *``` + * + * Requires `allow-read` permission. + */ + export function watchFs( + paths: string | string[], + options?: { recursive: boolean }, + ): AsyncIterableIterator<FsEvent>; + + export class Process<T extends RunOptions = RunOptions> { + readonly rid: number; + readonly pid: number; + readonly stdin: T["stdin"] extends "piped" ? Writer & Closer + : (Writer & Closer) | null; + readonly stdout: T["stdout"] extends "piped" ? Reader & Closer + : (Reader & Closer) | null; + readonly stderr: T["stderr"] extends "piped" ? Reader & Closer + : (Reader & Closer) | null; + /** Resolves to the current status of the process. */ + status(): Promise<ProcessStatus>; + /** Buffer the stdout until EOF and return it as `Uint8Array`. + * + * You must set stdout to `"piped"` when creating the process. + * + * This calls `close()` on stdout after its done. */ + output(): Promise<Uint8Array>; + /** Buffer the stderr until EOF and return it as `Uint8Array`. + * + * You must set stderr to `"piped"` when creating the process. + * + * This calls `close()` on stderr after its done. */ + stderrOutput(): Promise<Uint8Array>; + close(): void; + + /** **UNSTABLE**: The `signo` argument may change to require the Deno.Signal + * enum. + * + * Send a signal to process. This functionality currently only works on + * Linux and Mac OS. + */ + kill(signo: number): void; + } + + export type ProcessStatus = + | { + success: true; + code: 0; + signal?: undefined; + } + | { + success: false; + code: number; + signal?: number; + }; + + export interface RunOptions { + /** Arguments to pass. Note, the first element needs to be a path to the + * binary */ + cmd: string[]; + cwd?: string; + env?: { + [key: string]: string; + }; + stdout?: "inherit" | "piped" | "null" | number; + stderr?: "inherit" | "piped" | "null" | number; + stdin?: "inherit" | "piped" | "null" | number; + } + + /** Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`, + * an array of program arguments, the first of which is the binary. + * + * ```ts + * const p = Deno.run({ + * cmd: ["echo", "hello"], + * }); + * ``` + * + * Subprocess uses same working directory as parent process unless `opt.cwd` + * is specified. + * + * Environmental variables for subprocess can be specified using `opt.env` + * mapping. + * + * 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 an rid of open file or set to "inherit" "piped" + * or "null": + * + * `"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 + * sub-processes. + * + * `"null"` This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + * + * Details of the spawned process are returned. + * + * Requires `allow-run` permission. */ + export function run<T extends RunOptions = RunOptions>(opt: T): Process<T>; + + export interface InspectOptions { + /** Traversal depth for nested objects. Defaults to 4. */ + depth?: number; + /** Sort Object, Set and Map entries by key. Defaults to false. */ + sorted?: boolean; + /** Add a trailing comma for multiline collections. Defaults to false. */ + trailingComma?: boolean; + /** Try to fit more than one entry of a collection on the same line. + * Defaults to true. */ + compact?: boolean; + /** The maximum number of iterable entries to print. Defaults to 100. */ + iterableLimit?: number; + } + + /** Converts the input into a string that has the same format as printed by + * `console.log()`. + * + * ```ts + * const obj = {}; + * obj.propA = 10; + * obj.propB = "hello"; + * const objAsString = Deno.inspect(obj); // { propA: 10, propB: "hello" } + * console.log(obj); // prints same value as objAsString, e.g. { propA: 10, propB: "hello" } + * ``` + * + * You can also register custom inspect functions, via the `customInspect` Deno + * symbol on objects, to control and customize the output. + * + * ```ts + * class A { + * x = 10; + * y = "hello"; + * [Deno.customInspect](): string { + * return "x=" + this.x + ", y=" + this.y; + * } + * } + * ``` + * + * const inStringFormat = Deno.inspect(new A()); // "x=10, y=hello" + * console.log(inStringFormat); // prints "x=10, y=hello" + * + * Finally, you can also specify the depth to which it will format. + * + * Deno.inspect({a: {b: {c: {d: 'hello'}}}}, {depth: 2}); // { a: { b: [Object] } } + * + */ + export function inspect(value: unknown, options?: InspectOptions): string; + + /** Build related information. */ + export const build: { + /** The LLVM target triple */ + target: string; + /** Instruction set architecture */ + arch: "x86_64"; + /** Operating system */ + os: "darwin" | "linux" | "windows"; + /** Computer vendor */ + vendor: string; + /** Optional environment */ + env?: string; + }; + + interface Version { + deno: string; + v8: string; + typescript: string; + } + /** Version related information. */ + export const version: Version; + + /** Returns the script arguments to the program. If for example we run a + * program: + * + * deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd + * + * Then `Deno.args` will contain: + * + * [ "/etc/passwd" ] + */ + export const args: string[]; + + /** 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. */ + export const customInspect: unique symbol; +} |