@dereekb/util 13.3.1 → 13.4.1

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

@@ -10,11 +10,17 @@ import { type Maybe } from '../value/maybe.type';
  * I.E. http, https, etc.
  */
 export type WebsiteProtocol = string;
-/** The HTTP protocol string literal type. */
+/**
+ * The HTTP protocol string literal type.
+ */
 export type HttpWebsiteProtocol = 'http';
-/** The HTTPS protocol string literal type. */
+/**
+ * The HTTPS protocol string literal type.
+ */
 export type HttpsWebsiteProtocol = 'https';
-/** Known HTTP protocols: `"http"` or `"https"`. */
+/**
+ * Known HTTP protocols: `"http"` or `"https"`.
+ */
 export type KnownHttpWebsiteProtocol = HttpWebsiteProtocol | HttpsWebsiteProtocol;
 /**
  * Returns true if the input string is a known HTTP protocol (`"http"` or `"https"`).
@@ -147,27 +153,49 @@ export declare function isWebsiteUrl(input: string): input is WebsiteUrl;
  * Detailed analysis of whether an input string is a valid website URL, including its parsed components.
  */
 export interface WebsiteUrlDetails {
-    /** The original input string. */
+    /**
+     * The original input string.
+     */
     readonly input: string;
-    /** Whether the input is a valid website URL. */
+    /**
+     * Whether the input is a valid website URL.
+     */
     readonly isWebsiteUrl: boolean;
-    /** Whether the input has an `http://` or `https://` prefix. */
+    /**
+     * Whether the input has an `http://` or `https://` prefix.
+     */
     readonly hasHttpPrefix: boolean;
-    /** Whether the input contains a website domain. */
+    /**
+     * Whether the input contains a website domain.
+     */
     readonly hasWebsiteDomain: boolean;
-    /** Whether the input contains a port number. */
+    /**
+     * Whether the input contains a port number.
+     */
     readonly hasPortNumber: boolean;
-    /** The port number, or `undefined` if none is present. */
+    /**
+     * The port number, or `undefined` if none is present.
+     */
     readonly portNumber: PortNumber | undefined;
-    /** The domain and path split pair. */
+    /**
+     * The domain and path split pair.
+     */
     readonly splitPair: WebsiteDomainAndPathPair;
-    /** The extracted domain. */
+    /**
+     * The extracted domain.
+     */
     readonly domain: WebsiteDomain;
-    /** The full website path including query string. */
+    /**
+     * The full website path including query string.
+     */
     readonly websitePath: WebsitePath;
-    /** The path portion without query parameters. */
+    /**
+     * The path portion without query parameters.
+     */
     readonly path: string;
-    /** The query string portion, or undefined if none. */
+    /**
+     * The query string portion, or undefined if none.
+     */
     readonly query: string | undefined;
 }
 /**
@@ -286,9 +314,13 @@ export declare function isolateWebsitePathFunction(config?: IsolateWebsitePathFu
  * A pair containing the path and optional query string components of a website URL.
  */
 export interface WebsitePathAndQueryPair {
-    /** The path portion of the URL (before the `?`). */
+    /**
+     * The path portion of the URL (before the `?`).
+     */
     path: WebsitePath;
-    /** The query string portion of the URL (including the leading `?`), if present. */
+    /**
+     * The query string portion of the URL (including the leading `?`), if present.
+     */
     query?: Maybe<WebsiteQueryString>;
 }
 /**
@@ -333,9 +365,13 @@ export declare function websitePathFromWebsiteDomainAndPath(input: WebsiteDomain
  * A pair containing the domain and path components of a website URL.
  */
 export interface WebsiteDomainAndPathPair {
-    /** The domain portion of the URL. */
+    /**
+     * The domain portion of the URL.
+     */
     domain: WebsiteDomain;
-    /** The path portion of the URL. */
+    /**
+     * The path portion of the URL.
+     */
     path: WebsitePath;
 }
 /**
@@ -402,7 +438,9 @@ export declare function hasHttpPrefix(input: string): input is BaseWebsiteUrl;
  * Object representation of a `mailto:` URL.
  */
 export interface MailToUrl {
-    /** The email address for the mailto link. */
+    /**
+     * The email address for the mailto link.
+     */
     email: string;
 }
 /**

package/src/lib/tree/tree.d.ts

@@ -7,13 +7,21 @@
  *             which is suitable for basic trees but can be overridden for custom node types.
  */
 export interface TreeNode<T, N extends TreeNode<T, N> = TreeNode<T, any>> {
-    /** The depth of the node in the tree. The root node has a depth of 0. */
+    /**
+     * The depth of the node in the tree. The root node has a depth of 0.
+     */
     depth: number;
-    /** The value associated with this tree node. */
+    /**
+     * The value associated with this tree node.
+     */
     value: T;
-    /** A reference to the parent node, or undefined if this is the root node. */
+    /**
+     * A reference to the parent node, or undefined if this is the root node.
+     */
     parent?: N;
-    /** An array of child nodes, or undefined if this node has no children. */
+    /**
+     * An array of child nodes, or undefined if this node has no children.
+     */
     children?: N[];
 }
 /**

package/src/lib/tree/tree.flatten.d.ts

@@ -104,6 +104,7 @@ export declare function flattenTreeToArrayFunction<N extends TreeNode<unknown>>(
  * Creates a FlattenTreeFunction that flattens tree nodes themselves into an array.
  *
  * @template N The type of the tree node.
+ * @param config - configuration object with optional mapping and node filtering settings
  * @returns A FlattenTreeFunction that collects nodes of type N.
  */
 export declare function flattenTreeToArrayFunction<N extends TreeNode<unknown, N>, V>(config: FlattenTreeToArrayFunctionConfig<N, V>): FlattenTreeFunction<N, V>;
@@ -112,7 +113,8 @@ export declare function flattenTreeToArrayFunction<N extends TreeNode<unknown, N
  *
  * @template N The type of the tree node.
  * @template V The type of the value to map each node to.
- * @param mapNodeFn An optional function to transform each node N into a value V. If not provided, nodes are returned as is.
+ * @param mapNodeFn - optional function to transform each node N into a value V; if not provided, nodes are returned as-is
+ * @param defaultAddNodeFn - optional decision function that filters which nodes are included in the result
  * @returns A FlattenTreeFunction that collects values of type V.
  */
 export declare function flattenTreeToArrayFunction<N extends TreeNode<unknown, N>, V>(mapNodeFn?: (node: N) => V, defaultAddNodeFn?: Maybe<FlattenTreeAddNodeDecisionFunction<N, V>>): FlattenTreeFunction<N, V>;

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

@@ -31,15 +31,25 @@ export type ZipCodeString = string;
  * Basic US address with two address lines, city, state, and zip code.
  */
 export interface UnitedStatesAddress {
-    /** Primary street address line. */
+    /**
+     * Primary street address line.
+     */
     line1: AddressLineString;
-    /** Secondary address line (apartment, suite, etc.). */
+    /**
+     * Secondary address line (apartment, suite, etc.).
+     */
     line2?: AddressLineString;
-    /** City name. */
+    /**
+     * City name.
+     */
     city: CityString;
-    /** State name or two-letter state code. */
+    /**
+     * State name or two-letter state code.
+     */
     state: StateString | StateCodeString;
-    /** Postal/zip code. */
+    /**
+     * Postal/zip code.
+     */
     zip: ZipCodeString;
 }
 /**
@@ -47,9 +57,13 @@ export interface UnitedStatesAddress {
  * such as a recipient name and phone number.
  */
 export interface UnitedStatesAddressWithContact extends UnitedStatesAddress {
-    /** Contact name associated with this address. */
+    /**
+     * Contact name associated with this address.
+     */
     name?: string;
-    /** Phone number associated with this address. */
+    /**
+     * Phone number associated with this address.
+     */
     phone?: string;
 }
 /**
@@ -60,6 +74,7 @@ export interface UnitedStatesAddressWithContact extends UnitedStatesAddress {
  *
  * @param input - the address to format
  * @param addLinebreaks - whether to join parts with newlines (default `true`) or concatenate them directly
+ * @returns the formatted address string, or `undefined` if no meaningful parts are present
  */
 export declare function unitedStatesAddressString(input: Maybe<Partial<UnitedStatesAddress | UnitedStatesAddressWithContact>>, addLinebreaks?: boolean): Maybe<string>;
 /**
@@ -68,6 +83,7 @@ export declare function unitedStatesAddressString(input: Maybe<Partial<UnitedSta
  * Useful for validating an address before submission or display.
  *
  * @param input - the address to validate
+ * @returns `true` if all required fields (line1, city, state, zip) are populated
  *
  * @example
  * ```ts
@@ -95,6 +111,7 @@ export declare const US_STATE_CODE_STRING_REGEX: RegExp;
  * Only matches uppercase codes; lowercase input returns `false`.
  *
  * @param input - the string to test
+ * @returns `true` if the input matches a valid US state or territory code
  *
  * @example
  * ```ts

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

@@ -26,6 +26,9 @@ export interface LatLngBound {
 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.
+ *
+ * @param input - value to test
+ * @returns `true` if the input has `sw` and `ne` properties, indicating a bound
  */
 export declare function isLatLngBound(input: LatLngBound | unknown): input is LatLngBound;
 /**

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

@@ -28,6 +28,9 @@ export interface BuildConfig<T extends object> {
  * 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
+ * @param config.base - optional pre-existing partial object to build upon; defaults to an empty object
+ * @param config.build - function that mutates the base object to populate it with desired values
+ * @returns the fully constructed object of type T
  *
  * @example
  * ```ts

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

@@ -12,6 +12,7 @@ export type EqualityComparatorFunction<T> = (a: T, b: T) => boolean;
  * but `null === undefined` is `false`.
  *
  * @param compare - the comparator to wrap
+ * @returns a new comparator that handles nullish values safely before delegating to the wrapped comparator
  *
  * @example
  * ```ts
@@ -31,6 +32,7 @@ export declare function safeEqualityComparatorFunction<T>(compare: EqualityCompa
  * @param a - first value to compare
  * @param b - second value to compare
  * @param compare - the equality comparator for non-nullish values
+ * @returns `true` if the values are considered equal
  *
  * @example
  * ```ts
@@ -67,6 +69,7 @@ export type CompareEqualityWithValueFromItemsFunction<I, V> = ((a: Maybe<I>, b:
  *
  * @param readValues - extracts the comparable value from each item
  * @param equalityComparator - compares the extracted values for equality
+ * @returns a function that compares two items by their extracted values
  */
 export declare function compareEqualityWithValueFromItemsFunction<I, V>(readValues: ReadValueFunction<I, V>, equalityComparator: EqualityComparatorFunction<V>): CompareEqualityWithValueFromItemsFunction<I, V>;
 /**
@@ -80,6 +83,7 @@ export type CompareEqualityWithValueFromItemsFunctionFactory<I, V> = ((equalityC
  * with varying comparison strategies.
  *
  * @param readValues - extracts the comparable value from each item
+ * @returns a factory function that accepts an equality comparator and produces a comparison function
  *
  * @example
  * ```ts

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

@@ -11,6 +11,7 @@ export type CronExpression = string;
  * every 1 hour at minute 30), which means intervals won't be exactly N minutes apart.
  *
  * @param inputMinutes - interval in minutes between executions
+ * @returns a cron expression string that approximates the requested interval
  *
  * @example
  * ```ts

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

@@ -19,6 +19,7 @@ export type DecisionFunctionFactory<C, I> = FactoryWithRequiredInput<DecisionFun
  * Useful for providing a constant decision where a function is expected.
  *
  * @param decision - the constant boolean value to return
+ * @returns a decision function that always returns the given boolean
  *
  * @example
  * ```ts
@@ -50,6 +51,7 @@ export declare const invertDecision: <F extends DecisionFunction<any>>(fn: F, in
  *
  * @param valueOrFunction - a boolean, decision function, or undefined
  * @param defaultIfUndefined - fallback boolean when the input is nullish (defaults to true)
+ * @returns a {@link DecisionFunction} derived from the input
  *
  * @example
  * ```ts
@@ -68,6 +70,7 @@ export declare function asDecisionFunction<T = unknown>(valueOrFunction: Maybe<b
  * concrete value or a custom decision function interchangeably.
  *
  * @param equalityValue - the value to compare against, or an existing decision function
+ * @returns a decision function that checks strict equality with the given value
  *
  * @example
  * ```ts

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

@@ -16,6 +16,7 @@ export type AreEqualContext<T = unknown> = (x: IterableOrValue<T>) => boolean;
  *
  * @param contextValue - the reference value to compare against
  * @param fn - the equality comparator
+ * @returns a function that checks whether a given value equals the captured reference
  *
  * @example
  * ```ts
@@ -35,6 +36,7 @@ export declare function isEqualContext<T>(contextValue: T, fn: EqualityComparato
  *
  * @param contextValue - the reference value to compare against
  * @param fn - the equality comparator
+ * @returns a function that checks whether all input values equal the captured reference
  *
  * @example
  * ```ts
@@ -54,6 +56,7 @@ export declare function areEqualContext<T>(contextValue: T, fn: EqualityComparat
  *
  * @param values - the values to compare
  * @param fn - the equality comparator
+ * @returns `true` if all values are equal to each other, or if fewer than two values are provided
  *
  * @example
  * ```ts

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

@@ -363,11 +363,15 @@ export type IndexRefRangeCheckFunction<T> = (value: T) => boolean;
  * within the specified range. For IndexRef types, the index is read from `i` automatically.
  *
  * @param input - the range or range config to check against
+ * @returns a function that checks whether an item's index is within the range
  */
 export declare function indexRangeCheckReaderFunction<T extends IndexRef>(input: IndexRangeFunctionInput): IndexRefRangeCheckFunction<T>;
 /**
+ * Creates an {@link IndexRefRangeCheckFunction} that reads an item's index using a custom reader and checks whether it falls within the specified range.
+ *
  * @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
  */
 export declare function indexRangeCheckReaderFunction<T>(input: IndexRangeFunctionInput, read: ReadIndexFunction<T>): IndexRefRangeCheckFunction<T>;
 /**

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

@@ -17,6 +17,7 @@ export interface LabeledValue<T> extends LabelRef {
  * Enables fast lookup of labeled items by their value key.
  *
  * @param values - array of labeled values to index
+ * @returns a Map keyed by each item's value for fast lookup
  *
  * @example
  * ```ts

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

@@ -61,14 +61,22 @@ export declare function mapArrayFunction<I, O>(mapFunction: MapFunction<I, O>):
  *
  * Used as a sentinel value so that {@link chainMapSameFunctions} and other combinators can detect
  * and skip no-op mappings for efficiency.
+ *
+ * @param input - the value to pass through unchanged
+ * @returns the same input value, unmodified
  */
 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.
+ *
+ * @returns the singleton identity function typed as `MapFunction<T, T>`
  */
 export declare function mapIdentityFunction<T>(): MapFunction<T, T>;
 /**
  * Checks whether the given function is the singleton {@link MAP_IDENTITY} reference.
+ *
+ * @param fn - the function to check
+ * @returns `true` if the function is the identity singleton
  */
 export declare function isMapIdentityFunction(fn: unknown): fn is typeof MAP_IDENTITY;
 /**
@@ -136,6 +144,7 @@ export declare function chainMapSameFunctions<I>(input: ArrayOrValue<Maybe<MapSa
  * @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
  */
 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.d.ts

@@ -3,6 +3,7 @@ import { type Maybe, type MaybeNot, type MaybeSo } from './maybe.type';
  * Type guard that returns `true` if the value is not `null` or `undefined`.
  *
  * @param value - the value to check
+ * @returns `true` if the value is not `null` or `undefined`
  */
 export declare function hasNonNullValue<T = unknown>(value: Maybe<T>): value is MaybeSo<T>;
 /**
@@ -15,6 +16,7 @@ export declare function hasNonNullValue<T = unknown>(value: Maybe<T>): value is
  * NaN has undefined behavior.
  *
  * @param value - the value to check
+ * @returns `true` if the value is non-nullish and not empty
  */
 export declare function hasValueOrNotEmpty<T = unknown>(value: Maybe<T>): value is MaybeSo<T>;
 /**
@@ -26,12 +28,14 @@ export declare function hasValueOrNotEmpty<T = unknown>(value: Maybe<T>): value
  * NaN has undefined behavior.
  *
  * @param value - the value to check
+ * @returns `true` if the value is non-nullish, non-empty, and not an empty object
  */
 export declare function hasValueOrNotEmptyObject<T = unknown>(value: Maybe<T>): value is MaybeSo<T>;
 /**
  * Returns `true` if the input value is a non-empty string or is `true`.
  *
  * @param value - the value to check
+ * @returns `true` if the value is a non-empty string or is `true`
  */
 export declare function isStringOrTrue(value: Maybe<string | boolean>): boolean;
 /**
@@ -40,12 +44,14 @@ export declare function isStringOrTrue(value: Maybe<string | boolean>): boolean;
  * Useful for filtering out both nullish values and empty strings in a single check.
  *
  * @param value - the value to check
+ * @returns `true` if the value is not nullish and not an empty string
  */
 export declare function isNotNullOrEmptyString<T>(value: Maybe<MaybeNot | '' | T>): value is MaybeSo<T>;
 /**
  * Type guard that returns `true` if the input is `null` or `undefined`.
  *
  * @param value - the value to check
+ * @returns `true` if the value is `null` or `undefined`
  */
 export declare function isMaybeNot<T = unknown>(value: Maybe<T>): value is MaybeNot;
 /**
@@ -54,6 +60,7 @@ export declare function isMaybeNot<T = unknown>(value: Maybe<T>): value is Maybe
  * Equivalent to {@link hasNonNullValue} but with the `MaybeSo` narrowing type.
  *
  * @param value - the value to check
+ * @returns `true` if the value is neither `null` nor `undefined`
  */
 export declare function isMaybeSo<T>(value: Maybe<T>): value is MaybeSo<T>;
 /**
@@ -62,18 +69,21 @@ export declare function isMaybeSo<T>(value: Maybe<T>): value is MaybeSo<T>;
  * Useful for optional boolean flags where both absence and `true` indicate the same behavior.
  *
  * @param value - the value to check
+ * @returns `true` if the value is nullish or strictly `true`
  */
 export declare function isMaybeNotOrTrue<T = unknown>(value: Maybe<T | true>): value is MaybeNot | true;
 /**
  * Returns `true` if the input is not `null`, `undefined`, or `false`.
  *
  * @param value - the value to check
+ * @returns `true` if the value is not `null`, `undefined`, or `false`
  */
 export declare function isDefinedAndNotFalse<T = unknown>(value: Maybe<T>): boolean;
 /**
  * Returns `true` if the input is not strictly `false`. Nullish values return `true`.
  *
  * @param value - the value to check
+ * @returns `true` if the value is not strictly `false`
  */
 export declare function isNotFalse<T = unknown>(value: Maybe<T>): boolean;
 /**
@@ -81,6 +91,7 @@ export declare function isNotFalse<T = unknown>(value: Maybe<T>): boolean;
  *
  * @param a - first value
  * @param b - second value
+ * @returns `true` if both values are non-nullish and strictly equal
  */
 export declare function isSameNonNullValue<T>(a: Maybe<T>, b: Maybe<T>): a is NonNullable<T>;
 /**
@@ -90,6 +101,7 @@ export declare function isSameNonNullValue<T>(a: Maybe<T>, b: Maybe<T>): a is No
  *
  * @param a - first value
  * @param b - second value
+ * @returns `true` if both are nullish or both are the same value
  */
 export declare function valuesAreBothNullishOrEquivalent<T>(a: Maybe<T>, b: Maybe<T>): boolean;
 /**
@@ -101,5 +113,6 @@ export declare function valuesAreBothNullishOrEquivalent<T>(a: Maybe<T>, b: Mayb
  *
  * @param a - the current value
  * @param b - the update value
+ * @returns `a` if `b` is undefined, otherwise `b`
  */
 export declare function updateMaybeValue<T>(a: Maybe<T>, b: Maybe<T>): Maybe<T>;

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

@@ -30,6 +30,7 @@ export interface Modifier<T> extends ModifierFunctionRef<T> {
  *
  * @param key - unique identifier for the modifier
  * @param modify - function that mutates the target value
+ * @returns a new {@link Modifier} pairing the key with the modify function
  *
  * @example
  * ```ts
@@ -42,6 +43,8 @@ export interface Modifier<T> extends ModifierFunctionRef<T> {
 export declare function modifier<T>(key: string, modify: ModifierFunction<T>): Modifier<T>;
 /**
  * A no-operation modifier that does nothing to the input. Useful as a default/fallback.
+ *
+ * @returns undefined (no mutation is performed)
  */
 export declare const NOOP_MODIFIER: ModifierFunction<any>;
 /**
@@ -55,6 +58,7 @@ export type ModifierMap<T> = Map<ModifierKey, Modifier<T>>;
  *
  * @param modifiers - modifier(s) to add
  * @param map - existing map to add to, or undefined to create a new one
+ * @returns the modifier map with the new modifiers added
  *
  * @example
  * ```ts
@@ -69,6 +73,7 @@ export declare function addModifiers<T>(modifiers: ArrayOrValue<Modifier<T>>, ma
  *
  * @param modifiers - modifier(s) whose keys should be removed
  * @param map - the map to remove from
+ * @returns the modifier map with the specified modifiers removed
  *
  * @example
  * ```ts
@@ -85,6 +90,7 @@ export declare function removeModifiers<T>(modifiers: ArrayOrValue<Modifier<T>>,
  * Returns {@link NOOP_MODIFIER} if the map is nullish or empty.
  *
  * @param map - the modifier map to convert
+ * @returns a single modifier function that applies all mapped modifiers, or {@link NOOP_MODIFIER} if empty
  *
  * @example
  * ```ts
@@ -103,6 +109,7 @@ export declare function modifierMapToFunction<T>(map: Maybe<ModifierMap<T>>): Mo
  * Returns undefined if no map is provided, allowing callers to distinguish "no modifiers" from "empty modifiers".
  *
  * @param map - the modifier map to convert
+ * @returns a composed modifier function, or `undefined` if no map is provided
  */
 export declare function maybeModifierMapToFunction<T>(map: Maybe<ModifierMap<T>>): Maybe<ModifierFunction<T>>;
 /**
@@ -111,6 +118,7 @@ export declare function maybeModifierMapToFunction<T>(map: Maybe<ModifierMap<T>>
  * Returns {@link NOOP_MODIFIER} if the array is empty or nullish.
  *
  * @param modifiers - array of modifier functions to merge
+ * @returns a single modifier function that applies all provided modifiers, or {@link NOOP_MODIFIER} if empty
  *
  * @example
  * ```ts
@@ -129,5 +137,6 @@ export declare function mergeModifiers<T>(modifiers: ModifierFunction<T>[]): Mod
  * If only one modifier is provided, returns it directly without wrapping.
  *
  * @param modifiers - array of modifier functions to merge, or undefined
+ * @returns a composed modifier function, the single modifier if only one provided, or `undefined` if input is nullish
  */
 export declare function maybeMergeModifiers<T>(modifiers: Maybe<ModifierFunction<T>[]>): Maybe<ModifierFunction<T>>;

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

@@ -51,6 +51,9 @@ 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
  */
 export declare function isLatLngPoint(input: LatLngPoint | unknown): input is LatLngPoint;
 /**

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

@@ -4,6 +4,7 @@
  * 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
  *
  * @example
  * ```ts

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

@@ -18,6 +18,7 @@ export type VectorTuple = [number, number];
  *
  * @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;
 /**
@@ -25,6 +26,7 @@ export declare function isSameVector(a: Maybe<Partial<Vector>>, b: Maybe<Partial
  *
  * @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;
 /**
@@ -38,6 +40,7 @@ export type VectorResizeFunction = (input: Vector) => Vector;
  * 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
  *
  * @example
  * ```ts
@@ -79,6 +82,7 @@ export interface Rectangle {
  *
  * @param a - first rectangle
  * @param b - second rectangle
+ * @returns `true` if the rectangles share any interior area
  *
  * @example
  * ```ts
@@ -98,5 +102,6 @@ export declare function rectangleOverlapsRectangle(a: Rectangle, b: Rectangle):
  *
  * @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>;