effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/Deferred.ts

@@ -1,62 +1,9 @@
 /**
- * The `Deferred` module provides a one-shot coordination cell for Effect
- * programs. A `Deferred<A, E>` starts empty, can be completed exactly once, and
- * allows any number of fibers to wait until that completion is available.
- *
- * `Deferred` is useful when one fiber must hand a single result, failure, or
- * interruption signal to other fibers. Awaiters suspend without blocking an OS
- * thread and resume with the same completion once a producer wins the race to
- * complete the cell.
- *
- * **Mental model**
- *
- * - `Deferred.make` creates an empty cell
- * - `Deferred.await` waits for the cell and then observes its stored
- *   success, failure, defect, or interruption
- * - Completion functions such as {@link succeed}, {@link fail},
- *   {@link failCause}, {@link interrupt}, and {@link complete} return
- *   `true` when they complete the cell, or `false` when another fiber already
- *   completed it
- * - Once completed, the result is stable for both current and future awaiters
- *
- * **Common tasks**
- *
- * - Create a cell with {@link make}
- * - Wait for a result with {@link _await await}
- * - Complete with a value or failure using {@link succeed}, {@link fail},
- *   {@link failCause}, {@link die}, or {@link interrupt}
- * - Complete from another effect using {@link complete} or {@link completeWith}
- * - Check completion state with {@link isDone} or inspect it with {@link poll}
- *
- * **Gotchas**
- *
- * - A `Deferred` is for a single handoff; use `Queue` when producers emit many
- *   values over time
- * - `complete` runs an effect once and shares its memoized result, while
- *   `completeWith` stores an effect directly and each awaiter may run it
- * - Interrupting a fiber that is waiting on a `Deferred` removes that waiter;
- *   it does not complete the `Deferred`
- *
- * **Example** (Opening a start gate)
- *
- * ```ts
- * import { Deferred, Effect, Fiber } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const ready = yield* Deferred.make<void>()
- *
- *   const worker = yield* Effect.forkChild(
- *     Effect.gen(function*() {
- *       yield* Deferred.await(ready)
- *       return "started"
- *     })
- *   )
- *
- *   yield* Deferred.succeed(ready, undefined)
- *
- *   return yield* Fiber.join(worker)
- * })
- * ```
+ * One-time coordination cells for Effect programs. A `Deferred<A, E>` starts
+ * empty, can be completed exactly once with a success, failure, defect, or
+ * interruption, and lets any number of fibers wait for that result. Awaiting a
+ * `Deferred` suspends the fiber instead of blocking an operating-system thread,
+ * and every waiter observes the same completion.
  *
  * @since 2.0.0
  */

package/src/Differ.ts

@@ -1,39 +1,8 @@
 /**
- * The `Differ` module defines the core abstraction for describing changes to a
- * value. A `Differ<T, Patch>` knows how to compare two `T` values, produce a
- * patch that represents the difference, combine multiple patches, and apply a
- * patch to an old value to obtain the updated value.
- *
- * **Mental model**
- *
- * - A differ separates "what changed" from "the value after the change"
- * - `diff(oldValue, newValue)` produces a `Patch` that can later be applied
- * - `patch(oldValue, patch)` replays a patch against a value of the same domain
- * - `empty` is the identity patch: applying it should leave the value unchanged
- * - `combine(first, second)` composes patches in sequence, where `second`
- *   represents changes that happen after `first`
- * - Patch types are chosen by the differ implementation and may be compact,
- *   domain-specific, or compatible with a serialization format such as JSON
- *   Patch
- *
- * **Common tasks**
- *
- * - Construct a differ by providing the four operations of the {@link Differ}
- *   interface
- * - Compute a patch with `diff` when you have an old value and a new value
- * - Store, transmit, or aggregate patches instead of storing full replacement
- *   values
- * - Combine incremental updates with `combine` before applying them
- * - Apply updates with `patch` to reconstruct the next value from a previous
- *   value and a patch
- *
- * **Gotchas**
- *
- * - `combine` is order-sensitive for most patch formats
- * - A patch is generally meaningful only for values that belong to the same
- *   domain and assumptions used by the differ that created it
- * - Differs should make `empty` a true identity and should make combined
- *   patches behave the same as applying the original patches in order
+ * Interfaces for describing changes to a value as patches. A
+ * `Differ<T, Patch>` compares an old and new value, creates a patch for the
+ * difference, combines patches in order, and applies a patch to an old value to
+ * produce an updated value.
  *
  * @since 4.0.0
  */

package/src/Duration.ts

@@ -1,51 +1,11 @@
 /**
- * The `Duration` module models spans of time as immutable values with support
- * for unit conversion, ordering, arithmetic, and positive or negative infinity.
- * It is the standard representation for delays, timeouts, intervals, and
- * TTL-like values across Effect APIs.
- *
- * **Mental model**
- *
- * - A `Duration` stores either milliseconds, nanoseconds, `Infinity`, or
- *   `-Infinity`; operations preserve that distinction where it matters
- * - Constructor helpers such as {@link seconds} and {@link millis} build
- *   duration values for the chosen unit
- * - {@link Input} values are decoded at API boundaries: numbers mean
- *   milliseconds, bigints mean nanoseconds, tuples mean `[seconds, nanos]`,
- *   and strings use units such as `"5 seconds"`
- * - Arithmetic and ordering helpers return new duration values rather than
- *   mutating existing ones
- *
- * **Common tasks**
- *
- * - Build durations with {@link nanos}, {@link micros}, {@link millis},
- *   {@link seconds}, {@link minutes}, {@link hours}, {@link days}, or
- *   {@link weeks}
- * - Decode flexible inputs with {@link fromInput} or {@link fromInputUnsafe}
- * - Convert with {@link toMillis}, {@link toSeconds}, {@link toNanos},
- *   {@link toHrTime}, {@link parts}, or {@link format}
- * - Compare and constrain durations with {@link Order}, {@link between},
- *   {@link min}, {@link max}, and {@link clamp}
- * - Combine durations with {@link sum}, {@link subtract}, {@link times}, and
- *   {@link divide}
+ * Represents immutable spans of time.
  *
- * **Gotchas**
- *
- * - Passing a plain number means milliseconds, not seconds
- * - {@link toNanosUnsafe} throws for infinite durations; {@link toNanos}
- *   returns `Option.none()` instead
- * - Unsafe decoders and unsafe math helpers throw or apply fallback rules for
- *   invalid inputs; prefer the safe variants when input is external
- *
- * **Example** (Decoding and formatting a duration)
- *
- * ```ts
- * import { Duration, Option } from "effect"
- *
- * const formatted = Duration.fromInput("90 seconds").pipe(
- *   Option.map((duration) => Duration.format(duration))
- * )
- * ```
+ * A `Duration` can be finite, positive infinity, or negative infinity. It is
+ * the standard representation for delays, timeouts, intervals, and
+ * time-to-live values across Effect APIs. This module includes constructors
+ * from common input shapes, unit conversions, comparisons, arithmetic,
+ * formatting, and reusable reducer or combiner helpers.
  *
  * @since 2.0.0
  */

package/src/Effect.ts

@@ -1,79 +1,12 @@
 /**
- * `Effect` is the core data type for describing programs that may perform
- * synchronous or asynchronous work, fail with typed errors, require services,
- * acquire resources, or run concurrently. An `Effect<A, E, R>` is lazy: creating
- * one describes a workflow, and running it executes that workflow.
- *
- * **Mental model**
- *
- * - `A` is the success value, `E` is the expected failure type, and `R` is the
- *   context of services required to run
- * - Effects are immutable descriptions, not promises; composition with
- *   {@link map}, {@link flatMap}, {@link zip}, or {@link gen} builds a larger
- *   description
- * - Failures in `E` are part of the type signature and can be handled with
- *   {@link match}, {@link matchEffect}, {@link catchTag}, or {@link catchTags}
- * - Requirements in `R` are satisfied before running, usually with
- *   {@link provide}, {@link provideService}, or layers
- * - Fibers are lightweight executions of effects and are used by concurrency
- *   operators such as {@link all}, {@link race}, {@link forkScoped}, and
- *   {@link forkDetach}
- *
- * **Common tasks**
- *
- * - Create values and failures: {@link succeed}, {@link fail}, {@link failSync}
- * - Wrap promise-producing code: {@link tryPromise}
- * - Sequence workflows: {@link gen}, {@link flatMap}, {@link map}, {@link tap}
- * - Handle errors: {@link match}, {@link matchEffect}, {@link catchTag},
- *   {@link catchTags}
- * - Run effects at the edge of an application: {@link runPromise},
- *   {@link runSync}, {@link runFork}
- * - Work with time and interruption: {@link sleep}, {@link timeout},
- *   {@link retry}
- * - Manage resources: {@link acquireRelease}, {@link scoped},
- *   {@link scopedWith}
- * - Provide services: {@link provide}, {@link provideContext},
- *   {@link provideService}, {@link provideServiceEffect}
+ * Describes workflows that run only when executed by the Effect runtime.
  *
- * **Gotchas**
- *
- * - Effects do nothing until run by a runtime function such as
- *   {@link runPromise}, {@link runSync}, or {@link runFork}
- * - {@link runSync} is only for effects that can complete synchronously; use
- *   {@link runPromise} for effects that may suspend asynchronously
- * - In {@link gen}, use `yield*` to compose effects; do not use `await` inside
- *   the generator
- * - The `E` type tracks expected failures, not every possible JavaScript
- *   defect such as an unchecked throw
- * - Any remaining `R` requirement must be provided before an effect can be run
- *
- * **Quickstart**
- *
- * **Example** (Composing and running a typed workflow)
- *
- * ```ts
- * import { Console, Effect } from "effect"
- *
- * const divide = (a: number, b: number) =>
- *   b === 0
- *     ? Effect.fail("divide by zero")
- *     : Effect.succeed(a / b)
- *
- * const program = Effect.gen(function*() {
- *   const result = yield* divide(10, 2)
- *   yield* Console.log(`result: ${result}`)
- *   return result
- * })
- *
- * Effect.runPromise(program).then(console.log)
- * ```
- *
- * **See also**
- *
- * - {@link gen} for generator-based sequencing
- * - {@link tryPromise} for asynchronous boundaries
- * - {@link acquireRelease} and {@link scoped} for resource safety
- * - {@link runPromise}, {@link runSync}, and {@link runFork} for execution
+ * An `Effect<A, E, R>` can succeed with an `A`, fail with an `E`, and require
+ * services `R`. Creating an effect does not perform the work; it builds a value
+ * that can be composed, provided with services, retried, interrupted, run
+ * concurrently, or inspected by the runtime. This module is the main API for
+ * creating effects, combining them, handling failures, managing resources, and
+ * running effect programs.
  *
  * @since 2.0.0
  */
@@ -328,7 +261,7 @@ export declare namespace All {
   /**
    * Alias for any `Effect` value accepted by `Effect.all`.
    *
-   * @category models
+   * @category utility types
    * @since 2.0.0
    */
   export type EffectAny = Effect<any, any, any>
@@ -336,7 +269,7 @@ export declare namespace All {
   /**
    * Computes the return type for `Effect.all` when collecting an iterable.
    *
-   * @category models
+   * @category utility types
    * @since 2.0.0
    */
   export type ReturnIterable<
@@ -353,7 +286,7 @@ export declare namespace All {
   /**
    * Computes the return type for `Effect.all` when collecting a tuple.
    *
-   * @category models
+   * @category utility types
    * @since 2.0.0
    */
   export type ReturnTuple<
@@ -384,7 +317,7 @@ export declare namespace All {
   /**
    * Computes the return type for `Effect.all` when collecting a record.
    *
-   * @category models
+   * @category utility types
    * @since 2.0.0
    */
   export type ReturnObject<T, Discard extends boolean, Mode extends boolean = false> = [T] extends [
@@ -410,7 +343,7 @@ export declare namespace All {
   /**
    * Detects whether `Effect.all` should discard collected values.
    *
-   * @category models
+   * @category utility types
    * @since 2.0.0
    */
   export type IsDiscard<A> = [Extract<A, { readonly discard: true }>] extends [
@@ -421,7 +354,7 @@ export declare namespace All {
   /**
    * Detects whether `Effect.all` should collect results in `Result` mode.
    *
-   * @category models
+   * @category utility types
    * @since 4.0.0
    */
   export type IsResult<A> = [Extract<A, { readonly mode: "result" }>] extends [never] ? false : true
@@ -429,7 +362,7 @@ export declare namespace All {
   /**
    * Computes the return type for `Effect.all` from its input and options.
    *
-   * @category models
+   * @category utility types
    * @since 2.0.0
    */
   export type Return<
@@ -17889,9 +17822,46 @@ export const runSyncExitWith: <R>(
  */
 export declare namespace fn {
   /**
-   * Generator return type accepted by `Effect.fn` and `Effect.fnUntraced`.
+   * Generator return type accepted by {@link fn} and {@link fnUntraced}.
+   *
+   * **When to use**
+   *
+   * Use when you need to annotate the return type of a generator body while
+   * keeping the produced function's `Effect` return type inferred.
+   *
+   * **Example** (Annotating an Effect function)
    *
-   * @category models
+   * ```ts
+   * import { Effect } from "effect"
+   *
+   * const f = Effect.fnUntraced(function*(
+   *   value: string
+   * ): Effect.fn.Return<number> {
+   *   return yield* Effect.succeed(value.length)
+   * })
+   *
+   * //      ┌─── Effect.Effect<number>
+   * //      ▼
+   * const program = f("hello")
+   * ```
+   *
+   * **Example** (Annotating a parametric Effect function)
+   *
+   * ```ts
+   * import { Effect } from "effect"
+   *
+   * const f = Effect.fnUntraced(function*<A>(
+   *   value: A
+   * ): Effect.fn.Return<A> {
+   *   return yield* Effect.succeed(value)
+   * })
+   *
+   * //      ┌─── Effect.Effect<string>
+   * //      ▼
+   * const program = f("hello")
+   * ```
+   *
+   * @category utility types
    * @since 3.19.0
    */
   export type Return<A, E = never, R = never> = Generator<Effect<any, E, R>, A, any>
@@ -17899,7 +17869,7 @@ export declare namespace fn {
   /**
    * Type of the untraced function builder used by `Effect.fnUntraced`.
    *
-   * @category models
+   * @category utility types
    * @since 3.11.0
    */
   export type Untraced = {
@@ -19487,7 +19457,7 @@ export declare namespace fn {
   /**
    * Type of the traced function builder used by `Effect.fn`.
    *
-   * @category models
+   * @category utility types
    * @since 4.0.0
    */
   export type Traced = {
@@ -21931,21 +21901,88 @@ export declare namespace fn {
 /**
  * Creates an Effect-returning function without tracing.
  *
+ * **When to use**
+ *
+ * Use when you are defining a reusable Effect function whose implementation
+ * would otherwise be a normal function returning {@link gen}, especially when
+ * tracing spans or stack-frame capture are not needed.
+ *
  * **Details**
  *
- * `Effect.fnUntraced` also acts as a `pipe` function, so you can append transforms after the body.
+ * Compared to a plain function that returns {@link gen}, `Effect.fnUntraced`
+ * reuses the generator body instead of allocating a fresh generator closure
+ * around the arguments on every call. It does not record an Effect stack-frame
+ * boundary and does not create tracing spans. Use {@link fn} when you need
+ * those stack frames or spans. Additional arguments after the generator body
+ * act like `pipe` transforms: each transform receives the previous result and
+ * the original function arguments. Annotate the generator return type with
+ * `Effect.fn.Return<A, E, R>` when the produced `Effect` type needs to be
+ * stated explicitly.
  *
  * **Example** (Defining untraced effect functions)
  *
  * ```ts
- * import { Console, Effect } from "effect"
+ * import { Effect } from "effect"
  *
- * const greet = Effect.fnUntraced(function* (name: string) {
- *   yield* Console.log(`Hello, ${name}`)
- *   return name.length
+ * const f = Effect.fnUntraced(function*(
+ *   value: string
+ * ) {
+ *   return yield* Effect.succeed(value.length)
  * })
  *
- * Effect.runFork(greet("Ada"))
+ * //      ┌─── Effect.Effect<number>
+ * //      ▼
+ * const program = f("hello")
+ * ```
+ *
+ * **Example** (Transforming the returned Effect)
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * const f = Effect.fnUntraced(
+ *   function*(value: string) {
+ *     return yield* Effect.succeed(value.length)
+ *   },
+ *   (effect, value) =>
+ *     effect.pipe(Effect.map((length) => `${value}: ${length}`))
+ * )
+ *
+ * //      ┌─── Effect.Effect<string>
+ * //      ▼
+ * const program = f("hello")
+ * ```
+ *
+ * **Example** (Annotating an untraced non-parametric function)
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * const f = Effect.fnUntraced(function*(
+ *   value: string
+ * ): Effect.fn.Return<number> {
+ *   return yield* Effect.succeed(value.length)
+ * })
+ *
+ * //      ┌─── Effect.Effect<number>
+ * //      ▼
+ * const program = f("hello")
+ * ```
+ *
+ * **Example** (Annotating an untraced parametric function)
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * const f = Effect.fnUntraced(function*<A>(
+ *   value: A
+ * ): Effect.fn.Return<A> {
+ *   return yield* Effect.succeed(value)
+ * })
+ *
+ * //      ┌─── Effect.Effect<string>
+ * //      ▼
+ * const program = f("hello")
  * ```
  *
  * @category functions
@@ -21954,30 +21991,117 @@ export declare namespace fn {
 export const fnUntraced: fn.Untraced = internal.fnUntraced
 
 /**
- * Creates a traced function with an optional span name and `SpanOptionsNoTrace` that adds spans and stack frames, plus pipeable post-processing that receives the Effect and the original arguments.
+ * Creates a reusable traced function from an Effect body.
+ *
+ * **When to use**
+ *
+ * Use when you are defining a reusable Effect function whose implementation
+ * would otherwise be a normal function returning {@link gen}, and you want
+ * tracing spans or stack-frame capture.
  *
  * **Details**
  *
- * Pipeable functions run after the body and can transform the resulting Effect.
+ * Compared to a plain function that returns {@link gen}, `Effect.fn` reuses the
+ * generator body instead of allocating a fresh generator closure around the
+ * arguments on every call. Call `Effect.fn(body, ...)` for a generic
+ * stack-frame boundary without creating a span. Call
+ * `Effect.fn("operationName", options?)(body, ...)` when that boundary should
+ * have a readable operation name and the returned `Effect` should create a
+ * tracing span when run. {@link SpanOptionsNoTrace} configures span metadata
+ * such as attributes, links, parent or root selection, kind, sampling, and log
+ * level. Additional arguments after the generator body act like `pipe`
+ * transforms: each transform receives the previous result and the original
+ * function arguments. When those transforms return an `Effect`, the returned
+ * effect includes stack-frame metadata and, for the named form, a tracing span.
+ * Generator bodies may declare a `this` parameter; pass `{ self }` before the
+ * body to bind `this` when the function is created.
  *
  * **Example** (Defining traced effect functions)
  *
  * ```ts
- * import { Console, Effect } from "effect"
+ * import { Effect } from "effect"
  *
- * // Create a named span and post-process the returned Effect.
- * const greet = Effect.fn("greet")(
- *   function*(name: string) {
- *     yield* Console.log(`Hello, ${name}`)
- *     return name.length
+ * const f = Effect.fn("calculateLength")(function*(value: string) {
+ *   return yield* Effect.succeed(value.length)
+ * })
+ *
+ * //      ┌─── Effect.Effect<number>
+ * //      ▼
+ * const program = f("hello")
+ * ```
+ *
+ * **Example** (Transforming the returned Effect)
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * const f = Effect.fn("formatLength")(
+ *   function*(value: string) {
+ *     return yield* Effect.succeed(value.length)
  *   },
- *   Effect.map((length) => length + 1)
+ *   (effect, value) =>
+ *     effect.pipe(Effect.map((length) => `${value}: ${length}`))
  * )
  *
- * const program = Effect.gen(function*() {
- *   const result = yield* greet("Ada")
- *   yield* Console.log(`Length: ${result}`)
+ * //      ┌─── Effect.Effect<string>
+ * //      ▼
+ * const program = f("hello")
+ * ```
+ *
+ * **Example** (Binding this)
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * class Counter {
+ *   count = 0
+ *
+ *   increment = Effect.fn("Counter.increment")(
+ *     { self: this },
+ *     function*(this: Counter, by: number) {
+ *       this.count += by
+ *       return yield* Effect.succeed(this.count)
+ *     }
+ *   )
+ * }
+ *
+ * const counter = new Counter()
+ *
+ * //      ┌─── Effect.Effect<number>
+ * //      ▼
+ * const program = counter.increment(1)
+ * ```
+ *
+ * **Example** (Annotating a traced non-parametric function)
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * const f = Effect.fn("calculateLength")(function*(
+ *   value: string
+ * ): Effect.fn.Return<number> {
+ *   return yield* Effect.succeed(value.length)
  * })
+ *
+ * //      ┌─── Effect.Effect<number>
+ * //      ▼
+ * const program = f("hello")
+ * ```
+ *
+ * **Example** (Annotating a traced parametric function)
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * const f = Effect.fn("succeed")(function*<A>(
+ *   value: A
+ * ): Effect.fn.Return<A> {
+ *   return yield* Effect.succeed(value)
+ * })
+ *
+ * //      ┌─── Effect.Effect<string>
+ * //      ▼
+ * const program = f("hello")
  * ```
  *
  * @category functions

package/src/Effectable.ts

@@ -1,38 +1,8 @@
 /**
- * The `Effectable` module provides low-level building blocks for defining
- * custom values that behave like `Effect`s. It is primarily used by library
- * authors who need domain-specific effect-like data types, such as service
- * keys, configuration descriptions, prompts, or other declarative programs
- * that can be yielded inside `Effect.gen`.
- *
- * **Mental model**
- *
- * - `Effectable` does not run effects by itself; it provides prototypes that
- *   implement the internal Effect protocol.
- * - {@link Prototype} creates a primitive Effect prototype with a custom
- *   evaluation function that receives the current `Fiber`.
- * - {@link Class} is an abstract base class for defining custom classes whose
- *   instances are also `Effect` values.
- * - The success, error, and service requirements of the custom type are
- *   preserved through the `Effect.Effect<A, E, R>` type parameters.
- *
- * **Common tasks**
- *
- * - Build an effect-like interface around a declarative data structure.
- * - Implement a custom `evaluate` hook that interprets the value in terms of
- *   the current fiber and returns the underlying `Effect`.
- * - Extend {@link Class} when a nominal class-based API is more convenient
- *   than manually wiring a prototype.
- *
- * **Gotchas**
- *
- * - This module is intentionally low-level; most application code should use
- *   `Effect` constructors and combinators instead.
- * - `evaluate` must return an `Effect` with the same success, error, and
- *   service types as the custom value.
- * - Because these APIs participate in the internal Effect protocol, keep
- *   implementations small and follow existing modules such as `Config` and
- *   `Context` when adding new effect-like types.
+ * Low-level helpers for making custom values behave like Effects. The module
+ * exposes a prototype builder and an abstract base class that let
+ * domain-specific values, such as service keys or configuration descriptions,
+ * be evaluated by Effect and yielded inside `Effect.gen`.
  *
  * @since 4.0.0
  */