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
*/