File System

Changes the permission of a specific file/directory of specified path. Ignores the process's umask.

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.

Note: On Windows, only the read and write permissions can be modified. Distinctions between owner, group, and others are not supported.

Requires allow-write permission.

Synchronously changes the permission of a specific file/directory of specified path. Ignores the process's umask.

Deno.chmodSync("/path/to/file", 0o666);

For a full description, see Deno.chmod.

Requires allow-write permission.

Change owner of a regular file or directory.

This functionality is not available on Windows.

await Deno.chown("myFile.txt", 1000, 1002);

Requires allow-write permission.

Throws Error (not implemented) if executed on Windows.

Synchronously change owner of a regular file or directory.

This functionality is not available on Windows.

Deno.chownSync("myFile.txt", 1000, 1002);

Requires allow-write permission.

Throws Error (not implemented) if executed on Windows.

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.

await Deno.copyFile("from.txt", "to.txt");

Requires allow-read permission on fromPath.

Requires allow-write permission on toPath.

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.

Deno.copyFileSync("from.txt", "to.txt");

Requires allow-read permission on fromPath.

Requires allow-write permission on toPath.

Creates a file if none exists or truncates an existing file and resolves to an instance of Deno.FsFile.

const file = await Deno.create("/foo/bar.txt");

Requires allow-read and allow-write permissions.

Creates a file if none exists or truncates an existing file and returns an instance of Deno.FsFile.

const file = Deno.createSync("/foo/bar.txt");

Requires allow-read and allow-write permissions.

Creates newpath as a hard link to oldpath.

await Deno.link("old/name", "new/name");

Requires allow-read and allow-write permissions.

Synchronously creates newpath as a hard link to oldpath.

Deno.linkSync("old/name", "new/name");

Requires allow-read and allow-write permissions.

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.

import { assert } from "jsr:@std/assert";
const fileInfo = await Deno.lstat("hello.txt");
assert(fileInfo.isFile);

Requires allow-read permission.

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.

import { assert } from "jsr:@std/assert";
const fileInfo = Deno.lstatSync("hello.txt");
assert(fileInfo.isFile);

Requires allow-read permission.

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.

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.

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.

const tempDirName0 = Deno.makeTempDirSync();  // e.g. /tmp/2894ea76
const tempDirName1 = Deno.makeTempDirSync({ prefix: 'my_temp' });  // e.g. /tmp/my_temp339c944d

Requires allow-write permission.

Creates a new temporary file in the default directory for temporary files, unless dir is specified.

Other 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.

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.

Synchronously creates a new temporary file in the default directory for temporary files, unless dir is specified.

Other 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.

const tempFileName0 = Deno.makeTempFileSync(); // e.g. /tmp/419e0bf2
const tempFileName1 = Deno.makeTempFileSync({ prefix: 'my_temp' });  // e.g. /tmp/my_temp754d3098

Requires allow-write permission.

Creates a new directory with the specified path.

await Deno.mkdir("new_dir");
await Deno.mkdir("nested/directories", { recursive: true });
await Deno.mkdir("restricted_access_dir", { mode: 0o700 });

Throws if the directory already exists, unless recursive is set to true.

Requires allow-write permission.

Synchronously creates a new directory with the specified path.

Deno.mkdirSync("new_dir");
Deno.mkdirSync("nested/directories", { recursive: true });
Deno.mkdirSync("restricted_access_dir", { mode: 0o700 });

Throws if the directory already exists, unless recursive is set to true.

Requires allow-write permission.

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. The caller may have the resulting file automatically closed by the runtime once it's out of scope by declaring the file variable with the using keyword.

using file = await Deno.open("/foo/bar.txt", { read: true, write: true });
// Do work with file

Alternatively, the caller may manually close the resource when finished with it.

const file = await Deno.open("/foo/bar.txt", { read: true, write: true });
// Do work with file
file.close();

Requires allow-read and/or allow-write permissions depending on options.

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. The caller may have the resulting file automatically closed by the runtime once it's out of scope by declaring the file variable with the using keyword.

using file = Deno.openSync("/foo/bar.txt", { read: true, write: true });
// Do work with file

Alternatively, the caller may manually close the resource when finished with it.

const file = Deno.openSync("/foo/bar.txt", { read: true, write: true });
// Do work with file
file.close();

Requires allow-read and/or allow-write permissions depending on options.

Reads the directory given by path and returns an async iterable of Deno.DirEntry. The order of entries is not guaranteed.

for await (const dirEntry of Deno.readDir("/")) {
  console.log(dirEntry.name);
}

Throws error if path is not a directory.

Requires allow-read permission.

Synchronously reads the directory given by path and returns an iterable of Deno.DirEntry. The order of entries is not guaranteed.

for (const dirEntry of Deno.readDirSync("/")) {
  console.log(dirEntry.name);
}

Throws error if path is not a directory.

Requires allow-read permission.

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. Rejects with an error when reading a directory.

const decoder = new TextDecoder("utf-8");
const data = await Deno.readFile("hello.txt");
console.log(decoder.decode(data));

Requires allow-read permission.

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. Throws an error when reading a directory.

const decoder = new TextDecoder("utf-8");
const data = Deno.readFileSync("hello.txt");
console.log(decoder.decode(data));

Requires allow-read permission.

Resolves to the full path destination of the named symbolic link.

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.

Synchronously returns the full path destination of the named symbolic link.

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.

Asynchronously reads and returns the entire contents of a file as an UTF-8 decoded string.

const data = await Deno.readTextFile("hello.txt");
console.log(data);

The returned promise rejects if the operation fails, for example with Deno.errors.NotFound if the file does not exist, Deno.errors.IsADirectory if path refers to a directory, or Deno.errors.PermissionDenied if the required permission has not been granted.

Requires allow-read permission.

Synchronously reads and returns the entire contents of a file as an UTF-8 decoded string.

const data = Deno.readTextFileSync("hello.txt");
console.log(data);

Throws if the operation fails, for example with Deno.errors.NotFound if the file does not exist, Deno.errors.IsADirectory if path refers to a directory, or Deno.errors.PermissionDenied if the required permission has not been granted.

Requires allow-read permission.

Resolves to the absolute normalized path, with symbolic links resolved.

// 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.

Synchronously returns absolute normalized path, with symbolic links resolved.

// 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.

Removes the named file or directory.

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.

Synchronously removes the named file or directory.

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.

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.

await Deno.rename("old/path", "new/path");

On Unix-like OSes, 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.

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.

Deno.renameSync("old/path", "new/path");

On Unix-like OSes, 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.

Resolves to a Deno.FileInfo for the specified path. Will always follow symlinks.

import { assert } from "jsr:@std/assert";
const fileInfo = await Deno.stat("hello.txt");
assert(fileInfo.isFile);

Requires allow-read permission.

Synchronously returns a Deno.FileInfo for the specified path. Will always follow symlinks.

import { assert } from "jsr:@std/assert";
const fileInfo = Deno.statSync("hello.txt");
assert(fileInfo.isFile);

Requires allow-read permission.

Creates newpath as a symbolic link to oldpath.

The options.type parameter can be set to "file", "dir" or "junction". This argument is only available on Windows and ignored on other platforms.

await Deno.symlink("old/name", "new/name");

Requires allow-read and allow-write permissions granted without a path scope (i.e. --allow-read --allow-write, not --allow-read=./dir --allow-write=./dir). A symlink's target may be a relative, absolute, or not-yet-existing path that is only resolved when the link is later traversed, so it cannot be checked against a path-scoped allow-list at creation time. Path-scoped grants are therefore rejected.

Creates newpath as a symbolic link to oldpath.

The options.type parameter can be set to "file", "dir" or "junction". This argument is only available on Windows and ignored on other platforms.

Deno.symlinkSync("old/name", "new/name");

Requires allow-read and allow-write permissions granted without a path scope (i.e. --allow-read --allow-write, not --allow-read=./dir --allow-write=./dir). A symlink's target may be a relative, absolute, or not-yet-existing path that is only resolved when the link is later traversed, so it cannot be checked against a path-scoped allow-list at creation time. Path-scoped grants are therefore rejected.

Truncates (or extends) the specified file, to reach the specified len. If len is not specified then the entire file contents are truncated.

Truncate the entire file

await Deno.truncate("my_file.txt");

Truncate part of the file

const file = await Deno.makeTempFile();
await Deno.writeTextFile(file, "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.

Synchronously truncates (or extends) the specified file, to reach the specified len. If len is not specified then the entire file contents are truncated.

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.

Retrieve the process umask. If mask is provided, sets the process umask. This call always returns what the umask was before the call.

console.log(Deno.umask());  // e.g. 18 (0o022)
const prevUmaskValue = Deno.umask(0o077);  // e.g. 18 (0o022)
console.log(Deno.umask());  // e.g. 63 (0o077)

Requires allow-sys="umask" permission.

Note: This API is not implemented on Windows

Changes the access (atime) and modification (mtime) times of a file system object referenced by path. Given times are either in seconds (UNIX epoch time) or as Date objects.

await Deno.utime("myfile.txt", 1556495550, new Date());

Requires allow-write permission.

Synchronously changes the access (atime) and modification (mtime) times of a file system object referenced by path. Given times are either in seconds (UNIX epoch time) or as Date objects.

Deno.utimeSync("myfile.txt", 1556495550, new Date());

Requires allow-write permission.

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).

The 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.

const watcher = Deno.watchFs("/");
for await (const event of watcher) {
   console.log(">>>> event", event);
   // { kind: "create", paths: [ "/foo.txt" ] }
}

The ignore option can be used to filter out events for one or more paths. A path matches when it is, or is contained within, an ignored path, so ignoring a directory ignores everything beneath it. Relative paths are resolved against the current working directory. Ignored paths still require allow-read permission, the same as the watched paths.

// Watch the project but skip the `.git` directory and `build` output.
const watcher = Deno.watchFs(".", { ignore: [".git", "build"] });

Call watcher.close() to stop watching.

const watcher = Deno.watchFs("/");

setTimeout(() => {
  watcher.close();
}, 5000);

for await (const event of watcher) {
   console.log(">>>> event", event);
}

Requires allow-read permission.

Write data to the given path, by default creating a new file if needed, else overwriting.

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.

Synchronously write data to the given path, by default creating a new file if needed, else overwriting.

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.

Write string data to the given path, by default creating a new file if needed, else overwriting.

await Deno.writeTextFile("hello1.txt", "Hello world\n");  // overwrite "hello1.txt" or create it

The data is written to the file and the file is closed, but this does not guarantee that the contents have been flushed from the operating system's buffers to the physical storage device. If you need such a durability guarantee (for example before signalling that a write has been committed), open the file with Deno.open and call Deno.FsFile.sync before closing it.

Requires allow-write permission, and allow-read if options.create is false.

Synchronously write string data to the given path, by default creating a new file if needed, else overwriting.

Deno.writeTextFileSync("hello1.txt", "Hello world\n");  // overwrite "hello1.txt" or create it

As with Deno.writeTextFile, the data is written and the file is closed, but this does not guarantee the contents have been flushed from the operating system's buffers to the physical storage device. If you need such a durability guarantee, open the file with Deno.openSync and call Deno.FsFile.syncSync before closing it.

Requires allow-write permission, and allow-read if options.create is false.