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

package/src/Number.ts

@@ -15,7 +15,8 @@ import * as Reducer from "./Reducer.ts"
 /**
  * The global `Number` constructor.
  *
- * @example
+ * **Example** (Coercing values to numbers)
+ *
  * ```ts
  * import * as N from "effect/Number"
  *
@@ -34,7 +35,8 @@ export const Number = globalThis.Number
 /**
  * Tests if a value is a `number`.
  *
- * @example
+ * **Example** (Checking for numbers)
+ *
  * ```ts
  * import { isNumber } from "effect/Number"
  * import * as assert from "node:assert"
@@ -51,7 +53,8 @@ export const isNumber: (input: unknown) => input is number = predicate.isNumber
 /**
  * Provides an addition operation on `number`s.
  *
- * @example
+ * **Example** (Adding numbers)
+ *
  * ```ts
  * import { sum } from "effect/Number"
  * import * as assert from "node:assert"
@@ -66,7 +69,8 @@ export const sum: {
   /**
    * Provides an addition operation on `number`s.
    *
-   * @example
+   * **Example** (Adding numbers)
+   *
    * ```ts
    * import { sum } from "effect/Number"
    * import * as assert from "node:assert"
@@ -81,7 +85,8 @@ export const sum: {
   /**
    * Provides an addition operation on `number`s.
    *
-   * @example
+   * **Example** (Adding numbers)
+   *
    * ```ts
    * import { sum } from "effect/Number"
    * import * as assert from "node:assert"
@@ -98,7 +103,8 @@ export const sum: {
 /**
  * Provides a multiplication operation on `number`s.
  *
- * @example
+ * **Example** (Multiplying numbers)
+ *
  * ```ts
  * import { multiply } from "effect/Number"
  * import * as assert from "node:assert"
@@ -113,7 +119,8 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `number`s.
    *
-   * @example
+   * **Example** (Multiplying numbers)
+   *
    * ```ts
    * import { multiply } from "effect/Number"
    * import * as assert from "node:assert"
@@ -128,7 +135,8 @@ export const multiply: {
   /**
    * Provides a multiplication operation on `number`s.
    *
-   * @example
+   * **Example** (Multiplying numbers)
+   *
    * ```ts
    * import { multiply } from "effect/Number"
    * import * as assert from "node:assert"
@@ -145,7 +153,8 @@ export const multiply: {
 /**
  * Provides a subtraction operation on `number`s.
  *
- * @example
+ * **Example** (Subtracting numbers)
+ *
  * ```ts
  * import { subtract } from "effect/Number"
  * import * as assert from "node:assert"
@@ -160,7 +169,8 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `number`s.
    *
-   * @example
+   * **Example** (Subtracting numbers)
+   *
    * ```ts
    * import { subtract } from "effect/Number"
    * import * as assert from "node:assert"
@@ -175,7 +185,8 @@ export const subtract: {
   /**
    * Provides a subtraction operation on `number`s.
    *
-   * @example
+   * **Example** (Subtracting numbers)
+   *
    * ```ts
    * import { subtract } from "effect/Number"
    * import * as assert from "node:assert"
@@ -194,7 +205,7 @@ export const subtract: {
  *
  * Returns `Option.none()` if the divisor is `0`.
  *
- * **Example**
+ * **Example** (Dividing numbers safely)
  *
  * ```ts
  * import { Number } from "effect"
@@ -212,7 +223,7 @@ export const divide: {
    *
    * Returns `Option.none()` if the divisor is `0`.
    *
-   * **Example**
+   * **Example** (Dividing numbers safely)
    *
    * ```ts
    * import { Number } from "effect"
@@ -230,7 +241,7 @@ export const divide: {
    *
    * Returns `Option.none()` if the divisor is `0`.
    *
-   * **Example**
+   * **Example** (Dividing numbers safely)
    *
    * ```ts
    * import { Number } from "effect"
@@ -253,13 +264,14 @@ export const divide: {
  *
  * Throws a `RangeError` if the divisor is `0`.
  *
- * **Example**
+ * **Example** (Dividing numbers unsafely)
  *
  * ```ts
  * import { Number } from "effect"
  *
- * Number.divideUnsafe(6, 3) // 2
- * Number.divideUnsafe(6, 0) // throws RangeError("Division by zero")
+ * console.log(Number.divideUnsafe(6, 3)) // 2
+ *
+ * // Passing 0 as the divisor throws a RangeError("Division by zero").
  * ```
  *
  * @category math
@@ -271,13 +283,14 @@ export const divideUnsafe: {
    *
    * Throws a `RangeError` if the divisor is `0`.
    *
-   * **Example**
+   * **Example** (Dividing numbers unsafely)
    *
    * ```ts
    * import { Number } from "effect"
    *
-   * Number.divideUnsafe(6, 3) // 2
-   * Number.divideUnsafe(6, 0) // throws RangeError("Division by zero")
+   * console.log(Number.divideUnsafe(6, 3)) // 2
+   *
+   * // Passing 0 as the divisor throws a RangeError("Division by zero").
    * ```
    *
    * @category math
@@ -289,13 +302,14 @@ export const divideUnsafe: {
    *
    * Throws a `RangeError` if the divisor is `0`.
    *
-   * **Example**
+   * **Example** (Dividing numbers unsafely)
    *
    * ```ts
    * import { Number } from "effect"
    *
-   * Number.divideUnsafe(6, 3) // 2
-   * Number.divideUnsafe(6, 0) // throws RangeError("Division by zero")
+   * console.log(Number.divideUnsafe(6, 3)) // 2
+   *
+   * // Passing 0 as the divisor throws a RangeError("Division by zero").
    * ```
    *
    * @category math
@@ -311,7 +325,8 @@ export const divideUnsafe: {
 /**
  * Returns the result of adding `1` to a given number.
  *
- * @example
+ * **Example** (Incrementing a number)
+ *
  * ```ts
  * import { increment } from "effect/Number"
  * import * as assert from "node:assert"
@@ -327,7 +342,8 @@ export const increment = (n: number): number => n + 1
 /**
  * Decrements a number by `1`.
  *
- * @example
+ * **Example** (Decrementing a number)
+ *
  * ```ts
  * import { decrement } from "effect/Number"
  * import * as assert from "node:assert"
@@ -343,7 +359,8 @@ export const decrement = (n: number): number => n - 1
 /**
  * An `Order` instance for `number` values.
  *
- * @example
+ * **Example** (Comparing numbers)
+ *
  * ```ts
  * import * as Number from "effect/Number"
  *
@@ -362,7 +379,8 @@ export const Order: order.Order<number> = order.Number
  *
  * `NaN` is considered equal to `NaN`.
  *
- * @example
+ * **Example** (Comparing numbers for equivalence)
+ *
  * ```ts
  * import { Number } from "effect"
  *
@@ -379,7 +397,8 @@ export const Equivalence: Equ.Equivalence<number> = Equ.Number
 /**
  * Returns `true` if the first argument is less than the second, otherwise `false`.
  *
- * @example
+ * **Example** (Checking less-than comparisons)
+ *
  * ```ts
  * import { isLessThan } from "effect/Number"
  * import * as assert from "node:assert"
@@ -396,7 +415,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/Number"
    * import * as assert from "node:assert"
@@ -413,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/Number"
    * import * as assert from "node:assert"
@@ -432,7 +453,8 @@ export const isLessThan: {
 /**
  * Returns a function that checks if a given `number` is less than or equal to the provided one.
  *
- * @example
+ * **Example** (Checking less-than-or-equal comparisons)
+ *
  * ```ts
  * import { isLessThanOrEqualTo } from "effect/Number"
  * import * as assert from "node:assert"
@@ -449,7 +471,8 @@ export const isLessThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `number` is less than or equal to the provided one.
    *
-   * @example
+   * **Example** (Checking less-than-or-equal comparisons)
+   *
    * ```ts
    * import { isLessThanOrEqualTo } from "effect/Number"
    * import * as assert from "node:assert"
@@ -466,7 +489,8 @@ export const isLessThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `number` is less than or equal to the provided one.
    *
-   * @example
+   * **Example** (Checking less-than-or-equal comparisons)
+   *
    * ```ts
    * import { isLessThanOrEqualTo } from "effect/Number"
    * import * as assert from "node:assert"
@@ -485,7 +509,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/Number"
  * import * as assert from "node:assert"
@@ -502,7 +527,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/Number"
    * import * as assert from "node:assert"
@@ -519,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/Number"
    * import * as assert from "node:assert"
@@ -538,7 +565,8 @@ export const isGreaterThan: {
 /**
  * Returns a function that checks if a given `number` is greater than or equal to the provided one.
  *
- * @example
+ * **Example** (Checking greater-than-or-equal comparisons)
+ *
  * ```ts
  * import { isGreaterThanOrEqualTo } from "effect/Number"
  * import * as assert from "node:assert"
@@ -555,7 +583,8 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `number` is greater than or equal to the provided one.
    *
-   * @example
+   * **Example** (Checking greater-than-or-equal comparisons)
+   *
    * ```ts
    * import { isGreaterThanOrEqualTo } from "effect/Number"
    * import * as assert from "node:assert"
@@ -572,7 +601,8 @@ export const isGreaterThanOrEqualTo: {
   /**
    * Returns a function that checks if a given `number` is greater than or equal to the provided one.
    *
-   * @example
+   * **Example** (Checking greater-than-or-equal comparisons)
+   *
    * ```ts
    * import { isGreaterThanOrEqualTo } from "effect/Number"
    * import * as assert from "node:assert"
@@ -591,7 +621,8 @@ export const isGreaterThanOrEqualTo: {
 /**
  * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
  *
- * @example
+ * **Example** (Checking inclusive ranges)
+ *
  * ```ts
  * import * as Number from "effect/Number"
  * import * as assert from "node:assert"
@@ -610,7 +641,8 @@ export const between: {
   /**
    * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
    *
-   * @example
+   * **Example** (Checking inclusive ranges)
+   *
    * ```ts
    * import * as Number from "effect/Number"
    * import * as assert from "node:assert"
@@ -634,7 +666,8 @@ export const between: {
   /**
    * Checks if a `number` is between a `minimum` and `maximum` value (inclusive).
    *
-   * @example
+   * **Example** (Checking inclusive ranges)
+   *
    * ```ts
    * import * as Number from "effect/Number"
    * import * as assert from "node:assert"
@@ -665,7 +698,8 @@ export const between: {
  * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
  * - Otherwise, it returns the original `number`.
  *
- * @example
+ * **Example** (Clamping to a range)
+ *
  * ```ts
  * import * as Number from "effect/Number"
  * import * as assert from "node:assert"
@@ -688,7 +722,8 @@ export const clamp: {
    * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
    * - Otherwise, it returns the original `number`.
    *
-   * @example
+   * **Example** (Clamping to a range)
+   *
    * ```ts
    * import * as Number from "effect/Number"
    * import * as assert from "node:assert"
@@ -716,7 +751,8 @@ export const clamp: {
    * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
    * - Otherwise, it returns the original `number`.
    *
-   * @example
+   * **Example** (Clamping to a range)
+   *
    * ```ts
    * import * as Number from "effect/Number"
    * import * as assert from "node:assert"
@@ -743,7 +779,8 @@ export const clamp: {
 /**
  * Returns the minimum between two `number`s.
  *
- * @example
+ * **Example** (Finding the minimum)
+ *
  * ```ts
  * import { min } from "effect/Number"
  * import * as assert from "node:assert"
@@ -758,7 +795,8 @@ export const min: {
   /**
    * Returns the minimum between two `number`s.
    *
-   * @example
+   * **Example** (Finding the minimum)
+   *
    * ```ts
    * import { min } from "effect/Number"
    * import * as assert from "node:assert"
@@ -773,7 +811,8 @@ export const min: {
   /**
    * Returns the minimum between two `number`s.
    *
-   * @example
+   * **Example** (Finding the minimum)
+   *
    * ```ts
    * import { min } from "effect/Number"
    * import * as assert from "node:assert"
@@ -790,7 +829,8 @@ export const min: {
 /**
  * Returns the maximum between two `number`s.
  *
- * @example
+ * **Example** (Finding the maximum)
+ *
  * ```ts
  * import { max } from "effect/Number"
  * import * as assert from "node:assert"
@@ -805,7 +845,8 @@ export const max: {
   /**
    * Returns the maximum between two `number`s.
    *
-   * @example
+   * **Example** (Finding the maximum)
+   *
    * ```ts
    * import { max } from "effect/Number"
    * import * as assert from "node:assert"
@@ -820,7 +861,8 @@ export const max: {
   /**
    * Returns the maximum between two `number`s.
    *
-   * @example
+   * **Example** (Finding the maximum)
+   *
    * ```ts
    * import { max } from "effect/Number"
    * import * as assert from "node:assert"
@@ -837,7 +879,8 @@ export const max: {
 /**
  * Determines the sign of a given `number`.
  *
- * @example
+ * **Example** (Determining the sign)
+ *
  * ```ts
  * import { sign } from "effect/Number"
  * import * as assert from "node:assert"
@@ -855,7 +898,8 @@ export const sign = (n: number): Ordering => Order(n, 0)
 /**
  * Takes an `Iterable` of `number`s and returns their sum as a single `number`.
  *
- * @example
+ * **Example** (Summing an iterable)
+ *
  * ```ts
  * import { sumAll } from "effect/Number"
  * import * as assert from "node:assert"
@@ -877,7 +921,8 @@ export const sumAll = (collection: Iterable<number>): number => {
 /**
  * Takes an `Iterable` of `number`s and returns their multiplication as a single `number`.
  *
- * @example
+ * **Example** (Multiplying an iterable)
+ *
  * ```ts
  * import { multiplyAll } from "effect/Number"
  * import * as assert from "node:assert"
@@ -904,7 +949,8 @@ export const multiplyAll = (collection: Iterable<number>): number => {
  *
  * It always takes the sign of the dividend.
  *
- * @example
+ * **Example** (Calculating remainders)
+ *
  * ```ts
  * import { remainder } from "effect/Number"
  * import * as assert from "node:assert"
@@ -923,7 +969,8 @@ export const remainder: {
    *
    * It always takes the sign of the dividend.
    *
-   * @example
+   * **Example** (Calculating remainders)
+   *
    * ```ts
    * import { remainder } from "effect/Number"
    * import * as assert from "node:assert"
@@ -942,7 +989,8 @@ export const remainder: {
    *
    * It always takes the sign of the dividend.
    *
-   * @example
+   * **Example** (Calculating remainders)
+   *
    * ```ts
    * import { remainder } from "effect/Number"
    * import * as assert from "node:assert"
@@ -979,7 +1027,8 @@ function decimalCount(n: number): number {
 /**
  * Returns the next power of 2 from the given number.
  *
- * @example
+ * **Example** (Finding the next power of two)
+ *
  * ```ts
  * import { nextPow2 } from "effect/Number"
  * import * as assert from "node:assert"
@@ -1000,7 +1049,7 @@ export const nextPow2 = (n: number): number => {
  * Tries to parse a `number` from a `string` using the `Number()` function.
  * The following special string values are supported: "NaN", "Infinity", "-Infinity".
  *
- * **Example**
+ * **Example** (Parsing numbers from strings)
  *
  * ```ts
  * import { Number } from "effect"
@@ -1036,7 +1085,8 @@ export const parse = (s: string): Option.Option<number> => {
 /**
  * Returns the number rounded with the given precision.
  *
- * @example
+ * **Example** (Rounding with precision)
+ *
  * ```ts
  * import { round } from "effect/Number"
  * import * as assert from "node:assert"
@@ -1052,7 +1102,8 @@ export const round: {
   /**
    * Returns the number rounded with the given precision.
    *
-   * @example
+   * **Example** (Rounding with precision)
+   *
    * ```ts
    * import { round } from "effect/Number"
    * import * as assert from "node:assert"
@@ -1068,7 +1119,8 @@ export const round: {
   /**
    * Returns the number rounded with the given precision.
    *
-   * @example
+   * **Example** (Rounding with precision)
+   *
    * ```ts
    * import { round } from "effect/Number"
    * import * as assert from "node:assert"
@@ -1108,14 +1160,14 @@ export const ReducerMultiply: Reducer.Reducer<number> = Reducer.make((a, b) => a
 })
 
 /**
- * A `Combiner` that returns the maximum `number`.
+ * A `Reducer` for reducing `number`s by keeping the maximum value.
  *
  * @since 4.0.0
  */
 export const ReducerMax: Reducer.Reducer<number> = Reducer.make((a, b) => Math.max(a, b), -Infinity)
 
 /**
- * A `Combiner` that returns the minimum `number`.
+ * A `Reducer` for reducing `number`s by keeping the minimum value.
  *
  * @since 4.0.0
  */

package/src/Optic.ts

@@ -92,7 +92,6 @@
  * - {@link some} / {@link success} / {@link failure} — built-in prisms
  *
  * @since 4.0.0
- * @module
  */
 
 import { format } from "./Formatter.ts"
@@ -882,7 +881,7 @@ export interface Optional<in out S, in out A> {
    *
    * @see `.pick()` — the inverse operation
    *
-   * @since 1.0.0
+   * @since 4.0.0
    */
   omit<S, A, Keys extends ReadonlyArray<keyof A>>(
     this: Lens<S, A>,