effect-patterns-platform

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.

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.

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();

   stats = * .().(
    .(
      .({
        : stat.,
        : stat.(),
        : stat.,
      })
    )
  );

  .();
  .();
  .();

  
  .();

  * .();

  * .(
    .({ :  }, 
      .(
        ,
        
      )
    )
  );

  * .();

  
  .();

   entries = * .();

  entries.( {
    .();
  });

  
  .();

   appendContent = ;

  * .(, appendContent);

   finalContent = * .();

  .();

  
  .();

  * .(
    .({ :  }, 
      .()
    )
  );

  * .();
  * .();

  * .();
});

.(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.

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();

  
  .();

   stored = * store.();

   (stored. === ) {
     retrievedSession = .(stored.)  ;

    .();
    .();
    .(
      
    );
  }

  
  .();

   hasSession = * store.();
   hasOther = * store.();

  .();
  .();

  
  .();

   apiResponses = [
    { : , : [{ : , :  }] },
    { : , : [{ : , :  }] },
    { : , : [] },
  ];

  * .(
    apiResponses.(
      store.(
        ,
        .(item.)
      )
    )
  );

  * .();

  
  .();

   ( item  apiResponses) {
     cached = * store.();

     (cached. === ) {
       data = .(cached.);

      .(
        
      );
    }
  }

  
  .();

  * store.();

   removed = * store.();

  .();

  
  .();

   allKeys = * store..(
    .( entries.)
  );

  .();
});

.(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.

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();

   fileCheckCmd = * .(, [
    ,
    ,
  ]).(
    .,
    .
  );

   (fileCheckCmd. === ) {
    .();
  }  {
    .();
  }

  
  .();

   findResult = * .(, [
    ,
    ,
    ,
    ,
    ,
  ]).(
    .
  );

   tsFiles = .(findResult, ); 

  .(tsFiles,  {
    .();
  });

   (.(findResult) > ) {
    .();
  }

  
  .();

   failResult = * .().(
    .,
    .(
      .(-) 
    )
  );

  .();
});

.(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.

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.(* () {
  .();

   platformInfo = * ();

  
  .();

   segments = [, , ];

   joinedPath = .(...segments);

  * .();
  * .();

  
  .();

   relativePath = ;

   absolutePath = .(relativePath);

  * .();
  * .();

  
  .();

   filePath = ;

   parsed = .(filePath);

  * .();
  * .();
  * .();
  * .();
  * .();
  * .();

  
  .();

   expandPath = (: ):  {
     result = pathStr;

    
    result = result.(, .());
    result = result.(, .());
    result = result.(, process.. || );
    result = result.(, process.());

    
    result = result.(, .());
    result = result.(, process.. || );
    result = result.(, .());

     result;
  };

   envPaths = [
    ,
    ,
    ,
    ,
  ];

   ( envPath  envPaths) {
     expanded = (envPath);

    * .(
      
    );
  }

  
  .();

   messyPaths = [
    ,
    ,
    ,
    ,
  ];

   ( messy  messyPaths) {
     normalized = .(messy);

    * .(
      
    );
    * .(
      
    );
  }

  
  .();

   baseDir = ;

   safeJoin = (: , : ): <> => {
    
     (.(userPath)) {
       { : , :  };
    }

    
     (userPath.()) {
       { : , :  };
    }

    
     fullPath = .(base, userPath);

     (!fullPath.(base)) {
       { : , :  };
    }

     { : , : fullPath };
  };

   <T> {
    : ;
    ?: ;
    ?: T;
  }

   testPaths = [
    ,
    ,
    ,
    ,
  ];

   ( test  testPaths) {
     result = (baseDir, test);

     (result.) {
      * .();
    }  {
      * .();
    }
  }

  
  .();

   fromDir = ;
   toPath = ;

   relativePath2 = .(fromDir, toPath);

  * .();
  * .();
  * .();

  
  .();

  
   fileName = ;
   ext = .(fileName);
   baseName = .(fileName);
   dirName = .();

  * .();
  * .();
  * .();
  * .();

  
  .();

   segmentPath = ;

   segments2 = segmentPath.(.).( s);

  * .();
  * .();
});

.(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.

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.(
          .(tempPath, content, )
        );

        * .();

        
        * .(
          .(tempPath, content, )
        );

        * .();

        
        * .(
          .(tempPath, filePath)
        );

        * .();
      }  (error) {
        
         {
          * .( .(tempPath));
        }  {
          
        }

        * .(error);
      }
    });

  
   testFile = ;

  * (testFile, );

  
   content = * .(
    .(testFile, )
  );

  * .();

  
  .();

    = () =>
    .(* () {
       byteCount = ;
       lineCount = ;

       readStream = .(filePath, {
        : ,
        :  * , 
      });

      * .();

        = () =>
        .(* () {
          byteCount += line.;
          lineCount++;

           (lineCount <=  || lineCount %  === ) {
            * .(
              
            );
          }
        });

      
      * ();
      * ();

      * .(
        
      );
    });

  * (testFile);

  
  .();

   recursiveList = (
    : ,
    :  = 
  ): .<<{ : ; :  |  }>> =>
    .(* () {
       : <{ : ; :  |  }> = [];

        = () =>
        .(* () {
           (depth > maxDepth) {
            ;
          }

           entries = * .(
            .(currentDir, { :  })
          );

           ( entry  entries) {
             fullPath = .(currentDir, entry.);

             (entry.()) {
              results.({ : fullPath, :  });

              * (fullPath, depth + );
            }  {
              results.({ : fullPath, :  });
            }
          }
        });

      * (dir, );

       results;
    });

  
   entries = * (, );

  * .(
    
  );

   ( entry  entries.(, )) {
      = entry. ===  ?  : ;

    * .();
  }

  
  .();

    = () =>
    .(* () {
      * .();

       ( file  files) {
        * (, file.);
      }

      * .();
    });

   testFiles = [
    { : , :  },
    { : , :  },
    { : , :  },
  ];

  * (testFiles);

  
  .();

    = () =>
    .(* () {
      * .();

       changeCount = ;

      
        = () =>
        .(* () {
           ( i = ; i < ; i++) {
            * .();

            
             stat = * .(
              .(filePath)
            );

            
             (i === ) {
              changeCount++;

              * .(
                
              );
            }
          }
        });

      * ();

      * .();
    });

  * (testFile);

  
  .();

    = () =>
    .(* () {
       lockPath = ;

      
      * (lockPath, );

      * .();

       {
        
        * .();

        * .();
      }  {
        
        * .(
          .(lockPath)
        );

        * .();
      }
    });

  * (testFile);

  
  .();

   efficientCopy = (
    : ,
    : 
  ): .<> =>
    .(* () {
       stat = * .(
        .(source)
      );

      * .(
        
      );

       content = * .(
        .(source)
      );

      * (destination, content.());

      * .();
    });

  * (testFile, );

  
  * .();

   ( name  [testFile, , ...testFiles.( )]) {
     {
      * .(
        .(name)
      );

      * .();
    }  {
      
    }
  }
});

.(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

---

---