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

package/src/Deferred.ts

@@ -86,9 +86,11 @@ const TypeId = "~effect/Deferred"
  * once, with the ability for an arbitrary number of fibers to suspend (by
  * calling `Deferred.await`) and automatically resume when the variable is set.
  *
- * `Deferred` can be used for building primitive actions whose completions
- * require the coordinated action of multiple fibers, and for building
- * higher-level concurrent or asynchronous structures.
+ * **When to use**
+ *
+ * Use `Deferred` for primitive actions whose completions require the
+ * coordinated action of multiple fibers, and for building higher-level
+ * concurrent or asynchronous structures.
  *
  * **Example** (Creating a Deferred for inter-fiber communication)
  *
@@ -149,6 +151,8 @@ export declare namespace Deferred {
   /**
    * Type-level variance marker for the value and error channels of `Deferred`.
    *
+   * **Details**
+   *
    * This interface is part of the public type structure and is not intended to
    * be constructed directly.
    *
@@ -176,6 +180,8 @@ const DeferredProto = {
 /**
  * Synchronously creates an empty `Deferred` outside the `Effect` runtime.
  *
+ * **When to use**
+ *
  * Prefer `Deferred.make` in effectful code so allocation is represented in
  * `Effect`; use this only when direct synchronous allocation is required.
  *
@@ -256,18 +262,19 @@ export {
 }
 
 /**
- * Completes the `Deferred` with the supplied `Effect` without running or
- * memoizing it.
+ * Runs the supplied `Effect` and attempts to complete the `Deferred` with its
+ * memoized result.
  *
- * Awaiting fibers run the stored effect when they await, so repeated awaits can
- * repeat the effect. Returns `false` if the `Deferred` has already been
- * completed.
+ * **When to use**
  *
  * Use `Deferred.complete` when the effect should be evaluated once and the
- * resulting `Exit` memoized.
+ * resulting `Exit` memoized. Use `Deferred.completeWith` when you need to store
+ * an effect directly without memoizing its result.
  *
- * Note that `Deferred.completeWith` will be much faster, so consider using
- * that if you do not need to memoize the result of the specified effect.
+ * **Details**
+ *
+ * The returned effect succeeds with `true` when this call completed the
+ * `Deferred`, or `false` if it was already completed.
  *
  * **Example** (Completing a Deferred from an effect)
  *
@@ -289,18 +296,19 @@ export {
  */
 export const complete: {
   /**
-   * Completes the `Deferred` with the supplied `Effect` without running or
-   * memoizing it.
+   * Runs the supplied `Effect` and attempts to complete the `Deferred` with its
+   * memoized result.
    *
-   * Awaiting fibers run the stored effect when they await, so repeated awaits can
-   * repeat the effect. Returns `false` if the `Deferred` has already been
-   * completed.
+   * **When to use**
    *
    * Use `Deferred.complete` when the effect should be evaluated once and the
-   * resulting `Exit` memoized.
+   * resulting `Exit` memoized. Use `Deferred.completeWith` when you need to store
+   * an effect directly without memoizing its result.
+   *
+   * **Details**
    *
-   * Note that `Deferred.completeWith` will be much faster, so consider using
-   * that if you do not need to memoize the result of the specified effect.
+   * The returned effect succeeds with `true` when this call completed the
+   * `Deferred`, or `false` if it was already completed.
    *
    * **Example** (Completing a Deferred from an effect)
    *
@@ -322,18 +330,19 @@ export const complete: {
    */
   <A, E, R>(effect: Effect<A, E, R>): (self: Deferred<A, E>) => Effect<boolean, never, R>
   /**
-   * Completes the `Deferred` with the supplied `Effect` without running or
-   * memoizing it.
+   * Runs the supplied `Effect` and attempts to complete the `Deferred` with its
+   * memoized result.
    *
-   * Awaiting fibers run the stored effect when they await, so repeated awaits can
-   * repeat the effect. Returns `false` if the `Deferred` has already been
-   * completed.
+   * **When to use**
    *
    * Use `Deferred.complete` when the effect should be evaluated once and the
-   * resulting `Exit` memoized.
+   * resulting `Exit` memoized. Use `Deferred.completeWith` when you need to store
+   * an effect directly without memoizing its result.
    *
-   * Note that `Deferred.completeWith` will be much faster, so consider using
-   * that if you do not need to memoize the result of the specified effect.
+   * **Details**
+   *
+   * The returned effect succeeds with `true` when this call completed the
+   * `Deferred`, or `false` if it was already completed.
    *
    * **Example** (Completing a Deferred from an effect)
    *
@@ -506,6 +515,8 @@ export const done: {
 /**
  * Attempts to complete the `Deferred` with the specified error.
  *
+ * **Details**
+ *
  * Fibers waiting on the `Deferred` fail with that error only if this call
  * completes it. The returned effect succeeds with `true` when this call
  * completed the `Deferred`, or `false` if it was already completed.
@@ -529,6 +540,8 @@ export const fail: {
   /**
    * Attempts to complete the `Deferred` with the specified error.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` fail with that error only if this call
    * completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -552,6 +565,8 @@ export const fail: {
   /**
    * Attempts to complete the `Deferred` with the specified error.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` fail with that error only if this call
    * completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -578,6 +593,8 @@ export const fail: {
  * Computes an error when the returned effect is run, then attempts to complete
  * the `Deferred` with that error.
  *
+ * **Details**
+ *
  * Fibers waiting on the `Deferred` fail with the computed error only if this
  * call completes it. The returned effect succeeds with `true` when this call
  * completed the `Deferred`, or `false` if it was already completed.
@@ -602,6 +619,8 @@ export const failSync: {
    * Computes an error when the returned effect is run, then attempts to complete
    * the `Deferred` with that error.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` fail with the computed error only if this
    * call completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -626,6 +645,8 @@ export const failSync: {
    * Computes an error when the returned effect is run, then attempts to complete
    * the `Deferred` with that error.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` fail with the computed error only if this
    * call completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -655,6 +676,8 @@ export const failSync: {
 /**
  * Attempts to complete the `Deferred` with the specified `Cause`.
  *
+ * **Details**
+ *
  * Fibers waiting on the `Deferred` observe that cause only if this call
  * completes it. The returned effect succeeds with `true` when this call
  * completed the `Deferred`, or `false` if it was already completed.
@@ -681,6 +704,8 @@ export const failCause: {
   /**
    * Attempts to complete the `Deferred` with the specified `Cause`.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` observe that cause only if this call
    * completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -707,6 +732,8 @@ export const failCause: {
   /**
    * Attempts to complete the `Deferred` with the specified `Cause`.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` observe that cause only if this call
    * completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -739,6 +766,8 @@ export const failCause: {
  * Computes a `Cause` when the returned effect is run, then attempts to
  * complete the `Deferred` with that cause.
  *
+ * **Details**
+ *
  * Fibers waiting on the `Deferred` observe the computed cause only if this
  * call completes it. The returned effect succeeds with `true` when this call
  * completed the `Deferred`, or `false` if it was already completed.
@@ -766,6 +795,8 @@ export const failCauseSync: {
    * Computes a `Cause` when the returned effect is run, then attempts to
    * complete the `Deferred` with that cause.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` observe the computed cause only if this
    * call completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -793,6 +824,8 @@ export const failCauseSync: {
    * Computes a `Cause` when the returned effect is run, then attempts to
    * complete the `Deferred` with that cause.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` observe the computed cause only if this
    * call completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -825,6 +858,8 @@ export const failCauseSync: {
 /**
  * Attempts to complete the `Deferred` with a defect.
  *
+ * **Details**
+ *
  * Fibers waiting on the `Deferred` die with that defect only if this call
  * completes it. The returned effect succeeds with `true` when this call
  * completed the `Deferred`, or `false` if it was already completed.
@@ -851,6 +886,8 @@ export const die: {
   /**
    * Attempts to complete the `Deferred` with a defect.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` die with that defect only if this call
    * completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -877,6 +914,8 @@ export const die: {
   /**
    * Attempts to complete the `Deferred` with a defect.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` die with that defect only if this call
    * completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -906,6 +945,8 @@ export const die: {
  * Computes a defect when the returned effect is run, then attempts to complete
  * the `Deferred` with that defect.
  *
+ * **Details**
+ *
  * Fibers waiting on the `Deferred` die with the computed defect only if this
  * call completes it. The returned effect succeeds with `true` when this call
  * completed the `Deferred`, or `false` if it was already completed.
@@ -933,6 +974,8 @@ export const dieSync: {
    * Computes a defect when the returned effect is run, then attempts to complete
    * the `Deferred` with that defect.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` die with the computed defect only if this
    * call completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -960,6 +1003,8 @@ export const dieSync: {
    * Computes a defect when the returned effect is run, then attempts to complete
    * the `Deferred` with that defect.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` die with the computed defect only if this
    * call completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -992,6 +1037,8 @@ export const dieSync: {
 /**
  * Attempts to complete the `Deferred` with interruption by the current fiber.
  *
+ * **Details**
+ *
  * Fibers waiting on the `Deferred` are interrupted with the current fiber id
  * only if this call completes it. The returned effect succeeds with `true`
  * when this call completed the `Deferred`, or `false` if it was already
@@ -1019,6 +1066,8 @@ export const interrupt = <A, E>(self: Deferred<A, E>): Effect<boolean> =>
  * Attempts to complete the `Deferred` with interruption by the specified
  * `FiberId`.
  *
+ * **Details**
+ *
  * Fibers waiting on the `Deferred` are interrupted with that fiber id only if
  * this call completes it. The returned effect succeeds with `true` when this
  * call completed the `Deferred`, or `false` if it was already completed.
@@ -1043,6 +1092,8 @@ export const interruptWith: {
    * Attempts to complete the `Deferred` with interruption by the specified
    * `FiberId`.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` are interrupted with that fiber id only if
    * this call completes it. The returned effect succeeds with `true` when this
    * call completed the `Deferred`, or `false` if it was already completed.
@@ -1067,6 +1118,8 @@ export const interruptWith: {
    * Attempts to complete the `Deferred` with interruption by the specified
    * `FiberId`.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` are interrupted with that fiber id only if
    * this call completes it. The returned effect succeeds with `true` when this
    * call completed the `Deferred`, or `false` if it was already completed.
@@ -1158,6 +1211,8 @@ export function poll<A, E>(self: Deferred<A, E>): Effect<Option.Option<Effect<A,
 /**
  * Attempts to complete the `Deferred` with the specified value.
  *
+ * **Details**
+ *
  * Fibers waiting on the `Deferred` receive the value only if this call
  * completes it. The returned effect succeeds with `true` when this call
  * completed the `Deferred`, or `false` if it was already completed.
@@ -1183,6 +1238,8 @@ export const succeed: {
   /**
    * Attempts to complete the `Deferred` with the specified value.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` receive the value only if this call
    * completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -1208,6 +1265,8 @@ export const succeed: {
   /**
    * Attempts to complete the `Deferred` with the specified value.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` receive the value only if this call
    * completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -1236,6 +1295,8 @@ export const succeed: {
  * Computes a value when the returned effect is run, then attempts to complete
  * the `Deferred` with that value.
  *
+ * **Details**
+ *
  * Fibers waiting on the `Deferred` receive the computed value only if this call
  * completes it. The returned effect succeeds with `true` when this call
  * completed the `Deferred`, or `false` if it was already completed.
@@ -1262,6 +1323,8 @@ export const sync: {
    * Computes a value when the returned effect is run, then attempts to complete
    * the `Deferred` with that value.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` receive the computed value only if this call
    * completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -1288,6 +1351,8 @@ export const sync: {
    * Computes a value when the returned effect is run, then attempts to complete
    * the `Deferred` with that value.
    *
+   * **Details**
+   *
    * Fibers waiting on the `Deferred` receive the computed value only if this call
    * completes it. The returned effect succeeds with `true` when this call
    * completed the `Deferred`, or `false` if it was already completed.
@@ -1320,6 +1385,8 @@ export const sync: {
  * Synchronously attempts to complete the `Deferred` with the specified
  * completion effect.
  *
+ * **Details**
+ *
  * This mutates the `Deferred` directly and should be reserved for low-level
  * code; prefer the effectful completion APIs when possible. Returns `true` if
  * this call completed the `Deferred`, or `false` if it was already completed.

package/src/Differ.ts

@@ -41,6 +41,8 @@
 /**
  * Describes how to compute, combine, and apply patches for values of type `T`.
  *
+ * **Details**
+ *
  * A `Differ` provides an empty patch, computes the patch between two values,
  * combines patches, and applies a patch to an old value to produce an updated
  * value.

package/src/Duration.ts

@@ -51,6 +51,8 @@ export interface Duration extends Equal.Equal, Pipeable, Inspectable.Inspectable
 /**
  * Tagged representation of a `Duration` value.
  *
+ * **Details**
+ *
  * A duration is represented as milliseconds, nanoseconds, positive infinity,
  * or negative infinity.
  *
@@ -90,6 +92,8 @@ export type Unit =
 /**
  * Valid input types that can be converted to a Duration.
  *
+ * **Details**
+ *
  * String inputs accept values like `"10 seconds"`, `"500 millis"`,
  * `"Infinity"`, and `"-Infinity"`.
  *
@@ -110,6 +114,8 @@ export type Input =
  * An object with optional duration components that can be combined to create
  * a Duration. All fields are optional and additive.
  *
+ * **Details**
+ *
  * Compatible with Temporal.Duration-like objects.
  *
  * **Example** (Combining duration object fields)
@@ -141,6 +147,8 @@ const DURATION_REGEXP = /^(-?\d+(?:\.\d+)?)\s+(nanos?|micros?|millis?|seconds?|m
 /**
  * Decodes a `Duration.Input` into a `Duration`.
  *
+ * **Gotchas**
+ *
  * If the input is not a valid `Duration.Input`, it throws an error.
  *
  * **Example** (Decoding duration inputs)
@@ -828,6 +836,8 @@ export const toWeeks = (self: Input): number =>
 /**
  * Get the duration in nanoseconds as a bigint.
  *
+ * **Gotchas**
+ *
  * If the duration is infinite, it throws an error.
  *
  * **Example** (Reading nanoseconds unsafely)
@@ -862,6 +872,8 @@ export const toNanosUnsafe = (input: Input): bigint => {
 /**
  * Get the duration in nanoseconds as a bigint.
  *
+ * **Details**
+ *
  * If the duration is infinite, returns `Option.none()`.
  *
  * **Example** (Safely reading nanoseconds)
@@ -927,6 +939,8 @@ export const toHrTime = (input: Input): [seconds: number, nanos: number] => {
 /**
  * Pattern matches on the representation of a `Duration`.
  *
+ * **Details**
+ *
  * Provide handlers for millisecond-backed values, nanosecond-backed values,
  * and positive infinity. Use `onNegativeInfinity` to handle negative infinity
  * separately; otherwise negative infinity is handled by `onInfinity`.
@@ -951,6 +965,8 @@ export const match: {
   /**
    * Pattern matches on the representation of a `Duration`.
    *
+   * **Details**
+   *
    * Provide handlers for millisecond-backed values, nanosecond-backed values,
    * and positive infinity. Use `onNegativeInfinity` to handle negative infinity
    * separately; otherwise negative infinity is handled by `onInfinity`.
@@ -982,6 +998,8 @@ export const match: {
   /**
    * Pattern matches on the representation of a `Duration`.
    *
+   * **Details**
+   *
    * Provide handlers for millisecond-backed values, nanosecond-backed values,
    * and positive infinity. Use `onNegativeInfinity` to handle negative infinity
    * separately; otherwise negative infinity is handled by `onInfinity`.
@@ -1132,6 +1150,8 @@ export const matchPair: {
 /**
  * Order instance for `Duration`, allowing comparison operations.
  *
+ * **Details**
+ *
  * `NegativeInfinity` < any finite value < `Infinity`.
  *
  * **Example** (Sorting durations)
@@ -1413,6 +1433,8 @@ export const clamp: {
 /**
  * Safely divides a `Duration` by a finite, non-zero number.
  *
+ * **Details**
+ *
  * Returns `Option.none()` for zero, negative zero, or non-finite divisors. For
  * nanosecond-backed durations, also returns `Option.none()` when the divisor
  * cannot be converted to a `bigint`, such as a fractional divisor.
@@ -1435,6 +1457,8 @@ export const divide: {
   /**
    * Safely divides a `Duration` by a finite, non-zero number.
    *
+   * **Details**
+   *
    * Returns `Option.none()` for zero, negative zero, or non-finite divisors. For
    * nanosecond-backed durations, also returns `Option.none()` when the divisor
    * cannot be converted to a `bigint`, such as a fractional divisor.
@@ -1457,6 +1481,8 @@ export const divide: {
   /**
    * Safely divides a `Duration` by a finite, non-zero number.
    *
+   * **Details**
+   *
    * Returns `Option.none()` for zero, negative zero, or non-finite divisors. For
    * nanosecond-backed durations, also returns `Option.none()` when the divisor
    * cannot be converted to a `bigint`, such as a fractional divisor.
@@ -1500,6 +1526,8 @@ export const divide: {
  * Divides a `Duration` by a number using fallback rules instead of returning
  * an `Option`.
  *
+ * **Details**
+ *
  * Non-finite divisors return `Duration.zero`. Division by positive or negative
  * zero can produce signed infinity for non-zero finite durations, while zero
  * or infinite durations divided by zero produce `Duration.zero`.
@@ -1526,6 +1554,8 @@ export const divideUnsafe: {
    * Divides a `Duration` by a number using fallback rules instead of returning
    * an `Option`.
    *
+   * **Details**
+   *
    * Non-finite divisors return `Duration.zero`. Division by positive or negative
    * zero can produce signed infinity for non-zero finite durations, while zero
    * or infinite durations divided by zero produce `Duration.zero`.
@@ -1552,6 +1582,8 @@ export const divideUnsafe: {
    * Divides a `Duration` by a number using fallback rules instead of returning
    * an `Option`.
    *
+   * **Details**
+   *
    * Non-finite divisors return `Duration.zero`. Division by positive or negative
    * zero can produce signed infinity for non-zero finite durations, while zero
    * or infinite durations divided by zero produce `Duration.zero`.
@@ -1603,6 +1635,8 @@ export const divideUnsafe: {
 /**
  * Multiplies a `Duration` by a number.
  *
+ * **Details**
+ *
  * For nanosecond-backed durations, the multiplier must be convertible to a
  * `bigint`; fractional or non-finite multipliers can throw. Infinite
  * durations return positive infinity, negative infinity, or zero depending on
@@ -1624,6 +1658,8 @@ export const times: {
   /**
    * Multiplies a `Duration` by a number.
    *
+   * **Details**
+   *
    * For nanosecond-backed durations, the multiplier must be convertible to a
    * `bigint`; fractional or non-finite multipliers can throw. Infinite
    * durations return positive infinity, negative infinity, or zero depending on
@@ -1645,6 +1681,8 @@ export const times: {
   /**
    * Multiplies a `Duration` by a number.
    *
+   * **Details**
+   *
    * For nanosecond-backed durations, the multiplier must be convertible to a
    * `bigint`; fractional or non-finite multipliers can throw. Infinite
    * durations return positive infinity, negative infinity, or zero depending on
@@ -1677,7 +1715,10 @@ export const times: {
 /**
  * Subtracts one Duration from another. The result can be negative.
  *
- * **Infinity Subtraction Rules**
+ * **Details**
+ *
+ * Infinity subtraction follows these rules:
+ *
  * - infinity - infinity = 0
  * - infinity - negativeInfinity = infinity
  * - infinity - finite = infinity
@@ -1703,7 +1744,10 @@ export const subtract: {
   /**
    * Subtracts one Duration from another. The result can be negative.
    *
-   * **Infinity Subtraction Rules**
+   * **Details**
+   *
+   * Infinity subtraction follows these rules:
+   *
    * - infinity - infinity = 0
    * - infinity - negativeInfinity = infinity
    * - infinity - finite = infinity
@@ -1729,7 +1773,10 @@ export const subtract: {
   /**
    * Subtracts one Duration from another. The result can be negative.
    *
-   * **Infinity Subtraction Rules**
+   * **Details**
+   *
+   * Infinity subtraction follows these rules:
+   *
    * - infinity - infinity = 0
    * - infinity - negativeInfinity = infinity
    * - infinity - finite = infinity
@@ -1771,7 +1818,10 @@ export const subtract: {
 /**
  * Adds two Durations together.
  *
- * **Infinity Addition Rules**
+ * **Details**
+ *
+ * Infinity addition follows these rules:
+ *
  * - infinity + infinity = infinity
  * - infinity + negativeInfinity = zero
  * - infinity + finite = infinity
@@ -1794,7 +1844,10 @@ export const sum: {
   /**
    * Adds two Durations together.
    *
-   * **Infinity Addition Rules**
+   * **Details**
+   *
+   * Infinity addition follows these rules:
+   *
    * - infinity + infinity = infinity
    * - infinity + negativeInfinity = zero
    * - infinity + finite = infinity
@@ -1817,7 +1870,10 @@ export const sum: {
   /**
    * Adds two Durations together.
    *
-   * **Infinity Addition Rules**
+   * **Details**
+   *
+   * Infinity addition follows these rules:
+   *
    * - infinity + infinity = infinity
    * - infinity + negativeInfinity = zero
    * - infinity + finite = infinity
@@ -2127,6 +2183,8 @@ export const equals: {
 /**
  * Decomposes a `Duration` into normalized signed components.
  *
+ * **Details**
+ *
  * Finite durations are returned as `{ days, hours, minutes, seconds, millis,
  * nanos }`. Infinite durations return every component as `Infinity` or
  * `-Infinity`.