FsFile

import { FsFile } from "jsr:@ende/fs/unstable-types";

interface · experimental

interface FsFile extends Disposable

The abstraction for reading and writing files.

This is the most straight forward way of handling files and is recommended over using the discrete functions.

Example: Usage

import { open } from "@ende/fs/unstable-open";
using file = await 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"
}

Properties

`readable`

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.

Example: Usage

import { open } from "@ende/fs/unstable-open";
using file = await open("my_file.txt", { read: true });
const decoder = new TextDecoder();
for await (const chunk of file.readable) {
  console.log(decoder.decode(chunk));
}

`writable`

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.

Example: Usage

import { open } from "@ende/fs/unstable-open";
const items = ["hello", "world"];
using file = await 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));
}

Methods

`close`

close(): void

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

Example: Usage

import { open } from "@ende/fs/unstable-open";
using file = await open("my_file.txt");
// do work with "file" object

`[Symbol.dispose]`

[Symbol.dispose](): void

Disposal protocol enabling the using keyword TypeScript Only

`isTerminal`

isTerminal(): boolean

Checks if the file resource is a TTY (terminal).

Example: Usage

// This example is system and context specific
import { open } from "@ende/fs/unstable-open";
using file = await open("/dev/tty6");
file.isTerminal(); // true

`lock`

lock(exclusive?: boolean): Promise<void>

Acquire an advisory file-system lock for the file.

Default: false

`lockSync`

lockSync(exclusive?: boolean): void

Synchronously acquire an advisory file-system lock synchronously for the file.

Default: false

`read`

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.

Example: Usage

import { open } from "@ende/fs/unstable-open";
// if "/foo/bar.txt" contains the text "hello world":
using file = await 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`

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.

Example: Usage

import { openSync } from "@ende/fs/unstable-open";
// if "/foo/bar.txt" contains the text "hello world":
using file = openSync("/foo/bar.txt");
const buf = new Uint8Array(100);
const numberOfBytesRead = file.readSync(buf); // 11 bytes
const text = new TextDecoder().decode(buf);  // "hello world"

`setRaw`

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.

Example: Usage

import { open } from "@ende/fs/unstable-open";
using file = await open("/dev/tty6");
file.setRaw(true, { cbreak: true });

`stat`

stat(): Promise<FileInfo>

Resolves to a FileInfo for the file.

Example: Usage

import { assert } from "@ende/assert";
import { open } from "@ende/fs/unstable-open";
using file = await open("hello.txt");
const fileInfo = await file.stat();
assert(fileInfo.isFile);

`statSync`

statSync(): FileInfo

Synchronously returns a FileInfo for the file.

Example: Usage

import { assert } from "@ende/assert";
import { openSync } from "@ende/fs/unstable-open";
using file = openSync("hello.txt");
const fileInfo = file.statSync();
assert(fileInfo.isFile);

`sync`

sync(): Promise<void>

Flushes any pending data and metadata operations of the given file stream to disk.

Example: Usage

import { open } from "@ende/fs/unstable-open";
import { readTextFile } from "@ende/fs/unstable-read-text-file";
const file = await 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 readTextFile("my_file.txt")); // H

`syncSync`

syncSync(): void

Synchronously flushes any pending data and metadata operations of the given file stream to disk.

Example: Usage

import { openSync } from "@ende/fs/unstable-open";
import { readTextFileSync } from "@ende/fs/unstable-read-text-file";
const file = openSync(
  "my_file.txt",
  { read: true, write: true, create: true },
);
file.writeSync(new TextEncoder().encode("Hello World"));
file.truncateSync(1);
file.syncSync();
console.log(readTextFileSync("my_file.txt")); // H

`syncData`

syncData(): Promise<void>

Flushes any pending data operations of the given file stream to disk.

Example: Usage

import { open } from "@ende/fs/unstable-open";
import { readTextFile } from "@ende/fs/unstable-read-text-file";
using file = await open(
  "my_file.txt",
  { read: true, write: true, create: true },
);
await file.write(new TextEncoder().encode("Hello World"));
await file.syncData();
console.log(await readTextFile("my_file.txt")); // Hello World

`syncDataSync`

syncDataSync(): void

Synchronously flushes any pending data operations of the given file stream to disk.

Example: Usage

import { openSync } from "@ende/fs/unstable-open";
import { readTextFileSync } from "@ende/fs/unstable-read-text-file";
using file = openSync(
  "my_file.txt",
  { read: true, write: true, create: true },
);
file.writeSync(new TextEncoder().encode("Hello World"));
file.syncDataSync();
console.log(readTextFileSync("my_file.txt")); // Hello World

`truncate`

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.

Example: Truncate the entire file

import { open } from "@ende/fs/unstable-open";
using file = await open("my_file.txt", { write: true });
await file.truncate();

Example: Truncate part of the file

import { open } from "@ende/fs/unstable-open";
// if "my_file.txt" contains the text "hello world":
using file = await 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`

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.

Example: Truncate the entire file

import { openSync } from "@ende/fs/unstable-open";
using file = openSync("my_file.txt", { write: true });
file.truncateSync();

Example: Truncate part of the file

import { openSync } from "@ende/fs/unstable-open";
// if "my_file.txt" contains the text "hello world":
using file = 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`

unlock(): Promise<void>

Release an advisory file-system lock for the file.

`unlockSync`

unlockSync(): void

Synchronously release an advisory file-system lock for the file.

`utime`

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.

Example: Usage

import { open } from "@ende/fs/unstable-open";
using file = await open("file.txt", { create: true, write: true });
await file.utime(1556495550, new Date());

`utimeSync`

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.

Example: Usage

import { openSync } from "@ende/fs/unstable-open";
using file = openSync("file.txt", { create: true, write: true });
file.utime(1556495550, new Date());

`write`

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.

Example: Usage

import { open } from "@ende/fs/unstable-open";
const encoder = new TextEncoder();
const data = encoder.encode("Hello world");
using file = await open("/foo/bar.txt", { write: true });
const bytesWritten = await file.write(data); // 11

`writeSync`

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.

Example: Usage

import { openSync } from "@ende/fs/unstable-open";
const encoder = new TextEncoder();
const data = encoder.encode("Hello world");
using file = openSync("/foo/bar.txt", { write: true });
const bytesWritten = file.writeSync(data); // 11

Source