@dereekb/util 13.11.2 → 13.11.4

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

@@ -69,9 +69,16 @@ export declare const PRIMATIVE_KEY_DENCODER_VALUE: (_input: unknown) => null;
  * Creates a new {@link PrimativeKeyDencoderFunction} that can bidirectionally encode/decode
  * primitive key values based on the configured value pairs.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, encode, decode, dencoder, bidirectional, factory, primitive
+ * @dbxUtilRelated primative-key-dencoder-map, primative-key-string-dencoder
+ *
  * @param config - configuration with value pairs and optional default fallback
  * @returns a function that encodes or decodes single values or arrays
  * @throws Error if a single value lookup produces a null result and no default handles it
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function primativeKeyDencoder<D extends PrimativeKey, E extends PrimativeKey>(config: PrimativeKeyDencoderConfig<D, E>): PrimativeKeyDencoderFunction<D, E>;
 /**
@@ -101,9 +108,16 @@ export type PrimativeKeyStringDencoderFunction<D extends PrimativeKey, E extends
  * When no splitter is defined, all encoded values must be exactly one character long so the string
  * can be split character-by-character.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, encode, decode, dencoder, splitter, factory, primitive
+ * @dbxUtilRelated primative-key-dencoder, primative-key-dencoder-map
+ *
  * @param config - configuration with dencoder and optional splitter
  * @returns a bidirectional function for string-to-array and array-to-string conversion
  * @throws Error if encoded values contain the splitter character, or if values exceed one character when no splitter is defined
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function primativeKeyStringDencoder<D extends PrimativeKey, E extends PrimativeKey>(config: PrimativeKeyStringDencoderConfig<D, E>): PrimativeKeyStringDencoderFunction<D, E>;
 /**
@@ -211,23 +225,44 @@ export type NumberStringDencoderFunction = ((input: NumberStringDencoderString)
  * Creates a {@link NumberStringDencoderFunction} from the given dencoder.
  * The returned function auto-detects the input type: numbers are encoded, strings are decoded.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, number, encode, decode, dencoder, bidirectional, factory
+ * @dbxUtilRelated number-string-dencoder, number-string-dencoder-encoded-string-value-function, number-string-dencoder-decoded-number-value-function
+ *
  * @param dencoder - the NumberStringDencoder to wrap
  * @returns a bidirectional encode/decode function
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function numberStringDencoderFunction(dencoder: NumberStringDencoder): NumberStringDencoderFunction;
 /**
  * Creates a function that always returns the encoded string form of the input.
  * Numbers are encoded; strings are passed through as-is.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, number, encode, normalize, factory
+ * @dbxUtilRelated number-string-dencoder-function, number-string-dencoder-decoded-number-value-function
+ *
  * @param dencoder - the NumberStringDencoder to use for encoding
  * @returns a function that normalizes input to an encoded string
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function numberStringDencoderEncodedStringValueFunction(dencoder: NumberStringDencoder): (input: NumberStringDencoderString | NumberStringDencoderNumber) => NumberStringDencoderString;
 /**
  * Creates a function that always returns the decoded number form of the input.
  * Strings are decoded; numbers are passed through as-is.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, number, decode, normalize, factory
+ * @dbxUtilRelated number-string-dencoder-function, number-string-dencoder-encoded-string-value-function
+ *
  * @param dencoder - the NumberStringDencoder to use for decoding
  * @returns a function that normalizes input to a decoded number
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function numberStringDencoderDecodedNumberValueFunction(dencoder: NumberStringDencoder): (input: NumberStringDencoderString | NumberStringDencoderNumber) => NumberStringDencoderNumber;

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

@@ -12,9 +12,16 @@ export type ToStringFunction<T, K extends string = string> = FactoryWithRequired
 /**
  * Wraps an existing factory with a {@link ToStringFunction} to produce strings from the factory's output.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, factory, wrap, transform, to-string
+ * @dbxUtilRelated string-from-date-factory, string-from-time-factory
+ *
  * @param factory - the original value factory
  * @param toStringFunction - function to convert the factory's output to a string
  * @returns a new factory that produces string values
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function stringFactoryFromFactory<T, K extends string = string>(factory: Factory<T>, toStringFunction: ToStringFunction<T, K>): StringFactory<K>;
 /**
@@ -42,15 +49,29 @@ export interface StringFromDateConfig {
 }
 /**
  * Creates a factory that returns a string based on the input date.
- 
+ *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, date, factory, transform, slice
+ * @dbxUtilRelated string-from-time-factory, string-factory-from-factory, transform-string-function
+ *
  * @param config Configuration for the factory.
  * @returns A factory that returns a string based on the input date.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function stringFromDateFactory(config: StringFromDateConfig): StringFromDateFactory;
 /**
  * Creates a factory that returns a string based on the Unix timestamp of the input date.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, date, time, timestamp, factory, suffix
+ * @dbxUtilRelated string-from-date-factory
+ *
  * @param digitsFromEnd The number of digits to return from the end of the generated string. Defaults to 7.
  * @returns A StringFromDateFactory.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function stringFromTimeFactory(digitsFromEnd?: number): StringFromDateFactory;

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

@@ -21,8 +21,15 @@ export interface ReplaceStringsConfig {
 /**
  * Creates a function that replaces all occurrences of the configured target strings with a replacement value.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, replace, regex, substitute, factory
+ * @dbxUtilRelated find-strings-regex-string, escape-string-for-regex
+ *
  * @param config - Configuration specifying strings to find and the replacement value.
  * @returns A function that performs the configured replacements on an input string.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function replaceStringsFunction(config: ReplaceStringsConfig): (input: string) => string;
 /**
@@ -36,6 +43,11 @@ export declare const REGEX_SPECIAL_CHARACTERS_SET: Set<string>;
 /**
  * Creates an escaped regex string that matches any of the input values, joined with the OR (`|`) operator.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilTags string, regex, escape, alternation, pattern
+ * @dbxUtilRelated escape-string-for-regex, replace-strings-function
+ *
  * @param find - One or more strings to create a matching regex pattern for.
  * @returns A regex-compatible string with special characters escaped and values joined by `|`.
  */
@@ -67,8 +79,15 @@ export type EscapeStringCharactersFunction = (input: string) => string;
 /**
  * Creates an {@link EscapeStringCharactersFunction} that escapes specific characters in a string using the configured escape strategy.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, escape, characters, factory, transform
+ * @dbxUtilRelated escape-string-for-regex, find-all-character-occurences-function
+ *
  * @param config - Configuration specifying which characters to escape and how to escape them.
  * @returns A function that escapes the configured characters in any input string.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function escapeStringCharactersFunction(config: EscapeStringCharactersFunctionConfig): EscapeStringCharactersFunction;
 /**
@@ -76,6 +95,12 @@ export declare function escapeStringCharactersFunction(config: EscapeStringChara
  *
  * For instance, `'hello.world'` will be escaped to `'hello\\.world'`.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind const
+ * @dbxUtilTags string, regex, escape, sanitize, pattern
+ * @dbxUtilRelated escape-string-characters-function, find-strings-regex-string
+ *
  * @param input - The string to escape for regex use.
  * @returns The escaped string with all regex special characters prefixed with a backslash.
  */
@@ -91,13 +116,25 @@ export type FindAllCharacterOccurencesFunction = (input: string, max?: Maybe<num
 /**
  * Creates a {@link FindAllCharacterOccurencesFunction} that searches for characters from the given set.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, search, characters, indices, factory, occurrences
+ * @dbxUtilRelated find-all-character-occurences, find-first-character-occurence
+ *
  * @param characterSet - The set of characters to search for.
  * @returns A function that finds all occurrences of the configured characters in an input string.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function findAllCharacterOccurencesFunction(characterSet: Set<string>): FindAllCharacterOccurencesFunction;
 /**
  * Finds all indices of characters from the set that appear in the input string.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilTags string, search, characters, indices, occurrences
+ * @dbxUtilRelated find-all-character-occurences-function, find-first-character-occurence
+ *
  * @param set - The set of characters to search for.
  * @param input - The string to search through.
  * @param max - Optional maximum number of occurrences to return.
@@ -107,6 +144,11 @@ export declare function findAllCharacterOccurences(set: Set<string>, input: stri
 /**
  * Finds the index of the first occurrence of any character from the set in the input string.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilTags string, search, characters, first, index, occurrence
+ * @dbxUtilRelated find-all-character-occurences, find-all-character-occurences-function
+ *
  * @param set - The set of characters to search for.
  * @param input - The string to search through.
  * @returns The zero-based index of the first matching character, or `undefined` if none found.
@@ -126,13 +168,25 @@ export type SplitStringAtFirstCharacterOccurenceFunction = (input: string) => Sp
 /**
  * Creates a function that splits a string into two parts at the first occurrence of any character in the configured set.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, split, characters, occurrence, factory
+ * @dbxUtilRelated split-string-at-first-character-occurence, keep-characters-after-first-character-occurence-function
+ *
  * @param splitAt - A single character or set of characters to split on.
  * @returns A function that splits input strings at the first matching character.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function splitStringAtFirstCharacterOccurenceFunction(splitAt: string | Set<string>): SplitStringAtFirstCharacterOccurenceFunction;
 /**
  * Splits the input string into two parts at the first occurrence of any character in the split set.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilTags string, split, characters, occurrence, tuple
+ * @dbxUtilRelated split-string-at-first-character-occurence-function, find-first-character-occurence
+ *
  * @param input - The string to split.
  * @param splitAt - A single character or set of characters to split on.
  * @returns A tuple of [before, after], where `after` is `undefined` if no split character was found.
@@ -147,13 +201,25 @@ export type KeepCharactersAfterFirstCharacterOccurenceFunction = (input: string)
 /**
  * Creates a function that returns only the characters after the first occurrence of any character in the configured set.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, keep, after, occurrence, factory, suffix
+ * @dbxUtilRelated keep-characters-after-first-character-occurence, remove-characters-after-first-character-occurence-function
+ *
  * @param findCharacters - A single character or set of characters to search for.
  * @returns A function that extracts the substring after the first matching character, or an empty string if none found.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function keepCharactersAfterFirstCharacterOccurenceFunction(findCharacters: string | Set<string>): KeepCharactersAfterFirstCharacterOccurenceFunction;
 /**
  * Returns only the characters after the first occurrence of any character from the find set.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilTags string, keep, after, occurrence, suffix
+ * @dbxUtilRelated keep-characters-after-first-character-occurence-function, remove-characters-after-first-character-occurence
+ *
  * @param input - The string to search through.
  * @param findCharacters - A single character or set of characters to search for.
  * @returns The substring after the first matching character, or an empty string if none found.
@@ -166,13 +232,25 @@ export type RemoveCharactersAfterFirstCharacterOccurenceFunction = (input: strin
 /**
  * Creates a function that removes all characters after (and including) the first occurrence of any character in the configured set.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, remove, truncate, occurrence, factory, prefix
+ * @dbxUtilRelated remove-characters-after-first-character-occurence, keep-characters-after-first-character-occurence-function
+ *
  * @param findCharacters - A single character or set of characters to search for.
  * @returns A function that truncates input strings at the first matching character.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function removeCharactersAfterFirstCharacterOccurenceFunction(findCharacters: string | Set<string>): RemoveCharactersAfterFirstCharacterOccurenceFunction;
 /**
  * Removes all characters after (and including) the first occurrence of any character from the find set.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilTags string, remove, truncate, occurrence, prefix
+ * @dbxUtilRelated remove-characters-after-first-character-occurence-function, keep-characters-after-first-character-occurence
+ *
  * @param input - The string to truncate.
  * @param findCharacters - A single character or set of characters to search for.
  * @returns The substring before the first matching character, or the full string if none found.

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

@@ -34,8 +34,15 @@ export type SearchStringFilterFunctionConfigInput<T> = ReadKeyFunction<T, string
 /**
  * Creates a {@link SearchStringFilterFunction} that filters values based on whether their string representation matches the filter text.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, search, filter, factory, match, decision
+ * @dbxUtilRelated case-insensitive-filter-by-index-of-decision-factory
+ *
  * @param config - A read function or full configuration specifying how to extract and match search strings.
  * @returns A function that filters an array of values by a search/filter text string.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function searchStringFilterFunction<T>(config: SearchStringFilterFunctionConfigInput<T>): SearchStringFilterFunction<T>;
 /**

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

@@ -7,8 +7,15 @@ export type SortByStringFunction<T> = SortCompareFunction<T>;
 /**
  * Creates a {@link SortByStringFunction} that sorts values in ascending alphabetical order using `localeCompare`.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilKind factory
+ * @dbxUtilTags string, sort, compare, alphabetical, factory, locale
+ * @dbxUtilRelated sort-by-label-function
+ *
  * @param readStringFn - Function to extract a string from each value for comparison.
  * @returns A comparator function suitable for use with `Array.sort()`.
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function sortByStringFunction<T>(readStringFn: ReadStringFunction<T>): SortByStringFunction<T>;
 /**

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

@@ -298,6 +298,7 @@ export type CutStringFunction = ((input: string) => string) & ((input: Maybe<str
  *
  * @param config - configuration controlling max length and end text behavior
  * @returns a reusable function that truncates input strings
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function cutStringFunction(config: CutStringFunctionConfig): CutStringFunction;
 /**

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

@@ -3,22 +3,40 @@ import { type Maybe } from '../value/maybe.type';
 /**
  * Trims leading and trailing whitespace from a 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.
  *
+ * @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.
  *
+ * @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;
 /**
@@ -97,9 +115,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.
  *
+ * @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>;
 /**
@@ -117,8 +142,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.
  *
+ * @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;
 /**
@@ -136,8 +168,15 @@ 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.
  *
+ * @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;
 /**
@@ -147,9 +186,16 @@ export type PadStartFunction = TransformStringFunction;
 /**
  * Pads the start of a string to a minimum length.
  *
+ * @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;
 /**
@@ -182,7 +228,14 @@ export interface SliceStringFunctionConfig {
 /**
  * Creates a function that slices and concats parts of a string based on the configuration.
  *
+ * @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,8 +91,15 @@ export type SplitStringTreeFactoryConfig<M = unknown> = AddToSplitStringTreeInpu
 /**
  * Creates a {@link SplitStringTreeFactory} that builds tree structures by splitting strings on the configured separator.
  *
+ * @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>;
 /**

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

@@ -340,8 +340,15 @@ export interface IsolateWebsitePathFunctionConfig {
 /**
  * Creates an {@link IsolateWebsitePathFunction} that extracts and transforms a path from a website URL based on the configuration.
  *
+ * @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

@@ -28,5 +28,6 @@ export type ExpandFlattenTreeFunction<T, V> = (values: T[]) => 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.
+ * @__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.explore.d.ts

@@ -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>;
 /**
@@ -143,6 +144,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>;
 /**
@@ -166,5 +168,6 @@ 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/type.d.ts

@@ -1,4 +1,4 @@
-import { type Merge, type NonNever, type PickProperties, type StrictOmit, type UnionToIntersection, type Writable } from 'ts-essentials';
+import { type Merge, type OmitNeverProperties, type PickProperties, type StrictOmit, type UnionToIntersection, type Writable } from 'ts-essentials';
 import { type Maybe } from './value/maybe.type';
 /**
  * Boolean, string or number value.
@@ -63,6 +63,7 @@ export declare function getFunctionType(x: unknown): Maybe<FunctionType>;
  *
  * @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;
 /**
@@ -123,7 +124,7 @@ export type PartialOnKeys<T, K> = K extends keyof T ? Omit<T, K> & Partial<Pick<
 /**
  * Returns only properties that have string keys.
  */
-export type StringKeyProperties<T> = NonNever<{
+export type StringKeyProperties<T> = OmitNeverProperties<{
     [K in keyof T]: K extends string ? T[K] : never;
 }>;
 /**

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

@@ -179,8 +179,15 @@ export type LatLngBoundTupleFunctionConfig = LatLngBoundFunctionConfig;
  * Creates a {@link LatLngBoundTupleFunction} that converts various bound inputs into a `[sw, ne]` tuple,
  * applying optional precision to the resulting points.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, lat-lng, bound, tuple, factory, geographic
+ * @dbxUtilRelated lat-lng-bound-function, lat-lng-bound
+ *
  * @param config - optional configuration for point precision
  * @returns a function that produces bound tuples from flexible inputs
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function latLngBoundTupleFunction(config?: LatLngBoundTupleFunctionConfig): LatLngBoundTupleFunction;
 /**
@@ -224,12 +231,19 @@ export interface LatLngBoundFunctionConfig {
  * @returns a function that produces bounds from flexible inputs
  * @throws {Error} when the input cannot be parsed into a valid bound
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, lat-lng, bound, factory, geographic, normalize
+ * @dbxUtilRelated lat-lng-bound, lat-lng-bound-tuple-function, lat-lng-point-function
+ *
  * @example
  * ```ts
  * const fn = latLngBoundFunction({ precision: 3 });
  * const result = fn([{ lat: 20, lng: 20 }, { lat: 30, lng: 30 }]);
  * // result.sw.lat === 20, result.ne.lat === 30
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function latLngBoundFunction(config?: LatLngBoundFunctionConfig): LatLngBoundFunction;
 /**
@@ -281,8 +295,15 @@ export type IsWithinLatLngBoundFunction = LatLngBoundCheckFunction & {
  * falls entirely within the specified bound. Points are checked directly; bounds require
  * both corners to be within.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, lat-lng, bound, contains, decision, factory, geographic
+ * @dbxUtilRelated overlaps-lat-lng-bound-function, is-lat-lng-point-within-lat-lng-bound
+ *
  * @param bound - the reference bound to check containment against
  * @returns a function that returns `true` if the input is within the reference bound
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function isWithinLatLngBoundFunction(bound: LatLngBound): IsWithinLatLngBoundFunction;
 /**
@@ -330,8 +351,15 @@ export declare function latLngBoundOverlapsLatLngBound(a: LatLngBound, b: LatLng
  * overlaps the reference bound. Internally converts bounds to rectangles for overlap detection,
  * handling antimeridian wrapping.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, lat-lng, bound, overlap, decision, factory, geographic
+ * @dbxUtilRelated is-within-lat-lng-bound-function, lat-lng-bound-overlaps-lat-lng-bound
+ *
  * @param bound - the reference bound to check overlap against
  * @returns a function that returns `true` if the input overlaps the reference bound
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function overlapsLatLngBoundFunction(bound: LatLngBound): OverlapsLatLngBoundFunction;
 /**

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

@@ -27,6 +27,7 @@ export type EqualityComparatorFunction<T> = (a: T, b: T) => boolean;
  * safeCompare(null, null);  // true
  * safeCompare(null, undefined); // false
  * ```
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function safeEqualityComparatorFunction<T>(compare: EqualityComparatorFunction<T>): EqualityComparatorFunction<Maybe<T>>;
 /**
@@ -78,9 +79,16 @@ export type CompareEqualityWithValueFromItemsFunction<I, V> = ((a: Maybe<I>, b:
  * This is a convenience wrapper around {@link compareEqualityWithValueFromItemsFunctionFactory} that
  * accepts both the value reader and comparator in a single call.
  *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, comparator, equality, factory, read
+ * @dbxUtilRelated compare-equality-with-value-from-items-function-factory, safe-equality-comparator-function
+ *
  * @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
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function compareEqualityWithValueFromItemsFunction<I, V>(readValues: ReadValueFunction<I, V>, equalityComparator: EqualityComparatorFunction<V>): CompareEqualityWithValueFromItemsFunction<I, V>;
 /**
@@ -106,5 +114,13 @@ export type CompareEqualityWithValueFromItemsFunctionFactory<I, V> = ((equalityC
  * fn(undefined, undefined); // true
  * fn(0, 1);           // false
  * ```
+ *
+ * @dbxUtil
+ * @dbxUtilCategory value
+ * @dbxUtilKind factory
+ * @dbxUtilTags value, comparator, equality, factory, read, reuse
+ * @dbxUtilRelated compare-equality-with-value-from-items-function, safe-equality-comparator-function
+ *
+ * @__NO_SIDE_EFFECTS__
  */
 export declare function compareEqualityWithValueFromItemsFunctionFactory<I, V>(readValues: ReadValueFunction<I, V>): CompareEqualityWithValueFromItemsFunctionFactory<I, V>;