writeFile

Write data to a file, replacing the file if it exists. Supports encodings, mode, and flag.

Basic usage

import { writeFile } from '@vooya/fs'
 
await writeFile('./out.txt', 'hello world')
await writeFile('./out.bin', buffer)
await writeFile('./out.txt', 'content', { encoding: 'utf8', mode: 0o644 })

The options argument also accepts an encoding string, for example "utf8" or "hex". Encoding names are case-insensitive. ASCII and Latin-1 writes truncate each UTF-16 code unit to its low byte, matching Node. Both Base64 variants accept either alphabet and stop at padding.

Methods

writeFile(path, data, options?)

Async. Returns Promise<void>.

Options: encoding (utf8, ascii, latin1, base64, base64url, hex), mode (number), flag (e.g. 'w', 'wx', 'a', 'ax').

writeFileSync(path, data, options?)

Sync. Same arguments; throws on error.

Performance

Buffer writes borrow the input bytes for synchronous calls. Promise calls keep one entry-time copy so the worker owns a stable snapshot, then write directly from that snapshot. This removes a redundant payload-sized allocation and copy; it is not a zero-copy or faster-disk guarantee. String encoding is unchanged.

See the native overhead report for release-build Node 22/24 comparisons, including small inputs, raw samples and memory limits. Large Buffer workloads are the intended target; small writes remain dominated by scheduling, opening the file and filesystem cost. These APIs do not implement Node’s flush option, so the measurements compare writes without an explicit flush.

Local macOS arm64 medians, two warmups and ten samples; times include the public entry. Inputs are Buffer subarrays, concurrency 1, warm cache, no flush.

Small-input results include regressions; reduced copying does not imply a speedup for every payload or filesystem. RSS samples in the report are not peak memory.

Notes

• Encodings: Same as Node.js (utf8, ascii, latin1, base64, base64url, hex).
• Hex compatibility: Odd trailing nibbles and invalid trailing pairs follow Node’s string-encoding behavior.
• Mode: Applies when a file is created and is filtered by the process umask; writing an existing file does not reset its permissions.
• Supported input shape: Vooya FS currently accepts string paths and string | Buffer data. Node also accepts URL / Buffer paths and more typed array data shapes; those are deferred.
• Known gap: Filesystem errors currently have Node-like messages, but do not expose Node-style code, path, and syscall fields yet.
• Unsupported Node options: AbortSignal, flush, and file-handle targets are not part of the current Vooya FS writeFile surface.
• Large data: Writing a very large string (e.g. 4 MB) crosses the N-API boundary and can be slower than Node.js; prefer Buffer for large binary data where possible.

Buffer ownership

Buffer.subarray() writes only the selected bytes, including a nonzero offset. Async calls snapshot those bytes before returning the Promise; later mutation of the original Buffer does not change that operation’s input. This is Vooya’s ownership policy, not a promise that Node snapshots mutable inputs identically. Await writes to the same file in the required order; separate concurrent calls are not an ordering primitive.

Competitor measurements

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