@dereekb/util 13.11.1 → 13.11.3

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

@@ -48,12 +48,19 @@ export type MaybeIndexRef<T extends IndexRef> = Omit<T, 'i'> & Partial<Pick<T, '
  *
  * @returns a compare function suitable for Array.sort()
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, sort, ascending, factory, ref
+ * @dbxUtilRelated sort-by-index-ascending-compare-function, sort-by-index-range-ascending-compare-function
+ *
  * @example
  * ```ts
  * const items = [{ i: 4 }, { i: 0 }, { i: 2 }];
  * items.sort(sortAscendingIndexNumberRefFunction());
  * // items[0].i === 0
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function sortAscendingIndexNumberRefFunction<T extends IndexRef>(): SortCompareFunction<T>;
 /**
@@ -99,6 +106,12 @@ export type IndexDeltaGroupFunction<T> = (inputItems: T[], previousItems?: Maybe
  * @param readIndex - reads an item's index, returning null/undefined for unindexed items
  * @returns a function that groups items by their index state
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, delta, group, factory, classify
+ * @dbxUtilRelated separate-values, compute-next-free-index-function
+ *
  * @example
  * ```ts
  * const groupFn = indexDeltaGroupFunction<{ x: string; i?: number }>((x) => x.i);
@@ -107,6 +120,7 @@ export type IndexDeltaGroupFunction<T> = (inputItems: T[], previousItems?: Maybe
  * // result.newItems.length === 1     (item without an index)
  * // result.currentItems.length === 2 (items with indexes)
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function indexDeltaGroupFunction<T>(readIndex: ReadMaybeIndexFunction<T>): IndexDeltaGroupFunction<T>;
 /**
@@ -121,8 +135,15 @@ export declare function indexDeltaGroup<T>(readIndex: ReadMaybeIndexFunction<T>,
 /**
  * Creates a SortCompareFunction that sorts items in ascending order using a custom index reader.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, sort, ascending, factory, compare
+ * @dbxUtilRelated sort-ascending-index-number-ref-function, sort-by-index-range-ascending-compare-function
+ *
  * @param readIndex - extracts the index number from each item
  * @returns a compare function suitable for Array.sort()
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function sortByIndexAscendingCompareFunction<T>(readIndex: ReadIndexFunction<T>): SortCompareFunction<T>;
 /**
@@ -139,21 +160,35 @@ export type ComputeNextFreeIndexFunction<T> = (values: T[]) => IndexNumber;
  * @param nextIndex - optional custom function to compute the next index from the max item; defaults to max + 1
  * @returns a function that computes the next free index for a given array
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, free, next, factory, max
+ * @dbxUtilRelated compute-next-free-index-on-sorted-values-function, min-and-max-index-function
+ *
  * @example
  * ```ts
  * const fn = computeNextFreeIndexFunction<IndexRef>((x) => x.i);
  * const nextIndex = fn([{ i: 0 }, { i: 1 }, { i: 5 }]);
  * // nextIndex === 6
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function computeNextFreeIndexFunction<T>(readIndex: ReadIndexFunction<T>, nextIndex?: (value: T) => IndexNumber): ComputeNextFreeIndexFunction<T>;
 /**
  * Creates a {@link ComputeNextFreeIndexFunction} optimized for pre-sorted input arrays.
  * Instead of scanning all items for the maximum, it reads only the last element.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, free, next, sorted, factory, optimized
+ * @dbxUtilRelated compute-next-free-index-function
+ *
  * @param readIndex - extracts the index number from each item
  * @param nextIndex - optional custom function to compute the next index from the last item; defaults to last + 1
  * @returns a function that computes the next free index from sorted arrays
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function computeNextFreeIndexOnSortedValuesFunction<T>(readIndex: ReadIndexFunction<T>, nextIndex?: (value: T) => IndexNumber): ComputeNextFreeIndexFunction<T>;
 /**
@@ -168,12 +203,19 @@ export type MinAndMaxIndexFunction<T> = ((values: Iterable<T>) => MinAndMaxFunct
  * @param readIndex - extracts the index number from each item
  * @returns a function returning the min/max indexes, or null for empty input
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, min, max, factory, range
+ * @dbxUtilRelated min-and-max-index, min-and-max-index-items-function
+ *
  * @example
  * ```ts
  * const fn = minAndMaxIndexFunction<IndexRef>((x) => x.i);
  * const result = fn([{ i: 3 }, { i: 0 }, { i: 5 }]);
  * // result?.min === 0, result?.max === 5
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function minAndMaxIndexFunction<T>(readIndex: ReadIndexFunction<T>): MinAndMaxIndexFunction<T>;
 /**
@@ -194,8 +236,15 @@ export type MinAndMaxIndexItemsFunction<T> = MinAndMaxFunction<T> & {
  * Creates a {@link MinAndMaxIndexItemsFunction} that returns the actual items (not just index numbers)
  * with the minimum and maximum index values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, min, max, items, factory
+ * @dbxUtilRelated min-and-max-index-function, min-and-max-function
+ *
  * @param readIndex - extracts the index number from each item
  * @returns a function returning the min/max items, or null for empty input
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function minAndMaxIndexItemsFunction<T>(readIndex: ReadIndexFunction<T>): MinAndMaxIndexItemsFunction<T>;
 /**
@@ -246,6 +295,14 @@ export type FindBestIndexMatchFunction<T> = <I extends IndexRef>(value: I) => T;
  * fn({ i: 6 });  // returns { i: 5 }
  * fn({ i: 11 }); // returns { i: 10 }
  * ```
+ *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, match, find, factory, lookup
+ * @dbxUtilRelated find-best-index-match, safe-find-best-index-match
+ *
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function findBestIndexMatchFunction<T extends IndexRef>(items: Iterable<T>): FindBestIndexMatchFunction<T>;
 /**
@@ -292,8 +349,15 @@ export type ReadIndexRangeFunction<T> = FactoryWithRequiredInput<IndexRange, T>;
  * Creates a SortCompareFunction that sorts items by their IndexRange in ascending order.
  * Sorts by minIndex first, then by maxIndex for items with equal minIndex values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index-range, sort, ascending, factory, compare
+ * @dbxUtilRelated sort-by-index-ascending-compare-function, index-range-reader-pair-factory
+ *
  * @param readIndexRange - extracts the IndexRange from each item
  * @returns a compare function suitable for Array.sort()
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function sortByIndexRangeAscendingCompareFunction<T>(readIndexRange: ReadIndexRangeFunction<T>): SortCompareFunction<T>;
 /**
@@ -310,8 +374,15 @@ export type IndexRangeReaderPairFactory<T> = FactoryWithRequiredInput<IndexRange
 /**
  * Creates a new {@link IndexRangeReaderPairFactory} that pairs each value with its computed IndexRange.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index-range, pair, factory, reader
+ * @dbxUtilRelated sort-by-index-range-ascending-compare-function
+ *
  * @param reader - reads the IndexRange from the input value
  * @returns a factory that creates IndexRangeReaderPair instances
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function indexRangeReaderPairFactory<T>(reader: ReadIndexRangeFunction<T>): IndexRangeReaderPairFactory<T>;
 /**
@@ -334,8 +405,15 @@ export type FitToIndexRangeFunction = (input: IndexNumber) => IndexNumber;
 /**
  * Creates a {@link FitToIndexRangeFunction} that clamps index numbers to the given range boundaries.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, clamp, range, factory, fit
+ * @dbxUtilRelated wrap-index-range-function, bound-number-function
+ *
  * @param input - the range to clamp to
  * @returns a function that clamps any index to the range
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function fitToIndexRangeFunction(input: IndexRange): FitToIndexRangeFunction;
 /**
@@ -350,12 +428,19 @@ export type WrapIndexNumberFunction = WrapNumberFunction;
  * @param fencePosts - whether to use fencepost semantics (maxIndex is exclusive); defaults to true
  * @returns a function that wraps any index into the range
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, wrap, range, factory, modular
+ * @dbxUtilRelated fit-to-index-range-function, wrap-number-function
+ *
  * @example
  * ```ts
  * const wrap = wrapIndexRangeFunction({ minIndex: 0, maxIndex: 6 });
  * wrap(6);  // 0 (wraps from positive side)
  * wrap(-1); // 5 (wraps from negative side)
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function wrapIndexRangeFunction(input: IndexRange, fencePosts?: boolean): WrapIndexNumberFunction;
 /**
@@ -373,9 +458,16 @@ export declare function indexRangeCheckReaderFunction<T extends IndexRef>(input:
 /**
  * Creates an {@link IndexRefRangeCheckFunction} that reads an item's index using a custom reader and checks whether it falls within the specified range.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, range, check, factory, predicate
+ * @dbxUtilRelated index-range-check-function, is-index-number-in-index-range-function
+ *
  * @param input - the range or range config to check against
  * @param read - custom function to extract the index from the item
  * @returns a function that checks whether an item's index is within the range
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function indexRangeCheckReaderFunction<T>(input: IndexRangeFunctionInput, read: ReadIndexFunction<T>): IndexRefRangeCheckFunction<T>;
 /**
@@ -409,8 +501,15 @@ export declare function asIndexRangeCheckFunctionConfig(input: IndexRangeFunctio
  * Creates an {@link IndexRangeCheckFunction} that tests whether an index number falls within the configured range.
  * The min is inclusive and the max is exclusive by default unless `inclusiveMaxIndex` is set.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, range, check, factory, predicate
+ * @dbxUtilRelated index-range-check-reader-function, is-index-number-in-index-range-function
+ *
  * @param input - the range or range config to check against
  * @returns a predicate function for index numbers
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function indexRangeCheckFunction(input: IndexRangeFunctionInput): IndexRangeCheckFunction;
 /**
@@ -429,8 +528,15 @@ export declare function isIndexNumberInIndexRange(index: IndexNumber, indexRange
 /**
  * Creates an {@link IsIndexNumberInIndexRangeFunction} bound to the given range configuration.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, range, check, factory, predicate
+ * @dbxUtilRelated is-index-number-in-index-range, index-range-check-function
+ *
  * @param input - the range or range config to bind
  * @returns a predicate that tests index numbers against the bound range
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function isIndexNumberInIndexRangeFunction(input: IndexRangeFunctionInput): IsIndexNumberInIndexRangeFunction;
 /**
@@ -448,8 +554,15 @@ export declare function isIndexRangeInIndexRange(compareIndexRange: IndexRange,
 /**
  * Creates an {@link IsIndexRangeInIndexRangeFunction} bound to the given range configuration.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index-range, contains, decision, factory, predicate
+ * @dbxUtilRelated is-index-range-in-index-range, index-range-overlaps-index-range-function
+ *
  * @param input - the bounding range or range config to bind
  * @returns a predicate that tests whether index ranges are fully contained
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function isIndexRangeInIndexRangeFunction(input: IndexRangeFunctionInput): IsIndexRangeInIndexRangeFunction;
 /**
@@ -467,8 +580,15 @@ export declare function indexRangeOverlapsIndexRange(compareIndexRange: IndexRan
 /**
  * Creates an {@link IndexRangeOverlapsIndexRangeFunction} bound to the given range configuration.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index-range, overlap, decision, factory, predicate
+ * @dbxUtilRelated is-index-range-in-index-range-function, index-range-check-function
+ *
  * @param input - the reference range or range config to bind
  * @returns a predicate that tests for overlap with the bound range
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function indexRangeOverlapsIndexRangeFunction(input: IndexRangeFunctionInput): IndexRangeOverlapsIndexRangeFunction;
 /**
@@ -514,8 +634,15 @@ export type StepsFromIndexFunction = ((startIndex: number, wrapAround?: boolean,
  * Creates a {@link StepsFromIndexFunction} that computes the next index after stepping from a start position.
  * Returns undefined when the result falls outside the range (unless wrapping or fitting is enabled).
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, index, step, range, factory, wrap, navigation
+ * @dbxUtilRelated wrap-index-range-function, fit-to-index-range-function
+ *
  * @param config - stepping behavior configuration
  * @returns a function that computes the stepped index
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function stepsFromIndexFunction(config: StepsFromIndexFunctionConfig): StepsFromIndexFunction;
 /**

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

@@ -33,6 +33,7 @@ export type ReadValueFunction<I, O> = MapFunction<I, O>;
  * maybeDouble(undefined); // undefined
  * maybeDouble(null);      // null
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function mapMaybeFunction<I, O>(mapFunction: MapFunction<I, O>): MapFunction<Maybe<I>, Maybe<O>>;
 /**
@@ -66,6 +67,7 @@ export type ApplyMapFunctionWithOptions<I, O, C> = (input: I, target?: Maybe<Par
  *
  * @param mapFunction - per-element transformation
  * @returns a function that maps entire arrays
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function mapArrayFunction<I, O>(mapFunction: MapFunction<I, O>): MapArrayFunction<MapFunction<I, O>>;
 /**
@@ -87,14 +89,26 @@ export declare const MAP_IDENTITY: <T>(input: T) => T;
 /**
  * Returns the shared {@link MAP_IDENTITY} function cast to the requested type, useful for providing a typed no-op transformation.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilTags map, identity, no-op, typed
+ * @dbxUtilRelated map-identity, is-map-identity-function
+ *
  * @returns the singleton identity function typed as `MapFunction<T, T>`
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function mapIdentityFunction<T>(): MapFunction<T, T>;
 /**
  * Checks whether the given function is the singleton {@link MAP_IDENTITY} reference.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilTags map, identity, type-guard, sentinel
+ * @dbxUtilRelated map-identity, map-identity-function
+ *
  * @param fn - the function to check
  * @returns `true` if the function is the identity singleton
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function isMapIdentityFunction(fn: unknown): fn is typeof MAP_IDENTITY;
 /**
@@ -156,6 +170,8 @@ export declare function mapFunctionOutput<O extends object, I = unknown>(output:
  * const result = fnChain('aaaab');
  * // result === 'aaaab'
  * ```
+ *
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function chainMapSameFunctions<I>(input: ArrayOrValue<Maybe<MapSameFunction<I>>>): MapSameFunction<I>;
 /**
@@ -164,10 +180,16 @@ export declare function chainMapSameFunctions<I>(input: ArrayOrValue<Maybe<MapSa
  * If `apply` is false, or `b` is null/undefined, returns `a` unchanged. This conditional chaining
  * is useful when a second transform step is optional.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilTags map, chain, compose, pipeline, transform
+ * @dbxUtilRelated chain-map-same-functions, map-identity-function
+ *
  * @param a - the first map function
  * @param b - the optional second map function to chain after `a`
  * @param apply - when false, skips chaining and returns `a` directly
  * @returns a composed function piping `a` into `b`, or `a` alone if `b` is absent or `apply` is false
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function chainMapFunction<I>(a: MapSameFunction<I>, b: Maybe<MapSameFunction<I>>): MapSameFunction<I>;
 export declare function chainMapFunction<I>(a: MapSameFunction<I>, b: Maybe<MapSameFunction<I>>, apply?: boolean): MapSameFunction<I>;

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

@@ -1,4 +1,4 @@
-import { type NonNever } from 'ts-essentials';
+import { type OmitNeverProperties } from 'ts-essentials';
 /**
  * A null/undefined value.
  */
@@ -18,6 +18,6 @@ export type MaybeSoStrict<T> = T extends Maybe<infer A> ? (A extends Maybe<infer
 /**
  * Turns all key values in an object into a Maybe value.
  */
-export type MaybeMap<T extends object> = NonNever<{
+export type MaybeMap<T extends object> = OmitNeverProperties<{
     [K in keyof T]: T[K] extends MaybeNot ? never : Maybe<T[K]>;
 }>;

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

@@ -110,6 +110,13 @@ export declare function removeModifiers<T>(modifiers: ArrayOrValue<Modifier<T>>,
  * fn(obj);
  * // 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>;
 /**
@@ -117,8 +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".
  *
+ * @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>>;
 /**

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

@@ -217,8 +217,15 @@ export type LatLngTupleFunctionConfig = LatLngPointFunctionConfig;
  * Creates a {@link LatLngTupleFunction} that converts various input formats into `[lat, lng]` tuples,
  * applying optional precision configuration.
  *
+ * @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;
 /**
@@ -324,9 +331,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.
  *
+ * @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;
 /**
@@ -338,8 +352,15 @@ export type LatLngStringFunctionConfig = LatLngPointFunctionConfig;
  * Creates a {@link LatLngStringFunction} that converts various input formats into comma-separated lat/lng strings,
  * applying optional precision configuration.
  *
+ * @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;
 /**
@@ -401,12 +422,19 @@ export declare function latLngPoint(lat: LatLngPointInput, lng?: Longitude): Lat
  * @returns a function that produces points from flexible inputs
  * @throws {Error} when the input cannot be parsed into a valid point
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, lat-lng, point, factory, geographic, normalize
+ * @dbxUtilRelated lat-lng-point, lat-lng-tuple-function, lat-lng-string-function, lat-lng-point-precision-function
+ *
  * @example
  * ```ts
  * const fn = latLngPointFunction({ precision: 3 });
  * 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;
 /**
@@ -431,8 +459,15 @@ export type ValidLatLngPointFunction = (latLngPoint: LatLngPoint) => LatLngPoint
 /**
  * Creates a {@link ValidLatLngPointFunction} that returns the input point when valid, or a default point otherwise.
  *
+ * @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;
 /**
@@ -476,8 +511,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.
  *
+ * @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>;
 /**
@@ -505,8 +547,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.
  *
+ * @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;
 /**
@@ -530,7 +579,14 @@ export interface RandomLatLngFromCenterFactoryConfig extends Pick<RandomLatLngFa
  * Creates a {@link RandomLatLngFactory} that generates random points within a rectangle
  * centered on the given point, extending by `latDistance` and `lngDistance` in each direction.
  *
+ * @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/use.d.ts

@@ -53,15 +53,30 @@ export type MappedUseFunction<A, I> = <O = void>(input: Maybe<A>, use: UseValue<
  * const fallback = mappedUseFn(undefined, () => 'wrong', 'default');
  * // 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>;
 /**
  * Wraps an existing {@link MappedUseFunction} with an additional mapping step, allowing further transformation
  * of the intermediate value before it reaches the consumer.
  *
+ * @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>;
 /**
@@ -73,9 +88,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.
  *
+ * @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>;
 /**
@@ -120,14 +142,29 @@ export type MappedUseAsyncFunction<A, I> = <O = void>(input: Maybe<A>, use: UseA
  * const result = await mappedUseAsyncFn(1, () => Promise.resolve('hello'));
  * // 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>;
 /**
  * Wraps an existing {@link MappedUseAsyncFunction} with an additional async-capable mapping step,
  * allowing further transformation of the intermediate value before it reaches the consumer.
  *
+ * @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

@@ -42,12 +42,19 @@ export type VectorResizeFunction = (input: Vector) => Vector;
  * @param minSize - the minimum dimensions to enforce
  * @returns a resize function that clamps each axis to the specified minimum
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, vector, resize, minimum, factory, clamp
+ * @dbxUtilRelated vector
+ *
  * @example
  * ```ts
  * const resize = vectorMinimumSizeResizeFunction({ x: 5 });
  * resize({ x: 3, y: 10 });
  * // { x: 5, y: 10 }
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function vectorMinimumSizeResizeFunction(minSize: Partial<Vector>): VectorResizeFunction;
 /**

package/test/index.cjs.js

@@ -1090,8 +1090,9 @@ function _ts_generator(thisArg, body) {
 /**
  * Throws an {@link ExpectedFailError} to signal that a test reached the expected failure point.
  *
- * Used within {@link shouldFail} or {@link expectSuccessfulFail} to indicate that the expected
- * error path was taken successfully.
+ * Must be called inside {@link shouldFail} (typically via {@link itShouldFail}) or {@link expectSuccessfulFail},
+ * which catch `ExpectedFailError` and convert it into a passing test. Calling it inside a plain
+ * `it()` block causes the test to fail because the error propagates uncaught.
  *
  * @param message - optional error message
  */ function failSuccessfully(message) {
@@ -1170,11 +1171,23 @@ function _ts_generator(thisArg, body) {
     };
 }
 /**
- * Function that expects any failure to be thrown, then throws an ExpectedFailError.
+ * Function that expects any failure to be thrown, then throws an {@link ExpectedFailError}.
+ *
+ * Intended to be used inside {@link itShouldFail} or {@link shouldFail}, which catch the
+ * `ExpectedFailError` and treat it as a passing test. When used inside a plain `it()` block
+ * the thrown `ExpectedFailError` propagates and fails the test even though `errorFn` rejected
+ * as expected — for that case use vitest's `await expect(...).rejects.toThrow(...)` instead.
  *
  * @param errorFn - function expected to throw an error (sync or async)
  * @param assertFailType - optional assertion to validate the type or content of the thrown error
- * @returns a promise that resolves when the expected failure is verified
+ * @returns a promise that rejects with {@link ExpectedFailError} when the expected failure is verified, or with {@link UnexpectedSuccessFailureError} when `errorFn` resolves successfully
+ *
+ * @example
+ * ```ts
+ * itShouldFail('when the user is not authorized', async () => {
+ *   await expectFail(() => callProtectedEndpoint(), expectFailAssertHttpErrorServerErrorCode(403));
+ * });
+ * ```
  */ function expectFail(errorFn, assertFailType) {
     function handleError(e) {
         if (_instanceof(e, UnexpectedSuccessFailureError)) {