class Deno.FsFile
implements Disposable
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 discrete functions within the `Deno` namespace.
```ts
using 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"
}
```
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.
```ts
using 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));
}
```
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.
```ts
const items = ["hello", "world"];
using 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));
}
```
[Symbol.dispose](): void
close(): void
Close the file. Closing a file when you are finished with it is
important to avoid leaking resources.
```ts
using file = await Deno.open("my_file.txt");
// do work with "file" object
```
isTerminal(): boolean
Checks if the file resource is a TTY (terminal).
```ts
// This example is system and context specific
using file = await Deno.open("/dev/tty6");
file.isTerminal(); // true
```
lock(exclusive?: boolean): Promise<void>
Acquire an advisory file-system lock for the file.
lockSync(exclusive?: boolean): void
Synchronously acquire an advisory file-system lock synchronously for the file.
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.**
```ts
// if "/foo/bar.txt" contains the text "hello world":
using 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"
```
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.**
```ts
// if "/foo/bar.txt" contains the text "hello world":
using 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"
```
Seek 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 the file contains "Hello world" text, which is 11 bytes long:
using 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"
```
The seek modes work as follows:
```ts
// Given the file contains "Hello world" text, 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" (i.e. 11-2)
```
Synchronously seek to the given `offset` under mode given by `whence`.
The new position within the resource (bytes from the start) is returned.
```ts
using 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"
```
The seek modes work as follows:
```ts
// Given the file contains "Hello world" text, which is 11 bytes long:
using 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" (i.e. 11-2)
```
setRaw(mode: boolean,options?: SetRawOptions,): void
Set TTY to be under raw mode or not. In raw mode, characters are read and
returned as is, without being processed. All special processing of
characters by the terminal is disabled, including echoing input
characters. Reading from a TTY device in raw mode is faster than reading
from a TTY device in canonical mode.
```ts
using file = await Deno.open("/dev/tty6");
file.setRaw(true, { cbreak: true });
```
Resolves to a [`Deno.FileInfo`](../././~/Deno.FileInfo) for the file.
```ts
import { assert } from "jsr:@std/assert";
using file = await Deno.open("hello.txt");
const fileInfo = await file.stat();
assert(fileInfo.isFile);
```
Synchronously returns a [`Deno.FileInfo`](../././~/Deno.FileInfo) for the file.
```ts
import { assert } from "jsr:@std/assert";
using file = Deno.openSync("hello.txt")
const fileInfo = file.statSync();
assert(fileInfo.isFile);
```
sync(): Promise<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 file.write(new TextEncoder().encode("Hello World"));
await file.truncate(1);
await file.sync();
console.log(await Deno.readTextFile("my_file.txt")); // H
```
syncData(): Promise<void>
Flushes any pending data operations of the given file stream to disk.
```ts
using file = await Deno.open(
"my_file.txt",
{ read: true, write: true, create: true },
);
await file.write(new TextEncoder().encode("Hello World"));
await file.syncData();
console.log(await Deno.readTextFile("my_file.txt")); // Hello World
```
syncDataSync(): void
Synchronously flushes any pending data operations of the given file stream
to disk.
```ts
using file = Deno.openSync(
"my_file.txt",
{ read: true, write: true, create: true },
);
file.writeSync(new TextEncoder().encode("Hello World"));
file.syncDataSync();
console.log(Deno.readTextFileSync("my_file.txt")); // Hello World
```
syncSync(): void
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 },
);
file.writeSync(new TextEncoder().encode("Hello World"));
file.truncateSync(1);
file.syncSync();
console.log(Deno.readTextFileSync("my_file.txt")); // H
```
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
```ts
using file = await Deno.open("my_file.txt", { write: true });
await file.truncate();
```
### Truncate part of the file
```ts
// if "my_file.txt" contains the text "hello world":
using 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"
```
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
```ts
using file = Deno.openSync("my_file.txt", { write: true });
file.truncateSync();
```
### Truncate part of the file
```ts
// if "my_file.txt" contains the text "hello world":
using 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"
```
unlock(): Promise<void>
Release an advisory file-system lock for the file.
unlockSync(): void
Synchronously release an advisory file-system lock for the file.
utime(atime: number | Date,mtime: number | Date,): Promise<void>
Changes the access (`atime`) and modification (`mtime`) times of the
file stream resource. Given times are either in seconds (UNIX epoch
time) or as `Date` objects.
```ts
using file = await Deno.open("file.txt", { create: true, write: true });
await file.utime(1556495550, new Date());
```
utimeSync(atime: number | Date,mtime: number | Date,): void
Synchronously changes the access (`atime`) and modification (`mtime`)
times of the file stream resource. Given times are either in seconds
(UNIX epoch time) or as `Date` objects.
```ts
using file = Deno.openSync("file.txt", { create: true, write: true });
file.utime(1556495550, new Date());
```
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.**
```ts
const encoder = new TextEncoder();
const data = encoder.encode("Hello world");
using file = await Deno.open("/foo/bar.txt", { write: true });
const bytesWritten = await file.write(data); // 11
```
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.**
```ts
const encoder = new TextEncoder();
const data = encoder.encode("Hello world");
using file = Deno.openSync("/foo/bar.txt", { write: true });
const bytesWritten = file.writeSync(data); // 11
```