XFile

The XFile class provides a unified interface for file system operations with automatic MIME type detection. It wraps the underlying platform file implementation (Bun's BunFile) with a consistent API for checking existence, reading text content, and streaming file data.

Contents
  1. Usage
  2. Constructor Parameters
  3. Properties and getters
  4. Methods

Usage

Basic file operations

import { X } from "@ozanarslan/corpus";

const file = new X.File("assets/document.txt");

// Check existence
if (await file.exists()) {
	const content = await file.text();
	console.log(content);
}

Streaming files

const video = new X.File("assets/video.mp4");

// Stream for responses
return X.Res.streamFile(video);

MIME type detection

const css = new X.File("styles/main.css");
console.log(css.mimeType); // "text/css"

const unknown = new X.File("data.xyz", "json");
console.log(unknown.mimeType); // "application/json" (from fallback)

Constructor Parameters

path

string

The file system path to the file.

fallbackExtension (optional)

string

Extension to use for MIME type detection when the path has no extension.

Properties and getters

PropertyTypeDescription
pathstringThe path from constructor.
namestringThe name of the file without the extension.
extensionstringThe file extension (e.g., "html", "md"), excluding the leading dot.
fullnamestringThe full name of the file, including the extension.
mimeTypestringThe standard MIME type associated with the file's extension.
parentDirsstringGets the parent directory names as an array, ordered from the immediate parent up to the root.

Methods

exists

exists(): Promise<boolean>

Checks if the file exists on the file system.

const file = new X.File("assets/data.json");
const ok = await file.exists(); // boolean

text

text(): Promise<string>

Reads the entire file contents as a UTF-8 string.

const file = new X.File("assets/template.html");
const html = await file.text();

stream

stream(): ReadableStream

Returns a readable stream for the file. Useful for large files that shouldn't be loaded into memory.

const file = new X.File("assets/video.mp4");
const stream = file.stream();
// Use with Res or pipe elsewhere