foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-12-23 07:44:48 -05:00
Code Issues Packages 1 Wiki Activity
denoland-deno/cli/dts/lib.deno.ns.d.ts
Geert-Jan Zwiers 6613a312b1
docs: code example to structuredClone, CompressionStream, DecompressionStream (#13719) 
Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>
2022-02-22 20:41:59 +01:00

3008 lines
102 KiB
TypeScript
Vendored
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

// 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[][]>;
}
View git blame Copy permalink