effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/Number.ts

@@ -15,9 +15,10 @@ import * as Reducer from "./Reducer.ts"
 /**
  * The global `Number` constructor.
  *
- * @example
+ * **Example** (Coercing values to numbers)
+ *
  * ```ts
- * import * as N from "effect/Number"
+ * import { Number as N } from "effect"
  *
  * const num = N.Number("42")
  * console.log(num) // 42
@@ -34,13 +35,14 @@ export const Number = globalThis.Number
 /**
  * Tests if a value is a `number`.
  *
- * @example
+ * **Example** (Checking for numbers)
+ *
  * ```ts
- * import { isNumber } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isNumber(2), true)
- * assert.deepStrictEqual(isNumber("2"), false)
+ * assert.deepStrictEqual(Number.isNumber(2), true)
+ * assert.deepStrictEqual(Number.isNumber("2"), false)
  * ```
  *
  * @category guards
@@ -51,12 +53,13 @@ export const isNumber: (input: unknown) => input is number = predicate.isNumber
 /**
  * Provides an addition operation on `number`s.
  *
- * @example
+ * **Example** (Adding numbers)
+ *
  * ```ts
- * import { sum } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(sum(2, 3), 5)
+ * assert.deepStrictEqual(Number.sum(2, 3), 5)
  * ```
  *
  * @category math
@@ -66,12 +69,13 @@ export const sum: {
   /**
    * Provides an addition operation on `number`s.
    *
-   * @example
+   * **Example** (Adding numbers)
+   *
    * ```ts
-   * import { sum } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(sum(2, 3), 5)
+   * assert.deepStrictEqual(Number.sum(2, 3), 5)
    * ```
    *
    * @category math
@@ -81,12 +85,13 @@ export const sum: {
   /**
    * Provides an addition operation on `number`s.
    *
-   * @example
+   * **Example** (Adding numbers)
+   *
    * ```ts
-   * import { sum } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(sum(2, 3), 5)
+   * assert.deepStrictEqual(Number.sum(2, 3), 5)
    * ```
    *
    * @category math
@@ -98,12 +103,13 @@ export const sum: {
 /**
  * Provides a multiplication operation on `number`s.
  *
- * @example
+ * **Example** (Multiplying numbers)
+ *
  * ```ts
- * import { multiply } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(multiply(2, 3), 6)
+ * assert.deepStrictEqual(Number.multiply(2, 3), 6)
  * ```
  *
  * @category math
@@ -113,12 +119,13 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `number`s.
    *
-   * @example
+   * **Example** (Multiplying numbers)
+   *
    * ```ts
-   * import { multiply } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(multiply(2, 3), 6)
+   * assert.deepStrictEqual(Number.multiply(2, 3), 6)
    * ```
    *
    * @category math
@@ -128,12 +135,13 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `number`s.
    *
-   * @example
+   * **Example** (Multiplying numbers)
+   *
    * ```ts
-   * import { multiply } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(multiply(2, 3), 6)
+   * assert.deepStrictEqual(Number.multiply(2, 3), 6)
    * ```
    *
    * @category math
@@ -145,12 +153,13 @@ export const multiply: {
 /**
  * Provides a subtraction operation on `number`s.
  *
- * @example
+ * **Example** (Subtracting numbers)
+ *
  * ```ts
- * import { subtract } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(subtract(2, 3), -1)
+ * assert.deepStrictEqual(Number.subtract(2, 3), -1)
  * ```
  *
  * @category math
@@ -160,12 +169,13 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `number`s.
    *
-   * @example
+   * **Example** (Subtracting numbers)
+   *
    * ```ts
-   * import { subtract } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(subtract(2, 3), -1)
+   * assert.deepStrictEqual(Number.subtract(2, 3), -1)
    * ```
    *
    * @category math
@@ -175,12 +185,13 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `number`s.
    *
-   * @example
+   * **Example** (Subtracting numbers)
+   *
    * ```ts
-   * import { subtract } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(subtract(2, 3), -1)
+   * assert.deepStrictEqual(Number.subtract(2, 3), -1)
    * ```
    *
    * @category math
@@ -194,7 +205,7 @@ export const subtract: {
  *
  * Returns `Option.none()` if the divisor is `0`.
  *
- * **Example**
+ * **Example** (Dividing numbers safely)
  *
  * ```ts
  * import { Number } from "effect"
@@ -212,7 +223,7 @@ export const divide: {
    *
    * Returns `Option.none()` if the divisor is `0`.
    *
-   * **Example**
+   * **Example** (Dividing numbers safely)
    *
    * ```ts
    * import { Number } from "effect"
@@ -230,7 +241,7 @@ export const divide: {
    *
    * Returns `Option.none()` if the divisor is `0`.
    *
-   * **Example**
+   * **Example** (Dividing numbers safely)
    *
    * ```ts
    * import { Number } from "effect"
@@ -253,17 +264,18 @@ export const divide: {
  *
  * Throws a `RangeError` if the divisor is `0`.
  *
- * **Example**
+ * **Example** (Dividing numbers unsafely)
  *
  * ```ts
  * import { Number } from "effect"
  *
- * Number.divideUnsafe(6, 3) // 2
- * Number.divideUnsafe(6, 0) // throws RangeError("Division by zero")
+ * console.log(Number.divideUnsafe(6, 3)) // 2
+ *
+ * // Passing 0 as the divisor throws a RangeError("Division by zero").
  * ```
  *
  * @category math
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const divideUnsafe: {
   /**
@@ -271,17 +283,18 @@ export const divideUnsafe: {
    *
    * Throws a `RangeError` if the divisor is `0`.
    *
-   * **Example**
+   * **Example** (Dividing numbers unsafely)
    *
    * ```ts
    * import { Number } from "effect"
    *
-   * Number.divideUnsafe(6, 3) // 2
-   * Number.divideUnsafe(6, 0) // throws RangeError("Division by zero")
+   * console.log(Number.divideUnsafe(6, 3)) // 2
+   *
+   * // Passing 0 as the divisor throws a RangeError("Division by zero").
    * ```
    *
    * @category math
-   * @since 2.0.0
+   * @since 4.0.0
    */
   (that: number): (self: number) => number
   /**
@@ -289,17 +302,18 @@ export const divideUnsafe: {
    *
    * Throws a `RangeError` if the divisor is `0`.
    *
-   * **Example**
+   * **Example** (Dividing numbers unsafely)
    *
    * ```ts
    * import { Number } from "effect"
    *
-   * Number.divideUnsafe(6, 3) // 2
-   * Number.divideUnsafe(6, 0) // throws RangeError("Division by zero")
+   * console.log(Number.divideUnsafe(6, 3)) // 2
+   *
+   * // Passing 0 as the divisor throws a RangeError("Division by zero").
    * ```
    *
    * @category math
-   * @since 2.0.0
+   * @since 4.0.0
    */
   (self: number, that: number): number
 } = dual(
@@ -311,12 +325,13 @@ export const divideUnsafe: {
 /**
  * Returns the result of adding `1` to a given number.
  *
- * @example
+ * **Example** (Incrementing a number)
+ *
  * ```ts
- * import { increment } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(increment(2), 3)
+ * assert.deepStrictEqual(Number.increment(2), 3)
  * ```
  *
  * @category math
@@ -327,12 +342,13 @@ export const increment = (n: number): number => n + 1
 /**
  * Decrements a number by `1`.
  *
- * @example
+ * **Example** (Decrementing a number)
+ *
  * ```ts
- * import { decrement } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(decrement(3), 2)
+ * assert.deepStrictEqual(Number.decrement(3), 2)
  * ```
  *
  * @category math
@@ -343,9 +359,10 @@ export const decrement = (n: number): number => n - 1
 /**
  * An `Order` instance for `number` values.
  *
- * @example
+ * **Example** (Comparing numbers)
+ *
  * ```ts
- * import * as Number from "effect/Number"
+ * import { Number } from "effect"
  *
  * console.log(Number.Order(1, 2)) // -1
  * console.log(Number.Order(2, 1)) // 1
@@ -362,7 +379,8 @@ export const Order: order.Order<number> = order.Number
  *
  * `NaN` is considered equal to `NaN`.
  *
- * @example
+ * **Example** (Comparing numbers for equivalence)
+ *
  * ```ts
  * import { Number } from "effect"
  *
@@ -372,59 +390,62 @@ export const Order: order.Order<number> = order.Number
  * ```
  *
  * @category instances
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const Equivalence: Equ.Equivalence<number> = Equ.Number
 
 /**
  * Returns `true` if the first argument is less than the second, otherwise `false`.
  *
- * @example
+ * **Example** (Checking less-than comparisons)
+ *
  * ```ts
- * import { isLessThan } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isLessThan(2, 3), true)
- * assert.deepStrictEqual(isLessThan(3, 3), false)
- * assert.deepStrictEqual(isLessThan(4, 3), false)
+ * assert.deepStrictEqual(Number.isLessThan(2, 3), true)
+ * assert.deepStrictEqual(Number.isLessThan(3, 3), false)
+ * assert.deepStrictEqual(Number.isLessThan(4, 3), false)
  * ```
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isLessThan: {
   /**
    * Returns `true` if the first argument is less than the second, otherwise `false`.
    *
-   * @example
+   * **Example** (Checking less-than comparisons)
+   *
    * ```ts
-   * import { isLessThan } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(isLessThan(2, 3), true)
-   * assert.deepStrictEqual(isLessThan(3, 3), false)
-   * assert.deepStrictEqual(isLessThan(4, 3), false)
+   * assert.deepStrictEqual(Number.isLessThan(2, 3), true)
+   * assert.deepStrictEqual(Number.isLessThan(3, 3), false)
+   * assert.deepStrictEqual(Number.isLessThan(4, 3), false)
    * ```
    *
    * @category predicates
-   * @since 2.0.0
+   * @since 4.0.0
    */
   (that: number): (self: number) => boolean
   /**
    * Returns `true` if the first argument is less than the second, otherwise `false`.
    *
-   * @example
+   * **Example** (Checking less-than comparisons)
+   *
    * ```ts
-   * import { isLessThan } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(isLessThan(2, 3), true)
-   * assert.deepStrictEqual(isLessThan(3, 3), false)
-   * assert.deepStrictEqual(isLessThan(4, 3), false)
+   * assert.deepStrictEqual(Number.isLessThan(2, 3), true)
+   * assert.deepStrictEqual(Number.isLessThan(3, 3), false)
+   * assert.deepStrictEqual(Number.isLessThan(4, 3), false)
    * ```
    *
    * @category predicates
-   * @since 2.0.0
+   * @since 4.0.0
    */
   (self: number, that: number): boolean
 } = order.isLessThan(Order)
@@ -432,52 +453,55 @@ export const isLessThan: {
 /**
  * Returns a function that checks if a given `number` is less than or equal to the provided one.
  *
- * @example
+ * **Example** (Checking less-than-or-equal comparisons)
+ *
  * ```ts
- * import { isLessThanOrEqualTo } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isLessThanOrEqualTo(2, 3), true)
- * assert.deepStrictEqual(isLessThanOrEqualTo(3, 3), true)
- * assert.deepStrictEqual(isLessThanOrEqualTo(4, 3), false)
+ * assert.deepStrictEqual(Number.isLessThanOrEqualTo(2, 3), true)
+ * assert.deepStrictEqual(Number.isLessThanOrEqualTo(3, 3), true)
+ * assert.deepStrictEqual(Number.isLessThanOrEqualTo(4, 3), false)
  * ```
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isLessThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `number` is less than or equal to the provided one.
    *
-   * @example
+   * **Example** (Checking less-than-or-equal comparisons)
+   *
    * ```ts
-   * import { isLessThanOrEqualTo } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(isLessThanOrEqualTo(2, 3), true)
-   * assert.deepStrictEqual(isLessThanOrEqualTo(3, 3), true)
-   * assert.deepStrictEqual(isLessThanOrEqualTo(4, 3), false)
+   * assert.deepStrictEqual(Number.isLessThanOrEqualTo(2, 3), true)
+   * assert.deepStrictEqual(Number.isLessThanOrEqualTo(3, 3), true)
+   * assert.deepStrictEqual(Number.isLessThanOrEqualTo(4, 3), false)
    * ```
    *
    * @category predicates
-   * @since 2.0.0
+   * @since 4.0.0
    */
   (that: number): (self: number) => boolean
   /**
    * Returns a function that checks if a given `number` is less than or equal to the provided one.
    *
-   * @example
+   * **Example** (Checking less-than-or-equal comparisons)
+   *
    * ```ts
-   * import { isLessThanOrEqualTo } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(isLessThanOrEqualTo(2, 3), true)
-   * assert.deepStrictEqual(isLessThanOrEqualTo(3, 3), true)
-   * assert.deepStrictEqual(isLessThanOrEqualTo(4, 3), false)
+   * assert.deepStrictEqual(Number.isLessThanOrEqualTo(2, 3), true)
+   * assert.deepStrictEqual(Number.isLessThanOrEqualTo(3, 3), true)
+   * assert.deepStrictEqual(Number.isLessThanOrEqualTo(4, 3), false)
    * ```
    *
    * @category predicates
-   * @since 2.0.0
+   * @since 4.0.0
    */
   (self: number, that: number): boolean
 } = order.isLessThanOrEqualTo(Order)
@@ -485,52 +509,55 @@ export const isLessThanOrEqualTo: {
 /**
  * Returns `true` if the first argument is greater than the second, otherwise `false`.
  *
- * @example
+ * **Example** (Checking greater-than comparisons)
+ *
  * ```ts
- * import { isGreaterThan } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isGreaterThan(2, 3), false)
- * assert.deepStrictEqual(isGreaterThan(3, 3), false)
- * assert.deepStrictEqual(isGreaterThan(4, 3), true)
+ * assert.deepStrictEqual(Number.isGreaterThan(2, 3), false)
+ * assert.deepStrictEqual(Number.isGreaterThan(3, 3), false)
+ * assert.deepStrictEqual(Number.isGreaterThan(4, 3), true)
  * ```
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isGreaterThan: {
   /**
    * Returns `true` if the first argument is greater than the second, otherwise `false`.
    *
-   * @example
+   * **Example** (Checking greater-than comparisons)
+   *
    * ```ts
-   * import { isGreaterThan } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(isGreaterThan(2, 3), false)
-   * assert.deepStrictEqual(isGreaterThan(3, 3), false)
-   * assert.deepStrictEqual(isGreaterThan(4, 3), true)
+   * assert.deepStrictEqual(Number.isGreaterThan(2, 3), false)
+   * assert.deepStrictEqual(Number.isGreaterThan(3, 3), false)
+   * assert.deepStrictEqual(Number.isGreaterThan(4, 3), true)
    * ```
    *
    * @category predicates
-   * @since 2.0.0
+   * @since 4.0.0
    */
   (that: number): (self: number) => boolean
   /**
    * Returns `true` if the first argument is greater than the second, otherwise `false`.
    *
-   * @example
+   * **Example** (Checking greater-than comparisons)
+   *
    * ```ts
-   * import { isGreaterThan } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(isGreaterThan(2, 3), false)
-   * assert.deepStrictEqual(isGreaterThan(3, 3), false)
-   * assert.deepStrictEqual(isGreaterThan(4, 3), true)
+   * assert.deepStrictEqual(Number.isGreaterThan(2, 3), false)
+   * assert.deepStrictEqual(Number.isGreaterThan(3, 3), false)
+   * assert.deepStrictEqual(Number.isGreaterThan(4, 3), true)
    * ```
    *
    * @category predicates
-   * @since 2.0.0
+   * @since 4.0.0
    */
   (self: number, that: number): boolean
 } = order.isGreaterThan(Order)
@@ -538,52 +565,55 @@ export const isGreaterThan: {
 /**
  * Returns a function that checks if a given `number` is greater than or equal to the provided one.
  *
- * @example
+ * **Example** (Checking greater-than-or-equal comparisons)
+ *
  * ```ts
- * import { isGreaterThanOrEqualTo } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isGreaterThanOrEqualTo(2, 3), false)
- * assert.deepStrictEqual(isGreaterThanOrEqualTo(3, 3), true)
- * assert.deepStrictEqual(isGreaterThanOrEqualTo(4, 3), true)
+ * assert.deepStrictEqual(Number.isGreaterThanOrEqualTo(2, 3), false)
+ * assert.deepStrictEqual(Number.isGreaterThanOrEqualTo(3, 3), true)
+ * assert.deepStrictEqual(Number.isGreaterThanOrEqualTo(4, 3), true)
  * ```
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isGreaterThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `number` is greater than or equal to the provided one.
    *
-   * @example
+   * **Example** (Checking greater-than-or-equal comparisons)
+   *
    * ```ts
-   * import { isGreaterThanOrEqualTo } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(isGreaterThanOrEqualTo(2, 3), false)
-   * assert.deepStrictEqual(isGreaterThanOrEqualTo(3, 3), true)
-   * assert.deepStrictEqual(isGreaterThanOrEqualTo(4, 3), true)
+   * assert.deepStrictEqual(Number.isGreaterThanOrEqualTo(2, 3), false)
+   * assert.deepStrictEqual(Number.isGreaterThanOrEqualTo(3, 3), true)
+   * assert.deepStrictEqual(Number.isGreaterThanOrEqualTo(4, 3), true)
    * ```
    *
    * @category predicates
-   * @since 2.0.0
+   * @since 4.0.0
    */
   (that: number): (self: number) => boolean
   /**
    * Returns a function that checks if a given `number` is greater than or equal to the provided one.
    *
-   * @example
+   * **Example** (Checking greater-than-or-equal comparisons)
+   *
    * ```ts
-   * import { isGreaterThanOrEqualTo } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(isGreaterThanOrEqualTo(2, 3), false)
-   * assert.deepStrictEqual(isGreaterThanOrEqualTo(3, 3), true)
-   * assert.deepStrictEqual(isGreaterThanOrEqualTo(4, 3), true)
+   * assert.deepStrictEqual(Number.isGreaterThanOrEqualTo(2, 3), false)
+   * assert.deepStrictEqual(Number.isGreaterThanOrEqualTo(3, 3), true)
+   * assert.deepStrictEqual(Number.isGreaterThanOrEqualTo(4, 3), true)
    * ```
    *
    * @category predicates
-   * @since 2.0.0
+   * @since 4.0.0
    */
   (self: number, that: number): boolean
 } = order.isGreaterThanOrEqualTo(Order)
@@ -591,9 +621,10 @@ export const isGreaterThanOrEqualTo: {
 /**
  * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
  *
- * @example
+ * **Example** (Checking inclusive ranges)
+ *
  * ```ts
- * import * as Number from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
  * const between = Number.between({ minimum: 0, maximum: 5 })
@@ -610,9 +641,10 @@ export const between: {
   /**
    * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
    *
-   * @example
+   * **Example** (Checking inclusive ranges)
+   *
    * ```ts
-   * import * as Number from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
    * const between = Number.between({ minimum: 0, maximum: 5 })
@@ -634,9 +666,10 @@ export const between: {
   /**
    * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
    *
-   * @example
+   * **Example** (Checking inclusive ranges)
+   *
    * ```ts
-   * import * as Number from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
    * const between = Number.between({ minimum: 0, maximum: 5 })
@@ -665,9 +698,10 @@ export const between: {
  * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
  * - Otherwise, it returns the original `number`.
  *
- * @example
+ * **Example** (Clamping to a range)
+ *
  * ```ts
- * import * as Number from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
  * const clamp = Number.clamp({ minimum: 1, maximum: 5 })
@@ -688,9 +722,10 @@ export const clamp: {
    * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
    * - Otherwise, it returns the original `number`.
    *
-   * @example
+   * **Example** (Clamping to a range)
+   *
    * ```ts
-   * import * as Number from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
    * const clamp = Number.clamp({ minimum: 1, maximum: 5 })
@@ -716,9 +751,10 @@ export const clamp: {
    * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
    * - Otherwise, it returns the original `number`.
    *
-   * @example
+   * **Example** (Clamping to a range)
+   *
    * ```ts
-   * import * as Number from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
    * const clamp = Number.clamp({ minimum: 1, maximum: 5 })
@@ -743,12 +779,13 @@ export const clamp: {
 /**
  * Returns the minimum between two `number`s.
  *
- * @example
+ * **Example** (Finding the minimum)
+ *
  * ```ts
- * import { min } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(min(2, 3), 2)
+ * assert.deepStrictEqual(Number.min(2, 3), 2)
  * ```
  *
  * @category math
@@ -758,12 +795,13 @@ export const min: {
   /**
    * Returns the minimum between two `number`s.
    *
-   * @example
+   * **Example** (Finding the minimum)
+   *
    * ```ts
-   * import { min } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(min(2, 3), 2)
+   * assert.deepStrictEqual(Number.min(2, 3), 2)
    * ```
    *
    * @category math
@@ -773,12 +811,13 @@ export const min: {
   /**
    * Returns the minimum between two `number`s.
    *
-   * @example
+   * **Example** (Finding the minimum)
+   *
    * ```ts
-   * import { min } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(min(2, 3), 2)
+   * assert.deepStrictEqual(Number.min(2, 3), 2)
    * ```
    *
    * @category math
@@ -790,12 +829,13 @@ export const min: {
 /**
  * Returns the maximum between two `number`s.
  *
- * @example
+ * **Example** (Finding the maximum)
+ *
  * ```ts
- * import { max } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(max(2, 3), 3)
+ * assert.deepStrictEqual(Number.max(2, 3), 3)
  * ```
  *
  * @category math
@@ -805,12 +845,13 @@ export const max: {
   /**
    * Returns the maximum between two `number`s.
    *
-   * @example
+   * **Example** (Finding the maximum)
+   *
    * ```ts
-   * import { max } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(max(2, 3), 3)
+   * assert.deepStrictEqual(Number.max(2, 3), 3)
    * ```
    *
    * @category math
@@ -820,12 +861,13 @@ export const max: {
   /**
    * Returns the maximum between two `number`s.
    *
-   * @example
+   * **Example** (Finding the maximum)
+   *
    * ```ts
-   * import { max } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(max(2, 3), 3)
+   * assert.deepStrictEqual(Number.max(2, 3), 3)
    * ```
    *
    * @category math
@@ -837,14 +879,15 @@ export const max: {
 /**
  * Determines the sign of a given `number`.
  *
- * @example
+ * **Example** (Determining the sign)
+ *
  * ```ts
- * import { sign } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(sign(-5), -1)
- * assert.deepStrictEqual(sign(0), 0)
- * assert.deepStrictEqual(sign(5), 1)
+ * assert.deepStrictEqual(Number.sign(-5), -1)
+ * assert.deepStrictEqual(Number.sign(0), 0)
+ * assert.deepStrictEqual(Number.sign(5), 1)
  * ```
  *
  * @category math
@@ -855,12 +898,13 @@ export const sign = (n: number): Ordering => Order(n, 0)
 /**
  * Takes an `Iterable` of `number`s and returns their sum as a single `number`.
  *
- * @example
+ * **Example** (Summing an iterable)
+ *
  * ```ts
- * import { sumAll } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(sumAll([2, 3, 4]), 9)
+ * assert.deepStrictEqual(Number.sumAll([2, 3, 4]), 9)
  * ```
  *
  * @category math
@@ -877,12 +921,13 @@ export const sumAll = (collection: Iterable<number>): number => {
 /**
  * Takes an `Iterable` of `number`s and returns their multiplication as a single `number`.
  *
- * @example
+ * **Example** (Multiplying an iterable)
+ *
  * ```ts
- * import { multiplyAll } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(multiplyAll([2, 3, 4]), 24)
+ * assert.deepStrictEqual(Number.multiplyAll([2, 3, 4]), 24)
  * ```
  *
  * @category math
@@ -904,14 +949,15 @@ export const multiplyAll = (collection: Iterable<number>): number => {
  *
  * It always takes the sign of the dividend.
  *
- * @example
+ * **Example** (Calculating remainders)
+ *
  * ```ts
- * import { remainder } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(remainder(2, 2), 0)
- * assert.deepStrictEqual(remainder(3, 2), 1)
- * assert.deepStrictEqual(remainder(-4, 2), -0)
+ * assert.deepStrictEqual(Number.remainder(2, 2), 0)
+ * assert.deepStrictEqual(Number.remainder(3, 2), 1)
+ * assert.deepStrictEqual(Number.remainder(-4, 2), -0)
  * ```
  *
  * @category math
@@ -923,14 +969,15 @@ export const remainder: {
    *
    * It always takes the sign of the dividend.
    *
-   * @example
+   * **Example** (Calculating remainders)
+   *
    * ```ts
-   * import { remainder } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(remainder(2, 2), 0)
-   * assert.deepStrictEqual(remainder(3, 2), 1)
-   * assert.deepStrictEqual(remainder(-4, 2), -0)
+   * assert.deepStrictEqual(Number.remainder(2, 2), 0)
+   * assert.deepStrictEqual(Number.remainder(3, 2), 1)
+   * assert.deepStrictEqual(Number.remainder(-4, 2), -0)
    * ```
    *
    * @category math
@@ -942,14 +989,15 @@ export const remainder: {
    *
    * It always takes the sign of the dividend.
    *
-   * @example
+   * **Example** (Calculating remainders)
+   *
    * ```ts
-   * import { remainder } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(remainder(2, 2), 0)
-   * assert.deepStrictEqual(remainder(3, 2), 1)
-   * assert.deepStrictEqual(remainder(-4, 2), -0)
+   * assert.deepStrictEqual(Number.remainder(2, 2), 0)
+   * assert.deepStrictEqual(Number.remainder(3, 2), 1)
+   * assert.deepStrictEqual(Number.remainder(-4, 2), -0)
    * ```
    *
    * @category math
@@ -979,13 +1027,14 @@ function decimalCount(n: number): number {
 /**
  * Returns the next power of 2 from the given number.
  *
- * @example
+ * **Example** (Finding the next power of two)
+ *
  * ```ts
- * import { nextPow2 } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(nextPow2(5), 8)
- * assert.deepStrictEqual(nextPow2(17), 32)
+ * assert.deepStrictEqual(Number.nextPow2(5), 8)
+ * assert.deepStrictEqual(Number.nextPow2(17), 32)
  * ```
  *
  * @category math
@@ -1000,7 +1049,7 @@ export const nextPow2 = (n: number): number => {
  * Tries to parse a `number` from a `string` using the `Number()` function.
  * The following special string values are supported: "NaN", "Infinity", "-Infinity".
  *
- * **Example**
+ * **Example** (Parsing numbers from strings)
  *
  * ```ts
  * import { Number } from "effect"
@@ -1036,13 +1085,14 @@ export const parse = (s: string): Option.Option<number> => {
 /**
  * Returns the number rounded with the given precision.
  *
- * @example
+ * **Example** (Rounding with precision)
+ *
  * ```ts
- * import { round } from "effect/Number"
+ * import { Number } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(round(1.1234, 2), 1.12)
- * assert.deepStrictEqual(round(1.567, 2), 1.57)
+ * assert.deepStrictEqual(Number.round(1.1234, 2), 1.12)
+ * assert.deepStrictEqual(Number.round(1.567, 2), 1.57)
  * ```
  *
  * @category math
@@ -1052,13 +1102,14 @@ export const round: {
   /**
    * Returns the number rounded with the given precision.
    *
-   * @example
+   * **Example** (Rounding with precision)
+   *
    * ```ts
-   * import { round } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(round(1.1234, 2), 1.12)
-   * assert.deepStrictEqual(round(1.567, 2), 1.57)
+   * assert.deepStrictEqual(Number.round(1.1234, 2), 1.12)
+   * assert.deepStrictEqual(Number.round(1.567, 2), 1.57)
    * ```
    *
    * @category math
@@ -1068,13 +1119,14 @@ export const round: {
   /**
    * Returns the number rounded with the given precision.
    *
-   * @example
+   * **Example** (Rounding with precision)
+   *
    * ```ts
-   * import { round } from "effect/Number"
+   * import { Number } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(round(1.1234, 2), 1.12)
-   * assert.deepStrictEqual(round(1.567, 2), 1.57)
+   * assert.deepStrictEqual(Number.round(1.1234, 2), 1.12)
+   * assert.deepStrictEqual(Number.round(1.567, 2), 1.57)
    * ```
    *
    * @category math
@@ -1089,6 +1141,7 @@ export const round: {
 /**
  * A `Reducer` for combining `number`s using addition.
  *
+ * @category math
  * @since 4.0.0
  */
 export const ReducerSum: Reducer.Reducer<number> = Reducer.make((a, b) => a + b, 0)
@@ -1096,6 +1149,7 @@ export const ReducerSum: Reducer.Reducer<number> = Reducer.make((a, b) => a + b,
 /**
  * A `Reducer` for combining `number`s using multiplication.
  *
+ * @category math
  * @since 4.0.0
  */
 export const ReducerMultiply: Reducer.Reducer<number> = Reducer.make((a, b) => a * b, 1, (collection) => {
@@ -1108,15 +1162,17 @@ export const ReducerMultiply: Reducer.Reducer<number> = Reducer.make((a, b) => a
 })
 
 /**
- * A `Combiner` that returns the maximum `number`.
+ * A `Reducer` for reducing `number`s by keeping the maximum value.
  *
+ * @category math
  * @since 4.0.0
  */
 export const ReducerMax: Reducer.Reducer<number> = Reducer.make((a, b) => Math.max(a, b), -Infinity)
 
 /**
- * A `Combiner` that returns the minimum `number`.
+ * A `Reducer` for reducing `number`s by keeping the minimum value.
  *
+ * @category math
  * @since 4.0.0
  */
 export const ReducerMin: Reducer.Reducer<number> = Reducer.make((a, b) => Math.min(a, b), Infinity)