---
name: effect-patterns-platform
description: Effect-TS patterns for Platform. Use when working with platform in Effect-TS applications.
---
# Effect-TS Patterns: Platform
This skill provides 6 curated Effect-TS patterns for platform.
Use this skill when working on tasks related to:
- platform
- Best practices in Effect-TS applications
- Real-world patterns and solutions

---

## 🟢 Beginner Patterns

### Platform Pattern 4: Interactive Terminal I/O

**Rule:** Use Terminal for user input/output in CLI applications, providing proper buffering and cross-platform character encoding.

**Good Example:**

This example demonstrates building an interactive CLI application.

```typescript
import { Terminal, Effect } from "@effect/platform";

interface UserInput {
  readonly name: string;
  readonly email: string;
  readonly age: number;
}

const program = Effect.gen(function* () {
  console.log(`\n[INTERACTIVE CLI] User Information Form\n`);

  // Example 1: Simple prompts
  yield* Terminal.writeLine(`=== User Setup ===`);
  yield* Terminal.writeLine(``);

  yield* Terminal.write(`What is your name? `);
  const name = yield* Terminal.readLine();

  yield* Terminal.write(`What is your email? `);
  const email = yield* Terminal.readLine();

  yield* Terminal.write(`What is your age? `);
  const ageStr = yield* Terminal.readLine();

  const age = parseInt(ageStr);

  // Example 2: Display collected information
  yield* Terminal.writeLine(``);
  yield* Terminal.writeLine(`=== Summary ===`);
  yield* Terminal.writeLine(`Name: ${name}`);
  yield* Terminal.writeLine(`Email: ${email}`);
  yield* Terminal.writeLine(`Age: ${age}`);

  // Example 3: Confirmation
  yield* Terminal.writeLine(``);
  yield* Terminal.write(`Confirm information? (yes/no) `);
  const confirm = yield* Terminal.readLine();

  if (confirm.toLowerCase() === "yes") {
    yield* Terminal.writeLine(`✓ Information saved`);
  } else {
    yield* Terminal.writeLine(`✗ Cancelled`);
  }
});

Effect.runPromise(program);
```

---

**Rationale:**

Terminal operations:

- **readLine**: Read single line of user input
- **readPassword**: Read input without echoing (passwords)
- **writeLine**: Write line with newline
- **write**: Write without newline
- **clearScreen**: Clear terminal

Pattern: `Terminal.readLine().pipe(...)`

---


Direct stdin/stdout causes issues:

- **No buffering**: Interleaved output in concurrent context
- **Encoding issues**: Special characters corrupted
- **Password echo**: Security vulnerability
- **No type safety**: String manipulation error-prone

Terminal enables:

- **Buffered I/O**: Safe concurrent output
- **Encoding handling**: UTF-8 and special chars
- **Password input**: No echo mode
- **Structured interaction**: Prompts and validation

Real-world example: CLI setup wizard
- **Direct**: console.log mixed with readline, no error handling
- **With Terminal**: Structured input, validation, formatted output

---

---

### Platform Pattern 2: Filesystem Operations

**Rule:** Use FileSystem module for safe, resource-managed file operations with proper error handling and cleanup.

**Good Example:**

This example demonstrates reading, writing, and manipulating files.

```typescript
import { FileSystem, Effect, Stream } from "@effect/platform";
import * as fs from "fs/promises";

const program = Effect.gen(function* () {
  console.log(`\n[FILESYSTEM] Demonstrating file operations\n`);

  // Example 1: Write a file
  console.log(`[1] Writing file:\n`);

  const content = `Hello, Effect-TS!\nThis is a test file.\nCreated at ${new Date().toISOString()}`;

  yield* FileSystem.writeFileUtf8("test.txt", content);

  yield* Effect.log(`✓ File written: test.txt`);

  // Example 2: Read the file
  console.log(`\n[2] Reading file:\n`);

  const readContent = yield* FileSystem.readFileUtf8("test.txt");

  console.log(readContent);

  // Example 3: Get file stats
  console.log(`\n[3] File stats:\n`);

  const stats = yield* FileSystem.stat("test.txt").pipe(
    Effect.flatMap((stat) =>
      Effect.succeed({
        size: stat.size,
        isFile: stat.isFile(),
        modified: stat.mtimeMs,
      })
    )
  );

  console.log(`  Size: ${stats.size} bytes`);
  console.log(`  Is file: ${stats.isFile}`);
  console.log(`  Modified: ${new Date(stats.modified).toISOString()}`);

  // Example 4: Create directory and write multiple files
  console.log(`\n[4] Creating directory and files:\n`);

  yield* FileSystem.mkdir("test-dir");

  yield* Effect.all(
    Array.from({ length: 3 }, (_, i) =>
      FileSystem.writeFileUtf8(
        `test-dir/file-${i + 1}.txt`,
        `Content of file ${i + 1}`
      )
    )
  );

  yield* Effect.log(`✓ Created directory with 3 files`);

  // Example 5: List directory contents
  console.log(`\n[5] Listing directory:\n`);

  const entries = yield* FileSystem.readDirectory("test-dir");

  entries.forEach((entry) => {
    console.log(`  - ${entry}`);
  });

  // Example 6: Append to file
  console.log(`\n[6] Appending to file:\n`);

  const appendContent = `\nAppended line at ${new Date().toISOString()}`;

  yield* FileSystem.appendFileUtf8("test.txt", appendContent);

  const finalContent = yield* FileSystem.readFileUtf8("test.txt");

  console.log(`File now has ${finalContent.split("\n").length} lines`);

  // Example 7: Clean up
  console.log(`\n[7] Cleaning up:\n`);

  yield* Effect.all(
    Array.from({ length: 3 }, (_, i) =>
      FileSystem.remove(`test-dir/file-${i + 1}.txt`)
    )
  );

  yield* FileSystem.remove("test-dir");
  yield* FileSystem.remove("test.txt");

  yield* Effect.log(`✓ Cleanup complete`);
});

Effect.runPromise(program);
```

---

**Rationale:**

FileSystem operations:

- **read**: Read file as string
- **readDirectory**: List files in directory
- **write**: Write string to file
- **remove**: Delete file or directory
- **stat**: Get file metadata

Pattern: `FileSystem.read(path).pipe(...)`

---


Direct file operations without FileSystem create issues:

- **Resource leaks**: Files not closed on errors
- **No error context**: Missing file names in errors
- **Blocking**: No async/await integration
- **Cross-platform**: Path handling differences

FileSystem enables:

- **Resource safety**: Automatic cleanup
- **Error context**: Full error messages
- **Async integration**: Effect-native
- **Cross-platform**: Handles path separators

Real-world example: Process log files
- **Direct**: Open file, read, close, handle exceptions manually
- **With FileSystem**: `FileSystem.read(path).pipe(...)`

---

---


## 🟡 Intermediate Patterns

### Platform Pattern 3: Persistent Key-Value Storage

**Rule:** Use KeyValueStore for simple persistent storage of key-value pairs, enabling lightweight caching and session management.

**Good Example:**

This example demonstrates storing and retrieving persistent data.

```typescript
import { KeyValueStore, Effect } from "@effect/platform";

interface UserSession {
  readonly userId: string;
  readonly token: string;
  readonly expiresAt: number;
}

const program = Effect.gen(function* () {
  console.log(`\n[KEYVALUESTORE] Persistent storage example\n`);

  const store = yield* KeyValueStore.KeyValueStore;

  // Example 1: Store session data
  console.log(`[1] Storing session:\n`);

  const session: UserSession = {
    userId: "user-123",
    token: "token-abc-def",
    expiresAt: Date.now() + 3600000, // 1 hour
  };

  yield* store.set("session:user-123", JSON.stringify(session));

  yield* Effect.log(`✓ Session stored`);

  // Example 2: Retrieve stored data
  console.log(`\n[2] Retrieving session:\n`);

  const stored = yield* store.get("session:user-123");

  if (stored._tag === "Some") {
    const retrievedSession = JSON.parse(stored.value) as UserSession;

    console.log(`  User ID: ${retrievedSession.userId}`);
    console.log(`  Token: ${retrievedSession.token}`);
    console.log(
      `  Expires: ${new Date(retrievedSession.expiresAt).toISOString()}`
    );
  }

  // Example 3: Check if key exists
  console.log(`\n[3] Checking keys:\n`);

  const hasSession = yield* store.has("session:user-123");
  const hasOther = yield* store.has("session:user-999");

  console.log(`  Has session:user-123: ${hasSession}`);
  console.log(`  Has session:user-999: ${hasOther}`);

  // Example 4: Store multiple cache entries
  console.log(`\n[4] Caching API responses:\n`);

  const apiResponses = [
    { endpoint: "/api/users", data: [{ id: 1, name: "Alice" }] },
    { endpoint: "/api/posts", data: [{ id: 1, title: "First Post" }] },
    { endpoint: "/api/comments", data: [] },
  ];

  yield* Effect.all(
    apiResponses.map((item) =>
      store.set(
        `cache:${item.endpoint}`,
        JSON.stringify(item.data)
      )
    )
  );

  yield* Effect.log(`✓ Cached ${apiResponses.length} endpoints`);

  // Example 5: Retrieve cache with expiration
  console.log(`\n[5] Checking cached data:\n`);

  for (const item of apiResponses) {
    const cached = yield* store.get(`cache:${item.endpoint}`);

    if (cached._tag === "Some") {
      const data = JSON.parse(cached.value);

      console.log(
        `  ${item.endpoint}: ${Array.isArray(data) ? data.length : 1} items`
      );
    }
  }

  // Example 6: Remove specific entry
  console.log(`\n[6] Removing entry:\n`);

  yield* store.remove("cache:/api/comments");

  const removed = yield* store.has("cache:/api/comments");

  console.log(`  Exists after removal: ${removed}`);

  // Example 7: Iterate and count entries
  console.log(`\n[7] Counting entries:\n`);

  const allKeys = yield* store.entries.pipe(
    Effect.map((entries) => entries.length)
  );

  console.log(`  Total entries: ${allKeys}`);
});

Effect.runPromise(program);
```

---

**Rationale:**

KeyValueStore operations:

- **set**: Store key-value pair
- **get**: Retrieve value by key
- **remove**: Delete key
- **has**: Check if key exists
- **clear**: Remove all entries

Pattern: `KeyValueStore.set(key, value).pipe(...)`

---


Without persistent storage, transient data is lost:

- **Session data**: Lost on restart
- **Caches**: Rebuilt from scratch
- **Configuration**: Hardcoded or file-based
- **State**: Scattered across code

KeyValueStore enables:

- **Transparent persistence**: Automatic backend handling
- **Simple API**: Key-value abstraction
- **Pluggable backends**: Memory, filesystem, database
- **Effect integration**: Type-safe, composable

Real-world example: Caching API responses
- **Direct**: Cache in memory Map (lost on restart)
- **With KeyValueStore**: Persistent across restarts

---

---

### Platform Pattern 1: Execute Shell Commands

**Rule:** Use Command to spawn and manage external processes, capturing output and handling exit codes reliably with proper error handling.

**Good Example:**

This example demonstrates executing commands and handling their output.

```typescript
import { Command, Effect, Chunk } from "@effect/platform";

// Simple command execution
const program = Effect.gen(function* () {
  console.log(`\n[COMMAND] Executing shell commands\n`);

  // Example 1: List files
  console.log(`[1] List files in current directory:\n`);

  const lsResult = yield* Command.make("ls", ["-la"]).pipe(
    Command.string
  );

  console.log(lsResult);

  // Example 2: Get current date
  console.log(`\n[2] Get current date:\n`);

  const dateResult = yield* Command.make("date", ["+%Y-%m-%d %H:%M:%S"]).pipe(
    Command.string
  );

  console.log(`Current date: ${dateResult.trim()}`);

  // Example 3: Capture exit code
  console.log(`\n[3] Check if file exists:\n`);

  const fileCheckCmd = yield* Command.make("test", [
    "-f",
    "/etc/passwd",
  ]).pipe(
    Command.exitCode,
    Effect.either
  );

  if (fileCheckCmd._tag === "Right") {
    console.log(`✓ File exists (exit code: 0)`);
  } else {
    console.log(`✗ File not found (exit code: ${fileCheckCmd.left})`);
  }

  // Example 4: Execute with custom working directory
  console.log(`\n[4] List TypeScript files:\n`);

  const findResult = yield* Command.make("find", [
    ".",
    "-name",
    "*.ts",
    "-type",
    "f",
  ]).pipe(
    Command.lines
  );

  const tsFiles = Chunk.take(findResult, 5); // First 5

  Chunk.forEach(tsFiles, (file) => {
    console.log(`  - ${file}`);
  });

  if (Chunk.size(findResult) > 5) {
    console.log(`  ... and ${Chunk.size(findResult) - 5} more`);
  }

  // Example 5: Handle command failure
  console.log(`\n[5] Handle command failure gracefully:\n`);

  const failResult = yield* Command.make("false").pipe(
    Command.exitCode,
    Effect.catchAll((error) =>
      Effect.succeed(-1) // Return -1 for any error
    )
  );

  console.log(`Exit code: ${failResult}`);
});

Effect.runPromise(program);
```

---

**Rationale:**

Execute shell commands with Command:

- **Spawn**: Start external process
- **Capture**: Get stdout/stderr/exit code
- **Wait**: Block until completion
- **Handle errors**: Exit codes indicate failure

Pattern: `Command.exec("command args").pipe(...)`

---


Shell integration without proper handling causes issues:

- **Unhandled errors**: Non-zero exit codes lost
- **Deadlocks**: Stdout buffer fills if not drained
- **Resource leaks**: Processes left running
- **Output loss**: stderr ignored
- **Race conditions**: Unsafe concurrent execution

Command enables:

- **Type-safe execution**: Success/failure handled in Effect
- **Output capture**: Both stdout and stderr available
- **Resource cleanup**: Automatic process termination
- **Exit code handling**: Explicit error mapping

Real-world example: Build pipeline
- **Direct**: Process spawned, output mixed with app logs, exit code ignored
- **With Command**: Output captured, exit code checked, errors propagated

---

---

### Platform Pattern 5: Cross-Platform Path Manipulation

**Rule:** Use Effect's platform-aware path utilities to handle separators, absolute/relative paths, and environment variables consistently.

**Good Example:**

This example demonstrates cross-platform path manipulation.

```typescript
import { Effect, FileSystem } from "@effect/platform";
import * as Path from "node:path";
import * as OS from "node:os";

interface PathOperation {
  readonly input: string;
  readonly description: string;
}

// Platform info
const getPlatformInfo = () =>
  Effect.gen(function* () {
    const platform = process.platform;
    const separator = Path.sep;
    const delimiter = Path.delimiter;
    const homeDir = OS.homedir();

    yield* Effect.log(
      `[PLATFORM] OS: ${platform}, Separator: "${separator}", Home: ${homeDir}`
    );

    return { platform, separator, delimiter, homeDir };
  });

const program = Effect.gen(function* () {
  console.log(`\n[PATH MANIPULATION] Cross-platform path operations\n`);

  const platformInfo = yield* getPlatformInfo();

  // Example 1: Path joining (handles separators)
  console.log(`\n[1] Joining paths (handles separators automatically):\n`);

  const segments = ["data", "reports", "2024"];

  const joinedPath = Path.join(...segments);

  yield* Effect.log(`[JOIN] Input: ${segments.join(" + ")}`);
  yield* Effect.log(`[JOIN] Output: ${joinedPath}`);

  // Example 2: Resolving to absolute paths
  console.log(`\n[2] Resolving relative → absolute:\n`);

  const relativePath = "./config/settings.json";

  const absolutePath = Path.resolve(relativePath);

  yield* Effect.log(`[RESOLVE] Relative: ${relativePath}`);
  yield* Effect.log(`[RESOLVE] Absolute: ${absolutePath}`);

  // Example 3: Path parsing
  console.log(`\n[3] Parsing path components:\n`);

  const filePath = "/home/user/documents/report.pdf";

  const parsed = Path.parse(filePath);

  yield* Effect.log(`[PARSE] Input: ${filePath}`);
  yield* Effect.log(`  root: ${parsed.root}`);
  yield* Effect.log(`  dir: ${parsed.dir}`);
  yield* Effect.log(`  base: ${parsed.base}`);
  yield* Effect.log(`  name: ${parsed.name}`);
  yield* Effect.log(`  ext: ${parsed.ext}`);

  // Example 4: Environment variable expansion
  console.log(`\n[4] Environment variable expansion:\n`);

  const expandPath = (pathStr: string): string => {
    let result = pathStr;

    // Expand common variables
    result = result.replace("$HOME", OS.homedir());
    result = result.replace("~", OS.homedir());
    result = result.replace("$USER", process.env.USER || "user");
    result = result.replace("$PWD", process.cwd());

    // Handle Windows-style env vars
    result = result.replace(/%USERPROFILE%/g, OS.homedir());
    result = result.replace(/%USERNAME%/g, process.env.USERNAME || "user");
    result = result.replace(/%TEMP%/g, OS.tmpdir());

    return result;
  };

  const envPaths = [
    "$HOME/myapp/data",
    "~/documents/file.txt",
    "$PWD/config",
    "/var/log/app.log",
  ];

  for (const envPath of envPaths) {
    const expanded = expandPath(envPath);

    yield* Effect.log(
      `[EXPAND] ${envPath} → ${expanded}`
    );
  }

  // Example 5: Path normalization (remove redundant separators)
  console.log(`\n[5] Path normalization:\n`);

  const messyPaths = [
    "/home//user///documents",
    "C:\\Users\\\\documents\\\\file.txt",
    "./config/../config/./settings",
    "../data/../../root",
  ];

  for (const messy of messyPaths) {
    const normalized = Path.normalize(messy);

    yield* Effect.log(
      `[NORMALIZE] ${messy}`
    );
    yield* Effect.log(
      `[NORMALIZE]   → ${normalized}`
    );
  }

  // Example 6: Safe path construction with base directory
  console.log(`\n[6] Safe path construction (path traversal prevention):\n`);

  const baseDir = "/var/app/data";

  const safeJoin = (base: string, userPath: string): Result<string> => {
    // Reject absolute paths from untrusted input
    if (Path.isAbsolute(userPath)) {
      return { success: false, reason: "Absolute paths not allowed" };
    }

    // Reject paths with ..
    if (userPath.includes("..")) {
      return { success: false, reason: "Path traversal attempt detected" };
    }

    // Resolve and verify within base
    const fullPath = Path.resolve(base, userPath);

    if (!fullPath.startsWith(base)) {
      return { success: false, reason: "Path escapes base directory" };
    }

    return { success: true, path: fullPath };
  };

  interface Result<T> {
    success: boolean;
    reason?: string;
    path?: T;
  }

  const testPaths = [
    "reports/2024.json",
    "/etc/passwd",
    "../../../root",
    "data/file.txt",
  ];

  for (const test of testPaths) {
    const result = safeJoin(baseDir, test);

    if (result.success) {
      yield* Effect.log(`[SAFE] ✓ ${test} → ${result.path}`);
    } else {
      yield* Effect.log(`[SAFE] ✗ ${test} (${result.reason})`);
    }
  }

  // Example 7: Relative path calculation
  console.log(`\n[7] Computing relative paths:\n`);

  const fromDir = "/home/user/projects/myapp";
  const toPath = "/home/user/data/config.json";

  const relativePath2 = Path.relative(fromDir, toPath);

  yield* Effect.log(`[RELATIVE] From: ${fromDir}`);
  yield* Effect.log(`[RELATIVE] To: ${toPath}`);
  yield* Effect.log(`[RELATIVE] Relative: ${relativePath2}`);

  // Example 8: Common path patterns
  console.log(`\n[8] Common patterns:\n`);

  // Get file extension
  const fileName = "document.tar.gz";
  const ext = Path.extname(fileName);
  const baseName = Path.basename(fileName);
  const dirName = Path.dirname("/home/user/file.txt");

  yield* Effect.log(`[PATTERNS] File: ${fileName}`);
  yield* Effect.log(`  basename: ${baseName}`);
  yield* Effect.log(`  dirname: ${dirName}`);
  yield* Effect.log(`  extname: ${ext}`);

  // Example 9: Path segments array
  console.log(`\n[9] Path segments:\n`);

  const segmentPath = "/home/user/documents/report.pdf";

  const segments2 = segmentPath.split(Path.sep).filter((s) => s);

  yield* Effect.log(`[SEGMENTS] ${segmentPath}`);
  yield* Effect.log(`[SEGMENTS] → [${segments2.map((s) => `"${s}"`).join(", ")}]`);
});

Effect.runPromise(program);
```

---

**Rationale:**

Path manipulation requires platform awareness:

- **Separators**: Windows uses `\`, Unix uses `/`
- **Absolute vs relative**: `/root` vs `./file`
- **Environment variables**: `$HOME`, `%APPDATA%`
- **Resolution**: Normalize, resolve symlinks
- **Validation**: Prevent path traversal attacks

Pattern: Avoid string concatenation, use `path.join()`, `path.resolve()`

---


String-based path handling causes problems:

**Problem 1: Platform inconsistency**
- Write path: `"C:\data\file.txt"` (Windows)
- Ship to Linux, gets interpreted as literal "C:\data\file.txt"
- File not found errors, production outage

**Problem 2: Path traversal attacks**
- User supplies path: `"../../../../etc/passwd"`
- No validation → reads sensitive files
- Security vulnerability

**Problem 3: Environment variable expansion**
- User's config: `"$HOME/myapp/data"`
- Without expansion: literal `$HOME` in path
- Can't find files

**Problem 4: Symlink resolution**
- File at `/etc/ssl/certs/ca-bundle.crt` (symlink)
- Real file at `/usr/share/ca-certificates/ca-bundle.crt`
- Both point to same file, but string equality fails

Solutions:

**Platform-aware API**:
- `path.join()` handles separators
- `path.resolve()` creates absolute paths
- `path.parse()` components
- Auto-handles platform differences

**Variable expansion**:
- `$HOME`, `~` → user home
- `$USER` → username
- `$PWD` → current directory

**Validation**:
- Reject paths with `..`
- Reject absolute paths from untrusted input
- Contain paths within base directory

---

---


## 🟠 Advanced Patterns

### Platform Pattern 6: Advanced FileSystem Operations

**Rule:** Use advanced file system patterns to implement efficient, reliable file operations with proper error handling and resource cleanup.

**Good Example:**

This example demonstrates advanced file system patterns.

```typescript
import { Effect, Stream, Ref, FileSystem } from "@effect/platform";
import * as Path from "node:path";
import * as FS from "node:fs";
import * as PromiseFS from "node:fs/promises";

const program = Effect.gen(function* () {
  console.log(`\n[ADVANCED FILESYSTEM] Complex file operations\n`);

  // Example 1: Atomic file write with temporary file
  console.log(`[1] Atomic write (crash-safe):\n`);

  const atomicWrite = (
    filePath: string,
    content: string
  ): Effect.Effect<void> =>
    Effect.gen(function* () {
      const tempPath = `${filePath}.tmp`;

      try {
        // Step 1: Write to temporary file
        yield* Effect.promise(() =>
          PromiseFS.writeFile(tempPath, content, "utf-8")
        );

        yield* Effect.log(`[WRITE] Wrote to temporary file`);

        // Step 2: Ensure on disk (fsync)
        yield* Effect.promise(() =>
          PromiseFS.writeFile(tempPath, content, "utf-8")
        );

        yield* Effect.log(`[FSYNC] Data on disk`);

        // Step 3: Atomic rename
        yield* Effect.promise(() =>
          PromiseFS.rename(tempPath, filePath)
        );

        yield* Effect.log(`[RENAME] Atomic rename complete`);
      } catch (error) {
        // Cleanup on failure
        try {
          yield* Effect.promise(() => PromiseFS.unlink(tempPath));
        } catch {
          // Ignore cleanup errors
        }

        yield* Effect.fail(error);
      }
    });

  // Test atomic write
  const testFile = "./test-file.txt";

  yield* atomicWrite(testFile, "Important configuration\n");

  // Verify file
  const content = yield* Effect.promise(() =>
    PromiseFS.readFile(testFile, "utf-8")
  );

  yield* Effect.log(`[READ] Got: "${content.trim()}"\n`);

  // Example 2: Streaming read (memory efficient)
  console.log(`[2] Streaming read (handle large files):\n`);

  const streamingRead = (filePath: string) =>
    Effect.gen(function* () {
      let byteCount = 0;
      let lineCount = 0;

      const readStream = FS.createReadStream(filePath, {
        encoding: "utf-8",
        highWaterMark: 64 * 1024, // 64KB chunks
      });

      yield* Effect.log(`[STREAM] Starting read with 64KB chunks`);

      const processLine = (line: string) =>
        Effect.gen(function* () {
          byteCount += line.length;
          lineCount++;

          if (lineCount <= 2 || lineCount % 1000 === 0) {
            yield* Effect.log(
              `[LINE ${lineCount}] Length: ${line.length} bytes`
            );
          }
        });

      // In real code, process all lines
      yield* processLine("line 1");
      yield* processLine("line 2");

      yield* Effect.log(
        `[TOTAL] Read ${lineCount} lines, ${byteCount} bytes`
      );
    });

  yield* streamingRead(testFile);

  // Example 3: Recursive directory listing
  console.log(`\n[3] Recursive directory traversal:\n`);

  const recursiveList = (
    dir: string,
    maxDepth: number = 3
  ): Effect.Effect<Array<{ path: string; type: "file" | "dir" }>> =>
    Effect.gen(function* () {
      const results: Array<{ path: string; type: "file" | "dir" }> = [];

      const traverse = (currentDir: string, depth: number) =>
        Effect.gen(function* () {
          if (depth > maxDepth) {
            return;
          }

          const entries = yield* Effect.promise(() =>
            PromiseFS.readdir(currentDir, { withFileTypes: true })
          );

          for (const entry of entries) {
            const fullPath = Path.join(currentDir, entry.name);

            if (entry.isDirectory()) {
              results.push({ path: fullPath, type: "dir" });

              yield* traverse(fullPath, depth + 1);
            } else {
              results.push({ path: fullPath, type: "file" });
            }
          }
        });

      yield* traverse(dir, 0);

      return results;
    });

  // List files in current directory
  const entries = yield* recursiveList(".", 1);

  yield* Effect.log(
    `[ENTRIES] Found ${entries.length} items:`
  );

  for (const entry of entries.slice(0, 5)) {
    const type = entry.type === "file" ? "📄" : "📁";

    yield* Effect.log(`  ${type} ${entry.path}`);
  }

  // Example 4: Bulk file operations
  console.log(`\n[4] Bulk operations (efficient batching):\n`);

  const bulkCreate = (files: Array<{ name: string; content: string }>) =>
    Effect.gen(function* () {
      yield* Effect.log(`[BULK] Creating ${files.length} files...`);

      for (const file of files) {
        yield* atomicWrite(`./${file.name}`, file.content);
      }

      yield* Effect.log(`[BULK] Created ${files.length} files`);
    });

  const testFiles = [
    { name: "config1.txt", content: "Config 1" },
    { name: "config2.txt", content: "Config 2" },
    { name: "config3.txt", content: "Config 3" },
  ];

  yield* bulkCreate(testFiles);

  // Example 5: File watching (detect changes)
  console.log(`\n[5] File watching (react to changes):\n`);

  const watchFile = (filePath: string) =>
    Effect.gen(function* () {
      yield* Effect.log(`[WATCH] Starting to watch: ${filePath}`);

      let changeCount = 0;

      // Simulate file watcher
      const checkForChanges = () =>
        Effect.gen(function* () {
          for (let i = 0; i < 3; i++) {
            yield* Effect.sleep("100 millis");

            // Check file modification time
            const stat = yield* Effect.promise(() =>
              PromiseFS.stat(filePath)
            );

            // In real implementation, compare previous mtime
            if (i === 1) {
              changeCount++;

              yield* Effect.log(
                `[CHANGE] File modified (${stat.size} bytes)`
              );
            }
          }
        });

      yield* checkForChanges();

      yield* Effect.log(`[WATCH] Detected ${changeCount} changes`);
    });

  yield* watchFile(testFile);

  // Example 6: Safe concurrent file operations
  console.log(`\n[6] Concurrent file operations with safety:\n`);

  const lockFile = (filePath: string) =>
    Effect.gen(function* () {
      const lockPath = `${filePath}.lock`;

      // Acquire lock
      yield* atomicWrite(lockPath, "locked");

      yield* Effect.log(`[LOCK] Acquired: ${lockPath}`);

      try {
        // Critical section
        yield* Effect.sleep("50 millis");

        yield* Effect.log(`[CRITICAL] Operating on locked file`);
      } finally {
        // Release lock
        yield* Effect.promise(() =>
          PromiseFS.unlink(lockPath)
        );

        yield* Effect.log(`[UNLOCK] Released: ${lockPath}`);
      }
    });

  yield* lockFile(testFile);

  // Example 7: Efficient file copying
  console.log(`\n[7] Efficient file copying:\n`);

  const efficientCopy = (
    source: string,
    destination: string
  ): Effect.Effect<void> =>
    Effect.gen(function* () {
      const stat = yield* Effect.promise(() =>
        PromiseFS.stat(source)
      );

      yield* Effect.log(
        `[COPY] Reading ${(stat.size / 1024).toFixed(2)}KB`
      );

      const content = yield* Effect.promise(() =>
        PromiseFS.readFile(source)
      );

      yield* atomicWrite(destination, content.toString());

      yield* Effect.log(`[COPY] Complete: ${destination}`);
    });

  yield* efficientCopy(testFile, "./test-file-copy.txt");

  // Cleanup
  yield* Effect.log(`\n[CLEANUP] Removing test files`);

  for (const name of [testFile, "test-file-copy.txt", ...testFiles.map((f) => `./${f.name}`)]) {
    try {
      yield* Effect.promise(() =>
        PromiseFS.unlink(name)
      );

      yield* Effect.log(`[REMOVED] ${name}`);
    } catch {
      // File doesn't exist, that's ok
    }
  }
});

Effect.runPromise(program);
```

---

**Rationale:**

Advanced file system operations require careful handling:

- **Atomic writes**: Prevent partial file corruption
- **File watching**: React to file changes
- **Recursive operations**: Handle directory trees
- **Bulk operations**: Efficient batch processing
- **Streaming**: Handle large files without loading all in memory
- **Permissions**: Handle access control safely

Pattern: Combine `FileSystem` API with `Ref` for state, `Stream` for data

---


Simple file operations cause problems at scale:

**Problem 1: Corrupted files**
- Write config file
- Server crashes mid-write
- File is partial/corrupted
- Application fails to start
- Production outage

**Problem 2: Large file handling**
- Load 10GB file into memory
- Server runs out of memory
- Everything crashes
- Now handling outages instead of serving

**Problem 3: Directory synchronization**
- Copy directory tree
- Process interrupted
- Some files copied, some not
- Directory in inconsistent state
- Hard to recover

**Problem 4: Inefficient updates**
- Update 10,000 files one by one
- Each file system call is slow
- Takes hours
- Meanwhile, users can't access data

**Problem 5: File locking**
- Process A reads file
- Process B writes file
- Process A gets partially written file
- Data corruption

Solutions:

**Atomic writes**:
- Write to temporary file
- Fsync (guarantee on disk)
- Atomic rename
- No corruption even on crash

**Streaming**:
- Process large files in chunks
- Keep memory constant
- Efficient for any file size

**Bulk operations**:
- Batch multiple operations
- Reduce system calls
- Faster overall completion

**File watching**:
- React to changes
- Avoid polling
- Real-time responsiveness

---

---