@dereekb/util 13.0.7 → 13.2.0

package/src/lib/value/cron.d.ts

@@ -4,13 +4,21 @@ import { type Minutes } from '../date/date';
  */
 export type CronExpression = string;
 /**
- * Creates a CronExpression for the input number of minutes.
+ * Creates a {@link CronExpression} that repeats at approximately every N minutes.
  *
- * Note that if the number of minutes is greater than 60, it will generate an expression that
- * isn't exactly n number of minutes apart from the previous execution, but instead create
- * an expression that is n/60 hours apart and take place on the n%60th minute.
+ * For values under 60, produces a cron expression using minute intervals (e.g., 5 produces every 5th minute).
+ * For values of 60 or more, the expression is split into hours and minutes (e.g., 90 minutes becomes
+ * every 1 hour at minute 30), which means intervals won't be exactly N minutes apart.
  *
- * @param inputMinutes
- * @returns
+ * @param inputMinutes - interval in minutes between executions
+ *
+ * @example
+ * ```ts
+ * // For intervals under 60 minutes:
+ * cronExpressionRepeatingEveryNMinutes(5);  // returns a cron for every 5th minute
+ *
+ * // For intervals of 60+ minutes:
+ * cronExpressionRepeatingEveryNMinutes(90); // returns a cron for every 1 hour at minute 30
+ * ```
  */
 export declare function cronExpressionRepeatingEveryNMinutes(inputMinutes: Minutes): CronExpression;

package/src/lib/value/decision.d.ts

@@ -2,34 +2,78 @@ import { type FactoryWithRequiredInput } from '../getter/getter';
 import { type MapFunction, type AsyncMapFunction } from './map';
 import { type Maybe } from './maybe.type';
 /**
- * A map function that derives a boolean from the input.
+ * A map function that derives a boolean decision from the input value.
  */
 export type DecisionFunction<I> = MapFunction<I, boolean>;
+/**
+ * Async variant of {@link DecisionFunction}.
+ */
 export type AsyncDecisionFunction<I> = AsyncMapFunction<DecisionFunction<I>>;
+/**
+ * Factory that creates a {@link DecisionFunction} from a configuration value.
+ */
 export type DecisionFunctionFactory<C, I> = FactoryWithRequiredInput<DecisionFunction<I>, C>;
+/**
+ * Creates a {@link DecisionFunction} that always returns the given boolean, regardless of input.
+ *
+ * Useful for providing a constant decision where a function is expected.
+ *
+ * @param decision - the constant boolean value to return
+ *
+ * @example
+ * ```ts
+ * const alwaysTrue = decisionFunction(true);
+ * alwaysTrue('anything'); // true
+ * ```
+ */
 export declare function decisionFunction<I>(decision: boolean): DecisionFunction<I>;
 /**
- * Used to invert a decision function by returning the opposite of what it returns.
+ * Inverts a decision function so it returns the opposite boolean value.
+ *
+ * When `invert` is false or omitted, the original function is returned unchanged.
  *
- * @param filterFn
- * @param invert whether or not to apply the inversion.
- * @returns
+ * @param fn - the decision function to potentially invert
+ * @param invert - whether to apply the inversion
+ *
+ * @example
+ * ```ts
+ * const isPositive: DecisionFunction<number> = (x) => x > 0;
+ * const isNotPositive = invertDecision(isPositive, true);
+ * isNotPositive(5); // false
+ * ```
  */
 export declare const invertDecision: <F extends DecisionFunction<any>>(fn: F, invert?: boolean) => F;
 /**
- * Creates a DecisionFunction from the input.
+ * Normalizes a boolean value, a {@link DecisionFunction}, or undefined into a consistent {@link DecisionFunction}.
+ *
+ * If the input is undefined, falls back to a constant function returning `defaultIfUndefined`.
  *
- * @param valueOrFunction
- * @param defaultIfUndefined
- * @returns
+ * @param valueOrFunction - a boolean, decision function, or undefined
+ * @param defaultIfUndefined - fallback boolean when the input is nullish (defaults to true)
+ *
+ * @example
+ * ```ts
+ * const fn = asDecisionFunction(true);
+ * fn('anything'); // true
+ *
+ * const fn2 = asDecisionFunction(undefined, false);
+ * fn2('anything'); // false
+ * ```
  */
 export declare function asDecisionFunction<T = unknown>(valueOrFunction: Maybe<boolean | DecisionFunction<T>>, defaultIfUndefined?: boolean): DecisionFunction<T>;
 /**
- * Creates a DecisionFunction from the input. If the input is not a function then that value is returned.
+ * Creates a {@link DecisionFunction} that checks strict equality against the given value.
+ *
+ * If the input is already a function, it is returned as-is, allowing callers to pass either a
+ * concrete value or a custom decision function interchangeably.
  *
- * If the input is
+ * @param equalityValue - the value to compare against, or an existing decision function
  *
- * @param equalityValue
- * @returns
+ * @example
+ * ```ts
+ * const isThree = isEqualToValueDecisionFunction(3);
+ * isThree(3); // true
+ * isThree(4); // false
+ * ```
  */
 export declare function isEqualToValueDecisionFunction<T>(equalityValue: T | DecisionFunction<T>): T extends DecisionFunction<T> ? T : DecisionFunction<T>;

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

@@ -11,28 +11,59 @@ export type IsEqualContext<T = unknown> = (x: T) => boolean;
  */
 export type AreEqualContext<T = unknown> = (x: IterableOrValue<T>) => boolean;
 /**
- * Creates an IsEqualContext
+ * Creates an {@link IsEqualContext} that captures a reference value and uses the provided comparator
+ * to check whether subsequent values are equal to it.
  *
- * @param contextValue
- * @param fn
- * @returns
+ * @param contextValue - the reference value to compare against
+ * @param fn - the equality comparator
+ *
+ * @example
+ * ```ts
+ * const isEqual = (a: number, b: number) => a === b;
+ * const context = isEqualContext(0, isEqual);
+ *
+ * context(0);  // true
+ * context(10); // false
+ * ```
  */
 export declare function isEqualContext<T>(contextValue: T, fn: EqualityComparatorFunction<T>): IsEqualContext<T>;
 /**
- * Creates an AreEqualContext
+ * Creates an {@link AreEqualContext} that checks whether a single value or all values in an iterable
+ * are equal to the captured reference value.
+ *
+ * Returns `true` only if every value in the input matches the context value according to the comparator.
+ *
+ * @param contextValue - the reference value to compare against
+ * @param fn - the equality comparator
  *
- * @param contextValue
- * @param fn
- * @returns
+ * @example
+ * ```ts
+ * const isEqual = (a: number, b: number) => a === b;
+ * const context = areEqualContext(0, isEqual);
+ *
+ * context([0, 0, 0]); // true
+ * context([0, 1, 2]); // false
+ * ```
  */
 export declare function areEqualContext<T>(contextValue: T, fn: EqualityComparatorFunction<T>): AreEqualContext<T>;
 /**
- * Returns true if all input values are equal.
+ * Returns `true` if all values in the input are equal according to the provided comparator.
+ *
+ * Empty iterables and single-value inputs return `true` by default, since there is nothing to contradict equality.
+ * Uses the first value as the reference and checks all remaining values against it.
+ *
+ * @param values - the values to compare
+ * @param fn - the equality comparator
+ *
+ * @example
+ * ```ts
+ * const isEqual = (a: unknown, b: unknown) => a === b;
  *
- * Arrays that are empty or have one value will return true by default.
+ * allObjectsAreEqual([undefined, undefined, undefined], isEqual);
+ * // true
  *
- * @param values
- * @param fn
- * @returns
+ * allObjectsAreEqual([undefined, 'test', undefined], isEqual);
+ * // false
+ * ```
  */
 export declare function allObjectsAreEqual<T>(values: IterableOrValue<T>, fn: EqualityComparatorFunction<T>): boolean;