@dereekb/util 13.11.14 → 13.11.15

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

@@ -3,39 +3,42 @@ import { type Maybe } from '../value/maybe.type';
 /**
  * Trims leading and trailing whitespace from a string.
  *
+ * @param input - The string to trim.
+ * @returns The trimmed string.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, trim, whitespace, transform
  * @dbxUtilRelated transform-string-function
  *
- * @param input The string to trim.
- * @returns The trimmed string.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function stringTrimFunction(input: string): string;
 /**
  * Converts a string to uppercase.
  *
+ * @param input - The string to convert.
+ * @returns The uppercase string.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, uppercase, case, transform
  * @dbxUtilRelated string-to-lowercase-function, transform-string-function
  *
- * @param input The string to convert.
- * @returns The uppercase string.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function stringToUppercaseFunction(input: string): string;
 /**
  * Converts a string to lowercase.
  *
+ * @param input - The string to convert.
+ * @returns The lowercase string.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilTags string, lowercase, case, transform
  * @dbxUtilRelated string-to-uppercase-function, transform-string-function
  *
- * @param input The string to convert.
- * @returns The lowercase string.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function stringToLowercaseFunction(input: string): string;
@@ -83,7 +86,7 @@ export interface TransformStringFunctionConfigRef<S extends string = string> {
     readonly transform: TransformStringFunctionConfig<S>;
 }
 /**
- * A function that maps a string of type S to another string of type S.
+ * Maps a string of type S to another string of type S.
  *
  * @template S The specific string type, defaults to `string`.
  */
@@ -100,9 +103,10 @@ export type TransformStringFunctionConfigInput<S extends string = string> = Tran
  * If the input is a function, it's wrapped into a config object with that function as the `transform` property.
  * If the input is undefined, it returns undefined.
  *
- * @template S The specific string type, defaults to `string`.
- * @param config The configuration input to normalize.
+ * @param config - The configuration input to normalize.
  * @returns A `TransformStringFunctionConfig` object, or `undefined` if the input config is undefined.
+ *
+ * @template S The specific string type, defaults to `string`.
  */
 export declare function transformStringFunctionConfig<S extends string = string>(config?: TransformStringFunctionConfigInput<S>): Maybe<TransformStringFunctionConfig<S>>;
 /**
@@ -115,15 +119,16 @@ export declare function transformStringFunctionConfig<S extends string = string>
  * 4. Lowercase conversion (if `config.toLowercase` is true and no `config.transform` or `config.toUppercase`).
  * If no transformations are specified, the identity function is returned.
  *
+ * @param config - The `TransformStringFunctionConfig` detailing the transformations.
+ * @returns A `TransformStringFunction` that applies the configured transformations.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, transform, trim, case, slice, factory
  * @dbxUtilRelated string-trim-function, string-to-uppercase-function, string-to-lowercase-function, slice-string-function
- *
  * @template S The specific string type, defaults to `string`.
- * @param config The `TransformStringFunctionConfig` detailing the transformations.
- * @returns A `TransformStringFunction` that applies the configured transformations.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function transformStringFunction<S extends string = string>(config: TransformStringFunctionConfig<S>): TransformStringFunction<S>;
@@ -142,14 +147,15 @@ export type AddPrefixFunction = (input: string) => string;
 /**
  * Creates a function that adds a configured prefix to the input string if it does not exist on that string.
  *
+ * @param prefix - The prefix to add.
+ * @returns Adds the prefix to a string.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, prefix, add, factory
  * @dbxUtilRelated add-prefix, add-suffix-function
  *
- * @param prefix The prefix to add.
- * @returns A function that adds the prefix to a string.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function addPrefixFunction(prefix: string): AddPrefixFunction;
@@ -160,22 +166,23 @@ export type AddSuffixFunction = TransformStringFunction;
 /**
  * Adds a suffix to a string if it does not already end with that suffix.
  *
- * @param suffix The suffix to add.
- * @param input The string to modify.
+ * @param suffix - The suffix to add.
+ * @param input - The string to modify.
  * @returns The modified string.
  */
 export declare function addSuffix(suffix: string, input: string): string;
 /**
  * Creates a function that adds a configured suffix to the input string if it does not exist on that string.
  *
+ * @param suffix - The suffix to add.
+ * @returns Adds the suffix to a string.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, suffix, add, factory
  * @dbxUtilRelated add-suffix, add-prefix-function
  *
- * @param suffix The suffix to add.
- * @returns A function that adds the suffix to a string.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function addSuffixFunction(suffix: string): AddSuffixFunction;
@@ -186,15 +193,16 @@ export type PadStartFunction = TransformStringFunction;
 /**
  * Pads the start of a string to a minimum length.
  *
+ * @param minLength - The minimum length of the string.
+ * @param padCharacter - The character to use for padding.
+ * @returns Pads the start of a string.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, pad, start, factory, minimum-length
  * @dbxUtilRelated transform-string-function
  *
- * @param minLength The minimum length of the string.
- * @param padCharacter The character to use for padding.
- * @returns A function that pads the start of a string.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function padStartFunction(minLength: number, padCharacter: string): PadStartFunction;
@@ -228,14 +236,15 @@ export interface SliceStringFunctionConfig {
 /**
  * Creates a function that slices and concats parts of a string based on the configuration.
  *
+ * @param config - The configuration for the slice function.
+ * @returns A SliceStringFunction.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, slice, take, factory, from-start, from-end
  * @dbxUtilRelated transform-string-function
  *
- * @param config The configuration for the slice function.
- * @returns A SliceStringFunction.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function sliceStringFunction(config: SliceStringFunctionConfig): SliceStringFunction;

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

@@ -91,14 +91,15 @@ export type SplitStringTreeFactoryConfig<M = unknown> = AddToSplitStringTreeInpu
 /**
  * Creates a {@link SplitStringTreeFactory} that builds tree structures by splitting strings on the configured separator.
  *
+ * @param config - Configuration specifying the separator and optional metadata merge strategy.
+ * @returns A factory function that creates or extends split string trees.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, tree, split, separator, factory, hierarchy
  * @dbxUtilRelated add-to-split-string-tree, find-best-split-string-tree-match
  *
- * @param config - Configuration specifying the separator and optional metadata merge strategy.
- * @returns A factory function that creates or extends split string trees.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function splitStringTreeFactory<M = unknown>(config: SplitStringTreeFactoryConfig<M>): SplitStringTreeFactory<M>;
@@ -202,7 +203,7 @@ export declare function findBestSplitStringTreeChildMatch<M = unknown>(tree: Spl
  *
  * @param tree - The tree to search.
  * @param value - The string value to find a match path for.
- * @returns An array of tree nodes forming the match path from root to deepest match, or `undefined` if no match is found.
+ * @returns The tree nodes forming the match path from root to deepest match, or `undefined` if no match is found.
  */
 export declare function findBestSplitStringTreeMatchPath<M = unknown>(tree: SplitStringTree<M>, value: SplitStringTreeNodeString): Maybe<SplitStringTree<M>[]>;
 /**
@@ -212,6 +213,6 @@ export declare function findBestSplitStringTreeMatchPath<M = unknown>(tree: Spli
  *
  * @param tree - The tree to search.
  * @param value - The string value to find a match path for.
- * @returns An array of child tree nodes forming the match path, or `undefined` if no match is found.
+ * @returns The child tree nodes forming the match path, or `undefined` if no match is found.
  */
 export declare function findBestSplitStringTreeChildMatchPath<M = unknown>(tree: SplitStringTree<M>, value: SplitStringTreeNodeString): Maybe<SplitStringTree<M>[]>;

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

@@ -198,7 +198,7 @@ export interface WebsiteUrlDetails {
     /**
      * The port number, or `undefined` if none is present.
      */
-    readonly portNumber: PortNumber | undefined;
+    readonly portNumber: Maybe<PortNumber>;
     /**
      * The domain and path split pair.
      */
@@ -218,7 +218,7 @@ export interface WebsiteUrlDetails {
     /**
      * The query string portion, or undefined if none.
      */
-    readonly query: string | undefined;
+    readonly query: Maybe<string>;
 }
 /**
  * Parses the input string as a website URL and returns detailed information about its components.
@@ -340,14 +340,15 @@ export interface IsolateWebsitePathFunctionConfig {
 /**
  * Creates an {@link IsolateWebsitePathFunction} that extracts and transforms a path from a website URL based on the configuration.
  *
+ * @param config - Configuration for path isolation, including base path removal, component range, query handling, and trailing slash behavior.
+ * @returns Isolates the configured portion of a website path.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, url, path, isolate, transform, factory, query
  * @dbxUtilRelated website-path-from-website-url, website-path-and-query-pair, fix-extra-query-parameters
  *
- * @param config - Configuration for path isolation, including base path removal, component range, query handling, and trailing slash behavior.
- * @returns A function that isolates the configured portion of a website path.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function isolateWebsitePathFunction(config?: IsolateWebsitePathFunctionConfig): IsolateWebsitePathFunction;

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

@@ -16,18 +16,19 @@ export type ExpandFlattenTreeFunction<T, V> = (values: T[]) => V[];
  * This higher-order function takes a function to expand an array of values `T` into a list of trees (`N[]` where `N` is a TreeNode)
  * and another function to flatten these trees into a single array of values `V`.
  *
+ * @param expand - An ExpandTreeFunction (values: T[]) => N[] that converts an array of T into an array of tree nodes N.
+ * @param flatten - A FlattenTreeFunction (tree: N, array?: V[]) => V[] that flattens a tree of N nodes into an array of V values.
+ * @returns An ExpandFlattenTreeFunction (values: T[]) => V[] that performs the combined expansion and flattening.
+ *
  * @dbxUtil
  * @dbxUtilCategory tree
  * @dbxUtilKind factory
  * @dbxUtilTags tree, expand, flatten, compose, factory, transform
  * @dbxUtilRelated expand-tree-function, flatten-tree-to-array-function, expand-trees
- *
  * @template T The type of the initial input values.
  * @template V The type of the values in the final flattened output array.
  * @template N The type of the intermediate tree nodes. Must extend TreeNode with value T and children of type N.
- * @param expand An ExpandTreeFunction (values: T[]) => N[] that converts an array of T into an array of tree nodes N.
- * @param flatten A FlattenTreeFunction (tree: N, array?: V[]) => V[] that flattens a tree of N nodes into an array of V values.
- * @returns An ExpandFlattenTreeFunction (values: T[]) => V[] that performs the combined expansion and flattening.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function expandFlattenTreeFunction<T, V, N extends TreeNode<T, N> = TreeNode<T, any>>(expand: ExpandTreeFunction<T, N>, flatten: FlattenTreeFunction<N, V>): ExpandFlattenTreeFunction<T, V>;

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

@@ -12,7 +12,7 @@ export interface ExpandTree<T> {
      *
      * @param value The current value of type T to retrieve children for.
      * @param depth The depth of the current node.
-     * @returns An array of child values of type T, or undefined/null if no children exist.
+     * @returns The child values of type T, or undefined/null if no children exist.
      */
     getChildren(value: T, depth: number): Maybe<T[]>;
 }
@@ -34,7 +34,7 @@ export interface ExpandTreeWithNodeBuilder<T, N extends TreeNode<T, N>> extends
     makeNode: (node: TreeNodeWithoutChildren<T, N>) => Omit<N, 'children'>;
 }
 /**
- * A function that expands an input value of type T into a TreeNode of type N.
+ * Expands an input value of type T into a TreeNode of type N.
  *
  * @template T The type of the input value to expand.
  * @template N The type of the TreeNode to be created. Defaults to TreeNode<T, any>.
@@ -65,15 +65,15 @@ export declare function expandTreeFunction<T, N extends TreeNode<T, N>>(config:
  * Convenience function for expanding multiple root values into an array of trees.
  * Each value in the input array is treated as a root for a new tree.
  *
+ * @param values - The root values of type T to expand.
+ * @param expandFn - An ExpandTreeFunction<T, N> used to expand each value into a tree.
+ * @returns Array of N, where each N is the root node of an expanded tree.
+ *
  * @dbxUtil
  * @dbxUtilCategory tree
  * @dbxUtilTags tree, expand, multiple, roots, hierarchy, build, batch
  * @dbxUtilRelated expand-tree-function, expand-flatten-tree-function
- *
  * @template T The type of the input values.
  * @template N The type of the TreeNode in the resulting trees. Must extend TreeNode<T, N>.
- * @param values An array of root values of type T to expand.
- * @param expandFn An ExpandTreeFunction<T, N> used to expand each value into a tree.
- * @returns An array of N, where each N is the root node of an expanded tree.
  */
 export declare function expandTrees<T, N extends TreeNode<T, N>>(values: T[], expandFn: ExpandTreeFunction<T, N>): N[];

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

@@ -73,16 +73,16 @@ export interface ExploreTreeFunctionConfig<N extends TreeNode<unknown>, V = N> {
     /**
      * Custom traversal strategy (e.g., breadth-first). Defaults to depth-first.
      */
-    traverseFunctionFactory?: ExploreTreeTraversalFactoryFunction<N, V>;
+    readonly traverseFunctionFactory?: ExploreTreeTraversalFactoryFunction<N, V>;
     /**
      * Transforms each node into a value before visiting. Defaults to identity.
      */
-    mapNodeFunction?: (node: N) => V;
+    readonly mapNodeFunction?: (node: N) => V;
     /**
      * Controls whether each node is visited, skipped, or has only its children visited.
      * Defaults to visiting all nodes.
      */
-    shouldVisitNodeFunction?: Maybe<ExploreTreeVisitNodeDecisionFunction<N, V>>;
+    readonly shouldVisitNodeFunction?: Maybe<ExploreTreeVisitNodeDecisionFunction<N, V>>;
 }
 /**
  * Traverses one or more trees, invoking a visit callback on each node.
@@ -100,15 +100,15 @@ export type ExploreTreeFunction<N extends TreeNode<unknown, N>, V> = (trees: Arr
  * By default uses depth-first traversal, identity mapping, and visits all nodes. All options
  * can be overridden per-call.
  *
+ * @param config - Optional default configuration for mapping, filtering, and traversal strategy.
+ * @returns A reusable function that explores trees with the configured behavior.
+ *
  * @dbxUtil
  * @dbxUtilCategory tree
  * @dbxUtilKind factory
  * @dbxUtilTags tree, explore, traverse, visit, factory, depth-first, breadth-first, walk
  * @dbxUtilRelated depth-first-explore-tree-traversal-factory-function, breadth-first-explore-tree-traversal-factory-function, flatten-tree-to-array-function
  *
- * @param config - Optional default configuration for mapping, filtering, and traversal strategy.
- * @returns A reusable function that explores trees with the configured behavior.
- *
  * @example
  * ```typescript
  * const exploreFn = exploreTreeFunction<TestNode, string>({
@@ -120,6 +120,7 @@ export type ExploreTreeFunction<N extends TreeNode<unknown, N>, V> = (trees: Arr
  *   visited.push(id);
  * });
  * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function exploreTreeFunction<N extends TreeNode<unknown, N>, V>(config?: Maybe<ExploreTreeFunctionConfig<N, V>>): ExploreTreeFunction<N, V>;
@@ -129,14 +130,14 @@ export declare function exploreTreeFunction<N extends TreeNode<unknown, N>, V>(c
  * Visits each node before its children (pre-order). This is the default traversal
  * strategy used by {@link exploreTreeFunction}.
  *
+ * @returns A traversal factory that processes nodes in depth-first order.
+ *
  * @dbxUtil
  * @dbxUtilCategory tree
  * @dbxUtilKind factory
  * @dbxUtilTags tree, traverse, depth-first, dfs, pre-order, factory, strategy
  * @dbxUtilRelated breadth-first-explore-tree-traversal-factory-function, explore-tree-function
  *
- * @returns A traversal factory that processes nodes in depth-first order.
- *
  * @example
  * ```typescript
  * const exploreFn = exploreTreeFunction<TestNode, TestNode>({
@@ -144,6 +145,7 @@ export declare function exploreTreeFunction<N extends TreeNode<unknown, N>, V>(c
  * });
  * // Visits: root -> child1 -> leaf1 -> leaf2 -> child2 -> leaf3
  * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function depthFirstExploreTreeTraversalFactoryFunction<N extends TreeNode<unknown, N>, V>(): ExploreTreeTraversalFactoryFunction<N, V>;
@@ -153,14 +155,14 @@ export declare function depthFirstExploreTreeTraversalFactoryFunction<N extends
  * Visits nodes level by level, processing all nodes at depth N before moving to depth N+1.
  * Uses an internal queue to defer child processing until the current level is complete.
  *
+ * @returns A traversal factory that processes nodes in breadth-first order.
+ *
  * @dbxUtil
  * @dbxUtilCategory tree
  * @dbxUtilKind factory
  * @dbxUtilTags tree, traverse, breadth-first, bfs, level-order, factory, strategy, queue
  * @dbxUtilRelated depth-first-explore-tree-traversal-factory-function, explore-tree-function
  *
- * @returns A traversal factory that processes nodes in breadth-first order.
- *
  * @example
  * ```typescript
  * const exploreFn = exploreTreeFunction<TestNode, TestNode>({
@@ -168,6 +170,7 @@ export declare function depthFirstExploreTreeTraversalFactoryFunction<N extends
  * });
  * // Visits: root -> child1, child2, child3 -> leaf1, leaf2, leaf3
  * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function breadthFirstExploreTreeTraversalFactoryFunction<N extends TreeNode<unknown, N>, V>(): ExploreTreeTraversalFactoryFunction<N, V>;

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

@@ -3,7 +3,7 @@ import { type Maybe } from '../value/maybe.type';
 import { type TreeNode } from './tree';
 import { type ExploreTreeFunctionConfig, ExploreTreeVisitNodeDecision, type ExploreTreeVisitNodeDecisionFunction } from './tree.explore';
 /**
- * A function that flattens a tree structure into an array of values.
+ * Flattens a tree structure into an array of values.
  *
  * @template N The type of the tree node, extending TreeNode.
  * @template V The type of values in the resulting flattened array.
@@ -54,15 +54,15 @@ export type FlattenTreeAddNodeDecisionFunction<N extends TreeNode<unknown>, V =
 /**
  * Flattens a tree into an array containing all its nodes using depth-first traversal.
  *
+ * @param tree - The root node to flatten.
+ * @param addNodeFn - Optional filter controlling which nodes and subtrees are included.
+ * @returns The all nodes in the tree that pass the filter.
+ *
  * @dbxUtil
  * @dbxUtilCategory tree
  * @dbxUtilTags tree, flatten, traverse, depth-first, collect, nodes, array
  * @dbxUtilRelated flatten-tree-to-array, flatten-tree-to-array-function, explore-tree-function
  *
- * @param tree - The root node to flatten.
- * @param addNodeFn - Optional filter controlling which nodes and subtrees are included.
- * @returns An array of all nodes in the tree that pass the filter.
- *
  * @example
  * ```typescript
  * const nodes = flattenTree(rootNode);
@@ -75,16 +75,16 @@ export declare function flattenTree<N extends TreeNode<unknown> = TreeNode<unkno
  *
  * Useful for accumulating nodes from multiple trees into a single collection.
  *
- * @dbxUtil
- * @dbxUtilCategory tree
- * @dbxUtilTags tree, flatten, append, accumulate, collect, mutate, array
- * @dbxUtilRelated flatten-tree, flatten-tree-to-array-function
- *
  * @param tree - The root node to flatten.
  * @param array - The target array to push flattened nodes into.
  * @param addNodeFn - Optional filter controlling which nodes and subtrees are included.
  * @returns The same array reference, now containing the appended nodes.
  *
+ * @dbxUtil
+ * @dbxUtilCategory tree
+ * @dbxUtilTags tree, flatten, append, accumulate, collect, mutate, array
+ * @dbxUtilRelated flatten-tree, flatten-tree-to-array-function
+ *
  * @example
  * ```typescript
  * const existing: TreeNode[] = [someNode];

package/src/lib/type.d.ts

@@ -4,6 +4,35 @@ import { type Maybe } from './value/maybe.type';
  * Boolean, string or number value.
  */
 export type PrimativeValue = boolean | string | number;
+/**
+ * Open-ended union of known string literals `T` plus an arbitrary string fallback.
+ *
+ * `T | string` collapses to `string` in TypeScript and erases IDE autocomplete for the
+ * literal members. The `(string & {})` intersection is the canonical workaround: at
+ * runtime it is just `string`, but the compiler keeps the literal members visible in
+ * the union so editors still suggest them.
+ *
+ * Always prefer this named alias over writing the intersection inline. Two lint rules
+ * enforce that:
+ *
+ * - `dereekb-util/no-inline-string-empty-object-intersection` (error) — flags every
+ *   inline `T | (string & {})` and tells the developer to switch to `SuggestedString<T>`.
+ * - `dereekb-util/prefer-suggested-string` (warn) — flags `T | string` where `T` is a
+ *   literal-string union; if you actually want autocomplete-preserving behavior, switch
+ *   to `SuggestedString<T>`, otherwise drop the literal half and keep plain `string`.
+ *
+ * Reach for `SuggestedString` only when the API genuinely accepts unknown string values
+ * alongside a known set (e.g. third-party APIs that document a literal set but allow
+ * custom strings). For closed sets, use a plain literal union; for unconstrained input,
+ * use plain `string`.
+ *
+ * @example
+ * ```ts
+ * type ZohoDeskTicketPriority = SuggestedString<'Low' | 'Medium' | 'High' | 'Urgent'>;
+ * // accepts any string, but autocompletes the four known priorities.
+ * ```
+ */
+export type SuggestedString<T extends string> = T | (string & Record<never, never>);
 /**
  * Class typing, restricted to types that have a constructor via the new keyword.
  */
@@ -17,26 +46,26 @@ export type ObjectWithConstructor = {
  * Returns true if the input is a function-like value with a prototype and constructor (i.e., a class or named function declaration).
  * Returns false for arrow functions, class instances, plain objects, and primitives.
  *
+ * @param obj - The value to check.
+ * @returns Whether the value is a function with a constructor.
+ *
  * @dbxUtil
  * @dbxUtilCategory type
  * @dbxUtilTags type, type-guard, function, class, constructor, reflection
  * @dbxUtilRelated is-class-like-type, get-function-type, is-non-class-function
- *
- * @param obj - The value to check.
- * @returns Whether the value is a function with a constructor.
  */
 export declare function isObjectWithConstructor(obj: any): obj is ObjectWithConstructor;
 /**
  * Returns true if the input is a class (requires `new` to instantiate). Distinguishes classes from regular functions
  * by checking that the prototype is non-writable.
  *
+ * @param obj - The value to check.
+ * @returns Whether the value is a class type.
+ *
  * @dbxUtil
  * @dbxUtilCategory type
  * @dbxUtilTags type, type-guard, class, reflection, instance
  * @dbxUtilRelated is-object-with-constructor, get-function-type
- *
- * @param obj - The value to check.
- * @returns Whether the value is a class type.
  */
 export declare function isClassLikeType(obj: unknown): obj is ClassLikeType;
 export type FunctionType = 'function' | 'class' | 'arrow';
@@ -44,25 +73,26 @@ export type FunctionType = 'function' | 'class' | 'arrow';
  * Determines the function type of the input value: `'class'`, `'function'`, or `'arrow'`.
  * Returns `null` if the input is not a function.
  *
+ * @param x - The value to inspect.
+ * @returns The {@link FunctionType}, or `null` for non-functions.
+ *
  * @dbxUtil
  * @dbxUtilCategory type
  * @dbxUtilTags type, function, class, arrow, reflection, kind, detect
  * @dbxUtilRelated is-class-like-type, is-non-class-function, is-object-with-constructor
- *
- * @param x - The value to inspect.
- * @returns The {@link FunctionType}, or `null` for non-functions.
  */
 export declare function getFunctionType(x: unknown): Maybe<FunctionType>;
 /**
  * Returns true if the input is a function but not a class (i.e., a regular function or arrow function).
  *
+ * @param x - The value to check.
+ * @returns Whether the value is a non-class function.
+ *
  * @dbxUtil
  * @dbxUtilCategory type
  * @dbxUtilTags type, type-guard, function, arrow, reflection, callable
  * @dbxUtilRelated is-class-like-type, get-function-type
  *
- * @param x - The value to check.
- * @returns Whether the value is a non-class function.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function isNonClassFunction(x: unknown): x is Function;
@@ -87,7 +117,7 @@ export type ValuesTypesAsArray<T> = T[keyof T][];
  * Converts the input value to a string, if possible. Never otherwise.
  */
 export type KeyAsString<K> = `${KeyCanBeString<K>}`;
-export type KeyCanBeString<K> = K extends number | boolean | string | null | undefined ? K : never;
+export type KeyCanBeString<K> = K extends Maybe<number | boolean | string> ? K : never;
 export type BooleanKeyValueTransformMap<T> = KeyValueTransformMap<T, boolean>;
 /**
  * Merges the types T and R, but replaces keys within T with those in R.

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

@@ -107,9 +107,9 @@ export interface UnitedStatesAddressWithContact extends UnitedStatesAddress {
  * Empty or undefined fields are omitted. If the input includes contact fields (name, phone), they appear at the top.
  * Returns `undefined` if no meaningful parts are present.
  *
- * @param input - the address to format
- * @param addLinebreaks - whether to join parts with newlines (default `true`) or concatenate them directly
- * @returns the formatted address string, or `undefined` if no meaningful parts are present
+ * @param input - The address to format.
+ * @param addLinebreaks - Whether to join parts with newlines (default `true`) or concatenate them directly.
+ * @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>;
 /**
@@ -117,8 +117,8 @@ 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
+ * @param input - The address to validate.
+ * @returns `true` if all required fields (line1, city, state, zip) are populated.
  *
  * @example
  * ```ts
@@ -145,8 +145,8 @@ 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
+ * @param input - The string to test.
+ * @returns `true` if the input matches a valid US state or territory code.
  *
  * @example
  * ```ts