add docs for Effect.exit

content/docs/400-guides/150-error-management/300-unexpected-errors.mdx

@@ -96,22 +96,68 @@ Effect provides two functions that allow you to handle unexpected errors that ma
   explanatory purposes.
 </Warning>
 
+### exit
+
+The `Effect.exit` function transforms an `Effect<A, E, R>` into an effect that encapsulates both potential failure and success within an [Exit](../../other/data-types/exit) data type:
+
+```ts
+Effect<A, E, R> -> Effect<Exit<A, E>, never, R>
+```
+
+The resulting effect cannot fail because the potential failure is now represented within the `Exit`'s `Failure` type.
+The error type of the returned `Effect` is specified as `never`, confirming that the effect is structured to not fail.
+
+By yielding an `Exit`, we gain the ability to "pattern match" on this type to handle both failure and success cases within the generator function.
+
+```ts twoslash
+import { Effect, Cause, Console, Exit } from "effect"
+
+// Simulating a runtime error
+const task = Effect.dieMessage("Boom!")
+
+const program = Effect.gen(function* () {
+  const exit = yield* Effect.exit(task)
+  if (Exit.isFailure(exit)) {
+    const cause = exit.cause
+    if (Cause.isDieType(cause) && Cause.isRuntimeException(cause.defect)) {
+      yield* Console.log(
+        `RuntimeException defect caught: ${cause.defect.message}`
+      )
+    } else {
+      yield* Console.log("Unknown defect caught.")
+    }
+  }
+})
+
+// We get an Exit.Success because we caught all defects
+Effect.runPromiseExit(program).then(console.log)
+/*
+Output:
+RuntimeException defect caught: Boom!
+{
+  _id: "Exit",
+  _tag: "Success",
+  value: undefined
+}
+*/
+```
+
 ### catchAllDefect
 
 The `Effect.catchAllDefect` function allows you to recover from all defects using a provided function. Here's an example:
 
 ```ts twoslash
 import { Effect, Cause, Console } from "effect"
 
-const program = Effect.catchAllDefect(
-  Effect.dieMessage("Boom!"), // Simulating a runtime error
-  (defect) => {
-    if (Cause.isRuntimeException(defect)) {
-      return Console.log(`RuntimeException defect caught: ${defect.message}`)
-    }
-    return Console.log("Unknown defect caught.")
+// Simulating a runtime error
+const task = Effect.dieMessage("Boom!")
+
+const program = Effect.catchAllDefect(task, (defect) => {
+  if (Cause.isRuntimeException(defect)) {
+    return Console.log(`RuntimeException defect caught: ${defect.message}`)
   }
-)
+  return Console.log("Unknown defect caught.")
+})
 
 // We get an Exit.Success because we caught all defects
 Effect.runPromiseExit(program).then(console.log)
@@ -139,38 +185,29 @@ The `Effect.catchSomeDefect` function in Effect allows you to recover from speci
 ```ts twoslash
 import { Effect, Cause, Option, Console } from "effect"
 
-const program = Effect.catchSomeDefect(
-  Effect.dieMessage("Boom!"), // Simulating a runtime error
-  (defect) => {
-    if (Cause.isIllegalArgumentException(defect)) {
-      return Option.some(
-        Console.log(
-          `Caught an IllegalArgumentException defect: ${defect.message}`
-        )
+// Simulating a runtime error
+const task = Effect.dieMessage("Boom!")
+
+const program = Effect.catchSomeDefect(task, (defect) => {
+  if (Cause.isIllegalArgumentException(defect)) {
+    return Option.some(
+      Console.log(
+        `Caught an IllegalArgumentException defect: ${defect.message}`
       )
-    }
-    return Option.none()
+    )
   }
-)
+  return Option.none()
+})
 
 // Since we are only catching IllegalArgumentException
 // we will get an Exit.Failure because we simulated a runtime error.
 Effect.runPromiseExit(program).then(console.log)
 /*
 Output:
 {
-  _id: "Exit",
-  _tag: "Failure",
-  cause: {
-    _id: "Cause",
-    _tag: "Die",
-    defect: {
-      _tag: "RuntimeException",
-      message: "Boom!",
-      [Symbol(@effect/io/Cause/errors/RuntimeException)]: Symbol(@effect/io/Cause/errors/RuntimeException),
-      toString: [Function: toString]
-    }
-  }
+  _id: 'Exit',
+  _tag: 'Failure',
+  cause: { _id: 'Cause', _tag: 'Die', defect: { _tag: 'RuntimeException' } }
 }
 */
 ```