@dereekb/util 13.10.8 → 13.11.0

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

@@ -20,6 +20,12 @@ export type IsInNumberBoundFunction = (number: number) => boolean;
 /**
  * Creates a function that checks whether a number falls within the specified inclusive bounds.
  *
+ * @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)
@@ -41,6 +47,12 @@ 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.
  *
+ * @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
  */
@@ -59,6 +71,12 @@ export type BoundNumberFunction<T extends number = number> = MapFunction<number,
  *
  * When `wrap` is true, uses modular wrapping. Otherwise, clamps values to the min/max 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
  */
@@ -66,6 +84,11 @@ export declare function boundNumberFunction<T extends number = number>(boundNumb
 /**
  * Clamps the input number between the min and max values (inclusive).
  *
+ * @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

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

@@ -46,6 +46,11 @@ export type PercentDecimal = number;
  *
  * Returns 0 for null/undefined input.
  *
+ * @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
  */
@@ -55,6 +60,11 @@ export declare function percentNumberToDecimal(input: Maybe<number>): number;
  *
  * Returns 0 for null/undefined input.
  *
+ * @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
  */
@@ -73,6 +83,10 @@ export type AsNumberInput = Maybe<NumberOrNumberString>;
  *
  * Strings are parsed via `Number()`. Null/undefined returns 0.
  *
+ * @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
  */
@@ -82,6 +96,11 @@ export declare function asNumber(input: AsNumberInput): number;
  *
  * Treats null/undefined as 0.
  *
+ * @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
@@ -96,6 +115,11 @@ export interface NearestDivisibleValues {
 /**
  * Finds the nearest values that are evenly divisible by the divisor, both above (ceil) and below (floor) the input value.
  *
+ * @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
@@ -104,6 +128,11 @@ export declare function nearestDivisibleValues(value: number, divisor: number):
 /**
  * Checks whether the input is an even number.
  *
+ * @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
  */
@@ -111,6 +140,11 @@ export declare function isEvenNumber(value: number): boolean;
 /**
  * Checks whether the input is an odd number.
  *
+ * @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
  */
@@ -120,6 +154,10 @@ export declare function isOddNumber(value: number): boolean;
  *
  * The `from` value is floored and the `to` value is ceiled before computation.
  *
+ * @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
@@ -136,6 +174,11 @@ export declare const sortCompareNumberFunction: SortCompareFunction<number>;
 /**
  * Finds the minimum and maximum values from an iterable of numbers.
  *
+ * @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
  */
@@ -143,6 +186,10 @@ export declare function minAndMaxNumber(values: Iterable<number>): MinAndMaxFunc
 /**
  * Computes the logarithm of `y` with base `x`.
  *
+ * @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

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

@@ -29,6 +29,12 @@ export type RandomNumberFactoryInput = number | RandomNumberFactoryConfig;
  *
  * Accepts either a simple max number or a full config object with min, max, and rounding options.
  *
+ * @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
@@ -37,6 +43,11 @@ export declare function randomNumberFactory(maxOrArgs: RandomNumberFactoryInput,
 /**
  * Generates a single random number using {@link randomNumberFactory}. Convenience function for one-off usage.
  *
+ * @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

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

@@ -7,6 +7,12 @@ export type RoundingFunction = MapFunction<number, number>;
 /**
  * Returns a rounding function for the specified rounding type.
  *
+ * @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'
  */
@@ -25,6 +31,11 @@ export type NumberPrecision = number;
  *
  * Accepts strings and null/undefined via {@link asNumber}.
  *
+ * @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
@@ -37,6 +48,11 @@ export declare const CUT_VALUE_TO_ZERO_PRECISION: CutValueToPrecisionFunction;
 /**
  * Truncates a value to an integer by cutting to zero decimal precision.
  *
+ * @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
  */

package/src/lib/object/object.d.ts

@@ -24,6 +24,11 @@ export type EmptyObject = Record<string, never>;
 /**
  * Checks whether the object has no own enumerable keys.
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilTags object, empty, keys, check, type-guard
+ * @dbxUtilRelated object-has-key, object-has-keys, has-value-or-not-empty-object
+ *
  * @param obj - Object to check
  * @returns `true` if the object has zero keys
  */
@@ -31,6 +36,11 @@ export declare function objectHasNoKeys(obj: object): obj is EmptyObject;
 /**
  * Checks whether the object has the specified own property using `Object.prototype.hasOwnProperty`.
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilTags object, key, has, own-property, check
+ * @dbxUtilRelated object-has-keys, object-has-no-keys
+ *
  * @param obj - Object to check
  * @param key - Property key to test for
  * @returns `true` if the object has the key as an own property
@@ -41,6 +51,11 @@ export declare function objectHasKey<T, K extends keyof T>(obj: T, key: K): bool
 /**
  * Checks whether the object has all or any of the specified keys, based on the mode.
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilTags object, keys, has, check, all, any
+ * @dbxUtilRelated object-has-key, object-has-no-keys
+ *
  * @param obj - Object to check
  * @param keys - Keys to test for
  * @param mode - Whether to require 'all' keys or just 'any'; defaults to 'all'
@@ -62,6 +77,10 @@ export declare function applyToMultipleFields<T extends object, X = unknown>(val
 /**
  * Converts a Map to a plain object by iterating entries and assigning key-value pairs.
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilTags object, map, convert, transform, dictionary
+ *
  * @param map - Map to convert
  * @returns A plain object with the same key-value pairs
  */
@@ -75,6 +94,11 @@ export type CopyObjectFunction<T> = (input: T) => T;
 /**
  * Creates a shallow copy of an object using the spread operator.
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilTags object, copy, clone, shallow, spread
+ * @dbxUtilRelated copy-array
+ *
  * @param input - Object to copy
  * @returns A new object with the same properties
  */

package/src/lib/object/object.empty.d.ts

@@ -3,6 +3,11 @@ import { type Maybe } from '../value/maybe.type';
  * Recursively checks whether an object is "empty" — meaning it is null/undefined, has no keys,
  * or all of its values are themselves empty (recursively for nested objects, or falsy for primitives).
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilTags object, empty, recursive, deep, check, has-value
+ * @dbxUtilRelated object-has-no-keys, has-value-or-not-empty-object
+ *
  * @param obj - Object to check
  * @returns `true` if the object is considered empty
  */

package/src/lib/object/object.equal.d.ts

@@ -6,6 +6,11 @@ import { type FilterFromPOJOFunction } from './object.filter.pojo';
  *
  * Recursively compares arrays, objects, Maps, Sets, primitives, and Dates.
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilTags object, equal, equality, deep, compare, recursive, pojo
+ * @dbxUtilRelated are-equal-pojo-values-using-pojo-filter, all-objects-are-equal
+ *
  * @param a - First value to compare
  * @param b - Second value to compare
  * @returns `true` if the values are deeply equal

package/src/lib/object/object.filter.pojo.d.ts

@@ -6,10 +6,40 @@ import { type FilterKeyValueTuplesInput, type KeyValueTuple, type KeyValueTupleF
  */
 export type StripObjectFunction<T extends object> = (input: Maybe<T>, copy?: Maybe<boolean>) => T | undefined;
 /**
+ * Creates a reusable {@link StripObjectFunction} that filters values from an object and returns
+ * `undefined` when no keys remain after filtering.
  *
- * @param input
+ * Useful when an upstream consumer treats an "empty" object as a missing value (e.g. for skipping
+ * persistence or omitting a field from a request body).
+ *
+ * @param filter - Filter controlling which key/value pairs are removed from the input object.
+ * @param copy - When true (default), the returned function shallow-copies the input before filtering instead of mutating it.
+ * @returns A function that returns the stripped object, or `undefined` when filtering removed every key.
+ *
+ * @example
+ * ```ts
+ * const stripUndef = stripObjectFunction(KeyValueTypleValueFilter.UNDEFINED);
+ * stripUndef({ a: 1, b: undefined });  // { a: 1 }
+ * stripUndef({ a: undefined });        // undefined
+ * ```
  */
 export declare function stripObjectFunction<T extends object>(filter: FilterKeyValueTuplesInput<T>, copy?: boolean): StripObjectFunction<T>;
+/**
+ * Removes `undefined` values from the input object and returns `undefined` when no keys remain.
+ *
+ * Convenience wrapper around {@link stripObjectFunction} pre-configured to filter out `undefined`.
+ *
+ * @param input - The object to strip; null/undefined inputs short-circuit and return `undefined`.
+ * @param copy - When true (default), shallow-copies the input before filtering instead of mutating it.
+ * @returns The stripped object, or `undefined` when input was missing or filtering removed every key.
+ *
+ * @example
+ * ```ts
+ * stripObject({ a: 1, b: undefined }); // { a: 1 }
+ * stripObject({ a: undefined });       // undefined
+ * stripObject(null);                   // undefined
+ * ```
+ */
 export declare function stripObject<T extends object>(input: Maybe<T>, copy?: boolean): T | undefined;
 /**
  * Assigns all non-filtered values from one or more source objects into the target object.

package/src/lib/object/object.flatten.d.ts

@@ -24,6 +24,10 @@ export interface FlattenObjectConfig {
  * Empty nested objects are omitted from the result (they produce no keys).
  * Circular references are detected and treated as leaf values to avoid infinite recursion.
  *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilTags object, flatten, flat, nested, dot-notation, deep, traverse
+ *
  * @example
  * ```ts
  * flattenObject({ a: 1, b: { c: 2, d: { e: 3 } } });