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

package/dist/BigInt.d.ts

@@ -13,9 +13,10 @@ import * as Reducer from "./Reducer.ts";
 /**
  * Reference to the global BigInt constructor.
  *
- * @example
+ * **Example** (Constructing bigints)
+ *
  * ```ts
- * import * as BigInt from "effect/BigInt"
+ * import { BigInt } from "effect"
  *
  * const bigInt = BigInt.BigInt(123)
  * console.log(bigInt) // 123n
@@ -31,13 +32,14 @@ export declare const BigInt: BigIntConstructor;
 /**
  * Tests if a value is a `bigint`.
  *
- * @example
+ * **Example** (Checking for bigints)
+ *
  * ```ts
- * import { isBigInt } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isBigInt(1n), true)
- * assert.deepStrictEqual(isBigInt(1), false)
+ * assert.deepStrictEqual(BigInt.isBigInt(1n), true)
+ * assert.deepStrictEqual(BigInt.isBigInt(1), false)
  * ```
  *
  * @category guards
@@ -47,12 +49,13 @@ export declare const isBigInt: (u: unknown) => u is bigint;
 /**
  * Provides an addition operation on `bigint`s.
  *
- * @example
+ * **Example** (Adding bigints)
+ *
  * ```ts
- * import { sum } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(sum(2n, 3n), 5n)
+ * assert.deepStrictEqual(BigInt.sum(2n, 3n), 5n)
  * ```
  *
  * @category math
@@ -62,12 +65,13 @@ export declare const sum: {
     /**
      * Provides an addition operation on `bigint`s.
      *
-     * @example
+     * **Example** (Adding bigints)
+     *
      * ```ts
-     * import { sum } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(sum(2n, 3n), 5n)
+     * assert.deepStrictEqual(BigInt.sum(2n, 3n), 5n)
      * ```
      *
      * @category math
@@ -77,12 +81,13 @@ export declare const sum: {
     /**
      * Provides an addition operation on `bigint`s.
      *
-     * @example
+     * **Example** (Adding bigints)
+     *
      * ```ts
-     * import { sum } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(sum(2n, 3n), 5n)
+     * assert.deepStrictEqual(BigInt.sum(2n, 3n), 5n)
      * ```
      *
      * @category math
@@ -93,12 +98,13 @@ export declare const sum: {
 /**
  * Provides a multiplication operation on `bigint`s.
  *
- * @example
+ * **Example** (Multiplying bigints)
+ *
  * ```ts
- * import { multiply } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(multiply(2n, 3n), 6n)
+ * assert.deepStrictEqual(BigInt.multiply(2n, 3n), 6n)
  * ```
  *
  * @category math
@@ -108,12 +114,13 @@ export declare const multiply: {
     /**
      * Provides a multiplication operation on `bigint`s.
      *
-     * @example
+     * **Example** (Multiplying bigints)
+     *
      * ```ts
-     * import { multiply } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(multiply(2n, 3n), 6n)
+     * assert.deepStrictEqual(BigInt.multiply(2n, 3n), 6n)
      * ```
      *
      * @category math
@@ -123,12 +130,13 @@ export declare const multiply: {
     /**
      * Provides a multiplication operation on `bigint`s.
      *
-     * @example
+     * **Example** (Multiplying bigints)
+     *
      * ```ts
-     * import { multiply } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(multiply(2n, 3n), 6n)
+     * assert.deepStrictEqual(BigInt.multiply(2n, 3n), 6n)
      * ```
      *
      * @category math
@@ -139,12 +147,13 @@ export declare const multiply: {
 /**
  * Provides a subtraction operation on `bigint`s.
  *
- * @example
+ * **Example** (Subtracting bigints)
+ *
  * ```ts
- * import { subtract } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(subtract(2n, 3n), -1n)
+ * assert.deepStrictEqual(BigInt.subtract(2n, 3n), -1n)
  * ```
  *
  * @category math
@@ -154,12 +163,13 @@ export declare const subtract: {
     /**
      * Provides a subtraction operation on `bigint`s.
      *
-     * @example
+     * **Example** (Subtracting bigints)
+     *
      * ```ts
-     * import { subtract } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(subtract(2n, 3n), -1n)
+     * assert.deepStrictEqual(BigInt.subtract(2n, 3n), -1n)
      * ```
      *
      * @category math
@@ -169,12 +179,13 @@ export declare const subtract: {
     /**
      * Provides a subtraction operation on `bigint`s.
      *
-     * @example
+     * **Example** (Subtracting bigints)
+     *
      * ```ts
-     * import { subtract } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(subtract(2n, 3n), -1n)
+     * assert.deepStrictEqual(BigInt.subtract(2n, 3n), -1n)
      * ```
      *
      * @category math
@@ -183,22 +194,19 @@ export declare const subtract: {
     (self: bigint, that: bigint): bigint;
 };
 /**
- * Provides a division operation on `bigint`s.
+ * Safely divides one `bigint` by another.
  *
- * If the dividend is not a multiple of the divisor the result will be a `bigint` value
- * which represents the integer division rounded down to the nearest integer.
+ * Uses JavaScript `bigint` division, so non-exact quotients are truncated
+ * toward zero. Returns `Option.none()` when the divisor is `0n`.
  *
- * Returns `Option.none()` if the divisor is `0n`.
+ * **Example** (Dividing bigints safely)
  *
- * @example
  * ```ts
- * import { divide } from "effect/BigInt"
+ * import { BigInt, Option } from "effect"
  * import * as assert from "node:assert"
  *
- * import { Option } from "effect"
- *
- * assert.deepStrictEqual(divide(6n, 3n), Option.some(2n))
- * assert.deepStrictEqual(divide(6n, 0n), Option.none())
+ * assert.deepStrictEqual(BigInt.divide(6n, 3n), Option.some(2n))
+ * assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
  * ```
  *
  * @category math
@@ -206,22 +214,19 @@ export declare const subtract: {
  */
 export declare const divide: {
     /**
-     * Provides a division operation on `bigint`s.
+     * Safely divides one `bigint` by another.
      *
-     * If the dividend is not a multiple of the divisor the result will be a `bigint` value
-     * which represents the integer division rounded down to the nearest integer.
+     * Uses JavaScript `bigint` division, so non-exact quotients are truncated
+     * toward zero. Returns `Option.none()` when the divisor is `0n`.
      *
-     * Returns `Option.none()` if the divisor is `0n`.
+     * **Example** (Dividing bigints safely)
      *
-     * @example
      * ```ts
-     * import { divide } from "effect/BigInt"
+     * import { BigInt, Option } from "effect"
      * import * as assert from "node:assert"
      *
-     * import { Option } from "effect"
-     *
-     * assert.deepStrictEqual(divide(6n, 3n), Option.some(2n))
-     * assert.deepStrictEqual(divide(6n, 0n), Option.none())
+     * assert.deepStrictEqual(BigInt.divide(6n, 3n), Option.some(2n))
+     * assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
      * ```
      *
      * @category math
@@ -229,22 +234,19 @@ export declare const divide: {
      */
     (that: bigint): (self: bigint) => Option.Option<bigint>;
     /**
-     * Provides a division operation on `bigint`s.
+     * Safely divides one `bigint` by another.
      *
-     * If the dividend is not a multiple of the divisor the result will be a `bigint` value
-     * which represents the integer division rounded down to the nearest integer.
+     * Uses JavaScript `bigint` division, so non-exact quotients are truncated
+     * toward zero. Returns `Option.none()` when the divisor is `0n`.
      *
-     * Returns `Option.none()` if the divisor is `0n`.
+     * **Example** (Dividing bigints safely)
      *
-     * @example
      * ```ts
-     * import { divide } from "effect/BigInt"
+     * import { BigInt, Option } from "effect"
      * import * as assert from "node:assert"
      *
-     * import { Option } from "effect"
-     *
-     * assert.deepStrictEqual(divide(6n, 3n), Option.some(2n))
-     * assert.deepStrictEqual(divide(6n, 0n), Option.none())
+     * assert.deepStrictEqual(BigInt.divide(6n, 3n), Option.some(2n))
+     * assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
      * ```
      *
      * @category math
@@ -253,78 +255,76 @@ export declare const divide: {
     (self: bigint, that: bigint): Option.Option<bigint>;
 };
 /**
- * Provides a division operation on `bigint`s.
+ * Divides one `bigint` by another, throwing if the divisor is zero.
  *
- * If the dividend is not a multiple of the divisor the result will be a `bigint` value
- * which represents the integer division rounded down to the nearest integer.
+ * Uses JavaScript `bigint` division, so non-exact quotients are truncated
+ * toward zero. Throws a `RangeError` when the divisor is `0n`.
  *
- * Throws a `RangeError` if the divisor is `0n`.
+ * **Example** (Dividing bigints unsafely)
  *
- * @example
  * ```ts
- * import { divideUnsafe } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(divideUnsafe(6n, 3n), 2n)
- * assert.deepStrictEqual(divideUnsafe(6n, 4n), 1n)
+ * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 3n), 2n)
+ * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 4n), 1n)
  * ```
  *
  * @category math
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const divideUnsafe: {
     /**
-     * Provides a division operation on `bigint`s.
+     * Divides one `bigint` by another, throwing if the divisor is zero.
      *
-     * If the dividend is not a multiple of the divisor the result will be a `bigint` value
-     * which represents the integer division rounded down to the nearest integer.
+     * Uses JavaScript `bigint` division, so non-exact quotients are truncated
+     * toward zero. Throws a `RangeError` when the divisor is `0n`.
      *
-     * Throws a `RangeError` if the divisor is `0n`.
+     * **Example** (Dividing bigints unsafely)
      *
-     * @example
      * ```ts
-     * import { divideUnsafe } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(divideUnsafe(6n, 3n), 2n)
-     * assert.deepStrictEqual(divideUnsafe(6n, 4n), 1n)
+     * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 3n), 2n)
+     * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 4n), 1n)
      * ```
      *
      * @category math
-     * @since 2.0.0
+     * @since 4.0.0
      */
     (that: bigint): (self: bigint) => bigint;
     /**
-     * Provides a division operation on `bigint`s.
+     * Divides one `bigint` by another, throwing if the divisor is zero.
      *
-     * If the dividend is not a multiple of the divisor the result will be a `bigint` value
-     * which represents the integer division rounded down to the nearest integer.
+     * Uses JavaScript `bigint` division, so non-exact quotients are truncated
+     * toward zero. Throws a `RangeError` when the divisor is `0n`.
      *
-     * Throws a `RangeError` if the divisor is `0n`.
+     * **Example** (Dividing bigints unsafely)
      *
-     * @example
      * ```ts
-     * import { divideUnsafe } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(divideUnsafe(6n, 3n), 2n)
-     * assert.deepStrictEqual(divideUnsafe(6n, 4n), 1n)
+     * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 3n), 2n)
+     * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 4n), 1n)
      * ```
      *
      * @category math
-     * @since 2.0.0
+     * @since 4.0.0
      */
     (self: bigint, that: bigint): bigint;
 };
 /**
- * Returns the result of adding `1n` to a given number.
+ * Returns the result of adding `1n` to a `bigint`.
+ *
+ * **Example** (Incrementing a bigint)
  *
- * @example
  * ```ts
- * import { increment } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(increment(2n), 3n)
+ * assert.deepStrictEqual(BigInt.increment(2n), 3n)
  * ```
  *
  * @category math
@@ -332,14 +332,15 @@ export declare const divideUnsafe: {
  */
 export declare const increment: (n: bigint) => bigint;
 /**
- * Decrements a number by `1n`.
+ * Returns the result of subtracting `1n` from a `bigint`.
+ *
+ * **Example** (Decrementing a bigint)
  *
- * @example
  * ```ts
- * import { decrement } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(decrement(3n), 2n)
+ * assert.deepStrictEqual(BigInt.decrement(3n), 2n)
  * ```
  *
  * @category math
@@ -349,9 +350,10 @@ export declare const decrement: (n: bigint) => bigint;
 /**
  * Provides an `Order` instance for `bigint` that allows comparing and sorting BigInt values.
  *
- * @example
+ * **Example** (Comparing bigints with Order)
+ *
  * ```ts
- * import * as BigInt from "effect/BigInt"
+ * import { BigInt } from "effect"
  *
  * const a = 123n
  * const b = 456n
@@ -369,7 +371,8 @@ export declare const Order: order.Order<bigint>;
 /**
  * An `Equivalence` instance for bigints using strict equality (`===`).
  *
- * @example
+ * **Example** (Comparing bigints for equivalence)
+ *
  * ```ts
  * import { BigInt } from "effect"
  *
@@ -378,223 +381,236 @@ export declare const Order: order.Order<bigint>;
  * ```
  *
  * @category instances
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare const Equivalence: Equ.Equivalence<bigint>;
 /**
  * Returns `true` if the first argument is less than the second, otherwise `false`.
  *
- * @example
+ * **Example** (Checking less-than comparisons)
+ *
  * ```ts
- * import { isLessThan } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isLessThan(2n, 3n), true)
- * assert.deepStrictEqual(isLessThan(3n, 3n), false)
- * assert.deepStrictEqual(isLessThan(4n, 3n), false)
+ * assert.deepStrictEqual(BigInt.isLessThan(2n, 3n), true)
+ * assert.deepStrictEqual(BigInt.isLessThan(3n, 3n), false)
+ * assert.deepStrictEqual(BigInt.isLessThan(4n, 3n), false)
  * ```
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare 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/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(isLessThan(2n, 3n), true)
-     * assert.deepStrictEqual(isLessThan(3n, 3n), false)
-     * assert.deepStrictEqual(isLessThan(4n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isLessThan(2n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isLessThan(3n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isLessThan(4n, 3n), false)
      * ```
      *
      * @category predicates
-     * @since 2.0.0
+     * @since 4.0.0
      */
     (that: bigint): (self: bigint) => 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/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(isLessThan(2n, 3n), true)
-     * assert.deepStrictEqual(isLessThan(3n, 3n), false)
-     * assert.deepStrictEqual(isLessThan(4n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isLessThan(2n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isLessThan(3n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isLessThan(4n, 3n), false)
      * ```
      *
      * @category predicates
-     * @since 2.0.0
+     * @since 4.0.0
      */
     (self: bigint, that: bigint): boolean;
 };
 /**
  * Returns a function that checks if a given `bigint` is less than or equal to the provided one.
  *
- * @example
+ * **Example** (Checking less-than-or-equal comparisons)
+ *
  * ```ts
- * import { isLessThanOrEqualTo } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isLessThanOrEqualTo(2n, 3n), true)
- * assert.deepStrictEqual(isLessThanOrEqualTo(3n, 3n), true)
- * assert.deepStrictEqual(isLessThanOrEqualTo(4n, 3n), false)
+ * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(2n, 3n), true)
+ * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(3n, 3n), true)
+ * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(4n, 3n), false)
  * ```
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const isLessThanOrEqualTo: {
     /**
      * Returns a function that checks if a given `bigint` is less than or equal to the provided one.
      *
-     * @example
+     * **Example** (Checking less-than-or-equal comparisons)
+     *
      * ```ts
-     * import { isLessThanOrEqualTo } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(isLessThanOrEqualTo(2n, 3n), true)
-     * assert.deepStrictEqual(isLessThanOrEqualTo(3n, 3n), true)
-     * assert.deepStrictEqual(isLessThanOrEqualTo(4n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(2n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(3n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(4n, 3n), false)
      * ```
      *
      * @category predicates
-     * @since 2.0.0
+     * @since 4.0.0
      */
     (that: bigint): (self: bigint) => boolean;
     /**
      * Returns a function that checks if a given `bigint` is less than or equal to the provided one.
      *
-     * @example
+     * **Example** (Checking less-than-or-equal comparisons)
+     *
      * ```ts
-     * import { isLessThanOrEqualTo } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(isLessThanOrEqualTo(2n, 3n), true)
-     * assert.deepStrictEqual(isLessThanOrEqualTo(3n, 3n), true)
-     * assert.deepStrictEqual(isLessThanOrEqualTo(4n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(2n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(3n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(4n, 3n), false)
      * ```
      *
      * @category predicates
-     * @since 2.0.0
+     * @since 4.0.0
      */
     (self: bigint, that: bigint): 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/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isGreaterThan(2n, 3n), false)
- * assert.deepStrictEqual(isGreaterThan(3n, 3n), false)
- * assert.deepStrictEqual(isGreaterThan(4n, 3n), true)
+ * assert.deepStrictEqual(BigInt.isGreaterThan(2n, 3n), false)
+ * assert.deepStrictEqual(BigInt.isGreaterThan(3n, 3n), false)
+ * assert.deepStrictEqual(BigInt.isGreaterThan(4n, 3n), true)
  * ```
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare 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/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(isGreaterThan(2n, 3n), false)
-     * assert.deepStrictEqual(isGreaterThan(3n, 3n), false)
-     * assert.deepStrictEqual(isGreaterThan(4n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isGreaterThan(2n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isGreaterThan(3n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isGreaterThan(4n, 3n), true)
      * ```
      *
      * @category predicates
-     * @since 2.0.0
+     * @since 4.0.0
      */
     (that: bigint): (self: bigint) => 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/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(isGreaterThan(2n, 3n), false)
-     * assert.deepStrictEqual(isGreaterThan(3n, 3n), false)
-     * assert.deepStrictEqual(isGreaterThan(4n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isGreaterThan(2n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isGreaterThan(3n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isGreaterThan(4n, 3n), true)
      * ```
      *
      * @category predicates
-     * @since 2.0.0
+     * @since 4.0.0
      */
     (self: bigint, that: bigint): boolean;
 };
 /**
  * Returns a function that checks if a given `bigint` is greater than or equal to the provided one.
  *
- * @example
+ * **Example** (Checking greater-than-or-equal comparisons)
+ *
  * ```ts
- * import { isGreaterThanOrEqualTo } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isGreaterThanOrEqualTo(2n, 3n), false)
- * assert.deepStrictEqual(isGreaterThanOrEqualTo(3n, 3n), true)
- * assert.deepStrictEqual(isGreaterThanOrEqualTo(4n, 3n), true)
+ * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(2n, 3n), false)
+ * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(3n, 3n), true)
+ * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(4n, 3n), true)
  * ```
  *
  * @category predicates
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const isGreaterThanOrEqualTo: {
     /**
      * Returns a function that checks if a given `bigint` is greater than or equal to the provided one.
      *
-     * @example
+     * **Example** (Checking greater-than-or-equal comparisons)
+     *
      * ```ts
-     * import { isGreaterThanOrEqualTo } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(isGreaterThanOrEqualTo(2n, 3n), false)
-     * assert.deepStrictEqual(isGreaterThanOrEqualTo(3n, 3n), true)
-     * assert.deepStrictEqual(isGreaterThanOrEqualTo(4n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(2n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(3n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(4n, 3n), true)
      * ```
      *
      * @category predicates
-     * @since 2.0.0
+     * @since 4.0.0
      */
     (that: bigint): (self: bigint) => boolean;
     /**
      * Returns a function that checks if a given `bigint` is greater than or equal to the provided one.
      *
-     * @example
+     * **Example** (Checking greater-than-or-equal comparisons)
+     *
      * ```ts
-     * import { isGreaterThanOrEqualTo } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(isGreaterThanOrEqualTo(2n, 3n), false)
-     * assert.deepStrictEqual(isGreaterThanOrEqualTo(3n, 3n), true)
-     * assert.deepStrictEqual(isGreaterThanOrEqualTo(4n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(2n, 3n), false)
+     * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(3n, 3n), true)
+     * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(4n, 3n), true)
      * ```
      *
      * @category predicates
-     * @since 2.0.0
+     * @since 4.0.0
      */
     (self: bigint, that: bigint): boolean;
 };
 /**
  * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
  *
- * @example
+ * **Example** (Checking whether a bigint is within bounds)
+ *
  * ```ts
- * import * as BigInt from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
  * const between = BigInt.between({ minimum: 0n, maximum: 5n })
@@ -611,9 +627,10 @@ export declare const between: {
     /**
      * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
      *
-     * @example
+     * **Example** (Checking whether a bigint is within bounds)
+     *
      * ```ts
-     * import * as BigInt from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
      * const between = BigInt.between({ minimum: 0n, maximum: 5n })
@@ -633,9 +650,10 @@ export declare const between: {
     /**
      * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
      *
-     * @example
+     * **Example** (Checking whether a bigint is within bounds)
+     *
      * ```ts
-     * import * as BigInt from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
      * const between = BigInt.between({ minimum: 0n, maximum: 5n })
@@ -660,9 +678,10 @@ export declare const between: {
  * - If the `bigint` is greater than the `maximum` value, the function returns the `maximum` value.
  * - Otherwise, it returns the original `bigint`.
  *
- * @example
+ * **Example** (Clamping a bigint to bounds)
+ *
  * ```ts
- * import * as BigInt from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
  * const clamp = BigInt.clamp({ minimum: 1n, maximum: 5n })
@@ -683,9 +702,10 @@ export declare const clamp: {
      * - If the `bigint` is greater than the `maximum` value, the function returns the `maximum` value.
      * - Otherwise, it returns the original `bigint`.
      *
-     * @example
+     * **Example** (Clamping a bigint to bounds)
+     *
      * ```ts
-     * import * as BigInt from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
      * const clamp = BigInt.clamp({ minimum: 1n, maximum: 5n })
@@ -709,9 +729,10 @@ export declare const clamp: {
      * - If the `bigint` is greater than the `maximum` value, the function returns the `maximum` value.
      * - Otherwise, it returns the original `bigint`.
      *
-     * @example
+     * **Example** (Clamping a bigint to bounds)
+     *
      * ```ts
-     * import * as BigInt from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
      * const clamp = BigInt.clamp({ minimum: 1n, maximum: 5n })
@@ -732,12 +753,13 @@ export declare const clamp: {
 /**
  * Returns the minimum between two `bigint`s.
  *
- * @example
+ * **Example** (Finding the minimum bigint)
+ *
  * ```ts
- * import { min } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(min(2n, 3n), 2n)
+ * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
  * ```
  *
  * @category math
@@ -747,12 +769,13 @@ export declare const min: {
     /**
      * Returns the minimum between two `bigint`s.
      *
-     * @example
+     * **Example** (Finding the minimum bigint)
+     *
      * ```ts
-     * import { min } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(min(2n, 3n), 2n)
+     * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
      * ```
      *
      * @category math
@@ -762,12 +785,13 @@ export declare const min: {
     /**
      * Returns the minimum between two `bigint`s.
      *
-     * @example
+     * **Example** (Finding the minimum bigint)
+     *
      * ```ts
-     * import { min } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(min(2n, 3n), 2n)
+     * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
      * ```
      *
      * @category math
@@ -778,12 +802,13 @@ export declare const min: {
 /**
  * Returns the maximum between two `bigint`s.
  *
- * @example
+ * **Example** (Finding the maximum bigint)
+ *
  * ```ts
- * import { max } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(max(2n, 3n), 3n)
+ * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
  * ```
  *
  * @category math
@@ -793,12 +818,13 @@ export declare const max: {
     /**
      * Returns the maximum between two `bigint`s.
      *
-     * @example
+     * **Example** (Finding the maximum bigint)
+     *
      * ```ts
-     * import { max } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(max(2n, 3n), 3n)
+     * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
      * ```
      *
      * @category math
@@ -808,12 +834,13 @@ export declare const max: {
     /**
      * Returns the maximum between two `bigint`s.
      *
-     * @example
+     * **Example** (Finding the maximum bigint)
+     *
      * ```ts
-     * import { max } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(max(2n, 3n), 3n)
+     * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
      * ```
      *
      * @category math
@@ -824,14 +851,15 @@ export declare const max: {
 /**
  * Determines the sign of a given `bigint`.
  *
- * @example
+ * **Example** (Determining bigint signs)
+ *
  * ```ts
- * import { sign } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(sign(-5n), -1)
- * assert.deepStrictEqual(sign(0n), 0)
- * assert.deepStrictEqual(sign(5n), 1)
+ * assert.deepStrictEqual(BigInt.sign(-5n), -1)
+ * assert.deepStrictEqual(BigInt.sign(0n), 0)
+ * assert.deepStrictEqual(BigInt.sign(5n), 1)
  * ```
  *
  * @category math
@@ -841,14 +869,15 @@ export declare const sign: (n: bigint) => Ordering;
 /**
  * Determines the absolute value of a given `bigint`.
  *
- * @example
+ * **Example** (Calculating absolute values)
+ *
  * ```ts
- * import { abs } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(abs(-5n), 5n)
- * assert.deepStrictEqual(abs(0n), 0n)
- * assert.deepStrictEqual(abs(5n), 5n)
+ * assert.deepStrictEqual(BigInt.abs(-5n), 5n)
+ * assert.deepStrictEqual(BigInt.abs(0n), 0n)
+ * assert.deepStrictEqual(BigInt.abs(5n), 5n)
  * ```
  *
  * @category math
@@ -858,14 +887,15 @@ export declare const abs: (n: bigint) => bigint;
 /**
  * Determines the greatest common divisor of two `bigint`s.
  *
- * @example
+ * **Example** (Calculating greatest common divisors)
+ *
  * ```ts
- * import { gcd } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(gcd(2n, 3n), 1n)
- * assert.deepStrictEqual(gcd(2n, 4n), 2n)
- * assert.deepStrictEqual(gcd(16n, 24n), 8n)
+ * assert.deepStrictEqual(BigInt.gcd(2n, 3n), 1n)
+ * assert.deepStrictEqual(BigInt.gcd(2n, 4n), 2n)
+ * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
  * ```
  *
  * @category math
@@ -875,14 +905,15 @@ export declare const gcd: {
     /**
      * Determines the greatest common divisor of two `bigint`s.
      *
-     * @example
+     * **Example** (Calculating greatest common divisors)
+     *
      * ```ts
-     * import { gcd } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(gcd(2n, 3n), 1n)
-     * assert.deepStrictEqual(gcd(2n, 4n), 2n)
-     * assert.deepStrictEqual(gcd(16n, 24n), 8n)
+     * assert.deepStrictEqual(BigInt.gcd(2n, 3n), 1n)
+     * assert.deepStrictEqual(BigInt.gcd(2n, 4n), 2n)
+     * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
      * ```
      *
      * @category math
@@ -892,14 +923,15 @@ export declare const gcd: {
     /**
      * Determines the greatest common divisor of two `bigint`s.
      *
-     * @example
+     * **Example** (Calculating greatest common divisors)
+     *
      * ```ts
-     * import { gcd } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(gcd(2n, 3n), 1n)
-     * assert.deepStrictEqual(gcd(2n, 4n), 2n)
-     * assert.deepStrictEqual(gcd(16n, 24n), 8n)
+     * assert.deepStrictEqual(BigInt.gcd(2n, 3n), 1n)
+     * assert.deepStrictEqual(BigInt.gcd(2n, 4n), 2n)
+     * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
      * ```
      *
      * @category math
@@ -910,14 +942,15 @@ export declare const gcd: {
 /**
  * Determines the least common multiple of two `bigint`s.
  *
- * @example
+ * **Example** (Calculating least common multiples)
+ *
  * ```ts
- * import { lcm } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(lcm(2n, 3n), 6n)
- * assert.deepStrictEqual(lcm(2n, 4n), 4n)
- * assert.deepStrictEqual(lcm(16n, 24n), 48n)
+ * assert.deepStrictEqual(BigInt.lcm(2n, 3n), 6n)
+ * assert.deepStrictEqual(BigInt.lcm(2n, 4n), 4n)
+ * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
  * ```
  *
  * @category math
@@ -927,14 +960,15 @@ export declare const lcm: {
     /**
      * Determines the least common multiple of two `bigint`s.
      *
-     * @example
+     * **Example** (Calculating least common multiples)
+     *
      * ```ts
-     * import { lcm } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(lcm(2n, 3n), 6n)
-     * assert.deepStrictEqual(lcm(2n, 4n), 4n)
-     * assert.deepStrictEqual(lcm(16n, 24n), 48n)
+     * assert.deepStrictEqual(BigInt.lcm(2n, 3n), 6n)
+     * assert.deepStrictEqual(BigInt.lcm(2n, 4n), 4n)
+     * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
      * ```
      *
      * @category math
@@ -944,14 +978,15 @@ export declare const lcm: {
     /**
      * Determines the least common multiple of two `bigint`s.
      *
-     * @example
+     * **Example** (Calculating least common multiples)
+     *
      * ```ts
-     * import { lcm } from "effect/BigInt"
+     * import { BigInt } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(lcm(2n, 3n), 6n)
-     * assert.deepStrictEqual(lcm(2n, 4n), 4n)
-     * assert.deepStrictEqual(lcm(16n, 24n), 48n)
+     * assert.deepStrictEqual(BigInt.lcm(2n, 3n), 6n)
+     * assert.deepStrictEqual(BigInt.lcm(2n, 4n), 4n)
+     * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
      * ```
      *
      * @category math
@@ -960,27 +995,34 @@ export declare const lcm: {
     (self: bigint, that: bigint): bigint;
 };
 /**
- * Determines the square root of a given `bigint` unsafely. Throws if the given `bigint` is negative.
+ * Returns the integer square root of a non-negative `bigint`.
+ *
+ * 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.
+ *
+ * **Example** (Calculating square roots unsafely)
  *
- * @example
  * ```ts
- * import { sqrtUnsafe } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(sqrtUnsafe(4n), 2n)
- * assert.deepStrictEqual(sqrtUnsafe(9n), 3n)
- * assert.deepStrictEqual(sqrtUnsafe(16n), 4n)
+ * assert.deepStrictEqual(BigInt.sqrtUnsafe(4n), 2n)
+ * assert.deepStrictEqual(BigInt.sqrtUnsafe(9n), 3n)
+ * assert.deepStrictEqual(BigInt.sqrtUnsafe(16n), 4n)
  * ```
  *
  * @category math
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const sqrtUnsafe: (n: bigint) => bigint;
 /**
- * Determines the square root of a given `bigint` safely. Returns `Option.none()` if
- * the given `bigint` is negative.
+ * Safely returns the integer square root of a `bigint`.
+ *
+ * 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.
  *
- * **Example**
+ * **Example** (Calculating square roots safely)
  *
  * ```ts
  * import { BigInt } from "effect"
@@ -996,14 +1038,17 @@ export declare const sqrtUnsafe: (n: bigint) => bigint;
  */
 export declare const sqrt: (n: bigint) => Option.Option<bigint>;
 /**
- * Takes an `Iterable` of `bigint`s and returns their sum as a single `bigint
+ * Takes an `Iterable` of `bigint`s and returns their sum as a single `bigint`.
+ *
+ * Returns `0n` for an empty iterable.
+ *
+ * **Example** (Summing iterable bigints)
  *
- * @example
  * ```ts
- * import { sumAll } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(sumAll([2n, 3n, 4n]), 9n)
+ * assert.deepStrictEqual(BigInt.sumAll([2n, 3n, 4n]), 9n)
  * ```
  *
  * @category math
@@ -1011,14 +1056,18 @@ export declare const sqrt: (n: bigint) => Option.Option<bigint>;
  */
 export declare const sumAll: (collection: Iterable<bigint>) => bigint;
 /**
- * Takes an `Iterable` of `bigint`s and returns their multiplication as a single `number`.
+ * Takes an `Iterable` of `bigint`s and returns their product as a single
+ * `bigint`.
+ *
+ * Returns `1n` for an empty iterable.
+ *
+ * **Example** (Multiplying iterable bigints)
  *
- * @example
  * ```ts
- * import { multiplyAll } from "effect/BigInt"
+ * import { BigInt } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(multiplyAll([2n, 3n, 4n]), 24n)
+ * assert.deepStrictEqual(BigInt.multiplyAll([2n, 3n, 4n]), 24n)
  * ```
  *
  * @category math
@@ -1031,7 +1080,8 @@ export declare const multiplyAll: (collection: Iterable<bigint>) => bigint;
  * If the `bigint` is outside the safe integer range for JavaScript (`Number.MAX_SAFE_INTEGER`
  * and `Number.MIN_SAFE_INTEGER`), it returns `Option.none()`.
  *
- * @example
+ * **Example** (Converting bigints to numbers)
+ *
  * ```ts
  * import { BigInt as BI } from "effect"
  *
@@ -1040,7 +1090,7 @@ export declare const multiplyAll: (collection: Iterable<bigint>) => bigint;
  * BI.toNumber(BigInt(Number.MIN_SAFE_INTEGER) - 1n) // Option.none()
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export declare const toNumber: (b: bigint) => Option.Option<number>;
@@ -1050,7 +1100,8 @@ export declare const toNumber: (b: bigint) => Option.Option<number>;
  * If the string is empty or contains characters that cannot be converted into a
  * `bigint`, it returns `Option.none()`.
  *
- * @example
+ * **Example** (Parsing strings as bigints)
+ *
  * ```ts
  * import { BigInt } from "effect"
  *
@@ -1059,7 +1110,7 @@ export declare const toNumber: (b: bigint) => Option.Option<number>;
  * BigInt.fromString("a") // Option.none()
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.4.12
  */
 export declare const fromString: (s: string) => Option.Option<bigint>;
@@ -1070,7 +1121,8 @@ export declare const fromString: (s: string) => Option.Option<bigint>;
  * (`Number.MAX_SAFE_INTEGER` and `Number.MIN_SAFE_INTEGER`) or if the number is
  * not a valid `bigint`, it returns `Option.none()`.
  *
- * @example
+ * **Example** (Converting numbers to bigints)
+ *
  * ```ts
  * import { BigInt } from "effect"
  *
@@ -1080,14 +1132,18 @@ export declare const fromString: (s: string) => Option.Option<bigint>;
  * BigInt.fromNumber(Number.MIN_SAFE_INTEGER - 1) // Option.none()
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.4.12
  */
 export declare function fromNumber(n: number): Option.Option<bigint>;
 /**
- * Returns the remainder of dividing the first `bigint` by the second `bigint`.
+ * Returns the JavaScript remainder of dividing one `bigint` by another.
+ *
+ * The result follows JavaScript `%` semantics, including the sign of the
+ * dividend. Throws a `RangeError` when the divisor is `0n`.
+ *
+ * **Example** (Calculating remainders)
  *
- * @example
  * ```ts
  * import { BigInt } from "effect"
  *
@@ -1101,9 +1157,13 @@ export declare function fromNumber(n: number): Option.Option<bigint>;
  */
 export declare const remainder: {
     /**
-     * Returns the remainder of dividing the first `bigint` by the second `bigint`.
+     * Returns the JavaScript remainder of dividing one `bigint` by another.
+     *
+     * The result follows JavaScript `%` semantics, including the sign of the
+     * dividend. Throws a `RangeError` when the divisor is `0n`.
+     *
+     * **Example** (Calculating remainders)
      *
-     * @example
      * ```ts
      * import { BigInt } from "effect"
      *
@@ -1117,9 +1177,13 @@ export declare const remainder: {
      */
     (divisor: bigint): (self: bigint) => bigint;
     /**
-     * Returns the remainder of dividing the first `bigint` by the second `bigint`.
+     * Returns the JavaScript remainder of dividing one `bigint` by another.
+     *
+     * The result follows JavaScript `%` semantics, including the sign of the
+     * dividend. Throws a `RangeError` when the divisor is `0n`.
+     *
+     * **Example** (Calculating remainders)
      *
-     * @example
      * ```ts
      * import { BigInt } from "effect"
      *
@@ -1136,24 +1200,28 @@ export declare const remainder: {
 /**
  * A `Reducer` for combining `bigint`s using addition.
  *
+ * @category math
  * @since 4.0.0
  */
 export declare const ReducerSum: Reducer.Reducer<bigint>;
 /**
  * A `Reducer` for combining `bigint`s using multiplication.
  *
+ * @category math
  * @since 4.0.0
  */
 export declare const ReducerMultiply: Reducer.Reducer<bigint>;
 /**
  * A `Combiner` that returns the maximum `bigint`.
  *
+ * @category math
  * @since 4.0.0
  */
 export declare const CombinerMax: Combiner.Combiner<bigint>;
 /**
  * A `Combiner` that returns the minimum `bigint`.
  *
+ * @category math
  * @since 4.0.0
  */
 export declare const CombinerMin: Combiner.Combiner<bigint>;