LocalFile

LocalFile represents a file stored on the local filesystem. It provides a small API for reading file content and managing the file's lifecycle, including automatic deletion when the object is garbage-collected.

Package: @opra/http

MultipartReader.File extends LocalFile — every uploaded file you receive from a MultipartReader is a LocalFile instance with an additional kind and field property.

---

Constructor

new LocalFile(storedPath: string, options?: LocalFile.Options)

Parameter	Type	Description
storedPath	string	Absolute path to the file on disk.
options.filename	string	Display name of the file. Defaults to the basename of storedPath.
options.type	string	MIME type, e.g. 'image/png'.
options.encoding	BufferEncoding	File encoding, e.g. 'utf-8'.
options.autoDelete	boolean	Delete the file automatically when the object is GC'd. Defaults to false.

import { LocalFile } from '@opra/http';

const file = new LocalFile('/tmp/report.pdf', {
  filename: 'report.pdf',
  type: 'application/pdf',
  autoDelete: true,
});

---

Properties

Property	Type	Description
storedPath	string	Absolute path to the file on disk. Readonly.
filename	string	Display name of the file.
type	string | undefined	MIME type.
encoding	BufferEncoding | undefined	File encoding.
size	number	File size in bytes. Computed via fs.statSync on each access.
autoDelete	boolean	When true, the file is scheduled for deletion when the object is garbage-collected. Setter registers or unregisters the GC finalizer.

---

Methods

buffer()

buffer(): Promise<Buffer>

Reads the entire file into memory and returns it as a Buffer.

const buf = await file.buffer();
await s3.putObject({ Body: buf, Key: file.filename });

---

text()

text(): Promise<string>

Reads the entire file as a string. Uses file.encoding if set, otherwise defaults to 'utf-8'.

const content = await file.text();
const data = JSON.parse(content);

---

delete()

delete(): Promise<void>

Deletes the file from disk immediately. If the file does not exist, the call resolves without error. After deletion, autoDelete is set to false to prevent a double-delete attempt by the GC finalizer.

await file.delete();

---

Static methods

LocalFile.tempFilename()

static tempFilename(filename?: string, tempDirectory?: string): string

Generates a unique file path inside a temp directory. If filename is provided, the basename is preserved and a random prefix is added only if there is a collision. If filename is omitted, a random name prefixed with opra- is generated.

Parameter	Type	Description
filename	string | undefined	Original file name. Optional.
tempDirectory	string | undefined	Target directory. Defaults to os.tmpdir().

const path1 = LocalFile.tempFilename('report.pdf');
// → '/tmp/report.pdf'  (or '/tmp/a3f9bx-report.pdf' if that already exists)

const path2 = LocalFile.tempFilename();
// → '/tmp/opra-k8n2p4qs7x1m'

---

Auto-deletion

autoDelete controls two independent deletion mechanisms:

• GC-based — a FinalizationRegistry schedules fs.unlink when the object is garbage-collected.
• Process-exit-based — if process.finalization is available (Node.js 24+), delete() is called on process exit.

Both mechanisms are registered when autoDelete is set to true and unregistered when it is set back to false or after delete() is called.

const file = new LocalFile('/tmp/upload.bin', { autoDelete: true });

// Disable auto-deletion if you move the file somewhere permanent
await fs.rename(file.storedPath, '/data/uploads/upload.bin');
file.autoDelete = false;

note

Files received from MultipartReader always have autoDelete: true. Call file.delete() explicitly once you have finished processing to free disk space immediately rather than waiting for GC.

---

Interfaces

LocalFile.Options

namespace LocalFile {
  interface Options {
    filename?: string;
    autoDelete?: boolean;
    type?: string;
    encoding?: BufferEncoding;
  }
}