@effect/platform 0.64.0 → 0.65.0

package/README.md

@@ -2,23 +2,8 @@
 
 Welcome to the documentation for `@effect/platform`, a library designed for creating platform-independent abstractions (Node.js, Bun, browsers).
 
-With `@effect/platform`, you can incorporate abstract services like `Terminal` or `FileSystem` into your program. Later, during the assembly of the final application, you can provide specific layers for the target platform using the corresponding packages: `platform-node`, `platform-bun`, and `platform-browser`.
-
-This package empowers you to perform various operations, such as:
-
-| **Operation**  | **Description**                                                                                  |
-| -------------- | ------------------------------------------------------------------------------------------------ |
-| HTTP API       | Declarative HTTP API servers & clients                                                           |
-| HTTP Client    | Sending HTTP requests and receiving responses                                                    |
-| HTTP Server    | Creating HTTP servers to handle incoming requests                                                |
-| HTTP Router    | Routing HTTP requests to specific handlers                                                       |
-| Terminal       | Reading and writing from/to standard input/output                                                |
-| Command        | Creating and running a command with the specified process name and an optional list of arguments |
-| FileSystem     | Reading and writing from/to the file system                                                      |
-| KeyValueStore  | Storing and retrieving key-value pairs                                                           |
-| PlatformLogger | Creating a logger that writes to a specified file from another string logger                     |
-
-By utilizing `@effect/platform`, you can write code that remains platform-agnostic, ensuring compatibility across different environments.
+> [!WARNING]
+> This documentation focuses on **unstable modules**. For stable modules, refer to the [official website documentation](https://effect.website/docs/guides/platform/introduction).
 
 # HTTP API
 
@@ -579,42 +564,46 @@ Effect.gen(function* () {
 
 ## Overview
 
-An `HttpClient` is a function that takes a request and produces a certain value `A` in an effectful way (possibly resulting in an error `E` and depending on some requirement `R`).
-
-```ts
-type HttpClient<A, E, R> = (request: HttpClientRequest): Effect<A, E, R>
-```
+The `@effect/platform/HttpClient*` modules provide a way to send HTTP requests,
+handle responses, and abstract over the differences between platforms.
 
-Generally, you'll deal with a specialization called `Default` where `A`, `E`, and `R` are predefined:
+The `HttpClient` interface has a set of methods for sending requests:
 
-```ts
-type Default = (request: HttpClientRequest): Effect<HttpClientResponse, RequestError | ResponseError, Scope>
-```
+- `.execute` - takes a `HttpClientRequest` and returns a `HttpClientResponse`
+- `.{get, post, ...}` - convenience methods for creating a request and
+  executing it in one step
 
-The goal of `Default` is straightforward: transform a `HttpClientRequest` into a `HttpClientResponse`.
+To access the `HttpClient`, you can use the `HttpClient.HttpClient` `Context.Tag`.
+This will give you access to a `HttpClient.Service` instance, which is the default
+type of the `HttpClient` interface.
 
 ### A First Example: Retrieving JSON Data (GET)
 
 Here's a simple example demonstrating how to retrieve JSON data using `HttpClient` from `@effect/platform`.
 
 ```ts
-import {
-  HttpClient,
-  HttpClientRequest,
-  HttpClientResponse
-} from "@effect/platform"
+import { FetchHttpClient, HttpClient } from "@effect/platform"
 import { Effect } from "effect"
 
-const req = HttpClientRequest.get(
-  "https://jsonplaceholder.typicode.com/posts/1"
-)
+const program = Effect.gen(function* () {
+  // access the HttpClient
+  const client = yield* HttpClient.HttpClient
 
-// HttpClient.fetch is a Default
-const res = HttpClient.fetch(req)
+  const response = yield* client.get(
+    "https://jsonplaceholder.typicode.com/posts/1"
+  )
 
-const json = HttpClientResponse.json(res)
+  const json = yield* response.json
 
-Effect.runPromise(json).then(console.log)
+  console.log(json)
+}).pipe(
+  // ensure the request is aborted if the program is interrupted
+  Effect.scoped,
+  // provide the HttpClient
+  Effect.provide(FetchHttpClient.layer)
+)
+
+Effect.runPromise(program)
 /*
 Output:
 {
@@ -629,29 +618,15 @@ Output:
 */
 ```
 
-In this example:
-
-- `HttpClientRequest.get` creates a GET request to the specified URL.
-- `HttpClient.fetch` executes the request.
-- `HttpClientResponse.json` converts the response to JSON.
-- `Effect.runPromise` runs the effect and logs the result.
-
-### Built-in Defaults
+### Custom `HttpClient.Service`'s
 
-| Default              | Description                                                               |
-| -------------------- | ------------------------------------------------------------------------- |
-| `HttpClient.fetch`   | Execute the request using the global `fetch` function                     |
-| `HttpClient.fetchOk` | Same as `fetch` but ensures only `2xx` responses are treated as successes |
-
-### Custom Default
-
-You can create your own `Default` using the `HttpClient.makeDefault` constructor.
+You can create your own `HttpClient.Service` using the `HttpClient.makeService` constructor.
 
 ```ts
 import { HttpClient, HttpClientResponse } from "@effect/platform"
 import { Effect } from "effect"
 
-const myClient = HttpClient.makeDefault((req) =>
+const myClient = HttpClient.makeService((req) =>
   Effect.succeed(
     HttpClientResponse.fromWeb(
       req,
@@ -672,27 +647,25 @@ const myClient = HttpClient.makeDefault((req) =>
 ## Tapping
 
 ```ts
-import {
-  HttpClient,
-  HttpClientRequest,
-  HttpClientResponse
-} from "@effect/platform"
+import { FetchHttpClient, HttpClient } from "@effect/platform"
 import { Console, Effect } from "effect"
 
-const req = HttpClientRequest.get(
-  "https://jsonplaceholder.typicode.com/posts/1"
-)
+const program = Effect.gen(function* () {
+  const client = (yield* HttpClient.HttpClient).pipe(
+    // Log the request before fetching
+    HttpClient.tapRequest(Console.log)
+  )
 
-// Log the request before fetching
-const tapFetch: HttpClient.HttpClient.Default = HttpClient.fetch.pipe(
-  HttpClient.tapRequest(Console.log)
-)
+  const response = yield* client.get(
+    "https://jsonplaceholder.typicode.com/posts/1"
+  )
 
-const res = tapFetch(req)
+  const json = yield* response.json
 
-const json = HttpClientResponse.json(res)
+  console.log(json)
+}).pipe(Effect.scoped, Effect.provide(FetchHttpClient.layer))
 
-Effect.runPromise(json).then(console.log)
+Effect.runPromise(program)
 /*
 Output:
 {
@@ -847,20 +820,21 @@ Output:
 To convert a GET response to JSON:
 
 ```ts
-import {
-  HttpClient,
-  HttpClientRequest,
-  HttpClientResponse
-} from "@effect/platform"
+import { FetchHttpClient, HttpClient } from "@effect/platform"
 import { NodeRuntime } from "@effect/platform-node"
 import { Console, Effect } from "effect"
 
-const getPostAsJson = HttpClientRequest.get(
-  "https://jsonplaceholder.typicode.com/posts/1"
-).pipe(HttpClient.fetch, HttpClientResponse.json)
+const getPostAsJson = Effect.gen(function* () {
+  const client = yield* HttpClient.HttpClient
+  const response = yield* client.get(
+    "https://jsonplaceholder.typicode.com/posts/1"
+  )
+  return yield* response.json
+}).pipe(Effect.scoped, Effect.provide(FetchHttpClient.layer))
 
-NodeRuntime.runMain(
-  getPostAsJson.pipe(Effect.andThen((post) => Console.log(typeof post, post)))
+getPostAsJson.pipe(
+  Effect.andThen((post) => Console.log(typeof post, post)),
+  NodeRuntime.runMain
 )
 /*
 Output:
@@ -881,20 +855,21 @@ object {
 To convert a GET response to text:
 
 ```ts
-import {
-  HttpClient,
-  HttpClientRequest,
-  HttpClientResponse
-} from "@effect/platform"
+import { FetchHttpClient, HttpClient } from "@effect/platform"
 import { NodeRuntime } from "@effect/platform-node"
 import { Console, Effect } from "effect"
 
-const getPostAsText = HttpClientRequest.get(
-  "https://jsonplaceholder.typicode.com/posts/1"
-).pipe(HttpClient.fetch, HttpClientResponse.text)
+const getPostAsJson = Effect.gen(function* () {
+  const client = yield* HttpClient.HttpClient
+  const response = yield* client.get(
+    "https://jsonplaceholder.typicode.com/posts/1"
+  )
+  return yield* response.text
+}).pipe(Effect.scoped, Effect.provide(FetchHttpClient.layer))
 
-NodeRuntime.runMain(
-  getPostAsText.pipe(Effect.andThen((post) => Console.log(typeof post, post)))
+getPostAsJson.pipe(
+  Effect.andThen((post) => Console.log(typeof post, post)),
+  NodeRuntime.runMain
 )
 /*
 Output:
@@ -914,14 +889,14 @@ string {
 
 Here are some APIs you can use to convert the response:
 
-| API                                | Description                           |
-| ---------------------------------- | ------------------------------------- |
-| `HttpClientResponse.arrayBuffer`   | Convert to `ArrayBuffer`              |
-| `HttpClientResponse.formData`      | Convert to `FormData`                 |
-| `HttpClientResponse.json`          | Convert to JSON                       |
-| `HttpClientResponse.stream`        | Convert to a `Stream` of `Uint8Array` |
-| `HttpClientResponse.text`          | Convert to text                       |
-| `HttpClientResponse.urlParamsBody` | Convert to `Http.urlParams.UrlParams` |
+| API                      | Description                           |
+| ------------------------ | ------------------------------------- |
+| `response.arrayBuffer`   | Convert to `ArrayBuffer`              |
+| `response.formData`      | Convert to `FormData`                 |
+| `response.json`          | Convert to JSON                       |
+| `response.stream`        | Convert to a `Stream` of `Uint8Array` |
+| `response.text`          | Convert to text                       |
+| `response.urlParamsBody` | Convert to `UrlParams`                |
 
 ### Decoding Data with Schemas
 
@@ -929,8 +904,8 @@ A common use case when fetching data is to validate the received format. For thi
 
 ```ts
 import {
+  FetchHttpClient,
   HttpClient,
-  HttpClientRequest,
   HttpClientResponse
 } from "@effect/platform"
 import { NodeRuntime } from "@effect/platform-node"
@@ -946,17 +921,17 @@ const Post = Schema.Struct({
 const getPostAndValidate: Effect.Effect<{
     readonly id: number;
     readonly title: string;
-}, Http.error.HttpClientError | ParseError, never>
+}, HttpClientError | ParseError, never>
 */
-const getPostAndValidate = HttpClientRequest.get(
-  "https://jsonplaceholder.typicode.com/posts/1"
-).pipe(
-  HttpClient.fetch,
-  Effect.andThen(HttpClientResponse.schemaBodyJson(Post)),
-  Effect.scoped
-)
+const getPostAndValidate = Effect.gen(function* () {
+  const client = yield* HttpClient.HttpClient
+  const response = yield* client.get(
+    "https://jsonplaceholder.typicode.com/posts/1"
+  )
+  return yield* HttpClientResponse.schemaBodyJson(Post)(response)
+}).pipe(Effect.scoped, Effect.provide(FetchHttpClient.layer))
 
-NodeRuntime.runMain(getPostAndValidate.pipe(Effect.andThen(Console.log)))
+getPostAndValidate.pipe(Effect.andThen(Console.log), NodeRuntime.runMain)
 /*
 Output:
 {
@@ -979,19 +954,19 @@ You can use `HttpClient.filterStatusOk`, or `HttpClient.fetchOk` to ensure only
 In this example, we attempt to fetch a non-existent page and don't receive any error:
 
 ```ts
-import {
-  HttpClient,
-  HttpClientRequest,
-  HttpClientResponse
-} from "@effect/platform"
+import { FetchHttpClient, HttpClient } from "@effect/platform"
 import { NodeRuntime } from "@effect/platform-node"
 import { Console, Effect } from "effect"
 
-const getText = HttpClientRequest.get(
-  "https://jsonplaceholder.typicode.com/non-existing-page"
-).pipe(HttpClient.fetch, HttpClientResponse.text)
+const getText = Effect.gen(function* () {
+  const client = yield* HttpClient.HttpClient
+  const response = yield* client.get(
+    "https://jsonplaceholder.typicode.com/non-existing-page"
+  )
+  return yield* response.text
+}).pipe(Effect.scoped, Effect.provide(FetchHttpClient.layer))
 
-NodeRuntime.runMain(getText.pipe(Effect.andThen(Console.log)))
+getText.pipe(Effect.andThen(Console.log), NodeRuntime.runMain)
 /*
 Output:
 {}
@@ -1001,19 +976,19 @@ Output:
 However, if we use `HttpClient.filterStatusOk`, an error is logged:
 
 ```ts
-import {
-  HttpClient,
-  HttpClientRequest,
-  HttpClientResponse
-} from "@effect/platform"
+import { FetchHttpClient, HttpClient } from "@effect/platform"
 import { NodeRuntime } from "@effect/platform-node"
 import { Console, Effect } from "effect"
 
-const getText = HttpClientRequest.get(
-  "https://jsonplaceholder.typicode.com/non-existing-page"
-).pipe(HttpClient.filterStatusOk(HttpClient.fetch), HttpClientResponse.text)
+const getText = Effect.gen(function* () {
+  const client = (yield* HttpClient.HttpClient).pipe(HttpClient.filterStatusOk)
+  const response = yield* client.get(
+    "https://jsonplaceholder.typicode.com/non-existing-page"
+  )
+  return yield* response.text
+}).pipe(Effect.scoped, Effect.provide(FetchHttpClient.layer))
 
-NodeRuntime.runMain(getText.pipe(Effect.andThen(Console.log)))
+getText.pipe(Effect.andThen(Console.log), NodeRuntime.runMain)
 /*
 Output:
 timestamp=... level=ERROR fiber=#0 cause="ResponseError: StatusCode error (404 GET https://jsonplaceholder.typicode.com/non-existing-page): non 2xx status code
@@ -1021,60 +996,36 @@ timestamp=... level=ERROR fiber=#0 cause="ResponseError: StatusCode error (404 G
 */
 ```
 
-Note that you can use `HttpClient.fetchOk` as a shortcut for `HttpClient.filterStatusOk(HttpClient.fetch)`:
-
-```ts
-const getText = HttpClientRequest.get(
-  "https://jsonplaceholder.typicode.com/non-existing-page"
-).pipe(HttpClient.fetchOk, HttpClientResponse.text)
-```
-
-You can also create your own status-based filters. In fact, `HttpClient.filterStatusOk` is just a shortcut for the following filter:
-
-```ts
-const getText = HttpClientRequest.get(
-  "https://jsonplaceholder.typicode.com/non-existing-page"
-).pipe(
-  HttpClient.filterStatus(
-    HttpClient.fetch,
-    (status) => status >= 200 && status < 300
-  ),
-  HttpClientResponse.text
-)
-
-/*
-Output:
-timestamp=... level=ERROR fiber=#0 cause="ResponseError: StatusCode error (404 GET https://jsonplaceholder.typicode.com/non-existing-page): invalid status code
-    ... stack trace ...
-*/
-```
-
 ## POST
 
-To make a POST request, you can use the `HttpClientRequest.post` function provided by the `HttpClient` module. Here's an example of how to create and send a POST request:
+To make a POST request, you can use the `HttpClientRequest.post` function provided by the `HttpClientRequest` module. Here's an example of how to create and send a POST request:
 
 ```ts
 import {
+  FetchHttpClient,
   HttpClient,
-  HttpClientRequest,
-  HttpClientResponse
+  HttpClientRequest
 } from "@effect/platform"
 import { NodeRuntime } from "@effect/platform-node"
 import { Console, Effect } from "effect"
 
-const addPost = HttpClientRequest.post(
-  "https://jsonplaceholder.typicode.com/posts"
-).pipe(
-  HttpClientRequest.jsonBody({
-    title: "foo",
-    body: "bar",
-    userId: 1
-  }),
-  Effect.andThen(HttpClient.fetch),
-  HttpClientResponse.json
-)
+const addPost = Effect.gen(function* () {
+  const client = yield* HttpClient.HttpClient
+  return yield* HttpClientRequest.post(
+    "https://jsonplaceholder.typicode.com/posts"
+  ).pipe(
+    HttpClientRequest.bodyJson({
+      title: "foo",
+      body: "bar",
+      userId: 1
+    }),
+    Effect.flatMap(client.execute),
+    Effect.flatMap((res) => res.json),
+    Effect.scoped
+  )
+}).pipe(Effect.provide(FetchHttpClient.layer))
 
-NodeRuntime.runMain(addPost.pipe(Effect.andThen(Console.log)))
+addPost.pipe(Effect.andThen(Console.log), NodeRuntime.runMain)
 /*
 Output:
 { title: 'foo', body: 'bar', userId: 1, id: 101 }
@@ -1087,29 +1038,33 @@ In the following example, we send the data as text:
 
 ```ts
 import {
+  FetchHttpClient,
   HttpClient,
-  HttpClientRequest,
-  HttpClientResponse
+  HttpClientRequest
 } from "@effect/platform"
 import { NodeRuntime } from "@effect/platform-node"
 import { Console, Effect } from "effect"
 
-const addPost = HttpClientRequest.post(
-  "https://jsonplaceholder.typicode.com/posts"
-).pipe(
-  HttpClientRequest.textBody(
-    JSON.stringify({
-      title: "foo",
-      body: "bar",
-      userId: 1
-    }),
-    "application/json; charset=UTF-8"
-  ),
-  HttpClient.fetch,
-  HttpClientResponse.json
-)
+const addPost = Effect.gen(function* () {
+  const client = yield* HttpClient.HttpClient
+  return yield* HttpClientRequest.post(
+    "https://jsonplaceholder.typicode.com/posts"
+  ).pipe(
+    HttpClientRequest.bodyText(
+      JSON.stringify({
+        title: "foo",
+        body: "bar",
+        userId: 1
+      }),
+      "application/json; charset=UTF-8"
+    ),
+    client.execute,
+    Effect.flatMap((res) => res.json),
+    Effect.scoped
+  )
+}).pipe(Effect.provide(FetchHttpClient.layer))
 
-NodeRuntime.runMain(Effect.andThen(addPost, Console.log))
+addPost.pipe(Effect.andThen(Console.log), NodeRuntime.runMain)
 /*
 Output:
 { title: 'foo', body: 'bar', userId: 1, id: 101 }
@@ -1122,6 +1077,7 @@ A common use case when fetching data is to validate the received format. For thi
 
 ```ts
 import {
+  FetchHttpClient,
   HttpClient,
   HttpClientRequest,
   HttpClientResponse
@@ -1135,20 +1091,26 @@ const Post = Schema.Struct({
   title: Schema.String
 })
 
-const addPost = HttpClientRequest.post(
-  "https://jsonplaceholder.typicode.com/posts"
-).pipe(
-  HttpClientRequest.jsonBody({
-    title: "foo",
-    body: "bar",
-    userId: 1
-  }),
-  Effect.andThen(HttpClient.fetch),
-  Effect.andThen(HttpClientResponse.schemaBodyJson(Post)),
-  Effect.scoped
-)
+const addPost = Effect.gen(function* () {
+  const client = yield* HttpClient.HttpClient
+  return yield* HttpClientRequest.post(
+    "https://jsonplaceholder.typicode.com/posts"
+  ).pipe(
+    HttpClientRequest.bodyText(
+      JSON.stringify({
+        title: "foo",
+        body: "bar",
+        userId: 1
+      }),
+      "application/json; charset=UTF-8"
+    ),
+    client.execute,
+    Effect.flatMap(HttpClientResponse.schemaBodyJson(Post)),
+    Effect.scoped
+  )
+}).pipe(Effect.provide(FetchHttpClient.layer))
 
-NodeRuntime.runMain(addPost.pipe(Effect.andThen(Console.log)))
+addPost.pipe(Effect.andThen(Console.log), NodeRuntime.runMain)
 /*
 Output:
 { id: 101, title: 'foo' }
@@ -1162,30 +1124,31 @@ Output:
 To test HTTP requests, you can inject a mock fetch implementation.
 
 ```ts
-import {
-  HttpClient,
-  HttpClientRequest,
-  HttpClientResponse
-} from "@effect/platform"
+import { FetchHttpClient, HttpClient } from "@effect/platform"
 import { Effect, Layer } from "effect"
 import * as assert from "node:assert"
 
 // Mock fetch implementation
-const FetchTest = Layer.succeed(HttpClient.Fetch, () =>
+const FetchTest = Layer.succeed(FetchHttpClient.Fetch, () =>
   Promise.resolve(new Response("not found", { status: 404 }))
 )
 
-// Program to test
-const program = HttpClientRequest.get("https://www.google.com/").pipe(
-  HttpClient.fetch,
-  HttpClientResponse.text
-)
+const TestLayer = FetchHttpClient.layer.pipe(Layer.provide(FetchTest))
+
+const program = Effect.gen(function* () {
+  const client = yield* HttpClient.HttpClient
+
+  return yield* client.get("https://www.google.com/").pipe(
+    Effect.flatMap((res) => res.text),
+    Effect.scoped
+  )
+})
 
 // Test
 Effect.gen(function* () {
   const response = yield* program
   assert.equal(response, "not found")
-}).pipe(Effect.provide(FetchTest), Effect.runPromise)
+}).pipe(Effect.provide(TestLayer), Effect.runPromise)
 ```
 
 # HTTP Server
@@ -2345,402 +2308,3 @@ const handler = HttpApp.toWebHandler(router)
 const response = await handler(new Request("http://localhost:3000/foo"))
 console.log(await response.text()) // Output: content 2
 ```
-
-# Terminal
-
-The `@effect/platform/Terminal` module exports a single `Terminal` tag, which serves as the entry point to reading from and writing to standard input and standard output.
-
-## Writing to standard output
-
-```ts
-import { Terminal } from "@effect/platform"
-import { NodeRuntime, NodeTerminal } from "@effect/platform-node"
-import { Effect } from "effect"
-
-// const displayMessage: Effect.Effect<void, PlatformError, Terminal.Terminal>
-const displayMessage = Effect.gen(function* (_) {
-  const terminal = yield* _(Terminal.Terminal)
-  yield* _(terminal.display("a message\n"))
-})
-
-NodeRuntime.runMain(displayMessage.pipe(Effect.provide(NodeTerminal.layer)))
-// Output: "a message"
-```
-
-## Reading from standard input
-
-```ts
-import { Terminal } from "@effect/platform"
-import { NodeRuntime, NodeTerminal } from "@effect/platform-node"
-import { Console, Effect } from "effect"
-
-// const readLine: Effect.Effect<void, Terminal.QuitException, Terminal.Terminal>
-const readLine = Effect.gen(function* (_) {
-  const terminal = yield* _(Terminal.Terminal)
-  const input = yield* _(terminal.readLine)
-  yield* _(Console.log(`input: ${input}`))
-})
-
-NodeRuntime.runMain(readLine.pipe(Effect.provide(NodeTerminal.layer)))
-// Input: "hello"
-// Output: "input: hello"
-```
-
-These simple examples illustrate how to utilize the `Terminal` module for handling standard input and output in your programs. Let's use this knowledge to build a number guessing game:
-
-```ts
-import { Terminal } from "@effect/platform"
-import type { PlatformError } from "@effect/platform/Error"
-import { Effect, Option, Random } from "effect"
-
-export const secret = Random.nextIntBetween(1, 100)
-
-const parseGuess = (input: string) => {
-  const n = parseInt(input, 10)
-  return isNaN(n) || n < 1 || n > 100 ? Option.none() : Option.some(n)
-}
-
-const display = (message: string) =>
-  Effect.gen(function* (_) {
-    const terminal = yield* _(Terminal.Terminal)
-    yield* _(terminal.display(`${message}\n`))
-  })
-
-const prompt = Effect.gen(function* (_) {
-  const terminal = yield* _(Terminal.Terminal)
-  yield* _(terminal.display("Enter a guess: "))
-  return yield* _(terminal.readLine)
-})
-
-const answer: Effect.Effect<
-  number,
-  Terminal.QuitException | PlatformError,
-  Terminal.Terminal
-> = Effect.gen(function* (_) {
-  const input = yield* _(prompt)
-  const guess = parseGuess(input)
-  if (Option.isNone(guess)) {
-    yield* _(display("You must enter an integer from 1 to 100"))
-    return yield* _(answer)
-  }
-  return guess.value
-})
-
-const check = <A, E, R>(
-  secret: number,
-  guess: number,
-  ok: Effect.Effect<A, E, R>,
-  ko: Effect.Effect<A, E, R>
-): Effect.Effect<A, E | PlatformError, R | Terminal.Terminal> =>
-  Effect.gen(function* (_) {
-    if (guess > secret) {
-      yield* _(display("Too high"))
-      return yield* _(ko)
-    } else if (guess < secret) {
-      yield* _(display("Too low"))
-      return yield* _(ko)
-    } else {
-      return yield* _(ok)
-    }
-  })
-
-const end = display("You guessed it!")
-
-const loop = (
-  secret: number
-): Effect.Effect<
-  void,
-  Terminal.QuitException | PlatformError,
-  Terminal.Terminal
-> =>
-  Effect.gen(function* (_) {
-    const guess = yield* _(answer)
-    return yield* _(
-      check(
-        secret,
-        guess,
-        end,
-        Effect.suspend(() => loop(secret))
-      )
-    )
-  })
-
-export const game = Effect.gen(function* (_) {
-  yield* _(
-    display(
-      "We have selected a random number between 1 and 100. See if you can guess it in 10 turns or fewer. We'll tell you if your guess was too high or too low."
-    )
-  )
-  yield* _(loop(yield* _(secret)))
-})
-```
-
-Let's run the game in Node.js:
-
-```ts
-import { NodeRuntime, NodeTerminal } from "@effect/platform-node"
-import * as Effect from "effect/Effect"
-import { game } from "./game.js"
-
-NodeRuntime.runMain(game.pipe(Effect.provide(NodeTerminal.layer)))
-```
-
-Let's run the game in Bun:
-
-```ts
-import { BunRuntime, BunTerminal } from "@effect/platform-bun"
-import * as Effect from "effect/Effect"
-import { game } from "./game.js"
-
-BunRuntime.runMain(game.pipe(Effect.provide(BunTerminal.layer)))
-```
-
-# Command
-
-As an example of using the `@effect/platform/Command` module, let's see how to run the TypeScript compiler `tsc`:
-
-```ts
-import { Command, CommandExecutor } from "@effect/platform"
-import {
-  NodeCommandExecutor,
-  NodeFileSystem,
-  NodeRuntime
-} from "@effect/platform-node"
-import { Effect } from "effect"
-
-// const program: Effect.Effect<string, PlatformError, CommandExecutor.CommandExecutor>
-const program = Effect.gen(function* (_) {
-  const executor = yield* _(CommandExecutor.CommandExecutor)
-
-  // Creating a command to run the TypeScript compiler
-  const command = Command.make("tsc", "--noEmit")
-  console.log("Running tsc...")
-
-  // Executing the command and capturing the output
-  const output = yield* _(executor.string(command))
-  console.log(output)
-  return output
-})
-
-// Running the program with the necessary runtime and executor layers
-NodeRuntime.runMain(
-  program.pipe(
-    Effect.provide(NodeCommandExecutor.layer),
-    Effect.provide(NodeFileSystem.layer)
-  )
-)
-```
-
-## Obtaining Information About the Running Process
-
-Here, we'll explore how to retrieve information about a running process.
-
-```ts
-import { Command, CommandExecutor } from "@effect/platform"
-import {
-  NodeCommandExecutor,
-  NodeFileSystem,
-  NodeRuntime
-} from "@effect/platform-node"
-import { Effect, Stream, String } from "effect"
-
-const runString = <E, R>(
-  stream: Stream.Stream<Uint8Array, E, R>
-): Effect.Effect<string, E, R> =>
-  stream.pipe(Stream.decodeText(), Stream.runFold(String.empty, String.concat))
-
-const program = Effect.gen(function* (_) {
-  const executor = yield* _(CommandExecutor.CommandExecutor)
-
-  const command = Command.make("ls")
-
-  const [exitCode, stdout, stderr] = yield* _(
-    // Start running the command and return a handle to the running process.
-    executor.start(command),
-    Effect.flatMap((process) =>
-      Effect.all(
-        [
-          // Waits for the process to exit and returns the ExitCode of the command that was run.
-          process.exitCode,
-          // The standard output stream of the process.
-          runString(process.stdout),
-          // The standard error stream of the process.
-          runString(process.stderr)
-        ],
-        { concurrency: 3 }
-      )
-    )
-  )
-  console.log({ exitCode, stdout, stderr })
-})
-
-NodeRuntime.runMain(
-  Effect.scoped(program).pipe(
-    Effect.provide(NodeCommandExecutor.layer),
-    Effect.provide(NodeFileSystem.layer)
-  )
-)
-```
-
-## Running a Platform Command with stdout Streamed to process.stdout
-
-To run a command (for example `cat`) and stream its `stdout` to `process.stdout` follow these steps:
-
-```ts
-import { Command } from "@effect/platform"
-import { NodeContext, NodeRuntime } from "@effect/platform-node"
-import { Effect } from "effect"
-
-// Create a command to run `cat` on a file and inherit stdout
-const program = Command.make("cat", "./some-file.txt").pipe(
-  Command.stdout("inherit"),
-  Command.exitCode
-)
-
-// Run the command using NodeRuntime with the NodeContext layer
-NodeRuntime.runMain(program.pipe(Effect.provide(NodeContext.layer)))
-```
-
-# FileSystem
-
-The `@effect/platform/FileSystem` module provides a single `FileSystem` tag, which acts as the gateway for interacting with the filesystem.
-
-Here's a list of operations that can be performed using the `FileSystem` tag:
-
-| **Name**                    | **Arguments**                                                    | **Return**                                     | **Description**                                                                                                                                                        |
-| --------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **access**                  | `path: string`, `options?: AccessFileOptions`                    | `Effect<void, PlatformError>`                  | Check if a file can be accessed. You can optionally specify the level of access to check for.                                                                          |
-| **copy**                    | `fromPath: string`, `toPath: string`, `options?: CopyOptions`    | `Effect<void, PlatformError>`                  | Copy a file or directory from `fromPath` to `toPath`. Equivalent to `cp -r`.                                                                                           |
-| **copyFile**                | `fromPath: string`, `toPath: string`                             | `Effect<void, PlatformError>`                  | Copy a file from `fromPath` to `toPath`.                                                                                                                               |
-| **chmod**                   | `path: string`, `mode: number`                                   | `Effect<void, PlatformError>`                  | Change the permissions of a file.                                                                                                                                      |
-| **chown**                   | `path: string`, `uid: number`, `gid: number`                     | `Effect<void, PlatformError>`                  | Change the owner and group of a file.                                                                                                                                  |
-| **exists**                  | `path: string`                                                   | `Effect<boolean, PlatformError>`               | Check if a path exists.                                                                                                                                                |
-| **link**                    | `fromPath: string`, `toPath: string`                             | `Effect<void, PlatformError>`                  | Create a hard link from `fromPath` to `toPath`.                                                                                                                        |
-| **makeDirectory**           | `path: string`, `options?: MakeDirectoryOptions`                 | `Effect<void, PlatformError>`                  | Create a directory at `path`. You can optionally specify the mode and whether to recursively create nested directories.                                                |
-| **makeTempDirectory**       | `options?: MakeTempDirectoryOptions`                             | `Effect<string, PlatformError>`                | Create a temporary directory. By default, the directory will be created inside the system's default temporary directory.                                               |
-| **makeTempDirectoryScoped** | `options?: MakeTempDirectoryOptions`                             | `Effect<string, PlatformError, Scope>`         | Create a temporary directory inside a scope. Functionally equivalent to `makeTempDirectory`, but the directory will be automatically deleted when the scope is closed. |
-| **makeTempFile**            | `options?: MakeTempFileOptions`                                  | `Effect<string, PlatformError>`                | Create a temporary file. The directory creation is functionally equivalent to `makeTempDirectory`. The file name will be a randomly generated string.                  |
-| **makeTempFileScoped**      | `options?: MakeTempFileOptions`                                  | `Effect<string, PlatformError, Scope>`         | Create a temporary file inside a scope. Functionally equivalent to `makeTempFile`, but the file will be automatically deleted when the scope is closed.                |
-| **open**                    | `path: string`, `options?: OpenFileOptions`                      | `Effect<File, PlatformError, Scope>`           | Open a file at `path` with the specified `options`. The file handle will be automatically closed when the scope is closed.                                             |
-| **readDirectory**           | `path: string`, `options?: ReadDirectoryOptions`                 | `Effect<Array<string>, PlatformError>`         | List the contents of a directory. You can recursively list the contents of nested directories by setting the `recursive` option.                                       |
-| **readFile**                | `path: string`                                                   | `Effect<Uint8Array, PlatformError>`            | Read the contents of a file.                                                                                                                                           |
-| **readFileString**          | `path: string`, `encoding?: string`                              | `Effect<string, PlatformError>`                | Read the contents of a file as a string.                                                                                                                               |
-| **readLink**                | `path: string`                                                   | `Effect<string, PlatformError>`                | Read the destination of a symbolic link.                                                                                                                               |
-| **realPath**                | `path: string`                                                   | `Effect<string, PlatformError>`                | Resolve a path to its canonicalized absolute pathname.                                                                                                                 |
-| **remove**                  | `path: string`, `options?: RemoveOptions`                        | `Effect<void, PlatformError>`                  | Remove a file or directory. By setting the `recursive` option to `true`, you can recursively remove nested directories.                                                |
-| **rename**                  | `oldPath: string`, `newPath: string`                             | `Effect<void, PlatformError>`                  | Rename a file or directory.                                                                                                                                            |
-| **sink**                    | `path: string`, `options?: SinkOptions`                          | `Sink<void, Uint8Array, never, PlatformError>` | Create a writable `Sink` for the specified `path`.                                                                                                                     |
-| **stat**                    | `path: string`                                                   | `Effect<File.Info, PlatformError>`             | Get information about a file at `path`.                                                                                                                                |
-| **stream**                  | `path: string`, `options?: StreamOptions`                        | `Stream<Uint8Array, PlatformError>`            | Create a readable `Stream` for the specified `path`.                                                                                                                   |
-| **symlink**                 | `fromPath: string`, `toPath: string`                             | `Effect<void, PlatformError>`                  | Create a symbolic link from `fromPath` to `toPath`.                                                                                                                    |
-| **truncate**                | `path: string`, `length?: SizeInput`                             | `Effect<void, PlatformError>`                  | Truncate a file to a specified length. If the `length` is not specified, the file will be truncated to length `0`.                                                     |
-| **utimes**                  | `path: string`, `atime: Date \| number`, `mtime: Date \| number` | `Effect<void, PlatformError>`                  | Change the file system timestamps of the file at `path`.                                                                                                               |
-| **watch**                   | `path: string`                                                   | `Stream<WatchEvent, PlatformError>`            | Watch a directory or file for changes.                                                                                                                                 |
-
-Let's explore a simple example using `readFileString`:
-
-```ts
-import { FileSystem } from "@effect/platform"
-import { NodeFileSystem, NodeRuntime } from "@effect/platform-node"
-import { Effect } from "effect"
-
-// const readFileString: Effect.Effect<void, PlatformError, FileSystem.FileSystem>
-const readFileString = Effect.gen(function* (_) {
-  const fs = yield* _(FileSystem.FileSystem)
-
-  // Reading the content of the same file where this code is written
-  const content = yield* _(fs.readFileString("./index.ts", "utf8"))
-  console.log(content)
-})
-
-NodeRuntime.runMain(readFileString.pipe(Effect.provide(NodeFileSystem.layer)))
-```
-
-# KeyValueStore
-
-## Overview
-
-The `KeyValueStore` module provides a robust and effectful interface for managing key-value pairs. It supports asynchronous operations, ensuring data integrity and consistency, and includes built-in implementations for in-memory, file system-based, and schema-validated stores.
-
-## Basic Usage
-
-The `KeyValueStore` interface includes the following operations:
-
-- **get**: Retrieve a value by key.
-- **set**: Store a key-value pair.
-- **remove**: Delete a key-value pair.
-- **clear**: Remove all key-value pairs.
-- **size**: Get the number of stored pairs.
-- **modify**: Atomically modify a value.
-- **has**: Check if a key exists.
-- **isEmpty**: Check if the store is empty.
-
-**Example**
-
-```ts
-import { KeyValueStore, layerMemory } from "@effect/platform/KeyValueStore"
-import { Effect } from "effect"
-
-const program = Effect.gen(function* () {
-  const store = yield* KeyValueStore
-  console.log(yield* store.size) // Outputs: 0
-
-  yield* store.set("key", "value")
-  console.log(yield* store.size) // Outputs: 1
-
-  const value = yield* store.get("key")
-  console.log(value) // Outputs: { _id: 'Option', _tag: 'Some', value: 'value' }
-
-  yield* store.remove("key")
-  console.log(yield* store.size) // Outputs: 0
-})
-
-Effect.runPromise(program.pipe(Effect.provide(layerMemory)))
-```
-
-## Built-in Implementations
-
-The module provides several built-in implementations to suit different needs:
-
-- **In-Memory Store**: `layerMemory` provides a simple, in-memory key-value store, ideal for lightweight or testing scenarios.
-- **File System Store**: `layerFileSystem` offers a file-based store for persistent storage needs.
-- **Schema Store**: `layerSchema` enables schema-based validation for stored values, ensuring data integrity and type safety.
-
-## Schema Store
-
-The `SchemaStore` implementation allows you to validate and parse values according to a defined schema. This ensures that all data stored in the key-value store adheres to the specified structure, enhancing data integrity and type safety.
-
-**Example**
-
-```ts
-import { KeyValueStore, layerMemory } from "@effect/platform/KeyValueStore"
-import { Schema } from "@effect/schema"
-import { Effect } from "effect"
-
-// Define a schema for the values
-const Person = Schema.Struct({
-  name: Schema.String,
-  age: Schema.Number
-})
-
-const program = Effect.gen(function* () {
-  const store = (yield* KeyValueStore).forSchema(Person)
-
-  // Create a value that adheres to the schema
-  const value = { name: "Alice", age: 30 }
-  yield* store.set("user1", value)
-  console.log(yield* store.size) // Outputs: 1
-
-  // Retrieve and validate the value
-  const retrievedValue = yield* store.get("user1")
-  console.log(retrievedValue) // Outputs: { _id: 'Option', _tag: 'Some', value: { name: 'Alice', age: 30 } }
-})
-
-Effect.runPromise(program.pipe(Effect.provide(layerMemory)))
-```
-
-In this example:
-
-- **Person**: Defines the structure for the values stored in the key-value store.
-- **store.set**: Stores a value adhering to `Person`.
-- **store.get**: Retrieves and validates the stored value against `Person`.