readFile

This page describes @vooya/fs@0.1.1. See Node compatibility and execution policy for native fast paths, Node routes and verified limits.

Read the entire contents of a file. Returns a Buffer or a decoded string depending on encoding.

Basic usage

import { readFile } from '@vooya/fs'
 
// As UTF-8 string (explicit encoding)
const text = await readFile('./package.json', { encoding: 'utf8' })
 
// As Buffer
const buf = await readFile('./image.png')
 
// Other encodings
const base64 = await readFile('./file.bin', { encoding: 'base64' })
const hex = await readFile('./file.bin', { encoding: 'hex' })

Encoding names are case-insensitive. Whole-file UTF-8 reads replace malformed byte sequences with the replacement character, matching Node. The lines extension applies the same decoding after selecting raw line bytes.

Read a line range

Always supply a text encoding when using lines:

const excerpt = await readFile('./test.ts', {
  encoding: 'utf8',
  lines: { from: 110, to: 120 },
})

Bounds are one-based and inclusive. A range past EOF returns an empty string; when only the upper bound exceeds EOF, the result ends at the last available line. Selected lines are joined with \n, without a final line terminator. Omitting the encoding (or using encoding: null) returns the whole file as a Buffer, so it does not limit how much content your caller receives.

Version 0.1.1 preserves blank lines in the selected range. The published 0.1.0 release can drop leading blank lines from the excerpt; its missing-file errors also lack 0.1.1’s structured fields. See version-specific troubleshooting.

Methods

readFile(path, options?)

Async. Returns Promise<string | Buffer>.

Options:

readFileSync(path, options?)

Sync. Same arguments and return types; throws on error.

An explicit encoding: null uses the default Buffer result, just like omitting the encoding. This also works with frozen options objects.

Performance

Whole-file results depend on encoding, file size and runtime. The clearest benefit is reading an early line range: the native reader stops at the requested upper bound instead of loading the entire file. See Batch API evidence for current measurements and the exact baseline used for the line-range comparison.

Local scale report

Generated from local performance reports. Do not edit this block by hand.

• Runtime: v22.22.0 on darwin/arm64
• Samples: 2 warmup runs, 10 measured runs
• Aggregation: trimmed mean for wall-clock time; average per-run memory delta for RSS

Notes

• Encodings: Supported encodings are utf8, ascii, latin1, base64, base64url, hex. Behavior matches Node.js where implemented.
• Flags: Standard flags (e.g. r, r+) are supported. Use the same semantics as Node.js for compatibility.
• Lines extension: lines is a Vooya FS extension for text reads, not a Node.js option.
• Early line ranges: The native reader stops once to is reached. This can avoid reading and decoding the remainder of a large text file; the scale report includes a 16 MB / first-100-lines case.
• Errors: Missing-path errors expose code, path, syscall and errno.
• Node options: The public entry supports AbortSignal, Buffer/file URL paths and FileHandle inputs; advanced options use Node. The lines extension cannot be combined with cancellation or file handles.
• Large files: Reading the whole file into memory is the same as Node.js; for very large files consider streaming (Node.js fs.createReadStream; Vooya FS does not provide a stream API for this yet).

Competitor measurements

See the full readFile comparison table for Node 22/24, peer libraries, sync/Promise modes, small and batch workloads, execution routes and measurement limits.