effect 4.0.0-beta.69 → 4.0.0-beta.70

package/dist/Order.js

@@ -54,12 +54,14 @@ import * as Reducer from "./Reducer.js";
 /**
  * Creates a new `Order` instance from a comparison function.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When creating a custom order for a type that doesn't have a built-in order
  * - When you need fine-grained control over comparison logic
  * - When implementing orders for complex types
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Uses reference equality (`===`) as a shortcut: if `self === that`, returns `0` without calling the comparison function
  * - The comparison function should return `-1`, `0`, or `1` based on the comparison result
@@ -80,10 +82,8 @@ import * as Reducer from "./Reducer.js";
  * console.log(byAge({ name: "Alice", age: 25 }, { name: "Bob", age: 30 })) // -1
  * ```
  *
- * See also:
- * - {@link mapInput} - Transform an order by mapping the input type
- * - {@link combine} - Combine multiple orders
- *
+ * @see {@link mapInput} - Transform an order by mapping the input type
+ * @see {@link combine} - Combine multiple orders
  * @category constructors
  * @since 2.0.0
  */
@@ -93,12 +93,14 @@ export function make(compare) {
 /**
  * An `Order` instance for strings that compares them lexicographically using JavaScript's `<` operator.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When comparing strings alphabetically
  * - When sorting string collections
  * - As a base for creating orders on types containing strings
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Uses lexicographic (dictionary) ordering
  * - Empty string is less than any non-empty string
@@ -114,10 +116,8 @@ export function make(compare) {
  * console.log(Order.String("apple", "apple")) // 0
  * ```
  *
- * See also:
- * - {@link mapInput} - Use this order to compare objects by a string property
- * - {@link Struct} - Combine with other orders for struct comparison
- *
+ * @see {@link mapInput} - Use this order to compare objects by a string property
+ * @see {@link Struct} - Combine with other orders for struct comparison
  * @category instances
  * @since 4.0.0
  */
@@ -125,12 +125,14 @@ export const String = /*#__PURE__*/make((self, that) => self < that ? -1 : 1);
 /**
  * An `Order` instance for numbers that compares them numerically.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When comparing numbers for sorting or searching
  * - As a base for creating orders on types containing numbers
  * - When implementing numeric comparisons in data structures
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - `0` is considered equal to `-0`
  * - All `NaN` values are considered equal to each other
@@ -150,10 +152,8 @@ export const String = /*#__PURE__*/make((self, that) => self < that ? -1 : 1);
  * console.log(Order.Number(NaN, 1)) // -1
  * ```
  *
- * See also:
- * - {@link mapInput} - Use this order to compare objects by a number property
- * - {@link BigInt} - For bigint comparisons
- *
+ * @see {@link mapInput} - Use this order to compare objects by a number property
+ * @see {@link BigInt} - For bigint comparisons
  * @category instances
  * @since 4.0.0
  */
@@ -166,12 +166,14 @@ export const Number = /*#__PURE__*/make((self, that) => {
 /**
  * An `Order` instance for booleans where `false` is considered less than `true`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When comparing booleans for sorting or searching
  * - As a base for creating orders on types containing booleans
  * - When implementing boolean-based comparisons
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - `false` is less than `true`
  * - Equal values return `0`
@@ -186,9 +188,7 @@ export const Number = /*#__PURE__*/make((self, that) => {
  * console.log(Order.Boolean(true, true)) // 0
  * ```
  *
- * See also:
- * - {@link mapInput} - Use this order to compare objects by a boolean property
- *
+ * @see {@link mapInput} - Use this order to compare objects by a boolean property
  * @category instances
  * @since 4.0.0
  */
@@ -196,12 +196,14 @@ export const Boolean = /*#__PURE__*/make((self, that) => self < that ? -1 : 1);
 /**
  * An `Order` instance for bigints that compares them numerically.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When comparing bigint values for sorting or searching
  * - As a base for creating orders on types containing bigints
  * - When working with large integers that exceed number precision
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Uses standard numeric comparison for bigint values
  * - Handles arbitrarily large integers
@@ -216,10 +218,8 @@ export const Boolean = /*#__PURE__*/make((self, that) => self < that ? -1 : 1);
  * console.log(Order.BigInt(1n, 1n)) // 0
  * ```
  *
- * See also:
- * - {@link Number} - For regular number comparisons
- * - {@link mapInput} - Use this order to compare objects by a bigint property
- *
+ * @see {@link Number} - For regular number comparisons
+ * @see {@link mapInput} - Use this order to compare objects by a bigint property
  * @category instances
  * @since 4.0.0
  */
@@ -227,12 +227,14 @@ export const BigInt = /*#__PURE__*/make((self, that) => self < that ? -1 : 1);
 /**
  * Creates a new `Order` that reverses the comparison order of the input `Order`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you need descending order instead of ascending
  * - When reversing an existing order without modifying the original
  * - When creating orders that compare in the opposite direction
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Returns a new order that swaps the arguments before comparison
  * - If the original order returns `-1`, the flipped order returns `1`, and vice versa
@@ -250,9 +252,7 @@ export const BigInt = /*#__PURE__*/make((self, that) => self < that ? -1 : 1);
  * console.log(flip(1, 1)) // 0
  * ```
  *
- * See also:
- * - {@link combine} - Combine orders for multi-criteria comparison
- *
+ * @see {@link combine} - Combine orders for multi-criteria comparison
  * @category combinators
  * @since 4.0.0
  */
@@ -263,12 +263,14 @@ export function flip(O) {
  * Combines two `Order` instances to create a new `Order` that first compares using the first `Order`,
  * and if the values are equal, then compares using the second `Order`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you need multi-criteria comparison (e.g., sort by age, then by name)
  * - When creating composite orders from simpler orders
  * - When implementing lexicographic ordering
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - First applies the first order; if the result is non-zero, returns that result
  * - If the first order returns `0` (equal), applies the second order
@@ -297,10 +299,8 @@ export function flip(O) {
  * console.log(byAgeAndName(person1, person3)) // 1 (Alice (30) > Charlie (25))
  * ```
  *
- * See also:
- * - {@link combineAll} - Combine multiple orders from a collection
- * - {@link mapInput} - Transform orders to work with different types
- *
+ * @see {@link combineAll} - Combine multiple orders from a collection
+ * @see {@link mapInput} - Transform orders to work with different types
  * @category combining
  * @since 2.0.0
  */
@@ -314,12 +314,14 @@ export const combine = /*#__PURE__*/dual(2, (self, that) => make((a1, a2) => {
 /**
  * Creates an `Order` that considers all values as equal.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you need an order that doesn't distinguish between values
  * - As a default or fallback order when no meaningful comparison exists
  * - When implementing optional ordering where equality is sufficient
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Always returns `0` regardless of input values
  * - Useful as a neutral element in order composition
@@ -336,9 +338,7 @@ export const combine = /*#__PURE__*/dual(2, (self, that) => make((a1, a2) => {
  * console.log(alwaysEqualOrder(1, 1)) // 0
  * ```
  *
- * See also:
- * - {@link combine} - Combine with other orders
- *
+ * @see {@link combine} - Combine with other orders
  * @category constructors
  * @since 4.0.0
  */
@@ -349,12 +349,14 @@ export function alwaysEqual() {
  * Combines all `Order` instances in the provided collection into a single `Order`.
  * The resulting `Order` compares using each `Order` in sequence until a non-zero result is found.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you have a variable number of orders to combine
  * - When combining orders from a collection or array
  * - When implementing dynamic multi-criteria sorting
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Applies orders in iteration order
  * - Returns the first non-zero result from any order
@@ -383,10 +385,8 @@ export function alwaysEqual() {
  * console.log(combinedOrder(person1, person2)) // -1 (Same age, Alice < Bob)
  * ```
  *
- * See also:
- * - {@link combine} - Combine two orders
- * - {@link makeReducer} - Create a reducer for combining orders
- *
+ * @see {@link combine} - Combine two orders
+ * @see {@link makeReducer} - Create a reducer for combining orders
  * @category combining
  * @since 2.0.0
  */
@@ -406,12 +406,14 @@ export function combineAll(collection) {
  * Transforms an `Order` on type `A` into an `Order` on type `B` by providing a function that
  * maps values of type `B` to values of type `A`.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you have an order for a property type and want to compare objects by that property
  * - When extracting a comparable value from a complex type
  * - When creating orders for types that contain comparable values
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Applies the mapping function to both values before comparison
  * - The mapping function should be pure and not have side effects
@@ -429,10 +431,8 @@ export function combineAll(collection) {
  * console.log(byLength("aa", "bb")) // 0
  * ```
  *
- * See also:
- * - {@link combine} - Combine mapped orders for multi-criteria comparison
- * - {@link Struct} - Create orders for structs with multiple fields
- *
+ * @see {@link combine} - Combine mapped orders for multi-criteria comparison
+ * @see {@link Struct} - Create orders for structs with multiple fields
  * @category mapping
  * @since 2.0.0
  */
@@ -440,12 +440,14 @@ export const mapInput = /*#__PURE__*/dual(2, (self, f) => make((b1, b2) => self(
 /**
  * An `Order` instance for `Date` objects that compares them chronologically by their timestamp.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When comparing dates for sorting or searching
  * - As a base for creating orders on types containing dates
  * - When implementing time-based comparisons
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Compares dates by their underlying timestamp (milliseconds since epoch)
  * - Earlier dates are less than later dates
@@ -464,9 +466,7 @@ export const mapInput = /*#__PURE__*/dual(2, (self, f) => make((b1, b2) => self(
  * console.log(Order.Date(date1, date1)) // 0
  * ```
  *
- * See also:
- * - {@link mapInput} - Use this order to compare objects by a date property
- *
+ * @see {@link mapInput} - Use this order to compare objects by a date property
  * @category instances
  * @since 2.0.0
  */
@@ -474,12 +474,14 @@ export const Date = /*#__PURE__*/mapInput(Number, date => date.getTime());
 /**
  * Creates an `Order` for a tuple type based on orders for each element.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When comparing tuples with different types for each position
  * - When you need type-safe tuple ordering
  * - When working with fixed-length heterogeneous collections
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Compares tuples element-by-element using the corresponding order
  * - Stops at the first non-zero comparison result
@@ -498,9 +500,7 @@ export const Date = /*#__PURE__*/mapInput(Number, date => date.getTime());
  * console.log(tupleOrder([1, "a"], [1, "a"])) // 0
  * ```
  *
- * See also:
- * - {@link Array} - Compare arrays with length consideration
- *
+ * @see {@link Array} - Compare arrays with length consideration
  * @category combinators
  * @since 4.0.0
  */
@@ -537,12 +537,14 @@ export {
 /**
  * Creates an `Order` for arrays by applying the given `Order` to each element, then comparing by length if all elements are equal.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When comparing arrays of the same element type
  * - When you want shorter arrays to be considered less than longer arrays
  * - When sorting collections of arrays
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Compares arrays element-by-element using the provided order
  * - Stops at the first non-zero comparison result
@@ -562,9 +564,7 @@ export {
  * console.log(arrayOrder([1, 2], [1, 2])) // 0
  * ```
  *
- * See also:
- * - {@link Tuple} - Type-safe tuple ordering
- *
+ * @see {@link Tuple} - Type-safe tuple ordering
  * @category combinators
  * @since 4.0.0
  */
@@ -572,12 +572,14 @@ Array_ as Array };
 /**
  * Creates an `Order` for structs by applying the given `Order`s to each property in sequence.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When comparing objects with multiple properties
  * - When you need multi-field comparison for structs
  * - When creating orders for complex data types
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Compares structs field-by-field in the order of keys in the fields object
  * - Stops at the first non-zero comparison result
@@ -603,10 +605,8 @@ Array_ as Array };
  * console.log(personOrder(person1, person1)) // 0
  * ```
  *
- * See also:
- * - {@link combine} - Combine orders manually
- * - {@link mapInput} - Extract and compare by a single property
- *
+ * @see {@link combine} - Combine orders manually
+ * @see {@link mapInput} - Extract and compare by a single property
  * @category combinators
  * @since 4.0.0
  */
@@ -625,12 +625,14 @@ export function Struct(fields) {
 /**
  * Tests whether one value is strictly less than another according to the given order.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you need a boolean predicate instead of an ordering result
  * - When checking if a value is less than another in conditional logic
  * - When implementing range checks or comparisons
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Returns `true` if the order returns `-1` (first value is less than second)
  * - Returns `false` for equal or greater values
@@ -648,10 +650,8 @@ export function Struct(fields) {
  * console.log(isLessThanNumber(1, 1)) // false
  * ```
  *
- * See also:
- * - {@link isLessThanOrEqualTo} - Non-strict less than or equal
- * - {@link isGreaterThan} - Strict greater than
- *
+ * @see {@link isLessThanOrEqualTo} - Non-strict less than or equal
+ * @see {@link isGreaterThan} - Strict greater than
  * @category predicates
  * @since 4.0.0
  */
@@ -659,12 +659,14 @@ export const isLessThan = O => dual(2, (self, that) => O(self, that) === -1);
 /**
  * Tests whether one value is strictly greater than another according to the given order.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you need a boolean predicate instead of an ordering result
  * - When checking if a value is greater than another in conditional logic
  * - When implementing range checks or comparisons
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Returns `true` if the order returns `1` (first value is greater than second)
  * - Returns `false` for equal or lesser values
@@ -682,10 +684,8 @@ export const isLessThan = O => dual(2, (self, that) => O(self, that) === -1);
  * console.log(isGreaterThanNumber(1, 1)) // false
  * ```
  *
- * See also:
- * - {@link isGreaterThanOrEqualTo} - Non-strict greater than or equal
- * - {@link isLessThan} - Strict less than
- *
+ * @see {@link isGreaterThanOrEqualTo} - Non-strict greater than or equal
+ * @see {@link isLessThan} - Strict less than
  * @category predicates
  * @since 4.0.0
  */
@@ -693,12 +693,14 @@ export const isGreaterThan = O => dual(2, (self, that) => O(self, that) === 1);
 /**
  * Tests whether one value is less than or equal to another according to the given order.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you need a boolean predicate for non-strict comparison
  * - When checking if a value is within a range (inclusive lower bound)
  * - When implementing inclusive comparisons
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Returns `true` if the order returns `-1` or `0` (less than or equal)
  * - Returns `false` only if the order returns `1` (greater than)
@@ -716,10 +718,8 @@ export const isGreaterThan = O => dual(2, (self, that) => O(self, that) === 1);
  * console.log(isLessThanOrEqualToNumber(2, 1)) // false
  * ```
  *
- * See also:
- * - {@link isLessThan} - Strict less than
- * - {@link isGreaterThan} - Strict greater than
- *
+ * @see {@link isLessThan} - Strict less than
+ * @see {@link isGreaterThan} - Strict greater than
  * @category predicates
  * @since 4.0.0
  */
@@ -727,12 +727,14 @@ export const isLessThanOrEqualTo = O => dual(2, (self, that) => O(self, that) !=
 /**
  * Tests whether one value is greater than or equal to another according to the given order.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you need a boolean predicate for non-strict comparison
  * - When checking if a value is within a range (inclusive upper bound)
  * - When implementing inclusive comparisons
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Returns `true` if the order returns `1` or `0` (greater than or equal)
  * - Returns `false` only if the order returns `-1` (less than)
@@ -750,10 +752,8 @@ export const isLessThanOrEqualTo = O => dual(2, (self, that) => O(self, that) !=
  * console.log(isGreaterThanOrEqualToNumber(1, 2)) // false
  * ```
  *
- * See also:
- * - {@link isGreaterThan} - Strict greater than
- * - {@link isLessThanOrEqualTo} - Less than or equal
- *
+ * @see {@link isGreaterThan} - Strict greater than
+ * @see {@link isLessThanOrEqualTo} - Less than or equal
  * @category predicates
  * @since 4.0.0
  */
@@ -761,12 +761,14 @@ export const isGreaterThanOrEqualTo = O => dual(2, (self, that) => O(self, that)
 /**
  * Returns the minimum of two values according to the given order. If they are equal, returns the first argument.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you need to find the smaller of two values
  * - When implementing min/max operations
  * - When selecting values based on ordering
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Returns the value that compares as less than or equal to the other
  * - If values are equal, returns the first argument
@@ -784,10 +786,8 @@ export const isGreaterThanOrEqualTo = O => dual(2, (self, that) => O(self, that)
  * console.log(minNumber(1, 1)) // 1
  * ```
  *
- * See also:
- * - {@link max} - Maximum of two values
- * - {@link clamp} - Clamp a value between min and max
- *
+ * @see {@link max} - Maximum of two values
+ * @see {@link clamp} - Clamp a value between min and max
  * @category comparisons
  * @since 2.0.0
  */
@@ -795,12 +795,14 @@ export const min = O => dual(2, (self, that) => self === that || O(self, that) <
 /**
  * Returns the maximum of two values according to the given order. If they are equal, returns the first argument.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you need to find the larger of two values
  * - When implementing min/max operations
  * - When selecting values based on ordering
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Returns the value that compares as greater than or equal to the other
  * - If values are equal, returns the first argument
@@ -818,10 +820,8 @@ export const min = O => dual(2, (self, that) => self === that || O(self, that) <
  * console.log(maxNumber(1, 1)) // 1
  * ```
  *
- * See also:
- * - {@link min} - Minimum of two values
- * - {@link clamp} - Clamp a value between min and max
- *
+ * @see {@link min} - Minimum of two values
+ * @see {@link clamp} - Clamp a value between min and max
  * @category comparisons
  * @since 2.0.0
  */
@@ -829,12 +829,14 @@ export const max = O => dual(2, (self, that) => self === that || O(self, that) >
 /**
  * Clamps a value between a minimum and a maximum according to the given order.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you need to restrict a value to a specific range
  * - When implementing bounds checking and normalization
  * - When ensuring values stay within valid ranges
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Returns the value if it's between minimum and maximum (inclusive)
  * - Returns minimum if the value is less than minimum
@@ -854,11 +856,9 @@ export const max = O => dual(2, (self, that) => self === that || O(self, that) >
  * console.log(clamp(6)) // 5
  * ```
  *
- * See also:
- * - {@link min} - Minimum of two values
- * - {@link max} - Maximum of two values
- * - {@link isBetween} - Check if a value is within a range
- *
+ * @see {@link min} - Minimum of two values
+ * @see {@link max} - Maximum of two values
+ * @see {@link isBetween} - Check if a value is within a range
  * @category comparisons
  * @since 2.0.0
  */
@@ -866,12 +866,14 @@ export const clamp = O => dual(2, (self, options) => min(O)(options.maximum, max
 /**
  * Tests whether a value is between a minimum and a maximum (inclusive) according to the given order.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When validating that a value is within a valid range
  * - When implementing range checks for bounds validation
  * - When filtering or selecting values within a range
  *
- * Behavior:
+ * **Details**
+ *
  * - Pure function: does not mutate inputs
  * - Returns `true` if the value is greater than or equal to minimum and less than or equal to maximum
  * - Returns `false` if the value is outside the range
@@ -892,11 +894,9 @@ export const clamp = O => dual(2, (self, options) => min(O)(options.maximum, max
  * console.log(betweenNumber(11, { minimum: 1, maximum: 10 })) // false
  * ```
  *
- * See also:
- * - {@link clamp} - Clamp a value to a range
- * - {@link isLessThanOrEqualTo} - Less than or equal check
- * - {@link isGreaterThanOrEqualTo} - Greater than or equal check
- *
+ * @see {@link clamp} - Clamp a value to a range
+ * @see {@link isLessThanOrEqualTo} - Less than or equal check
+ * @see {@link isGreaterThanOrEqualTo} - Greater than or equal check
  * @category predicates
  * @since 4.0.0
  */
@@ -904,12 +904,14 @@ export const isBetween = O => dual(2, (self, options) => !isLessThan(O)(self, op
 /**
  * Creates a `Reducer` for combining `Order` instances, useful for aggregating orders in collections.
  *
- * When to use this:
+ * **When to use**
+ *
  * - When you need to combine multiple orders from a collection using reducer patterns
  * - When implementing fold operations over collections of orders
  * - When working with reducers that operate on orders
  *
- * Behavior:
+ * **Details**
+ *
  * - Returns a reducer that combines orders using {@link combine}
  * - Uses {@link alwaysEqual} as the identity element (returns `0` for empty collections)
  * - Uses {@link combineAll} for combining collections of orders
@@ -927,11 +929,9 @@ export const isBetween = O => dual(2, (self, options) => !isLessThan(O)(self, op
  * console.log(combined(1, 2)) // -1 (uses first order)
  * ```
  *
- * See also:
- * - {@link combine} - Combine two orders
- * - {@link combineAll} - Combine multiple orders
- * - {@link Reducer} - Reducer type for collection operations
- *
+ * @see {@link combine} - Combine two orders
+ * @see {@link combineAll} - Combine multiple orders
+ * @see {@link Reducer} - Reducer type for collection operations
  * @category utils
  * @since 4.0.0
  */