@dereekb/util 13.0.7 → 13.2.0

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

@@ -1,67 +1,116 @@
 import { type Maybe } from './maybe.type';
 /**
- * City name
+ * City name string (e.g. "San Antonio").
  */
 export type CityString = string;
 /**
- * Full state name
+ * Full state name string (e.g. "Texas").
  */
 export type StateString = string;
 /**
- * State code
+ * Two-letter US state code (e.g. "TX").
  */
 export type StateCodeString = string;
 /**
- * Full country name
+ * Full country name string (e.g. "United States").
  */
 export type CountryString = string;
 /**
- * Country code
+ * Country code string (e.g. "US").
  */
 export type CountryCodeString = string;
+/**
+ * A single line in a street address.
+ */
 export type AddressLineString = string;
+/**
+ * Postal/zip code string.
+ */
 export type ZipCodeString = string;
 /**
- * Basic US Address that has 2 lines, a city, state, and zip code.
+ * Basic US address with two address lines, city, state, and zip code.
  */
 export interface UnitedStatesAddress {
+    /** Primary street address line. */
     line1: AddressLineString;
+    /** Secondary address line (apartment, suite, etc.). */
     line2?: AddressLineString;
+    /** City name. */
     city: CityString;
+    /** State name or two-letter state code. */
     state: StateString | StateCodeString;
+    /** Postal/zip code. */
     zip: ZipCodeString;
 }
 /**
- * UnitedStatesAddress with an additional name field for display.
+ * Extends {@link UnitedStatesAddress} with optional contact information for display purposes,
+ * such as a recipient name and phone number.
  */
 export interface UnitedStatesAddressWithContact extends UnitedStatesAddress {
+    /** Contact name associated with this address. */
     name?: string;
+    /** Phone number associated with this address. */
     phone?: string;
 }
 /**
- * Creates a string from a UnitedStatesAddress. Linebreaks are added by default.
+ * Formats a {@link UnitedStatesAddress} or {@link UnitedStatesAddressWithContact} into a human-readable multi-line string.
  *
- * @param input
- * @returns
+ * Empty or undefined fields are omitted. If the input includes contact fields (name, phone), they appear at the top.
+ * Returns `undefined` if no meaningful parts are present.
+ *
+ * @param input - the address to format
+ * @param addLinebreaks - whether to join parts with newlines (default `true`) or concatenate them directly
  */
 export declare function unitedStatesAddressString(input: Maybe<Partial<UnitedStatesAddress | UnitedStatesAddressWithContact>>, addLinebreaks?: boolean): Maybe<string>;
 /**
- * Returns true if the input address is completely configured and not missing any info.
+ * Checks whether the input address has all required fields populated (line1, city, state, zip).
+ *
+ * Useful for validating an address before submission or display.
+ *
+ * @param input - the address to validate
+ *
+ * @example
+ * ```ts
+ * const address: UnitedStatesAddress = {
+ *   line1: 'hello world',
+ *   city: 'San Antonio',
+ *   state: 'TX',
+ *   zip: '78216'
+ * };
  *
- * @param input
- * @returns
+ * isCompleteUnitedStatesAddress(address);
+ * // true
+ * ```
  */
 export declare function isCompleteUnitedStatesAddress(input: Maybe<UnitedStatesAddress>): boolean;
 /**
- * Regex expression for all US states and territories.
+ * Regex that matches valid two-letter US state and territory codes (uppercase only).
+ *
+ * Includes all 50 states plus DC, PR, GU, AS, MP, VI, FM, MH, and PW.
  */
 export declare const US_STATE_CODE_STRING_REGEX: RegExp;
+/**
+ * Tests whether the input string is a valid two-letter US state or territory code.
+ *
+ * Only matches uppercase codes; lowercase input returns `false`.
+ *
+ * @param input - the string to test
+ *
+ * @example
+ * ```ts
+ * isUsStateCodeString('TX');
+ * // true
+ *
+ * isUsStateCodeString('XX');
+ * // false
+ * ```
+ */
 export declare function isUsStateCodeString(input: string): boolean;
 /**
- * Simple regex expression for zip codes.
+ * Simple regex for validating postal/zip codes.
  *
- * Credit to:
+ * Matches alphanumeric codes between 2 and 12 characters, allowing hyphens and spaces in the middle.
  *
- * https://stackoverflow.com/a/19844362
+ * Credit: https://stackoverflow.com/a/19844362
  */
 export declare const ZIP_CODE_STRING_REGEX: RegExp;

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

@@ -3,70 +3,204 @@ import { type Rectangle } from './vector';
 import { type LatLngPoint, type LatLngPointInput, type LatLngPrecision, type LatLngPointFunction } from './point';
 import { type DecisionFunction } from './decision';
 import { type ArrayOrValue } from '../array';
+/**
+ * Alias for the south-west corner point of a {@link LatLngBound}.
+ */
 export type LatLngBoundSouthWestPoint = LatLngPoint;
+/**
+ * Alias for the north-east corner point of a {@link LatLngBound}.
+ */
 export type LatLngBoundNothEastPoint = LatLngPoint;
+/**
+ * A geographic bounding box defined by its south-west and north-east corner points.
+ *
+ * Used throughout the library for spatial queries, overlap detection, and map viewport calculations.
+ */
 export interface LatLngBound {
     sw: LatLngBoundSouthWestPoint;
     ne: LatLngBoundNothEastPoint;
 }
+/**
+ * A value that is either a {@link LatLngBound} or a {@link LatLngPoint}.
+ */
 export type LatLngBoundOrPoint = LatLngBound | LatLngPoint;
+/**
+ * Type guard that checks whether the input is a {@link LatLngBound} by testing for the presence of `sw` and `ne` properties.
+ */
 export declare function isLatLngBound(input: LatLngBound | unknown): input is LatLngBound;
+/**
+ * Creates a deep copy of the bound so that mutations to the copy do not affect the original.
+ *
+ * @param input - bound to copy
+ * @returns a new bound with copied corner points
+ */
 export declare function copyLatLngBound(input: LatLngBound): LatLngBound;
+/**
+ * Checks whether two bounds are identical by comparing both corner points.
+ *
+ * @param a - first bound
+ * @param b - second bound
+ * @returns `true` if both the `sw` and `ne` corners are the same
+ */
 export declare function isSameLatLngBound(a: LatLngBound, b: LatLngBound): boolean;
+/**
+ * Computes the difference between the `ne` and `sw` corner points of a bound, giving the span in latitude and longitude.
+ *
+ * @param bounds - bound to measure
+ * @param wrap - whether to wrap the difference across the antimeridian
+ * @returns a point whose `lat`/`lng` represent the span of the bound
+ */
 export declare function diffLatLngBoundPoints(bounds: LatLngBound, wrap?: boolean): LatLngPoint;
 /**
  * Returns true if the input LatLngBound either strictly wraps the map or fully wraps the map.
  *
- * @param bound
- * @returns
+ * A bound "wraps" when it crosses the antimeridian (longitude +/-180), requiring special handling
+ * for containment and overlap checks.
+ *
+ * @param bound - bound to check
+ * @returns `true` if the bound wraps the map in either sense
  */
 export declare function latLngBoundWrapsMap(bound: LatLngBound): boolean;
 /**
- * Returns true if the input LatLngBound's sw corner comes after the ne corner.
+ * Returns true if the input LatLngBound's sw corner comes after the ne corner longitudinally,
+ * indicating the bound crosses the antimeridian.
  *
- * @param bound
- * @returns
+ * @param bound - bound to check
+ * @returns `true` if the sw longitude is greater than the ne longitude
  */
 export declare function latLngBoundStrictlyWrapsMap(bound: LatLngBound): boolean;
 /**
- * Returns true if the LatLngBound's sw and ne longitudes's total distance is greater than the
- * @param bound
- * @returns
+ * Returns true if the LatLngBound's longitudinal span exceeds the total longitude range (360 degrees),
+ * meaning the bound covers the entire map horizontally.
+ *
+ * @param bound - bound to check
+ * @returns `true` if the absolute longitude difference exceeds the total longitude range
  */
 export declare function latLngBoundFullyWrapsMap(bound: LatLngBound): boolean;
+/**
+ * Returns the north-east corner point of the bound.
+ *
+ * @param bound - bound to read
+ * @returns the `ne` corner point
+ */
 export declare function latLngBoundNorthEastPoint(bound: LatLngBound): LatLngPoint;
+/**
+ * Derives the north-west corner point from the bound's `ne` latitude and `sw` longitude.
+ *
+ * @param bound - bound to read
+ * @returns the computed north-west corner point
+ */
 export declare function latLngBoundNorthWestPoint(bound: LatLngBound): LatLngPoint;
+/**
+ * Derives the south-east corner point from the bound's `sw` latitude and `ne` longitude.
+ *
+ * @param bound - bound to read
+ * @returns the computed south-east corner point
+ */
 export declare function latLngBoundSouthEastPoint(bound: LatLngBound): LatLngPoint;
+/**
+ * Returns the south-west corner point of the bound.
+ *
+ * @param bound - bound to read
+ * @returns the `sw` corner point
+ */
 export declare function latLngBoundSouthWestPoint(bound: LatLngBound): LatLngPoint;
+/**
+ * Computes the geographic center of the bound by averaging the corner coordinates.
+ *
+ * @param bound - bound to compute the center of
+ * @returns the center point
+ *
+ * @example
+ * ```ts
+ * const bound = latLngBound({ lat: 0, lng: 0 }, { lat: 40, lng: 40 });
+ * const center = latLngBoundCenterPoint(bound);
+ * // center.lat === 20, center.lng === 20
+ * ```
+ */
 export declare function latLngBoundCenterPoint(bound: LatLngBound): LatLngPoint;
+/**
+ * Returns the northern latitude boundary (the `ne` latitude).
+ *
+ * @param bound - bound to read
+ * @returns the latitude of the north edge
+ */
 export declare function latLngBoundNorthBound(bound: LatLngBound): number;
+/**
+ * Returns the southern latitude boundary (the `sw` latitude).
+ *
+ * @param bound - bound to read
+ * @returns the latitude of the south edge
+ */
 export declare function latLngBoundSouthBound(bound: LatLngBound): number;
+/**
+ * Returns the eastern longitude boundary (the `ne` longitude).
+ *
+ * @param bound - bound to read
+ * @returns the longitude of the east edge
+ */
 export declare function latLngBoundEastBound(bound: LatLngBound): number;
+/**
+ * Returns the western longitude boundary (the `sw` longitude).
+ *
+ * @param bound - bound to read
+ * @returns the longitude of the west edge
+ */
 export declare function latLngBoundWestBound(bound: LatLngBound): number;
 /**
  * Tuple of the sw corner and the north east point.
  */
 export type LatLngBoundTuple = [LatLngBoundSouthWestPoint | LatLngPointInput, LatLngBoundNothEastPoint | LatLngPointInput];
+/**
+ * Tuple of four points that define the corners of a bounding box, from which the min/max extents are derived.
+ */
 export type LatLngBoundTuplePoints = [LatLngPointInput, LatLngPointInput, LatLngPointInput, LatLngPointInput];
+/**
+ * Accepted input types for creating a {@link LatLngBound}: a bound object, a 2-element tuple (sw/ne), or a 4-element tuple of corner points.
+ */
 export type LatLngBoundInput = LatLngBound | LatLngBoundTuple | LatLngBoundTuplePoints;
+/**
+ * Convenience function that creates a {@link LatLngBoundTuple} using the default configuration.
+ *
+ * @param input - a sw point or any bound input
+ * @param inputNe - optional ne point when providing two separate points
+ * @returns a tuple of `[sw, ne]` points
+ */
 export declare function latLngBoundTuple(input: LatLngBoundSouthWestPoint | LatLngBoundInput, inputNe?: LatLngBoundNothEastPoint): LatLngBoundTuple;
 /**
- * Converts the input to a LatLngString
+ * Converts the input to a {@link LatLngBoundTuple}. Accepts the same flexible input types as {@link LatLngBoundFunction}.
  */
 export type LatLngBoundTupleFunction = ((input: LatLngBoundSouthWestPoint | LatLngBoundInput, inputNe?: LatLngBoundNothEastPoint) => LatLngBoundTuple) & ((sw: LatLngBoundSouthWestPoint, ne: LatLngBoundNothEastPoint) => LatLngBoundTuple) & ((bound: LatLngBoundInput) => LatLngBoundTuple);
 export type LatLngBoundTupleFunctionConfig = LatLngBoundFunctionConfig;
 /**
- * Creates a LatLngBoundTupleFunction
+ * Creates a {@link LatLngBoundTupleFunction} that converts various bound inputs into a `[sw, ne]` tuple,
+ * applying optional precision to the resulting points.
  *
- * @param precision
- * @returns
+ * @param config - optional configuration for point precision
+ * @returns a function that produces bound tuples from flexible inputs
  */
 export declare function latLngBoundTupleFunction(config?: LatLngBoundTupleFunctionConfig): LatLngBoundTupleFunction;
+/**
+ * Convenience function that creates a {@link LatLngBound} using the default configuration.
+ *
+ * @param input - a sw point or any bound input
+ * @param inputNe - optional ne point when providing two separate points
+ * @returns a bound object
+ *
+ * @example
+ * ```ts
+ * const bound = latLngBound({ lat: 0, lng: 0 }, { lat: 40, lng: 40 });
+ * // bound.sw.lat === 0, bound.ne.lat === 40
+ * ```
+ */
 export declare function latLngBound(input: LatLngBoundSouthWestPoint | LatLngBoundInput, inputNe?: LatLngBoundNothEastPoint): LatLngBound;
 /**
- * Converts the input to a LatLngBound
+ * Converts various input types to a {@link LatLngBound}. Accepts two separate points, a bound object, a 2-element tuple, or a 4-element tuple.
  */
 export type LatLngBoundFunction = ((input: LatLngBoundSouthWestPoint | LatLngBoundInput, inputNe?: LatLngBoundNothEastPoint) => LatLngBound) & ((sw: LatLngBoundSouthWestPoint, ne: LatLngBoundNothEastPoint) => LatLngBound) & ((bound: LatLngBoundInput) => LatLngBound);
+/**
+ * Configuration for creating a {@link LatLngBoundFunction}.
+ */
 export interface LatLngBoundFunctionConfig {
     /**
      * Point function to use for calculations.
@@ -77,34 +211,136 @@ export interface LatLngBoundFunctionConfig {
      */
     precision?: LatLngPrecision;
 }
+/**
+ * Creates a {@link LatLngBoundFunction} that normalizes various bound input formats into a {@link LatLngBound}.
+ *
+ * Supports creating bounds from: two separate points, a `[sw, ne]` tuple, a four-point tuple (computes min/max extents),
+ * or a pre-existing bound object.
+ *
+ * @param config - optional configuration for point precision and custom point functions
+ * @returns a function that produces bounds from flexible inputs
+ * @throws {Error} when the input cannot be parsed into a valid bound
+ *
+ * @example
+ * ```ts
+ * const fn = latLngBoundFunction({ precision: 3 });
+ * const result = fn([{ lat: 20, lng: 20 }, { lat: 30, lng: 30 }]);
+ * // result.sw.lat === 20, result.ne.lat === 30
+ * ```
+ */
 export declare function latLngBoundFunction(config?: LatLngBoundFunctionConfig): LatLngBoundFunction;
+/**
+ * Input type for {@link extendLatLngBound}: a single bound/point or an array of them.
+ */
 export type ExtendLatLngBoundInput = ArrayOrValue<LatLngBoundOrPoint>;
+/**
+ * Creates a {@link LatLngBound} from the input, which may be a single point, a single bound, or an array of points/bounds.
+ *
+ * When given an array, the first element seeds the initial bound and subsequent elements extend it.
+ *
+ * @param input - one or more points/bounds to derive the bounding box from
+ * @returns the computed bound, or `undefined` if the input is empty
+ *
+ * @example
+ * ```ts
+ * const bound = latLngBoundFromInput([
+ *   { lat: 0, lng: 0 },
+ *   { lat: 40, lng: 40 }
+ * ]);
+ * // bound covers from (0,0) to (40,40)
+ * ```
+ */
 export declare function latLngBoundFromInput(input: ExtendLatLngBoundInput): Maybe<LatLngBound>;
+/**
+ * Extends an existing bound to include all the given points and/or bounds.
+ *
+ * The returned bound's `sw` corner uses the minimum lat/lng encountered, and its `ne` corner uses the maximum.
+ *
+ * @param bound - the starting bound to extend
+ * @param extendWith - one or more points/bounds to include
+ * @returns a new bound that encompasses the original and all extensions
+ */
 export declare function extendLatLngBound(bound: LatLngBound, extendWith: ExtendLatLngBoundInput): LatLngBound;
+/**
+ * A decision function that checks whether a point or bound satisfies a spatial condition against a reference bound.
+ */
 export type LatLngBoundCheckFunction = DecisionFunction<LatLngBoundOrPoint>;
 /**
  * Function that returns true if the input is entirely within the context's bound.
+ *
+ * Exposes the reference bound via the `_bound` property.
  */
 export type IsWithinLatLngBoundFunction = LatLngBoundCheckFunction & {
     readonly _bound: LatLngBound;
 };
+/**
+ * Creates an {@link IsWithinLatLngBoundFunction} that checks if a given point or bound
+ * falls entirely within the specified bound. Points are checked directly; bounds require
+ * both corners to be within.
+ *
+ * @param bound - the reference bound to check containment against
+ * @returns a function that returns `true` if the input is within the reference bound
+ */
 export declare function isWithinLatLngBoundFunction(bound: LatLngBound): IsWithinLatLngBoundFunction;
+/**
+ * Checks whether one bound is entirely contained within another by verifying both its corners are within the outer bound.
+ *
+ * @param bound - the inner bound to test
+ * @param within - the outer bound to test against
+ * @returns `true` if both corners of `bound` are within `within`
+ */
 export declare function isLatLngBoundWithinLatLngBound(bound: LatLngBound, within: LatLngBound): boolean;
+/**
+ * Checks whether a point lies within a bound. Handles bounds that wrap the antimeridian by checking
+ * if the longitude falls on either side of the wrap.
+ *
+ * @param point - the point to test
+ * @param within - the bound to test against
+ * @returns `true` if the point is within the bound
+ *
+ * @example
+ * ```ts
+ * const bound = latLngBound({ lat: 0, lng: 0 }, { lat: 40, lng: 40 });
+ * isLatLngPointWithinLatLngBound(latLngPoint(10, 10), bound);
+ * // true
+ * ```
+ */
 export declare function isLatLngPointWithinLatLngBound(point: LatLngPoint, within: LatLngBound): boolean;
 /**
  * Function that returns true if the input overlaps the context's bound.
+ *
+ * Exposes the reference bound via the `_bound` property.
  */
 export type OverlapsLatLngBoundFunction = LatLngBoundCheckFunction & {
     readonly _bound: LatLngBound;
 };
+/**
+ * Checks whether two bounds overlap each other.
+ *
+ * @param a - the first bound
+ * @param b - the second bound
+ * @returns `true` if the bounds overlap
+ */
 export declare function latLngBoundOverlapsLatLngBound(a: LatLngBound, b: LatLngBound): boolean;
+/**
+ * Creates an {@link OverlapsLatLngBoundFunction} that checks whether a given point or bound
+ * overlaps the reference bound. Internally converts bounds to rectangles for overlap detection,
+ * handling antimeridian wrapping.
+ *
+ * @param bound - the reference bound to check overlap against
+ * @returns a function that returns `true` if the input overlaps the reference bound
+ */
 export declare function overlapsLatLngBoundFunction(bound: LatLngBound): OverlapsLatLngBoundFunction;
+/**
+ * The total span of longitude in degrees (360).
+ */
 export declare const TOTAL_SPAN_OF_LONGITUDE = 360;
 /**
- * "normalizes" the space so that the left -180 longitudinal bound will begin at 360.
- *
- * This turns the latitude/longitude into two rectangles in an arbitrary space that can be safely compared without worrying about wrapping.
+ * Normalizes a {@link LatLngBound} into a {@link Rectangle} in an arbitrary coordinate space
+ * where the left edge (-180 longitude) begins at x=360. This allows safe rectangle-based
+ * overlap comparisons without worrying about antimeridian wrapping.
  *
- * @param bound
+ * @param bound - the geographic bound to convert
+ * @returns a rectangle suitable for overlap calculations
  */
 export declare function boundToRectangle(bound: LatLngBound): Rectangle;

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

@@ -1,18 +1,43 @@
 import { type Configurable } from '../type';
 /**
- * Denotes a typically read-only like model is being built/configured.
+ * Represents a mutable partial version of a normally read-only model, used during construction/configuration.
+ *
+ * Combines `Partial` and `Configurable` (writable) so that properties can be set incrementally before the object is treated as complete.
  */
 export type Building<T> = Partial<Configurable<T>>;
+/**
+ * Function that mutates a {@link Building} instance to populate its properties.
+ */
 export type BuildFunction<T> = (base: Building<T>) => void;
+/**
+ * Configuration for the {@link build} function, providing the base object and the build function to apply.
+ */
 export interface BuildConfig<T extends object> {
+    /**
+     * Optional pre-existing partial object to build upon. If omitted, an empty object is used.
+     */
     base?: Building<T>;
+    /**
+     * Function that mutates the base to populate it with the desired values.
+     */
     build: BuildFunction<T>;
 }
 /**
- * Convenience function that is used to "build" an object of a specific type.
+ * Convenience function for imperatively constructing an object of a specific type by mutating a base object via a build function.
+ *
+ * This is useful when building objects whose type is normally read-only, allowing incremental property assignment during construction.
+ *
+ * @param config - the build configuration containing the base object and build function
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number; }
  *
- * @param base
- * @param buildFn
- * @returns
+ * const user = build<User>({
+ *   base: {},
+ *   build: (x) => { x.name = 'Alice'; x.age = 30; }
+ * });
+ * // user === { name: 'Alice', age: 30 }
+ * ```
  */
 export declare function build<T extends object>({ base, build }: BuildConfig<T>): T;

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

@@ -5,19 +5,41 @@ import { type Maybe } from './maybe.type';
  */
 export type EqualityComparatorFunction<T> = (a: T, b: T) => boolean;
 /**
- * Wraps a EqualityComparatorFunction that handles Maybe values and only uses the comparator when the input values are not null/undefined.
+ * Wraps an {@link EqualityComparatorFunction} to safely handle `Maybe` values.
  *
- * @param compare
- * @returns
+ * The wrapped function delegates to the comparator only when both values are non-nullish.
+ * When both are nullish, it uses strict equality (`===`), so `null === null` is `true`
+ * but `null === undefined` is `false`.
+ *
+ * @param compare - the comparator to wrap
+ *
+ * @example
+ * ```ts
+ * const safeCompare = safeEqualityComparatorFunction((a: number, b: number) => a === b);
+ * safeCompare(1, 1);       // true
+ * safeCompare(null, null);  // true
+ * safeCompare(null, undefined); // false
+ * ```
  */
 export declare function safeEqualityComparatorFunction<T>(compare: EqualityComparatorFunction<T>): EqualityComparatorFunction<Maybe<T>>;
 /**
- * Safely compares two Maybe values.
+ * Convenience function that safely compares two `Maybe` values using the provided comparator.
+ *
+ * Delegates to {@link safeEqualityComparatorFunction} internally, so nullish values are handled
+ * without invoking the comparator.
+ *
+ * @param a - first value to compare
+ * @param b - second value to compare
+ * @param compare - the equality comparator for non-nullish values
  *
- * @param a
- * @param b
- * @param compare
- * @returns
+ * @example
+ * ```ts
+ * safeCompareEquality(0, 1, (a, b) => a === b);
+ * // false
+ *
+ * safeCompareEquality(null, null, (a, b) => a === b);
+ * // true (comparator is not invoked)
+ * ```
  */
 export declare function safeCompareEquality<T>(a: Maybe<T>, b: Maybe<T>, compare: EqualityComparatorFunction<T>): boolean;
 /**
@@ -29,29 +51,22 @@ export declare function safeCompareEquality<T>(a: Maybe<T>, b: Maybe<T>, compare
  */
 export type CompareEqualityWithValueFromItemsFunction<I, V> = ((a: Maybe<I>, b: Maybe<I>) => boolean) & {
     /**
-     * Used to read the values from the input, if the input is defined.
-     *
-     * @param a
-     * @returns
+     * The function used to extract comparable values from each input item.
      */
     readonly _readValues: ReadValueFunction<I, V>;
     /**
-     * Decision function.
-     *
-     * @param a
-     * @param b
-     * @returns
+     * The equality comparator applied to the extracted values.
      */
     readonly _equalityComparator: EqualityComparatorFunction<V>;
 };
 /**
- * Creates a new CompareEqualityWithValueFromItemsFunction.
+ * Creates a {@link CompareEqualityWithValueFromItemsFunction} that extracts values from items before comparing them.
  *
- * Convenience function for calling compareEqualityWithValueFromItemsFunctionFactory() and passing the read values and values decision functions.
+ * This is a convenience wrapper around {@link compareEqualityWithValueFromItemsFunctionFactory} that
+ * accepts both the value reader and comparator in a single call.
  *
- * @param readValues
- * @param equalityComparator
- * @returns
+ * @param readValues - extracts the comparable value from each item
+ * @param equalityComparator - compares the extracted values for equality
  */
 export declare function compareEqualityWithValueFromItemsFunction<I, V>(readValues: ReadValueFunction<I, V>, equalityComparator: EqualityComparatorFunction<V>): CompareEqualityWithValueFromItemsFunction<I, V>;
 /**
@@ -59,9 +74,22 @@ export declare function compareEqualityWithValueFromItemsFunction<I, V>(readValu
  */
 export type CompareEqualityWithValueFromItemsFunctionFactory<I, V> = ((equalityComparator: EqualityComparatorFunction<V>) => CompareEqualityWithValueFromItemsFunction<I, V>) & Pick<CompareEqualityWithValueFromItemsFunction<I, V>, '_readValues'>;
 /**
- * Creates a new CompareEqualityWithValueFromItemsFunctionFactory.
+ * Creates a {@link CompareEqualityWithValueFromItemsFunctionFactory} that is pre-configured with a value reader.
+ *
+ * The returned factory accepts different equality comparators, allowing reuse of the same value extraction logic
+ * with varying comparison strategies.
+ *
+ * @param readValues - extracts the comparable value from each item
+ *
+ * @example
+ * ```ts
+ * const factory = compareEqualityWithValueFromItemsFunctionFactory<number, number[]>((x) => [x]);
+ * const fn = factory(iterablesAreSetEquivalent);
  *
- * @param readValues
- * @returns
+ * fn(0, 0);           // true
+ * fn(null, null);     // true
+ * fn(undefined, undefined); // true
+ * fn(0, 1);           // false
+ * ```
  */
 export declare function compareEqualityWithValueFromItemsFunctionFactory<I, V>(readValues: ReadValueFunction<I, V>): CompareEqualityWithValueFromItemsFunctionFactory<I, V>;