# getDataFromFile

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

```ts
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

```ts
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`.