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

package/src/Newtype.ts

@@ -76,13 +76,18 @@ const TypeId = "~effect/Newtype"
  * A tagged interface that wraps a carrier type under a unique key, preventing
  * accidental interchange of structurally identical values.
  *
- * - Define your newtype as an `interface` extending
- *   `Newtype<"MyKey", CarrierType>`.
- * - The tag is compile-time only; no runtime wrapper is allocated.
- * - Use {@link makeIso} to create a two-way conversion, or {@link value} to
- *   unwrap.
+ * **When to use**
  *
- * **Example** (defining a newtype)
+ * Define your newtype as an `interface` extending
+ * `Newtype<"MyKey", CarrierType>` when you need two structurally identical
+ * carrier types to remain distinct in TypeScript.
+ *
+ * **Details**
+ *
+ * The tag is compile-time only, so no runtime wrapper is allocated. Use
+ * {@link makeIso} to create a two-way conversion, or {@link value} to unwrap.
+ *
+ * **Example** (Defining a newtype)
  *
  * ```ts
  * import { Newtype } from "effect"
@@ -128,7 +133,9 @@ export declare namespace Newtype {
   /**
    * Extracts the key literal type from a newtype.
    *
-   * - Useful in generic code that needs to inspect or constrain the key.
+   * **When to use**
+   *
+   * Use this in generic code that needs to inspect or constrain the key.
    *
    * @category utility types
    * @since 4.0.0
@@ -138,7 +145,9 @@ export declare namespace Newtype {
   /**
    * Extracts the carrier (underlying) type from a newtype.
    *
-   * - Useful when you need to refer to the wrapped type in generic utilities.
+   * **When to use**
+   *
+   * Use this when you need to refer to the wrapped type in generic utilities.
    *
    * @category utility types
    * @since 4.0.0
@@ -149,12 +158,16 @@ export declare namespace Newtype {
 /**
  * Unwraps a newtype value, returning the underlying carrier value.
  *
- * - Use when you only need to read the inner value and do not need to wrap new
- *   values.
- * - For both wrapping and unwrapping, prefer {@link makeIso}.
- * - Zero runtime cost: this is an identity cast.
+ * **When to use**
+ *
+ * Use this when you only need to read the inner value and do not need to wrap
+ * new values. For both wrapping and unwrapping, prefer {@link makeIso}.
  *
- * **Example** (unwrapping a newtype)
+ * **Details**
+ *
+ * This has zero runtime cost because it is an identity cast.
+ *
+ * **Example** (Unwrapping a newtype)
  *
  * ```ts
  * import { Newtype } from "effect"
@@ -178,11 +191,16 @@ export const value: <N extends Newtype.Any>(newtype: N) => Newtype.Carrier<N> =
  * Creates an `Optic.Iso` for a newtype, providing both wrapping (`set`) and
  * unwrapping (`get`).
  *
- * - Use this as the primary way to construct and deconstruct newtype values.
- * - The returned iso composes with other optics via the standard `Optic` API.
- * - Zero runtime cost: both directions are identity casts.
+ * **When to use**
+ *
+ * Use this as the primary way to construct and deconstruct newtype values.
  *
- * **Example** (wrapping and unwrapping with an iso)
+ * **Details**
+ *
+ * The returned iso composes with other optics via the standard `Optic` API.
+ * Both directions have zero runtime cost because they are identity casts.
+ *
+ * **Example** (Wrapping and unwrapping with an iso)
  *
  * ```ts
  * import { Newtype } from "effect"
@@ -208,11 +226,16 @@ export function makeIso<N extends Newtype.Any>(): Optic.Iso<N, Newtype.Carrier<N
  * Lifts an `Equivalence` for the carrier type into an `Equivalence` for the
  * newtype.
  *
- * - Use when you need to compare two newtype values for equality.
- * - The returned equivalence delegates to the provided carrier equivalence.
- * - Zero runtime cost beyond the underlying equivalence check.
+ * **When to use**
+ *
+ * Use this when you need to compare two newtype values for equality.
  *
- * **Example** (comparing newtypes)
+ * **Details**
+ *
+ * The returned equivalence delegates to the provided carrier equivalence and
+ * has zero runtime cost beyond the underlying equivalence check.
+ *
+ * **Example** (Comparing newtypes)
  *
  * ```ts
  * import { Equivalence, Newtype } from "effect"
@@ -238,10 +261,15 @@ export const makeEquivalence: <N extends Newtype.Any>(
 /**
  * Lifts an `Order` for the carrier type into an `Order` for the newtype.
  *
- * - Use when you need to sort or compare newtype values.
- * - The returned order delegates to the provided carrier order.
+ * **When to use**
+ *
+ * Use this when you need to sort or compare newtype values.
  *
- * **Example** (ordering newtypes)
+ * **Details**
+ *
+ * The returned order delegates to the provided carrier order.
+ *
+ * **Example** (Ordering newtypes)
  *
  * ```ts
  * import { Newtype, Order } from "effect"
@@ -264,10 +292,15 @@ export const makeOrder: <N extends Newtype.Any>(order: Order.Order<Newtype.Carri
 /**
  * Lifts a `Combiner` for the carrier type into a `Combiner` for the newtype.
  *
- * - Use when you need to combine (e.g. concatenate, add) newtype values.
- * - The returned combiner delegates to the provided carrier combiner.
+ * **When to use**
+ *
+ * Use this when you need to combine newtype values.
  *
- * **Example** (combining newtypes)
+ * **Details**
+ *
+ * The returned combiner delegates to the provided carrier combiner.
+ *
+ * **Example** (Combining newtypes)
  *
  * ```ts
  * import { Combiner, Newtype } from "effect"
@@ -294,10 +327,16 @@ export const makeCombiner: <N extends Newtype.Any>(
 /**
  * Lifts a `Reducer` for the carrier type into a `Reducer` for the newtype.
  *
- * - Use when you need to fold/reduce over a collection of newtype values.
- * - The returned reducer delegates to the provided carrier reducer.
+ * **When to use**
+ *
+ * Use this when you need to fold or reduce over a collection of newtype
+ * values.
+ *
+ * **Details**
+ *
+ * The returned reducer delegates to the provided carrier reducer.
  *
- * **Example** (reducing newtypes)
+ * **Example** (Reducing newtypes)
  *
  * ```ts
  * import { Newtype, Reducer } from "effect"

package/src/NonEmptyIterable.ts

@@ -145,6 +145,8 @@
 /**
  * A unique symbol used to brand the `NonEmptyIterable` type.
  *
+ * **Details**
+ *
  * This symbol ensures that `NonEmptyIterable<A>` is a distinct type from regular
  * `Iterable<A>`, providing compile-time guarantees about non-emptiness while
  * maintaining full compatibility with the JavaScript iteration protocol.
@@ -157,6 +159,8 @@ export declare const nonEmpty: unique symbol
 /**
  * Represents an iterable that is guaranteed to contain at least one element.
  *
+ * **Details**
+ *
  * `NonEmptyIterable<A>` extends the standard `Iterable<A>` interface with a type-level
  * guarantee of non-emptiness. This allows for safe operations that would otherwise
  * require runtime checks or could throw exceptions.
@@ -216,6 +220,8 @@ export interface NonEmptyIterable<out A> extends Iterable<A> {
 /**
  * Safely extracts the first element and remaining elements from a non-empty iterable.
  *
+ * **Details**
+ *
  * This function provides a safe way to deconstruct a `NonEmptyIterable` into its
  * head (first element) and tail (remaining elements as an iterator). Since the
  * iterable is guaranteed to be non-empty, the first element is always available.

package/src/Number.ts

@@ -201,9 +201,7 @@ export const subtract: {
 } = dual(2, (self: number, that: number): number => self - that)
 
 /**
- * Provides a division operation on `number`s.
- *
- * Returns `Option.none()` if the divisor is `0`.
+ * Provides a division operation on `number`s, returning `Option.none()` if the divisor is `0`.
  *
  * **Example** (Dividing numbers safely)
  *
@@ -219,9 +217,7 @@ export const subtract: {
  */
 export const divide: {
   /**
-   * Provides a division operation on `number`s.
-   *
-   * Returns `Option.none()` if the divisor is `0`.
+   * Provides a division operation on `number`s, returning `Option.none()` if the divisor is `0`.
    *
    * **Example** (Dividing numbers safely)
    *
@@ -237,9 +233,7 @@ export const divide: {
    */
   (that: number): (self: number) => Option.Option<number>
   /**
-   * Provides a division operation on `number`s.
-   *
-   * Returns `Option.none()` if the divisor is `0`.
+   * Provides a division operation on `number`s, returning `Option.none()` if the divisor is `0`.
    *
    * **Example** (Dividing numbers safely)
    *
@@ -260,9 +254,7 @@ export const divide: {
 )
 
 /**
- * Provides an unsafe division operation on `number`s.
- *
- * Throws a `RangeError` if the divisor is `0`.
+ * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
  *
  * **Example** (Dividing numbers unsafely)
  *
@@ -279,9 +271,7 @@ export const divide: {
  */
 export const divideUnsafe: {
   /**
-   * Provides an unsafe division operation on `number`s.
-   *
-   * Throws a `RangeError` if the divisor is `0`.
+   * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
    *
    * **Example** (Dividing numbers unsafely)
    *
@@ -298,9 +288,7 @@ export const divideUnsafe: {
    */
   (that: number): (self: number) => number
   /**
-   * Provides an unsafe division operation on `number`s.
-   *
-   * Throws a `RangeError` if the divisor is `0`.
+   * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
    *
    * **Example** (Dividing numbers unsafely)
    *
@@ -375,9 +363,7 @@ export const decrement = (n: number): number => n - 1
 export const Order: order.Order<number> = order.Number
 
 /**
- * An `Equivalence` instance for numbers.
- *
- * `NaN` is considered equal to `NaN`.
+ * An `Equivalence` instance for numbers where `NaN` is considered equal to `NaN`.
  *
  * **Example** (Comparing numbers for equivalence)
  *
@@ -694,6 +680,8 @@ export const between: {
 /**
  * Restricts the given `number` to be within the range specified by the `minimum` and `maximum` values.
  *
+ * **Details**
+ *
  * - If the `number` is less than the `minimum` value, the function returns the `minimum` value.
  * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
  * - Otherwise, it returns the original `number`.
@@ -718,6 +706,8 @@ export const clamp: {
   /**
    * Restricts the given `number` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **Details**
+   *
    * - If the `number` is less than the `minimum` value, the function returns the `minimum` value.
    * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
    * - Otherwise, it returns the original `number`.
@@ -747,6 +737,8 @@ export const clamp: {
   /**
    * Restricts the given `number` to be within the range specified by the `minimum` and `maximum` values.
    *
+   * **Details**
+   *
    * - If the `number` is less than the `minimum` value, the function returns the `minimum` value.
    * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
    * - Otherwise, it returns the original `number`.
@@ -945,9 +937,7 @@ export const multiplyAll = (collection: Iterable<number>): number => {
 }
 
 /**
- * Returns the remainder left over when one operand is divided by a second operand.
- *
- * It always takes the sign of the dividend.
+ * Returns the remainder left over when one operand is divided by a second operand, always taking the sign of the dividend.
  *
  * **Example** (Calculating remainders)
  *
@@ -965,9 +955,7 @@ export const multiplyAll = (collection: Iterable<number>): number => {
  */
 export const remainder: {
   /**
-   * Returns the remainder left over when one operand is divided by a second operand.
-   *
-   * It always takes the sign of the dividend.
+   * Returns the remainder left over when one operand is divided by a second operand, always taking the sign of the dividend.
    *
    * **Example** (Calculating remainders)
    *
@@ -985,9 +973,7 @@ export const remainder: {
    */
   (divisor: number): (self: number) => number
   /**
-   * Returns the remainder left over when one operand is divided by a second operand.
-   *
-   * It always takes the sign of the dividend.
+   * Returns the remainder left over when one operand is divided by a second operand, always taking the sign of the dividend.
    *
    * **Example** (Calculating remainders)
    *