Skip to content
Docs menu / FileSystem

FileSystem

The @effect/platform/FileSystem module provides a set of operations for reading and writing from/to the file system.

Basic Usage

The module provides a single FileSystem tag, which acts as the gateway for interacting with the filesystem.

Example (Accessing File System Operations)

import { FileSystem } from "@effect/platform"
import { Effect } from "effect"


const program = Effect.gen(function* () {
  const fs = yield* FileSystem.FileSystem


  // Use `fs` to perform file system operations
})

The FileSystem interface includes the following operations:

Operation Description
access Check if a file can be accessed. You can optionally specify the level of access to check for.
copy Copy a file or directory from fromPath to toPath. Equivalent to cp -r.
copyFile Copy a file from fromPath to toPath.
chmod Change the permissions of a file.
chown Change the owner and group of a file.
exists Check if a path exists.
link Create a hard link from fromPath to toPath.
makeDirectory Create a directory at path. You can optionally specify the mode and whether to recursively create nested directories.
makeTempDirectory Create a temporary directory. By default, the directory will be created inside the system’s default temporary directory.
makeTempDirectoryScoped Create a temporary directory inside a scope. Functionally equivalent to makeTempDirectory, but the directory will be automatically deleted when the scope is closed.
makeTempFile Create a temporary file. The directory creation is functionally equivalent to makeTempDirectory. The file name will be a randomly generated string.
makeTempFileScoped Create a temporary file inside a scope. Functionally equivalent to makeTempFile, but the file will be automatically deleted when the scope is closed.
open Open a file at path with the specified options. The file handle will be automatically closed when the scope is closed.
readDirectory List the contents of a directory. You can recursively list the contents of nested directories by setting the recursive option.
readFile Read the contents of a file.
readFileString Read the contents of a file as a string.
readLink Read the destination of a symbolic link.
realPath Resolve a path to its canonicalized absolute pathname.
remove Remove a file or directory. By setting the recursive option to true, you can recursively remove nested directories.
rename Rename a file or directory.
sink Create a writable Sink for the specified path.
stat Get information about a file at path.
stream Create a readable Stream for the specified path.
symlink Create a symbolic link from fromPath to toPath.
truncate Truncate a file to a specified length. If the length is not specified, the file will be truncated to length 0.
utimes Change the file system timestamps of the file at path.
watch Watch a directory or file for changes.
writeFile Write data to a file at path.
writeFileString Write a string to a file at path.

Example (Reading a File as a String)

import { FileSystem } from "@effect/platform"
import { NodeContext, NodeRuntime } from "@effect/platform-node"
import { Effect } from "effect"


//      ┌─── Effect<void, PlatformError, FileSystem>
//      ▼
const program = Effect.gen(function* () {
  const fs = yield* FileSystem.FileSystem


  // Reading the content of the same file where this code is written
  const content = yield* fs.readFileString("./index.ts", "utf8")
  console.log(content)
})


// Provide the necessary context and run the program
NodeRuntime.runMain(program.pipe(Effect.provide(NodeContext.layer)))

Mocking the File System

In testing environments, you may want to mock the file system to avoid performing actual disk operations. The FileSystem.layerNoop provides a no-operation implementation of the FileSystem service.

Most operations in FileSystem.layerNoop return a failure (e.g., Effect.fail for missing files) or a defect (e.g., Effect.die for unimplemented features). However, you can override specific behaviors by passing an object to FileSystem.layerNoop to define custom return values for selected methods.

Example (Mocking File System with Custom Behavior)

import { FileSystem } from "@effect/platform"
import { Effect } from "effect"


const program = Effect.gen(function* () {
  const fs = yield* FileSystem.FileSystem


  const exists = yield* fs.exists("/some/path")
  console.log(exists)


  const content = yield* fs.readFileString("/some/path")
  console.log(content)
})


//      ┌─── Layer<FileSystem.FileSystem, never, never>
//      ▼
const customMock = FileSystem.layerNoop({
  readFileString: () => Effect.succeed("mocked content"),
  exists: (path) => Effect.succeed(path === "/some/path"),
})


// Provide the customized FileSystem mock implementation
Effect.runPromise(program.pipe(Effect.provide(customMock)))
/*
Output:
true
mocked content
*/