effect 4.0.0-beta.83 → 4.0.0-beta.84

package/dist/Data.d.ts

@@ -168,7 +168,7 @@ export declare namespace TaggedEnum {
      * `this["A"]`, `this["B"]`, etc. as placeholders for the generics. The
      * `Count` parameter declares how many generics are used (up to 4).
      *
-     * **Example** (Generic tagged enum)
+     * **Example** (Defining a generic tagged enum)
      *
      * ```ts
      * import { Data } from "effect"
@@ -289,7 +289,7 @@ export declare namespace TaggedEnum {
      *
      * Use to select one full tagged-union variant by its `_tag` value.
      *
-     * **Example** (extracting a variant type)
+     * **Example** (Extracting a variant type)
      *
      * ```ts
      * import type { Data } from "effect"
@@ -463,7 +463,7 @@ export declare namespace TaggedEnum {
  *   on the tag being globally unique and the value being produced by your
  *   constructors. For untrusted input, validate with the `Schema` module first.
  *
- * **Example** (Basic usage)
+ * **Example** (Creating and matching tagged enum values)
  *
  * ```ts
  * import { Data } from "effect"
@@ -488,7 +488,7 @@ export declare namespace TaggedEnum {
  * console.log(msg) // "/missing not found"
  * ```
  *
- * **Example** (Generic tagged enum)
+ * **Example** (Defining a generic tagged enum)
  *
  * ```ts
  * import { Data } from "effect"
@@ -536,7 +536,7 @@ export declare const taggedEnum: {
      *   on the tag being globally unique and the value being produced by your
      *   constructors. For untrusted input, validate with the `Schema` module first.
      *
-     * **Example** (Basic usage)
+     * **Example** (Creating and matching tagged enum values)
      *
      * ```ts
      * import { Data } from "effect"
@@ -561,7 +561,7 @@ export declare const taggedEnum: {
      * console.log(msg) // "/missing not found"
      * ```
      *
-     * **Example** (Generic tagged enum)
+     * **Example** (Defining a generic tagged enum)
      *
      * ```ts
      * import { Data } from "effect"
@@ -613,7 +613,7 @@ export declare const taggedEnum: {
      *   on the tag being globally unique and the value being produced by your
      *   constructors. For untrusted input, validate with the `Schema` module first.
      *
-     * **Example** (Basic usage)
+     * **Example** (Creating and matching tagged enum values)
      *
      * ```ts
      * import { Data } from "effect"
@@ -638,7 +638,7 @@ export declare const taggedEnum: {
      * console.log(msg) // "/missing not found"
      * ```
      *
-     * **Example** (Generic tagged enum)
+     * **Example** (Defining a generic tagged enum)
      *
      * ```ts
      * import { Data } from "effect"
@@ -690,7 +690,7 @@ export declare const taggedEnum: {
      *   on the tag being globally unique and the value being produced by your
      *   constructors. For untrusted input, validate with the `Schema` module first.
      *
-     * **Example** (Basic usage)
+     * **Example** (Creating and matching tagged enum values)
      *
      * ```ts
      * import { Data } from "effect"
@@ -715,7 +715,7 @@ export declare const taggedEnum: {
      * console.log(msg) // "/missing not found"
      * ```
      *
-     * **Example** (Generic tagged enum)
+     * **Example** (Defining a generic tagged enum)
      *
      * ```ts
      * import { Data } from "effect"
@@ -767,7 +767,7 @@ export declare const taggedEnum: {
      *   on the tag being globally unique and the value being produced by your
      *   constructors. For untrusted input, validate with the `Schema` module first.
      *
-     * **Example** (Basic usage)
+     * **Example** (Creating and matching tagged enum values)
      *
      * ```ts
      * import { Data } from "effect"
@@ -792,7 +792,7 @@ export declare const taggedEnum: {
      * console.log(msg) // "/missing not found"
      * ```
      *
-     * **Example** (Generic tagged enum)
+     * **Example** (Defining a generic tagged enum)
      *
      * ```ts
      * import { Data } from "effect"
@@ -844,7 +844,7 @@ export declare const taggedEnum: {
      *   on the tag being globally unique and the value being produced by your
      *   constructors. For untrusted input, validate with the `Schema` module first.
      *
-     * **Example** (Basic usage)
+     * **Example** (Creating and matching tagged enum values)
      *
      * ```ts
      * import { Data } from "effect"
@@ -869,7 +869,7 @@ export declare const taggedEnum: {
      * console.log(msg) // "/missing not found"
      * ```
      *
-     * **Example** (Generic tagged enum)
+     * **Example** (Defining a generic tagged enum)
      *
      * ```ts
      * import { Data } from "effect"
@@ -954,7 +954,7 @@ export declare const Error: new <A extends Record<string, any> = {}>(args: Types
  * The `_tag` is excluded from the constructor argument. Yielding an instance
  * inside `Effect.gen` fails the effect with this error.
  *
- * **Example** (Tag-based error recovery)
+ * **Example** (Recovering by tag)
  *
  * ```ts
  * import { Data, Effect } from "effect"

package/dist/Data.js

@@ -101,7 +101,7 @@ export const TaggedClass = tag => class extends Class {
  *   on the tag being globally unique and the value being produced by your
  *   constructors. For untrusted input, validate with the `Schema` module first.
  *
- * **Example** (Basic usage)
+ * **Example** (Creating and matching tagged enum values)
  *
  * ```ts
  * import { Data } from "effect"
@@ -126,7 +126,7 @@ export const TaggedClass = tag => class extends Class {
  * console.log(msg) // "/missing not found"
  * ```
  *
- * **Example** (Generic tagged enum)
+ * **Example** (Defining a generic tagged enum)
  *
  * ```ts
  * import { Data } from "effect"
@@ -229,7 +229,7 @@ export const Error = core.Error;
  * The `_tag` is excluded from the constructor argument. Yielding an instance
  * inside `Effect.gen` fails the effect with this error.
  *
- * **Example** (Tag-based error recovery)
+ * **Example** (Recovering by tag)
  *
  * ```ts
  * import { Data, Effect } from "effect"

package/dist/DateTime.d.ts

@@ -2974,7 +2974,7 @@ export declare const mapEpochMillis: {
  * `DateTime.Zoned` values. Use `DateTime.withDateUtc` when the callback should
  * receive the UTC instant.
  *
- * **Example** (Using time zone adjusted Dates)
+ * **Example** (Applying time zone adjusted Dates)
  *
  * ```ts
  * import { DateTime } from "effect"
@@ -2999,7 +2999,7 @@ export declare const withDate: {
      * `DateTime.Zoned` values. Use `DateTime.withDateUtc` when the callback should
      * receive the UTC instant.
      *
-     * **Example** (Using time zone adjusted Dates)
+     * **Example** (Applying time zone adjusted Dates)
      *
      * ```ts
      * import { DateTime } from "effect"
@@ -3024,7 +3024,7 @@ export declare const withDate: {
      * `DateTime.Zoned` values. Use `DateTime.withDateUtc` when the callback should
      * receive the UTC instant.
      *
-     * **Example** (Using time zone adjusted Dates)
+     * **Example** (Applying time zone adjusted Dates)
      *
      * ```ts
      * import { DateTime } from "effect"
@@ -3049,7 +3049,7 @@ export declare const withDate: {
  * This ignores any associated time zone. Use `DateTime.withDate` when the
  * callback should receive the time-zone-adjusted wall-clock date.
  *
- * **Example** (Using UTC Dates)
+ * **Example** (Applying UTC Dates)
  *
  * ```ts
  * import { DateTime } from "effect"
@@ -3073,7 +3073,7 @@ export declare const withDateUtc: {
      * This ignores any associated time zone. Use `DateTime.withDate` when the
      * callback should receive the time-zone-adjusted wall-clock date.
      *
-     * **Example** (Using UTC Dates)
+     * **Example** (Applying UTC Dates)
      *
      * ```ts
      * import { DateTime } from "effect"
@@ -3097,7 +3097,7 @@ export declare const withDateUtc: {
      * This ignores any associated time zone. Use `DateTime.withDate` when the
      * callback should receive the time-zone-adjusted wall-clock date.
      *
-     * **Example** (Using UTC Dates)
+     * **Example** (Applying UTC Dates)
      *
      * ```ts
      * import { DateTime } from "effect"

package/dist/DateTime.js

@@ -1554,7 +1554,7 @@ export const mapEpochMillis = Internal.mapEpochMillis;
  * `DateTime.Zoned` values. Use `DateTime.withDateUtc` when the callback should
  * receive the UTC instant.
  *
- * **Example** (Using time zone adjusted Dates)
+ * **Example** (Applying time zone adjusted Dates)
  *
  * ```ts
  * import { DateTime } from "effect"
@@ -1578,7 +1578,7 @@ export const withDate = Internal.withDate;
  * This ignores any associated time zone. Use `DateTime.withDate` when the
  * callback should receive the time-zone-adjusted wall-clock date.
  *
- * **Example** (Using UTC Dates)
+ * **Example** (Applying UTC Dates)
  *
  * ```ts
  * import { DateTime } from "effect"

package/dist/Duration.d.ts

@@ -304,7 +304,7 @@ export declare const negate: (self: Duration) => Duration;
 /**
  * A Duration representing zero time.
  *
- * **Example** (Using the zero duration)
+ * **Example** (Referencing the zero duration)
  *
  * ```ts
  * import { Duration } from "effect"
@@ -319,7 +319,7 @@ export declare const zero: Duration;
 /**
  * A Duration representing infinite time.
  *
- * **Example** (Using infinite duration)
+ * **Example** (Referencing infinite duration)
  *
  * ```ts
  * import { Duration } from "effect"
@@ -334,7 +334,7 @@ export declare const infinity: Duration;
 /**
  * A Duration representing negative infinite time.
  *
- * **Example** (Using negative infinite duration)
+ * **Example** (Referencing negative infinite duration)
  *
  * ```ts
  * import { Duration } from "effect"

package/dist/Duration.js

@@ -424,7 +424,7 @@ export const negate = self => {
 /**
  * A Duration representing zero time.
  *
- * **Example** (Using the zero duration)
+ * **Example** (Referencing the zero duration)
  *
  * ```ts
  * import { Duration } from "effect"
@@ -439,7 +439,7 @@ export const zero = /*#__PURE__*/make(0);
 /**
  * A Duration representing infinite time.
  *
- * **Example** (Using infinite duration)
+ * **Example** (Referencing infinite duration)
  *
  * ```ts
  * import { Duration } from "effect"
@@ -454,7 +454,7 @@ export const infinity = /*#__PURE__*/make(Infinity);
 /**
  * A Duration representing negative infinite time.
  *
- * **Example** (Using negative infinite duration)
+ * **Example** (Referencing negative infinite duration)
  *
  * ```ts
  * import { Duration } from "effect"

package/dist/Effect.d.ts

@@ -1150,8 +1150,8 @@ export declare const whileLoop: <A, E, R>(options: {
  */
 export declare const promise: <A>(evaluate: (signal: AbortSignal) => PromiseLike<A>) => Effect<A>;
 /**
- * Creates an `Effect` that represents an asynchronous computation that might
- * fail.
+ * Creates an `Effect` from an asynchronous computation that may throw or
+ * reject, mapping failures into the error channel.
  *
  * **When to use**
  *
@@ -1161,19 +1161,24 @@ export declare const promise: <A>(evaluate: (signal: AbortSignal) => PromiseLike
  *
  * **Details**
  *
- * Error Handling:
+ * The promise thunk is evaluated when the effect runs. If it returns a promise
+ * that resolves, the resolved value becomes the success value. If the thunk
+ * throws before returning a promise, or if the returned promise rejects, the
+ * thrown or rejected value is mapped into the error channel.
  *
- * There are two ways to handle errors with `tryPromise`:
+ * Passing the thunk directly maps failures to {@link Cause.UnknownError}.
+ * Passing `{ try, catch }` uses `catch` to map failures to an error of type
+ * `E`.
  *
- * 1. If you don't provide a `catch` function, the error is caught and the
- *    effect fails with an `UnknownError`.
- * 2. If you provide a `catch` function, the error is caught and the `catch`
- *    function maps it to an error of type `E`.
+ * The thunk receives an `AbortSignal` that is aborted if the effect is
+ * interrupted. The underlying asynchronous operation only stops if it observes
+ * that signal.
  *
- * Interruptions:
+ * **Gotchas**
  *
- * An optional `AbortSignal` can be provided to allow for interruption of the
- * wrapped `Promise` API.
+ * If `catch` throws while mapping the error, that thrown value is treated as a
+ * defect. Return the error value you want in the error channel instead of
+ * throwing it.
  *
  * **Example** (Wrapping a fetch request that may fail)
  *
@@ -1982,7 +1987,7 @@ export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Ef
  * The error channel of the resulting effect is of type `never`, indicating that
  * it cannot recover from this failure.
  *
- * **Example** (Failing when division by zero)
+ * **Example** (Failing on division by zero)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -2006,52 +2011,53 @@ export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Ef
  * @since 2.0.0
  */
 export declare const die: (defect: unknown) => Effect<never>;
-declare const try_: <A, E>(options: {
-    try: LazyArg<A>;
-    catch: (error: unknown) => E;
-}) => Effect<A, E>;
+declare const try_: <A, E = Cause.UnknownError>(options: {
+    readonly try: LazyArg<A>;
+    readonly catch: (error: unknown) => E;
+} | LazyArg<A>) => Effect<A, E>;
 export { 
 /**
- * Creates an `Effect` that represents a synchronous computation that might
- * fail.
+ * Creates an `Effect` from a synchronous computation that may throw, mapping
+ * thrown values into the error channel.
  *
  * **When to use**
  *
  * Use when you need to perform synchronous operations that might throw, such
- * as parsing JSON, and convert thrown exceptions into typed Effect failures.
+ * as parsing JSON, and want thrown exceptions captured as Effect errors.
  *
  * **Details**
  *
- * Error Handling:
+ * The thunk is evaluated when the effect runs. If it returns normally, the
+ * returned value becomes the success value. If it throws, the thrown value is
+ * mapped into the error channel.
  *
- * There are two ways to handle errors with `try`:
+ * Passing the thunk directly maps failures to {@link Cause.UnknownError}.
+ * Passing `{ try, catch }` uses `catch` to map failures to an error of type
+ * `E`.
  *
- * 1. If you don't provide a `catch` function, the error is caught and the
- *    effect fails with an `UnknownError`.
- * 2. If you provide a `catch` function, the error is caught and the `catch`
- *    function maps it to an error of type `E`.
+ * **Gotchas**
+ *
+ * If `catch` throws while mapping the error, that thrown value is treated as
+ * a defect. Return the error value you want in the error channel instead of
+ * throwing it.
  *
- * **Example** (Parsing JSON with typed error mapping)
+ * **Example** (Parsing JSON)
  *
  * ```ts
  * import { Effect } from "effect"
  *
  * const parseJSON = (input: string) =>
- *   Effect.try({
- *     try: () => JSON.parse(input),
- *     catch: (error) => error as Error
- *   })
+ *   Effect.try(() => JSON.parse(input))
  *
  * // Success case
  * Effect.runPromise(parseJSON("{\"name\": \"Alice\"}")).then(console.log)
  * // Output: { name: "Alice" }
  *
- * // Failure case
+ * // Failure case maps the thrown value to UnknownError
  * Effect.runPromiseExit(parseJSON("invalid json")).then(console.log)
- * // Output: Exit.failure with Error
  * ```
  *
- * **Example** (Mapping synchronous exceptions to a tagged error)
+ * **Example** (Mapping exceptions to a tagged error)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -2192,6 +2198,39 @@ export declare const fromResult: <A, E>(result: Result.Result<A, E>) => Effect<A
  * @since 4.0.0
  */
 export declare const fromOption: <A>(option: Option<A>) => Effect<A, Cause.NoSuchElementError>;
+/**
+ * Converts an `Option` of an `Effect` into an `Effect` of an `Option`.
+ *
+ * **When to use**
+ *
+ * Use when an effect should run only when an optional value is present, while
+ * preserving absence as a successful `None`.
+ *
+ * **Details**
+ *
+ * - `None` becomes an effect that succeeds with `None`
+ * - `Some(effect)` runs the inner effect and wraps its success value in `Some`
+ * - Inner failures are preserved in the resulting effect
+ *
+ * **Example** (Transposing an Option of an Effect)
+ *
+ * ```ts
+ * import { Effect, Option } from "effect"
+ *
+ * const some = Option.some(Effect.succeed(42))
+ *
+ * //      ┌─── Effect<Option<number>, never, never>
+ * //      ▼
+ * const program = Effect.transposeOption(some)
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // Output: { _id: 'Option', _tag: 'Some', value: 42 }
+ * ```
+ *
+ * @category converting
+ * @since 3.13.0
+ */
+export declare const transposeOption: <A = never, E = never, R = never>(self: Option<Effect<A, E, R>>) => Effect<Option<A>, E, R>;
 /**
  * Converts a nullable value to an `Effect`, failing with a `NoSuchElementError`
  * when the value is `null` or `undefined`.
@@ -2238,7 +2277,7 @@ export declare const fromNullishOr: <A>(value: A) => Effect<NonNullable<A>, Caus
  * Since effects are immutable, `flatMap` always returns a new effect instead of
  * changing the original one.
  *
- * **Example** (Syntax)
+ * **Example** (Choosing flatMap syntax variants)
  *
  * ```ts
  * import { Effect, pipe } from "effect"
@@ -2305,7 +2344,7 @@ export declare const flatMap: {
      * Since effects are immutable, `flatMap` always returns a new effect instead of
      * changing the original one.
      *
-     * **Example** (Syntax)
+     * **Example** (Choosing flatMap syntax variants)
      *
      * ```ts
      * import { Effect, pipe } from "effect"
@@ -2372,7 +2411,7 @@ export declare const flatMap: {
      * Since effects are immutable, `flatMap` always returns a new effect instead of
      * changing the original one.
      *
-     * **Example** (Syntax)
+     * **Example** (Choosing flatMap syntax variants)
      *
      * ```ts
      * import { Effect, pipe } from "effect"
@@ -2460,7 +2499,7 @@ export declare const flatten: <A, E, R, E2, R2>(self: Effect<Effect<A, E, R>, E2
  * Failures or requirements from either effect are preserved in the returned
  * effect.
  *
- * **Example** (Syntax)
+ * **Example** (Choosing andThen syntax variants)
  *
  * ```ts
  * import { Effect, pipe } from "effect"
@@ -2536,7 +2575,7 @@ export declare const andThen: {
      * Failures or requirements from either effect are preserved in the returned
      * effect.
      *
-     * **Example** (Syntax)
+     * **Example** (Choosing andThen syntax variants)
      *
      * ```ts
      * import { Effect, pipe } from "effect"
@@ -2612,7 +2651,7 @@ export declare const andThen: {
      * Failures or requirements from either effect are preserved in the returned
      * effect.
      *
-     * **Example** (Syntax)
+     * **Example** (Choosing andThen syntax variants)
      *
      * ```ts
      * import { Effect, pipe } from "effect"
@@ -2688,7 +2727,7 @@ export declare const andThen: {
      * Failures or requirements from either effect are preserved in the returned
      * effect.
      *
-     * **Example** (Syntax)
+     * **Example** (Choosing andThen syntax variants)
      *
      * ```ts
      * import { Effect, pipe } from "effect"
@@ -2764,7 +2803,7 @@ export declare const andThen: {
      * Failures or requirements from either effect are preserved in the returned
      * effect.
      *
-     * **Example** (Syntax)
+     * **Example** (Choosing andThen syntax variants)
      *
      * ```ts
      * import { Effect, pipe } from "effect"
@@ -3250,7 +3289,7 @@ export declare const exit: <A, E, R>(self: Effect<A, E, R>) => Effect<Exit.Exit<
  * effect is not modified. Instead, a new effect is returned with the updated
  * value.
  *
- * **Example** (Syntax)
+ * **Example** (Choosing map syntax variants)
  *
  * ```ts
  * import { Effect, pipe } from "effect"
@@ -3306,7 +3345,7 @@ export declare const map: {
      * effect is not modified. Instead, a new effect is returned with the updated
      * value.
      *
-     * **Example** (Syntax)
+     * **Example** (Choosing map syntax variants)
      *
      * ```ts
      * import { Effect, pipe } from "effect"
@@ -3362,7 +3401,7 @@ export declare const map: {
      * effect is not modified. Instead, a new effect is returned with the updated
      * value.
      *
-     * **Example** (Syntax)
+     * **Example** (Choosing map syntax variants)
      *
      * ```ts
      * import { Effect, pipe } from "effect"
@@ -11965,7 +12004,7 @@ export declare const acquireDisposable: <A extends AsyncDisposable | Disposable,
  * is not desired, errors produced by the `release` `Effect` value can be caught
  * and ignored.
  *
- * **Example** (Using a resource with cleanup)
+ * **Example** (Acquiring resources with cleanup)
  *
  * ```ts
  * import { Console, Effect, Exit } from "effect"