effect 4.0.0-beta.99 → 4.0.0-rc.108

package/src/BigInt.ts

@@ -36,14 +36,11 @@ import * as Reducer from "./Reducer.ts"
  *
  * **Example** (Constructing bigints)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
  *
- * const bigInt = BigInt.BigInt(123)
- * console.log(bigInt) // 123n
- *
- * const fromString = BigInt.BigInt("456")
- * console.log(fromString) // 456n
+ * BigInt.BigInt(123) // => 123n
+ * BigInt.BigInt("456") // => 456n
  * ```
  *
  * @category constructors
@@ -64,12 +61,11 @@ const bigint2 = BigInt(2)
  *
  * **Example** (Checking for bigints)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.isBigInt(1n), true)
- * assert.deepStrictEqual(BigInt.isBigInt(1), false)
+ * BigInt.isBigInt(1n) // => true
+ * BigInt.isBigInt(1) // => false
  * ```
  *
  * @category guards
@@ -87,11 +83,10 @@ export const isBigInt: (u: unknown) => u is bigint = predicate.isBigInt
  *
  * **Example** (Adding bigints)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.sum(2n, 3n), 5n)
+ * BigInt.sum(2n, 3n) // => 5n
  * ```
  *
  * @see {@link sumAll} for summing an iterable of `bigint` values
@@ -110,11 +105,10 @@ export const sum: {
    *
    * **Example** (Adding bigints)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.sum(2n, 3n), 5n)
+   * BigInt.sum(2n, 3n) // => 5n
    * ```
    *
    * @see {@link sumAll} for summing an iterable of `bigint` values
@@ -133,11 +127,10 @@ export const sum: {
    *
    * **Example** (Adding bigints)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.sum(2n, 3n), 5n)
+   * BigInt.sum(2n, 3n) // => 5n
    * ```
    *
    * @see {@link sumAll} for summing an iterable of `bigint` values
@@ -157,11 +150,10 @@ export const sum: {
  *
  * **Example** (Multiplying bigints)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.multiply(2n, 3n), 6n)
+ * BigInt.multiply(2n, 3n) // => 6n
  * ```
  *
  * @see {@link multiplyAll} for multiplying an iterable of `bigint` values
@@ -179,11 +171,10 @@ export const multiply: {
    *
    * **Example** (Multiplying bigints)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.multiply(2n, 3n), 6n)
+   * BigInt.multiply(2n, 3n) // => 6n
    * ```
    *
    * @see {@link multiplyAll} for multiplying an iterable of `bigint` values
@@ -201,11 +192,10 @@ export const multiply: {
    *
    * **Example** (Multiplying bigints)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.multiply(2n, 3n), 6n)
+   * BigInt.multiply(2n, 3n) // => 6n
    * ```
    *
    * @see {@link multiplyAll} for multiplying an iterable of `bigint` values
@@ -225,11 +215,10 @@ export const multiply: {
  *
  * **Example** (Subtracting bigints)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.subtract(2n, 3n), -1n)
+ * BigInt.subtract(2n, 3n) // => -1n
  * ```
  *
  * @category math
@@ -245,11 +234,10 @@ export const subtract: {
    *
    * **Example** (Subtracting bigints)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.subtract(2n, 3n), -1n)
+   * BigInt.subtract(2n, 3n) // => -1n
    * ```
    *
    * @category math
@@ -265,11 +253,10 @@ export const subtract: {
    *
    * **Example** (Subtracting bigints)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.subtract(2n, 3n), -1n)
+   * BigInt.subtract(2n, 3n) // => -1n
    * ```
    *
    * @category math
@@ -293,12 +280,11 @@ export const subtract: {
  *
  * **Example** (Dividing bigints safely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt, Option } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.divide(6n, 3n), Option.some(2n))
- * assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
+ * BigInt.divide(6n, 3n) // => Option.some(2n)
+ * BigInt.divide(6n, 0n) // => Option.none()
  * ```
  *
  * @see {@link divideUnsafe} for division that throws when the divisor is `0n`
@@ -323,12 +309,11 @@ export const divide: {
    *
    * **Example** (Dividing bigints safely)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt, Option } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.divide(6n, 3n), Option.some(2n))
-   * assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
+   * BigInt.divide(6n, 3n) // => Option.some(2n)
+   * BigInt.divide(6n, 0n) // => Option.none()
    * ```
    *
    * @see {@link divideUnsafe} for division that throws when the divisor is `0n`
@@ -353,12 +338,11 @@ export const divide: {
    *
    * **Example** (Dividing bigints safely)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt, Option } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.divide(6n, 3n), Option.some(2n))
-   * assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
+   * BigInt.divide(6n, 3n) // => Option.some(2n)
+   * BigInt.divide(6n, 0n) // => Option.none()
    * ```
    *
    * @see {@link divideUnsafe} for division that throws when the divisor is `0n`
@@ -392,12 +376,11 @@ export const divide: {
  *
  * **Example** (Dividing bigints unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 3n), 2n)
- * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 4n), 1n)
+ * BigInt.divideUnsafe(6n, 3n) // => 2n
+ * BigInt.divideUnsafe(6n, 4n) // => 1n
  * ```
  *
  * @see {@link divide} for division that returns `Option.none` when the divisor is `0n`
@@ -425,12 +408,11 @@ export const divideUnsafe: {
    *
    * **Example** (Dividing bigints unsafely)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 3n), 2n)
-   * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 4n), 1n)
+   * BigInt.divideUnsafe(6n, 3n) // => 2n
+   * BigInt.divideUnsafe(6n, 4n) // => 1n
    * ```
    *
    * @see {@link divide} for division that returns `Option.none` when the divisor is `0n`
@@ -458,12 +440,11 @@ export const divideUnsafe: {
    *
    * **Example** (Dividing bigints unsafely)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 3n), 2n)
-   * assert.deepStrictEqual(BigInt.divideUnsafe(6n, 4n), 1n)
+   * BigInt.divideUnsafe(6n, 3n) // => 2n
+   * BigInt.divideUnsafe(6n, 4n) // => 1n
    * ```
    *
    * @see {@link divide} for division that returns `Option.none` when the divisor is `0n`
@@ -483,11 +464,10 @@ export const divideUnsafe: {
  *
  * **Example** (Incrementing a bigint)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.increment(2n), 3n)
+ * BigInt.increment(2n) // => 3n
  * ```
  *
  * @category math
@@ -504,11 +484,10 @@ export const increment = (n: bigint): bigint => n + bigint1
  *
  * **Example** (Decrementing a bigint)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.decrement(3n), 2n)
+ * BigInt.decrement(3n) // => 2n
  * ```
  *
  * @category math
@@ -526,16 +505,16 @@ export const decrement = (n: bigint): bigint => n - bigint1
  *
  * **Example** (Comparing bigints with Order)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
  *
  * const a = 123n
  * const b = 456n
  * const c = 123n
  *
- * console.log(BigInt.Order(a, b)) // -1 (a < b)
- * console.log(BigInt.Order(b, a)) // 1 (b > a)
- * console.log(BigInt.Order(a, c)) // 0 (a === c)
+ * BigInt.Order(a, b) // => -1
+ * BigInt.Order(b, a) // => 1
+ * BigInt.Order(a, c) // => 0
  * ```
  *
  * @category instances
@@ -553,11 +532,11 @@ export const Order: order.Order<bigint> = order.BigInt
  *
  * **Example** (Comparing bigints for equivalence)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
  *
- * console.log(BigInt.Equivalence(1n, 1n)) // true
- * console.log(BigInt.Equivalence(1n, 2n)) // false
+ * BigInt.Equivalence(1n, 1n) // => true
+ * BigInt.Equivalence(1n, 2n) // => false
  * ```
  *
  * @category instances
@@ -574,13 +553,12 @@ export const Equivalence: Equ.Equivalence<bigint> = Equ.BigInt
  *
  * **Example** (Checking less-than comparisons)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.isLessThan(2n, 3n), true)
- * assert.deepStrictEqual(BigInt.isLessThan(3n, 3n), false)
- * assert.deepStrictEqual(BigInt.isLessThan(4n, 3n), false)
+ * BigInt.isLessThan(2n, 3n) // => true
+ * BigInt.isLessThan(3n, 3n) // => false
+ * BigInt.isLessThan(4n, 3n) // => false
  * ```
  *
  * @category predicates
@@ -596,13 +574,12 @@ export const isLessThan: {
    *
    * **Example** (Checking less-than comparisons)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.isLessThan(2n, 3n), true)
-   * assert.deepStrictEqual(BigInt.isLessThan(3n, 3n), false)
-   * assert.deepStrictEqual(BigInt.isLessThan(4n, 3n), false)
+   * BigInt.isLessThan(2n, 3n) // => true
+   * BigInt.isLessThan(3n, 3n) // => false
+   * BigInt.isLessThan(4n, 3n) // => false
    * ```
    *
    * @category predicates
@@ -618,13 +595,12 @@ export const isLessThan: {
    *
    * **Example** (Checking less-than comparisons)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.isLessThan(2n, 3n), true)
-   * assert.deepStrictEqual(BigInt.isLessThan(3n, 3n), false)
-   * assert.deepStrictEqual(BigInt.isLessThan(4n, 3n), false)
+   * BigInt.isLessThan(2n, 3n) // => true
+   * BigInt.isLessThan(3n, 3n) // => false
+   * BigInt.isLessThan(4n, 3n) // => false
    * ```
    *
    * @category predicates
@@ -642,13 +618,12 @@ export const isLessThan: {
  *
  * **Example** (Checking less-than-or-equal comparisons)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(2n, 3n), true)
- * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(3n, 3n), true)
- * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(4n, 3n), false)
+ * BigInt.isLessThanOrEqualTo(2n, 3n) // => true
+ * BigInt.isLessThanOrEqualTo(3n, 3n) // => true
+ * BigInt.isLessThanOrEqualTo(4n, 3n) // => false
  * ```
  *
  * @category predicates
@@ -664,13 +639,12 @@ export const isLessThanOrEqualTo: {
    *
    * **Example** (Checking less-than-or-equal comparisons)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(2n, 3n), true)
-   * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(3n, 3n), true)
-   * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(4n, 3n), false)
+   * BigInt.isLessThanOrEqualTo(2n, 3n) // => true
+   * BigInt.isLessThanOrEqualTo(3n, 3n) // => true
+   * BigInt.isLessThanOrEqualTo(4n, 3n) // => false
    * ```
    *
    * @category predicates
@@ -686,13 +660,12 @@ export const isLessThanOrEqualTo: {
    *
    * **Example** (Checking less-than-or-equal comparisons)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(2n, 3n), true)
-   * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(3n, 3n), true)
-   * assert.deepStrictEqual(BigInt.isLessThanOrEqualTo(4n, 3n), false)
+   * BigInt.isLessThanOrEqualTo(2n, 3n) // => true
+   * BigInt.isLessThanOrEqualTo(3n, 3n) // => true
+   * BigInt.isLessThanOrEqualTo(4n, 3n) // => false
    * ```
    *
    * @category predicates
@@ -710,13 +683,12 @@ export const isLessThanOrEqualTo: {
  *
  * **Example** (Checking greater-than comparisons)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.isGreaterThan(2n, 3n), false)
- * assert.deepStrictEqual(BigInt.isGreaterThan(3n, 3n), false)
- * assert.deepStrictEqual(BigInt.isGreaterThan(4n, 3n), true)
+ * BigInt.isGreaterThan(2n, 3n) // => false
+ * BigInt.isGreaterThan(3n, 3n) // => false
+ * BigInt.isGreaterThan(4n, 3n) // => true
  * ```
  *
  * @category predicates
@@ -732,13 +704,12 @@ export const isGreaterThan: {
    *
    * **Example** (Checking greater-than comparisons)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.isGreaterThan(2n, 3n), false)
-   * assert.deepStrictEqual(BigInt.isGreaterThan(3n, 3n), false)
-   * assert.deepStrictEqual(BigInt.isGreaterThan(4n, 3n), true)
+   * BigInt.isGreaterThan(2n, 3n) // => false
+   * BigInt.isGreaterThan(3n, 3n) // => false
+   * BigInt.isGreaterThan(4n, 3n) // => true
    * ```
    *
    * @category predicates
@@ -754,13 +725,12 @@ export const isGreaterThan: {
    *
    * **Example** (Checking greater-than comparisons)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.isGreaterThan(2n, 3n), false)
-   * assert.deepStrictEqual(BigInt.isGreaterThan(3n, 3n), false)
-   * assert.deepStrictEqual(BigInt.isGreaterThan(4n, 3n), true)
+   * BigInt.isGreaterThan(2n, 3n) // => false
+   * BigInt.isGreaterThan(3n, 3n) // => false
+   * BigInt.isGreaterThan(4n, 3n) // => true
    * ```
    *
    * @category predicates
@@ -778,13 +748,12 @@ export const isGreaterThan: {
  *
  * **Example** (Checking greater-than-or-equal comparisons)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(2n, 3n), false)
- * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(3n, 3n), true)
- * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(4n, 3n), true)
+ * BigInt.isGreaterThanOrEqualTo(2n, 3n) // => false
+ * BigInt.isGreaterThanOrEqualTo(3n, 3n) // => true
+ * BigInt.isGreaterThanOrEqualTo(4n, 3n) // => true
  * ```
  *
  * @category predicates
@@ -800,13 +769,12 @@ export const isGreaterThanOrEqualTo: {
    *
    * **Example** (Checking greater-than-or-equal comparisons)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(2n, 3n), false)
-   * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(3n, 3n), true)
-   * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(4n, 3n), true)
+   * BigInt.isGreaterThanOrEqualTo(2n, 3n) // => false
+   * BigInt.isGreaterThanOrEqualTo(3n, 3n) // => true
+   * BigInt.isGreaterThanOrEqualTo(4n, 3n) // => true
    * ```
    *
    * @category predicates
@@ -822,13 +790,12 @@ export const isGreaterThanOrEqualTo: {
    *
    * **Example** (Checking greater-than-or-equal comparisons)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(2n, 3n), false)
-   * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(3n, 3n), true)
-   * assert.deepStrictEqual(BigInt.isGreaterThanOrEqualTo(4n, 3n), true)
+   * BigInt.isGreaterThanOrEqualTo(2n, 3n) // => false
+   * BigInt.isGreaterThanOrEqualTo(3n, 3n) // => true
+   * BigInt.isGreaterThanOrEqualTo(4n, 3n) // => true
    * ```
    *
    * @category predicates
@@ -846,15 +813,14 @@ export const isGreaterThanOrEqualTo: {
  *
  * **Example** (Checking whether a bigint is within bounds)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
  * const between = BigInt.between({ minimum: 0n, maximum: 5n })
  *
- * assert.deepStrictEqual(between(3n), true)
- * assert.deepStrictEqual(between(-1n), false)
- * assert.deepStrictEqual(between(6n), false)
+ * between(3n) // => true
+ * between(-1n) // => false
+ * between(6n) // => false
  * ```
  *
  * @see {@link clamp} for forcing a `bigint` into an inclusive range
@@ -872,15 +838,14 @@ export const between: {
    *
    * **Example** (Checking whether a bigint is within bounds)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
    * const between = BigInt.between({ minimum: 0n, maximum: 5n })
    *
-   * assert.deepStrictEqual(between(3n), true)
-   * assert.deepStrictEqual(between(-1n), false)
-   * assert.deepStrictEqual(between(6n), false)
+   * between(3n) // => true
+   * between(-1n) // => false
+   * between(6n) // => false
    * ```
    *
    * @see {@link clamp} for forcing a `bigint` into an inclusive range
@@ -903,15 +868,14 @@ export const between: {
    *
    * **Example** (Checking whether a bigint is within bounds)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
    * const between = BigInt.between({ minimum: 0n, maximum: 5n })
    *
-   * assert.deepStrictEqual(between(3n), true)
-   * assert.deepStrictEqual(between(-1n), false)
-   * assert.deepStrictEqual(between(6n), false)
+   * between(3n) // => true
+   * between(-1n) // => false
+   * between(6n) // => false
    * ```
    *
    * @see {@link clamp} for forcing a `bigint` into an inclusive range
@@ -943,15 +907,14 @@ export const between: {
  *
  * **Example** (Clamping a bigint to bounds)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
  * const clamp = BigInt.clamp({ minimum: 1n, maximum: 5n })
  *
- * assert.equal(clamp(3n), 3n)
- * assert.equal(clamp(0n), 1n)
- * assert.equal(clamp(6n), 5n)
+ * clamp(3n) // => 3n
+ * clamp(0n) // => 1n
+ * clamp(6n) // => 5n
  * ```
  *
  * @see {@link between} for checking whether a `bigint` is already inside a range
@@ -975,15 +938,14 @@ export const clamp: {
    *
    * **Example** (Clamping a bigint to bounds)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
    * const clamp = BigInt.clamp({ minimum: 1n, maximum: 5n })
    *
-   * assert.equal(clamp(3n), 3n)
-   * assert.equal(clamp(0n), 1n)
-   * assert.equal(clamp(6n), 5n)
+   * clamp(3n) // => 3n
+   * clamp(0n) // => 1n
+   * clamp(6n) // => 5n
    * ```
    *
    * @see {@link between} for checking whether a `bigint` is already inside a range
@@ -1012,15 +974,14 @@ export const clamp: {
    *
    * **Example** (Clamping a bigint to bounds)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
    * const clamp = BigInt.clamp({ minimum: 1n, maximum: 5n })
    *
-   * assert.equal(clamp(3n), 3n)
-   * assert.equal(clamp(0n), 1n)
-   * assert.equal(clamp(6n), 5n)
+   * clamp(3n) // => 3n
+   * clamp(0n) // => 1n
+   * clamp(6n) // => 5n
    * ```
    *
    * @see {@link between} for checking whether a `bigint` is already inside a range
@@ -1046,11 +1007,10 @@ export const clamp: {
  *
  * **Example** (Finding the minimum bigint)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
+ * BigInt.min(2n, 3n) // => 2n
  * ```
  *
  * @see {@link max} for selecting the larger value
@@ -1068,11 +1028,10 @@ export const min: {
    *
    * **Example** (Finding the minimum bigint)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
+   * BigInt.min(2n, 3n) // => 2n
    * ```
    *
    * @see {@link max} for selecting the larger value
@@ -1090,11 +1049,10 @@ export const min: {
    *
    * **Example** (Finding the minimum bigint)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.min(2n, 3n), 2n)
+   * BigInt.min(2n, 3n) // => 2n
    * ```
    *
    * @see {@link max} for selecting the larger value
@@ -1114,11 +1072,10 @@ export const min: {
  *
  * **Example** (Finding the maximum bigint)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
+ * BigInt.max(2n, 3n) // => 3n
  * ```
  *
  * @see {@link min} for selecting the smaller value
@@ -1136,11 +1093,10 @@ export const max: {
    *
    * **Example** (Finding the maximum bigint)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
+   * BigInt.max(2n, 3n) // => 3n
    * ```
    *
    * @see {@link min} for selecting the smaller value
@@ -1158,11 +1114,10 @@ export const max: {
    *
    * **Example** (Finding the maximum bigint)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.max(2n, 3n), 3n)
+   * BigInt.max(2n, 3n) // => 3n
    * ```
    *
    * @see {@link min} for selecting the smaller value
@@ -1182,13 +1137,12 @@ export const max: {
  *
  * **Example** (Determining bigint signs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.sign(-5n), -1)
- * assert.deepStrictEqual(BigInt.sign(0n), 0)
- * assert.deepStrictEqual(BigInt.sign(5n), 1)
+ * BigInt.sign(-5n) // => -1
+ * BigInt.sign(0n) // => 0
+ * BigInt.sign(5n) // => 1
  * ```
  *
  * @category math
@@ -1205,13 +1159,12 @@ export const sign = (n: bigint): Ordering => order.BigInt(n, bigint0)
  *
  * **Example** (Calculating absolute values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.abs(-5n), 5n)
- * assert.deepStrictEqual(BigInt.abs(0n), 0n)
- * assert.deepStrictEqual(BigInt.abs(5n), 5n)
+ * BigInt.abs(-5n) // => 5n
+ * BigInt.abs(0n) // => 0n
+ * BigInt.abs(5n) // => 5n
  * ```
  *
  * @category math
@@ -1228,13 +1181,12 @@ export const abs = (n: bigint): bigint => (n < bigint0 ? -n : n)
  *
  * **Example** (Calculating greatest common divisors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.gcd(2n, 3n), 1n)
- * assert.deepStrictEqual(BigInt.gcd(2n, 4n), 2n)
- * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
+ * BigInt.gcd(2n, 3n) // => 1n
+ * BigInt.gcd(2n, 4n) // => 2n
+ * BigInt.gcd(16n, 24n) // => 8n
  * ```
  *
  * @see {@link lcm} for computing the least common multiple
@@ -1252,13 +1204,12 @@ export const gcd: {
    *
    * **Example** (Calculating greatest common divisors)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.gcd(2n, 3n), 1n)
-   * assert.deepStrictEqual(BigInt.gcd(2n, 4n), 2n)
-   * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
+   * BigInt.gcd(2n, 3n) // => 1n
+   * BigInt.gcd(2n, 4n) // => 2n
+   * BigInt.gcd(16n, 24n) // => 8n
    * ```
    *
    * @see {@link lcm} for computing the least common multiple
@@ -1276,13 +1227,12 @@ export const gcd: {
    *
    * **Example** (Calculating greatest common divisors)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.gcd(2n, 3n), 1n)
-   * assert.deepStrictEqual(BigInt.gcd(2n, 4n), 2n)
-   * assert.deepStrictEqual(BigInt.gcd(16n, 24n), 8n)
+   * BigInt.gcd(2n, 3n) // => 1n
+   * BigInt.gcd(2n, 4n) // => 2n
+   * BigInt.gcd(16n, 24n) // => 8n
    * ```
    *
    * @see {@link lcm} for computing the least common multiple
@@ -1297,7 +1247,7 @@ export const gcd: {
     that = self % that
     self = t
   }
-  return self
+  return abs(self)
 })
 
 /**
@@ -1309,13 +1259,12 @@ export const gcd: {
  *
  * **Example** (Calculating least common multiples)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.lcm(2n, 3n), 6n)
- * assert.deepStrictEqual(BigInt.lcm(2n, 4n), 4n)
- * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
+ * BigInt.lcm(2n, 3n) // => 6n
+ * BigInt.lcm(2n, 4n) // => 4n
+ * BigInt.lcm(16n, 24n) // => 48n
  * ```
  *
  * @see {@link gcd} for computing the greatest common divisor
@@ -1333,13 +1282,12 @@ export const lcm: {
    *
    * **Example** (Calculating least common multiples)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.lcm(2n, 3n), 6n)
-   * assert.deepStrictEqual(BigInt.lcm(2n, 4n), 4n)
-   * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
+   * BigInt.lcm(2n, 3n) // => 6n
+   * BigInt.lcm(2n, 4n) // => 4n
+   * BigInt.lcm(16n, 24n) // => 48n
    * ```
    *
    * @see {@link gcd} for computing the greatest common divisor
@@ -1357,13 +1305,12 @@ export const lcm: {
    *
    * **Example** (Calculating least common multiples)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
-   * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(BigInt.lcm(2n, 3n), 6n)
-   * assert.deepStrictEqual(BigInt.lcm(2n, 4n), 4n)
-   * assert.deepStrictEqual(BigInt.lcm(16n, 24n), 48n)
+   * BigInt.lcm(2n, 3n) // => 6n
+   * BigInt.lcm(2n, 4n) // => 4n
+   * BigInt.lcm(16n, 24n) // => 48n
    * ```
    *
    * @see {@link gcd} for computing the greatest common divisor
@@ -1372,7 +1319,11 @@ export const lcm: {
    * @since 2.0.0
    */
   (self: bigint, that: bigint): bigint
-} = dual(2, (self: bigint, that: bigint): bigint => (self * that) / gcd(self, that))
+} = dual(
+  2,
+  (self: bigint, that: bigint): bigint =>
+    self === bigint0 || that === bigint0 ? bigint0 : abs((self * that) / gcd(self, that))
+)
 
 /**
  * Returns the integer square root of a non-negative `bigint`.
@@ -1394,13 +1345,12 @@ export const lcm: {
  *
  * **Example** (Calculating square roots unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.sqrtUnsafe(4n), 2n)
- * assert.deepStrictEqual(BigInt.sqrtUnsafe(9n), 3n)
- * assert.deepStrictEqual(BigInt.sqrtUnsafe(16n), 4n)
+ * BigInt.sqrtUnsafe(4n) // => 2n
+ * BigInt.sqrtUnsafe(9n) // => 3n
+ * BigInt.sqrtUnsafe(16n) // => 4n
  * ```
  *
  * @see {@link sqrt} for returning `Option.none` when the input is negative
@@ -1438,13 +1388,13 @@ export const sqrtUnsafe = (n: bigint): bigint => {
  *
  * **Example** (Calculating square roots safely)
  *
- * ```ts
- * import { BigInt } from "effect"
+ * ```ts import.meta.vitest
+ * import { BigInt, Option } from "effect"
  *
- * BigInt.sqrt(4n) // Option.some(2n)
- * BigInt.sqrt(9n) // Option.some(3n)
- * BigInt.sqrt(16n) // Option.some(4n)
- * BigInt.sqrt(-1n) // Option.none()
+ * BigInt.sqrt(4n) // => Option.some(2n)
+ * BigInt.sqrt(9n) // => Option.some(3n)
+ * BigInt.sqrt(16n) // => Option.some(4n)
+ * BigInt.sqrt(-1n) // => Option.none()
  * ```
  *
  * @see {@link sqrtUnsafe} for square root computation that throws on negative input
@@ -1465,11 +1415,10 @@ export const sqrt = (n: bigint): Option.Option<bigint> =>
  *
  * **Example** (Summing iterable bigints)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.sumAll([2n, 3n, 4n]), 9n)
+ * BigInt.sumAll([2n, 3n, 4n]) // => 9n
  * ```
  *
  * @see {@link sum} for adding two `bigint` values
@@ -1495,11 +1444,10 @@ export const sumAll = (collection: Iterable<bigint>): bigint => {
  *
  * **Example** (Multiplying iterable bigints)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(BigInt.multiplyAll([2n, 3n, 4n]), 24n)
+ * BigInt.multiplyAll([2n, 3n, 4n]) // => 24n
  * ```
  *
  * @see {@link multiply} for multiplying two `bigint` values
@@ -1534,12 +1482,12 @@ export const multiplyAll = (collection: Iterable<bigint>): bigint => {
  *
  * **Example** (Converting bigints to numbers)
  *
- * ```ts
- * import { BigInt as BI } from "effect"
+ * ```ts import.meta.vitest
+ * import { BigInt as BI, Option } from "effect"
  *
- * BI.toNumber(42n) // Option.some(42)
- * BI.toNumber(BigInt(Number.MAX_SAFE_INTEGER) + 1n) // Option.none()
- * BI.toNumber(BigInt(Number.MIN_SAFE_INTEGER) - 1n) // Option.none()
+ * BI.toNumber(42n) // => Option.some(42)
+ * BI.toNumber(9007199254740992n) // => Option.none()
+ * BI.toNumber(-9007199254740992n) // => Option.none()
  * ```
  *
  * @see {@link fromNumber} for converting a safe integer number to `bigint`
@@ -1568,12 +1516,12 @@ export const toNumber = (b: bigint): Option.Option<number> => {
  *
  * **Example** (Parsing strings as bigints)
  *
- * ```ts
- * import { BigInt } from "effect"
+ * ```ts import.meta.vitest
+ * import { BigInt, Option } from "effect"
  *
- * BigInt.fromString("42") // Option.some(42n)
- * BigInt.fromString(" ") // Option.none()
- * BigInt.fromString("a") // Option.none()
+ * BigInt.fromString("42") // => Option.some(42n)
+ * BigInt.fromString(" ") // => Option.none()
+ * BigInt.fromString("a") // => Option.none()
  * ```
  *
  * @see {@link BigInt} for native constructor coercion that throws on invalid input
@@ -1606,13 +1554,12 @@ export const fromString = (s: string): Option.Option<bigint> => {
  *
  * **Example** (Converting numbers to bigints)
  *
- * ```ts
- * import { BigInt } from "effect"
- *
- * BigInt.fromNumber(42) // Option.some(42n)
+ * ```ts import.meta.vitest
+ * import { BigInt, Option } from "effect"
  *
- * BigInt.fromNumber(Number.MAX_SAFE_INTEGER + 1) // Option.none()
- * BigInt.fromNumber(Number.MIN_SAFE_INTEGER - 1) // Option.none()
+ * BigInt.fromNumber(42) // => Option.some(42n)
+ * BigInt.fromNumber(Number.MAX_SAFE_INTEGER + 1) // => Option.none()
+ * BigInt.fromNumber(Number.MIN_SAFE_INTEGER - 1) // => Option.none()
  * ```
  *
  * @see {@link toNumber} for converting `bigint` values back to safe integer numbers
@@ -1647,12 +1594,11 @@ export function fromNumber(n: number): Option.Option<bigint> {
  *
  * **Example** (Calculating remainders)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { BigInt } from "effect"
  *
- * BigInt.remainder(10n, 3n) // 1n
- *
- * BigInt.remainder(15n, 4n) // 3n
+ * BigInt.remainder(10n, 3n) // => 1n
+ * BigInt.remainder(15n, 4n) // => 3n
  * ```
  *
  * @see {@link divide} for quotient calculation with division-by-zero represented as `Option.none`
@@ -1675,12 +1621,11 @@ export const remainder: {
    *
    * **Example** (Calculating remainders)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
    *
-   * BigInt.remainder(10n, 3n) // 1n
-   *
-   * BigInt.remainder(15n, 4n) // 3n
+   * BigInt.remainder(10n, 3n) // => 1n
+   * BigInt.remainder(15n, 4n) // => 3n
    * ```
    *
    * @see {@link divide} for quotient calculation with division-by-zero represented as `Option.none`
@@ -1703,12 +1648,11 @@ export const remainder: {
    *
    * **Example** (Calculating remainders)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { BigInt } from "effect"
    *
-   * BigInt.remainder(10n, 3n) // 1n
-   *
-   * BigInt.remainder(15n, 4n) // 3n
+   * BigInt.remainder(10n, 3n) // => 1n
+   * BigInt.remainder(15n, 4n) // => 3n
    * ```
    *
    * @see {@link divide} for quotient calculation with division-by-zero represented as `Option.none`