skills/docs/foundation/flow/streams/src/utils/buffer/get-data-from-file/get-data-from-file.md

getDataFromFile

(no submodules)

Purpose

getDataFromFile reads a file from the local filesystem and returns its contents as a plain Uint8Array. It is a thin Node-only convenience for the streams package: the streams package is environment-agnostic, but many byte-oriented helpers (chunking, framing, hashing) need a way to load test fixtures and real-world inputs from disk without each call site re-implementing the dynamic import + error-mapping dance.

The function is browser-safe in the sense that importing it does not pull in node:fs eagerly. The Node module is loaded lazily inside the function body and calling it in a non-Node environment surfaces a structured StreamFileBrowserNotSupportedError rather than an opaque module-resolution crash.

Features

• Lazy node:fs/promises import — zero overhead on the browser bundle path.
• Runtime environment detection via globalThis.process?.versions?.node.
• Returns a fresh Uint8Array decoupled from Node's pooled Buffer allocator.
• Structured errors with the original cause and the offending filePath.
• Stable STREAM.FILE_BROWSER_NOT_SUPPORTED and STREAM.FILE_READ_FAILED codes.

Usage: Basic Example

import { getDataFromFile } from "@suaveplan/streams/utils/buffer/get-data-from-file/get-data-from-file";

const bytes = await getDataFromFile("/etc/hostname");
console.log(bytes.byteLength);

Usage: Advanced Example

import { getDataFromFile } from "@suaveplan/streams/utils/buffer/get-data-from-file/get-data-from-file";
import { StreamFileReadFailedError } from "@suaveplan/streams/errors/stream-error";

try {
    const data = await getDataFromFile("/no/such/file");
    process.stdout.write(data);
} catch (err) {
    if (err instanceof StreamFileReadFailedError) {
        console.error("read failed", err.context, err.cause);
    } else {
        throw err;
    }
}

API Reference

getDataFromFile(filePath: string): Promise<Uint8Array>

• filePath — absolute or relative path resolved against process.cwd().
• Returns — Promise<Uint8Array> containing the file's exact bytes.
• Throws — StreamFileBrowserNotSupportedError outside Node; StreamFileReadFailedError (with cause and context.filePath) on any underlying I/O failure (ENOENT, EACCES, EISDIR, …).

Implementation Notes

• The dynamic import("node:fs/promises") keeps the universal entry-point free of Node-only deps; bundlers that target the browser tree-shake this branch away, and the runtime guard prevents accidental invocation.
• The returned array is sliced off the underlying ArrayBuffer so consumers never receive a Buffer subclass — useful when feeding the result into APIs that strictly type-check Uint8Array.
• All thrown errors extend SuaveplanError and round-trip through the standard redaction / wire-format adapters supplied by @suaveplan/error.