@dereekb/util 13.10.9 → 13.11.0

package/src/lib/path/path.d.ts

@@ -5,13 +5,46 @@ import { type FactoryWithRequiredInput } from '../getter/getter';
 import { type PrimativeValue } from '../type';
 import { type Maybe } from '../value/maybe.type';
 import { type IndexRangeInput } from '../value/indexed';
+/**
+ * The forward-slash character used to separate parts of a slash path.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind const
+ * @dbxUtilTags path, slash, separator, constant, delimiter
+ * @dbxUtilRelated slash-path-file-type-separator, slash-path-parts
+ */
 export declare const SLASH_PATH_SEPARATOR = "/";
+/**
+ * The dot character used to separate the file extension from the file name within a slash path.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind const
+ * @dbxUtilTags path, slash, separator, dot, file-type, extension, constant
+ * @dbxUtilRelated slash-path-separator, slash-path-type, slash-path-details
+ */
 export declare const SLASH_PATH_FILE_TYPE_SEPARATOR = ".";
 export type SlashPathSeparatorString = typeof SLASH_PATH_SEPARATOR;
 export type SlashFileTypeSeparatorString = typeof SLASH_PATH_FILE_TYPE_SEPARATOR;
+/**
+ * The default set of characters that are considered illegal in a slash path.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind const
+ * @dbxUtilTags path, slash, illegal, characters, default, sanitize, validate
+ * @dbxUtilRelated default-slash-path-illegal-character-replacement, slash-path-validation-factory
+ */
 export declare const DEFAULT_SLASH_PATH_ILLEGAL_CHARACTERS: string[];
 /**
  * Default replacement character for illegal characters.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind const
+ * @dbxUtilTags path, slash, illegal, replacement, default, sanitize
+ * @dbxUtilRelated default-slash-path-illegal-characters, slash-path-validation-factory
  */
 export declare const DEFAULT_SLASH_PATH_ILLEGAL_CHARACTER_REPLACEMENT = "_";
 /**
@@ -91,6 +124,11 @@ export type SlashPathType = 'folder' | 'file' | 'typedfile' | 'invalid';
 /**
  * Determines the type of a slash path string.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, type, classify, file, folder, typed, detect
+ * @dbxUtilRelated is-slash-path-file, is-slash-path-folder, is-slash-path-typed-file, is-valid-slash-path
+ *
  * @param input - The slash path to classify.
  * @returns The path type classification.
  */
@@ -98,6 +136,11 @@ export declare function slashPathType(input: SlashPath): SlashPathType;
 /**
  * Type guard that checks if the input is a file path (typed or untyped).
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, file, type-guard, predicate, check, is
+ * @dbxUtilRelated is-slash-path-typed-file, is-slash-path-folder, slash-path-type
+ *
  * @param input - The string to check.
  * @returns Whether the input is a file path.
  */
@@ -105,6 +148,11 @@ export declare function isSlashPathFile(input: string): input is SlashPathFile;
 /**
  * Type guard that checks if the input is a typed file path (contains a file extension).
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, file, extension, type-guard, predicate, typed
+ * @dbxUtilRelated is-slash-path-file, is-slash-path-folder, slash-path-type
+ *
  * @param input - The string to check.
  * @returns Whether the input is a typed file path.
  */
@@ -112,6 +160,11 @@ export declare function isSlashPathTypedFile(input: string): input is SlashPathT
 /**
  * Type guard that checks if the input is a folder path (ends with a slash).
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, folder, directory, type-guard, predicate, trailing
+ * @dbxUtilRelated is-slash-path-file, is-valid-slash-path, slash-path-type
+ *
  * @param input - The string to check.
  * @returns Whether the input is a folder path.
  */
@@ -119,6 +172,11 @@ export declare function isSlashPathFolder(input: string): input is SlashPathFold
 /**
  * Type guard that checks if the input is a valid slash path (not 'invalid' type).
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, valid, type-guard, predicate, check, validate
+ * @dbxUtilRelated slash-path-type, slash-path-validation-factory, slash-path-invalid-error
+ *
  * @param input - The string to check.
  * @returns Whether the input is a valid slash path.
  */
@@ -126,6 +184,11 @@ export declare function isValidSlashPath(input: string): input is SlashPath;
 /**
  * Returns the last part of the slash path.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, name, last, basename, leaf, file, folder
+ * @dbxUtilRelated slash-path-parts, slash-path-details, isolate-slash-path
+ *
  * @param slashPath - The path to extract the name from.
  * @returns The last part of the path (file name or folder name).
  */
@@ -133,6 +196,11 @@ export declare function slashPathName(slashPath: SlashPath): SlashPathPart;
 /**
  * Returns each section of a SlashPath.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, split, parts, segments, sections, components
+ * @dbxUtilRelated slash-path-name, slash-path-details, isolate-slash-path
+ *
  * @param slashPath - The path to split.
  * @returns Array of non-empty path segments.
  */
@@ -151,6 +219,12 @@ export type SlashPathStartTypeFactory = SlashPathFunction;
 /**
  * Creates a function that enforces the specified start type on a slash path.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind factory
+ * @dbxUtilTags path, slash, factory, start-type, relative, absolute, normalize
+ * @dbxUtilRelated to-relative-slash-path-start-type, to-absolute-slash-path-start-type, slash-path-factory
+ *
  * @param type - The start type to enforce.
  * @returns A function that transforms paths to the specified start type.
  */
@@ -164,6 +238,11 @@ export declare const ALL_SLASH_PATH_FILE_TYPE_SEPARATORS_REGEX: RegExp;
 /**
  * Converts a slash path to a relative path by removing all leading slashes.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, relative, leading, strip, normalize, convert
+ * @dbxUtilRelated to-absolute-slash-path-start-type, slash-path-start-type-factory
+ *
  * @param input - The slash path to convert.
  * @returns A relative path without leading slashes.
  */
@@ -199,6 +278,12 @@ export interface SlashPathFolderFactoryConfig {
 /**
  * Creates a SlashPathFolderFactory.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind factory
+ * @dbxUtilTags path, slash, folder, factory, validate, normalize, trailing-slash
+ * @dbxUtilRelated slash-path-folder, slash-path-validation-factory, add-trailing-slash
+ *
  * @param config Configuration options for the factory.
  * @returns A SlashPathFolderFactory.
  */
@@ -208,6 +293,11 @@ export declare function slashPathFolderFactory(config?: SlashPathFolderFactoryCo
  *
  * If the input is a file, the folder of the file is returned instead.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, folder, convert, normalize, validate, directory
+ * @dbxUtilRelated slash-path-folder-factory, slash-path-details, add-trailing-slash
+ *
  * @param input - the string path to convert to a folder path
  * @param config - optional configuration controlling path type inference and invalid-path handling
  * @returns a valid slash path folder string with a trailing slash, or an empty string for relative root
@@ -216,6 +306,11 @@ export declare function slashPathFolder(input: string, config?: SlashPathFolderF
 /**
  * Converts a slash path to an absolute path by ensuring exactly one leading slash.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, absolute, leading, prefix, normalize, convert
+ * @dbxUtilRelated to-relative-slash-path-start-type, slash-path-start-type-factory, fix-multi-slashes-in-slash-path
+ *
  * @param input - The slash path to convert.
  * @returns An absolute path starting with a single slash.
  */
@@ -223,6 +318,11 @@ export declare function toAbsoluteSlashPathStartType(input: SlashPath): SlashPat
 /**
  * Replaces consecutive double slashes with single slashes.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, fix, collapse, double, normalize, dedupe
+ * @dbxUtilRelated merge-slash-paths, replace-multiple-file-paths-in-slash-path
+ *
  * @param input - The slash path to fix.
  * @returns The path with double slashes collapsed.
  */
@@ -230,6 +330,11 @@ export declare function fixMultiSlashesInSlashPath(input: SlashPath): SlashPath;
 /**
  * Replaces consecutive double slashes with single slashes. Alias for {@link fixMultiSlashesInSlashPath}.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, alias, collapse, double, normalize
+ * @dbxUtilRelated fix-multi-slashes-in-slash-path, merge-slash-paths
+ *
  * @param input - The slash path to fix.
  * @returns The path with double slashes collapsed.
  */
@@ -237,6 +342,11 @@ export declare function replaceMultipleFilePathsInSlashPath(input: SlashPath): S
 /**
  * Removes all trailing slashes from a slash path.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, trim, trailing, strip, remove, normalize
+ * @dbxUtilRelated add-trailing-slash, remove-trailing-file-type-separators
+ *
  * @param input - The slash path to trim.
  * @returns The path without trailing slashes.
  */
@@ -244,6 +354,11 @@ export declare function removeTrailingSlashes(input: SlashPath): SlashPath;
 /**
  * Removes all trailing dots from a slash path.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, trim, trailing, dot, file-type, strip, normalize
+ * @dbxUtilRelated remove-trailing-slashes, replace-invalid-file-path-type-separators-in-slash-path
+ *
  * @param input - The slash path to trim.
  * @returns The path without trailing dots.
  */
@@ -251,6 +366,11 @@ export declare function removeTrailingFileTypeSeparators(input: SlashPath): Slas
 /**
  * Adds a trailing slash to the input if it does not already have one.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, trailing, append, folder, ensure, normalize
+ * @dbxUtilRelated remove-trailing-slashes, slash-path-folder, slash-path-folder-factory
+ *
  * @param input A slash path.
  * @returns A slash path folder.
  */
@@ -258,6 +378,11 @@ export declare function addTrailingSlash(input: SlashPath): SlashPathFolder;
 /**
  * Replaces all extra and invalidate FilePathTypeSeparator values from the SlashPath, returning a valid SlashPath.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, dot, file-type, replace, sanitize, fix, validate
+ * @dbxUtilRelated replace-invalid-file-path-type-separators-in-slash-path-function, slash-path-validation-factory
+ *
  * @param input
  * @param replaceWith
  * @returns
@@ -266,6 +391,12 @@ export declare function replaceInvalidFilePathTypeSeparatorsInSlashPath(input: S
 /**
  * Creates a function that replaces all extra and invalidate FilePathTypeSeparator values from the SlashPath, returning a valid SlashPath.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind factory
+ * @dbxUtilTags path, slash, dot, file-type, factory, replace, sanitize, validate
+ * @dbxUtilRelated replace-invalid-file-path-type-separators-in-slash-path, slash-path-validation-factory
+ *
  * @param input
  * @param replaceWith
  * @returns
@@ -302,6 +433,12 @@ export interface SlashPathValidationFactoryConfig {
 /**
  * Creates a validation/fixup function for slash paths that replaces illegal characters and extra dots.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind factory
+ * @dbxUtilTags path, slash, validate, factory, sanitize, illegal, replace, fix
+ * @dbxUtilRelated is-valid-slash-path, replace-invalid-file-path-type-separators-in-slash-path-function, slash-path-factory, slash-path-invalid-error
+ *
  * @param config - Configuration for validation behavior.
  * @returns A function that validates and fixes a slash path.
  */
@@ -327,6 +464,12 @@ export interface SlashPathFactoryConfig {
 /**
  * Creates a factory function that merges path segments together with optional base path, start type enforcement, and validation.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind factory
+ * @dbxUtilTags path, slash, factory, merge, base, start-type, validate, normalize
+ * @dbxUtilRelated merge-slash-paths, slash-path-validation-factory, slash-path-start-type-factory
+ *
  * @param config - Configuration for path generation.
  * @returns A factory function that merges input paths into a single validated slash path.
  */
@@ -334,6 +477,11 @@ export declare function slashPathFactory(config?: SlashPathFactoryConfig): Slash
 /**
  * Merges an array of path segments into a single slash path, filtering nullish values and collapsing double slashes.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, merge, join, concat, segments, normalize, dedupe
+ * @dbxUtilRelated slash-path-factory, fix-multi-slashes-in-slash-path, slash-path-parts
+ *
  * @param paths - Array of path segments to merge.
  * @returns The merged slash path.
  */
@@ -341,12 +489,22 @@ export declare function mergeSlashPaths(paths: Maybe<SlashPath>[]): SlashPath;
 /**
  * Creates an Error indicating that a slash path is invalid.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, error, invalid, throw, validate
+ * @dbxUtilRelated is-valid-slash-path, slash-path-validation-factory
+ *
  * @returns A new Error with a descriptive message.
  */
 export declare function slashPathInvalidError(): Error;
 /**
  * Splits the path and returns the items at the given ranges.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, isolate, slice, range, segments, extract, sub-path
+ * @dbxUtilRelated isolate-slash-path-function, slash-path-parts, slash-path-details
+ *
  * @param path - The path to isolate parts from.
  * @param range - Index range defining which path segments to extract.
  * @returns A new slash path containing only the segments within the range.
@@ -378,6 +536,12 @@ export type IsolateSlashPathFunction = (path: SlashPath) => SlashPath;
 /**
  * Creates an IsolateSlashPathFunction.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind factory
+ * @dbxUtilTags path, slash, isolate, factory, slice, range, segments, sub-path
+ * @dbxUtilRelated isolate-slash-path, slash-path-parts, slash-path-details
+ *
  * @param config - Configuration with range, optional start type, and file mode.
  * @returns A function that isolates path segments within the configured range.
  */
@@ -449,6 +613,11 @@ export interface SlashPathDetails {
 /**
  * Returns the details of a path.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, details, parse, decompose, file, folder, extension, parts
+ * @dbxUtilRelated slash-path-type, slash-path-parts, slash-path-folder, slash-path-name
+ *
  * @param path The path to get details for.
  * @returns The details of the path.
  */
@@ -479,6 +648,11 @@ export type SlashPathPathMatcherPath = ArrayOrValue<SlashPathPathMatcherPart>;
 /**
  * Expands the input matcher path into decision functions.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, matcher, expand, decision, predicate, wildcard, build
+ * @dbxUtilRelated slash-path-path-matcher, slash-path-sub-path-matcher, slash-path-path-matcher-config
+ *
  * @param path - Matcher path parts to expand into decision functions.
  * @returns Array of decision functions for each path part.
  */
@@ -550,6 +724,11 @@ export type SlashPathPathMatcherConfigInput<N extends PrimativeValue = Primative
 /**
  * Creates a SlashPathPathMatcherConfig from the input.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilTags path, slash, matcher, config, normalize, coerce
+ * @dbxUtilRelated slash-path-path-matcher, slash-path-sub-path-matcher
+ *
  * @param input The configuration input.
  * @returns The configuration.
  */
@@ -557,6 +736,12 @@ export declare function slashPathPathMatcherConfig<N extends PrimativeValue = Pr
 /**
  * Creates a SlashPathPathMatcher.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind factory
+ * @dbxUtilTags path, slash, matcher, factory, predicate, wildcard, target, compare
+ * @dbxUtilRelated slash-path-sub-path-matcher, expand-slash-path-path-matcher-part-to-decision-functions, slash-path-path-matcher-config
+ *
  * @param input - the matcher configuration, which may be a target path string, an array of path parts, or a full config object
  * @returns The matcher.
  */
@@ -615,6 +800,12 @@ export type SlashPathSubPathMatcher = (path: SlashPath) => SlashPathSubPathMatch
 /**
  * Creates a SlashPathSubPathMatcher.
  *
+ * @dbxUtil
+ * @dbxUtilCategory path
+ * @dbxUtilKind factory
+ * @dbxUtilTags path, slash, matcher, sub-path, factory, base-path, prefix, predicate
+ * @dbxUtilRelated slash-path-path-matcher, expand-slash-path-path-matcher-part-to-decision-functions
+ *
  * @param config The configuration for the matcher.
  * @returns The matcher.
  */

package/src/lib/promise/is.d.ts

@@ -1,6 +1,11 @@
 /**
  * Checks whether the input value is a native Promise by testing for a `.then` method.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilTags promise, type-guard, async, then, check
+ * @dbxUtilRelated is-promise-like, as-promise
+ *
  * @param obj - The value to test.
  * @returns `true` if the value is a Promise, `false` otherwise.
  */
@@ -9,6 +14,11 @@ export declare function isPromise<T, S>(obj: Promise<T> | S): obj is Promise<T>;
  * Checks whether the input value is PromiseLike (i.e., has a `.then` method), which
  * includes both native Promises and custom thenables.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilTags promise, type-guard, async, then, thenable, check
+ * @dbxUtilRelated is-promise, as-promise
+ *
  * @param obj - The value to test.
  * @returns `true` if the value is PromiseLike, `false` otherwise.
  */

package/src/lib/promise/poll.d.ts

@@ -22,6 +22,11 @@ export interface PollConfig {
 /**
  * Polls at a regular interval until a condition is met or the maximum number of attempts is reached.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilTags promise, poll, wait, retry, condition, async, interval
+ * @dbxUtilRelated wait-for-ms, perform-task-loop
+ *
  * @param config - Polling configuration including check function, wait interval, and max attempts.
  * @param config.check - predicate function that returns true when the polling condition has been satisfied
  * @param config.wait - milliseconds to wait between polling iterations; defaults to 250

package/src/lib/promise/promise.d.ts

@@ -16,6 +16,11 @@ export type RunAsyncTasksForValuesConfig<T = unknown> = Omit<PerformAsyncTasksCo
 /**
  * Runs a single async task and returns the resulting value. Always configured to throw on failure.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilTags promise, async, task, retry, run, value
+ * @dbxUtilRelated perform-async-task, run-async-tasks-for-values, perform-async-tasks
+ *
  * @param taskFn - The async task to execute.
  * @param config - Optional configuration for retries and retry behavior.
  * @returns The value produced by the task, or undefined if the task produced no value.
@@ -26,6 +31,11 @@ export declare function runAsyncTaskForValue<O>(taskFn: () => Promise<O>, config
  * Runs an async task for each input value and returns an array of the resulting values.
  * Always configured to throw on failure.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilTags promise, async, tasks, parallel, batch, retry, run, values
+ * @dbxUtilRelated perform-async-tasks, run-async-task-for-value
+ *
  * @param input - The array of input values to process.
  * @param taskFn - The async task function to run for each input value.
  * @param config - Optional configuration for parallelism and retries.
@@ -106,6 +116,11 @@ export interface PerformAsyncTasksConfig<I = unknown, K extends PrimativeKey = P
  * Performs async tasks for each input value with configurable retry and parallelism behavior.
  * Useful for operations that may experience optimistic concurrency collisions.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilTags async, promise, parallel, retry, task, batch, concurrency, throttle
+ * @dbxUtilRelated perform-tasks-in-parallel, perform-async-task
+ *
  * @param input - The array of input values to process.
  * @param taskFn - The async function to execute for each input.
  * @param config - Configuration for retries, parallelism, and error handling.
@@ -116,6 +131,11 @@ export declare function performAsyncTasks<I, O = unknown, K extends PrimativeKey
 /**
  * Performs a single async task with configurable retry behavior and returns the result with success status.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilTags promise, async, task, retry, run, success
+ * @dbxUtilRelated perform-async-tasks, run-async-task-for-value
+ *
  * @param taskFn - The async task to execute.
  * @param config - Optional configuration for retries and error handling.
  * @returns A result object containing the value (if successful) and a success flag.

package/src/lib/promise/promise.type.d.ts

@@ -5,6 +5,10 @@ export type PromiseOrValue<T> = Promise<T> | T;
 /**
  * Wraps the input in a resolved Promise if it is not already a Promise.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilTags promise, async, normalize, resolve, ensure
+ *
  * @param input - A value or Promise to normalize into a Promise.
  * @returns A Promise that resolves to the input value.
  */

package/src/lib/promise/wait.d.ts

@@ -2,6 +2,11 @@
  * Returns a Promise that resolves after the specified number of milliseconds.
  * Optionally resolves with the provided value.
  *
+ * @dbxUtil
+ * @dbxUtilCategory promise
+ * @dbxUtilTags promise, wait, sleep, delay, async, timeout
+ * @dbxUtilRelated perform-async-tasks, poll
+ *
  * @param ms - The number of milliseconds to wait before resolving.
  * @param value - An optional value to resolve the Promise with.
  * @returns A Promise that resolves after the specified delay.

package/src/lib/set/set.d.ts

@@ -11,6 +11,11 @@ export type AllOrNoneSelection = 'all' | 'none';
 /**
  * Converts an {@link IterableOrValue} into a Set. Strings are treated as single values rather than character iterables.
  *
+ * @dbxUtil
+ * @dbxUtilCategory set
+ * @dbxUtilTags set, convert, normalize, ensure, unique, dedupe
+ * @dbxUtilRelated add-to-set, iterable-to-set
+ *
  * @param values - The value or iterable to convert.
  * @returns A new Set containing all values.
  */
@@ -34,6 +39,11 @@ export declare function addToSetCopy<T>(set: Maybe<Set<T>>, values: Maybe<Iterab
 /**
  * Adds one or more values to the given set in place.
  *
+ * @dbxUtil
+ * @dbxUtilCategory set
+ * @dbxUtilTags set, add, mutate, insert, in-place
+ * @dbxUtilRelated add-to-set-copy, remove-from-set, toggle-in-set
+ *
  * @param set - The set to add values to.
  * @param values - The value or iterable of values to add.
  */
@@ -49,6 +59,11 @@ export declare function toggleInSetCopy<T>(set: Set<T>, values: Maybe<IterableOr
 /**
  * Toggles values in the set in place: adds if absent, removes if present.
  *
+ * @dbxUtil
+ * @dbxUtilCategory set
+ * @dbxUtilTags set, toggle, add, remove, mutate, in-place
+ * @dbxUtilRelated toggle-in-set-copy, add-to-set, remove-from-set
+ *
  * @param set - The set to modify.
  * @param values - The values to toggle.
  */

package/src/lib/sort.d.ts

@@ -44,6 +44,11 @@ export type SortDescendingCompareFunction<T> = SortCompareFunction<T>;
 /**
  * Convenience function that reverses the order of the sorted values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory sort
+ * @dbxUtilTags sort, reverse, compare, descending, ascending, order
+ * @dbxUtilRelated compare-fn-order, compare-with-mapped-values-function
+ *
  * @param compareFn - the comparison function whose order should be reversed
  * @returns a new comparison function with the opposite sort direction
  */
@@ -54,6 +59,11 @@ export declare function reverseCompareFn<T>(compareFn: SortDescendingCompareFunc
  *
  * The input comparison function must be in ascending order.
  *
+ * @dbxUtil
+ * @dbxUtilCategory sort
+ * @dbxUtilTags sort, order, ascending, descending, compare, direction
+ * @dbxUtilRelated reverse-compare-fn, compare-with-mapped-values-function
+ *
  * @param ascendingCompareFn - a comparison function that sorts in ascending order
  * @param order - the desired sort direction; defaults to 'asc'
  * @returns the original function if ascending, or a reversed version if descending
@@ -67,6 +77,12 @@ export declare function compareFnOrder<T>(ascendingCompareFn: AscendingSortCompa
  * @param comparesFunction - Compares the mapped values.
  * @returns A sort comparison function for the original type.
  *
+ * @dbxUtil
+ * @dbxUtilCategory sort
+ * @dbxUtilKind factory
+ * @dbxUtilTags sort, compare, map, derive, factory, by, key
+ * @dbxUtilRelated reverse-compare-fn, compare-fn-order
+ *
  * @example
  * ```ts
  * const byName = compareWithMappedValuesFunction(

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

@@ -12,6 +12,11 @@
  *
  * Empty segments (e.g. leading underscores in `_USER_ID`) are skipped.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilTags string, case, camelcase, snakecase, screaming, convert, transform
+ * @dbxUtilRelated camel-or-pascal-to-screaming-snake
+ *
  * @param input The SCREAMING_SNAKE_CASE input.
  * @returns The camelCase form.
  */
@@ -22,6 +27,11 @@ export declare function screamingSnakeToCamelCase(input: string): string;
  * Each upper-case character (other than the first) is preceded by an
  * underscore, then the whole result is upper-cased.
  *
+ * @dbxUtil
+ * @dbxUtilCategory string
+ * @dbxUtilTags string, case, camelcase, pascalcase, snakecase, screaming, convert, transform
+ * @dbxUtilRelated screaming-snake-to-camel-case
+ *
  * @param input The camelCase / PascalCase input.
  * @returns The SCREAMING_SNAKE_CASE form.
  */