// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
/// <reference no-default-lib="true" />
/// <reference lib="esnext" />
/// <reference lib="deno.net" />
/** Deno provides extra properties on `import.meta`. These are included here
* to ensure that these are still available when using the Deno namespace 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. */
// deno-lint-ignore 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. */
// deno-lint-ignore 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 namespace errors {
export class NotFound extends Error {}
export class PermissionDenied extends Error {}
export class ConnectionRefused extends Error {}
export class ConnectionReset extends Error {}
export class ConnectionAborted extends Error {}
export class NotConnected extends Error {}
export class AddrInUse extends Error {}
export class AddrNotAvailable extends Error {}
export class BrokenPipe extends Error {}
export class AlreadyExists extends Error {}
export class InvalidData extends Error {}
export class TimedOut extends Error {}
export class Interrupted extends Error {}
export class WriteZero extends Error {}
export class UnexpectedEof extends Error {}
export class BadResource extends Error {}
export class Http extends Error {}
export class Busy extends Error {}
export class NotSupported extends Error {}
}
/** The current process id of the runtime. */
export const pid: number;
/**
* The pid of the current process's parent.
*/
export const ppid: number;
export interface MemoryUsage {
rss: number;
heapTotal: number;
heapUsed: number;
external: number;
}
/**
* Returns an object describing the memory usage of the Deno process measured
* in bytes.
*/
export function memoryUsage(): MemoryUsage;
/** Reflects the `NO_COLOR` environment variable at program start.
*
* See: https://no-color.org/ */
export const noColor: boolean;
export interface TestContext {
/** Run a sub step of the parent test or step. Returns a promise
* that resolves to a boolean signifying if the step completed successfully.
* The returned promise never rejects unless the arguments are invalid.
* If the test was ignored the promise returns `false`.
*/
step(t: TestStepDefinition): Promise<boolean>;
/** Run a sub step of the parent test or step. Returns a promise
* that resolves to a boolean signifying if the step completed successfully.
* The returned promise never rejects unless the arguments are invalid.
* If the test was ignored the promise returns `false`.
*/
step(
name: string,
fn: (t: TestContext) => void | Promise<void>,
): Promise<boolean>;
}
export interface TestStepDefinition {
fn: (t: TestContext) => void | Promise<void>;
name: string;
ignore?: boolean;
/** Check that the number of async completed ops after the test step is the same
* as number of dispatched ops. Defaults to the parent test or step's value. */
sanitizeOps?: boolean;
/** Ensure the test step does not "leak" resources - ie. the resource table
* after the test has exactly the same contents as before the test. Defaults
* to the parent test or step's value. */
sanitizeResources?: boolean;
/** Ensure the test step does not prematurely cause the process to exit,
* for example via a call to `Deno.exit`. Defaults to the parent test or
* step's value. */
sanitizeExit?: boolean;
}
export interface TestDefinition {
fn: (t: TestContext) => void | Promise<void>;
name: string;
ignore?: boolean;
/** If at least 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;
/** Ensure the test case does not prematurely cause the process to exit,
* for example via a call to `Deno.exit`. Defaults to true. */
sanitizeExit?: boolean;
/** Specifies the permissions that should be used to run the test.
* Set this to "inherit" to keep the calling thread's permissions.
* Set this to "none" to revoke all permissions.
*
* Defaults to "inherit".
*/
permissions?: "inherit" | "none" | {
/** Specifies if the `net` permission should be requested or revoked.
* If set to `"inherit"`, the current `env` permission will be inherited.
* If set to `true`, the global `net` permission will be requested.
* If set to `false`, the global `net` permission will be revoked.
*
* Defaults to "inherit".
*/
env?: "inherit" | boolean | string[];
/** Specifies if the `hrtime` permission should be requested or revoked.
* If set to `"inherit"`, the current `hrtime` permission will be inherited.
* If set to `true`, the global `hrtime` permission will be requested.
* If set to `false`, the global `hrtime` permission will be revoked.
*
* Defaults to "inherit".
*/
hrtime?: "inherit" | boolean;
/** Specifies if the `net` permission should be requested or revoked.
* if set to `"inherit"`, the current `net` permission will be inherited.
* if set to `true`, the global `net` permission will be requested.
* if set to `false`, the global `net` permission will be revoked.
* if set to `string[]`, the `net` permission will be requested with the
* specified host strings with the format `"<host>[:<port>]`.
*
* Defaults to "inherit".
*
* Examples:
*
* ```ts
* import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
*
* Deno.test({
* name: "inherit",
* permissions: {
* net: "inherit",
* },
* async fn() {
* const status = await Deno.permissions.query({ name: "net" })
* assertEquals(status.state, "granted");
* },
* });
* ```
*
* ```ts
* import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
*
* Deno.test({
* name: "true",
* permissions: {
* net: true,
* },
* async fn() {
* const status = await Deno.permissions.query({ name: "net" });
* assertEquals(status.state, "granted");
* },
* });
* ```
*
* ```ts
* import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
*
* Deno.test({
* name: "false",
* permissions: {
* net: false,
* },
* async fn() {
* const status = await Deno.permissions.query({ name: "net" });
* assertEquals(status.state, "denied");
* },
* });
* ```
*
* ```ts
* import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
*
* Deno.test({
* name: "localhost:8080",
* permissions: {
* net: ["localhost:8080"],
* },
* async fn() {
* const status = await Deno.permissions.query({ name: "net", host: "localhost:8080" });
* assertEquals(status.state, "granted");
* },
* });
* ```
*/
net?: "inherit" | boolean | string[];
/** Specifies if the `ffi` permission should be requested or revoked.
* If set to `"inherit"`, the current `ffi` permission will be inherited.
* If set to `true`, the global `ffi` permission will be requested.
* If set to `false`, the global `ffi` permission will be revoked.
*
* Defaults to "inherit".
*/
ffi?: "inherit" | boolean | Array<string | URL>;
/** Specifies if the `read` permission should be requested or revoked.
* If set to `"inherit"`, the current `read` permission will be inherited.
* If set to `true`, the global `read` permission will be requested.
* If set to `false`, the global `read` permission will be revoked.
* If set to `Array<string | URL>`, the `read` permission will be requested with the
* specified file paths.
*
* Defaults to "inherit".
*/
read?: "inherit" | boolean | Array<string | URL>;
/** Specifies if the `run` permission should be requested or revoked.
* If set to `"inherit"`, the current `run` permission will be inherited.
* If set to `true`, the global `run` permission will be requested.
* If set to `false`, the global `run` permission will be revoked.
*
* Defaults to "inherit".
*/
run?: "inherit" | boolean | Array<string | URL>;
/** Specifies if the `write` permission should be requested or revoked.
* If set to `"inherit"`, the current `write` permission will be inherited.
* If set to `true`, the global `write` permission will be requested.
* If set to `false`, the global `write` permission will be revoked.
* If set to `Array<string | URL>`, the `write` permission will be requested with the
* specified file paths.
*
* Defaults to "inherit".
*/
write?: "inherit" | boolean | Array<string | URL>;
};
}
/** 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: (t: TestContext) => void | Promise<void>,
): 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. Declared function must have a name.
*
* ```ts
* import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts";
*
* Deno.test(function myTestName(): void {
* assertEquals("hello", "hello");
* });
*
* Deno.test(async function myOtherTestName(): Promise<void> {
* const decoder = new TextDecoder("utf-8");
* const data = await Deno.readFile("hello_world.txt");
* assertEquals(decoder.decode(data), "Hello world");
* });
* ```
*/
export function test(fn: (t: TestContext) => void | Promise<void>): 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", { permissions: { read: true } }, (): void => {
* assertEquals("hello", "hello");
* });
*
* Deno.test("My async test description", { permissions: { read: false } }, async (): Promise<void> => {
* const decoder = new TextDecoder("utf-8");
* const data = await Deno.readFile("hello_world.txt");
* assertEquals(decoder.decode(data), "Hello world");
* });
* ```
*/
export function test(
name: string,
options: Omit<TestDefinition, "fn" | "name">,
fn: (t: TestContext) => void | Promise<void>,
): 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({ name: "My test description", permissions: { read: true } }, (): void => {
* assertEquals("hello", "hello");
* });
*
* Deno.test({ name: "My async test description", permissions: { read: false } }, async (): Promise<void> => {
* const decoder = new TextDecoder("utf-8");
* const data = await Deno.readFile("hello_world.txt");
* assertEquals(decoder.decode(data), "Hello world");
* });
* ```
*/
export function test(
options: Omit<TestDefinition, "fn">,
fn: (t: TestContext) => void | Promise<void>,
): 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. Declared function must have a name.
*
* ```ts
* import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts";
*
* Deno.test({ permissions: { read: true } }, function myTestName(): void {
* assertEquals("hello", "hello");
* });
*
* Deno.test({ permissions: { read: false } }, async function myOtherTestName(): Promise<void> {
* const decoder = new TextDecoder("utf-8");
* const data = await Deno.readFile("hello_world.txt");
* assertEquals(decoder.decode(data), "Hello world");
* });
* ```
*/
export function test(
options: Omit<TestDefinition, "fn" | "name">,
fn: (t: TestContext) => 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 | URL): 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;
/**
* Synchronously creates `newpath` as a hard link to `oldpath`.
*
* ```ts
* Deno.linkSync("old/name", "new/name");
* ```
*
* Requires `allow-read` and `allow-write` permissions. */
export function linkSync(oldpath: string, newpath: string): void;
/**
* Creates `newpath` as a hard link to `oldpath`.
*
* ```ts
* await Deno.link("old/name", "new/name");
* ```
*
* Requires `allow-read` and `allow-write` permissions. */
export function link(oldpath: string, newpath: string): Promise<void>;
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 iter() from https://deno.land/std/io/util.ts 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 `readSync()` 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, `readSync()` 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 iterSync() from https://deno.land/std/io/util.ts 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 bytesCopied1 = await Deno.copy(source, Deno.stdout);
* const destination = await Deno.create("my_file_2.txt");
* const bytesCopied2 = await Deno.copy(source, destination);
* ```
*
* @deprecated Use `copy` from https://deno.land/std/streams/conversion.ts
* instead. `Deno.copy` will be removed in Deno 2.0.
*
* @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.
*
* @deprecated Use `iterateReader` from
* https://deno.land/std/streams/conversion.ts instead. `Deno.iter` will be
* removed in Deno 2.0.
*/
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.
*
* @deprecated Use `iterateReaderSync` from
* https://deno.land/std/streams/conversion.ts instead. `Deno.iterSync` will
* be removed in Deno 2.0.
*/
export function iterSync(
r: ReaderSync,
options?: {
bufSize?: number;
},
): IterableIterator<Uint8Array>;
/** Synchronously open a file and return an instance of `Deno.FsFile`. 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): FsFile;
/** Open a file and resolve to an instance of `Deno.FsFile`. 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<FsFile>;
/** Creates a file if none exists or truncates an existing file and returns
* an instance of `Deno.FsFile`.
*
* ```ts
* const file = Deno.createSync("/foo/bar.txt");
* ```
*
* Requires `allow-read` and `allow-write` permissions.
*/
export function createSync(path: string | URL): FsFile;
/** Creates a file if none exists or truncates an existing file and resolves to
* an instance of `Deno.FsFile`.
*
* ```ts
* const file = await Deno.create("/foo/bar.txt");
* ```
*
* Requires `allow-read` and `allow-write` permissions.
*/
export function create(path: string | URL): Promise<FsFile>;
/** 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
* `writeAllSync()` from https://deno.land/std/streams/conversion.ts 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:
* const file = Deno.openSync('hello.txt', {read: true, write: true, truncate: true, create: true});
* Deno.writeSync(file.rid, new TextEncoder().encode("Hello world"));
*
* // 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
* // Given file.rid pointing to file with "Hello world", which is 11 bytes long:
* 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:
* 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"));
*
* // 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>;
/**
* Synchronously flushes any pending data and metadata operations of the given file stream to disk.
* ```ts
* const file = Deno.openSync("my_file.txt", { read: true, write: true, create: true });
* Deno.writeSync(file.rid, new TextEncoder().encode("Hello World"));
* Deno.ftruncateSync(file.rid, 1);
* Deno.fsyncSync(file.rid);
* console.log(new TextDecoder().decode(Deno.readFileSync("my_file.txt"))); // H
* ```
*/
export function fsyncSync(rid: number): void;
/**
* Flushes any pending data and metadata operations of the given file stream to disk.
* ```ts
* const file = await Deno.open("my_file.txt", { read: true, write: true, create: true });
* await Deno.write(file.rid, new TextEncoder().encode("Hello World"));
* await Deno.ftruncate(file.rid, 1);
* await Deno.fsync(file.rid);
* console.log(new TextDecoder().decode(await Deno.readFile("my_file.txt"))); // H
* ```
*/
export function fsync(rid: number): Promise<void>;
/*
* Synchronously flushes any pending data operations of the given file stream to disk.
* ```ts
* const file = Deno.openSync("my_file.txt", { read: true, write: true, create: true });
* Deno.writeSync(file.rid, new TextEncoder().encode("Hello World"));
* Deno.fdatasyncSync(file.rid);
* console.log(new TextDecoder().decode(Deno.readFileSync("my_file.txt"))); // Hello World
* ```
*/
export function fdatasyncSync(rid: number): void;
/**
* Flushes any pending data operations of the given file stream to disk.
* ```ts
* const file = await Deno.open("my_file.txt", { read: true, write: true, create: true });
* await Deno.write(file.rid, new TextEncoder().encode("Hello World"));
* await Deno.fdatasync(file.rid);
* console.log(new TextDecoder().decode(await Deno.readFile("my_file.txt"))); // Hello World
* ```
*/
export function fdatasync(rid: number): Promise<void>;
/** 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 FsFile
implements
Reader,
ReaderSync,
Writer,
WriterSync,
Seeker,
SeekerSync,
Closer {
readonly rid: number;
constructor(rid: number);
write(p: Uint8Array): Promise<number>;
writeSync(p: Uint8Array): number;
truncate(len?: number): Promise<void>;
truncateSync(len?: number): void;
read(p: Uint8Array): Promise<number | null>;
readSync(p: Uint8Array): number | null;
seek(offset: number, whence: SeekMode): Promise<number>;
seekSync(offset: number, whence: SeekMode): number;
stat(): Promise<FileInfo>;
statSync(): FileInfo;
close(): void;
readonly readable: ReadableStream<Uint8Array>;
readonly writable: WritableStream<Uint8Array>;
}
/**
* @deprecated Use `Deno.FsFile` instead. `Deno.File` will be removed in Deno 2.0.
*
* 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;
truncate(len?: number): Promise<void>;
truncateSync(len?: number): void;
read(p: Uint8Array): Promise<number | null>;
readSync(p: Uint8Array): number | null;
seek(offset: number, whence: SeekMode): Promise<number>;
seekSync(offset: number, whence: SeekMode): number;
stat(): Promise<FileInfo>;
statSync(): FileInfo;
close(): void;
readonly readable: ReadableStream<Uint8Array>;
readonly writable: WritableStream<Uint8Array>;
}
/** A handle for `stdin`. */
export const stdin: Reader & ReaderSync & Closer & {
readonly rid: number;
readonly readable: ReadableStream<Uint8Array>;
};
/** A handle for `stdout`. */
export const stdout: Writer & WriterSync & Closer & {
readonly rid: number;
readonly writable: WritableStream<Uint8Array>;
};
/** A handle for `stderr`. */
export const stderr: Writer & WriterSync & Closer & {
readonly rid: number;
readonly writable: WritableStream<Uint8Array>;
};
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;
}
export interface ReadFileOptions {
/**
* An abort signal to allow cancellation of the file read operation.
* If the signal becomes aborted the readFile operation will be stopped
* and the promise returned will be rejected with an AbortError.
*/
signal?: AbortSignal;
}
/**
* 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;
/**
* @deprecated Use Buffer from https://deno.land/std/io/buffer.ts instead. Deno.Buffer will be removed in Deno 2.0.
*
* 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 synchronously; it's provided for
* compatibility with `Reader` interfaces.
*/
read(p: Uint8Array): Promise<number | null>;
writeSync(p: Uint8Array): number;
/** NOTE: This methods writes bytes synchronously; 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);
* ```
*
* @deprecated Use `readAll` from https://deno.land/std/streams/conversion.ts
* instead. `Deno.readAll` will be removed in Deno 2.0.
*/
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);
* ```
*
* @deprecated Use `readAllSync` from
* https://deno.land/std/streams/conversion.ts instead. `Deno.readAllSync`
* will be removed in Deno 2.0.
*/
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);
* ```
*
* ```ts
* // 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);
* ```
*
* ```ts
* // 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
* ```
*
* @deprecated Use `writeAll` from https://deno.land/std/streams/conversion.ts
* instead. `Deno.writeAll` will be removed in Deno 2.0.
*/
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);
* ```
*
* ```ts
* // 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);
* ```
*
* ```ts
* // 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
* ```
*
* @deprecated Use `writeAllSync` from
* https://deno.land/std/streams/conversion.ts instead. `Deno.writeAllSync`
* will be removed in Deno 2.0.
*/
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, 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, 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, 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, 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](#Deno.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 | URL,
newpath: string | URL,
): 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 | URL,
newpath: string | URL,
): Promise<void>;
/** Synchronously reads and returns the entire contents of a file as utf8
* encoded string. Reading a directory throws an error.
*
* ```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 utf8
* encoded string. Reading a directory throws an error.
*
* ```ts
* const data = await Deno.readTextFile("hello.txt");
* console.log(data);
* ```
*
* Requires `allow-read` permission. */
export function readTextFile(
path: string | URL,
options?: ReadFileOptions,
): 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,
options?: ReadFileOptions,
): 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 | URL): 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 | URL): 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 | URL): 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 | URL): 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
* import { assert } from "https://deno.land/std/testing/asserts.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;
/**
* An abort signal to allow cancellation of the file write operation.
* If the signal becomes aborted the writeFile operation will be stopped
* and the promise returned will be rejected with an AbortError.
*/
signal?: AbortSignal;
}
/** 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
* 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 OpMetrics {
opsDispatched: number;
opsDispatchedSync: number;
opsDispatchedAsync: number;
opsDispatchedAsyncUnref: number;
opsCompleted: number;
opsCompletedSync: number;
opsCompletedAsync: number;
opsCompletedAsyncUnref: number;
bytesSentControl: number;
bytesSentData: number;
bytesReceived: number;
}
export interface Metrics extends OpMetrics {
ops: Record<string, OpMetrics>;
}
/** 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 {
// deno-lint-ignore 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;
/**
* Additional information for FsEvent objects with the "other" kind.
*
* - "rescan": rescan notices indicate either a lapse in the events or a
* change in the filesystem such that events received so far can no longer
* be relied on to represent the state of the filesystem now. An
* application that simply reacts to file changes may not care about this.
* An application that keeps an in-memory representation of the filesystem
* will need to care, and will need to refresh that representation directly
* from the filesystem.
*/
export type FsEventFlag = "rescan";
export interface FsEvent {
kind: "any" | "access" | "create" | "modify" | "remove" | "other";
paths: string[];
flag?: FsEventFlag;
}
/**
* FsWatcher is returned by `Deno.watchFs` function when you start watching
* the file system. You can iterate over this interface to get the file
* system events, and also you can stop watching the file system by calling
* `.close()` method.
*/
export interface FsWatcher extends AsyncIterable<FsEvent> {
/** The resource id of the `FsWatcher`. */
readonly rid: number;
/** Stops watching the file system and closes the watcher resource. */
close(): void;
/**
* Stops watching the file system and closes the watcher resource.
*
* @deprecated Will be removed at 2.0.
*/
return?(value?: any): Promise<IteratorResult<FsEvent>>;
[Symbol.asyncIterator](): AsyncIterableIterator<FsEvent>;
}
/** 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.
*
* Call `watcher.close()` to stop watching.
*
* ```ts
* const watcher = Deno.watchFs("/");
*
* setTimeout(() => {
* watcher.close();
* }, 5000);
*
* for await (const event of watcher) {
* console.log(">>>> event", event);
* }
* ```
*/
export function watchFs(
paths: string | string[],
options?: { recursive: boolean },
): FsWatcher;
export class Process<T extends RunOptions = RunOptions> {
readonly rid: number;
readonly pid: number;
readonly stdin: T["stdin"] extends "piped" ? Writer & Closer & {
writable: WritableStream<Uint8Array>;
}
: (Writer & Closer & { writable: WritableStream<Uint8Array> }) | null;
readonly stdout: T["stdout"] extends "piped" ? Reader & Closer & {
readable: ReadableStream<Uint8Array>;
}
: (Reader & Closer & { readable: ReadableStream<Uint8Array> }) | null;
readonly stderr: T["stderr"] extends "piped" ? Reader & Closer & {
readable: ReadableStream<Uint8Array>;
}
: (Reader & Closer & { readable: ReadableStream<Uint8Array> }) | null;
/** Wait for the process to exit and return its exit status.
*
* Calling this function multiple times will return the same status.
*
* Stdin handle to the process will be closed before waiting to avoid
* a deadlock.
*
* If `stdout` and/or `stderr` were set to `"piped"`, they must be closed
* manually before the process can exit.
*
* To run process to completion and collect output from both `stdout` and
* `stderr` use:
*
* ```ts
* const p = Deno.run({ cmd: [ "echo", "hello world" ], stderr: 'piped', stdout: 'piped' });
* const [status, stdout, stderr] = await Promise.all([
* p.status(),
* p.output(),
* p.stderrOutput()
* ]);
* p.close();
* ```
*/
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;
/** Send a signal to process.
*
* ```ts
* const p = Deno.run({ cmd: [ "sleep", "20" ]});
* p.kill("SIGTERM");
* p.close();
* ```
*/
kill(signo: Signal): void;
}
export type Signal =
| "SIGABRT"
| "SIGALRM"
| "SIGBUS"
| "SIGCHLD"
| "SIGCONT"
| "SIGEMT"
| "SIGFPE"
| "SIGHUP"
| "SIGILL"
| "SIGINFO"
| "SIGINT"
| "SIGIO"
| "SIGKILL"
| "SIGPIPE"
| "SIGPROF"
| "SIGPWR"
| "SIGQUIT"
| "SIGSEGV"
| "SIGSTKFLT"
| "SIGSTOP"
| "SIGSYS"
| "SIGTERM"
| "SIGTRAP"
| "SIGTSTP"
| "SIGTTIN"
| "SIGTTOU"
| "SIGURG"
| "SIGUSR1"
| "SIGUSR2"
| "SIGVTALRM"
| "SIGWINCH"
| "SIGXCPU"
| "SIGXFSZ";
/** Registers the given function as a listener of the given signal event.
*
* ```ts
* Deno.addSignalListener("SIGTERM", () => {
* console.log("SIGTERM!")
* });
* ```
*
* NOTE: This functionality is not yet implemented on Windows.
*/
export function addSignalListener(signal: Signal, handler: () => void): void;
/** Removes the given signal listener that has been registered with
* Deno.addSignalListener.
*
* ```ts
* const listener = () => {
* console.log("SIGTERM!")
* };
* Deno.addSignalListener("SIGTERM", listener);
* Deno.removeSignalListener("SIGTERM", listener);
* ```
*
* NOTE: This functionality is not yet implemented on Windows.
*/
export function removeSignalListener(
signal: Signal,
handler: () => void,
): 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[] | [URL, ...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 from parent process can be cleared using `opt.clearEnv`.
* Doesn't guarantee that only `opt.env` variables are present,
* as the OS may set environmental variables for processes.
*
* Environmental variables for subprocess can be specified using `opt.env`
* mapping.
*
* `opt.uid` sets the child process’s user ID. This translates to a setuid call
* in the child process. Failure in the setuid call will cause the spawn to fail.
*
* `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process.
* This has the same semantics as the uid field.
*
* 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 {
/** Stylize output with ANSI colors. Defaults to false. */
colors?: boolean;
/** Try to fit more than one entry of a collection on the same line.
* Defaults to true. */
compact?: boolean;
/** Traversal depth for nested objects. Defaults to 4. */
depth?: number;
/** The maximum number of iterable entries to print. Defaults to 100. */
iterableLimit?: number;
/** Show a Proxy's target and handler. Defaults to false. */
showProxy?: boolean;
/** 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;
/*** Evaluate the result of calling getters. Defaults to false. */
getters?: boolean;
/** Show an object's non-enumerable properties. Defaults to false. */
showHidden?: boolean;
}
/** Converts the input into a string that has the same format as printed by
* `console.log()`.
*
* ```ts
* const obj = {
* a: 10,
* b: "hello",
* };
* const objAsString = Deno.inspect(obj); // { a: 10, b: "hello" }
* console.log(obj); // prints same value as objAsString, e.g. { a: 10, b: "hello" }
* ```
*
* You can also register custom inspect functions, via the symbol `Symbol.for("Deno.customInspect")`,
* on objects, to control and customize the output.
*
* ```ts
* class A {
* x = 10;
* y = "hello";
* [Symbol.for("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.
*
* ```ts
* Deno.inspect({a: {b: {c: {d: 'hello'}}}}, {depth: 2}); // { a: { b: [Object] } }
* ```
*/
export function inspect(value: unknown, options?: InspectOptions): string;
/** The name of a "powerful feature" which needs permission. */
export type PermissionName =
| "run"
| "read"
| "write"
| "net"
| "env"
| "ffi"
| "hrtime";
/** The current status of the permission. */
export type PermissionState = "granted" | "denied" | "prompt";
export interface RunPermissionDescriptor {
name: "run";
command?: string | URL;
}
export interface ReadPermissionDescriptor {
name: "read";
path?: string | URL;
}
export interface WritePermissionDescriptor {
name: "write";
path?: string | URL;
}
export interface NetPermissionDescriptor {
name: "net";
/** Optional host string of the form `"<hostname>[:<port>]"`. Examples:
*
* "github.com"
* "deno.land:8080"
*/
host?: string;
}
export interface EnvPermissionDescriptor {
name: "env";
variable?: string;
}
export interface FfiPermissionDescriptor {
name: "ffi";
path?: string | URL;
}
export interface HrtimePermissionDescriptor {
name: "hrtime";
}
/** Permission descriptors which define a permission and can be queried,
* requested, or revoked. */
export type PermissionDescriptor =
| RunPermissionDescriptor
| ReadPermissionDescriptor
| WritePermissionDescriptor
| NetPermissionDescriptor
| EnvPermissionDescriptor
| FfiPermissionDescriptor
| HrtimePermissionDescriptor;
export interface PermissionStatusEventMap {
"change": Event;
}
export class PermissionStatus extends EventTarget {
// deno-lint-ignore no-explicit-any
onchange: ((this: PermissionStatus, ev: Event) => any) | null;
readonly state: PermissionState;
addEventListener<K extends keyof PermissionStatusEventMap>(
type: K,
listener: (
this: PermissionStatus,
ev: PermissionStatusEventMap[K],
) => any,
options?: boolean | AddEventListenerOptions,
): void;
addEventListener(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void;
removeEventListener<K extends keyof PermissionStatusEventMap>(
type: K,
listener: (
this: PermissionStatus,
ev: PermissionStatusEventMap[K],
) => any,
options?: boolean | EventListenerOptions,
): void;
removeEventListener(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void;
}
export class Permissions {
/** Resolves to the current status of a permission.
*
* ```ts
* const status = await Deno.permissions.query({ name: "read", path: "/etc" });
* console.log(status.state);
* ```
*/
query(desc: PermissionDescriptor): Promise<PermissionStatus>;
/** Revokes a permission, and resolves to the state of the permission.
*
* ```ts
* import { assert } from "https://deno.land/std/testing/asserts.ts";
*
* const status = await Deno.permissions.revoke({ name: "run" });
* assert(status.state !== "granted")
* ```
*/
revoke(desc: PermissionDescriptor): Promise<PermissionStatus>;
/** Requests the permission, and resolves to the state of the permission.
*
* ```ts
* const status = await Deno.permissions.request({ name: "env" });
* if (status.state === "granted") {
* console.log("'env' permission is granted.");
* } else {
* console.log("'env' permission is denied.");
* }
* ```
*/
request(desc: PermissionDescriptor): Promise<PermissionStatus>;
}
/** Deno's permission management API. */
export const permissions: Permissions;
/** Build related information. */
export const build: {
/** The LLVM target triple */
target: string;
/** Instruction set architecture */
arch: "x86_64" | "aarch64";
/** Operating system */
os: "darwin" | "linux" | "windows";
/** Computer vendor */
vendor: string;
/** Optional environment */
env?: string;
};
/** Version related information. */
export const version: {
/** Deno's version. For example: `"1.0.0"` */
deno: string;
/** The V8 version used by Deno. For example: `"8.0.0.0"` */
v8: string;
/** The TypeScript version used by Deno. For example: `"4.0.0"` */
typescript: string;
};
/** 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.
*
* @deprecated This symbol is deprecated since 1.9. Use
* `Symbol.for("Deno.customInspect")` instead.
*/
export const customInspect: unique symbol;
/** The URL of the entrypoint module entered from the command-line. */
export const mainModule: string;
export type SymlinkOptions = {
type: "file" | "dir";
};
/**
* Creates `newpath` as a symbolic link to `oldpath`.
*
* The options.type parameter can be set to `file` or `dir`. This argument is only
* available on Windows and ignored on other platforms.
*
* ```ts
* Deno.symlinkSync("old/name", "new/name");
* ```
*
* Requires full `allow-read` and `allow-write` permissions. */
export function symlinkSync(
oldpath: string | URL,
newpath: string | URL,
options?: SymlinkOptions,
): void;
/**
* Creates `newpath` as a symbolic link to `oldpath`.
*
* The options.type parameter can be set to `file` or `dir`. This argument is only
* available on Windows and ignored on other platforms.
*
* ```ts
* await Deno.symlink("old/name", "new/name");
* ```
*
* Requires full `allow-read` and `allow-write` permissions. */
export function symlink(
oldpath: string | URL,
newpath: string | URL,
options?: SymlinkOptions,
): Promise<void>;
/**
* Synchronously truncates or extends the specified file stream, to reach the
* specified `len`.
*
* If `len` is not specified then the entire file contents are truncated as if len was set to 0.
*
* if the file previously was larger than this new length, the extra data is lost.
*
* if the file previously was shorter, it is extended, and the extended part reads as null bytes ('\0').
*
* ```ts
* // truncate the entire file
* const file = Deno.openSync("my_file.txt", { read: true, write: true, truncate: true, create: true });
* Deno.ftruncateSync(file.rid);
* ```
*
* ```ts
* // truncate part of the file
* const file = Deno.openSync("my_file.txt", { read: true, write: true, create: true });
* Deno.writeSync(file.rid, new TextEncoder().encode("Hello World"));
* Deno.ftruncateSync(file.rid, 7);
* Deno.seekSync(file.rid, 0, Deno.SeekMode.Start);
* const data = new Uint8Array(32);
* Deno.readSync(file.rid, data);
* console.log(new TextDecoder().decode(data)); // Hello W
* ```
*/
export function ftruncateSync(rid: number, len?: number): void;
/**
* Truncates or extends the specified file stream, to reach the specified `len`.
*
* If `len` is not specified then the entire file contents are truncated as if len was set to 0.
*
* If the file previously was larger than this new length, the extra data is lost.
*
* If the file previously was shorter, it is extended, and the extended part reads as null bytes ('\0').
*
* ```ts
* // truncate the entire file
* const file = await Deno.open("my_file.txt", { read: true, write: true, create: true });
* await Deno.ftruncate(file.rid);
* ```
*
* ```ts
* // truncate part of the file
* const file = await Deno.open("my_file.txt", { read: true, write: true, create: true });
* await Deno.write(file.rid, new TextEncoder().encode("Hello World"));
* await Deno.ftruncate(file.rid, 7);
* const data = new Uint8Array(32);
* await Deno.read(file.rid, data);
* console.log(new TextDecoder().decode(data)); // Hello W
* ```
*/
export function ftruncate(rid: number, len?: number): Promise<void>;
/**
* Synchronously returns a `Deno.FileInfo` for the given file stream.
*
* ```ts
* import { assert } from "https://deno.land/std/testing/asserts.ts";
* const file = Deno.openSync("file.txt", { read: true });
* const fileInfo = Deno.fstatSync(file.rid);
* assert(fileInfo.isFile);
* ```
*/
export function fstatSync(rid: number): FileInfo;
/**
* Returns a `Deno.FileInfo` for the given file stream.
*
* ```ts
* import { assert } from "https://deno.land/std/testing/asserts.ts";
* const file = await Deno.open("file.txt", { read: true });
* const fileInfo = await Deno.fstat(file.rid);
* assert(fileInfo.isFile);
* ```
*/
export function fstat(rid: number): Promise<FileInfo>;
export interface RequestEvent {
readonly request: Request;
respondWith(r: Response | Promise<Response>): Promise<void>;
}
export interface HttpConn extends AsyncIterable<RequestEvent> {
readonly rid: number;
nextRequest(): Promise<RequestEvent | null>;
close(): void;
}
/**
* Services HTTP requests given a TCP or TLS socket.
*
* ```ts
* const conn = await Deno.listen({ port: 80 });
* const httpConn = Deno.serveHttp(await conn.accept());
* const e = await httpConn.nextRequest();
* if (e) {
* e.respondWith(new Response("Hello World"));
* }
* ```
*
* If `httpConn.nextRequest()` encounters an error or returns `null`
* then the underlying HttpConn resource is closed automatically.
*
* Alternatively, you can also use the Async Iterator approach:
*
* ```ts
* async function handleHttp(conn: Deno.Conn) {
* for await (const e of Deno.serveHttp(conn)) {
* e.respondWith(new Response("Hello World"));
* }
* }
*
* for await (const conn of Deno.listen({ port: 80 })) {
* handleHttp(conn);
* }
* ```
*/
export function serveHttp(conn: Conn): HttpConn;
export interface WebSocketUpgrade {
response: Response;
socket: WebSocket;
}
export interface UpgradeWebSocketOptions {
protocol?: string;
/**
* If the client does not respond to this frame with a
* `pong` within the timeout specified, the connection is deemed
* unhealthy and is closed. The `close` and `error` event will be emitted.
*
* The default is 120 seconds. Set to 0 to disable timeouts.
*/
idleTimeout?: number;
}
/**
* Used to upgrade an incoming HTTP request to a WebSocket.
*
* Given a request, returns a pair of WebSocket and Response. The original
* request must be responded to with the returned response for the websocket
* upgrade to be successful.
*
* ```ts
* const conn = await Deno.listen({ port: 80 });
* const httpConn = Deno.serveHttp(await conn.accept());
* const e = await httpConn.nextRequest();
* if (e) {
* const { socket, response } = Deno.upgradeWebSocket(e.request);
* socket.onopen = () => {
* socket.send("Hello World!");
* };
* socket.onmessage = (e) => {
* console.log(e.data);
* socket.close();
* };
* socket.onclose = () => console.log("WebSocket has been closed.");
* socket.onerror = (e) => console.error("WebSocket error:", e);
* e.respondWith(response);
* }
* ```
*
* If the request body is disturbed (read from) before the upgrade is
* completed, upgrading fails.
*
* This operation does not yet consume the request or open the websocket. This
* only happens once the returned response has been passed to `respondWith`.
*/
export function upgradeWebSocket(
request: Request,
options?: UpgradeWebSocketOptions,
): WebSocketUpgrade;
/** Send a signal to process under given `pid`.
*
* If `pid` is negative, the signal will be sent to the process group
* identified by `pid`.
*
* ```ts
* const p = Deno.run({
* cmd: ["sleep", "10000"]
* });
*
* Deno.kill(p.pid, "SIGINT");
* ```
*
* Requires `allow-run` permission. */
export function kill(pid: number, signo: Signal): void;
/** The type of the resource record.
* Only the listed types are supported currently. */
export type RecordType =
| "A"
| "AAAA"
| "ANAME"
| "CNAME"
| "MX"
| "PTR"
| "SRV"
| "TXT";
export interface ResolveDnsOptions {
/** The name server to be used for lookups.
* If not specified, defaults to the system configuration e.g. `/etc/resolv.conf` on Unix. */
nameServer?: {
/** The IP address of the name server */
ipAddr: string;
/** The port number the query will be sent to.
* If not specified, defaults to 53. */
port?: number;
};
}
/** If `resolveDns` is called with "MX" record type specified, it will return an array of this interface. */
export interface MXRecord {
preference: number;
exchange: string;
}
/** If `resolveDns` is called with "SRV" record type specified, it will return an array of this interface. */
export interface SRVRecord {
priority: number;
weight: number;
port: number;
target: string;
}
export function resolveDns(
query: string,
recordType: "A" | "AAAA" | "ANAME" | "CNAME" | "PTR",
options?: ResolveDnsOptions,
): Promise<string[]>;
export function resolveDns(
query: string,
recordType: "MX",
options?: ResolveDnsOptions,
): Promise<MXRecord[]>;
export function resolveDns(
query: string,
recordType: "SRV",
options?: ResolveDnsOptions,
): Promise<SRVRecord[]>;
export function resolveDns(
query: string,
recordType: "TXT",
options?: ResolveDnsOptions,
): Promise<string[][]>;
/**
* Performs DNS resolution against the given query, returning resolved records.
* Fails in the cases such as:
* - the query is in invalid format
* - the options have an invalid parameter, e.g. `nameServer.port` is beyond the range of 16-bit unsigned integer
* - timed out
*
* ```ts
* const a = await Deno.resolveDns("example.com", "A");
*
* const aaaa = await Deno.resolveDns("example.com", "AAAA", {
* nameServer: { ipAddr: "8.8.8.8", port: 53 },
* });
* ```
*
* Requires `allow-net` permission.
*/
export function resolveDns(
query: string,
recordType: RecordType,
options?: ResolveDnsOptions,
): Promise<string[] | MXRecord[] | SRVRecord[] | string[][]>;
}