Fs - API reference

File system operations for Tasks.

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 through runMain or createRun. Tasks declare FsDep and access the file system through run.deps.fs.

FsError includes the path, a diagnostic message, and a FsErrorReason such as NotFound or PermissionDenied. Fs.exists returns false for NotFound and preserves other errors.

Example

import {
  assertEqual,
  ok,
  type FsDep,
  type FsError,
  type Task,
} from "@evolu/common";
import { createNodeFs, runMain } from "@evolu/nodejs";
import { join } from "node:path";

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	Asynchronous file system operations.
FsDep	Dependency wrapper for Fs.
FsMetadata	File metadata as data, with Node's numeric and timestamp field names.
FsReadFile	Reads bytes by default, or text when an encoding is specified.
FsTempDirectory	A temporary directory removed, with its contents, on asynchronous disposal.
FsEncoding	Supported text encodings.
FsEntryType	The kind of file system entry described by FsMetadata.
FsOpenFlag	Supported file opening modes for Fs.writeFile.
FsPath	A file system path, or a `file:` URL.

Options

Interface	Description
FsCopyFileOptions	Options for Fs.copyFile.
FsCopyOptions	Options for Fs.copy.
FsCreateDirectoryOptions	Options for Fs.createDirectory.
FsCreateTempDirectoryOptions	Options for Fs.createTempDirectory.
FsReadDirectoryOptions	Options for Fs.readDirectory.
FsRemoveOptions	Options for Fs.remove.
FsWriteFileOptions	Options for Fs.writeFile.

Errors

Name	Description
FsError	A failed file system operation.
FsErrorReason	Why a file system operation failed, mapped from the platform's error code.

Testing

Function	Description
testCreateFs	Creates a test Fs with the supplied operation overrides.