@dereekb/util 13.0.7 → 13.2.0

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

@@ -2,19 +2,40 @@ import { type Factory } from '../getter/getter';
 import { type NumberPrecision, type RoundToPrecisionFunctionType } from '../number/round';
 import { type Maybe } from './maybe.type';
 /**
- * Latitude value
+ * Latitude value in degrees, ranging from -90 to 90.
  */
 export type Latitude = number;
 /**
- * Longitude value
+ * Longitude value in degrees, ranging from -180 to 180.
  */
 export type Longitude = number;
+/**
+ * Minimum valid latitude value (-90 degrees).
+ */
 export declare const MIN_LATITUDE_VALUE = -90;
+/**
+ * Maximum valid latitude value (90 degrees).
+ */
 export declare const MAX_LATITUDE_VALUE = 90;
+/**
+ * Total range of latitude values (180 degrees).
+ */
 export declare const TOTAL_LATITUDE_RANGE: number;
+/**
+ * Minimum valid longitude value (-180 degrees).
+ */
 export declare const MIN_LONGITUDE_VALUE = -180;
+/**
+ * Maximum valid longitude value (180 degrees).
+ */
 export declare const MAX_LONGITUDE_VALUE = 180;
+/**
+ * Total range of longitude values (360 degrees).
+ */
 export declare const TOTAL_LONGITUDE_RANGE: number;
+/**
+ * A geographic point represented by latitude and longitude.
+ */
 export interface LatLngPoint {
     lat: Latitude;
     lng: Longitude;
@@ -28,26 +49,119 @@ export interface LonLatPoint {
     lat: Latitude;
     lon: Longitude;
 }
+/**
+ * Type guard that checks whether the input is a {@link LatLngPoint} by testing for `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
+ */
 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
+ */
 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
+ */
 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
+ */
 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
+ */
 export declare function wrapLatLngPoint(a: LatLngPoint): LatLngPoint;
+/**
+ * Caps a latitude value to the valid range [-90, 90]. Values outside are clamped to the nearest boundary.
+ */
 export declare const capLatValue: import("..").BoundNumberFunction<number>;
+/**
+ * Wraps a longitude value into the valid range [-180, 180]. Values that exceed the range wrap around to the opposite side.
+ *
+ * @example
+ * ```ts
+ * wrapLngValue(-190);
+ * // 170
+ *
+ * wrapLngValue(190);
+ * // -170
+ * ```
+ */
 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
+ */
 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
+ */
 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
+ */
 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
+ */
 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
+ */
 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
+ */
 export declare function swMostLatLngPoint(): LatLngPoint;
+/**
+ * Returns the north-east-most possible point (90, 180).
+ *
+ * @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
- * @returns
+ * @param input - point to validate
+ * @returns `true` if both lat and lng are within valid ranges
  */
 export declare function isValidLatLngPoint(input: LatLngPoint): boolean;
 /**
@@ -59,53 +173,75 @@ export type LatLngTuple = [Latitude, Longitude];
  */
 export type LonLatTuple = [Longitude, Latitude];
 /**
- * Converts the input to a LatLngTuple.
+ * Converts the input to a {@link LatLngTuple} using the default configuration.
  *
- * @param lat
- * @param lng
- * @returns
+ * @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 LonLatTuple.
+ * 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
- * @param lng
- * @returns
+ * @example
+ * ```ts
+ * const result: LonLatTuple = lonLatTuple([-120, 80]);
+ * // result === [-120, 80]
+ * ```
  */
 export declare function lonLatTuple(lat: LatLngPointInput, lng?: Longitude): LonLatTuple;
 /**
- * Converts the input to a LatLngString
+ * Converts various lat/lng input formats into a {@link LatLngTuple}.
  */
 export type LatLngTupleFunction = ((lat: LatLngPointInput, lng?: Longitude) => LatLngTuple) & ((latLng: string | LatLngTuple) => LatLngTuple) & ((latLng: LatLngPoint | LonLatPoint) => LatLngTuple) & ((lat: Latitude, lng?: Longitude) => LatLngTuple);
 export type LatLngTupleFunctionConfig = LatLngPointFunctionConfig;
 /**
- * Creates a LatLngTupleFunction
+ * Creates a {@link LatLngTupleFunction} that converts various input formats into `[lat, lng]` tuples,
+ * applying optional precision configuration.
  *
- * @param precision
- * @returns
+ * @param config - optional configuration for precision and wrapping behavior
+ * @returns a function that produces lat/lng tuples from flexible inputs
  */
 export declare function latLngTupleFunction(config?: LatLngTupleFunctionConfig): LatLngTupleFunction;
 /**
- * A lat,lng encoded value.
+ * A lat,lng encoded value as a comma-separated string.
  */
 export type LatLngString = `${Latitude},${Longitude}`;
 /**
  * Default LatLng value as a string.
  */
 export declare const DEFAULT_LAT_LNG_STRING_VALUE = "0,0";
+/**
+ * Returns the default {@link LatLngString} value (`'0,0'`).
+ *
+ * @returns the default lat/lng string
+ */
 export declare function defaultLatLngString(): typeof DEFAULT_LAT_LNG_STRING_VALUE;
+/**
+ * Union type of all accepted input formats for creating a {@link LatLngPoint}: a numeric latitude, a point object, a lat/lng string, or a tuple.
+ */
 export type LatLngPointInput = Latitude | LatLngPoint | LonLatPoint | LatLngString | LatLngTuple | string;
+/**
+ * Precision for lat/lng rounding, expressed as the number of decimal places.
+ */
 export type LatLngPrecision = NumberPrecision;
 /**
- * Creates a LatLngString from the input.
+ * Creates a {@link LatLngString} from the input using the default configuration.
  *
- * @param lat
- * @param lng
+ * @param lat - latitude value or a point input
+ * @param lng - optional longitude when `lat` is a numeric latitude
+ * @returns a comma-separated lat/lng string
  */
 export declare function latLngString(lat: Latitude, lng?: Longitude): LatLngString;
 export declare function latLngString(latLng: LatLngPoint): LatLngString;
 export declare function latLngString(latLng: LatLngString): LatLngString;
+/**
+ * Maximum number of decimal places supported by the lat/lng regex pattern.
+ */
 export declare const LAT_LNG_PATTERN_MAX_PRECISION = 15;
 /**
  * A lat/lng regex with capture groups for lat and lng.
@@ -116,37 +252,38 @@ export declare const LAT_LNG_PATTERN_MAX_PRECISION = 15;
  */
 export declare const LAT_LNG_PATTERN: RegExp;
 /**
- * Checks whether or not the input has the expected pattern.
+ * Checks whether the input string matches the expected lat/lng pattern (e.g., `"30.5,-96.3"`).
  *
- * @param input
+ * @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;
 /**
- * 111KM meter preicison, 0 decimal places
+ * 111KM meter precision, 0 decimal places
  */
 export declare const LAT_LONG_100KM_PRECISION = 0;
 /**
- * 11.1KM meter preicison, 1 decimal place
+ * 11.1KM meter precision, 1 decimal place
  */
 export declare const LAT_LONG_10KM_PRECISION = 1;
 /**
- * 1.11KM meter preicison, 2 decimal places
+ * 1.11KM meter precision, 2 decimal places
  */
 export declare const LAT_LONG_1KM_PRECISION = 2;
 /**
- * 111 meter preicison, 3 decimal places
+ * 111 meter precision, 3 decimal places
  */
 export declare const LAT_LONG_100M_PRECISION = 3;
 /**
- * 11.1 meter preicison, 4 decimal places
+ * 11.1 meter precision, 4 decimal places
  */
 export declare const LAT_LONG_10M_PRECISION = 4;
 /**
- * 001.11 meter preicison, 5 decimal places
+ * 001.11 meter precision, 5 decimal places
  */
 export declare const LAT_LONG_1M_PRECISION = 5;
 /**
- * 011.10 centimeter preicison, 6 decimal places
+ * 011.10 centimeter precision, 6 decimal places
  */
 export declare const LAT_LONG_10CM_PRECISION = 6;
 /**
@@ -170,27 +307,34 @@ export declare const LAT_LONG_GRAINS_OF_SAND_PRECISION = 9;
  */
 export type LatLngPointPrecisionFunction = (latLngPoint: LatLngPoint) => LatLngPoint;
 /**
- * Creates a LatLngPointPrecisionFunction
- * @param precision
- * @returns
+ * 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 a function that rounds points to the given precision
  */
 export declare function latLngPointPrecisionFunction(precision: LatLngPrecision, precisionRounding?: RoundToPrecisionFunctionType): LatLngPointPrecisionFunction;
 /**
- * Converts the input to a LatLngString
+ * Converts various lat/lng input formats into a {@link LatLngString}.
  */
 export type LatLngStringFunction = ((lat: LatLngPointInput, lng?: Longitude) => LatLngString) & ((latLng: string | LatLngString) => LatLngString) & ((latLng: LatLngPoint | LonLatPoint) => LatLngString) & ((lat: Latitude, lng?: Longitude) => LatLngString);
 export type LatLngStringFunctionConfig = LatLngPointFunctionConfig;
 /**
- * Creates a LatLngStringFunction
+ * Creates a {@link LatLngStringFunction} that converts various input formats into comma-separated lat/lng strings,
+ * applying optional precision configuration.
  *
- * @param precision
- * @returns
+ * @param config - optional configuration for precision and wrapping behavior
+ * @returns a function that produces lat/lng strings from flexible inputs
  */
 export declare function latLngStringFunction(config?: LatLngStringFunctionConfig): LatLngStringFunction;
 /**
- * Converts the input to a LatLngPoint
+ * Converts various lat/lng input formats into a {@link LatLngPoint}.
  */
 export type LatLngPointFunction = ((lat: LatLngPointInput, lng?: Longitude) => LatLngPoint) & ((latLng: string | LatLngString) => LatLngPoint) & ((latLng: LatLngPoint | LonLatPoint) => LatLngPoint) & ((lat: Latitude, lng: Longitude) => LatLngPoint);
+/**
+ * Configuration for creating a {@link LatLngPointFunction}.
+ */
 export interface LatLngPointFunctionConfig {
     /**
      * LatLngPrecision to use
@@ -222,33 +366,60 @@ export interface LatLngPointFunctionConfig {
     readLonLatTuples?: boolean;
 }
 /**
- * Creates a LatLngPoint. Uses latLngPointFunction() internally.
+ * 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
- * @param lng
- * @returns
+ * @example
+ * ```ts
+ * const point = latLngPoint(30.59929, -96.38315);
+ * // point.lat === 30.59929, point.lng === -96.38315
+ * ```
  */
 export declare function latLngPoint(lat: LatLngPointInput, lng?: Longitude): LatLngPoint;
 /**
- * Creates a LatLngPointFunction
+ * 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 precision
- * @returns
+ * @example
+ * ```ts
+ * const fn = latLngPointFunction({ precision: 3 });
+ * const result = fn(30.59929, -96.38315);
+ * // result.lat === 30.599, result.lng === -96.383
+ * ```
  */
 export declare function latLngPointFunction(config?: LatLngPointFunctionConfig): LatLngPointFunction;
 /**
- * Creates a LatLngPoint from the input latLng string.
+ * Parses a comma-separated lat/lng string into a {@link LatLngPoint}. Invalid numeric values default to 0.
  *
- * @param latLngString
+ * @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
+ */
 export declare function validLatLngPoint(latLngPoint: LatLngPoint, defaultValue?: Factory<LatLngPoint>): LatLngPoint;
 /**
  * Returns a valid LatLngPoint by validating the input and returns the input value if it is valid, or a default value that is valid.
- *
- * @param latLngPoint
  */
 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
+ */
 export declare function validLatLngPointFunction(defaultValue?: Factory<LatLngPoint>): ValidLatLngPointFunction;
 /**
  * References a latLng using a LatLngPoint
@@ -289,22 +460,44 @@ export type LatLngDataPoint<T> = LatLngPointRef & {
  */
 export type LatLngDataPointFunction<T extends LatLngRef> = (data: T) => LatLngDataPoint<T>;
 /**
- * Creates a LatLngDataPointFunction
+ * Creates a {@link LatLngDataPointFunction} that wraps a {@link LatLngRef} object with its resolved point coordinates.
  *
- * @param precision
- * @returns
+ * @param config - optional configuration for precision and wrapping behavior
+ * @returns a function that produces data points from lat/lng references
  */
 export declare function latLngDataPointFunction<T extends LatLngRef>(config?: LatLngPointFunctionConfig): LatLngDataPointFunction<T>;
+/**
+ * Configuration for {@link randomLatLngFactory}.
+ */
 export interface RandomLatLngFactoryConfig {
+    /**
+     * South-west corner of the bounding box for random generation. Partial values default to the minimum valid coordinates.
+     */
     sw?: Partial<LatLngPoint>;
+    /**
+     * North-east corner of the bounding box for random generation. Partial values default to the maximum valid coordinates.
+     */
     ne?: Partial<LatLngPoint>;
     /**
      * Precision of the LatLng to keep.
      */
     precision?: LatLngPrecision;
 }
+/**
+ * A factory that produces random {@link LatLngPoint} values.
+ */
 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
+ */
 export declare function randomLatLngFactory(config?: RandomLatLngFactoryConfig): RandomLatLngFactory;
+/**
+ * Configuration for {@link randomLatLngFromCenterFactory}.
+ */
 export interface RandomLatLngFromCenterFactoryConfig extends Pick<RandomLatLngFactoryConfig, 'precision'> {
     /**
      * Center from which a rectangle is generated to pick random
@@ -320,9 +513,10 @@ export interface RandomLatLngFromCenterFactoryConfig extends Pick<RandomLatLngFa
     lngDistance: number;
 }
 /**
- * Creates a RandomLatLngFactory that creates a random LatLngPoint value from the center in the given distances.
+ * 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
- * @returns
+ * @param config - center point, distances, and optional precision
+ * @returns a factory that produces random points near the center
  */
 export declare function randomLatLngFromCenterFactory(config: RandomLatLngFromCenterFactoryConfig): RandomLatLngFactory;

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

@@ -1,7 +1,14 @@
 /**
- * Removes any query parameters and hashbang parameters from the input string.
+ * Strips query parameters (`?...`) and hash fragments (`#...`) from a URL string, returning only the base URL.
  *
- * @param url
- * @returns
+ * 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
+ *
+ * @example
+ * ```ts
+ * const base = urlWithoutParameters('https://test.com:1234?test=true');
+ * // base === 'https://test.com:1234'
+ * ```
  */
 export declare function urlWithoutParameters(url: string): string;

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

@@ -3,40 +3,131 @@ import { type PromiseOrValue } from '../promise/promise.type';
 import { type MapFunction } from './map';
 import { type Maybe } from './maybe.type';
 /**
- * A map function with the intent of using the input value, and returning another value.
+ * A MapFunction whose primary intent is to consume (use) the input value, optionally producing an output.
+ * Defaults to void when no output is needed, making it suitable for side-effect-style consumers.
  */
 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
+ *
+ * @example
+ * ```ts
+ * const result = useValue(5, (x) => x * 2);
+ * // result === 10
+ *
+ * const fallback = useValue(undefined, (x: number) => x * 2, 0);
+ * // fallback === 0
+ * ```
+ */
 export declare function useValue<I, O = void>(input: Maybe<I>, use: UseValue<I, O>, defaultValue?: Maybe<GetterOrValue<O>>): Maybe<O>;
+/**
+ * A MappedUseFunction where no mapping step is applied; the input type is used directly.
+ */
 export type UseFunction<I> = MappedUseFunction<I, I>;
+/**
+ * A function that first maps an input of type `A` to type `I`, then applies a {@link UseValue} consumer
+ * to the mapped result. Falls back to a default value when the input is null/undefined.
+ */
 export type MappedUseFunction<A, I> = <O = void>(input: Maybe<A>, use: UseValue<I, O>, defaultValue?: Maybe<GetterOrValue<O>>) => Maybe<O>;
 /**
- * Creates a MappedUseFunction.
+ * 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
+ *
+ * @example
+ * ```ts
+ * const mapFn = (n: number) => String(n);
+ * const mappedUseFn = mappedUseFunction(mapFn);
+ *
+ * const result = mappedUseFn(1, () => 'hello');
+ * // result === 'hello'
+ *
+ * const fallback = mappedUseFn(undefined, () => 'wrong', 'default');
+ * // fallback === 'default'
+ * ```
  */
 export declare function mappedUseFunction<A, I>(map: MapFunction<A, Maybe<I>>): MappedUseFunction<A, I>;
 /**
- * Wraps another MappedUseFunction and maps the input values.
+ * 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
  */
 export declare function wrapUseFunction<A, B, I>(mappedUseFn: MappedUseFunction<A, B>, map: MapFunction<B, Maybe<I>>): MappedUseFunction<A, I>;
 /**
- * Runs a pre-determined function on the input to return a value.
+ * A pre-configured consumer function that accepts an input and returns a value, encapsulating both the
+ * consumer logic and default value in a single callable.
  */
 export type UseContextFunction<I> = <O>(input: Maybe<I>) => Maybe<O>;
 /**
- * Creates a UseContextFunction.
+ * 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
  */
 export declare function useContextFunction<I, O>(use: UseValue<I, O>, defaultValue?: GetterOrValue<O>): UseContextFunction<I>;
 /**
- * A map function with the intent of using the input value, and returning another value as a promise.
+ * Async variant of {@link UseValue} that may return a Promise, allowing asynchronous consumption of values.
  */
 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
+ *
+ * @example
+ * ```ts
+ * const result = await useAsync(1, (x) => Promise.resolve(x * 2));
+ * // result === 2
+ * ```
+ */
 export declare function useAsync<I, O = void>(input: Maybe<I>, use: UseValue<I, O>, defaultValue?: Maybe<GetterOrValue<O>>): Promise<Maybe<O>>;
+/**
+ * A {@link MappedUseAsyncFunction} where no mapping step is applied; the input type is used directly.
+ */
 export type UseAsyncFunction<I> = MappedUseAsyncFunction<I, I>;
+/**
+ * Async variant of {@link MappedUseFunction} that maps, then asynchronously consumes the result.
+ */
 export type MappedUseAsyncFunction<A, I> = <O = void>(input: Maybe<A>, use: UseAsync<I, O>, defaultValue?: Maybe<AsyncGetterOrValue<O>>) => Promise<Maybe<O>>;
 /**
- * Creates a MappedUseFunction.
+ * 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
+ *
+ * @example
+ * ```ts
+ * const mapFn = (n: number) => String(n);
+ * const mappedUseAsyncFn = mappedUseAsyncFunction(mapFn);
+ *
+ * const result = await mappedUseAsyncFn(1, () => Promise.resolve('hello'));
+ * // result === 'hello'
+ * ```
  */
 export declare function mappedUseAsyncFunction<A, I>(map: MapFunction<A, Maybe<PromiseOrValue<Maybe<I>>>>): MappedUseAsyncFunction<A, I>;
 /**
- * Wraps another MappedUseFunction or MappedUseAsyncFunction and maps the input values.
+ * 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
  */
 export declare function wrapUseAsyncFunction<A, B, I>(mappedUsePromiseFn: MappedUseAsyncFunction<A, B>, map: MapFunction<B, Maybe<PromiseOrValue<Maybe<I>>>>): MappedUseAsyncFunction<A, I>;