FileSystem
Defines the portable file system service for Effect programs.
FileSystem is the boundary between Effect code and the host file system. Platform packages provide concrete layers, while this module defines the operations for reading, writing, inspecting, streaming, and watching files. Operations return Effect, Stream, or Sink values and fail with PlatformError. The module also includes file handles, size helpers, open flags, watch events, and the watch backend service.
Constructors
Signature
declare function make(
impl: Omit<
FileSystem,
typeof TypeId | "exists" | "readFileString" | "stream" | "sink" | "writeFileString"
>,
): FileSystem;Creates a stub FileSystem implementation for tests.
Details
By default, exists returns false, remove succeeds, many file operations fail with PlatformError NotFound, and temporary-directory/file operations die as not implemented. Pass method overrides to provide the behavior needed by a specific test without touching the real file system.
Signature
declare function makeNoop(fileSystem: Partial<FileSystem>): FileSystem;Guards
Returns true if a value is a File handle by checking for the FileTypeId marker.
When to use
Use when accepting an unknown value and you need to narrow it to a File before calling file-handle operations.
Details
This is a structural marker check. It does not validate the marker value or the shape of the file handle.
See
Filefor the file-handle interface narrowed by this guardFileTypeIdfor the runtime marker checked by this guard
Signature
declare function isFile(u: unknown): u is File;Layers
Creates a Layer that provides a no-op FileSystem implementation for testing.
Details
This is a convenience function that wraps makeNoop in a Layer, making it easy to provide the test filesystem to your Effect programs.
Signature
declare function layerNoop(fileSystem: Partial<FileSystem>): Layer<FileSystem>;Models
Interface representing an open file handle.
Details
Provides low-level file operations including reading, writing, seeking, and retrieving file information. File handles are automatically managed within scoped operations to ensure proper cleanup.
Signature
interface File {
readonly "~effect/platform/FileSystem/File": "~effect/platform/FileSystem/File";
readonly read: (buffer: Uint8Array) => Effect<Size, PlatformError>;
readonly readAlloc: (
size: SizeInput,
) => Effect<Option<Uint8Array<ArrayBufferLike>>, PlatformError>;
readonly seek: (offset: SizeInput, from: SeekMode) => Effect<Size>;
readonly stat: Effect<Info, PlatformError>;
readonly sync: Effect<void, PlatformError>;
readonly truncate: (length?: SizeInput) => Effect<void, PlatformError>;
readonly write: (buffer: Uint8Array) => Effect<Size, PlatformError>;
readonly writeAll: (buffer: Uint8Array) => Effect<void, PlatformError>;
}File open flags that determine how a file is opened and what operations are allowed.
Details
These flags correspond to standard POSIX file open modes and control the file access permissions and behavior when opening files.
- "r" - Read-only. File must exist. - "r+" - Read/write. File must exist. - "w" - Write-only. Truncates file to zero length or creates new file. - "wx" - Like 'w' but fails if file exists. - "w+" - Read/write. Truncates file to zero length or creates new file. - "wx+" - Like 'w+' but fails if file exists. - "a" - Write-only. Appends to file or creates new file. - "ax" - Like 'a' but fails if file exists. - "a+" - Read/write. Appends to file or creates new file. - "ax+" - Like 'a+' but fails if file exists.
Signature
type OpenFlag = "r" | "r+" | "w" | "wx" | "w+" | "wx+" | "a" | "ax" | "a+" | "ax+";Specifies the reference point for seeking within an open file.
When to use
Use with File handles when positioning the cursor before a read or write and the offset must be interpreted from either the start of the file or the current cursor.
Details
- "start" seeks from the beginning of the file. - "current" seeks from the current cursor position.
See
Filefor the open file handle API whoseseekmethod consumes this mode
Signature
type SeekMode = "start" | "current";WatchEvent type
Represents file system events emitted when watching files or directories.
When to use
Use when consuming file system watch streams and pattern matching on _tag to handle created, updated, or removed paths.
Details
The union covers create, update, and remove events. Each event carries the reported path.
See
FileSystemfor the service interface whosewatchoperation emits these events
Signature
type WatchEvent = WatchEvent.Create | WatchEvent.Update | WatchEvent.Remove;WatchOptions interface
Options for watching files or directories.
Signature
interface WatchOptions {
readonly recursive?: boolean;
}Other
Namespace containing types associated with open file handles, including file descriptors, entry kinds, and stat information.
WatchEvent
Namespace containing the concrete event shapes emitted by FileSystem.watch.
Services
FileSystem
Service tag for platform file-system operations.
When to use
Use to access or provide operations for files, directories, permissions, streams, and sinks through the Effect context.
Details
This key is used to provide and access the FileSystem service in the Effect context.
Signature
declare const FileSystem: Service<FileSystem, FileSystem>;FileSystem interface
Core interface for file system operations in Effect.
Details
The FileSystem interface provides a comprehensive set of file and directory operations that work cross-platform. All operations return Effect values that can be composed, transformed, and executed safely with proper error handling.
Signature
interface FileSystem {
readonly "~effect/platform/FileSystem": "~effect/platform/FileSystem";
readonly access: (path: string, options?: {
readonly ok?: boolean;
readonly readable?: boolean;
readonly writable?: boolean;
}) => Effect<void, PlatformError>;
readonly chmod: (path: string, mode: number) => Effect<void, PlatformError>;
readonly chown: (path: string, uid: number, gid: number) => Effect<void, PlatformError>;
readonly copy: (fromPath: string, toPath: string, options?: {
readonly overwrite?: boolean;
readonly preserveTimestamps?: boolean;
}) => Effect<void, PlatformError>;
readonly copyFile: (fromPath: string, toPath: string) => Effect<void, PlatformError>;
readonly exists: (path: string) => Effect<boolean, PlatformError>;
readonly glob: (pattern: string, options?: {
readonly exclude?: readonly Array<string>;
readonly root?: string;
}) => Effect<Array<string>, PlatformError>;
readonly link: (fromPath: string, toPath: string) => Effect<void, PlatformError>;
readonly makeDirectory: (path: string, options?: {
readonly mode?: number;
readonly recursive?: boolean;
}) => Effect<void, PlatformError>;
readonly makeTempDirectory: (options?: {
readonly directory?: string;
readonly prefix?: string;
}) => Effect<string, PlatformError>;
readonly makeTempDirectoryScoped: (options?: {
readonly directory?: string;
readonly prefix?: string;
}) => Effect<string, PlatformError, Scope>;
readonly makeTempFile: (options?: {
readonly directory?: string;
readonly prefix?: string;
readonly suffix?: string;
}) => Effect<string, PlatformError>;
readonly makeTempFileScoped: (options?: {
readonly directory?: string;
readonly prefix?: string;
readonly suffix?: string;
}) => Effect<string, PlatformError, Scope>;
readonly open: (path: string, options?: {
readonly flag?: OpenFlag;
readonly mode?: number;
}) => Effect<File, PlatformError, Scope>;
readonly readDirectory: (path: string, options?: {
readonly recursive?: boolean;
}) => Effect<Array<string>, PlatformError>;
readonly readFile: (path: string) => Effect<Uint8Array<ArrayBufferLike>, PlatformError>;
readonly readFileString: (path: string, encoding?: string) => Effect<string, PlatformError>;
readonly readLink: (path: string) => Effect<string, PlatformError>;
readonly realPath: (path: string) => Effect<string, PlatformError>;
readonly remove: (path: string, options?: {
readonly force?: boolean;
readonly recursive?: boolean;
}) => Effect<void, PlatformError>;
readonly rename: (oldPath: string, newPath: string) => Effect<void, PlatformError>;
readonly sink: (path: string, options?: {
readonly flag?: OpenFlag;
readonly mode?: number;
}) => Sink<void, Uint8Array<ArrayBufferLike>, never, PlatformError>;
readonly stat: (path: string) => Effect<Info, PlatformError>;
readonly stream: (path: string, options?: {
readonly bytesToRead?: SizeInput;
readonly chunkSize?: SizeInput;
readonly offset?: SizeInput;
}) => Stream<Uint8Array<ArrayBufferLike>, PlatformError>;
readonly symlink: (fromPath: string, toPath: string) => Effect<void, PlatformError>;
readonly truncate: (path: string, length?: SizeInput) => Effect<void, PlatformError>;
readonly utimes: (path: string, atime: number | Date, mtime: number | Date) => Effect<void, PlatformError>;
readonly watch: (path: string, options?: WatchOptions) => Stream<WatchEvent, PlatformError>;
readonly writeFile: (path: string, data: Uint8Array, options?: {
readonly flag?: OpenFlag;
readonly mode?: number;
}) => Effect<void, PlatformError>;
readonly writeFileString: (path: string, data: string, options?: {
readonly flag?: OpenFlag;
readonly mode?: number;
}) => Effect<void, PlatformError>;
}WatchBackend
Service key for file system watch backend implementations.
Details
This service provides the low-level file watching capabilities that can be implemented differently on various platforms (e.g., inotify on Linux, FSEvents on macOS, etc.).
Signature
declare class WatchBackend extends Shape<
"effect/platform/FileSystem/WatchBackend",
{
readonly register: (
path: string,
stat: Info,
options?: WatchOptions,
) => Option<Stream<WatchEvent, PlatformError, never>>;
},
this
> {
constructor(_: never);
}Sizes
Creates a Size representing gibibytes (1024³ bytes).
Details
Converts a number of gibibytes to the equivalent size in bytes. Uses binary gibibytes (1,073,741,824 bytes) rather than decimal gigabytes.
Signature
declare function GiB(n: number): Size;Creates a Size representing kilobytes (1024 bytes).
Details
Converts a number of kilobytes to the equivalent size in bytes. Uses binary kilobytes (1024 bytes) rather than decimal (1000 bytes).
Signature
declare function KiB(n: number): Size;Creates a Size representing mebibytes (1024² bytes).
Details
Converts a number of mebibytes to the equivalent size in bytes. Uses binary mebibytes (1,048,576 bytes) rather than decimal megabytes.
Signature
declare function MiB(n: number): Size;Creates a Size representing pebibytes (1024⁵ bytes).
Details
Converts a number of pebibytes to the equivalent size in bytes. Uses binary pebibytes (1,125,899,906,842,624 bytes) rather than decimal petabytes. This function uses BigInt arithmetic to handle the very large numbers involved.
Signature
declare function PiB(n: number): Size;Creates a Size from various numeric input types.
Details
Converts numbers, bigints, or existing Size values into a properly branded Size type. This function handles the conversion and ensures type safety for file size operations.
Signature
declare const Size: (bytes: SizeInput) => Size;Represents a file size in bytes using a branded bigint.
Details
This type ensures type safety when working with file sizes, preventing accidental mixing of regular numbers with size values. The underlying bigint allows for handling very large file sizes beyond JavaScript's number precision limits.
Signature
type Size = Brand.Branded<bigint, "Size">;Input type for size parameters that accepts multiple numeric types.
Details
This union type allows file system operations to accept size values in different formats for convenience, which are then normalized to the branded Size type internally.
Signature
type SizeInput = bigint | number | Size;Creates a Size representing tebibytes (1024⁴ bytes).
Details
Converts a number of tebibytes to the equivalent size in bytes. Uses binary tebibytes (1,099,511,627,776 bytes) rather than decimal terabytes.
Signature
declare function TiB(n: number): Size;Type IDs
FileTypeId
Runtime type identifier attached to FileSystem.File handles and used by isFile to recognize them.
Details
This marker is part of the runtime representation of file handles. Prefer isFile when narrowing unknown values.
See
Signature
declare const FileTypeId: "~effect/platform/FileSystem/File";
Creates a FileSystem implementation from a partial implementation.
When to use
Use to build a concrete
FileSystemservice from platform-specific core operations while deriving the convenience methods that can be implemented from them.Details
This function takes a partial FileSystem implementation and automatically provides default implementations for
exists,readFileString,stream,sink, andwriteFileStringmethods based on the provided core methods.See
makeNoopfor a testing stub that accepts method overrides without requiring a complete implementationlayerNoopfor providing a no-opFileSystemas aLayerin tests