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

package/dist/BigInt.d.ts

@@ -13,7 +13,8 @@ import * as Reducer from "./Reducer.ts";
 /**
  * Reference to the global BigInt constructor.
  *
- * @example
+ * **Example** (Constructing bigints)
+ *
  * ```ts
  * import * as BigInt from "effect/BigInt"
  *
@@ -31,7 +32,8 @@ export declare const BigInt: BigIntConstructor;
 /**
  * Tests if a value is a `bigint`.
  *
- * @example
+ * **Example** (Checking for bigints)
+ *
  * ```ts
  * import { isBigInt } from "effect/BigInt"
  * import * as assert from "node:assert"
@@ -47,7 +49,8 @@ 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 * as assert from "node:assert"
@@ -62,7 +65,8 @@ export declare 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"
@@ -77,7 +81,8 @@ export declare 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"
@@ -93,7 +98,8 @@ export declare 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"
@@ -108,7 +114,8 @@ export declare 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"
@@ -123,7 +130,8 @@ export declare 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"
@@ -139,7 +147,8 @@ export declare 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"
@@ -154,7 +163,8 @@ export declare 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"
@@ -169,7 +179,8 @@ export declare 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"
@@ -183,14 +194,13 @@ 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 * as assert from "node:assert"
@@ -206,14 +216,13 @@ 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 * as assert from "node:assert"
@@ -229,14 +238,13 @@ 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 * as assert from "node:assert"
@@ -253,14 +261,13 @@ 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 * as assert from "node:assert"
@@ -274,14 +281,13 @@ export declare const divide: {
  */
 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 * as assert from "node:assert"
@@ -295,14 +301,13 @@ export declare 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"
@@ -317,9 +322,10 @@ export declare const divideUnsafe: {
     (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 * as assert from "node:assert"
@@ -332,9 +338,10 @@ 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 * as assert from "node:assert"
@@ -349,7 +356,8 @@ 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"
  *
@@ -369,7 +377,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"
  *
@@ -384,7 +393,8 @@ 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 * as assert from "node:assert"
@@ -401,7 +411,8 @@ 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 * as assert from "node:assert"
@@ -418,7 +429,8 @@ 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 * as assert from "node:assert"
@@ -436,7 +448,8 @@ export declare 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"
@@ -453,7 +466,8 @@ 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 * as assert from "node:assert"
@@ -470,7 +484,8 @@ 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 * as assert from "node:assert"
@@ -488,7 +503,8 @@ export declare 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"
@@ -505,7 +521,8 @@ 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 * as assert from "node:assert"
@@ -522,7 +539,8 @@ 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 * as assert from "node:assert"
@@ -540,7 +558,8 @@ export declare 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"
@@ -557,7 +576,8 @@ 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 * as assert from "node:assert"
@@ -574,7 +594,8 @@ 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 * as assert from "node:assert"
@@ -592,7 +613,8 @@ export declare 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"
@@ -611,7 +633,8 @@ 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 * as assert from "node:assert"
@@ -633,7 +656,8 @@ 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 * as assert from "node:assert"
@@ -660,7 +684,8 @@ 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 * as assert from "node:assert"
@@ -683,7 +708,8 @@ 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 * as assert from "node:assert"
@@ -709,7 +735,8 @@ 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 * as assert from "node:assert"
@@ -732,7 +759,8 @@ export declare 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"
@@ -747,7 +775,8 @@ export declare 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"
@@ -762,7 +791,8 @@ export declare 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"
@@ -778,7 +808,8 @@ export declare 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"
@@ -793,7 +824,8 @@ export declare 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"
@@ -808,7 +840,8 @@ export declare 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"
@@ -824,7 +857,8 @@ export declare 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"
@@ -841,7 +875,8 @@ 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 * as assert from "node:assert"
@@ -858,7 +893,8 @@ 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 * as assert from "node:assert"
@@ -875,7 +911,8 @@ 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 * as assert from "node:assert"
@@ -892,7 +929,8 @@ 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 * as assert from "node:assert"
@@ -910,7 +948,8 @@ 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 * as assert from "node:assert"
@@ -927,7 +966,8 @@ 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 * as assert from "node:assert"
@@ -944,7 +984,8 @@ 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 * as assert from "node:assert"
@@ -960,9 +1001,13 @@ 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 * as assert from "node:assert"
@@ -977,10 +1022,13 @@ export declare const lcm: {
  */
 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,9 +1044,12 @@ 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 * as assert from "node:assert"
@@ -1011,9 +1062,13 @@ 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 * as assert from "node:assert"
@@ -1031,7 +1086,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"
  *
@@ -1050,7 +1106,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"
  *
@@ -1070,7 +1127,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"
  *
@@ -1085,9 +1143,13 @@ export declare const fromString: (s: string) => Option.Option<bigint>;
  */
 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 +1163,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 +1183,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"
      *