effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Runtime.ts

@@ -1,28 +1,58 @@
 /**
- * This module provides utilities for running Effect programs and managing their execution lifecycle.
- *
- * The Runtime module contains functions for creating main program runners that handle process
- * teardown, error reporting, and exit code management. These utilities are particularly useful
- * for creating CLI applications and server processes that need to manage their lifecycle properly.
- *
- * **Example** (Creating a main runner)
+ * Runtime helpers for turning an `Effect` program into a host application's
+ * main entry point.
+ *
+ * This module is the low-level layer used by platform adapters to run a main
+ * effect, observe its fiber, report unhandled failures, and translate the
+ * resulting `Exit` into an application or process exit code. Application code
+ * usually calls the platform-provided runner; runtime integrations use
+ * {@link makeRunMain} directly.
+ *
+ * **Mental model**
+ *
+ * - {@link makeRunMain} forks the supplied `Effect` and gives the host adapter
+ *   the running fiber plus a teardown callback
+ * - The host adapter installs platform-specific hooks such as signal handlers,
+ *   fiber observers, process exits, worker termination, or test harness
+ *   callbacks
+ * - {@link defaultTeardown} maps successful exits to `0`, interruption-only
+ *   failures to `130`, failures with {@link errorExitCode} to that code, and
+ *   other failures to `1`
+ * - {@link errorReported} controls automatic failure logging; set it to
+ *   `false` on errors that have already been reported
+ *
+ * **Common tasks**
+ *
+ * - Build a platform runner: {@link makeRunMain}
+ * - Reuse the standard exit-code rules: {@link defaultTeardown}
+ * - Customize failure exit codes: {@link errorExitCode},
+ *   {@link getErrorExitCode}
+ * - Control automatic failure logging: {@link errorReported},
+ *   {@link getErrorReported}
+ *
+ * **Gotchas**
+ *
+ * - `makeRunMain` starts the main fiber, but the adapter callback is
+ *   responsible for observing that fiber and eventually invoking teardown.
+ * - `disableErrorReporting` only disables automatic failure logging. It does
+ *   not change the `Exit`, interruption behavior, or teardown exit-code rules.
+ * - Error markers are read from `Cause.squash(cause)`, so causes with multiple
+ *   failures use the squashed failure value to determine logging and exit code.
+ *
+ * **Example** (Creating a minimal runner)
  *
  * ```ts
- * import { Effect, Fiber, Runtime } from "effect"
- *
- * // Create a main runner for Node.js
- * const runMain = Runtime.makeRunMain((options) => {
- *   process.on("SIGINT", () => Effect.runFork(Fiber.interrupt(options.fiber)))
- *   process.on("SIGTERM", () => Effect.runFork(Fiber.interrupt(options.fiber)))
+ * import { Effect, Runtime } from "effect"
  *
- *   options.fiber.addObserver((exit) => {
- *     options.teardown(exit, (code) => process.exit(code))
+ * const runMain = Runtime.makeRunMain(({ fiber, teardown }) => {
+ *   fiber.addObserver((exit) => {
+ *     teardown(exit, (code) => {
+ *       console.log(`finished with exit code ${code}`)
+ *     })
  *   })
  * })
  *
- * // Use the runner
- * const program = Effect.log("Hello, World!")
- * runMain(program)
+ * runMain(Effect.log("booted"))
  * ```
  *
  * @since 4.0.0
@@ -36,9 +66,16 @@ import type * as Fiber from "./Fiber.ts"
 /**
  * Represents a teardown function that handles program completion and determines the exit code.
  *
+ * **When to use**
+ *
+ * Use when integrating {@link makeRunMain} with a host platform that needs to
+ * translate an Effect `Exit` into a process, worker, or application exit code.
+ *
  * **Details**
  *
- * A teardown function is called when an Effect program completes, either successfully or with a failure. It determines the appropriate exit code and can perform cleanup before invoking the supplied `onExit` callback.
+ * A teardown function is called when an Effect program completes, either
+ * successfully or with a failure. It determines the appropriate exit code and
+ * can perform cleanup before invoking the supplied `onExit` callback.
  *
  * **Example** (Customizing teardown behavior)
  *
@@ -79,9 +116,25 @@ export interface Teardown {
 /**
  * The default teardown function that determines exit codes from an Effect exit.
  *
+ * **When to use**
+ *
+ * Use as the standard teardown for main programs when you want conventional
+ * process exit codes and support for {@link errorExitCode}.
+ *
  * **Details**
  *
- * This teardown function follows standard Unix conventions: exit code `0` for successful completion, exit code `1` for failures unless the squashed error has a `Runtime.errorExitCode` marker, and exit code `130` for interruption-only failures.
+ * This teardown follows these exit-code rules:
+ *
+ * - `0` for successful completion.
+ * - `130` for interruption-only failures.
+ * - The squashed error's {@link errorExitCode} value for other failures when
+ *   present.
+ * - `1` for other failures.
+ *
+ * **Gotchas**
+ *
+ * The `130` code is used only when the Cause contains interruptions and no
+ * other failure reasons. Mixed causes use the squashed error path instead.
  *
  * **Example** (Using default teardown)
  *
@@ -104,7 +157,9 @@ export interface Teardown {
  * // Output: Exit code: 130
  * ```
  *
- * @category Teardown
+ * @see {@link errorExitCode} for customizing failure exit codes
+ *
+ * @category running
  * @since 4.0.0
  */
 export const defaultTeardown: Teardown = <E, A>(
@@ -119,10 +174,27 @@ export const defaultTeardown: Teardown = <E, A>(
 /**
  * Creates a platform-specific main program runner that handles Effect execution lifecycle.
  *
+ * **When to use**
+ *
+ * Use when building a runtime adapter for a host platform. Most applications
+ * should use a platform-provided runner, such as `NodeRuntime.runMain`, rather
+ * than constructing one directly.
+ *
  * **Details**
  *
  * The runner executes Effect programs as main entry points. The provided function receives a forked fiber and a teardown callback so it can install platform-specific signal handling, fiber observers, and final exit behavior.
  *
+ * `disableErrorReporting` disables the automatic log emitted for unreported
+ * non-interruption failures. It does not change exit-code calculation or the
+ * custom teardown callback.
+ *
+ * **Gotchas**
+ *
+ * The setup function is responsible for observing the fiber and eventually
+ * invoking teardown. `makeRunMain` also tries to keep the host process alive
+ * with a long interval while the main fiber is running; if the host blocks
+ * timers, the runner still starts but cannot use that keep-alive fallback.
+ *
  * **Example** (Creating platform runners)
  *
  * ```ts
@@ -224,10 +296,14 @@ declare global {
 }
 
 /**
- * Type-level key for the `Runtime.errorExitCode` property that can be attached
- * to an `Error` to customize the process exit code used by `runMain`.
+ * Type-level key for the `Runtime.errorExitCode` marker.
+ *
+ * **When to use**
+ *
+ * Use to type properties keyed by `Runtime.errorExitCode` on custom error
+ * values.
  *
- * @category Exit code management
+ * @category symbols
  * @since 4.0.0
  */
 export type errorExitCode = "~effect/Runtime/errorExitCode"
@@ -236,6 +312,22 @@ export type errorExitCode = "~effect/Runtime/errorExitCode"
  * Allows associating an exit code with an error for determining the process
  * exit code on failure.
  *
+ * **When to use**
+ *
+ * Use when error classes should map failures to a specific process exit code
+ * when handled by {@link defaultTeardown}.
+ *
+ * **Details**
+ *
+ * Attach this marker as a readonly property on an error object. When the main
+ * program fails, {@link defaultTeardown} squashes the Cause and reads the marker
+ * from the resulting error value.
+ *
+ * **Gotchas**
+ *
+ * The marker is read from the squashed failure value. If a Cause contains
+ * multiple failures, the selected squashed error determines the exit code.
+ *
  * **Example** (Setting a process exit code)
  *
  * ```ts
@@ -250,7 +342,11 @@ export type errorExitCode = "~effect/Runtime/errorExitCode"
  * NodeRuntime.runMain(Effect.fail(new MyError()))
  * ```
  *
- * @category Exit code management
+ * @see {@link errorReported} for controlling automatic error logging
+ * @see {@link defaultTeardown} for the default failure exit-code rules that read this marker
+ * @see {@link getErrorExitCode} for reading the marker from unknown error values
+ *
+ * @category symbols
  * @since 4.0.0
  */
 export const errorExitCode: errorExitCode = "~effect/Runtime/errorExitCode"
@@ -258,13 +354,25 @@ export const errorExitCode: errorExitCode = "~effect/Runtime/errorExitCode"
 /**
  * Reads the runtime exit-code marker from an unknown error value.
  *
+ * **When to use**
+ *
+ * Use to read a custom failure exit code from an unknown error value, falling
+ * back to the default failure code.
+ *
  * **Details**
  *
  * Returns the numeric `[Runtime.errorExitCode]` property when it is present on
  * an object. Otherwise returns `1`, the default failure exit code used by
  * `defaultTeardown`.
  *
- * @category Exit code management
+ * **Gotchas**
+ *
+ * Non-object values, missing markers, and non-number marker values all return
+ * `1`.
+ *
+ * @see {@link errorExitCode} for the marker read by this function
+ *
+ * @category accessors
  * @since 4.0.0
  */
 export const getErrorExitCode = (u: unknown): number => {
@@ -278,16 +386,25 @@ export const getErrorExitCode = (u: unknown): number => {
 }
 
 /**
- * Type-level key for the `Runtime.errorReported` property that controls default
- * `runMain` error logging for an `Error`.
+ * Type-level key for the `Runtime.errorReported` marker.
  *
- * @category Error reporting management
+ * **When to use**
+ *
+ * Use to type properties keyed by `Runtime.errorReported` on custom error
+ * values.
+ *
+ * @category symbols
  * @since 4.0.0
  */
 export type errorReported = "~effect/Runtime/errorReported"
 
 /**
- * Runtime marker that controls default `runMain` error logging for an error.
+ * Defines the runtime marker that controls default `runMain` error logging for an error.
+ *
+ * **When to use**
+ *
+ * Use when error classes are already reported by application code and should
+ * not be logged again by the default main runner.
  *
  * **Details**
  *
@@ -295,6 +412,14 @@ export type errorReported = "~effect/Runtime/errorReported"
  * runtime log because the error has already been reported. Omitted or
  * non-boolean values are treated as `true`, so failures are logged by default.
  *
+ * **Gotchas**
+ *
+ * This marker controls only automatic error logging. It does not change the
+ * failure Cause or the process exit code.
+ * `makeRunMain` reads the marker from `Cause.squash(cause)`, so for causes
+ * with multiple failures, the squashed error determines whether default logging
+ * is suppressed.
+ *
  * **Example** (Suppressing error reporting)
  *
  * ```ts
@@ -310,7 +435,10 @@ export type errorReported = "~effect/Runtime/errorReported"
  * NodeRuntime.runMain(Effect.fail(new MyError()))
  * ```
  *
- * @category Error reporting management
+ * @see {@link errorExitCode} for controlling failure exit codes
+ * @see {@link getErrorReported} for reading the marker from unknown error values
+ *
+ * @category symbols
  * @since 4.0.0
  */
 export const errorReported: errorReported = "~effect/Runtime/errorReported"
@@ -318,12 +446,24 @@ export const errorReported: errorReported = "~effect/Runtime/errorReported"
 /**
  * Reads the runtime error-reporting marker from an unknown error value.
  *
+ * **When to use**
+ *
+ * Use to read whether an unknown error value should be treated as already
+ * reported by the default main runner.
+ *
  * **Details**
  *
  * Returns a boolean `[Runtime.errorReported]` property when it is present on an
  * object. Otherwise returns `true`, so failures are logged by default.
  *
- * @category Error reporting management
+ * **Gotchas**
+ *
+ * Non-object values, missing markers, and non-boolean marker values all return
+ * `true`.
+ *
+ * @see {@link errorReported} for the marker read by this function
+ *
+ * @category accessors
  * @since 4.0.0
  */
 export const getErrorReported = (u: unknown): boolean => {