FileEntity#

The FileEntity class provides low-level file read and write operations. It allows scripts and HTTP servers to open, read, write, seek, and close files efficiently. FileEntity can also be used as a response body for HttpResponse.raw() to serve static or downloadable files.

Overview#

FileEntity enables direct file operations, including:

• Opening files in different modes (read, write, read/write, append, etc.)
• Reading and writing binary data (Data objects)
• Seeking to a specific offset in the file
• Closing files to release resources
• Returning file streams as HTTP responses

Instance Properties#

path: string#

The full path of the file represented by this FileEntity instance.

Example:

1const file = FileEntity.openForReading("/path/to/file.txt")
2console.log(file.path)
3// Output: "/path/to/file.txt"

Instance Methods#

seek(offset: number): boolean#

Moves the file pointer to the specified byte offset. Returns true if successful, or false if seeking fails.

Parameters:

Example:

1const file = FileEntity.openForReading("/path/to/data.bin")
2file.seek(128)

read(size: number): Data#

Reads a specified number of bytes from the current file position and returns them as a Data object.

Parameters:

Returns: A Data object containing the read bytes.

Example:

1const file = FileEntity.openForReading("/path/to/text.txt")
2const data = file.read(100)
3console.log(data.toRawString("utf-8"))
4file.close()

write(data: Data): void#

Writes the provided Data to the current file position. Throws an error if the file was not opened in a writable mode.

Parameters:

Example:

1const data = Data.fromRawString("Hello, Scripting!", "utf-8")
2const file = FileEntity.openNewForWriting("/tmp/test.txt")
3file.write(data)
4file.close()

close(): void#

Closes the file and releases the associated resources. After closing, you should not call read() or write() again.

Example:

1const file = FileEntity.openForReading("/path/to/file.txt")
2// ... perform operations ...
3file.close()

Static Methods#

static openForReading(path: string): FileEntity#

Opens a file in read-only mode. Throws an error if the file does not exist or cannot be read.

Parameters:

Example:

1const file = FileEntity.openForReading("/path/to/image.png")

static openNewForWriting(path: string): FileEntity#

Opens a file in write-only mode. If the file already exists, it will be overwritten.

Example:

1const file = FileEntity.openNewForWriting("/tmp/output.txt")
2file.write(Data.fromRawString("New file created"))
3file.close()

static openForWritingAndReading(path: string): FileEntity#

Opens a file in read/write mode. If the file does not exist, it will be created automatically.

Example:

1const file = FileEntity.openForWritingAndReading("/tmp/data.txt")
2file.write(Data.fromRawString("abc"))
3file.seek(0)
4console.log(file.read(3).toRawString("utf-8"))
5file.close()

static openForMode(path: string, mode: string): FileEntity#

Opens a file using the specified access mode. The supported modes follow standard POSIX file semantics, but it is strongly recommended to use binary-safe modes such as "rb" or "r+b" for better cross-platform compatibility, since FileEntity performs all read/write operations in binary mode internally.

Parameters:

💡 Note: Always prefer binary-safe modes (those ending with b), such as "rb", "wb", or "r+b". This ensures consistent behavior across platforms and avoids newline or encoding conversion issues, since FileEntity handles all file I/O as binary streams.

Example:

1// Open file in binary read/write mode (recommended)
2const file = FileEntity.openForMode("/tmp/log.bin", "r+b")
3
4// Write binary data
5file.write(Data.fromRawString("append log\n"))
6
7// Move to the beginning and read data
8file.seek(0)
9const content = file.read(20).toRawString("utf-8")
10console.log(content)
11
12file.close()

Using FileEntity in HttpResponse#

FileEntity can be used directly as the body of an HTTP response via HttpResponse.raw(). This allows serving files or implementing file download endpoints.

Example:

1server.registerHandler("/download", (req) => {
2  const file = FileEntity.openForReading(Path.join(Script.directory, "manual.pdf"))
3  return HttpResponse.raw(200, "OK", {
4    headers: { "Content-Type": "application/pdf" },
5    body: file
6  })
7})

Clients accessing /download will directly receive the file as a download.

Summary#