---
title: Fs
---
Utilities for high-level file system interactions. Utilizes WASI Preview 1 for underlying API
Added in 0.7.0
No other changes yet.
```grain
from "fs" include Fs
```
```grain
Fs.Utf8.readFile(Path.fromString("baz.txt"))
```
```grain
Fs.Utf8.writeFile(Path.fromString("baz.txt"), "Hello World\n")
```
```grain
Fs.copy(Path.fromString("foo.txt"), Path.fromString("foocopy.txt"))
```
## Types
Type declarations included in the Fs module.
### Fs.**FileError**
```grain
enum FileError {
NoPreopenedDirectories,
PermissionDenied,
AddressInUse,
AddressNotAvailable,
AddressFamilyNotSupported,
ResourceUnavailableOrOperationWouldBlock,
ConnectionAlreadyInProgress,
BadFileDescriptor,
BadMessage,
DeviceOrResourceBusy,
OperationCanceled,
NoChildProcesses,
ConnectionAborted,
ConnectionRefused,
ConnectionReset,
ResourceDeadlockWouldOccur,
DestinationAddressRequired,
MathematicsArgumentOutOfDomainOfFunction,
FileExists,
BadAddress,
FileTooLarge,
HostIsUnreachable,
IdentifierRemoved,
IllegalByteSequence,
OperationInProgress,
InterruptedFunction,
InvalidArgument,
IOError,
SocketIsConnected,
IsADirectory,
TooManyLevelsOfSymbolicLinks,
FileDescriptorValueTooLarge,
TooManyLinks,
MessageTooLarge,
FilenameTooLong,
NetworkIsDown,
ConnectionAbortedByNetwork,
NetworkUnreachable,
TooManyFilesOpenInSystem,
NoBufferSpaceAvailable,
NoSuchDevice,
NoSuchFileOrDirectory,
ExecutableFileFormatError,
NoLocksAvailable,
NotEnoughSpace,
NoMessageOfTheDesiredType,
ProtocolNotAvailable,
NoSpaceLeftOnDevice,
FunctionNotSupported,
TheSocketIsNotConnected,
NotADirectoryOrASymbolicLinkToADirectory,
DirectoryNotEmpty,
StateNotRecoverable,
NotASocket,
NotSupportedOrOperationNotSupportedOnSocket,
InappropriateIOControlOperation,
NoSuchDeviceOrAddress,
ValueTooLargeToBeStoredInDataType,
PreviousOwnerDied,
OperationNotPermitted,
BrokenPipe,
ProtocolError,
ProtocolNotSupported,
ProtocolWrongTypeForSocket,
ResultTooLarge,
ReadOnlyFileSystem,
InvalidSeek,
NoSuchProcess,
ConnectionTimedOut,
TextFileBusy,
CrossDeviceLink,
ExtensionCapabilitiesInsufficient,
UnknownFileError(Number),
}
```
Potential errors that can be raised from system interactions.
### Fs.**SpecialFileType**
```grain
enum SpecialFileType {
Unknown,
BlockDevice,
CharacterDevice,
SocketDatagram,
SocketStream,
}
```
Represents non-standard system file types.
### Fs.**FileType**
```grain
enum FileType {
File,
Directory,
SymbolicLink,
Special(SpecialFileType),
}
```
Represents different system file types.
### Fs.**Stats**
```grain
record Stats {
fileType: FileType,
size: Number,
accessedTimestamp: Number,
modifiedTimestamp: Number,
changedTimestamp: Number,
}
```
Represents metadata about a file.
Fields:
| name | type | description |
| ------------------- | ---------- | ------------------------------------------------ |
| `fileType` | `FileType` | |
| `size` | `Number` | File size in bytes |
| `accessedTimestamp` | `Number` | Last accessed timestamp in nanoseconds |
| `modifiedTimestamp` | `Number` | Last modified timestamp in nanoseconds |
| `changedTimestamp` | `Number` | Last file status change timestamp in nanoseconds |
### Fs.**DirectoryEntry**
```grain
record DirectoryEntry {
name: String,
fileType: FileType,
}
```
Represents information about an item in a directory.
### Fs.**RemoveMode**
```grain
enum RemoveMode {
RemoveFile,
RemoveEmptyDirectory,
RemoveRecursive,
}
```
The type of removal operation to perform when calling `remove`.
### Fs.**CopyMode**
```grain
enum CopyMode {
CopyFile,
CopyRecursive,
}
```
The type of copy operation to perform when calling `copy`.
### Fs.**WriteMode**
```grain
enum WriteMode {
Truncate,
Append,
}
```
The type of write operation to perform when calling `writeFile`.
## Values
Functions and constants included in the Fs module.
### Fs.**remove**
Added in 0.7.0
No other changes yet.
```grain
remove:
(?removeMode: RemoveMode, ?baseDirPath: Option, path: Path.Path) =>
Result
```
Removes a file or directory.
Parameters:
| param | type | description |
| -------------- | ------------------- | --------------------------------------------------------- |
| `?removeMode` | `RemoveMode` | The type of removal to perform; `RemoveFile` by default |
| `?baseDirPath` | `Option` | The path to the directory in which path resolution starts |
| `path` | `Path.Path` | The path of the file or directory to remove |
Returns:
| type | description |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `Result` | `Ok(void)` if the operation succeeds, `Err(err)` if a file system error is encountered |
Examples:
```grain
Fs.remove(Path.fromString("file.txt")) // removes a file
```
```grain
Fs.remove(removeMode=Fs.RemoveEmptyDirectory, Path.fromString("dir")) // removes an empty directory
```
```grain
Fs.remove(removeMode=Fs.RemoveRecursive, Path.fromString("dir")) // removes the directory and its contents
```
### Fs.**readDir**
Added in 0.7.0
No other changes yet.
```grain
readDir:
(?baseDirPath: Option, path: Path.Path) =>
Result, FileError>
```
Reads the contents of a directory.
Parameters:
| param | type | description |
| -------------- | ------------------- | ---------------------------------------------------------- |
| `?baseDirPath` | `Option` | The path to the directory in which resolution should begin |
| `path` | `Path.Path` | The path to the directory to read |
Returns:
| type | description |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `Result, FileError>` | `Ok(contents)` containing the directory contents or `Err(err)` if a file system error is encountered |
### Fs.**createDir**
Added in 0.7.0
No other changes yet.
```grain
createDir:
(?baseDirPath: Option, path: Path.Path) =>
Result
```
Creates a new empty directory at the given path.
Parameters:
| param | type | description |
| -------------- | ------------------- | -------------------------------------------------------------------- |
| `?baseDirPath` | `Option` | The path to the directory in which resolution should begin |
| `path` | `Path.Path` | The path to create the new directory, relative to the base directory |
Returns:
| type | description |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `Result` | `Ok(void)` if the operation succeeds, `Err(err)` if a file system error is encountered |
### Fs.**createSymlink**
Added in 0.7.0
No other changes yet.
```grain
createSymlink:
(linkContents: Path.Path, ?targetBaseDirPath: Option,
targetPath: Path.Path) => Result
```
Creates a new symbolic link with the given contents.
Parameters:
| param | type | description |
| -------------------- | ------------------- | -------------------------------------------------------------------- |
| `linkContents` | `Path.Path` | The path to store into the link |
| `?targetBaseDirPath` | `Option` | The path to the directory in which the target path resolution starts |
| `targetPath` | `Path.Path` | The path to the target of the link |
Returns:
| type | description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `Result` | `Ok(void)` if the operation succeeds, `Err(err)` if a file system error or relativization error is encountered |
### Fs.**stats**
Added in 0.7.0
No other changes yet.
```grain
stats:
(?followSymlink: Bool, ?baseDirPath: Option, path: Path.Path) =>
Result
```
Queries information about a file.
Parameters:
| param | type | description |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `?followSymlink` | `Bool` | Whether to follow symlinks or not; if `true` then the stats of a valid symlink's underlying file will be returned. `true` by default |
| `?baseDirPath` | `Option` | The path to the directory in which the path resolution starts |
| `path` | `Path.Path` | The path of the file to query |
Returns:
| type | description |
| -------------------------- | ----------------------------------------------------------------------------------- |
| `Result` | `Ok(stats)` containing metadata or `Err(err)` if a file system error is encountered |
### Fs.**exists**
Added in 0.7.0
No other changes yet.
```grain
exists: (?baseDirPath: Option, path: Path.Path) => Bool
```
Polls whether or not a file or directory exists at the given path.
Parameters:
| param | type | description |
| -------------- | ------------------- | ------------------------------------------------------------- |
| `?baseDirPath` | `Option` | The path to the directory in which the path resolution starts |
| `path` | `Path.Path` | The path of the file to query |
Returns:
| type | description |
| ------ | --------------------------------------------------------------------- |
| `Bool` | `true` if a file or directory exists at the path or `false` otherwise |
### Fs.**readLink**
Added in 0.7.0
No other changes yet.
```grain
readLink:
(?baseDirPath: Option, path: Path.Path) =>
Result
```
Reads the contents of a symbolic link.
Parameters:
| param | type | description |
| -------------- | ------------------- | -------------------------------------------------- |
| `?baseDirPath` | `Option` | The path to the directory to begin path resolution |
| `path` | `Path.Path` | The path to the link to read |
Returns:
| type | description |
| ------------------------------ | ------------------------------------------------------------------------------------------- |
| `Result` | `Ok(path)` containing the link contents or `Err(err)` if a file system error is encountered |
### Fs.**copy**
```grain
copy:
(?copyMode: CopyMode, ?followSymlink: Bool,
?sourceBaseDirPath: Option, sourcePath: Path.Path,
?targetBaseDirPath: Option, targetPath: Path.Path) =>
Result
```
Copies a file or directory.
Parameters:
| param | type | description |
| -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `?copyMode` | `CopyMode` | The type of copy to perform; `CopyFile` by default |
| `?followSymlink` | `Bool` | Whether to follow symlinks or not; if `true` then the stats of a valid symlink's underlying file will be returned. `true` by default |
| `?sourceBaseDirPath` | `Option` | The path to the directory in which the source path resolution starts |
| `sourcePath` | `Path.Path` | The path of the file or directory to copy |
| `?targetBaseDirPath` | `Option` | The path to the directory in which the target path resolution starts |
| `targetPath` | `Path.Path` | The path to copy the file or directory to |
Returns:
| type | description |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `Result` | `Ok(void)` if the operation succeeds, `Err(err)` if a file system error is encountered |
### Fs.**rename**
Added in 0.7.0
No other changes yet.
```grain
rename:
(?sourceBaseDirPath: Option, sourcePath: Path.Path,
?targetBaseDirPath: Option, targetPath: Path.Path) =>
Result
```
Renames a file or directory.
Parameters:
| param | type | description |
| -------------------- | ------------------- | -------------------------------------------------------------------- |
| `?sourceBaseDirPath` | `Option` | The path to the directory in which the source path resolution starts |
| `sourcePath` | `Path.Path` | The path of the file to rename |
| `?targetBaseDirPath` | `Option` | The path to the directory in which the target path resolution starts |
| `targetPath` | `Path.Path` | The new path of the file |
Returns:
| type | description |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `Result` | `Ok(void)` if the operation succeeds, `Err(err)` if a file system error is encountered |
## Fs.Binary
Functionality for reading and writing `Bytes` to files.
Added in 0.7.0
No other changes yet.
### Values
Functions and constants included in the Fs.Binary module.
#### Fs.Binary.**readFile**
Added in 0.7.0
No other changes yet.
```grain
readFile:
(?sync: Bool, ?baseDirPath: Option, path: Path.Path) =>
Result
```
Read the contents of a file as `Bytes`.
Parameters:
| param | type | description |
| -------------- | ------------------- | -------------------------------------------------- |
| `?sync` | `Bool` | Whether to synchronously read; `true` by default |
| `?baseDirPath` | `Option` | The path to the directory to begin path resolution |
| `path` | `Path.Path` | The file path to read from |
Returns:
| type | description |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `Result` | `Ok(contents)` containing the bytes read if successful or `Err(err)` if a file system error is encountered |
#### Fs.Binary.**writeFile**
Added in 0.7.0
No other changes yet.
```grain
writeFile:
(?writeMode: WriteMode, ?sync: Bool, ?baseDirPath: Option,
path: Path.Path, data: Bytes) => Result
```
Write `Bytes` to a file.
Parameters:
| param | type | description |
| -------------- | ------------------- | ------------------------------------------------------------- |
| `?writeMode` | `WriteMode` | The type of write operation to perform; `Truncate` by default |
| `?sync` | `Bool` | Whether to synchronously write; `true` by default |
| `?baseDirPath` | `Option` | The path to the directory to begin path resolution |
| `path` | `Path.Path` | The file path to write to |
| `data` | `Bytes` | The bytes to write to the file |
Returns:
| type | description |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| `Result` | `Ok(void)` if the operation is successful or `Err(err)` if a file system error is encountered |
## Fs.Utf8
Functionality for reading and writing `String`s to files.
Added in 0.7.0
No other changes yet.
### Values
Functions and constants included in the Fs.Utf8 module.
#### Fs.Utf8.**readFile**
Added in 0.7.0
No other changes yet.
```grain
readFile:
(?sync: Bool, ?baseDirPath: Option, path: Path.Path) =>
Result
```
Read the contents of a file as a `String`.
Parameters:
| param | type | description |
| -------------- | ------------------- | -------------------------------------------------- |
| `?sync` | `Bool` | Whether to synchronously read; `true` by default |
| `?baseDirPath` | `Option` | The path to the directory to begin path resolution |
| `path` | `Path.Path` | The file path to read from |
Returns:
| type | description |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `Result` | `Ok(contents)` containing the string read if successful or `Err(err)` if a file system error is encountered |
#### Fs.Utf8.**writeFile**
Added in 0.7.0
No other changes yet.
```grain
writeFile:
(?writeMode: WriteMode, ?sync: Bool, ?baseDirPath: Option,
path: Path.Path, data: String) => Result
```
Write a `String` to a file.
Parameters:
| param | type | description |
| -------------- | ------------------- | ------------------------------------------------------------- |
| `?writeMode` | `WriteMode` | The type of write operation to perform; `Truncate` by default |
| `?sync` | `Bool` | Whether to synchronously write; `true` by default |
| `?baseDirPath` | `Option` | The path to the directory to begin path resolution |
| `path` | `Path.Path` | The file path to write to |
| `data` | `String` | The string to write to the file |
Returns:
| type | description |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| `Result` | `Ok(void)` if the operation is successful or `Err(err)` if a file system error is encountered |