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

package/src/BigDecimal.ts

@@ -207,6 +207,8 @@ export const normalize = (self: BigDecimal): BigDecimal => {
 /**
  * Scales a `BigDecimal` to the specified scale.
  *
+ * **Details**
+ *
  * Increasing the scale appends decimal zeros. Decreasing the scale discards
  * digits beyond the target scale by `bigint` division, which truncates toward
  * zero.
@@ -234,6 +236,8 @@ export const scale: {
   /**
    * Scales a `BigDecimal` to the specified scale.
    *
+   * **Details**
+   *
    * Increasing the scale appends decimal zeros. Decreasing the scale discards
    * digits beyond the target scale by `bigint` division, which truncates toward
    * zero.
@@ -261,6 +265,8 @@ export const scale: {
   /**
    * Scales a `BigDecimal` to the specified scale.
    *
+   * **Details**
+   *
    * Increasing the scale appends decimal zeros. Decreasing the scale discards
    * digits beyond the target scale by `bigint` division, which truncates toward
    * zero.
@@ -642,10 +648,11 @@ export const roundTerminal = (n: bigint): bigint => {
 /**
  * Provides a division operation on `BigDecimal`s.
  *
- * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
- * with up to the default division precision.
+ * **Details**
  *
- * If the divisor is `0`, the result will be `Option.none()`.
+ * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
+ * with up to the default division precision. If the divisor is `0`, the result
+ * will be `Option.none()`.
  *
  * **Example** (Dividing decimals safely)
  *
@@ -685,10 +692,11 @@ export const divide: {
   /**
    * Provides a division operation on `BigDecimal`s.
    *
-   * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
-   * with up to the default division precision.
+   * **Details**
    *
-   * If the divisor is `0`, the result will be `Option.none()`.
+   * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
+   * with up to the default division precision. If the divisor is `0`, the result
+   * will be `Option.none()`.
    *
    * **Example** (Dividing decimals safely)
    *
@@ -728,10 +736,11 @@ export const divide: {
   /**
    * Provides a division operation on `BigDecimal`s.
    *
-   * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
-   * with up to the default division precision.
+   * **Details**
    *
-   * If the divisor is `0`, the result will be `Option.none()`.
+   * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
+   * with up to the default division precision. If the divisor is `0`, the result
+   * will be `Option.none()`.
    *
    * **Example** (Dividing decimals safely)
    *
@@ -788,9 +797,13 @@ export const divide: {
 /**
  * Provides an unsafe division operation on `BigDecimal`s.
  *
+ * **Details**
+ *
  * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
  * with up to the default division precision.
  *
+ * **Gotchas**
+ *
  * Throws a `RangeError` if the divisor is `0`.
  *
  * **Example** (Dividing decimals unsafely)
@@ -809,9 +822,13 @@ export const divideUnsafe: {
   /**
    * Provides an unsafe division operation on `BigDecimal`s.
    *
+   * **Details**
+   *
    * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
    * with up to the default division precision.
    *
+   * **Gotchas**
+   *
    * Throws a `RangeError` if the divisor is `0`.
    *
    * **Example** (Dividing decimals unsafely)
@@ -830,9 +847,13 @@ export const divideUnsafe: {
   /**
    * Provides an unsafe division operation on `BigDecimal`s.
    *
+   * **Details**
+   *
    * If the dividend is not a multiple of the divisor, the result will be a `BigDecimal` value
    * with up to the default division precision.
    *
+   * **Gotchas**
+   *
    * Throws a `RangeError` if the divisor is `0`.
    *
    * **Example** (Dividing decimals unsafely)
@@ -1318,9 +1339,11 @@ export const between: {
 /**
  * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
  *
- * - If the `BigDecimal` is less than the `minimum` value, the function returns the `minimum` value.
- * - If the `BigDecimal` is greater than the `maximum` value, the function returns the `maximum` value.
- * - Otherwise, it returns the original `BigDecimal`.
+ * **Details**
+ *
+ * If the `BigDecimal` is less than the `minimum` value, the function returns
+ * the `minimum` value. If it is greater than the `maximum` value, the function
+ * returns the `maximum` value. Otherwise, it returns the original `BigDecimal`.
  *
  * **Example** (Clamping decimals to a range)
  *
@@ -1354,9 +1377,11 @@ export const clamp: {
   /**
    * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
    *
-   * - If the `BigDecimal` is less than the `minimum` value, the function returns the `minimum` value.
-   * - If the `BigDecimal` is greater than the `maximum` value, the function returns the `maximum` value.
-   * - Otherwise, it returns the original `BigDecimal`.
+   * **Details**
+   *
+   * If the `BigDecimal` is less than the `minimum` value, the function returns
+   * the `minimum` value. If it is greater than the `maximum` value, the function
+   * returns the `maximum` value. Otherwise, it returns the original `BigDecimal`.
    *
    * **Example** (Clamping decimals to a range)
    *
@@ -1395,9 +1420,11 @@ export const clamp: {
   /**
    * Restricts the given `BigDecimal` to be within the range specified by the `minimum` and `maximum` values.
    *
-   * - If the `BigDecimal` is less than the `minimum` value, the function returns the `minimum` value.
-   * - If the `BigDecimal` is greater than the `maximum` value, the function returns the `maximum` value.
-   * - Otherwise, it returns the original `BigDecimal`.
+   * **Details**
+   *
+   * If the `BigDecimal` is less than the `minimum` value, the function returns
+   * the `minimum` value. If it is greater than the `maximum` value, the function
+   * returns the `maximum` value. Otherwise, it returns the original `BigDecimal`.
    *
    * **Example** (Clamping decimals to a range)
    *
@@ -1613,6 +1640,8 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
 /**
  * Returns the remainder left over when one operand is divided by a second operand.
  *
+ * **Details**
+ *
  * If the divisor is `0`, the result will be `Option.none()`.
  *
  * **Example** (Computing remainders safely)
@@ -1651,6 +1680,8 @@ export const remainder: {
   /**
    * Returns the remainder left over when one operand is divided by a second operand.
    *
+   * **Details**
+   *
    * If the divisor is `0`, the result will be `Option.none()`.
    *
    * **Example** (Computing remainders safely)
@@ -1689,6 +1720,8 @@ export const remainder: {
   /**
    * Returns the remainder left over when one operand is divided by a second operand.
    *
+   * **Details**
+   *
    * If the divisor is `0`, the result will be `Option.none()`.
    *
    * **Example** (Computing remainders safely)
@@ -1736,6 +1769,8 @@ export const remainder: {
 /**
  * Returns the remainder left over when one operand is divided by a second operand.
  *
+ * **Gotchas**
+ *
  * Throws a `RangeError` if the divisor is `0`.
  *
  * **Example** (Computing remainders unsafely)
@@ -1765,6 +1800,8 @@ export const remainderUnsafe: {
   /**
    * Returns the remainder left over when one operand is divided by a second operand.
    *
+   * **Gotchas**
+   *
    * Throws a `RangeError` if the divisor is `0`.
    *
    * **Example** (Computing remainders unsafely)
@@ -1794,6 +1831,8 @@ export const remainderUnsafe: {
   /**
    * Returns the remainder left over when one operand is divided by a second operand.
    *
+   * **Gotchas**
+   *
    * Throws a `RangeError` if the divisor is `0`.
    *
    * **Example** (Computing remainders unsafely)
@@ -1945,10 +1984,11 @@ export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
 /**
  * Creates a `BigDecimal` from a `number` value.
  *
- * It is not recommended to convert a floating point number to a decimal directly,
- * as the floating point representation may be unexpected.
+ * **Gotchas**
  *
- * Throws a `RangeError` if the number is not finite (`NaN`, `+Infinity` or `-Infinity`).
+ * It is not recommended to convert a floating point number to a decimal
+ * directly, as the floating point representation may be unexpected. Throws a
+ * `RangeError` if the number is not finite (`NaN`, `+Infinity` or `-Infinity`).
  *
  * **Example** (Creating decimals from finite numbers)
  *
@@ -1970,11 +2010,15 @@ export const fromNumberUnsafe = (n: number): BigDecimal => {
 /**
  * Creates a `BigDecimal` from a `number` value.
  *
- * It is not recommended to convert a floating point number to a decimal directly,
- * as the floating point representation may be unexpected.
+ * **Details**
  *
  * Returns `Option.none()` for `NaN`, `+Infinity` or `-Infinity`.
  *
+ * **Gotchas**
+ *
+ * It is not recommended to convert a floating point number to a decimal
+ * directly, as the floating point representation may be unexpected.
+ *
  * **Example** (Creating decimals from numbers safely)
  *
  * ```ts
@@ -2009,6 +2053,8 @@ export const fromNumber = (n: number): Option.Option<BigDecimal> => {
 /**
  * Safely parses a decimal string into a `BigDecimal`.
  *
+ * **Details**
+ *
  * Returns `Option.some` for valid decimal or exponent notation and
  * `Option.none` when the string cannot be parsed or would produce an unsafe
  * scale. The empty string parses as zero.
@@ -2079,6 +2125,8 @@ export const fromString = (s: string): Option.Option<BigDecimal> => {
  * Parses a decimal string into a `BigDecimal`, throwing if the string is
  * invalid.
  *
+ * **Details**
+ *
  * Accepts the same syntax as `fromString`. Use `fromString` when invalid input
  * should be represented as `Option.none` instead of throwing.
  *
@@ -2103,6 +2151,8 @@ export const fromStringUnsafe = (s: string): BigDecimal => {
 /**
  * Formats a `BigDecimal` as a string.
  *
+ * **Details**
+ *
  * The value is normalized before formatting. Scientific notation is used when
  * the absolute value of the normalized scale is at least `16`; otherwise plain
  * decimal notation is used.
@@ -2189,6 +2239,8 @@ export const toExponential = (n: BigDecimal): string => {
 /**
  * Converts a `BigDecimal` to a JavaScript `number`.
  *
+ * **Gotchas**
+ *
  * This conversion is unsafe because the result can lose integer or fractional
  * precision, round to a nearby representable value, or become `Infinity` when
  * the decimal cannot be represented as a finite JavaScript `number`.
@@ -2287,16 +2339,18 @@ const isBigDecimalArgs = (args: IArguments) => isBigDecimal(args[0])
 /**
  * Rounding modes for `BigDecimal`.
  *
- * `ceil`: round towards positive infinity
- * `floor`: round towards negative infinity
- * `to-zero`: round towards zero
- * `from-zero`: round away from zero
- * `half-ceil`: round to the nearest neighbor; if equidistant round towards positive infinity
- * `half-floor`: round to the nearest neighbor; if equidistant round towards negative infinity
- * `half-to-zero`: round to the nearest neighbor; if equidistant round towards zero
- * `half-from-zero`: round to the nearest neighbor; if equidistant round away from zero
- * `half-even`: round to the nearest neighbor; if equidistant round to the neighbor with an even digit
- * `half-odd`: round to the nearest neighbor; if equidistant round to the neighbor with an odd digit
+ * **Details**
+ *
+ * - `ceil`: round towards positive infinity
+ * - `floor`: round towards negative infinity
+ * - `to-zero`: round towards zero
+ * - `from-zero`: round away from zero
+ * - `half-ceil`: round to the nearest neighbor; if equidistant round towards positive infinity
+ * - `half-floor`: round to the nearest neighbor; if equidistant round towards negative infinity
+ * - `half-to-zero`: round to the nearest neighbor; if equidistant round towards zero
+ * - `half-from-zero`: round to the nearest neighbor; if equidistant round away from zero
+ * - `half-even`: round to the nearest neighbor; if equidistant round to the neighbor with an even digit
+ * - `half-odd`: round to the nearest neighbor; if equidistant round to the neighbor with an odd digit
  *
  * @category math
  * @since 3.16.0

package/src/BigInt.ts

@@ -209,6 +209,8 @@ export const subtract: {
 /**
  * Safely divides one `bigint` by another.
  *
+ * **Details**
+ *
  * Uses JavaScript `bigint` division, so non-exact quotients are truncated
  * toward zero. Returns `Option.none()` when the divisor is `0n`.
  *
@@ -229,6 +231,8 @@ export const divide: {
   /**
    * Safely divides one `bigint` by another.
    *
+   * **Details**
+   *
    * Uses JavaScript `bigint` division, so non-exact quotients are truncated
    * toward zero. Returns `Option.none()` when the divisor is `0n`.
    *
@@ -249,6 +253,8 @@ export const divide: {
   /**
    * Safely divides one `bigint` by another.
    *
+   * **Details**
+   *
    * Uses JavaScript `bigint` division, so non-exact quotients are truncated
    * toward zero. Returns `Option.none()` when the divisor is `0n`.
    *
@@ -274,8 +280,14 @@ export const divide: {
 /**
  * Divides one `bigint` by another, throwing if the divisor is zero.
  *
+ * **Details**
+ *
  * Uses JavaScript `bigint` division, so non-exact quotients are truncated
- * toward zero. Throws a `RangeError` when the divisor is `0n`.
+ * toward zero.
+ *
+ * **Gotchas**
+ *
+ * Throws a `RangeError` when the divisor is `0n`.
  *
  * **Example** (Dividing bigints unsafely)
  *
@@ -294,8 +306,14 @@ export const divideUnsafe: {
   /**
    * Divides one `bigint` by another, throwing if the divisor is zero.
    *
+   * **Details**
+   *
    * Uses JavaScript `bigint` division, so non-exact quotients are truncated
-   * toward zero. Throws a `RangeError` when the divisor is `0n`.
+   * toward zero.
+   *
+   * **Gotchas**
+   *
+   * Throws a `RangeError` when the divisor is `0n`.
    *
    * **Example** (Dividing bigints unsafely)
    *
@@ -314,8 +332,14 @@ export const divideUnsafe: {
   /**
    * Divides one `bigint` by another, throwing if the divisor is zero.
    *
+   * **Details**
+   *
    * Uses JavaScript `bigint` division, so non-exact quotients are truncated
-   * toward zero. Throws a `RangeError` when the divisor is `0n`.
+   * toward zero.
+   *
+   * **Gotchas**
+   *
+   * Throws a `RangeError` when the divisor is `0n`.
    *
    * **Example** (Dividing bigints unsafely)
    *
@@ -706,6 +730,8 @@ export const between: {
 /**
  * Restricts the given `bigint` to be within the range specified by the `minimum` and `maximum` values.
  *
+ * **Details**
+ *
  * - If the `bigint` is less than the `minimum` value, the function returns the `minimum` value.
  * - If the `bigint` is greater than the `maximum` value, the function returns the `maximum` value.
  * - Otherwise, it returns the original `bigint`.
@@ -730,6 +756,8 @@ export const clamp: {
   /**
    * Restricts the given `bigint` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **Details**
+   *
    * - If the `bigint` is less than the `minimum` value, the function returns the `minimum` value.
    * - If the `bigint` is greater than the `maximum` value, the function returns the `maximum` value.
    * - Otherwise, it returns the original `bigint`.
@@ -759,6 +787,8 @@ export const clamp: {
   /**
    * Restricts the given `bigint` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **Details**
+   *
    * - If the `bigint` is less than the `minimum` value, the function returns the `minimum` value.
    * - If the `bigint` is greater than the `maximum` value, the function returns the `maximum` value.
    * - Otherwise, it returns the original `bigint`.
@@ -1048,8 +1078,14 @@ export const lcm: {
 /**
  * Returns the integer square root of a non-negative `bigint`.
  *
+ * **Details**
+ *
  * For non-perfect squares, returns the largest `bigint` whose square is less
- * than or equal to the input. Throws a `RangeError` if the input is negative.
+ * than or equal to the input.
+ *
+ * **Gotchas**
+ *
+ * Throws a `RangeError` if the input is negative.
  *
  * **Example** (Calculating square roots unsafely)
  *
@@ -1082,6 +1118,8 @@ export const sqrtUnsafe = (n: bigint): bigint => {
 /**
  * Safely returns the integer square root of a `bigint`.
  *
+ * **Details**
+ *
  * For non-perfect squares, returns the largest `bigint` whose square is less
  * than or equal to the input. Returns `Option.none()` when the input is
  * negative.
@@ -1104,9 +1142,7 @@ export const sqrt = (n: bigint): Option.Option<bigint> =>
   isGreaterThanOrEqualTo(n, bigint0) ? Option.some(sqrtUnsafe(n)) : Option.none()
 
 /**
- * Takes an `Iterable` of `bigint`s and returns their sum as a single `bigint`.
- *
- * Returns `0n` for an empty iterable.
+ * Takes an `Iterable` of `bigint`s and returns their sum as a single `bigint`. Returns `0n` for an empty iterable.
  *
  * **Example** (Summing iterable bigints)
  *
@@ -1129,10 +1165,7 @@ export const sumAll = (collection: Iterable<bigint>): bigint => {
 }
 
 /**
- * Takes an `Iterable` of `bigint`s and returns their product as a single
- * `bigint`.
- *
- * Returns `1n` for an empty iterable.
+ * Takes an `Iterable` of `bigint`s and returns their product as a single `bigint`. Returns `1n` for an empty iterable.
  *
  * **Example** (Multiplying iterable bigints)
  *
@@ -1160,6 +1193,8 @@ export const multiplyAll = (collection: Iterable<bigint>): bigint => {
 /**
  * Converts a `bigint` to a `number`.
  *
+ * **Details**
+ *
  * If the `bigint` is outside the safe integer range for JavaScript (`Number.MAX_SAFE_INTEGER`
  * and `Number.MIN_SAFE_INTEGER`), it returns `Option.none()`.
  *
@@ -1186,6 +1221,8 @@ export const toNumber = (b: bigint): Option.Option<number> => {
 /**
  * Converts a string to a `bigint`.
  *
+ * **Details**
+ *
  * If the string is empty or contains characters that cannot be converted into a
  * `bigint`, it returns `Option.none()`.
  *
@@ -1215,6 +1252,8 @@ export const fromString = (s: string): Option.Option<bigint> => {
 /**
  * Converts a number to a `bigint`.
  *
+ * **Details**
+ *
  * If the number is outside the safe integer range for JavaScript
  * (`Number.MAX_SAFE_INTEGER` and `Number.MIN_SAFE_INTEGER`) or if the number is
  * not a valid `bigint`, it returns `Option.none()`.
@@ -1248,8 +1287,14 @@ export function fromNumber(n: number): Option.Option<bigint> {
 /**
  * Returns the JavaScript remainder of dividing one `bigint` by another.
  *
+ * **Details**
+ *
  * The result follows JavaScript `%` semantics, including the sign of the
- * dividend. Throws a `RangeError` when the divisor is `0n`.
+ * dividend.
+ *
+ * **Gotchas**
+ *
+ * Throws a `RangeError` when the divisor is `0n`.
  *
  * **Example** (Calculating remainders)
  *
@@ -1268,8 +1313,14 @@ export const remainder: {
   /**
    * Returns the JavaScript remainder of dividing one `bigint` by another.
    *
+   * **Details**
+   *
    * The result follows JavaScript `%` semantics, including the sign of the
-   * dividend. Throws a `RangeError` when the divisor is `0n`.
+   * dividend.
+   *
+   * **Gotchas**
+   *
+   * Throws a `RangeError` when the divisor is `0n`.
    *
    * **Example** (Calculating remainders)
    *
@@ -1288,8 +1339,14 @@ export const remainder: {
   /**
    * Returns the JavaScript remainder of dividing one `bigint` by another.
    *
+   * **Details**
+   *
    * The result follows JavaScript `%` semantics, including the sign of the
-   * dividend. Throws a `RangeError` when the divisor is `0n`.
+   * dividend.
+   *
+   * **Gotchas**
+   *
+   * Throws a `RangeError` when the divisor is `0n`.
    *
    * **Example** (Calculating remainders)
    *

package/src/Boolean.ts

@@ -657,6 +657,8 @@ export const some = (collection: Iterable<boolean>): boolean => {
 /**
  * A `Reducer` for combining `boolean`s using AND.
  *
+ * **Details**
+ *
  * The `initialValue` is `true`.
  *
  * @category math
@@ -667,6 +669,8 @@ export const ReducerAnd: Reducer.Reducer<boolean> = Reducer.make((a, b) => a &&
 /**
  * A `Reducer` for combining `boolean`s using OR.
  *
+ * **Details**
+ *
  * The `initialValue` is `false`.
  *
  * @category math

package/src/Brand.ts

@@ -180,13 +180,14 @@ export declare namespace Brand {
 export type Branded<A, Key extends string> = A & Brand<Key>
 
 /**
- * This function returns a `Constructor` that **does not apply any runtime
- * checks**, it just returns the provided value. It can be used to create
- * nominal types that allow distinguishing between two values of the same type
- * but with different meanings.
+ * Returns a `Constructor` that **does not apply any runtime checks** and just
+ * returns the provided value.
  *
- * If you also want to perform some validation, see {@link make} or
- * {@link check}.
+ * **When to use**
+ *
+ * Use this to create nominal types that allow distinguishing between two values
+ * of the same type but with different meanings. If you also want to perform
+ * some validation, see {@link make} or {@link check}.
  *
  * @category constructors
  * @since 2.0.0
@@ -200,12 +201,14 @@ export function nominal<A extends Brand<any>>(): Constructor<A> {
 }
 
 /**
- * Returns a `Constructor` that can construct a branded type from an
- * unbranded value using the provided `filter` predicate as validation of
- * the input data.
+ * Returns a `Constructor` that can construct a branded type from an unbranded
+ * value using the provided `filter` predicate as validation of the input data.
+ *
+ * **When to use**
  *
- * If you don't want to perform any validation but only distinguish between two
- * values of the same type but with different meanings, see {@link nominal}.
+ * Use this when you want validation while constructing the branded type. If you
+ * don't want to perform any validation but only distinguish between two values
+ * of the same type but with different meanings, see {@link nominal}.
  *
  * @category constructors
  * @since 4.0.0
@@ -219,6 +222,8 @@ export function make<A extends Brand<any>>(
 /**
  * Creates a branded type `Constructor` from one or more schema checks.
  *
+ * **Details**
+ *
  * Calling the returned constructor validates the unbranded value and throws on
  * failure. Use the returned `option`, `result`, or `is` methods for
  * non-throwing validation.

package/src/Cache.ts

@@ -140,7 +140,7 @@ export interface Cache<in out Key, in out A, in out E = never, out R = never> ex
  * Represents a low-level cache entry containing a deferred lookup result and
  * an optional expiration timestamp.
  *
- * **Notes**
+ * **Details**
  *
  * An `expiresAt` value of `undefined` means the entry does not expire. Most
  * users should interact with entries through the `Cache` combinators rather
@@ -157,6 +157,8 @@ export interface Entry<A, E> {
 /**
  * Creates a cache with dynamic time-to-live based on the result and key.
  *
+ * **Details**
+ *
  * The timeToLive function receives both the exit result and the key, allowing
  * for flexible TTL policies based on success/failure state and key characteristics.
  *
@@ -221,6 +223,8 @@ export const makeWith = <
 /**
  * Creates a cache with a fixed time-to-live for all entries.
  *
+ * **Details**
+ *
  * This is the basic cache constructor where all entries share the same TTL.
  * The lookup function will be called when a key is not found or has expired.
  *
@@ -2325,6 +2329,8 @@ export const invalidateWhen: {
 /**
  * Forces a refresh of the value associated with the specified key in the cache.
  *
+ * **Details**
+ *
  * It will always invoke the lookup function to construct a new value,
  * overwriting any existing value for that key.
  *
@@ -2416,6 +2422,8 @@ export const refresh: {
   /**
    * Forces a refresh of the value associated with the specified key in the cache.
    *
+   * **Details**
+   *
    * It will always invoke the lookup function to construct a new value,
    * overwriting any existing value for that key.
    *
@@ -2507,6 +2515,8 @@ export const refresh: {
   /**
    * Forces a refresh of the value associated with the specified key in the cache.
    *
+   * **Details**
+   *
    * It will always invoke the lookup function to construct a new value,
    * overwriting any existing value for that key.
    *
@@ -2602,6 +2612,8 @@ export const refresh: {
       const deferred = Deferred.makeUnsafe</**
        * Forces a refresh of the value associated with the specified key in the cache.
        *
+       * **Details**
+       *
        * It will always invoke the lookup function to construct a new value,
        * overwriting any existing value for that key.
        *
@@ -2692,6 +2704,8 @@ export const refresh: {
       A, /**
        * Forces a refresh of the value associated with the specified key in the cache.
        *
+       * **Details**
+       *
        * It will always invoke the lookup function to construct a new value,
        * overwriting any existing value for that key.
        *
@@ -2852,6 +2866,8 @@ export const invalidateAll = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.E
 /**
  * Retrieves the approximate number of entries in the cache.
  *
+ * **Details**
+ *
  * Note that expired entries are counted until they are accessed and removed.
  * The size reflects the current number of entries stored, not the number
  * of valid entries.