effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/Runtime.ts

@@ -36,8 +36,9 @@ import type * as Fiber from "./Fiber.ts"
 /**
  * Represents a teardown function that handles program completion and determines the exit code.
  *
- * The teardown function is called when an Effect program completes (either successfully or with failure)
- * and is responsible for determining the appropriate exit code and performing any cleanup operations.
+ * **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.
  *
  * **Example** (Customizing teardown behavior)
  *
@@ -76,12 +77,11 @@ export interface Teardown {
 }
 
 /**
- * The default teardown function that determines exit codes based on Effect completion.
+ * The default teardown function that determines exit codes from an Effect exit.
  *
- * This teardown function follows standard Unix conventions:
- * - Returns exit code 0 for successful completion
- * - Returns exit code 1 for failures (except interruption-only failures)
- * - Returns exit code 130 for interruption-only failures
+ * **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.
  *
  * **Example** (Using default teardown)
  *
@@ -119,9 +119,9 @@ export const defaultTeardown: Teardown = <E, A>(
 /**
  * Creates a platform-specific main program runner that handles Effect execution lifecycle.
  *
- * This function creates a runner that can execute Effect programs as main entry points,
- * handling process signals, fiber management, and teardown operations. The provided
- * function receives a fiber and teardown callback to implement platform-specific behavior.
+ * **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.
  *
  * **Example** (Creating platform runners)
  *
@@ -259,6 +259,7 @@ export const errorExitCode: errorExitCode = "~effect/Runtime/errorExitCode"
  * Reads the runtime exit-code marker from an unknown error value.
  *
  * **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`.
@@ -289,6 +290,7 @@ export type errorReported = "~effect/Runtime/errorReported"
  * Runtime marker that controls default `runMain` error logging for an error.
  *
  * **Details**
+ *
  * Set `[Runtime.errorReported]` to `false` on an error object to suppress the
  * runtime log because the error has already been reported. Omitted or
  * non-boolean values are treated as `true`, so failures are logged by default.
@@ -300,7 +302,7 @@ export type errorReported = "~effect/Runtime/errorReported"
  * import { NodeRuntime } from "@effect/platform-node"
  *
  * class MyError extends Data.TaggedError("MyError") {
- *   readonly [Runtime.errorReported] = true
+ *   readonly [Runtime.errorReported] = false
  * }
  *
  * // If the program fails with MyError, the process will exit with code 1 but
@@ -317,6 +319,7 @@ export const errorReported: errorReported = "~effect/Runtime/errorReported"
  * Reads the runtime error-reporting marker from an unknown error value.
  *
  * **Details**
+ *
  * Returns a boolean `[Runtime.errorReported]` property when it is present on an
  * object. Otherwise returns `true`, so failures are logged by default.
  *

package/src/Schedule.ts

@@ -178,6 +178,7 @@ export interface Metadata<Output = unknown, Input = unknown> extends InputMetada
  * Context reference containing metadata for the currently running schedule step.
  *
  * **Details**
+ *
  * Repeat, retry, stream, and channel scheduling operations provide this service
  * to effects run between schedule steps. The default value contains undefined
  * input and output values, zero duration, and zeroed timing fields before any
@@ -272,7 +273,8 @@ export declare namespace Schedule {
    * Type-level marker used by `Schedule.Variance` to record the variance of
    * `Schedule` type parameters.
    *
-   * **Notes**
+   * **Details**
+   *
    * This interface exists for TypeScript inference and assignability. Users
    * normally do not construct or inspect it directly.
    *
@@ -976,6 +978,8 @@ export const andThen: {
  * schedule to completion. Once the left schedule is complete, the right (i.e.
  * `other`) schedule will be executed to completion.
  *
+ * **Details**
+ *
  * The resulting schedule emits a `Result` to indicate which phase produced
  * each output: outputs from `self` are emitted as `Failure`, and outputs from
  * `other` are emitted as `Success`.
@@ -1018,6 +1022,8 @@ export const andThenResult: {
    * schedule to completion. Once the left schedule is complete, the right (i.e.
    * `other`) schedule will be executed to completion.
    *
+   * **Details**
+   *
    * The resulting schedule emits a `Result` to indicate which phase produced
    * each output: outputs from `self` are emitted as `Failure`, and outputs from
    * `other` are emitted as `Success`.
@@ -1062,6 +1068,8 @@ export const andThenResult: {
    * schedule to completion. Once the left schedule is complete, the right (i.e.
    * `other`) schedule will be executed to completion.
    *
+   * **Details**
+   *
    * The resulting schedule emits a `Result` to indicate which phase produced
    * each output: outputs from `self` are emitted as `Failure`, and outputs from
    * `other` are emitted as `Success`.
@@ -1134,6 +1142,8 @@ export const andThenResult: {
          * schedule to completion. Once the left schedule is complete, the right (i.e.
          * `other`) schedule will be executed to completion.
          *
+         * **Details**
+         *
          * The resulting schedule emits a `Result` to indicate which phase produced
          * each output: outputs from `self` are emitted as `Failure`, and outputs from
          * `other` are emitted as `Success`.
@@ -1176,6 +1186,8 @@ export const andThenResult: {
          * schedule to completion. Once the left schedule is complete, the right (i.e.
          * `other`) schedule will be executed to completion.
          *
+         * **Details**
+         *
          * The resulting schedule emits a `Result` to indicate which phase produced
          * each output: outputs from `self` are emitted as `Failure`, and outputs from
          * `other` are emitted as `Success`.
@@ -1218,6 +1230,8 @@ export const andThenResult: {
          * schedule to completion. Once the left schedule is complete, the right (i.e.
          * `other`) schedule will be executed to completion.
          *
+         * **Details**
+         *
          * The resulting schedule emits a `Result` to indicate which phase produced
          * each output: outputs from `self` are emitted as `Failure`, and outputs from
          * `other` are emitted as `Success`.
@@ -1260,6 +1274,8 @@ export const andThenResult: {
          * schedule to completion. Once the left schedule is complete, the right (i.e.
          * `other`) schedule will be executed to completion.
          *
+         * **Details**
+         *
          * The resulting schedule emits a `Result` to indicate which phase produced
          * each output: outputs from `self` are emitted as `Failure`, and outputs from
          * `other` are emitted as `Success`.
@@ -1925,6 +1941,7 @@ export const bothWith: {
  * far as an array.
  *
  * **Details**
+ *
  * This does not make the schedule run forever. The collected schedule stops
  * when `self` stops and fails when `self` fails.
  *
@@ -1963,6 +1980,7 @@ export const collectInputs = <Output, Input, Error, Env>(
  * seen so far as an array.
  *
  * **Details**
+ *
  * This does not make the schedule run forever. The collected schedule stops
  * when `self` stops and fails when `self` fails.
  *
@@ -2773,6 +2791,8 @@ export const delays = <Out, In, E, R>(self: Schedule<Out, In, E, R>): Schedule<D
 /**
  * Returns a schedule that recurs once after the specified duration.
  *
+ * **Details**
+ *
  * The schedule outputs the configured duration for its first recurrence and
  * then completes.
  *
@@ -3558,6 +3578,8 @@ export const eitherWith: {
 /**
  * A schedule that always recurs and returns the total elapsed duration since the first recurrence.
  *
+ * **Details**
+ *
  * This schedule never stops and outputs the cumulative time that has passed since the schedule
  * started executing. Useful for tracking execution time or implementing time-based logic.
  *
@@ -3733,10 +3755,12 @@ export const fibonacci = (one: Duration.Input): Schedule<Duration.Duration> => {
  * Returns a `Schedule` that recurs on the specified fixed `interval` and
  * outputs the number of repetitions of the schedule so far.
  *
+ * **Details**
+ *
  * If the action run between updates takes longer than the interval, then the
  * action will be run immediately, but re-runs will not "pile up".
  *
- * ```
+ * ```text
  * |-----interval-----|-----interval-----|-----interval-----|
  * |---------action--------||action|-----|action|-----------|
  * ```
@@ -4161,6 +4185,8 @@ export const modifyDelay: {
 /**
  * Returns a new `Schedule` that randomly adjusts each recurrence delay.
  *
+ * **Details**
+ *
  * Delays are jittered between `80%` and `120%` of the original delay.
  *
  * @category utils
@@ -5778,6 +5804,8 @@ export {
    * Returns a new schedule that passes each input and output of the specified
    * schedule to the provided `predicate`.
    *
+   * **Details**
+   *
    * If the `predicate` returns `true`, the schedule will continue, otherwise
    * the schedule will stop.
    *
@@ -5791,10 +5819,12 @@ export {
  * A schedule that divides the timeline to `interval`-long windows, and sleeps
  * until the nearest window boundary every time it recurs.
  *
+ * **Details**
+ *
  * For example, `Schedule.windowed("10 seconds")` would produce a schedule as
  * follows:
  *
- * ```
+ * ```text
  *      10s        10s        10s       10s
  * |----------|----------|----------|----------|
  * |action------|sleep---|act|-sleep|action----|
@@ -5835,6 +5865,8 @@ export const windowed = (interval: Duration.Input): Schedule<number> => {
 /**
  * Returns a new `Schedule` that will recur forever.
  *
+ * **Details**
+ *
  * The output of the schedule is the current count of its repetitions thus far
  * (i.e. `0, 1, 2, ...`).
  *

package/src/Scheduler.ts

@@ -24,14 +24,14 @@ import * as Context from "./Context.ts"
 import type * as Fiber from "./Fiber.ts"
 
 /**
- * A scheduler manages the execution of Effects by controlling when and how tasks
- * are scheduled and executed. It determines the execution mode (synchronous or
- * asynchronous) and handles task prioritization and yielding behavior.
+ * A scheduler manages the execution of Effect fibers by controlling when queued
+ * tasks run.
  *
- * The scheduler is responsible for:
- * - Scheduling tasks with different priorities
- * - Determining when fibers should yield control
- * - Managing the execution flow of Effects
+ * **Details**
+ *
+ * A scheduler determines the execution mode, schedules tasks with different
+ * priorities, and decides when fibers should yield control after consuming
+ * their operation budget.
  *
  * @category models
  * @since 2.0.0
@@ -47,6 +47,7 @@ export interface Scheduler {
  * tasks to run.
  *
  * **Details**
+ *
  * `scheduleTask` queues a task with a priority. `flush` drains pending work
  * synchronously, which is useful when callers need deterministic completion of
  * already scheduled tasks.
@@ -63,6 +64,7 @@ export interface SchedulerDispatcher {
  * Context reference for the scheduler used by the Effect runtime.
  *
  * **Details**
+ *
  * The default value creates a `MixedScheduler`. Provide this service to
  * customize execution mode, task dispatching, or yield behavior.
  *
@@ -114,15 +116,14 @@ class PriorityBuckets {
 }
 
 /**
- * A scheduler implementation that provides efficient task scheduling
- * with support for both synchronous and asynchronous execution modes.
+ * A scheduler implementation that batches queued tasks and dispatches them by
+ * priority.
  *
- * Features:
- * - Batches tasks for efficient execution
- * - Supports priority-based task scheduling
- * - Configurable execution mode (sync/async)
- * - Automatic yielding based on operation count
- * - Optimized for high-throughput scenarios
+ * **Details**
+ *
+ * `MixedScheduler` supports synchronous and asynchronous execution modes, uses
+ * operation counts to decide when fibers should yield, and is the default
+ * scheduler implementation.
  *
  * @category schedulers
  * @since 2.0.0
@@ -216,11 +217,13 @@ class MixedSchedulerDispatcher implements SchedulerDispatcher {
 
 /**
  * A service reference that controls the maximum number of operations a fiber
- * can perform before yielding control back to the scheduler. This helps
- * prevent long-running fibers from monopolizing the execution thread.
+ * can perform before yielding control back to the scheduler.
+ *
+ * **Details**
  *
- * The default value is 2048 operations, which provides a good balance between
- * performance and fairness in concurrent execution.
+ * The default value is `2048` operations, which balances performance and
+ * fairness by helping prevent long-running fibers from monopolizing the
+ * execution thread.
  *
  * @category references
  * @since 4.0.0