File Domain

The File domain bridges the gap between your code and the disk.

Your code lives in ephemeral memory, but data needs to persist. This domain lets you safely read configs, save user data, and inspect directories.

• Read/Write: Load a config or save a savegame.
• Check: "Does this file exist?"
• Inspect: "When was this modified?"

Direct file access is dangerous (locks, missing files, permissions). AIVI wraps these in Effect types, forcing you to handle errors explicitly. Your program won't crash just because a file is missing; it will handle it.

Overview

use aivi.file (readText, stat)

main = effect {
  // Safe reading
  contentRes <- readText "config.json"
  contentRes ?
    | Ok content => print content
    | Err _ => print "missing config"

  // Metadata inspection
  infoRes <- stat "large_video.mp4"
  infoRes ?
    | Ok info => print "File size: {info.size} bytes"
    | Err _   => print "File not found"
}

Types

FileStats = {
  size: Int          // Size in bytes
  created: Int       // Unix timestamp (ms)
  modified: Int      // Unix timestamp (ms)
  isFile: Bool
  isDirectory: Bool
}

Resource Operations

For more control or large files, use the resource-based API.

open

Function	Explanation
open path Text -> Resource Handle	Opens a file for reading and returns a managed Handle resource.

readAll

Function	Explanation
readAll handle Handle -> Effect (Result Text Text)	Reads the entire contents of an open handle as text.

close

Function	Explanation
close handle Handle -> Effect Unit	Closes the file handle (automatic with resource blocks).

Path Operations

readText

Function	Explanation
readText path Text -> Effect (Result Text Text)	Reads the entire contents of path as text.

writeText

Function	Explanation
writeText path contents Text -> Text -> Effect (Result Unit Text)	Writes contents to path, overwriting if it exists.

exists

Function	Explanation
exists path Text -> Effect Bool	Returns whether a file or directory exists at path.

stat

Function	Explanation
stat path Text -> Effect (Result FileStats Text)	Retrieves metadata about a file or directory at path.

delete

Function	Explanation
delete path Text -> Effect (Result Unit Text)	Removes the file at path.