appendFile

Append data to a file, creating the file if it does not exist.

Basic usage

import { appendFile } from '@vooya/fs'
 
await appendFile('./log.txt', 'new line\n')
await appendFile('./log.txt', buffer, { 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

appendFile(path, data, options?)

Async. Returns Promise<void>.

appendFileSync(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: utf8, ascii, latin1, base64, base64url, hex. Same semantics as Node.js.
• Known gap: Filesystem errors currently have Node-like messages, but do not expose Node-style code, path, and syscall fields yet.
• Unsupported Node inputs/options: Buffer paths, URL paths, TypedArray/DataView data, AbortSignal, and newer flush behavior are not part of the current Vooya FS appendFile surface.

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 appendFile comparison table for Node 22/24, peer libraries, sync/Promise modes, small and batch workloads, execution routes and measurement limits.