effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/Request.ts

@@ -449,8 +449,8 @@ export const TaggedClass = <Tag extends string>(
  *
  * **When to use**
  *
- * Use to finish a `Request.Entry` when you already have the request's final
- * `Exit` result.
+ * Use when you need to finish a `Request.Entry` with a prebuilt final `Exit`
+ * result.
  *
  * @see {@link completeEffect} for completing an entry from an effect that may succeed or fail
  * @see {@link succeed} for completing an entry with a successful value
@@ -466,8 +466,8 @@ export const complete: {
    *
    * **When to use**
    *
-   * Use to finish a `Request.Entry` when you already have the request's final
-   * `Exit` result.
+   * Use when you need to finish a `Request.Entry` with a prebuilt final `Exit`
+   * result.
    *
    * @see {@link completeEffect} for completing an entry from an effect that may succeed or fail
    * @see {@link succeed} for completing an entry with a successful value
@@ -483,8 +483,8 @@ export const complete: {
    *
    * **When to use**
    *
-   * Use to finish a `Request.Entry` when you already have the request's final
-   * `Exit` result.
+   * Use when you need to finish a `Request.Entry` with a prebuilt final `Exit`
+   * result.
    *
    * @see {@link completeEffect} for completing an entry from an effect that may succeed or fail
    * @see {@link succeed} for completing an entry with a successful value
@@ -649,8 +649,8 @@ export const fail: {
  *
  * **When to use**
  *
- * Use when a `RequestResolver` needs to complete an entry with structured cause
- * information rather than only the request's typed error value.
+ * Use when you need a `RequestResolver` to complete an entry with structured
+ * cause information rather than only the request's typed error value.
  *
  * @see {@link fail} for completing an entry with a typed error value
  * @see {@link complete} for completing an entry with an existing `Exit`
@@ -666,8 +666,8 @@ export const failCause: {
    *
    * **When to use**
    *
-   * Use when a `RequestResolver` needs to complete an entry with structured cause
-   * information rather than only the request's typed error value.
+   * Use when you need a `RequestResolver` to complete an entry with structured
+   * cause information rather than only the request's typed error value.
    *
    * @see {@link fail} for completing an entry with a typed error value
    * @see {@link complete} for completing an entry with an existing `Exit`
@@ -683,8 +683,8 @@ export const failCause: {
    *
    * **When to use**
    *
-   * Use when a `RequestResolver` needs to complete an entry with structured cause
-   * information rather than only the request's typed error value.
+   * Use when you need a `RequestResolver` to complete an entry with structured
+   * cause information rather than only the request's typed error value.
    *
    * @see {@link fail} for completing an entry with a typed error value
    * @see {@link complete} for completing an entry with an existing `Exit`
@@ -706,8 +706,8 @@ export const failCause: {
  *
  * **When to use**
  *
- * Use to finish a `Request.Entry` when you have a successful value for the
- * request.
+ * Use when you need to finish a `Request.Entry` with a successful request
+ * value.
  *
  * @see {@link complete} for completing an entry with a prebuilt `Exit`
  * @see {@link completeEffect} for completing an entry from an effect result
@@ -723,8 +723,8 @@ export const succeed: {
    *
    * **When to use**
    *
-   * Use to finish a `Request.Entry` when you have a successful value for the
-   * request.
+   * Use when you need to finish a `Request.Entry` with a successful request
+   * value.
    *
    * @see {@link complete} for completing an entry with a prebuilt `Exit`
    * @see {@link completeEffect} for completing an entry from an effect result
@@ -740,8 +740,8 @@ export const succeed: {
    *
    * **When to use**
    *
-   * Use to finish a `Request.Entry` when you have a successful value for the
-   * request.
+   * Use when you need to finish a `Request.Entry` with a successful request
+   * value.
    *
    * @see {@link complete} for completing an entry with a prebuilt `Exit`
    * @see {@link completeEffect} for completing an entry from an effect result

package/src/Resource.ts

@@ -113,8 +113,8 @@ const makeUnsafe = <A, E>(
  *
  * **When to use**
  *
- * Use when you need to control the timing of resource refreshes yourself rather
- * than relying on an automatic schedule.
+ * Use when you need manual control over resource refresh timing rather than an
+ * automatic schedule.
  *
  * @see {@link auto} for schedule-driven automatic refreshes
  * @see {@link refresh} to manually trigger a resource refresh

package/src/Result.ts

@@ -89,6 +89,11 @@ const TypeId = "~effect/data/Result"
 /**
  * A value that is either `Success<A, E>` or `Failure<A, E>`.
  *
+ * **When to use**
+ *
+ * Use when both success and failure should remain available as data and
+ * `Option` would lose failure information.
+ *
  * **Details**
  *
  * - Use {@link succeed} / {@link fail} to construct
@@ -341,7 +346,7 @@ export const succeed: <A>(right: A) => Result<A> = result.succeed
  *
  * **When to use**
  *
- * Use to represent a failed computation with a typed failure value.
+ * Use to represent a failed `Result` with a typed failure value.
  *
  * **Details**
  *
@@ -373,8 +378,8 @@ export {
    *
    * **When to use**
    *
-   * Use when a success should signal completion without carrying a meaningful
-   * value.
+   * Use when you need a successful `Result` value that signals completion
+   * without carrying meaningful data.
    *
    * **Details**
    *
@@ -405,8 +410,8 @@ export {
  *
  * **When to use**
  *
- * Use when a failure should act only as a control signal and no failure value
- * is needed.
+ * Use when you need a failed `Result` value that acts only as a control signal
+ * without failure data.
  *
  * **Details**
  *
@@ -437,9 +442,8 @@ export const failVoid: Result<never, void> = fail(void 0)
  *
  * **When to use**
  *
- * Use when an input may be `null` or `undefined` and absence should be
- * represented as a `Failure` while present values should remain available as
- * `Success`.
+ * Use when you need `null` or `undefined` input to become a `Failure` while
+ * present values remain available as `Success`.
  *
  * **Details**
  *
@@ -472,9 +476,8 @@ export const fromNullishOr: {
    *
    * **When to use**
    *
-   * Use when an input may be `null` or `undefined` and absence should be
-   * represented as a `Failure` while present values should remain available as
-   * `Success`.
+   * Use when you need `null` or `undefined` input to become a `Failure` while
+   * present values remain available as `Success`.
    *
    * **Details**
    *
@@ -507,9 +510,8 @@ export const fromNullishOr: {
    *
    * **When to use**
    *
-   * Use when an input may be `null` or `undefined` and absence should be
-   * represented as a `Failure` while present values should remain available as
-   * `Success`.
+   * Use when you need `null` or `undefined` input to become a `Failure` while
+   * present values remain available as `Success`.
    *
    * **Details**
    *
@@ -821,7 +823,8 @@ export const isSuccess: <A, E>(self: Result<A, E>) => self is Success<A, E> = re
  *
  * **When to use**
  *
- * Use to extract only the success value and discard failure information.
+ * Use when you need to extract the success value from a `Result` as an
+ * `Option` and discard failure information.
  *
  * **Details**
  *
@@ -853,7 +856,8 @@ export const getSuccess: <A, E>(self: Result<A, E>) => Option<A> = result.getSuc
  *
  * **When to use**
  *
- * Use to extract only the failure value and discard successful values.
+ * Use when you need to extract the failure value from a `Result` as an
+ * `Option` and discard successful values.
  *
  * **Details**
  *
@@ -1265,12 +1269,16 @@ export const map: {
 /**
  * Folds a `Result` into a single value by applying one of two functions.
  *
+ * **When to use**
+ *
+ * Use when a `Result`'s success and failure branches should be collapsed into
+ * one plain output type.
+ *
  * **Details**
  *
  * - Applies `onSuccess` if the result is a `Success`
  * - Applies `onFailure` if the result is a `Failure`
  * - Both branches must return the same type (or a common supertype)
- * - Use when you need to "exit" the `Result` type and produce a plain value
  *
  * **Example** (Folding to a string)
  *
@@ -1299,12 +1307,16 @@ export const match: {
   /**
    * Folds a `Result` into a single value by applying one of two functions.
    *
+   * **When to use**
+   *
+   * Use when a `Result`'s success and failure branches should be collapsed into
+   * one plain output type.
+   *
    * **Details**
    *
    * - Applies `onSuccess` if the result is a `Success`
    * - Applies `onFailure` if the result is a `Failure`
    * - Both branches must return the same type (or a common supertype)
-   * - Use when you need to "exit" the `Result` type and produce a plain value
    *
    * **Example** (Folding to a string)
    *
@@ -1338,12 +1350,16 @@ export const match: {
   /**
    * Folds a `Result` into a single value by applying one of two functions.
    *
+   * **When to use**
+   *
+   * Use when a `Result`'s success and failure branches should be collapsed into
+   * one plain output type.
+   *
    * **Details**
    *
    * - Applies `onSuccess` if the result is a `Success`
    * - Applies `onFailure` if the result is a `Failure`
    * - Both branches must return the same type (or a common supertype)
-   * - Use when you need to "exit" the `Result` type and produce a plain value
    *
    * **Example** (Folding to a string)
    *
@@ -1938,7 +1954,8 @@ export const getOrElse: {
  *
  * **When to use**
  *
- * Use with APIs that represent absence as `null`.
+ * Use when you need to pass failed `Result` values to APIs that represent
+ * absence as `null`.
  *
  * **Details**
  *
@@ -1970,7 +1987,8 @@ export const getOrNull: <A, E>(self: Result<A, E>) => A | null = getOrElse(const
  *
  * **When to use**
  *
- * Use with APIs that represent absence as `undefined`.
+ * Use when you need to pass failed `Result` values to APIs that represent
+ * absence as `undefined`.
  *
  * **Details**
  *
@@ -2152,11 +2170,15 @@ export const getOrThrow: <A, E>(self: Result<A, E>) => A = getOrThrowWith(identi
  * Returns the original `Result` if it is a `Success`, otherwise applies
  * `that` to the error and returns the resulting `Result`.
  *
+ * **When to use**
+ *
+ * Use when a failure should recover into another `Result` while keeping
+ * successes unchanged.
+ *
  * **Details**
  *
  * - `Success<A>` is returned unchanged
  * - `Failure<E>` calls `that(e)` to produce a new `Result`
- * - Use to provide a recovery path or fallback computation on failure
  *
  * **Example** (Recovering from a failure)
  *
@@ -2182,11 +2204,15 @@ export const orElse: {
    * Returns the original `Result` if it is a `Success`, otherwise applies
    * `that` to the error and returns the resulting `Result`.
    *
+   * **When to use**
+   *
+   * Use when a failure should recover into another `Result` while keeping
+   * successes unchanged.
+   *
    * **Details**
    *
    * - `Success<A>` is returned unchanged
    * - `Failure<E>` calls `that(e)` to produce a new `Result`
-   * - Use to provide a recovery path or fallback computation on failure
    *
    * **Example** (Recovering from a failure)
    *
@@ -2212,11 +2238,15 @@ export const orElse: {
    * Returns the original `Result` if it is a `Success`, otherwise applies
    * `that` to the error and returns the resulting `Result`.
    *
+   * **When to use**
+   *
+   * Use when a failure should recover into another `Result` while keeping
+   * successes unchanged.
+   *
    * **Details**
    *
    * - `Success<A>` is returned unchanged
    * - `Failure<E>` calls `that(e)` to produce a new `Result`
-   * - Use to provide a recovery path or fallback computation on failure
    *
    * **Example** (Recovering from a failure)
    *
@@ -2920,8 +2950,8 @@ export const flip = <A, E>(self: Result<A, E>): Result<E, A> =>
  *
  * **When to use**
  *
- * Use when sequential `Result` composition is clearer with generator syntax
- * than nested `flatMap` calls.
+ * Use when you need generator syntax to compose sequential `Result`
+ * computations instead of nested `flatMap` calls.
  *
  * **Details**
  *
@@ -3015,8 +3045,9 @@ export const Do: Result<{}> = succeed({})
  *
  * **When to use**
  *
- * Use when adding a `Result`-producing step to a do-notation pipeline and
- * storing its successful value under a named field in the accumulated object.
+ * Use when you need to add a `Result`-producing step to a `Result`
+ * do-notation pipeline and store its successful value under a named field in
+ * the accumulated object.
  *
  * **Details**
  *
@@ -3052,8 +3083,9 @@ export const bind: {
    *
    * **When to use**
    *
-   * Use when adding a `Result`-producing step to a do-notation pipeline and
-   * storing its successful value under a named field in the accumulated object.
+   * Use when you need to add a `Result`-producing step to a `Result`
+   * do-notation pipeline and store its successful value under a named field in
+   * the accumulated object.
    *
    * **Details**
    *
@@ -3089,8 +3121,9 @@ export const bind: {
    *
    * **When to use**
    *
-   * Use when adding a `Result`-producing step to a do-notation pipeline and
-   * storing its successful value under a named field in the accumulated object.
+   * Use when you need to add a `Result`-producing step to a `Result`
+   * do-notation pipeline and store its successful value under a named field in
+   * the accumulated object.
    *
    * **Details**
    *
@@ -3249,7 +3282,8 @@ export {
    *
    * **When to use**
    *
-   * Use to add a pure computed field to a do-notation accumulator.
+   * Use when you need to add a derived field that cannot fail inside a
+   * do-notation pipeline.
    *
    * **Details**
    *
@@ -3283,6 +3317,11 @@ export {
 /**
  * Transforms `Option<Result<A, E>>` into `Result<Option<A>, E>`.
  *
+ * **When to use**
+ *
+ * Use when optional absence should be treated as a successful `None`, while an
+ * inner `Result` failure should still fail the whole result.
+ *
  * **Details**
  *
  * - `None` becomes `Success(None)`
@@ -3318,6 +3357,11 @@ export const transposeOption = <A = never, E = never>(
  * Maps an `Option` value with a `Result`-producing function, then transposes
  * the structure from `Option<Result<B, E>>` to `Result<Option<B>, E>`.
  *
+ * **When to use**
+ *
+ * Use when an optional value should be validated only when present, preserving
+ * absence as a successful `None`.
+ *
  * **Details**
  *
  * - `None` becomes `Success(None)` (the function is never called)
@@ -3351,6 +3395,11 @@ export const transposeMapOption = dual<
    * Maps an `Option` value with a `Result`-producing function, then transposes
    * the structure from `Option<Result<B, E>>` to `Result<Option<B>, E>`.
    *
+   * **When to use**
+   *
+   * Use when an optional value should be validated only when present, preserving
+   * absence as a successful `None`.
+   *
    * **Details**
    *
    * - `None` becomes `Success(None)` (the function is never called)
@@ -3384,6 +3433,11 @@ export const transposeMapOption = dual<
    * Maps an `Option` value with a `Result`-producing function, then transposes
    * the structure from `Option<Result<B, E>>` to `Result<Option<B>, E>`.
    *
+   * **When to use**
+   *
+   * Use when an optional value should be validated only when present, preserving
+   * absence as a successful `None`.
+   *
    * **Details**
    *
    * - `None` becomes `Success(None)` (the function is never called)

package/src/Runtime.ts

@@ -118,8 +118,8 @@ export interface Teardown {
  *
  * **When to use**
  *
- * Use as the standard teardown for main programs when you want conventional
- * process exit codes and support for {@link errorExitCode}.
+ * Use as the standard teardown for main programs with conventional process
+ * exit codes and support for {@link errorExitCode}.
  *
  * **Details**
  *
@@ -176,13 +176,16 @@ export const defaultTeardown: Teardown = <E, A>(
  *
  * **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.
+ * Use when building a runtime adapter for a host platform.
  *
  * **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.
+ * 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.
+ *
+ * Most applications should use a platform-provided runner, such as
+ * `NodeRuntime.runMain`, rather than constructing one directly.
  *
  * `disableErrorReporting` disables the automatic log emitted for unreported
  * non-interruption failures. It does not change exit-code calculation or the
@@ -403,8 +406,8 @@ export type errorReported = "~effect/Runtime/errorReported"
  *
  * **When to use**
  *
- * Use when error classes are already reported by application code and should
- * not be logged again by the default main runner.
+ * Use when you need error classes reported by application code to avoid being
+ * logged again by the default main runner.
  *
  * **Details**
  *