effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/BigDecimal.ts

@@ -132,7 +132,7 @@ const BigDecimalProto: Omit<BigDecimal, "value" | "scale" | "normalized"> = {
 } as const
 
 /**
- * Checks if a given value is a `BigDecimal`.
+ * Checks whether a given value is a `BigDecimal`.
  *
  * **When to use**
  *
@@ -272,7 +272,7 @@ export const normalize = (self: BigDecimal): BigDecimal => {
 }
 
 /**
- * Scales a `BigDecimal` to the specified scale.
+ * Changes a `BigDecimal` to the specified scale.
  *
  * **When to use**
  *
@@ -307,7 +307,7 @@ export const normalize = (self: BigDecimal): BigDecimal => {
  */
 export const scale: {
   /**
-   * Scales a `BigDecimal` to the specified scale.
+   * Changes a `BigDecimal` to the specified scale.
    *
    * **When to use**
    *
@@ -342,7 +342,7 @@ export const scale: {
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
-   * Scales a `BigDecimal` to the specified scale.
+   * Changes a `BigDecimal` to the specified scale.
    *
    * **When to use**
    *
@@ -791,7 +791,7 @@ export const roundTerminal = (n: bigint): bigint => {
 }
 
 /**
- * Provides a division operation on `BigDecimal`s.
+ * Divides `BigDecimal`s safely.
  *
  * **When to use**
  *
@@ -843,7 +843,7 @@ export const roundTerminal = (n: bigint): bigint => {
  */
 export const divide: {
   /**
-   * Provides a division operation on `BigDecimal`s.
+   * Divides `BigDecimal`s safely.
    *
    * **When to use**
    *
@@ -895,7 +895,7 @@ export const divide: {
    */
   (that: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>
   /**
-   * Provides a division operation on `BigDecimal`s.
+   * Divides `BigDecimal`s safely.
    *
    * **When to use**
    *
@@ -968,8 +968,8 @@ export const divide: {
  *
  * **When to use**
  *
- * Use when the divisor is known to be non-zero and division by zero should be a
- * thrown exception.
+ * Use when you need the decimal quotient and the divisor is known to be
+ * non-zero, so division by zero should be a thrown exception.
  *
  * **Details**
  *
@@ -1000,8 +1000,8 @@ export const divideUnsafe: {
    *
    * **When to use**
    *
-   * Use when the divisor is known to be non-zero and division by zero should be a
-   * thrown exception.
+   * Use when you need the decimal quotient and the divisor is known to be
+   * non-zero, so division by zero should be a thrown exception.
    *
    * **Details**
    *
@@ -1032,8 +1032,8 @@ export const divideUnsafe: {
    *
    * **When to use**
    *
-   * Use when the divisor is known to be non-zero and division by zero should be a
-   * thrown exception.
+   * Use when you need the decimal quotient and the divisor is known to be
+   * non-zero, so division by zero should be a thrown exception.
    *
    * **Details**
    *
@@ -1080,7 +1080,8 @@ export const divideUnsafe: {
  *
  * **When to use**
  *
- * Use when an API needs an `Order` instance for `BigDecimal` values.
+ * Use when sorting or comparing decimal values through APIs that accept an
+ * ordering instance.
  *
  * **Example** (Comparing decimals)
  *
@@ -1212,7 +1213,7 @@ export const isLessThan: {
 } = order.isLessThan(Order)
 
 /**
- * Checks if a given `BigDecimal` is less than or equal to the provided one.
+ * Checks whether a given `BigDecimal` is less than or equal to the provided one.
  *
  * **When to use**
  *
@@ -1243,7 +1244,7 @@ export const isLessThan: {
  */
 export const isLessThanOrEqualTo: {
   /**
-   * Checks if a given `BigDecimal` is less than or equal to the provided one.
+   * Checks whether a given `BigDecimal` is less than or equal to the provided one.
    *
    * **When to use**
    *
@@ -1274,7 +1275,7 @@ export const isLessThanOrEqualTo: {
    */
   (that: BigDecimal): (self: BigDecimal) => boolean
   /**
-   * Checks if a given `BigDecimal` is less than or equal to the provided one.
+   * Checks whether a given `BigDecimal` is less than or equal to the provided one.
    *
    * **When to use**
    *
@@ -1402,7 +1403,7 @@ export const isGreaterThan: {
 } = order.isGreaterThan(Order)
 
 /**
- * Checks if a given `BigDecimal` is greater than or equal to the provided one.
+ * Checks whether a given `BigDecimal` is greater than or equal to the provided one.
  *
  * **When to use**
  *
@@ -1433,7 +1434,7 @@ export const isGreaterThan: {
  */
 export const isGreaterThanOrEqualTo: {
   /**
-   * Checks if a given `BigDecimal` is greater than or equal to the provided one.
+   * Checks whether a given `BigDecimal` is greater than or equal to the provided one.
    *
    * **When to use**
    *
@@ -1464,7 +1465,7 @@ export const isGreaterThanOrEqualTo: {
    */
   (that: BigDecimal): (self: BigDecimal) => boolean
   /**
-   * Checks if a given `BigDecimal` is greater than or equal to the provided one.
+   * Checks whether a given `BigDecimal` is greater than or equal to the provided one.
    *
    * **When to use**
    *
@@ -1497,7 +1498,7 @@ export const isGreaterThanOrEqualTo: {
 } = order.isGreaterThanOrEqualTo(Order)
 
 /**
- * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+ * Checks whether a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
  *
  * **When to use**
  *
@@ -1526,7 +1527,7 @@ export const isGreaterThanOrEqualTo: {
  */
 export const between: {
   /**
-   * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+   * Checks whether a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
    *
    * **When to use**
    *
@@ -1560,7 +1561,7 @@ export const between: {
     }
   ): (self: BigDecimal) => boolean
   /**
-   * Checks if a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
+   * Checks whether a `BigDecimal` is between a `minimum` and `maximum` value (inclusive).
    *
    * **When to use**
    *
@@ -1964,7 +1965,8 @@ export const abs = (n: BigDecimal): BigDecimal => n.value < bigint0 ? make(-n.va
 export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
 
 /**
- * Returns the remainder left over when one operand is divided by a second operand.
+ * Computes the decimal remainder safely when one operand is divided by a second
+ * operand.
  *
  * **When to use**
  *
@@ -2012,7 +2014,8 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
  */
 export const remainder: {
   /**
-   * Returns the remainder left over when one operand is divided by a second operand.
+   * Computes the decimal remainder safely when one operand is divided by a second
+   * operand.
    *
    * **When to use**
    *
@@ -2060,7 +2063,8 @@ export const remainder: {
    */
   (divisor: BigDecimal): (self: BigDecimal) => Option.Option<BigDecimal>
   /**
-   * Returns the remainder left over when one operand is divided by a second operand.
+   * Computes the decimal remainder safely when one operand is divided by a second
+   * operand.
    *
    * **When to use**
    *
@@ -2117,12 +2121,13 @@ export const remainder: {
 })
 
 /**
- * Returns the remainder left over when one operand is divided by a second operand.
+ * Returns the decimal remainder left over when one operand is divided by a
+ * non-zero second operand, throwing for division by zero.
  *
  * **When to use**
  *
- * Use when the divisor is known to be non-zero and division by zero should be a
- * thrown exception.
+ * Use when you need the decimal remainder and the divisor is known to be
+ * non-zero, so division by zero should be a thrown exception.
  *
  * **Gotchas**
  *
@@ -2155,12 +2160,13 @@ export const remainder: {
  */
 export const remainderUnsafe: {
   /**
-   * Returns the remainder left over when one operand is divided by a second operand.
+   * Returns the decimal remainder left over when one operand is divided by a
+   * non-zero second operand, throwing for division by zero.
    *
    * **When to use**
    *
-   * Use when the divisor is known to be non-zero and division by zero should be a
-   * thrown exception.
+   * Use when you need the decimal remainder and the divisor is known to be
+   * non-zero, so division by zero should be a thrown exception.
    *
    * **Gotchas**
    *
@@ -2193,12 +2199,13 @@ export const remainderUnsafe: {
    */
   (divisor: BigDecimal): (self: BigDecimal) => BigDecimal
   /**
-   * Returns the remainder left over when one operand is divided by a second operand.
+   * Returns the decimal remainder left over when one operand is divided by a
+   * non-zero second operand, throwing for division by zero.
    *
    * **When to use**
    *
-   * Use when the divisor is known to be non-zero and division by zero should be a
-   * thrown exception.
+   * Use when you need the decimal remainder and the divisor is known to be
+   * non-zero, so division by zero should be a thrown exception.
    *
    * **Gotchas**
    *
@@ -2244,7 +2251,8 @@ export const remainderUnsafe: {
  *
  * **When to use**
  *
- * Use when an API needs an `Equivalence` instance for decimal equality.
+ * Use when comparing decimal values through APIs that accept an equivalence
+ * relation.
  *
  * **Example** (Checking decimal equivalence)
  *
@@ -2275,7 +2283,7 @@ export const Equivalence: Equ.Equivalence<BigDecimal> = Equ.make((self, that) =>
 })
 
 /**
- * Checks if two `BigDecimal`s are equal.
+ * Checks whether two `BigDecimal`s are equal.
  *
  * **When to use**
  *
@@ -2301,7 +2309,7 @@ export const Equivalence: Equ.Equivalence<BigDecimal> = Equ.make((self, that) =>
  */
 export const equals: {
   /**
-   * Checks if two `BigDecimal`s are equal.
+   * Checks whether two `BigDecimal`s are equal.
    *
    * **When to use**
    *
@@ -2327,7 +2335,7 @@ export const equals: {
    */
   (that: BigDecimal): (self: BigDecimal) => boolean
   /**
-   * Checks if two `BigDecimal`s are equal.
+   * Checks whether two `BigDecimal`s are equal.
    *
    * **When to use**
    *
@@ -2381,7 +2389,7 @@ export const equals: {
 export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
 
 /**
- * Creates a `BigDecimal` from a `number` value.
+ * Creates a `BigDecimal` from a finite `number`, throwing for non-finite input.
  *
  * **When to use**
  *
@@ -2414,7 +2422,7 @@ export const fromNumberUnsafe = (n: number): BigDecimal => {
 }
 
 /**
- * Creates a `BigDecimal` from a `number` value.
+ * Creates a `BigDecimal` safely from a finite `number`.
  *
  * **When to use**
  *
@@ -2465,7 +2473,7 @@ export const fromNumber = (n: number): Option.Option<BigDecimal> => {
 }
 
 /**
- * Safely parses a decimal string into a `BigDecimal`.
+ * Parses a decimal string into a `BigDecimal` safely.
  *
  * **When to use**
  *
@@ -2706,7 +2714,7 @@ export const toExponential = (n: BigDecimal): string => {
 export const toNumberUnsafe = (n: BigDecimal): number => Number(format(n))
 
 /**
- * Checks if a given `BigDecimal` is an integer.
+ * Checks whether a given `BigDecimal` is an integer.
  *
  * **When to use**
  *
@@ -2729,7 +2737,7 @@ export const toNumberUnsafe = (n: BigDecimal): number => Number(format(n))
 export const isInteger = (n: BigDecimal): boolean => normalize(n).scale <= 0
 
 /**
- * Checks if a given `BigDecimal` is `0`.
+ * Checks whether a given `BigDecimal` is `0`.
  *
  * **When to use**
  *
@@ -2751,7 +2759,7 @@ export const isInteger = (n: BigDecimal): boolean => normalize(n).scale <= 0
 export const isZero = (n: BigDecimal): boolean => n.value === bigint0
 
 /**
- * Checks if a given `BigDecimal` is negative.
+ * Checks whether a given `BigDecimal` is negative.
  *
  * **When to use**
  *
@@ -2774,7 +2782,7 @@ export const isZero = (n: BigDecimal): boolean => n.value === bigint0
 export const isNegative = (n: BigDecimal): boolean => n.value < bigint0
 
 /**
- * Checks if a given `BigDecimal` is positive.
+ * Checks whether a given `BigDecimal` is positive.
  *
  * **When to use**
  *
@@ -2840,7 +2848,7 @@ export type RoundingMode =
   | "half-odd"
 
 /**
- * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
+ * Computes a rounded `BigDecimal` at the given scale with the specified rounding mode.
  *
  * **When to use**
  *
@@ -2871,7 +2879,7 @@ export type RoundingMode =
  */
 export const round: {
   /**
-   * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
+   * Computes a rounded `BigDecimal` at the given scale with the specified rounding mode.
    *
    * **When to use**
    *
@@ -2902,7 +2910,7 @@ export const round: {
    */
   (options: { scale?: number; mode?: RoundingMode }): (self: BigDecimal) => BigDecimal
   /**
-   * Rounds a `BigDecimal` at the given scale with the specified rounding mode.
+   * Computes a rounded `BigDecimal` at the given scale with the specified rounding mode.
    *
    * **When to use**
    *
@@ -2980,7 +2988,7 @@ export const round: {
 })
 
 /**
- * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+ * Computes a truncated `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
  * rounding toward zero.
  *
  * **When to use**
@@ -3005,7 +3013,7 @@ export const round: {
  */
 export const truncate: {
   /**
-   * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+   * Computes a truncated `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
    * rounding toward zero.
    *
    * **When to use**
@@ -3030,7 +3038,7 @@ export const truncate: {
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
-   * Truncate a `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
+   * Computes a truncated `BigDecimal` at the given scale. This removes fractional digits beyond the scale,
    * rounding toward zero.
    *
    * **When to use**
@@ -3064,7 +3072,7 @@ export const truncate: {
 })
 
 /**
- * Calculate the ceiling of a `BigDecimal` at the given scale.
+ * Computes the ceiling of a `BigDecimal` at the given scale.
  *
  * **When to use**
  *
@@ -3098,7 +3106,7 @@ export const truncate: {
  */
 export const ceil: {
   /**
-   * Calculate the ceiling of a `BigDecimal` at the given scale.
+   * Computes the ceiling of a `BigDecimal` at the given scale.
    *
    * **When to use**
    *
@@ -3132,7 +3140,7 @@ export const ceil: {
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
-   * Calculate the ceiling of a `BigDecimal` at the given scale.
+   * Computes the ceiling of a `BigDecimal` at the given scale.
    *
    * **When to use**
    *
@@ -3209,7 +3217,7 @@ export const digitAt: {
 })
 
 /**
- * Calculate the floor of a `BigDecimal` at the given scale.
+ * Computes the floor of a `BigDecimal` at the given scale.
  *
  * **When to use**
  *
@@ -3240,7 +3248,7 @@ export const digitAt: {
  */
 export const floor: {
   /**
-   * Calculate the floor of a `BigDecimal` at the given scale.
+   * Computes the floor of a `BigDecimal` at the given scale.
    *
    * **When to use**
    *
@@ -3271,7 +3279,7 @@ export const floor: {
    */
   (scale: number): (self: BigDecimal) => BigDecimal
   /**
-   * Calculate the floor of a `BigDecimal` at the given scale.
+   * Computes the floor of a `BigDecimal` at the given scale.
    *
    * **When to use**
    *

package/src/BigInt.ts

@@ -78,11 +78,11 @@ import * as predicate from "./Predicate.ts"
 import * as Reducer from "./Reducer.ts"
 
 /**
- * Reference to the global `BigInt` constructor for JavaScript bigint coercion.
+ * Exposes the global bigint constructor for JavaScript bigint coercion.
  *
  * **When to use**
  *
- * Use when you want the native `BigInt` constructor behavior from the Effect
+ * Use to access native JavaScript bigint constructor coercion from the Effect
  * module namespace.
  *
  * **Gotchas**
@@ -115,7 +115,7 @@ const bigint1 = BigInt(1)
 const bigint2 = BigInt(2)
 
 /**
- * Tests if a value is a `bigint`.
+ * Checks whether a value is a `bigint`.
  *
  * **When to use**
  *
@@ -335,7 +335,7 @@ export const subtract: {
 } = dual(2, (self: bigint, that: bigint): bigint => self - that)
 
 /**
- * Safely divides one `bigint` by another.
+ * Divides one `bigint` by another safely.
  *
  * **When to use**
  *
@@ -365,7 +365,7 @@ export const subtract: {
  */
 export const divide: {
   /**
-   * Safely divides one `bigint` by another.
+   * Divides one `bigint` by another safely.
    *
    * **When to use**
    *
@@ -395,7 +395,7 @@ export const divide: {
    */
   (that: bigint): (self: bigint) => Option.Option<bigint>
   /**
-   * Safely divides one `bigint` by another.
+   * Divides one `bigint` by another safely.
    *
    * **When to use**
    *
@@ -577,7 +577,8 @@ export const decrement = (n: bigint): bigint => n - bigint1
  *
  * **When to use**
  *
- * Use when an API needs an `Order` instance for `bigint` values.
+ * Use when sorting or comparing bigint values through APIs that accept an
+ * ordering instance.
  *
  * **Example** (Comparing bigints with Order)
  *
@@ -599,11 +600,12 @@ export const decrement = (n: bigint): bigint => n - bigint1
 export const Order: order.Order<bigint> = order.BigInt
 
 /**
- * An `Equivalence` instance for bigints using strict equality (`===`).
+ * Equivalence instance for bigints using strict equality (`===`).
  *
  * **When to use**
  *
- * Use when an API needs an `Equivalence` instance for `bigint` equality.
+ * Use when checking bigint equality through APIs that accept an equivalence
+ * relation.
  *
  * **Example** (Comparing bigints for equivalence)
  *
@@ -892,7 +894,7 @@ export const isGreaterThanOrEqualTo: {
 } = order.isGreaterThanOrEqualTo(Order)
 
 /**
- * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
+ * Checks whether a `bigint` is between a `minimum` and `maximum` value (inclusive).
  *
  * **When to use**
  *
@@ -918,7 +920,7 @@ export const isGreaterThanOrEqualTo: {
  */
 export const between: {
   /**
-   * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
+   * Checks whether a `bigint` is between a `minimum` and `maximum` value (inclusive).
    *
    * **When to use**
    *
@@ -949,7 +951,7 @@ export const between: {
     }
   ): (self: bigint) => boolean
   /**
-   * Checks if a `bigint` is between a `minimum` and `maximum` value (inclusive).
+   * Checks whether a `bigint` is between a `minimum` and `maximum` value (inclusive).
    *
    * **When to use**
    *
@@ -1475,7 +1477,7 @@ export const sqrtUnsafe = (n: bigint): bigint => {
 }
 
 /**
- * Safely returns the integer square root of a `bigint`.
+ * Computes the integer square root of a `bigint` safely.
  *
  * **When to use**
  *
@@ -1571,7 +1573,7 @@ export const multiplyAll = (collection: Iterable<bigint>): bigint => {
 }
 
 /**
- * Converts a `bigint` to a `number`.
+ * Converts a `bigint` to a `number` safely.
  *
  * **When to use**
  *
@@ -1606,7 +1608,7 @@ export const toNumber = (b: bigint): Option.Option<number> => {
 }
 
 /**
- * Converts a string to a `bigint`.
+ * Parses a string into a `bigint` safely.
  *
  * **When to use**
  *
@@ -1783,7 +1785,7 @@ export const remainder: {
 } = dual(2, (self: bigint, divisor: bigint): bigint => self % divisor)
 
 /**
- * A `Reducer` for combining `bigint`s using addition.
+ * Reducer for combining `bigint`s using addition.
  *
  * **When to use**
  *
@@ -1802,7 +1804,7 @@ export const remainder: {
 export const ReducerSum: Reducer.Reducer<bigint> = Reducer.make((a, b) => a + b, bigint0)
 
 /**
- * A `Reducer` for combining `bigint`s using multiplication.
+ * Reducer for combining `bigint`s using multiplication.
  *
  * **When to use**
  *
@@ -1828,7 +1830,7 @@ export const ReducerMultiply: Reducer.Reducer<bigint> = Reducer.make((a, b) => a
 })
 
 /**
- * A `Combiner` that returns the maximum `bigint`.
+ * Combiner that returns the maximum `bigint`.
  *
  * **When to use**
  *
@@ -1843,7 +1845,7 @@ export const ReducerMultiply: Reducer.Reducer<bigint> = Reducer.make((a, b) => a
 export const CombinerMax: Combiner.Combiner<bigint> = Combiner.max(Order)
 
 /**
- * A `Combiner` that returns the minimum `bigint`.
+ * Combiner that returns the minimum `bigint`.
  *
  * **When to use**
  *