@dereekb/util 13.11.14 → 13.11.15

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

@@ -63,48 +63,48 @@ export interface LonLatPoint {
 /**
  * Type guard that checks whether the input is a {@link LatLngPoint} by testing for `lat` and `lng` properties.
  *
- * @param input - the value to test
- * @returns `true` if the input has both `lat` and `lng` properties
+ * @param input - The value to test.
+ * @returns `true` if the input has both `lat` and `lng` properties.
  */
 export declare function isLatLngPoint(input: LatLngPoint | unknown): input is LatLngPoint;
 /**
  * Creates a shallow copy of the point so that mutations to the copy do not affect the original.
  *
- * @param input - point to copy
- * @returns a new point with the same coordinates
+ * @param input - Point to copy.
+ * @returns A new point with the same coordinates.
  */
 export declare function copyLatLngPoint(input: LatLngPoint): LatLngPoint;
 /**
  * Checks whether two points have identical coordinates. Handles `null`/`undefined` by returning `true` only if both are nullish.
  *
- * @param a - first point
- * @param b - second point
- * @returns `true` if both points have the same `lat` and `lng`, or both are nullish
+ * @param a - First point.
+ * @param b - Second point.
+ * @returns `true` if both points have the same `lat` and `lng`, or both are nullish.
  */
 export declare function isSameLatLngPoint(a: Maybe<LatLngPoint>, b: Maybe<LatLngPoint>): boolean;
 /**
  * Computes the difference between two points (`a - b`), optionally wrapping the result to valid lat/lng ranges.
  *
- * @param a - the point to subtract from
- * @param b - the point to subtract
- * @param wrap - whether to wrap the result to valid lat/lng ranges; defaults to `true`
- * @returns a point representing the difference
+ * @param a - The point to subtract from.
+ * @param b - The point to subtract.
+ * @param wrap - Whether to wrap the result to valid lat/lng ranges; defaults to `true`
+ * @returns A point representing the difference.
  */
 export declare function diffLatLngPoints(a: LatLngPoint, b: LatLngPoint, wrap?: boolean): LatLngPoint;
 /**
  * Computes the sum of two points (`a + b`), optionally wrapping the result to valid lat/lng ranges.
  *
- * @param a - the first point
- * @param b - the second point
- * @param wrap - whether to wrap the result to valid lat/lng ranges; defaults to `true`
- * @returns a point representing the sum
+ * @param a - The first point.
+ * @param b - The second point.
+ * @param wrap - Whether to wrap the result to valid lat/lng ranges; defaults to `true`
+ * @returns A point representing the sum.
  */
 export declare function addLatLngPoints(a: LatLngPoint, b: LatLngPoint, wrap?: boolean): LatLngPoint;
 /**
  * Wraps a point so its latitude is capped to [-90, 90] and its longitude wraps around [-180, 180].
  *
- * @param a - point to wrap
- * @returns a new point with valid coordinates
+ * @param a - Point to wrap.
+ * @returns A new point with valid coordinates.
  */
 export declare function wrapLatLngPoint(a: LatLngPoint): LatLngPoint;
 /**
@@ -127,55 +127,55 @@ export declare const wrapLngValue: import("..").WrapNumberFunction<number>;
 /**
  * Checks whether a latitude value is within the valid range [-90, 90].
  *
- * @param lat - latitude value to validate
- * @returns `true` if the value is a valid latitude
+ * @param lat - Latitude value to validate.
+ * @returns `true` if the value is a valid latitude.
  */
 export declare function isValidLatitude(lat: Latitude): boolean;
 /**
  * Checks whether a longitude value is within the valid range [-180, 180].
  *
- * @param lat - longitude value to validate
- * @returns `true` if the value is a valid longitude
+ * @param lat - Longitude value to validate.
+ * @returns `true` if the value is a valid longitude.
  */
 export declare function isValidLongitude(lat: Longitude): boolean;
 /**
  * Returns the default {@link LatLngPoint} at the origin (0, 0).
  *
- * @returns a point at latitude 0, longitude 0
+ * @returns A point at latitude 0, longitude 0.
  */
 export declare function defaultLatLngPoint(): LatLngPoint;
 /**
  * Checks whether a point or string represents the default (0, 0) location.
  * Treats empty strings as the default.
  *
- * @param point - a point or lat/lng string to check
- * @returns `true` if the input represents the default location
+ * @param point - A point or lat/lng string to check.
+ * @returns `true` if the input represents the default location.
  */
 export declare function isDefaultLatLngPoint(point: LatLngPoint | LatLngString | ''): boolean;
 /**
  * Checks whether a point has coordinates of exactly (0, 0).
  *
- * @param point - point to check
- * @returns `true` if both `lat` and `lng` are 0
+ * @param point - Point to check.
+ * @returns `true` if both `lat` and `lng` are 0.
  */
 export declare function isDefaultLatLngPointValue(point: LatLngPoint): boolean;
 /**
  * Returns the south-west-most possible point (-90, -180).
  *
- * @returns the minimum corner of the valid coordinate space
+ * @returns The minimum corner of the valid coordinate space.
  */
 export declare function swMostLatLngPoint(): LatLngPoint;
 /**
  * Returns the north-east-most possible point (90, 180).
  *
- * @returns the maximum corner of the valid coordinate space
+ * @returns The maximum corner of the valid coordinate space.
  */
 export declare function neMostLatLngPoint(): LatLngPoint;
 /**
  * Returns true if the input point's lat/lng values are within the acceptable values range.
  *
- * @param input - point to validate
- * @returns `true` if both lat and lng are within valid ranges
+ * @param input - Point to validate.
+ * @returns `true` if both lat and lng are within valid ranges.
  */
 export declare function isValidLatLngPoint(input: LatLngPoint): boolean;
 /**
@@ -189,17 +189,17 @@ export type LonLatTuple = [Longitude, Latitude];
 /**
  * Converts the input to a {@link LatLngTuple} using the default configuration.
  *
- * @param lat - a latitude value or any lat/lng point input
- * @param lng - optional longitude when `lat` is a numeric latitude
- * @returns a `[lat, lng]` tuple
+ * @param lat - A latitude value or any lat/lng point input.
+ * @param lng - Optional longitude when `lat` is a numeric latitude.
+ * @returns A `[lat, lng]` tuple.
  */
 export declare function latLngTuple(lat: LatLngPointInput, lng?: Longitude): LatLngTuple;
 /**
  * Converts the input to a {@link LonLatTuple} (longitude-first ordering), useful for interop with libraries like Mapbox.
  *
- * @param lat - a latitude value or any lat/lng point input
- * @param lng - optional longitude when `lat` is a numeric latitude
- * @returns a `[lng, lat]` tuple
+ * @param lat - A latitude value or any lat/lng point input.
+ * @param lng - Optional longitude when `lat` is a numeric latitude.
+ * @returns A `[lng, lat]` tuple.
  *
  * @example
  * ```ts
@@ -217,14 +217,15 @@ export type LatLngTupleFunctionConfig = LatLngPointFunctionConfig;
  * Creates a {@link LatLngTupleFunction} that converts various input formats into `[lat, lng]` tuples,
  * applying optional precision configuration.
  *
+ * @param config - Optional configuration for precision and wrapping behavior.
+ * @returns Produces lat/lng tuples from flexible inputs.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags value, lat-lng, tuple, factory, geographic, normalize
  * @dbxUtilRelated lat-lng-point-function, lat-lng-string-function
  *
- * @param config - optional configuration for precision and wrapping behavior
- * @returns a function that produces lat/lng tuples from flexible inputs
  * @__NO_SIDE_EFFECTS__
  */
 export declare function latLngTupleFunction(config?: LatLngTupleFunctionConfig): LatLngTupleFunction;
@@ -239,7 +240,7 @@ export declare const DEFAULT_LAT_LNG_STRING_VALUE = "0,0";
 /**
  * Returns the default {@link LatLngString} value (`'0,0'`).
  *
- * @returns the default lat/lng string
+ * @returns The default lat/lng string.
  */
 export declare function defaultLatLngString(): typeof DEFAULT_LAT_LNG_STRING_VALUE;
 /**
@@ -275,8 +276,8 @@ export declare const LAT_LNG_PATTERN: RegExp;
 /**
  * Checks whether the input string matches the expected lat/lng pattern (e.g., `"30.5,-96.3"`).
  *
- * @param input - string to test
- * @returns `true` if the string is a valid lat/lng format
+ * @param input - String to test.
+ * @returns `true` if the string is a valid lat/lng format.
  */
 export declare function isLatLngString(input: string): input is LatLngString;
 /**
@@ -331,15 +332,16 @@ export type LatLngPointPrecisionFunction = (latLngPoint: LatLngPoint) => LatLngP
  * Creates a {@link LatLngPointPrecisionFunction} that rounds both lat and lng values
  * to the specified number of decimal places.
  *
+ * @param precision - Number of decimal places to retain.
+ * @param precisionRounding - Optional rounding strategy (e.g., floor, ceil, round)
+ * @returns Rounds points to the given precision.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags value, lat-lng, precision, round, factory, geographic
  * @dbxUtilRelated lat-lng-point-function, cut-value-to-precision-function
  *
- * @param precision - number of decimal places to retain
- * @param precisionRounding - optional rounding strategy (e.g., floor, ceil, round)
- * @returns a function that rounds points to the given precision
  * @__NO_SIDE_EFFECTS__
  */
 export declare function latLngPointPrecisionFunction(precision: LatLngPrecision, precisionRounding?: RoundToPrecisionFunctionType): LatLngPointPrecisionFunction;
@@ -352,14 +354,15 @@ export type LatLngStringFunctionConfig = LatLngPointFunctionConfig;
  * Creates a {@link LatLngStringFunction} that converts various input formats into comma-separated lat/lng strings,
  * applying optional precision configuration.
  *
+ * @param config - Optional configuration for precision and wrapping behavior.
+ * @returns Produces lat/lng strings from flexible inputs.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags value, lat-lng, string, factory, geographic, normalize
  * @dbxUtilRelated lat-lng-point-function, lat-lng-tuple-function
  *
- * @param config - optional configuration for precision and wrapping behavior
- * @returns a function that produces lat/lng strings from flexible inputs
  * @__NO_SIDE_EFFECTS__
  */
 export declare function latLngStringFunction(config?: LatLngStringFunctionConfig): LatLngStringFunction;
@@ -374,38 +377,38 @@ export interface LatLngPointFunctionConfig {
     /**
      * LatLngPrecision to use
      */
-    precision?: LatLngPrecision | null;
+    readonly precision?: Maybe<LatLngPrecision>;
     /**
      * Precision rounding to use.
      */
-    precisionRounding?: RoundToPrecisionFunctionType;
+    readonly precisionRounding?: RoundToPrecisionFunctionType;
     /**
      * Whether or not to wrap invalid LatLng values. If false, the values are validated and a default value is used instead.
      *
      * Is true by default.
      */
-    wrap?: boolean;
+    readonly wrap?: boolean;
     /**
      * Whether or not to valiate the input. Is ignored if wrap is not false.
      */
-    validate?: boolean;
+    readonly validate?: boolean;
     /**
      * The default LatLngPoint to return if an invalid point is entered. Only used if validate is true.
      */
-    default?: Factory<LatLngPoint>;
+    readonly default?: Factory<LatLngPoint>;
     /**
      * Treat tuples as LonLat instead of LatLng.
      *
      * False by default
      */
-    readLonLatTuples?: boolean;
+    readonly readLonLatTuples?: boolean;
 }
 /**
  * Creates a {@link LatLngPoint} using the default configuration. Convenience wrapper around {@link latLngPointFunction}.
  *
- * @param lat - a latitude value or any lat/lng point input
- * @param lng - optional longitude when `lat` is a numeric latitude
- * @returns the parsed and normalized point
+ * @param lat - A latitude value or any lat/lng point input.
+ * @param lng - Optional longitude when `lat` is a numeric latitude.
+ * @returns The parsed and normalized point.
  *
  * @example
  * ```ts
@@ -418,9 +421,9 @@ export declare function latLngPoint(lat: LatLngPointInput, lng?: Longitude): Lat
  * Creates a {@link LatLngPointFunction} that normalizes various input formats (numbers, strings, tuples, objects)
  * into a {@link LatLngPoint}, with configurable precision, wrapping, and validation.
  *
- * @param config - optional configuration for precision, wrapping, validation, and tuple ordering
- * @returns a function that produces points from flexible inputs
- * @throws {Error} when the input cannot be parsed into a valid point
+ * @param config - Optional configuration for precision, wrapping, validation, and tuple ordering.
+ * @returns Produces points from flexible inputs.
+ * @throws {Error} When the input cannot be parsed into a valid point.
  *
  * @dbxUtil
  * @dbxUtilCategory value
@@ -434,22 +437,23 @@ export declare function latLngPoint(lat: LatLngPointInput, lng?: Longitude): Lat
  * const result = fn(30.59929, -96.38315);
  * // result.lat === 30.599, result.lng === -96.383
  * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function latLngPointFunction(config?: LatLngPointFunctionConfig): LatLngPointFunction;
 /**
  * Parses a comma-separated lat/lng string into a {@link LatLngPoint}. Invalid numeric values default to 0.
  *
- * @param latLngString - string in the format `"lat,lng"`
- * @returns the parsed point
+ * @param latLngString - String in the format `"lat,lng"`
+ * @returns The parsed point.
  */
 export declare function latLngPointFromString(latLngString: LatLngString | string): LatLngPoint;
 /**
  * Validates a point and returns it if valid, or a default point otherwise.
  *
- * @param latLngPoint - point to validate
- * @param defaultValue - optional factory for the fallback point; defaults to `defaultLatLngPoint`
- * @returns the original point if valid, or the default
+ * @param latLngPoint - Point to validate.
+ * @param defaultValue - Optional factory for the fallback point; defaults to `defaultLatLngPoint`
+ * @returns The original point if valid, or the default.
  */
 export declare function validLatLngPoint(latLngPoint: LatLngPoint, defaultValue?: Factory<LatLngPoint>): LatLngPoint;
 /**
@@ -459,14 +463,15 @@ export type ValidLatLngPointFunction = (latLngPoint: LatLngPoint) => LatLngPoint
 /**
  * Creates a {@link ValidLatLngPointFunction} that returns the input point when valid, or a default point otherwise.
  *
+ * @param defaultValue - Factory for the fallback point; defaults to `defaultLatLngPoint`
+ * @returns A validation function.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags value, lat-lng, validate, fallback, factory, geographic
  * @dbxUtilRelated valid-lat-lng-point, is-valid-lat-lng-point
  *
- * @param defaultValue - factory for the fallback point; defaults to `defaultLatLngPoint`
- * @returns a validation function
  * @__NO_SIDE_EFFECTS__
  */
 export declare function validLatLngPointFunction(defaultValue?: Factory<LatLngPoint>): ValidLatLngPointFunction;
@@ -511,14 +516,15 @@ export type LatLngDataPointFunction<T extends LatLngRef> = (data: T) => LatLngDa
 /**
  * Creates a {@link LatLngDataPointFunction} that wraps a {@link LatLngRef} object with its resolved point coordinates.
  *
+ * @param config - Optional configuration for precision and wrapping behavior.
+ * @returns Produces data points from lat/lng references.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags value, lat-lng, data-point, factory, geographic, ref
  * @dbxUtilRelated lat-lng-point-function
  *
- * @param config - optional configuration for precision and wrapping behavior
- * @returns a function that produces data points from lat/lng references
  * @__NO_SIDE_EFFECTS__
  */
 export declare function latLngDataPointFunction<T extends LatLngRef>(config?: LatLngPointFunctionConfig): LatLngDataPointFunction<T>;
@@ -529,15 +535,15 @@ export interface RandomLatLngFactoryConfig {
     /**
      * South-west corner of the bounding box for random generation. Partial values default to the minimum valid coordinates.
      */
-    sw?: Partial<LatLngPoint>;
+    readonly sw?: Partial<LatLngPoint>;
     /**
      * North-east corner of the bounding box for random generation. Partial values default to the maximum valid coordinates.
      */
-    ne?: Partial<LatLngPoint>;
+    readonly ne?: Partial<LatLngPoint>;
     /**
      * Precision of the LatLng to keep.
      */
-    precision?: LatLngPrecision;
+    readonly precision?: LatLngPrecision;
 }
 /**
  * A factory that produces random {@link LatLngPoint} values.
@@ -547,14 +553,15 @@ export type RandomLatLngFactory = () => LatLngPoint;
  * Creates a {@link RandomLatLngFactory} that generates random points within the specified bounding box.
  * The bounding box corners are capped/wrapped to valid coordinate ranges.
  *
+ * @param config - Optional bounding box and precision configuration.
+ * @returns A factory that produces random points within the bounds.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags value, lat-lng, random, factory, geographic, bounding-box
  * @dbxUtilRelated random-lat-lng-from-center-factory, random-number-factory
  *
- * @param config - optional bounding box and precision configuration
- * @returns a factory that produces random points within the bounds
  * @__NO_SIDE_EFFECTS__
  */
 export declare function randomLatLngFactory(config?: RandomLatLngFactoryConfig): RandomLatLngFactory;
@@ -565,28 +572,29 @@ export interface RandomLatLngFromCenterFactoryConfig extends Pick<RandomLatLngFa
     /**
      * Center from which a rectangle is generated to pick random
      */
-    center: LatLngPoint;
+    readonly center: LatLngPoint;
     /**
      * Max distance from the center.
      */
-    latDistance: number;
+    readonly latDistance: number;
     /**
      * Max lng distance from the center.
      */
-    lngDistance: number;
+    readonly lngDistance: number;
 }
 /**
  * Creates a {@link RandomLatLngFactory} that generates random points within a rectangle
  * centered on the given point, extending by `latDistance` and `lngDistance` in each direction.
  *
+ * @param config - Center point, distances, and optional precision.
+ * @returns A factory that produces random points near the center.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags value, lat-lng, random, factory, geographic, center
  * @dbxUtilRelated random-lat-lng-factory, random-number-factory
  *
- * @param config - center point, distances, and optional precision
- * @returns a factory that produces random points near the center
  * @__NO_SIDE_EFFECTS__
  */
 export declare function randomLatLngFromCenterFactory(config: RandomLatLngFromCenterFactoryConfig): RandomLatLngFactory;

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

@@ -3,8 +3,8 @@
  *
  * Operates via simple string splitting rather than URL parsing, so it works with partial or non-standard URLs.
  *
- * @param url - the full URL string to clean
- * @returns the URL string with query parameters and hash fragments removed
+ * @param url - The full URL string to clean.
+ * @returns The URL string with query parameters and hash fragments removed.
  *
  * @example
  * ```ts

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

@@ -11,10 +11,10 @@ export type UseValue<I, O = void> = MapFunction<I, O>;
  * Applies the `use` function to the input if it is defined, otherwise returns the `defaultValue`.
  * Provides a safe pattern for consuming nullable values with a fallback.
  *
- * @param input - the possibly null/undefined value to consume
- * @param use - function to apply when input is defined
- * @param defaultValue - fallback value or getter used when input is null/undefined
- * @returns the result of `use`, or the default value if input was null/undefined
+ * @param input - The possibly null/undefined value to consume.
+ * @param use - Function to apply when input is defined.
+ * @param defaultValue - Fallback value or getter used when input is null/undefined.
+ * @returns The result of `use`, or the default value if input was null/undefined.
  *
  * @example
  * ```ts
@@ -39,8 +39,14 @@ export type MappedUseFunction<A, I> = <O = void>(input: Maybe<A>, use: UseValue<
  * Creates a {@link MappedUseFunction} that transforms the input through the given `map` before applying the consumer.
  * If the mapped result is null/undefined, the default value is returned instead.
  *
- * @param map - transforms the outer input into the type expected by the consumer
- * @returns a MappedUseFunction that maps then consumes
+ * @param map - Transforms the outer input into the type expected by the consumer.
+ * @returns A MappedUseFunction that maps then consumes.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, use, map, factory, optional, fallback
+ * @dbxUtilRelated wrap-use-function, use-context-function
  *
  * @example
  * ```ts
@@ -54,12 +60,6 @@ export type MappedUseFunction<A, I> = <O = void>(input: Maybe<A>, use: UseValue<
  * // fallback === 'default'
  * ```
  *
- * @dbxUtil
- * @dbxUtilCategory value
- * @dbxUtilKind factory
- * @dbxUtilTags value, use, map, factory, optional, fallback
- * @dbxUtilRelated wrap-use-function, use-context-function
- *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function mappedUseFunction<A, I>(map: MapFunction<A, Maybe<I>>): MappedUseFunction<A, I>;
@@ -67,15 +67,16 @@ export declare function mappedUseFunction<A, I>(map: MapFunction<A, Maybe<I>>):
  * Wraps an existing {@link MappedUseFunction} with an additional mapping step, allowing further transformation
  * of the intermediate value before it reaches the consumer.
  *
+ * @param mappedUseFn - The existing mapped use function to wrap.
+ * @param map - Additional transformation applied to the intermediate value.
+ * @returns A new MappedUseFunction with the extra mapping layer.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags value, use, map, wrap, compose, factory
  * @dbxUtilRelated mapped-use-function, use-value
  *
- * @param mappedUseFn - the existing mapped use function to wrap
- * @param map - additional transformation applied to the intermediate value
- * @returns a new MappedUseFunction with the extra mapping layer
  * @__NO_SIDE_EFFECTS__
  */
 export declare function wrapUseFunction<A, B, I>(mappedUseFn: MappedUseFunction<A, B>, map: MapFunction<B, Maybe<I>>): MappedUseFunction<A, I>;
@@ -88,15 +89,16 @@ export type UseContextFunction<I> = <O>(input: Maybe<I>) => Maybe<O>;
  * Creates a {@link UseContextFunction} by binding a consumer and optional default value, so callers
  * only need to supply the input.
  *
+ * @param use - The consumer function to bind.
+ * @param defaultValue - Fallback when input is null/undefined.
+ * @returns A single-argument function that applies the bound consumer.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags value, use, context, factory, bind, default
  * @dbxUtilRelated use-value, mapped-use-function
  *
- * @param use - the consumer function to bind
- * @param defaultValue - fallback when input is null/undefined
- * @returns a single-argument function that applies the bound consumer
  * @__NO_SIDE_EFFECTS__
  */
 export declare function useContextFunction<I, O>(use: UseValue<I, O>, defaultValue?: GetterOrValue<O>): UseContextFunction<I>;
@@ -107,10 +109,10 @@ export type UseAsync<I, O = void> = MapFunction<I, PromiseOrValue<O>>;
 /**
  * Async variant of {@link useValue}. Awaits the consumer result and supports async default value getters.
  *
- * @param input - the possibly null/undefined value to consume
- * @param use - async-capable consumer function
- * @param defaultValue - fallback value or getter when input is null/undefined
- * @returns a Promise resolving to the consumer result or the default value
+ * @param input - The possibly null/undefined value to consume.
+ * @param use - Async-capable consumer function.
+ * @param defaultValue - Fallback value or getter when input is null/undefined.
+ * @returns Promise resolving to the consumer result or the default value.
  *
  * @example
  * ```ts
@@ -131,8 +133,14 @@ export type MappedUseAsyncFunction<A, I> = <O = void>(input: Maybe<A>, use: UseA
  * Creates a {@link MappedUseAsyncFunction} that transforms the input through the given `map` (which may return a Promise)
  * before applying the async consumer.
  *
- * @param map - transforms the outer input, optionally asynchronously, into the type expected by the consumer
- * @returns a MappedUseAsyncFunction that maps then asynchronously consumes
+ * @param map - Transforms the outer input, optionally asynchronously, into the type expected by the consumer.
+ * @returns A MappedUseAsyncFunction that maps then asynchronously consumes.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, use, async, map, factory, promise
+ * @dbxUtilRelated wrap-use-async-function, mapped-use-function
  *
  * @example
  * ```ts
@@ -143,12 +151,6 @@ export type MappedUseAsyncFunction<A, I> = <O = void>(input: Maybe<A>, use: UseA
  * // result === 'hello'
  * ```
  *
- * @dbxUtil
- * @dbxUtilCategory value
- * @dbxUtilKind factory
- * @dbxUtilTags value, use, async, map, factory, promise
- * @dbxUtilRelated wrap-use-async-function, mapped-use-function
- *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function mappedUseAsyncFunction<A, I>(map: MapFunction<A, Maybe<PromiseOrValue<Maybe<I>>>>): MappedUseAsyncFunction<A, I>;
@@ -156,15 +158,16 @@ export declare function mappedUseAsyncFunction<A, I>(map: MapFunction<A, Maybe<P
  * Wraps an existing {@link MappedUseAsyncFunction} with an additional async-capable mapping step,
  * allowing further transformation of the intermediate value before it reaches the consumer.
  *
+ * @param mappedUsePromiseFn - The existing async mapped use function to wrap.
+ * @param map - Additional transformation (sync or async) applied to the intermediate value.
+ * @returns A new MappedUseAsyncFunction with the extra mapping layer.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags value, use, async, map, wrap, compose, factory, promise
  * @dbxUtilRelated mapped-use-async-function, wrap-use-function
  *
- * @param mappedUsePromiseFn - the existing async mapped use function to wrap
- * @param map - additional transformation (sync or async) applied to the intermediate value
- * @returns a new MappedUseAsyncFunction with the extra mapping layer
  * @__NO_SIDE_EFFECTS__
  */
 export declare function wrapUseAsyncFunction<A, B, I>(mappedUsePromiseFn: MappedUseAsyncFunction<A, B>, map: MapFunction<B, Maybe<PromiseOrValue<Maybe<I>>>>): MappedUseAsyncFunction<A, I>;

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

@@ -16,17 +16,17 @@ export type VectorTuple = [number, number];
  * If both values are non-nullish, delegates to {@link vectorsAreEqual}.
  * If both are nullish, uses strict equality (`===`).
  *
- * @param a - first vector
- * @param b - second vector
- * @returns `true` if both vectors are equal or both are nullish
+ * @param a - First vector.
+ * @param b - Second vector.
+ * @returns `true` if both vectors are equal or both are nullish.
  */
 export declare function isSameVector(a: Maybe<Partial<Vector>>, b: Maybe<Partial<Vector>>): boolean;
 /**
  * Returns `true` if both vectors have the same `x` and `y` values using strict equality.
  *
- * @param a - first vector
- * @param b - second vector
- * @returns `true` if both vectors have identical `x` and `y` values
+ * @param a - First vector.
+ * @param b - Second vector.
+ * @returns `true` if both vectors have identical `x` and `y` values.
  */
 export declare function vectorsAreEqual(a: Partial<Vector>, b: Partial<Vector>): boolean;
 /**
@@ -39,8 +39,8 @@ export type VectorResizeFunction = (input: Vector) => Vector;
  * For each axis, if a minimum is specified, the result uses whichever value is larger (input or minimum).
  * If a minimum is not specified for an axis, the input value is passed through unchanged.
  *
- * @param minSize - the minimum dimensions to enforce
- * @returns a resize function that clamps each axis to the specified minimum
+ * @param minSize - The minimum dimensions to enforce.
+ * @returns A resize function that clamps each axis to the specified minimum.
  *
  * @dbxUtil
  * @dbxUtilCategory value
@@ -54,6 +54,7 @@ export type VectorResizeFunction = (input: Vector) => Vector;
  * resize({ x: 3, y: 10 });
  * // { x: 5, y: 10 }
  * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function vectorMinimumSizeResizeFunction(minSize: Partial<Vector>): VectorResizeFunction;
@@ -87,9 +88,9 @@ export interface Rectangle {
  *
  * Degenerate rectangles (where corners coincide on an axis) are considered non-overlapping.
  *
- * @param a - first rectangle
- * @param b - second rectangle
- * @returns `true` if the rectangles share any interior area
+ * @param a - First rectangle.
+ * @param b - Second rectangle.
+ * @returns `true` if the rectangles share any interior area.
  *
  * @example
  * ```ts
@@ -107,8 +108,8 @@ export declare function rectangleOverlapsRectangle(a: Rectangle, b: Rectangle):
  * Returns the overlapping {@link Rectangle} if the two inputs intersect,
  * or `undefined` if they do not overlap.
  *
- * @param a - first rectangle
- * @param b - second rectangle
- * @returns the overlapping {@link Rectangle}, or `undefined` if the rectangles do not intersect
+ * @param a - First rectangle.
+ * @param b - Second rectangle.
+ * @returns The overlapping {@link Rectangle}, or `undefined` if the rectangles do not intersect.
  */
 export declare function getOverlappingRectangle(a: Rectangle, b: Rectangle): Maybe<Rectangle>;