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

package/src/Record.ts

@@ -1,76 +1,11 @@
 /**
- * Tools for working with plain JavaScript records as immutable key-value
- * dictionaries. The module covers construction, lookup, updates, mapping,
- * filtering, folding, set-like combination, and typed conversions between
- * records and iterable entries.
- *
- * Reach for `Record` when your data is already represented as a plain object
- * with string or symbol keys and you want typed, data-first or data-last
- * helpers that return new records instead of mutating the input.
- *
- * **Mental model**
- *
- * - A `ReadonlyRecord<K, A>` is a plain object whose keys are known by type and
- *   whose values share a common type.
- * - Operations such as {@link set}, {@link remove}, {@link map}, and
- *   {@link filter} allocate new plain objects.
- * - Lookups and updates that might miss a key return `Option` values through
- *   APIs such as {@link get}, {@link modify}, {@link replace}, and {@link pop}.
- * - Many APIs are dual, so they work both as `Record.map(record, f)` and in
- *   pipelines as `pipe(record, Record.map(f))`.
- *
- * **Common tasks**
- *
- * - Create records: {@link empty}, {@link singleton}, {@link fromEntries},
- *   {@link fromIterableBy}, {@link fromIterableWith}
- * - Inspect records: {@link isEmptyRecord}, {@link size}, {@link has},
- *   {@link get}, {@link keys}, {@link values}, {@link toEntries}
- * - Add, update, or remove entries: {@link set}, {@link modify},
- *   {@link replace}, {@link remove}, {@link pop}
- * - Transform entries: {@link map}, {@link mapKeys}, {@link mapEntries},
- *   {@link collect}
- * - Filter or partition: {@link filter}, {@link filterMap}, {@link getSomes},
- *   {@link getFailures}, {@link getSuccesses}, {@link partition},
- *   {@link separate}
- * - Fold and search: {@link reduce}, {@link every}, {@link some},
- *   {@link findFirst}
- * - Combine records: {@link union}, {@link intersection}, {@link difference},
- *   {@link makeReducerUnion}, {@link makeReducerIntersection}
- * - Compare records: {@link isSubrecord}, {@link isSubrecordBy},
- *   {@link makeEquivalence}
+ * Works with plain JavaScript records as immutable key/value dictionaries.
  *
- * **Gotchas**
- *
- * - Iteration-based APIs use `Object.keys`, so they visit enumerable string
- *   keys. Targeted APIs such as {@link has}, {@link get}, {@link set}, and
- *   {@link remove} can work with symbol keys, but {@link keys}, {@link values},
- *   {@link map}, and similar traversal APIs do not visit symbols.
- * - When duplicate keys are produced by constructors or key-mapping APIs, later
- *   writes overwrite earlier values according to normal object assignment.
- *
- * **Quickstart**
- *
- * **Example** (Transforming a record without mutation)
- *
- * ```ts
- * import { Record } from "effect"
- *
- * const scores = { alice: 1, bob: 2 }
- *
- * const next = Record.set(scores, "carol", 3)
- * const doubled = Record.map(next, (score) => score * 2)
- *
- * console.log(scores) // { alice: 1, bob: 2 }
- * console.log(doubled) // { alice: 2, bob: 4, carol: 6 }
- * console.log(Record.get(doubled, "alice")) // Option.some(2)
- * ```
- *
- * **See also**
- *
- * - `Struct` for fixed-shape objects where each field may have a
- *   different type
- * - `HashMap` for immutable maps with arbitrary key types and Effect
- *   equality / hashing semantics
+ * A record is an object whose keys are strings or symbols. This module includes
+ * helpers for construction, lookup, updates, mapping, filtering, folding,
+ * set-like combination, and typed conversions between records and iterable
+ * entries. Helpers that change values return new records instead of mutating the
+ * input.
  *
  * @since 2.0.0
  */

package/src/Redactable.ts

@@ -6,64 +6,6 @@
  * Typical use cases include masking secrets, tokens, or personal data in logs, traces,
  * and serialized output.
  *
- * ## Mental model
- *
- * - **Redactable** - an object that implements `[symbolRedactable]`, a method
- *   that receives the current `Context` and returns a replacement value.
- * - **symbolRedactable** - the well-known `Symbol` key that marks an object as
- *   redactable.
- * - **redact** - the primary entry point: pass any value and get back either its
- *   redacted form (if it is `Redactable`) or the original value unchanged.
- * - **getRedacted** - lower-level helper that calls `[symbolRedactable]` directly
- *   on a value already known to be `Redactable`.
- * - The `Context` passed to `[symbolRedactable]` comes from the current fiber.
- *   If no fiber is active, an empty `Context` is used.
- *
- * ## Common tasks
- *
- * - **Make a value redactable**: implement the {@link Redactable} interface by
- *   adding a `[symbolRedactable]` method.
- * - **Redact an unknown value**: call {@link redact} - it returns the original
- *   value when it is not redactable.
- * - **Check if a value is redactable**: use {@link isRedactable}.
- * - **Get the redacted form of a known `Redactable`**: use {@link getRedacted}.
- *
- * ## Gotchas
- *
- * - `[symbolRedactable]` receives the fiber's `Context` as its argument.
- * - Outside of an Effect runtime (no current fiber), `getRedacted` still works
- *   but passes an empty `Context`, so service lookups will not find anything.
- * - `redact` is not recursive: if a redactable object contains nested
- *   redactable values, only the outermost redaction is applied.
- *
- * ## Quickstart
- *
- * **Example** (Masking an API key)
- *
- * ```ts
- * import { Context, Redactable } from "effect"
- *
- * class ApiKey {
- *   constructor(readonly raw: string) {}
- *
- *   [Redactable.symbolRedactable](_ctx: Context.Context<never>) {
- *     return this.raw.slice(0, 4) + "..."
- *   }
- * }
- *
- * const key = new ApiKey("sk-1234567890abcdef")
- *
- * console.log(Redactable.isRedactable(key))  // true
- * console.log(Redactable.redact(key))         // "sk-1..."
- * console.log(Redactable.redact("plain"))     // "plain"
- * ```
- *
- * ## See also
- *
- * - {@link Redactable} - the interface to implement
- * - {@link symbolRedactable} - the symbol key
- * - {@link redact} - the main redaction entry point
- *
  * @since 4.0.0
  */
 import type * as Context from "./Context.ts"

package/src/Redacted.ts

@@ -1,45 +1,12 @@
 /**
- * The `Redacted` module wraps sensitive values so normal rendering paths show
- * a placeholder instead of the underlying value. It is designed to reduce
- * accidental disclosure in logs, error messages, JSON output, and inspection
- * output while still allowing trusted code to recover the original value.
- *
- * **Mental model**
- *
- * - A `Redacted<A>` carries an underlying value of type `A` behind a wrapper
- * - String, JSON, and inspection output render as `<redacted>` or
- *   `<redacted:label>` when a label is provided
- * - {@link value} retrieves the underlying value and should be used only at
- *   trusted boundaries
- * - Equality and hashing are based on the underlying value, not the redacted
- *   placeholder
- *
- * **Common tasks**
- *
- * - Wrap a secret with {@link make}
- * - Check unknown input with {@link isRedacted}
- * - Recover the secret at a trusted boundary with {@link value}
- * - Remove the stored association with {@link wipeUnsafe}
- * - Compare redacted values with an underlying equivalence via
- *   {@link makeEquivalence}
- *
- * **Gotchas**
- *
- * - `Redacted` is not encryption and does not zero memory; it reduces
- *   accidental display of sensitive values
- * - Labels are visible in rendered output, so labels must not contain secrets
- * - After {@link wipeUnsafe}, calling {@link value} on the same wrapper fails
- *
- * **Example** (Rendering a redacted value)
- *
- * ```ts
- * import { Redacted } from "effect"
- *
- * const token = Redacted.make("secret-token", { label: "api-token" })
- *
- * String(token) // "<redacted:api-token>"
- * Redacted.value(token) // "secret-token"
- * ```
+ * Wraps sensitive values so normal output does not reveal them.
+ *
+ * A `Redacted<A>` shows a redacted placeholder in string, JSON, and inspection
+ * output, while still storing the original value for trusted code that needs to
+ * recover it. This helps reduce accidental leaks in logs and diagnostics. This
+ * module includes constructors, runtime checks, value recovery, wiping of stored
+ * values, and comparison helpers that avoid exposing the wrapped value at the
+ * call site.
  *
  * @since 3.3.0
  */

package/src/Reducer.ts

@@ -1,68 +1,9 @@
 /**
- * A module for reducing collections of values into a single result.
- *
- * A `Reducer<A>` extends {@link Combiner.Combiner} by adding an
- * `initialValue` (identity element) and a `combineAll` method that folds an
- * entire collection. Think `Array.prototype.reduce`, but packaged as a
- * reusable, composable value.
- *
- * ## Mental model
- *
- * - **Reducer** – a {@link Combiner.Combiner} plus an `initialValue` and a
- *   `combineAll` method.
- * - **initialValue** – the neutral/identity element. Combining any value with
- *   `initialValue` should return the original value unchanged (e.g. `0` for
- *   addition, `""` for string concatenation).
- * - **combineAll** – folds an `Iterable<A>` starting from `initialValue`.
- *   When omitted from {@link make}, a default left-to-right fold is used.
- * - **Purity** – all reducers produced by this module are pure; they never
- *   mutate their arguments.
- * - **Composability** – reducers can be lifted into `Option`, `Struct`,
- *   `Tuple`, `Record`, and other container types via helpers in those modules.
- * - **Subtype of Combiner** – every `Reducer` is also a valid
- *   `Combiner`, so you can pass a `Reducer` anywhere a `Combiner` is
- *   expected.
- *
- * ## Common tasks
- *
- * - Create a reducer from a combine function and initial value → {@link make}
- * - Swap argument order → {@link flip}
- * - Combine two values without an initial value → use {@link Combiner.Combiner}
- *   instead
- *
- * ## Gotchas
- *
- * - `combineAll` on an empty iterable returns `initialValue`, not an error.
- * - The default `combineAll` folds left-to-right. If your `combine` is not
- *   associative, order matters. Pass a custom `combineAll` to {@link make} if
- *   you need different traversal or short-circuiting.
- * - A `Reducer` is also a valid `Combiner` — but a `Combiner` is *not* a
- *   `Reducer` (it lacks `initialValue`).
- *
- * ## Quickstart
- *
- * **Example** (summing a list of numbers)
- *
- * ```ts
- * import { Reducer } from "effect"
- *
- * const Sum = Reducer.make<number>((a, b) => a + b, 0)
- *
- * console.log(Sum.combine(3, 4))
- * // Output: 7
- *
- * console.log(Sum.combineAll([1, 2, 3, 4]))
- * // Output: 10
- *
- * console.log(Sum.combineAll([]))
- * // Output: 0
- * ```
- *
- * ## See also
- *
- * - {@link make} – the primary constructor
- * - {@link Reducer} – the core interface
- * - {@link Combiner.Combiner} – the parent interface (no `initialValue`)
+ * Reusable strategies for reducing many values into one value. A `Reducer<A>`
+ * extends `Combiner.Combiner` with an `initialValue` for empty collections and
+ * a `combineAll` method for folding an entire iterable. This module provides a
+ * constructor for reducers and a helper for reversing the order in which values
+ * are combined.
  *
  * @since 4.0.0
  */

package/src/Ref.ts

@@ -1,53 +1,12 @@
 /**
- * The `Ref` module provides fiber-safe mutable references for state inside
- * Effect programs. A `Ref<A>` holds one value of type `A` and exposes reads,
- * writes, and atomic transformations as effects, so state changes compose with
- * Effect's concurrency model.
- *
- * **Mental model**
- *
- * - {@link make} creates a reference with an initial value
- * - {@link get} reads the current value, and {@link set} replaces it
- * - {@link update}, {@link updateAndGet}, and {@link getAndUpdate} transform
- *   the current value atomically
- * - {@link modify} updates the value and returns a separate result computed
- *   from the previous value
- * - The `Some` variants use `Option` to leave the value unchanged when a
- *   partial update does not apply
- *
- * **Common tasks**
- *
- * - Create refs: {@link make}, {@link makeUnsafe}
- * - Read and write: {@link get}, {@link set}, {@link getAndSet},
- *   {@link setAndGet}
- * - Update state: {@link update}, {@link updateAndGet}, {@link getAndUpdate}
- * - Update conditionally: {@link updateSome}, {@link updateSomeAndGet},
- *   {@link getAndUpdateSome}, {@link modifySome}
- * - Compute while updating: {@link modify}
- *
- * **Example** (Updating shared state)
- *
- * ```ts
- * import { Effect, Ref } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const counter = yield* Ref.make(0)
- *
- *   const next = yield* Ref.updateAndGet(counter, (n) => n + 1)
- *   const label = yield* Ref.modify(counter, (n) => [`count=${n}`, n + 1])
- *
- *   return { label, next }
- * })
- * ```
- *
- * **Gotchas**
- *
- * - Each `Ref` operation is atomic for that reference, but multiple refs are
- *   not updated transactionally as a group
- * - If the new value depends on the old value, prefer {@link update} or
- *   {@link modify} over a separate {@link get} followed by {@link set}
- * - Unsafe operations are synchronous low-level accessors; prefer effectful
- *   operations in application code
+ * Stores fiber-safe mutable state inside Effect programs.
+ *
+ * A `Ref<A>` holds one value and exposes reads, writes, and atomic
+ * transformations as effects, so state changes compose with Effect's
+ * concurrency model. This module includes constructors, safe and unsafe reads,
+ * set and get-and-set helpers, update and modify helpers, and conditional
+ * update variants that leave the value unchanged when an `Option.none` result
+ * is returned.
  *
  * @since 2.0.0
  */

package/src/References.ts

@@ -9,55 +9,6 @@
  * providing a new value changes behavior for the provided effect and the fibers
  * it starts.
  *
- * **Mental model**
- *
- * - Each exported value is a context key with a runtime default, so it can be
- *   read even when application code has not provided an override.
- * - Runtime services such as logging, tracing, scheduling, and concurrency
- *   controls read these keys from the current context.
- * - `Effect.provideService` overrides a reference for a specific effect scope;
- *   it does not mutate a process-wide global.
- * - Child fibers inherit the context active at the point they are started.
- *
- * **Common tasks**
- *
- * - Limit default concurrency with {@link CurrentConcurrency}.
- * - Control log severity and filtering with {@link CurrentLogLevel},
- *   {@link MinimumLogLevel}, and {@link UnhandledLogLevel}.
- * - Attach log metadata with {@link CurrentLogAnnotations} and
- *   {@link CurrentLogSpans}, or replace the active loggers with
- *   {@link CurrentLoggers}.
- * - Configure tracing with {@link Tracer}, {@link TracerEnabled},
- *   {@link TracerTimingEnabled}, {@link TracerSpanAnnotations}, and
- *   {@link TracerSpanLinks}.
- * - Tune scheduler behavior with {@link Scheduler}, {@link MaxOpsBeforeYield},
- *   and {@link PreventSchedulerYield}.
- *
- * **Example** (Providing a runtime reference)
- *
- * ```ts
- * import { Effect, References } from "effect"
- *
- * const readConcurrency = Effect.gen(function*() {
- *   return yield* References.CurrentConcurrency
- * })
- *
- * const limited = Effect.provideService(
- *   readConcurrency,
- *   References.CurrentConcurrency,
- *   4
- * )
- * ```
- *
- * **Gotchas**
- *
- * - Prefer higher-level logging, tracing, and concurrency APIs when they fit;
- *   this module is for direct access to the runtime knobs they use.
- * - `CurrentLogLevel` chooses the severity assigned to ordinary log entries,
- *   while `MinimumLogLevel` decides which entries are filtered out.
- * - References are context values, so scoped overrides end when the provided
- *   effect completes.
- *
  * @since 4.0.0
  */
 import type * as Context from "./Context.ts"

package/src/RegExp.ts

@@ -8,32 +8,6 @@
  * data-driven text, check whether an unknown value is already a `RegExp`, or
  * access the native constructor without leaving the Effect namespace.
  *
- * **Common tasks**
- *
- * - Construct expressions with the native constructor: {@link RegExp}
- * - Narrow unknown input to `RegExp`: {@link isRegExp}
- * - Escape literal text before interpolating it into a pattern: {@link escape}
- *
- * **Gotchas**
- *
- * - {@link escape} only escapes regular expression metacharacters in a string.
- *   It does not add anchors, flags, grouping, or validation for a full pattern.
- *
- * **Quickstart**
- *
- * **Example** (Matching literal text)
- *
- * ```ts
- * import { RegExp } from "effect"
- *
- * const literal = "a+b.txt"
- * const expression = new RegExp.RegExp(`^${RegExp.escape(literal)}$`)
- *
- * console.log(expression.test("a+b.txt")) // true
- * console.log(expression.test("aaab.txt")) // false
- * console.log(RegExp.isRegExp(expression)) // true
- * ```
- *
  * @since 2.0.0
  */
 import * as predicate from "./Predicate.ts"

package/src/Request.ts

@@ -1,46 +1,11 @@
 /**
- * The `Request` module defines typed request values for data loading with
- * `Effect.request`. A request is a description of work, not the execution of
- * that work: it records the success type, typed error, service requirements,
- * and the fields needed by a resolver to perform one logical operation.
- *
- * Requests are designed to be paired with a `RequestResolver`, which receives
- * pending request entries, batches or caches them when possible, and completes
- * each entry with a result. This lets calling code ask for data declaratively
- * while resolver code owns the backend-specific loading logic.
- *
- * **Mental model**
- *
- * - `Request<A, E, R>` describes one operation that succeeds with `A`, fails
- *   with `E`, and may require services `R`
- * - Constructors such as {@link of}, {@link tagged}, {@link Class}, and
- *   {@link TaggedClass} attach the request marker and structural behavior
- *   expected by the request runtime
- * - A resolver receives {@link Entry} values; each entry contains the original
- *   request, the captured context, and a completion callback
- * - Completion helpers such as {@link succeed}, {@link fail},
- *   {@link failCause}, {@link complete}, and {@link completeEffect} turn
- *   resolver results into the `Exit` expected by the waiting fiber
- *
- * **Common tasks**
- *
- * - Define request shapes with {@link Request}, {@link Class}, or
- *   {@link TaggedClass}
- * - Build lightweight request constructors with {@link of} or {@link tagged}
- * - Check unknown values with {@link isRequest}
- * - Complete pending resolver entries with {@link succeed}, {@link fail},
- *   {@link failCause}, {@link complete}, or {@link completeEffect}
- * - Extract request type members with {@link Success}, {@link Error},
- *   {@link Services}, and {@link Result}
+ * Typed request values for data loading with `Effect.request`.
  *
- * **Gotchas**
- *
- * - Creating a request value does not run anything; it must be submitted with
- *   `Effect.request` and handled by a resolver
- * - Resolver implementations must complete every {@link Entry} they receive,
- *   otherwise the fiber waiting for that request will not receive a value
- * - Cached and deduplicated requests depend on request identity and structural
- *   equality, so include only stable fields that describe the logical operation
+ * A request describes one logical piece of work without performing it. It
+ * records the success type, typed error, service requirements, and fields a
+ * resolver needs to complete the request. Requests are paired with
+ * `RequestResolver`, which performs backend-specific loading and completes each
+ * pending request entry with a success, failure, cause, exit, or effect.
  *
  * @since 2.0.0
  */

package/src/RequestResolver.ts

@@ -1,46 +1,11 @@
 /**
- * The `RequestResolver` module provides the data-loading side of
- * `Effect.request`. A `Request` describes what a fiber needs, while a
- * `RequestResolver` describes how to collect, batch, execute, cache, trace,
- * and complete those requests.
- *
- * **Mental model**
- *
- * - A resolver receives one or more `Request.Entry` values and must complete
- *   each entry with either a success or failure
- * - Concurrent requests made with the same resolver can be gathered into a
- *   batch before the resolver is run
- * - Batch keys split pending requests into independent groups, which is useful
- *   when different backends, tenants, or query shapes must be resolved
- *   separately
- * - Delays and `batchN` tune how long requests are collected and how large
- *   each batch may become
- * - Resolvers can be wrapped with tracing, in-memory caching, cache services,
- *   and persistence without changing the request type
- *
- * **Common tasks**
- *
- * - Create a resolver from batch logic: {@link make}
- * - Create grouped batch logic: {@link makeGrouped} or {@link grouped}
- * - Create a resolver from pure logic: {@link fromFunction} or
- *   {@link fromFunctionBatched}
- * - Create a resolver from effectful logic: {@link fromEffect} or
- *   {@link fromEffectTagged}
- * - Control batching: {@link setDelay}, {@link setDelayEffect},
- *   {@link batchN}
- * - Add operational behavior: {@link around}, {@link race}, {@link withSpan}
- * - Reuse results: {@link withCache}, {@link asCache}, {@link persisted}
+ * Resolves data requests made with `Effect.request`.
  *
- * **Gotchas**
- *
- * - Every entry passed to a resolver must be completed; leaving an entry
- *   incomplete causes the waiting request to fail
- * - Batched result collections must line up with the input entries in order
- *   and length when using the batched helper constructors
- * - Grouping controls which requests share a resolver run; choose stable keys
- *   for requests that can safely be handled together
- * - Caching and persistence depend on request identity and the request's
- *   equality semantics, so model request values deliberately when cached
+ * A `Request` describes what a fiber needs, while a `RequestResolver` describes
+ * how to collect request entries, group them into batches, run backend work,
+ * and complete each waiting entry. This module includes constructors for common
+ * resolver shapes and tools for controlling batching, grouping, delays,
+ * tracing, caching, racing, hooks around resolver execution, and persistence.
  *
  * @since 2.0.0
  */

package/src/Resource.ts

@@ -1,35 +1,10 @@
 /**
- * The `Resource` module provides refreshable, scoped values. A
- * `Resource<A, E>` stores the latest successful or failed acquisition result and
- * can be read with {@link get}, refreshed manually with {@link refresh}, or
- * refreshed automatically with {@link auto}.
+ * Stores refreshable scoped values.
  *
- * **Mental model**
- *
- * - A `Resource` wraps an acquisition `Effect` whose result is kept in a
- *   `ScopedRef`
- * - Each refresh re-runs acquisition and replaces the stored `Exit`
- * - Replacing the stored value releases resources associated with the previous
- *   scoped value
- * - Reading a resource returns the current acquired value or fails with the
- *   current acquisition error
- *
- * **Common tasks**
- *
- * - Create a manually refreshed resource with {@link manual}
- * - Create a schedule-driven resource with {@link auto}
- * - Read the current value with {@link get}
- * - Force a reload with {@link refresh}
- * - Check whether an unknown value is a resource with {@link isResource}
- *
- * **Gotchas**
- *
- * - Creating a resource requires a `Scope`; when the scope closes, scoped
- *   values held by the resource are released
- * - Failed acquisitions are stored too, so subsequent {@link get} calls fail
- *   until a refresh succeeds
- * - Automatic refreshes run in the resource scope and stop when that scope is
- *   closed
+ * A `Resource<A, E>` keeps the latest successful or failed acquisition result.
+ * It can be read repeatedly, refreshed manually, or refreshed automatically on a
+ * schedule. Resource acquisition runs in a scope, so replacements and final
+ * cleanup release the resources owned by previous values.
  *
  * @since 2.0.0
  */

package/src/Result.ts

@@ -1,69 +1,11 @@
 /**
- * A synchronous, pure type for representing computations that can succeed
- * (`Success<A>`) or fail (`Failure<E>`). Unlike `Effect`, `Result` is
- * evaluated eagerly and carries no side effects.
- *
- * **Mental model**
- *
- * - `Result<A, E>` is a discriminated union: `Success<A, E> | Failure<A, E>`
- * - `Success` wraps a value of type `A`, accessed via `.success`
- * - `Failure` wraps an error of type `E`, accessed via `.failure`
- * - `Result` is a monad: chain operations with {@link flatMap}, compose pipelines with `pipe`
- * - All operations are pure and return new `Result` values; the input is never mutated
- * - `Result` is yieldable in `Effect.gen`, producing the inner value or short-circuiting on failure
- *
- * **Common tasks**
- *
- * - Create from a value: {@link succeed}, {@link fail}
- * - Create from nullable: {@link fromNullishOr}
- * - Create from Option: {@link fromOption}
- * - Create from throwing code: {@link try_ try}
- * - Create from predicate: {@link liftPredicate}
- * - Transform: {@link map}, {@link mapError}, {@link mapBoth}
- * - Unwrap: {@link getOrElse}, {@link getOrNull}, {@link getOrUndefined}, {@link getOrThrow}
- * - Pattern match: {@link match}
- * - Sequence: {@link flatMap}, {@link andThen}, {@link all}
- * - Recover: {@link orElse}
- * - Filter: {@link filterOrFail}
- * - Convert to Option: {@link getSuccess}, {@link getFailure}
- * - Generator syntax: {@link gen}
- * - Do notation: {@link Do}, {@link bind}, {@link let_ let}
- * - Check variant: {@link isResult}, {@link isSuccess}, {@link isFailure}
- *
- * **Gotchas**
- *
- * - `E` defaults to `never`, so `Result<number>` means a result that cannot fail
- * - {@link andThen} accepts a `Result`, a function returning a `Result`, a plain value, or a function returning a plain value; {@link flatMap} only accepts a function returning a `Result`
- * - {@link all} short-circuits on the first `Failure` and returns it; later elements are not inspected
- * - {@link getOrThrow} throws the raw failure value `E`; use {@link getOrThrowWith} for custom error objects
- * - {@link tap} runs a side-effect but does not change the result; its return value is ignored
- *
- * **Quickstart**
- *
- * **Example** (Parsing and validating with Result)
+ * Models a value that has already succeeded or failed.
  *
- * ```ts
- * import { Result } from "effect"
- *
- * const parse = (input: string): Result.Result<number, string> =>
- *   isNaN(Number(input))
- *     ? Result.fail("not a number")
- *     : Result.succeed(Number(input))
- *
- * const ensurePositive = (n: number): Result.Result<number, string> =>
- *   n > 0 ? Result.succeed(n) : Result.fail("not positive")
- *
- * const result = Result.flatMap(parse("42"), ensurePositive)
- *
- * console.log(Result.getOrElse(result, (err) => `Error: ${err}`))
- * // Output: 42
- * ```
- *
- * **See also**
- *
- * - {@link succeed} / {@link fail} to create values
- * - {@link match} to fold both branches
- * - {@link gen} for generator-based composition
+ * A `Result<A, E>` is `Success<A, E>` when a value is available and
+ * `Failure<A, E>` when an error is available. It is plain data, so inspecting
+ * or transforming it does not run side effects. This module includes helpers
+ * for creating, checking, mapping, combining, and extracting results, plus
+ * conversions to and from `Option` and nullable values.
  *
  * @since 4.0.0
  */