@dereekb/util 13.11.14 → 13.11.15

package/src/lib/number/bitwise.dencoder.d.ts

@@ -30,8 +30,8 @@ export type BitwiseSetEncoder<D extends BitwiseEncodedSetIndex> = (set: Set<D>)
 /**
  * Encodes a Set of bit indices into a single {@link BitwiseEncodedSet} number using bitwise OR.
  *
- * @param input - Set of indices (0-31) to encode
- * @returns A number with bits set at each index position
+ * @param input - Set of indices (0-31) to encode.
+ * @returns Encoded value with each requested bit position set high.
  */
 export declare function encodeBitwiseSet<D extends BitwiseEncodedSetIndex>(input: Set<D>): BitwiseEncodedSet;
 /**
@@ -41,8 +41,8 @@ export type BitwiseSetDecoder<D extends BitwiseEncodedSetIndex> = (set: BitwiseE
 /**
  * Creates a decoder that converts a {@link BitwiseEncodedSet} number back into a Set of indices by checking each bit position up to `maxIndex`.
  *
- * @param maxIndex - The exclusive upper bound of indices to check
- * @returns A function that decodes an encoded number into a Set of active indices
+ * @param maxIndex - The exclusive upper bound of indices to check.
+ * @returns Reusable decoder that materializes the set of high-bit indices below `maxIndex`.
  */
 export declare function bitwiseSetDecoder<D extends BitwiseEncodedSetIndex>(maxIndex: number): BitwiseSetDecoder<D>;
 /**
@@ -58,8 +58,8 @@ export type BitwiseSetDencoder<D extends BitwiseEncodedSetIndex> = BitwiseSetEnc
  *
  * Accepts either a Set (encodes to number) or a number (decodes to Set).
  *
- * @param maxIndex - Optional exclusive upper bound of indices for decoding; defaults to 32
- * @returns A function that encodes Sets to numbers and decodes numbers to Sets
+ * @param maxIndex - Optional exclusive upper bound of indices for decoding; defaults to 32.
+ * @returns Encodes Sets to numbers and decodes numbers to Sets.
  */
 export declare function bitwiseSetDencoder<D extends BitwiseEncodedSetIndex>(maxIndex?: number): BitwiseSetDencoder<D>;
 /**
@@ -79,8 +79,8 @@ export type BitwiseObjectEncoder<T extends object> = (object: T) => BitwiseEncod
  *
  * Uses the provided `toSetFunction` to first map the object to a Set of indices, then encodes it.
  *
- * @param toSetFunction - Function that maps an object to a Set of bit indices
- * @returns An encoder function that produces a bitwise-encoded number from the object
+ * @param toSetFunction - Function that maps an object to a Set of bit indices.
+ * @returns An encoder function that produces a bitwise-encoded number from the object.
  */
 export declare function bitwiseObjectEncoder<T extends object, D extends BitwiseEncodedSetIndex>(toSetFunction: BitwiseObjectToSetFunction<T, D>): BitwiseObjectEncoder<T>;
 /**
@@ -90,9 +90,9 @@ export type BitwiseObjectDecoder<T extends object> = (set: BitwiseEncodedSet) =>
 /**
  * Creates a {@link BitwiseObjectDecoder} that converts a {@link BitwiseEncodedSet} number back into an object.
  *
- * @param fromSetFunction - Function that maps a Set of bit indices back to an object
- * @param maxIndex - Optional exclusive upper bound of indices for decoding; defaults to 32
- * @returns A decoder function that produces an object from a bitwise-encoded number
+ * @param fromSetFunction - Function that maps a Set of bit indices back to an object.
+ * @param maxIndex - Optional exclusive upper bound of indices for decoding; defaults to 32.
+ * @returns A decoder function that produces an object from a bitwise-encoded number.
  */
 export declare function bitwiseObjectdecoder<T extends object, D extends BitwiseEncodedSetIndex>(fromSetFunction: BitwiseObjectFromSetFunction<T, D>, maxIndex?: number): BitwiseObjectDecoder<T>;
 /**
@@ -113,6 +113,6 @@ export interface BitwiseObjectDencoderConfig<T extends object, D extends Bitwise
  * Accepts either a number (decodes to object) or an object (encodes to number). Returns 0 for null/undefined input.
  *
  * @param config - Configuration with `toSetFunction`, `fromSetFunction`, and optional `maxIndex`
- * @returns A function that encodes objects to numbers and decodes numbers to objects
+ * @returns Encodes objects to numbers and decodes numbers to objects.
  */
 export declare function bitwiseObjectDencoder<T extends object, D extends BitwiseEncodedSetIndex = BitwiseEncodedSetIndex>(config: BitwiseObjectDencoderConfig<T, D>): BitwiseObjectDencoder<T>;

package/src/lib/number/bound.d.ts

@@ -12,7 +12,7 @@ export interface NumberBound<T extends number = number> {
 /**
  * Checks whether a {@link NumberBound} is valid (min is less than or equal to max).
  *
- * @param bounds - The bounds to validate
+ * @param bounds - The bounds to validate.
  * @returns `true` if `min <= max`
  */
 export declare function isValidNumberBound(bounds: NumberBound): boolean;
@@ -20,15 +20,16 @@ export type IsInNumberBoundFunction = (number: number) => boolean;
 /**
  * Creates a function that checks whether a number falls within the specified inclusive bounds.
  *
+ * @param bounds - The min/max bounds to test against.
+ * @returns Returns `true` if the input number is within bounds.
+ * @throws {Error} If the bounds are invalid (min > max)
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilKind factory
  * @dbxUtilTags number, bound, range, between, check, inclusive, factory
  * @dbxUtilRelated bound-number-function, bound-number, is-valid-number-bound
  *
- * @param bounds - The min/max bounds to test against
- * @returns A function that returns `true` if the input number is within bounds
- * @throws Error if the bounds are invalid (min > max)
  * @__NO_SIDE_EFFECTS__
  */
 export declare function isInNumberBoundFunction(bounds: NumberBound): IsInNumberBoundFunction;
@@ -48,14 +49,15 @@ export type WrapNumberFunction<T extends number = number> = MapFunction<number,
  *
  * When `fencePosts` is true, wraps to the nearest "fence post" value, extending the wrap range by one in each direction.
  *
+ * @param wrapNumberFunctionConfig - Configuration with min, max, and optional fence post behavior.
+ * @returns Wraps input numbers into the bounded range.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilKind factory
  * @dbxUtilTags number, wrap, modulo, modular, range, factory, circular
  * @dbxUtilRelated bound-number-function, bound-number, is-in-number-bound-function
  *
- * @param wrapNumberFunctionConfig - Configuration with min, max, and optional fence post behavior
- * @returns A function that wraps input numbers into the bounded range
  * @__NO_SIDE_EFFECTS__
  */
 export declare function wrapNumberFunction<T extends number = number>(wrapNumberFunctionConfig: WrapNumberFunctionConfig<T>): WrapNumberFunction<T>;
@@ -73,28 +75,29 @@ export type BoundNumberFunction<T extends number = number> = MapFunction<number,
  *
  * When `wrap` is true, uses modular wrapping. Otherwise, clamps values to the min/max range.
  *
+ * @param boundNumberFunctionConfig - Configuration with min, max, and optional wrap behavior.
+ * @returns Bounds input numbers into the configured range.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilKind factory
  * @dbxUtilTags number, bound, clamp, wrap, range, factory, constrain
  * @dbxUtilRelated bound-number, wrap-number-function, is-in-number-bound-function
  *
- * @param boundNumberFunctionConfig - Configuration with min, max, and optional wrap behavior
- * @returns A function that bounds input numbers into the configured range
  * @__NO_SIDE_EFFECTS__
  */
 export declare function boundNumberFunction<T extends number = number>(boundNumberFunctionConfig: BoundNumberFunctionConfig<T>): BoundNumberFunction<T>;
 /**
  * Clamps the input number between the min and max values (inclusive).
  *
+ * @param input - Number to clamp.
+ * @param min - Minimum allowed value.
+ * @param max - Maximum allowed value.
+ * @returns The clamped value.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, clamp, bound, min, max, range, constrain
  * @dbxUtilRelated bound-number-function, wrap-number-function, is-in-number-bound-function
- *
- * @param input - Number to clamp
- * @param min - Minimum allowed value
- * @param max - Maximum allowed value
- * @returns The clamped value
  */
 export declare function boundNumber<T extends number = number>(input: number, min: T, max: T): T;

package/src/lib/number/dollar.d.ts

@@ -73,8 +73,8 @@ export declare const DOLLAR_AMOUNT_PRECISION = 2;
 /**
  * Checks whether the input string matches the expected dollar amount format (e.g., "12.50" or "$12.50").
  *
- * @param value - String to test
- * @returns `true` if the string matches the dollar amount regex
+ * @param value - String to test.
+ * @returns `true` if the string matches the dollar amount regex.
  */
 export declare function isDollarAmountString(value: string): boolean;
 /**
@@ -82,7 +82,7 @@ export declare function isDollarAmountString(value: string): boolean;
  *
  * Truncates (does not round) excess precision: e.g., 1.115 becomes "1.11". Returns "0.00" for null/undefined.
  *
- * @param number - The dollar amount to format
+ * @param number - The dollar amount to format.
  * @returns Formatted string with two decimal places (e.g., "12.50")
  */
 export declare function dollarAmountString(number: Maybe<number>): string;
@@ -98,14 +98,15 @@ export type DollarAmountStringWithUnitFunction<U extends DollarAmountUnit> = ((a
 /**
  * Creates a function that formats dollar amounts as strings with a unit prefix (e.g., "$12.50").
  *
+ * @param unit - The unit prefix to prepend; defaults to "$".
+ * @returns Formats dollar amounts with the configured unit.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilKind factory
  * @dbxUtilTags number, dollar, currency, format, factory, unit
  * @dbxUtilRelated dollar-amount-string
  *
- * @param unit - The unit prefix to prepend; defaults to "$"
- * @returns A function that formats dollar amounts with the configured unit
  * @__NO_SIDE_EFFECTS__
  */
 export declare function dollarAmountStringWithUnitFunction<U extends DollarAmountUnit>(unit?: U): DollarAmountStringWithUnitFunction<U>;

package/src/lib/number/encoded.d.ts

@@ -64,6 +64,9 @@ export declare const HEX_PATTERN: RegExp;
 /**
  * Checks whether the input string contains only valid hexadecimal characters.
  *
+ * @param value - The string to check.
+ * @returns True if the string is non-empty and contains only hex characters.
+ *
  * @example
  * ```ts
  * isHex('a1b2c3'); // true
@@ -71,9 +74,6 @@ export declare const HEX_PATTERN: RegExp;
  * isHex('hello');  // false
  * isHex('');       // false
  * ```
- *
- * @param value - The string to check.
- * @returns True if the string is non-empty and contains only hex characters.
  */
 export declare function isHex(value: string): value is HexString;
 /**
@@ -92,6 +92,10 @@ export interface IsHexWithByteLengthConfig {
  *
  * Each byte is encoded as 2 hex characters, so a 32-byte value requires a 64-character hex string.
  *
+ * @param value - The string to check.
+ * @param config - Configuration specifying the expected byte length.
+ * @returns True if the string is valid hex with exactly the expected number of bytes.
+ *
  * @example
  * ```ts
  * // Ed25519 public key is 32 bytes (64 hex chars)
@@ -99,9 +103,5 @@ export interface IsHexWithByteLengthConfig {
  * isHexWithByteLength('abc123', { byteLength: 32 });        // false (too short)
  * isHexWithByteLength('placeholder', { byteLength: 32 });   // false (not hex)
  * ```
- *
- * @param value - The string to check.
- * @param config - Configuration specifying the expected byte length.
- * @returns True if the string is valid hex with exactly the expected number of bytes.
  */
 export declare function isHexWithByteLength(value: string, config: IsHexWithByteLengthConfig): value is HexString;

package/src/lib/number/factory.d.ts

@@ -7,17 +7,17 @@ export interface IncrementingNumberFactoryConfig {
     /**
      * Value to start at. Defaults to 0.
      */
-    startAt?: number;
+    readonly startAt?: number;
     /**
      * Getter to increase by. Defaults to 1.
      */
-    increaseBy?: GetterOrValue<number>;
+    readonly increaseBy?: GetterOrValue<number>;
 }
 /**
  * Creates a factory that returns sequentially increasing numbers, starting from a configurable value and incrementing by a configurable step.
  *
  * @param config - Configuration with optional `startAt` (default 0) and `increaseBy` (default 1)
- * @returns A factory function that returns the next number in the sequence on each call
+ * @returns A factory function that returns the next number in the sequence on each call.
  *
  * @dbxUtil
  * @dbxUtilCategory number
@@ -32,6 +32,7 @@ export interface IncrementingNumberFactoryConfig {
  * factory(); // 15
  * factory(); // 20
  * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function incrementingNumberFactory(config?: IncrementingNumberFactoryConfig): NumberFactory;

package/src/lib/number/number.d.ts

@@ -46,13 +46,13 @@ export type PercentDecimal = number;
  *
  * Returns 0 for null/undefined input.
  *
+ * @param input - A percent number value (e.g., 5 means 5%)
+ * @returns The decimal equivalent.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, percent, decimal, convert, ratio
  * @dbxUtilRelated percent-number-from-decimal
- *
- * @param input - A percent number value (e.g., 5 means 5%)
- * @returns The decimal equivalent
  */
 export declare function percentNumberToDecimal(input: Maybe<number>): number;
 /**
@@ -60,13 +60,13 @@ export declare function percentNumberToDecimal(input: Maybe<number>): number;
  *
  * Returns 0 for null/undefined input.
  *
+ * @param input - A decimal percent value (e.g., 0.05 means 5%)
+ * @returns The percent number equivalent.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, percent, decimal, convert, ratio
  * @dbxUtilRelated percent-number-to-decimal
- *
- * @param input - A decimal percent value (e.g., 0.05 means 5%)
- * @returns The percent number equivalent
  */
 export declare function percentNumberFromDecimal(input: Maybe<number>): PercentNumber;
 export type NumberOrNumberString = number | NumberString;
@@ -83,12 +83,12 @@ export type AsNumberInput = Maybe<NumberOrNumberString>;
  *
  * Strings are parsed via `Number()`. Null/undefined returns 0.
  *
+ * @param input - Numeric value, numeric string, or null/undefined.
+ * @returns The numeric value, or 0 for null/undefined.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, parse, convert, coerce, string, normalize
- *
- * @param input - A number, number string, or null/undefined
- * @returns The numeric value, or 0 for null/undefined
  */
 export declare function asNumber(input: AsNumberInput): number;
 /**
@@ -96,14 +96,14 @@ export declare function asNumber(input: AsNumberInput): number;
  *
  * Treats null/undefined as 0.
  *
+ * @param value - The number to check.
+ * @param divisor - The divisor to test against.
+ * @returns `true` if the remainder is zero.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, divisible, modulo, division, math, check
  * @dbxUtilRelated nearest-divisible-values, is-even-number, is-odd-number
- *
- * @param value - The number to check
- * @param divisor - The divisor to test against
- * @returns `true` if the remainder is zero
  */
 export declare function isNumberDivisibleBy(value: Maybe<number>, divisor: number): boolean;
 export interface NearestDivisibleValues {
@@ -115,38 +115,38 @@ export interface NearestDivisibleValues {
 /**
  * Finds the nearest values that are evenly divisible by the divisor, both above (ceil) and below (floor) the input value.
  *
+ * @param value - The value to find divisible neighbors for.
+ * @param divisor - The divisor to align to.
+ * @returns Object with the input value, divisor, and the nearest ceil/floor divisible values.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, divisible, nearest, ceil, floor, round, snap, math
  * @dbxUtilRelated is-number-divisible-by
- *
- * @param value - The value to find divisible neighbors for
- * @param divisor - The divisor to align to
- * @returns Object with the input value, divisor, and the nearest ceil/floor divisible values
  */
 export declare function nearestDivisibleValues(value: number, divisor: number): NearestDivisibleValues;
 /**
  * Checks whether the input is an even number.
  *
+ * @param value - Number to test.
+ * @returns `true` if even.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, even, parity, math, check
  * @dbxUtilRelated is-odd-number, is-number-divisible-by
- *
- * @param value - Number to test
- * @returns `true` if even
  */
 export declare function isEvenNumber(value: number): boolean;
 /**
  * Checks whether the input is an odd number.
  *
+ * @param value - Number to test.
+ * @returns `true` if odd.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, odd, parity, math, check
  * @dbxUtilRelated is-even-number, is-number-divisible-by
- *
- * @param value - Number to test
- * @returns `true` if odd
  */
 export declare function isOddNumber(value: number): boolean;
 /**
@@ -154,46 +154,46 @@ export declare function isOddNumber(value: number): boolean;
  *
  * The `from` value is floored and the `to` value is ceiled before computation.
  *
+ * @param from - The starting value (floored to nearest integer)
+ * @param to - The ending value (ceiled to nearest integer)
+ * @returns Sum of all integers in the range.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, sum, range, integers, math, gauss, total
- *
- * @param from - The starting value (floored to nearest integer)
- * @param to - The ending value (ceiled to nearest integer)
- * @returns Sum of all integers in the range
  */
 export declare function sumOfIntegersBetween(from: number, to: number): number;
 /**
  * A {@link SortCompareFunction} for numbers that sorts in ascending order.
  *
- * @param a - the first number to compare
- * @param b - the second number to compare
- * @returns a negative value if `a` is less than `b`, zero if equal, or a positive value if `a` is greater
+ * @param a - The first number to compare.
+ * @param b - The second number to compare.
+ * @returns A negative value if `a` is less than `b`, zero if equal, or a positive value if `a` is greater.
  */
 export declare const sortCompareNumberFunction: SortCompareFunction<number>;
 /**
  * Finds the minimum and maximum values from an iterable of numbers.
  *
+ * @param values - Iterable of numbers to examine.
+ * @returns Object with `min` and `max` values.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, min, max, range, sort, bounds, extremes
  * @dbxUtilRelated sort-compare-number-function
- *
- * @param values - Iterable of numbers to examine
- * @returns Object with `min` and `max` values
  */
 export declare function minAndMaxNumber(values: Iterable<number>): MinAndMaxFunctionResult<number>;
 /**
  * Computes the logarithm of `y` with base `x`.
  *
+ * @param x - The base of the logarithm.
+ * @param y - The value to compute the logarithm of.
+ * @returns The base-x logarithm of y.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, log, logarithm, math, base
  *
- * @param x - The base of the logarithm
- * @param y - The value to compute the logarithm of
- * @returns The base-x logarithm of y
- *
  * @example
  * ```ts
  * getBaseLog(2, 16); // 4 (2^4 = 16)

package/src/lib/number/random.d.ts

@@ -13,15 +13,15 @@ export interface RandomNumberFactoryConfig {
      *
      * No rounding by default.
      */
-    round?: RoundingInput;
+    readonly round?: RoundingInput;
     /**
      * Minimum number (inclusive)
      */
-    min?: number;
+    readonly min?: number;
     /**
      * Max number (exclusive)
      */
-    max: number;
+    readonly max: number;
 }
 export type RandomNumberFactoryInput = number | RandomNumberFactoryConfig;
 /**
@@ -29,28 +29,29 @@ export type RandomNumberFactoryInput = number | RandomNumberFactoryConfig;
  *
  * Accepts either a simple max number or a full config object with min, max, and rounding options.
  *
+ * @param maxOrArgs - Maximum value (exclusive) or full configuration object.
+ * @param roundingInput - Optional rounding mode override.
+ * @returns A factory function that produces random numbers within the range.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilKind factory
  * @dbxUtilTags number, random, factory, range, min, max, generate
  * @dbxUtilRelated random-number, rounding-function
  *
- * @param maxOrArgs - Maximum value (exclusive) or full configuration object
- * @param roundingInput - Optional rounding mode override
- * @returns A factory function that produces random numbers within the range
  * @__NO_SIDE_EFFECTS__
  */
 export declare function randomNumberFactory(maxOrArgs: RandomNumberFactoryInput, roundingInput?: RoundingInput): RandomNumberFactory;
 /**
  * Generates a single random number using {@link randomNumberFactory}. Convenience function for one-off usage.
  *
+ * @param maxOrArgs - Maximum value (exclusive) or full configuration object.
+ * @param roundingInput - Optional rounding mode.
+ * @returns A single random number.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, random, range, generate
  * @dbxUtilRelated random-number-factory
- *
- * @param maxOrArgs - Maximum value (exclusive) or full configuration object
- * @param roundingInput - Optional rounding mode
- * @returns A single random number
  */
 export declare function randomNumber(maxOrArgs: RandomNumberFactoryInput, roundingInput?: RoundingInput): number;

package/src/lib/number/round.d.ts

@@ -7,14 +7,15 @@ export type RoundingFunction = MapFunction<number, number>;
 /**
  * Returns a rounding function for the specified rounding type.
  *
+ * @param type - The rounding strategy: 'floor', 'ceil', 'round', or 'none'.
+ * @returns The corresponding Math function, or an identity function for 'none'.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilKind factory
  * @dbxUtilTags number, round, floor, ceil, math, factory, rounding
  * @dbxUtilRelated cut-value-to-precision-function, round-to-precision-function
  *
- * @param type - The rounding strategy: 'floor', 'ceil', 'round', or 'none'
- * @returns The corresponding Math function, or an identity function for 'none'
  * @__NO_SIDE_EFFECTS__
  */
 export declare function roundingFunction(type: NumberRounding): RoundingFunction;
@@ -32,14 +33,14 @@ export type NumberPrecision = number;
  *
  * Accepts strings and null/undefined via {@link asNumber}.
  *
+ * @param input - Number, number string, or null/undefined.
+ * @param precision - Number of decimal places to retain.
+ * @returns The truncated number value.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, precision, decimal, truncate, cut, round
  * @dbxUtilRelated cut-value-to-precision-function, cut-value-to-integer, round-to-precision
- *
- * @param input - Number, number string, or null/undefined
- * @param precision - Number of decimal places to retain
- * @returns The truncated number value
  */
 export declare function cutValueToPrecision(input: AsNumberInput, precision: NumberPrecision): number;
 /**
@@ -49,13 +50,13 @@ export declare const CUT_VALUE_TO_ZERO_PRECISION: CutValueToPrecisionFunction;
 /**
  * Truncates a value to an integer by cutting to zero decimal precision.
  *
+ * @param input - Number, number string, or null/undefined.
+ * @returns The truncated integer value.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilTags number, integer, truncate, floor, cut, parse
  * @dbxUtilRelated cut-value-to-precision, as-number
- *
- * @param input - Number, number string, or null/undefined
- * @returns The truncated integer value
  */
 export declare function cutValueToInteger(input: AsNumberInput): number;
 /**
@@ -67,15 +68,16 @@ export type CutValueToPrecisionFunction = ((input: AsNumberInput) => number) & {
 /**
  * Creates a {@link CutValueToPrecisionFunction} that truncates values to the configured precision.
  *
+ * @param precision - Number of decimal places to retain.
+ * @param roundingType - Rounding strategy; defaults to 'cut' (truncation)
+ * @returns Accepts a number or string and returns the truncated number.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilKind factory
  * @dbxUtilTags number, precision, cut, truncate, factory, round
  * @dbxUtilRelated round-to-precision-function, cut-to-precision
  *
- * @param precision - Number of decimal places to retain
- * @param roundingType - Rounding strategy; defaults to 'cut' (truncation)
- * @returns A function that accepts a number or string and returns the truncated number
  * @__NO_SIDE_EFFECTS__
  */
 export declare function cutValueToPrecisionFunction(precision: NumberPrecision, roundingType?: RoundToPrecisionFunctionType): CutValueToPrecisionFunction;
@@ -91,24 +93,25 @@ export type RoundToPrecisionFunctionType = NumberRounding | 'cut';
 /**
  * Creates a function that rounds numbers to the specified precision using a configurable rounding strategy.
  *
+ * @param precision - Number of decimal places.
+ * @param roundFn - Rounding strategy; defaults to 'round'. Use 'cut' for truncation.
+ * @returns Rounds numbers to the configured precision.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilKind factory
  * @dbxUtilTags number, round, precision, factory, decimals
  * @dbxUtilRelated cut-value-to-precision-function, round-to-precision, cut-to-precision
  *
- * @param precision - Number of decimal places
- * @param roundFn - Rounding strategy; defaults to 'round'. Use 'cut' for truncation.
- * @returns A function that rounds numbers to the configured precision
  * @__NO_SIDE_EFFECTS__
  */
 export declare function roundToPrecisionFunction(precision: NumberPrecision, roundFn?: RoundToPrecisionFunctionType): RoundToPrecisionFunction;
 /**
  * Rounds a number to the specified decimal precision using `Math.round`.
  *
- * @param value - Number to round
- * @param precision - Number of decimal places to retain
- * @returns The rounded number
+ * @param value - Number to round.
+ * @param precision - Number of decimal places to retain.
+ * @returns The rounded number.
  */
 export declare function roundToPrecision(value: number, precision: NumberPrecision): number;
 /**
@@ -117,9 +120,9 @@ export declare function roundToPrecision(value: number, precision: NumberPrecisi
  * Uses `Math.floor` for positive numbers and `Math.ceil` for negative numbers to truncate toward zero.
  * For example, 1.25 with precision 1 becomes 1.2 (not 1.3).
  *
- * @param value - Number to truncate
- * @param precision - Number of decimal places to retain
- * @returns The truncated number
+ * @param value - Number to truncate.
+ * @param precision - Number of decimal places to retain.
+ * @returns The truncated number.
  */
 export declare function cutToPrecision(value: number, precision: NumberPrecision): number;
 /**
@@ -139,24 +142,24 @@ export type StepOrigin = number;
 /**
  * Rounds a number up to the nearest multiple of the step size using `Math.ceil`.
  *
- * @param value - Input value
- * @param step - Step size to round up to
- * @returns The nearest multiple of step that is >= value
+ * @param value - Input value.
+ * @param step - Step size to round up to.
+ * @returns The nearest multiple of step that is >= value.
  */
 export declare function roundNumberUpToStep(value: number, step: number): number;
 /**
  * roundNumberToStepFunction()
  */
 export interface RoundNumberToStepFunctionConfig {
-    step: StepNumber;
+    readonly step: StepNumber;
     /**
      * Type of rounding to use.
      */
-    round: Omit<NumberRounding, 'none'>;
+    readonly round: Omit<NumberRounding, 'none'>;
     /**
      * Offset to apply to each input number. Defaults to zero.
      */
-    origin?: StepOrigin;
+    readonly origin?: StepOrigin;
 }
 export type RoundNumberToStepFunctionInput = RoundNumberToStepFunctionConfig | StepNumber;
 /**
@@ -175,15 +178,16 @@ export type RoundNumberToStepFunction = ((input: Maybe<number>) => number) & {
  *
  * Accepts either a step number (uses 'ceil' rounding) or a full config with step, rounding type, and origin.
  *
+ * @param input - Step size or full configuration.
+ * @returns Rounds input numbers to the nearest step.
+ * @throws {Error} If step is 0 or undefined.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilKind factory
  * @dbxUtilTags number, round, step, factory, multiple, origin
  * @dbxUtilRelated round-number-up-to-step, round-to-precision-function
  *
- * @param input - Step size or full configuration
- * @returns A function that rounds input numbers to the nearest step
- * @throws Error if step is 0 or undefined
  * @__NO_SIDE_EFFECTS__
  */
 export declare function roundNumberToStepFunction(input: RoundNumberToStepFunctionInput): RoundNumberToStepFunction;

package/src/lib/number/sort.d.ts

@@ -7,14 +7,15 @@ export type SortByNumberFunction<T> = SortCompareFunction<T>;
 /**
  * Creates a {@link SortCompareFunction} that sorts values in ascending order by a numeric property.
  *
+ * @param readNumberFn - Function that extracts the numeric value from each item.
+ * @returns A sort comparator function for ascending numeric order.
+ *
  * @dbxUtil
  * @dbxUtilCategory number
  * @dbxUtilKind factory
  * @dbxUtilTags number, sort, compare, ascending, factory
  * @dbxUtilRelated sort-numbers-ascending-function, sort-by-string-function
  *
- * @param readNumberFn - Function that extracts the numeric value from each item
- * @returns A sort comparator function for ascending numeric order
  * @__NO_SIDE_EFFECTS__
  */
 export declare function sortByNumberFunction<T>(readNumberFn: ReadNumberFunction<T>): SortByNumberFunction<T>;