class Deno.FsFile

The Deno abstraction for reading and writing files.

This is the most straight forward way of handling files within Deno and is recommended over using the discreet functions within the Deno namespace.

const file = await Deno.open("/foo/bar.txt", { read: true });
const fileInfo = await file.stat();
if (fileInfo.isFile) {
  const buf = new Uint8Array(100);
  const numberOfBytesRead = await file.read(buf); // 11 bytes
  const text = new TextDecoder().decode(buf);  // "hello world"
}
file.close();

Constructors

new
FsFile(rid: number)

The constructor which takes a resource ID. Generally FsFile should not be constructed directly. Instead use Deno.open or Deno.openSync to create a new instance of FsFile.

Properties

readonly
readable: ReadableStream<Uint8Array>

A ReadableStream instance representing to the byte contents of the file. This makes it easy to interoperate with other web streams based APIs.

const file = await Deno.open("my_file.txt", { read: true });
const decoder = new TextDecoder();
for await (const chunk of file.readable) {
  console.log(decoder.decode(chunk));
}
file.close();
readonly
rid: number

The resource ID associated with the file instance. The resource ID should be considered an opaque reference to resource.

readonly
writable: WritableStream<Uint8Array>

A WritableStream instance to write the contents of the file. This makes it easy to interoperate with other web streams based APIs.

const items = ["hello", "world"];
const file = await Deno.open("my_file.txt", { write: true });
const encoder = new TextEncoder();
const writer = file.writable.getWriter();
for (const item of items) {
  await writer.write(encoder.encode(item));
}
file.close();

Methods

close(): void

Close the file. Closing a file when you are finished with it is important to avoid leaking resources.

const file = await Deno.open("my_file.txt");
// do work with "file" object
file.close();
read(p: Uint8Array): Promise<number | null>

Read the file into an array buffer (p).

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.

It is not guaranteed that the full buffer will be read in a single call.

// 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 file.read(buf); // 11 bytes
const text = new TextDecoder().decode(buf);  // "hello world"
file.close();
readSync(p: Uint8Array): number | null

Synchronously read from the file into an array buffer (p).

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.

It is not guaranteed that the full buffer will be read in a single call.

// if "/foo/bar.txt" contains the text "hello world":
const file = Deno.openSync("/foo/bar.txt");
const buf = new Uint8Array(100);
const numberOfBytesRead = file.readSync(buf); // 11 bytes
const text = new TextDecoder().decode(buf);  // "hello world"
file.close();
seek(offset: number, whence: SeekMode): Promise<number>

Seek to the given offset under mode given by whence. The call resolves to the new position within the resource (bytes from the start).

// Given file 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 file.write(new TextEncoder().encode("Hello world"));

// advance cursor 6 bytes
const cursorPosition = await file.seek(6, Deno.SeekMode.Start);
console.log(cursorPosition);  // 6
const buf = new Uint8Array(100);
await file.read(buf);
console.log(new TextDecoder().decode(buf)); // "world"
file.close();

The seek modes work as follows:

// 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 file.write(new TextEncoder().encode("Hello world"));

// Seek 6 bytes from the start of the file
console.log(await file.seek(6, Deno.SeekMode.Start)); // "6"
// Seek 2 more bytes from the current position
console.log(await file.seek(2, Deno.SeekMode.Current)); // "8"
// Seek backwards 2 bytes from the end of the file
console.log(await file.seek(-2, Deno.SeekMode.End)); // "9" (e.g. 11-2)
seekSync(offset: number, whence: SeekMode): number

Synchronously seek to the given offset under mode given by whence. The new position within the resource (bytes from the start) is returned.

const file = Deno.openSync(
  "hello.txt",
  { read: true, write: true, truncate: true, create: true },
);
file.writeSync(new TextEncoder().encode("Hello world"));

// advance cursor 6 bytes
const cursorPosition = file.seekSync(6, Deno.SeekMode.Start);
console.log(cursorPosition);  // 6
const buf = new Uint8Array(100);
file.readSync(buf);
console.log(new TextDecoder().decode(buf)); // "world"
file.close();

The seek modes work as follows:

// 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 },
);
file.writeSync(new TextEncoder().encode("Hello world"));

// Seek 6 bytes from the start of the file
console.log(file.seekSync(6, Deno.SeekMode.Start)); // "6"
// Seek 2 more bytes from the current position
console.log(file.seekSync(2, Deno.SeekMode.Current)); // "8"
// Seek backwards 2 bytes from the end of the file
console.log(file.seekSync(-2, Deno.SeekMode.End)); // "9" (e.g. 11-2)
file.close();
stat(): Promise<FileInfo>

Resolves to a Deno.FileInfo for the file.

import { assert } from "https://deno.land/std/testing/asserts.ts";

const file = await Deno.open("hello.txt");
const fileInfo = await file.stat();
assert(fileInfo.isFile);
file.close();
statSync(): FileInfo

Synchronously returns a Deno.FileInfo for the file.

import { assert } from "https://deno.land/std/testing/asserts.ts";

const file = Deno.openSync("hello.txt")
const fileInfo = file.statSync();
assert(fileInfo.isFile);
file.close();
truncate(len?: number): Promise<void>

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

Truncate the entire file

const file = await Deno.open("my_file.txt", { write: true });
await file.truncate();
file.close();

Truncate part of the file

// if "my_file.txt" contains the text "hello world":
const file = await Deno.open("my_file.txt", { write: true });
await file.truncate(7);
const buf = new Uint8Array(100);
await file.read(buf);
const text = new TextDecoder().decode(buf); // "hello w"
file.close();
truncateSync(len?: number): void

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

Truncate the entire file

const file = Deno.openSync("my_file.txt", { write: true });
file.truncateSync();
file.close();

Truncate part of the file

// if "my_file.txt" contains the text "hello world":
const file = Deno.openSync("my_file.txt", { write: true });
file.truncateSync(7);
const buf = new Uint8Array(100);
file.readSync(buf);
const text = new TextDecoder().decode(buf); // "hello w"
file.close();
write(p: Uint8Array): Promise<number>

Write the contents of the array buffer (p) to the file.

Resolves to the number of bytes written.

It is not guaranteed that the full buffer will be written in a single call.

const encoder = new TextEncoder();
const data = encoder.encode("Hello world");
const file = await Deno.open("/foo/bar.txt", { write: true });
const bytesWritten = await file.write(data); // 11
file.close();
writeSync(p: Uint8Array): number

Synchronously write the contents of the array buffer (p) to the file.

Returns the number of bytes written.

It is not guaranteed that the full buffer will be written in a single call.

const encoder = new TextEncoder();
const data = encoder.encode("Hello world");
const file = Deno.openSync("/foo/bar.txt", { write: true });
const bytesWritten = file.writeSync(data); // 11
file.close();