@dereekb/util 13.11.13 → 13.11.15

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

@@ -2,13 +2,13 @@ import { type Maybe, type MaybeNot, type MaybeSo } from './maybe.type';
 /**
  * Type guard that returns `true` if the value is not `null` or `undefined`.
  *
+ * @param value - The value to check.
+ * @returns `true` if the value is not `null` or `undefined`
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilTags maybe, nullish, type-guard, defined, not-null, value
  * @dbxUtilRelated is-maybe-so, is-maybe-not, has-value-or-not-empty
- *
- * @param value - the value to check
- * @returns `true` if the value is not `null` or `undefined`
  */
 export declare function hasNonNullValue<T = unknown>(value: Maybe<T>): value is MaybeSo<T>;
 /**
@@ -20,13 +20,13 @@ export declare function hasNonNullValue<T = unknown>(value: Maybe<T>): value is
  *
  * NaN has undefined behavior.
  *
+ * @param value - The value to check.
+ * @returns `true` if the value is non-nullish and not empty.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilTags maybe, empty, type-guard, non-empty, value, has-value
  * @dbxUtilRelated has-value-or-not-empty-object, has-non-null-value, is-not-null-or-empty-string
- *
- * @param value - the value to check
- * @returns `true` if the value is non-nullish and not empty
  */
 export declare function hasValueOrNotEmpty<T = unknown>(value: Maybe<T>): value is MaybeSo<T>;
 /**
@@ -37,19 +37,19 @@ export declare function hasValueOrNotEmpty<T = unknown>(value: Maybe<T>): value
  *
  * NaN has undefined behavior.
  *
+ * @param value - The value to check.
+ * @returns `true` if the value is non-nullish, non-empty, and not an empty object.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilTags maybe, empty, type-guard, object, non-empty, strict
  * @dbxUtilRelated has-value-or-not-empty, has-non-null-value, object-has-no-keys
- *
- * @param value - the value to check
- * @returns `true` if the value is non-nullish, non-empty, and not an empty object
  */
 export declare function hasValueOrNotEmptyObject<T = unknown>(value: Maybe<T>): value is MaybeSo<T>;
 /**
  * Returns `true` if the input value is a non-empty string or is `true`.
  *
- * @param value - the value to check
+ * @param value - The value to check.
  * @returns `true` if the value is a non-empty string or is `true`
  */
 export declare function isStringOrTrue(value: Maybe<string | boolean>): boolean;
@@ -58,25 +58,25 @@ export declare function isStringOrTrue(value: Maybe<string | boolean>): boolean;
  *
  * Useful for filtering out both nullish values and empty strings in a single check.
  *
+ * @param value - The value to check.
+ * @returns `true` if the value is not nullish and not an empty string.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilTags maybe, string, empty, type-guard, nullish, non-empty
  * @dbxUtilRelated has-value-or-not-empty, has-non-null-value
- *
- * @param value - the value to check
- * @returns `true` if the value is not nullish and not an empty string
  */
 export declare function isNotNullOrEmptyString<T>(value: Maybe<MaybeNot | '' | T>): value is MaybeSo<T>;
 /**
  * Type guard that returns `true` if the input is `null` or `undefined`.
  *
+ * @param value - The value to check.
+ * @returns `true` if the value is `null` or `undefined`
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilTags maybe, nullish, type-guard, null, undefined, missing
  * @dbxUtilRelated is-maybe-so, has-non-null-value
- *
- * @param value - the value to check
- * @returns `true` if the value is `null` or `undefined`
  */
 export declare function isMaybeNot<T = unknown>(value: Maybe<T>): value is MaybeNot;
 /**
@@ -84,13 +84,13 @@ export declare function isMaybeNot<T = unknown>(value: Maybe<T>): value is Maybe
  *
  * Equivalent to {@link hasNonNullValue} but with the `MaybeSo` narrowing type.
  *
+ * @param value - The value to check.
+ * @returns `true` if the value is neither `null` nor `undefined`
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilTags maybe, nullish, type-guard, defined, present, non-null
  * @dbxUtilRelated is-maybe-not, has-non-null-value
- *
- * @param value - the value to check
- * @returns `true` if the value is neither `null` nor `undefined`
  */
 export declare function isMaybeSo<T>(value: Maybe<T>): value is MaybeSo<T>;
 /**
@@ -98,40 +98,40 @@ export declare function isMaybeSo<T>(value: Maybe<T>): value is MaybeSo<T>;
  *
  * Useful for optional boolean flags where both absence and `true` indicate the same behavior.
  *
- * @param value - the value to check
+ * @param value - The value to check.
  * @returns `true` if the value is nullish or strictly `true`
  */
 export declare function isMaybeNotOrTrue<T = unknown>(value: Maybe<T | true>): value is MaybeNot | true;
 /**
  * Returns `true` if the input is not `null`, `undefined`, or `false`.
  *
+ * @param value - The value to check.
+ * @returns `true` if the value is not `null`, `undefined`, or `false`
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilTags maybe, boolean, defined, truthy, type-guard
  * @dbxUtilRelated is-not-false, has-non-null-value
- *
- * @param value - the value to check
- * @returns `true` if the value is not `null`, `undefined`, or `false`
  */
 export declare function isDefinedAndNotFalse<T = unknown>(value: Maybe<T>): boolean;
 /**
  * Returns `true` if the input is not strictly `false`. Nullish values return `true`.
  *
- * @param value - the value to check
+ * @param value - The value to check.
  * @returns `true` if the value is not strictly `false`
  */
 export declare function isNotFalse<T = unknown>(value: Maybe<T>): boolean;
 /**
  * Returns `true` if both inputs are non-nullish and strictly equal (`===`).
  *
+ * @param a - First value.
+ * @param b - Second value.
+ * @returns `true` if both values are non-nullish and strictly equal.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilTags maybe, equal, equality, compare, non-null
  * @dbxUtilRelated values-are-both-nullish-or-equivalent, has-non-null-value
- *
- * @param a - first value
- * @param b - second value
- * @returns `true` if both values are non-nullish and strictly equal
  */
 export declare function isSameNonNullValue<T>(a: Maybe<T>, b: Maybe<T>): a is NonNullable<T>;
 /**
@@ -139,14 +139,14 @@ export declare function isSameNonNullValue<T>(a: Maybe<T>, b: Maybe<T>): a is No
  *
  * This means `null` and `undefined` are considered equivalent to each other, but `false` and `null` are not.
  *
+ * @param a - First value.
+ * @param b - Second value.
+ * @returns `true` if both are nullish or both are the same value.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilTags maybe, equal, equality, nullish, compare
  * @dbxUtilRelated is-same-non-null-value
- *
- * @param a - first value
- * @param b - second value
- * @returns `true` if both are nullish or both are the same value
  */
 export declare function valuesAreBothNullishOrEquivalent<T>(a: Maybe<T>, b: Maybe<T>): boolean;
 /**
@@ -156,12 +156,12 @@ export declare function valuesAreBothNullishOrEquivalent<T>(a: Maybe<T>, b: Mayb
  * - If `b` is `null`, returns `null` (explicit clear).
  * - If `b` is defined, returns `b` (new value).
  *
+ * @param a - The current value.
+ * @param b - The update value.
+ * @returns `a` if `b` is undefined, otherwise `b`
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilTags maybe, update, merge, sentinel, patch, optional
- *
- * @param a - the current value
- * @param b - the update value
- * @returns `a` if `b` is undefined, otherwise `b`
  */
 export declare function updateMaybeValue<T>(a: Maybe<T>, b: Maybe<T>): Maybe<T>;

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

@@ -32,9 +32,9 @@ export interface Modifier<T> extends ModifierFunctionRef<T> {
 /**
  * Creates a {@link Modifier} with the given key and modify function.
  *
- * @param key - unique identifier for the modifier
- * @param modify - function that mutates the target value
- * @returns a new {@link Modifier} pairing the key with the modify function
+ * @param key - Unique identifier for the modifier.
+ * @param modify - Function that mutates the target value.
+ * @returns A new {@link Modifier} pairing the key with the modify function.
  *
  * @dbxUtil
  * @dbxUtilCategory value
@@ -53,7 +53,7 @@ export declare function modifier<T>(key: string, modify: ModifierFunction<T>): M
 /**
  * A no-operation modifier that does nothing to the input. Useful as a default/fallback.
  *
- * @returns undefined (no mutation is performed)
+ * @returns Undefined (no mutation is performed)
  */
 export declare const NOOP_MODIFIER: ModifierFunction<any>;
 /**
@@ -65,9 +65,9 @@ export type ModifierMap<T> = Map<ModifierKey, Modifier<T>>;
  *
  * If a modifier with the same key already exists, it is replaced.
  *
- * @param modifiers - modifier(s) to add
- * @param map - existing map to add to, or undefined to create a new one
- * @returns the modifier map with the new modifiers added
+ * @param modifiers - Modifier(s) to add.
+ * @param map - Existing map to add to, or undefined to create a new one.
+ * @returns The modifier map with the new modifiers added.
  *
  * @example
  * ```ts
@@ -80,9 +80,9 @@ export declare function addModifiers<T>(modifiers: ArrayOrValue<Modifier<T>>, ma
 /**
  * Removes one or more modifiers from the map by key. Returns an empty map if no map is provided.
  *
- * @param modifiers - modifier(s) whose keys should be removed
- * @param map - the map to remove from
- * @returns the modifier map with the specified modifiers removed
+ * @param modifiers - Modifier(s) whose keys should be removed.
+ * @param map - The map to remove from.
+ * @returns The modifier map with the specified modifiers removed.
  *
  * @example
  * ```ts
@@ -98,8 +98,13 @@ export declare function removeModifiers<T>(modifiers: ArrayOrValue<Modifier<T>>,
  *
  * Returns {@link NOOP_MODIFIER} if the map is nullish or empty.
  *
- * @param map - the modifier map to convert
- * @returns a single modifier function that applies all mapped modifiers, or {@link NOOP_MODIFIER} if empty
+ * @param map - The modifier map to convert.
+ * @returns A single modifier function that applies all mapped modifiers, or {@link NOOP_MODIFIER} if empty.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilTags modifier, map, factory, compose
+ * @dbxUtilRelated maybe-modifier-map-to-function, modifier
  *
  * @example
  * ```ts
@@ -111,11 +116,6 @@ export declare function removeModifiers<T>(modifiers: ArrayOrValue<Modifier<T>>,
  * // obj.x === 1
  * ```
  *
- * @dbxUtil
- * @dbxUtilCategory value
- * @dbxUtilTags modifier, map, factory, compose
- * @dbxUtilRelated maybe-modifier-map-to-function, modifier
- *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function modifierMapToFunction<T>(map: Maybe<ModifierMap<T>>): ModifierFunction<T>;
@@ -124,13 +124,14 @@ export declare function modifierMapToFunction<T>(map: Maybe<ModifierMap<T>>): Mo
  *
  * Returns undefined if no map is provided, allowing callers to distinguish "no modifiers" from "empty modifiers".
  *
+ * @param map - The modifier map to convert.
+ * @returns A composed modifier function, or `undefined` if no map is provided.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilTags modifier, map, factory, compose, optional
  * @dbxUtilRelated modifier-map-to-function, modifier
  *
- * @param map - the modifier map to convert
- * @returns a composed modifier function, or `undefined` if no map is provided
  * @__NO_SIDE_EFFECTS__
  */
 export declare function maybeModifierMapToFunction<T>(map: Maybe<ModifierMap<T>>): Maybe<ModifierFunction<T>>;
@@ -139,8 +140,8 @@ export declare function maybeModifierMapToFunction<T>(map: Maybe<ModifierMap<T>>
  *
  * Returns {@link NOOP_MODIFIER} if the array is empty or nullish.
  *
- * @param modifiers - array of modifier functions to merge
- * @returns a single modifier function that applies all provided modifiers, or {@link NOOP_MODIFIER} if empty
+ * @param modifiers - Array of modifier functions to merge.
+ * @returns A single modifier function that applies all provided modifiers, or {@link NOOP_MODIFIER} if empty.
  *
  * @example
  * ```ts
@@ -158,7 +159,7 @@ export declare function mergeModifiers<T>(modifiers: ModifierFunction<T>[]): Mod
  *
  * If only one modifier is provided, returns it directly without wrapping.
  *
- * @param modifiers - array of modifier functions to merge, or undefined
- * @returns a composed modifier function, the single modifier if only one provided, or `undefined` if input is nullish
+ * @param modifiers - Array of modifier functions to merge, or undefined.
+ * @returns A composed modifier function, the single modifier if only one provided, or `undefined` if input is nullish.
  */
 export declare function maybeMergeModifiers<T>(modifiers: Maybe<ModifierFunction<T>[]>): Maybe<ModifierFunction<T>>;