effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/BigInt.ts

@@ -17,7 +17,8 @@ import * as Reducer from "./Reducer.ts"
 /**
  * Reference to the global BigInt constructor.
  *
- * @example
+ * **Example** (Constructing bigints)
+ *
  * ```ts
  * import * as BigInt from "effect/BigInt"
  *
@@ -40,7 +41,8 @@ const bigint2 = BigInt(2)
 /**
  * Tests if a value is a `bigint`.
  *
- * @example
+ * **Example** (Checking for bigints)
+ *
  * ```ts
  * import { isBigInt } from "effect/BigInt"
  * import * as assert from "node:assert"
@@ -57,7 +59,8 @@ export const isBigInt: (u: unknown) => u is bigint = predicate.isBigInt
 /**
  * Provides an addition operation on `bigint`s.
  *
- * @example
+ * **Example** (Adding bigints)
+ *
  * ```ts
  * import { sum } from "effect/BigInt"
  * import * as assert from "node:assert"
@@ -72,7 +75,8 @@ export const sum: {
   /**
    * Provides an addition operation on `bigint`s.
    *
-   * @example
+   * **Example** (Adding bigints)
+   *
    * ```ts
    * import { sum } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -87,7 +91,8 @@ export const sum: {
   /**
    * Provides an addition operation on `bigint`s.
    *
-   * @example
+   * **Example** (Adding bigints)
+   *
    * ```ts
    * import { sum } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -104,7 +109,8 @@ export const sum: {
 /**
  * Provides a multiplication operation on `bigint`s.
  *
- * @example
+ * **Example** (Multiplying bigints)
+ *
  * ```ts
  * import { multiply } from "effect/BigInt"
  * import * as assert from "node:assert"
@@ -119,7 +125,8 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `bigint`s.
    *
-   * @example
+   * **Example** (Multiplying bigints)
+   *
    * ```ts
    * import { multiply } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -134,7 +141,8 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `bigint`s.
    *
-   * @example
+   * **Example** (Multiplying bigints)
+   *
    * ```ts
    * import { multiply } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -151,7 +159,8 @@ export const multiply: {
 /**
  * Provides a subtraction operation on `bigint`s.
  *
- * @example
+ * **Example** (Subtracting bigints)
+ *
  * ```ts
  * import { subtract } from "effect/BigInt"
  * import * as assert from "node:assert"
@@ -166,7 +175,8 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `bigint`s.
    *
-   * @example
+   * **Example** (Subtracting bigints)
+   *
    * ```ts
    * import { subtract } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -181,7 +191,8 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `bigint`s.
    *
-   * @example
+   * **Example** (Subtracting bigints)
+   *
    * ```ts
    * import { subtract } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -196,14 +207,13 @@ export const subtract: {
 } = dual(2, (self: bigint, that: bigint): bigint => self - that)
 
 /**
- * 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 * as assert from "node:assert"
@@ -219,14 +229,13 @@ export const subtract: {
  */
 export 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 * as assert from "node:assert"
@@ -242,14 +251,13 @@ export 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 * as assert from "node:assert"
@@ -270,14 +278,13 @@ export const divide: {
 )
 
 /**
- * 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 * as assert from "node:assert"
@@ -291,14 +298,13 @@ export const divide: {
  */
 export 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 * as assert from "node:assert"
@@ -312,14 +318,13 @@ export const divideUnsafe: {
    */
   (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 * as assert from "node:assert"
@@ -335,9 +340,10 @@ export const divideUnsafe: {
 } = dual(2, (self: bigint, that: bigint): bigint => self / that)
 
 /**
- * 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 * as assert from "node:assert"
@@ -351,9 +357,10 @@ export const divideUnsafe: {
 export const increment = (n: bigint): bigint => n + bigint1
 
 /**
- * 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 * as assert from "node:assert"
@@ -369,7 +376,8 @@ export const decrement = (n: bigint): bigint => n - bigint1
 /**
  * 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"
  *
@@ -390,7 +398,8 @@ export const Order: order.Order<bigint> = order.BigInt
 /**
  * An `Equivalence` instance for bigints using strict equality (`===`).
  *
- * @example
+ * **Example** (Comparing bigints for equivalence)
+ *
  * ```ts
  * import { BigInt } from "effect"
  *
@@ -406,7 +415,8 @@ export const Equivalence: Equ.Equivalence<bigint> = Equ.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 * as assert from "node:assert"
@@ -423,7 +433,8 @@ 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/BigInt"
    * import * as assert from "node:assert"
@@ -440,7 +451,8 @@ 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/BigInt"
    * import * as assert from "node:assert"
@@ -459,7 +471,8 @@ export const isLessThan: {
 /**
  * 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 * as assert from "node:assert"
@@ -476,7 +489,8 @@ export 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 * as assert from "node:assert"
@@ -493,7 +507,8 @@ export 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 * as assert from "node:assert"
@@ -512,7 +527,8 @@ 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/BigInt"
  * import * as assert from "node:assert"
@@ -529,7 +545,8 @@ 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/BigInt"
    * import * as assert from "node:assert"
@@ -546,7 +563,8 @@ 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/BigInt"
    * import * as assert from "node:assert"
@@ -565,7 +583,8 @@ export const isGreaterThan: {
 /**
  * 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 * as assert from "node:assert"
@@ -582,7 +601,8 @@ export 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 * as assert from "node:assert"
@@ -599,7 +619,8 @@ export 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 * as assert from "node:assert"
@@ -618,7 +639,8 @@ export const isGreaterThanOrEqualTo: {
 /**
  * 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 * as assert from "node:assert"
@@ -637,7 +659,8 @@ export 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 * as assert from "node:assert"
@@ -661,7 +684,8 @@ export 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 * as assert from "node:assert"
@@ -692,7 +716,8 @@ export 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 * as assert from "node:assert"
@@ -715,7 +740,8 @@ export 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 * as assert from "node:assert"
@@ -743,7 +769,8 @@ export 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 * as assert from "node:assert"
@@ -770,7 +797,8 @@ export const clamp: {
 /**
  * Returns the minimum between two `bigint`s.
  *
- * @example
+ * **Example** (Finding the minimum bigint)
+ *
  * ```ts
  * import { min } from "effect/BigInt"
  * import * as assert from "node:assert"
@@ -785,7 +813,8 @@ export const min: {
   /**
    * Returns the minimum between two `bigint`s.
    *
-   * @example
+   * **Example** (Finding the minimum bigint)
+   *
    * ```ts
    * import { min } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -800,7 +829,8 @@ export const min: {
   /**
    * Returns the minimum between two `bigint`s.
    *
-   * @example
+   * **Example** (Finding the minimum bigint)
+   *
    * ```ts
    * import { min } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -817,7 +847,8 @@ export const min: {
 /**
  * Returns the maximum between two `bigint`s.
  *
- * @example
+ * **Example** (Finding the maximum bigint)
+ *
  * ```ts
  * import { max } from "effect/BigInt"
  * import * as assert from "node:assert"
@@ -832,7 +863,8 @@ export const max: {
   /**
    * Returns the maximum between two `bigint`s.
    *
-   * @example
+   * **Example** (Finding the maximum bigint)
+   *
    * ```ts
    * import { max } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -847,7 +879,8 @@ export const max: {
   /**
    * Returns the maximum between two `bigint`s.
    *
-   * @example
+   * **Example** (Finding the maximum bigint)
+   *
    * ```ts
    * import { max } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -864,7 +897,8 @@ export const max: {
 /**
  * Determines the sign of a given `bigint`.
  *
- * @example
+ * **Example** (Determining bigint signs)
+ *
  * ```ts
  * import { sign } from "effect/BigInt"
  * import * as assert from "node:assert"
@@ -882,7 +916,8 @@ export const sign = (n: bigint): Ordering => order.BigInt(n, bigint0)
 /**
  * Determines the absolute value of a given `bigint`.
  *
- * @example
+ * **Example** (Calculating absolute values)
+ *
  * ```ts
  * import { abs } from "effect/BigInt"
  * import * as assert from "node:assert"
@@ -900,7 +935,8 @@ export const abs = (n: bigint): bigint => (n < bigint0 ? -n : n)
 /**
  * Determines the greatest common divisor of two `bigint`s.
  *
- * @example
+ * **Example** (Calculating greatest common divisors)
+ *
  * ```ts
  * import { gcd } from "effect/BigInt"
  * import * as assert from "node:assert"
@@ -917,7 +953,8 @@ export const gcd: {
   /**
    * Determines the greatest common divisor of two `bigint`s.
    *
-   * @example
+   * **Example** (Calculating greatest common divisors)
+   *
    * ```ts
    * import { gcd } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -934,7 +971,8 @@ export const gcd: {
   /**
    * Determines the greatest common divisor of two `bigint`s.
    *
-   * @example
+   * **Example** (Calculating greatest common divisors)
+   *
    * ```ts
    * import { gcd } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -960,7 +998,8 @@ export const gcd: {
 /**
  * Determines the least common multiple of two `bigint`s.
  *
- * @example
+ * **Example** (Calculating least common multiples)
+ *
  * ```ts
  * import { lcm } from "effect/BigInt"
  * import * as assert from "node:assert"
@@ -977,7 +1016,8 @@ export const lcm: {
   /**
    * Determines the least common multiple of two `bigint`s.
    *
-   * @example
+   * **Example** (Calculating least common multiples)
+   *
    * ```ts
    * import { lcm } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -994,7 +1034,8 @@ export const lcm: {
   /**
    * Determines the least common multiple of two `bigint`s.
    *
-   * @example
+   * **Example** (Calculating least common multiples)
+   *
    * ```ts
    * import { lcm } from "effect/BigInt"
    * import * as assert from "node:assert"
@@ -1011,9 +1052,13 @@ export const lcm: {
 } = dual(2, (self: bigint, that: bigint): bigint => (self * that) / gcd(self, that))
 
 /**
- * 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 * as assert from "node:assert"
@@ -1041,10 +1086,13 @@ export 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"
@@ -1062,9 +1110,12 @@ export const sqrt = (n: bigint): Option.Option<bigint> =>
   isGreaterThanOrEqualTo(n, bigint0) ? Option.some(sqrtUnsafe(n)) : Option.none()
 
 /**
- * Takes an `Iterable` of `bigint`s and returns their sum as a single `bigint
+ * 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 * as assert from "node:assert"
@@ -1084,9 +1135,13 @@ export 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 * as assert from "node:assert"
@@ -1114,7 +1169,8 @@ export 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"
  *
@@ -1139,7 +1195,8 @@ export 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"
  *
@@ -1168,7 +1225,8 @@ export 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"
  *
@@ -1194,9 +1252,13 @@ export 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"
  *
@@ -1210,9 +1272,13 @@ export function fromNumber(n: number): Option.Option<bigint> {
  */
 export 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"
    *
@@ -1226,9 +1292,13 @@ export 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"
    *