# node:fs

> How Elide supports Node's `fs` and `fs/promises` modules: glob, cp, statfs and watch match Node, `openAsBlob` is missing, and sandbox flags limit access.

`node:fs`, `node:fs/promises`, and `fs.promises` match [Node's `fs`](https://nodejs.org/api/fs.html), including `glob`,
`cp`, `statfs`, `opendir`, and `watch`.

## Example

```js
// fs.mjs
import { existsSync } from "node:fs";
import { mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";

const dir = await mkdtemp(join(tmpdir(), "notes-"));
await writeFile(join(dir, "todo.txt"), "ship the docs");
console.log(await readFile(join(dir, "todo.txt"), "utf8"));
console.log((await readdir(dir)).join(), (await stat(join(dir, "todo.txt"))).size);
await rm(dir, { recursive: true });
console.log(existsSync(dir));
```

`elide run fs.mjs` prints:

```text
ship the docs
todo.txt 13
false
```

## Differences from Node

- `lchmod` exists only in `fs/promises`; it has no callback or sync form.
- `fs.openAsBlob` is not available.
- Access is unrestricted until `--sandbox`, `--allow-read`, `--allow-write`, or `--fs-audit` is set; see
  [Sandbox](https://elide.help/docs/sandbox).

## Samples

- [Files and paths](https://elide.help/docs/code-samples#files-and-paths)
- [CSV report](https://elide.help/docs/code-samples#csv-report)

<!-- api-reference:start 4cd1c55e57d9 -->
## Reference

**Status:** Partial · 246 of 264 suite tests pass (93.2%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `readFile()`, `readFileSync()` | function | Full | Reads the entire contents of a file |
| `writeFile()`, `writeFileSync()` | function | Full | Writes data to a file, replacing it if it already exists |
| `appendFile()`, `appendFileSync()` | function | Full | Appends data to a file, creating it if it does not exist |
| `stat()`, `statSync()` | function | Full | Retrieves file status information |
| `mkdir()`, `mkdirSync()` | function | Full | Creates a directory |
| `rmdir()`, `rmdirSync()` | function | Full | Removes a directory |
| `unlink()`, `unlinkSync()` | function | Full | Deletes a file |
| `rename()`, `renameSync()` | function | Full | Renames (moves) a file or directory |
| `readdir()`, `readdirSync()` | function | Full | Reads the contents of a directory |
| `access()`, `accessSync()` | function | Full | Tests whether a path is accessible under the given mode |
| `copyFile()`, `copyFileSync()` | function | Full | Copies a file from src to dest |
| `chmod()`, `chmodSync()` | function | Full | Changes the permissions of a file |
| `lstat()`, `lstatSync()` | function | Full | Retrieves file status information without following symbolic links |
| `realpath()`, `realpathSync()` | function | Full | Resolves all symbolic links and returns the real absolute path |
| `mkdtemp()`, `mkdtempSync()` | function | Full | Creates a unique temporary directory using a prefix template |
| `open()`, `openSync()` | function | Full | Opens a file |
| `close()`, `closeSync()` | function | Full | Closes a file descriptor |
| `read()`, `readSync()` | function | Full | Reads from a file descriptor into a buffer |
| `write()`, `writeSync()` | function | Full | Writes to a file descriptor |
| `fsync()`, `fsyncSync()` | function | Full | Flushes data and metadata of a descriptor |
| `fdatasync()`, `fdatasyncSync()` | function | Full | Flushes data of a descriptor |
| `ftruncate()`, `ftruncateSync()` | function | Full | Truncates a file by descriptor |
| `truncate()`, `truncateSync()` | function | Full | Truncates a file by path |
| `readlink()`, `readlinkSync()` | function | Full | Reads a symbolic link's target |
| `link()`, `linkSync()` | function | Full | Creates a hard link |
| `symlink()`, `symlinkSync()` | function | Full | Creates a symbolic link |
| `rm()`, `rmSync()` | function | Full | Removes files and directories |
| `cp()`, `cpSync()` | function | Full | Copies a directory structure |
| `statfs()`, `statfsSync()` | function | Full | Returns filesystem statistics |
| `opendir()`, `opendirSync()` | function | Full | Opens a directory |
| `glob()`, `globSync()` | function | Full | Returns paths matching a glob |
| `chown()`, `chownSync()` | function | Full | Changes ownership of a file |
| `lchown()`, `lchownSync()` | function | Full | Changes ownership of a symlink |
| `fchown()`, `fchownSync()` | function | Full | Changes ownership by descriptor |
| `lchmod()`, `lchmodSync()` | function | Not implemented | Changes permissions of a symlink (macOS) |
| `fchmod()`, `fchmodSync()` | function | Full | Changes permissions by descriptor |
| `utimes()`, `utimesSync()` | function | Full | Sets file times |
| `lutimes()`, `lutimesSync()` | function | Full | Sets symlink times |
| `futimes()`, `futimesSync()` | function | Full | Sets times by descriptor |
| `fstat()`, `fstatSync()` | function | Full | Retrieves status by descriptor |
| `exists()`, `existsSync()` | function | Full | Deprecated: asynchronously tests whether a path exists |
| `createReadStream()` | function | Full | Creates a readable stream for a file |
| `createWriteStream()` | function | Full | Creates a writable stream for a file |
| `watch()` | function | Full | Watches for changes on a file or directory |
| `watchFile()` | function | Full | Watches a file for changes by polling its status at an interval |
| `unwatchFile()` | function | Full | Stops watching a file previously watched with watchFile |
| `promises` | property | Full | Promise-based variants of all fs methods (fs/promises) |
| `constants` | property | Full | File system constants such as F_OK, R_OK, W_OK, X_OK, COPYFILE_EXCL |
| top-level constants | constant | Full | `F_OK`, `R_OK`, `W_OK`, `X_OK`, `COPYFILE_EXCL`, `COPYFILE_FICLONE` and 46 more |

### `fs/promises`

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `access()` | function | Full | Test a path's accessibility |
| `appendFile()` | function | Full | Append data to a file |
| `chmod()` | function | Full | Change file permissions |
| `chown()` | function | Full | Change file ownership |
| `copyFile()` | function | Full | Copy a file |
| `cp()` | function | Full | Recursively copy a directory tree |
| `glob()` | function | Full | Match paths against a glob pattern |
| `lchmod()` | function | Full | Change permissions of a symbolic link (macOS) |
| `lchown()` | function | Full | Change ownership of a symbolic link |
| `link()` | function | Full | Create a hard link |
| `lstat()` | function | Full | Retrieve link status (does not follow symlinks) |
| `lutimes()` | function | Full | Set the times of a symbolic link |
| `mkdir()` | function | Full | Create a directory |
| `mkdtemp()` | function | Full | Create a unique temporary directory |
| `open()` | function | Full | Open a file, resolving to a FileHandle |
| `opendir()` | function | Full | Open a directory for iteration |
| `readdir()` | function | Full | Read the contents of a directory |
| `readFile()` | function | Full | Read the entire contents of a file |
| `readlink()` | function | Full | Read the target of a symbolic link |
| `realpath()` | function | Full | Resolve the canonical pathname |
| `rename()` | function | Full | Rename (move) a file or directory |
| `rm()` | function | Full | Remove files and directories |
| `rmdir()` | function | Full | Remove a directory |
| `stat()` | function | Full | Retrieve file status |
| `statfs()` | function | Full | Retrieve filesystem statistics |
| `symlink()` | function | Full | Create a symbolic link |
| `truncate()` | function | Full | Truncate a file |
| `unlink()` | function | Full | Delete a file |
| `utimes()` | function | Full | Set the access and modification times of a file |
| `watch()` | function | Full | Watch a file or directory, returning an async iterator of change events |
| `writeFile()` | function | Full | Write data to a file, replacing it if it exists |

### Not implemented

`FileReadStream`, `FileWriteStream`, `Utf8Stream`, `lchmod`, `lchmodSync`, `openAsBlob`.

**Tests:** [node-api `node:fs`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 246 pass, 18 fail, 0 error, 30 skipped. Failing: `test-fs-promises-file-handle-pull.js`, `test-fs-promises-file-handle-pullsync.js`, `test-fs-promises-file-handle-read-worker.js`, `test-fs-promises-file-handle-writer.js`, `test-fs-promises-watch.js`, `test-fs-promises.js`, `test-fs-read-stream-file-handle.js`, `test-fs-stat.js`, and 10 more.
<!-- api-reference:end -->