[API reference](https://evolu.dev/docs/api-reference) › [@evolu/common](https://evolu.dev/docs/api-reference/common) › Fs

File system operations for [Task](https://evolu.dev/docs/api-reference/common/Task/type-aliases/Task)s.

[Fs](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs) reads, writes, copies, and renames files; lists and manages
directories; and provides metadata and existence checks. Each operation
returns a Task.

Tasks can sequence file operations without synchronous I/O. Node.js's
synchronous methods are intentionally omitted to avoid accidentally blocking
the event loop.

Inject [createNodeFs](https://evolu.dev/docs/api-reference/nodejs/functions/createNodeFs) through
[runMain](https://evolu.dev/docs/api-reference/nodejs/functions/runMain) or [createRun](https://evolu.dev/docs/api-reference/common/Task/variables/createRun). Tasks declare
[FsDep](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsDep) and access the file system through `run.deps.fs`.

[FsError](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsError) includes the path, a diagnostic message, and a
[FsErrorReason](https://evolu.dev/docs/api-reference/common/Fs/type-aliases/FsErrorReason) such as `NotFound` or `PermissionDenied`.
[Fs.exists](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs#exists) returns `false` for `NotFound` and preserves other errors.

### Example

```ts
import {
  assertEqual,
  ok,
  type FsDep,
  type FsError,
  type Task,
} from "@evolu/common";

const main: Task<void, FsError, FsDep> = async (run) => {
  const { fs } = run.deps;
  const temp = await run(fs.createTempDirectory({ prefix: "evolu-fs-" }));
  if (!temp.ok) return temp;

  await using directory = temp.value;
  const path = join(directory.path, "message.txt");

  const result = await run(fs.writeFile(path, "hello"));
  if (!result.ok) return result;

  const text = await run(fs.readFile(path, "utf8"));
  if (!text.ok) return text;
  assertEqual(text.value, "hello");

  return ok();
};

await runMain({ fs: createNodeFs() }, { mode: "command" })(main);
```

## Core

| Name                                                                            | Description                                                                                                       |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| [Fs](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs)                           | Asynchronous file system operations.                                                                              |
| [FsDep](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsDep)                     | Dependency wrapper for [Fs](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs).                                     |
| [FsMetadata](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsMetadata)           | File metadata as data, with Node's numeric and timestamp field names.                                             |
| [FsReadFile](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsReadFile)           | Reads bytes by default, or text when an encoding is specified.                                                    |
| [FsTempDirectory](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsTempDirectory) | A temporary directory removed, with its contents, on asynchronous disposal.                                       |
| [FsEncoding](https://evolu.dev/docs/api-reference/common/Fs/type-aliases/FsEncoding)         | Supported text encodings.                                                                                         |
| [FsEntryType](https://evolu.dev/docs/api-reference/common/Fs/type-aliases/FsEntryType)       | The kind of file system entry described by [FsMetadata](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsMetadata). |
| [FsOpenFlag](https://evolu.dev/docs/api-reference/common/Fs/type-aliases/FsOpenFlag)         | Supported file opening modes for [Fs.writeFile](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs#writefile).       |
| [FsPath](https://evolu.dev/docs/api-reference/common/Fs/type-aliases/FsPath)                 | A file system path, or a `file:` URL.                                                                             |

## Options

| Interface                                                                                                 | Description                                                                                                |
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [FsCopyFileOptions](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsCopyFileOptions)                       | Options for [Fs.copyFile](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs#copyfile).                       |
| [FsCopyOptions](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsCopyOptions)                               | Options for [Fs.copy](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs#copy).                               |
| [FsCreateDirectoryOptions](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsCreateDirectoryOptions)         | Options for [Fs.createDirectory](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs#createdirectory).         |
| [FsCreateTempDirectoryOptions](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsCreateTempDirectoryOptions) | Options for [Fs.createTempDirectory](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs#createtempdirectory). |
| [FsReadDirectoryOptions](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsReadDirectoryOptions)             | Options for [Fs.readDirectory](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs#readdirectory).             |
| [FsRemoveOptions](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsRemoveOptions)                           | Options for [Fs.remove](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs#remove).                           |
| [FsWriteFileOptions](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsWriteFileOptions)                     | Options for [Fs.writeFile](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs#writefile).                     |

## Errors

| Name                                                                          | Description                                                                |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [FsError](https://evolu.dev/docs/api-reference/common/Fs/interfaces/FsError)               | A failed file system operation.                                            |
| [FsErrorReason](https://evolu.dev/docs/api-reference/common/Fs/type-aliases/FsErrorReason) | Why a file system operation failed, mapped from the platform's error code. |

## Testing

| Function                                                                 | Description                                                                                                 |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| [testCreateFs](https://evolu.dev/docs/api-reference/common/Fs/functions/testCreateFs) | Creates a test [Fs](https://evolu.dev/docs/api-reference/common/Fs/interfaces/Fs) with the supplied operation overrides. |