Ende.FsFile

readable

readonly readable: ReadableStream<Uint8Array<ArrayBuffer>>

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

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

Note that the readable stream takes ownership of the file: reading the stream to completion (or cancelling it) closes the file automatically, so you should not close the file yourself while the stream is still being consumed.

writable

readonly writable: WritableStream<Uint8Array<ArrayBufferLike>>

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"];
using file = await Ende.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));
}

Note that the writable stream takes ownership of the file: closing or aborting the stream closes the file automatically, so you should not close the file yourself while the stream is still in use.

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.

const encoder = new TextEncoder();
const data = encoder.encode("Hello world");
using file = await Ende.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.

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

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.

Truncate the entire file

using file = await Ende.open("my_file.txt", { write: true });
await file.truncate();

Truncate part of the file

// if "my_file.txt" contains the text "hello world":
using file = await Ende.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.

Truncate the entire file

using file = Ende.openSync("my_file.txt", { write: true });
file.truncateSync();

Truncate part of the file

// if "my_file.txt" contains the text "hello world":
using file = Ende.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"

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.

// if "/foo/bar.txt" contains the text "hello world":
using file = await Ende.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.

// if "/foo/bar.txt" contains the text "hello world":
using file = Ende.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

seek(offset: number | bigint, 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 the file contains "Hello world" text, which is 11 bytes long:
using file = await Ende.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, Ende.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:

// Given the file contains "Hello world" text, which is 11 bytes long:
const file = await Ende.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, Ende.SeekMode.Start)); // "6"
// Seek 2 more bytes from the current position
console.log(await file.seek(2, Ende.SeekMode.Current)); // "8"
// Seek backwards 2 bytes from the end of the file
console.log(await file.seek(-2, Ende.SeekMode.End)); // "9" (i.e. 11-2)

seekSync

seekSync(offset: number | bigint, 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.

using file = Ende.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, Ende.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:

// Given the file contains "Hello world" text, which is 11 bytes long:
using file = Ende.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, Ende.SeekMode.Start)); // "6"
// Seek 2 more bytes from the current position
console.log(file.seekSync(2, Ende.SeekMode.Current)); // "8"
// Seek backwards 2 bytes from the end of the file
console.log(file.seekSync(-2, Ende.SeekMode.End)); // "9" (i.e. 11-2)

stat

stat(): Promise<FileInfo>

Resolves to a Ende.FileInfo for the file.

import { assert } from "jsr:@ende/assert";

using file = await Ende.open("hello.txt");
const fileInfo = await file.stat();
assert(fileInfo.isFile);

statSync

statSync(): FileInfo

Synchronously returns a Ende.FileInfo for the file.

import { assert } from "jsr:@ende/assert";

using file = Ende.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.

const file = await Ende.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 Ende.readTextFile("my_file.txt")); // H

syncSync

syncSync(): void

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

const file = Ende.openSync(
  "my_file.txt",
  { read: true, write: true, create: true },
);
file.writeSync(new TextEncoder().encode("Hello World"));
file.truncateSync(1);
file.syncSync();
console.log(Ende.readTextFileSync("my_file.txt")); // H

syncData

syncData(): Promise<void>

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

using file = await Ende.open(
 "my_file.txt",
 { read: true, write: true, create: true },
);
await file.write(new TextEncoder().encode("Hello World"));
await file.syncData();
console.log(await Ende.readTextFile("my_file.txt")); // Hello World

syncDataSync

syncDataSync(): void

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

using file = Ende.openSync(
 "my_file.txt",
 { read: true, write: true, create: true },
);
file.writeSync(new TextEncoder().encode("Hello World"));
file.syncDataSync();
console.log(Ende.readTextFileSync("my_file.txt")); // Hello World

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.

using file = await Ende.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.

using file = Ende.openSync("file.txt", { create: true, write: true });
file.utime(1556495550, new Date());

isTerminal

isTerminal(): boolean

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

// This example is system and context specific
using file = await Ende.open("/dev/tty6");
file.isTerminal(); // true

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.

using file = await Ende.open("/dev/tty6");
file.setRaw(true, { cbreak: true });

lock

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

Acquire an advisory file-system lock for the file.

exclusive?: boolean

lockSync

lockSync(exclusive?: boolean): void

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

exclusive?: boolean

tryLock

tryLock(exclusive?: boolean): Promise<boolean>

Try to acquire an advisory file-system lock for the file. Returns true if the lock was acquired, false if the file is already locked.

Unlike Ende.FsFile.lock, this method will not block if the lock cannot be acquired.

exclusive?: boolean

tryLockSync

tryLockSync(exclusive?: boolean): boolean

Synchronously try to acquire an advisory file-system lock for the file. Returns true if the lock was acquired, false if the file is already locked.

Unlike Ende.FsFile.lockSync, this method will not block if the lock cannot be acquired.

exclusive?: boolean

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.

close

close(): void

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

using file = await Ende.open("my_file.txt");
// do work with "file" object

[Symbol.dispose]

[Symbol.dispose](): void