@dereekb/util 13.10.9 → 13.11.1

package/src/lib/cache/cache.memory.d.ts

@@ -0,0 +1,39 @@
+import { type Maybe } from '../value/maybe.type';
+import { type AsyncKeyedValueCache, type AsyncValueCache } from './cache';
+/**
+ * Creates an in-memory {@link AsyncValueCache} backed by a single closure-scoped variable.
+ *
+ * Useful as the inner of {@link memoizeAsyncValueCache} and as a stand-in for tests.
+ *
+ * @param initialValue - Optional starting value for the cache. When omitted (or null), the cache starts empty and {@link AsyncValueCache.load} resolves to undefined.
+ * @returns An {@link AsyncValueCache} that stores the latest written value in process memory.
+ *
+ * @example
+ * ```ts
+ * const cache = inMemoryAsyncValueCache<string>('hello');
+ * await cache.load();          // 'hello'
+ * await cache.update('world');
+ * await cache.load();          // 'world'
+ * ```
+ */
+export declare function inMemoryAsyncValueCache<T>(initialValue?: Maybe<T>): AsyncValueCache<T>;
+/**
+ * Creates an in-memory {@link AsyncKeyedValueCache} backed by a closure-scoped record.
+ *
+ * Useful as the inner of {@link memoizeAsyncKeyedValueCache} and as a stand-in for tests.
+ *
+ * Backed by a null-prototype object so inherited properties (`toString`, `hasOwnProperty`, etc.)
+ * are never returned from `get` and `__proto__` keys cannot mutate the prototype chain.
+ *
+ * @param initialEntries - Optional starting entries for the cache. When omitted (or null), the cache starts empty.
+ * @returns An {@link AsyncKeyedValueCache} that stores entries in process memory.
+ *
+ * @example
+ * ```ts
+ * const cache = inMemoryAsyncKeyedValueCache<number>({ a: 1 });
+ * await cache.get('a');        // 1
+ * await cache.set('b', 2);
+ * await cache.load();          // { a: 1, b: 2 }
+ * ```
+ */
+export declare function inMemoryAsyncKeyedValueCache<T>(initialEntries?: Maybe<Record<string, T>>): AsyncKeyedValueCache<T>;

package/src/lib/cache/cache.merge.d.ts

@@ -0,0 +1,48 @@
+import { type AsyncKeyedValueCache, type AsyncValueCache } from './cache';
+/**
+ * Composes multiple {@link AsyncValueCache} instances into a single read-from-first-write-to-all cache.
+ *
+ * - {@link AsyncValueCache.load} returns the first non-null/undefined value from the input caches in order.
+ * - {@link AsyncValueCache.update} writes the value to every input cache, propagating from the
+ *   lowest-precedence (slowest, source-of-truth) tier up to the highest-precedence (fastest) tier
+ *   so a failed write to the backing store is not masked by a successful write to memory.
+ * - {@link AsyncValueCache.clear} clears every input cache in the same lower-to-higher order.
+ *
+ * Useful for memory-then-disk layering or for combining a fast tier with a slow source-of-truth tier.
+ *
+ * @param caches - Ordered tiers from highest-precedence (fastest, e.g. memory) to lowest-precedence (source-of-truth, e.g. disk). Reads honor this order; writes propagate in reverse.
+ * @returns A single {@link AsyncValueCache} layered across the provided tiers.
+ *
+ * @example
+ * ```ts
+ * const layered = mergeAsyncValueCaches<string>([
+ *   inMemoryAsyncValueCache(),
+ *   diskBackedAsyncValueCache()
+ * ]);
+ * await layered.update('hello'); // writes to disk first, then memory
+ * await layered.load();          // returns from memory if present
+ * ```
+ */
+export declare function mergeAsyncValueCaches<T>(caches: ReadonlyArray<AsyncValueCache<T>>): AsyncValueCache<T>;
+/**
+ * Composes multiple {@link AsyncKeyedValueCache} instances into a single read-from-first-write-to-all cache.
+ *
+ * - {@link AsyncKeyedValueCache.get} returns the first non-null/undefined value from the input caches in order for a given key.
+ * - {@link AsyncKeyedValueCache.load} returns a merged record where earlier caches' entries take precedence over later caches'.
+ * - Writes ({@link AsyncKeyedValueCache.set} / {@link AsyncKeyedValueCache.remove}) propagate to every input cache.
+ * - {@link AsyncKeyedValueCache.clear} clears every input cache.
+ *
+ * @param caches - Ordered tiers from highest-precedence (fastest, e.g. memory) to lowest-precedence (source-of-truth, e.g. disk). Reads honor this order; writes propagate in reverse.
+ * @returns A single {@link AsyncKeyedValueCache} layered across the provided tiers.
+ *
+ * @example
+ * ```ts
+ * const layered = mergeAsyncKeyedValueCaches<number>([
+ *   inMemoryAsyncKeyedValueCache(),
+ *   diskBackedAsyncKeyedValueCache()
+ * ]);
+ * await layered.set('a', 1);     // writes to disk first, then memory
+ * await layered.get('a');        // returns from memory if present
+ * ```
+ */
+export declare function mergeAsyncKeyedValueCaches<T>(caches: ReadonlyArray<AsyncKeyedValueCache<T>>): AsyncKeyedValueCache<T>;

package/src/lib/cache/index.d.ts

@@ -0,0 +1,4 @@
+export * from './cache';
+export * from './cache.memory';
+export * from './cache.memoize';
+export * from './cache.merge';

package/src/lib/contact/domain.d.ts

@@ -11,6 +11,11 @@ export type EmailAddressDomain = string;
 /**
  * Extracts unique domain names from a list of email addresses (case-insensitive).
  *
+ * @dbxUtil
+ * @dbxUtilCategory contact
+ * @dbxUtilTags email, domain, extract, unique, dedupe, case-insensitive
+ * @dbxUtilRelated read-domain-from-email-address, read-email-domain-from-url-or-email-address
+ *
  * @param addresses - Array of email addresses to extract domains from
  * @returns Array of unique lowercase domain strings
  */
@@ -18,6 +23,11 @@ export declare function readDomainsFromEmailAddresses(addresses: EmailAddress[])
 /**
  * Extracts the domain portion from a single email address.
  *
+ * @dbxUtil
+ * @dbxUtilCategory contact
+ * @dbxUtilTags email, domain, extract, parse, lowercase
+ * @dbxUtilRelated read-domains-from-email-addresses, read-email-domain-from-url-or-email-address
+ *
  * @param address - The email address to extract the domain from
  * @returns The lowercase domain string
  */
@@ -33,6 +43,11 @@ export declare function readDomainFromEmailAddress(address: EmailAddress): Email
  *
  * The "www." prefix is stripped from URL-style inputs since emails typically don't use it.
  *
+ * @dbxUtil
+ * @dbxUtilCategory contact
+ * @dbxUtilTags email, domain, url, extract, normalize, parse, www
+ * @dbxUtilRelated read-domain-from-email-address, read-domains-from-email-addresses
+ *
  * @param urlLikeInput - A URL, email address, or domain string
  * @returns The extracted domain
  */

package/src/lib/contact/email.d.ts

@@ -32,6 +32,11 @@ export type EmailParticipantString = string;
  * Converts an EmailParticipant object to a formatted string representation.
  * The format is: "name<email>" or "<email>" if no name is provided.
  *
+ * @dbxUtil
+ * @dbxUtilCategory contact
+ * @dbxUtilTags email, participant, convert, format, serialize, name
+ * @dbxUtilRelated convert-email-participant-string-to-participant, coerce-to-email-participants
+ *
  * @param participant - The email participant to convert
  * @returns A formatted string representation of the participant
  */
@@ -40,6 +45,11 @@ export declare function convertParticipantToEmailParticipantString(participant:
  * Converts a formatted participant string into an EmailParticipant object.
  * Parses strings in the format "name<email>" or "<email>".
  *
+ * @dbxUtil
+ * @dbxUtilCategory contact
+ * @dbxUtilTags email, participant, parse, deserialize, name, address
+ * @dbxUtilRelated convert-participant-to-email-participant-string, coerce-to-email-participants
+ *
  * @param participantString - The string to parse
  * @returns An EmailParticipant object with the extracted name and email
  */
@@ -48,6 +58,11 @@ export declare function convertEmailParticipantStringToParticipant(participantSt
  * Combines an array of EmailParticipants with an array of email addresses.
  * Email addresses that don't already exist in the participants array are converted to EmailParticipant objects.
  *
+ * @dbxUtil
+ * @dbxUtilCategory contact
+ * @dbxUtilTags email, participant, merge, combine, dedupe, coerce, normalize
+ * @dbxUtilRelated convert-participant-to-email-participant-string, convert-email-participant-string-to-participant
+ *
  * @param options - Object containing participants and/or emails arrays
  * @param options.participants - Array of existing EmailParticipant objects
  * @param options.emails - Array of email addresses to include

package/src/lib/date/date.unix.d.ts

@@ -18,6 +18,11 @@ export type DateOrUnixDateTimeSecondsNumber = Date | UnixDateTimeSecondsNumber;
 /**
  * Converts a Date object or unix timestamp number to a unix timestamp number.
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags date, unix, seconds, timestamp, convert, normalize
+ * @dbxUtilRelated unix-date-time-seconds-number-from-date, date-from-date-or-time-seconds-number
+ *
  * @param input - Date object or unix timestamp number to convert
  * @returns Unix timestamp number if input is valid, null/undefined if input is null/undefined
  */
@@ -25,12 +30,22 @@ export declare function unixDateTimeSecondsNumberFromDateOrTimeNumber(input: May
 /**
  * Gets the current time as a unix timestamp number.
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags date, unix, seconds, timestamp, now, current, time
+ * @dbxUtilRelated unix-date-time-seconds-number-from-date
+ *
  * @returns Current time as unix timestamp number
  */
 export declare function unixDateTimeSecondsNumberForNow(): UnixDateTimeSecondsNumber;
 /**
  * Converts a Date object to a unix timestamp number.
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags date, unix, seconds, timestamp, convert, epoch
+ * @dbxUtilRelated unix-date-time-seconds-number-to-date, unix-date-time-seconds-number-for-now
+ *
  * @param date - Date object to convert
  * @returns Unix timestamp number if date is valid, null/undefined if date is null/undefined
  */
@@ -48,6 +63,11 @@ export declare function dateFromDateOrTimeSecondsNumber(input: Maybe<DateOrUnixD
 /**
  * Converts a unix timestamp number to a Date object.
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags date, unix, seconds, timestamp, convert, parse
+ * @dbxUtilRelated unix-date-time-seconds-number-from-date, date-from-date-or-time-seconds-number
+ *
  * @param dateTimeNumber - Unix timestamp number to convert
  * @returns Date object if timestamp is valid, null/undefined if timestamp is null/undefined
  */

package/src/lib/date/expires.d.ts

@@ -10,40 +10,53 @@ export interface Expires {
     expiresAt?: Maybe<Date>;
 }
 /**
- * Input configuration for the expirationDetails() function.
+ * Input configuration for the {@link expirationDetails}() function.
  *
- * The priority that the expiration calculation uses takes the following order:
- * 1. expires - An existing Expires object
- * 2. expiresAt - A specific date when something expires
- * 3. expiresFromDate + expiresIn - A base date plus a duration
+ * The expiration date is resolved from the first matching field in this order:
+ * 1. `expires.expiresAt` — pull from an existing Expires object
+ * 2. `expiresAt` — direct expiration date
+ * 3. `expiresFromDate + expiresIn` — base date plus a duration (negative `expiresIn` shifts the date earlier, useful for buffers/clock skew)
+ *
+ * @example
+ * // Direct expiration date.
+ * expirationDetails({ expiresAt: tokenExpiry });
+ *
+ * // From an existing Expires object.
+ * expirationDetails({ expires: token });
+ *
+ * // Throttle / TTL: "next allowed run" is `lastRunAt + throttleMs`.
+ * expirationDetails({ expiresFromDate: lastRunAt, expiresIn: throttleMs });
+ *
+ * // Pre-emptive refresh: treat the token as expired `bufferMs` before its real expiration.
+ * expirationDetails({ expiresFromDate: token.expiresAt, expiresIn: -bufferMs, now: new Date(nowMs) });
  */
 export interface ExpirationDetailsInput<T extends Expires = Expires> extends Expires {
     /**
-     * Existing expires instance to use.
-     *
-     * If provided/
+     * Existing expires instance to use. Highest priority — wins over `expiresAt` and `expiresFromDate`/`expiresIn`.
      */
     expires?: Maybe<T>;
     /**
-     * Default current now time to use.
+     * Default current "now" time to use.
      *
-     * If not set, functions will use the current time when they are called.
+     * If not set, functions will use the current time (`new Date()`) when they are called. Always overridable per-call via the `nowOverride` argument on `hasExpired()`/`getExpirationDate()`.
      */
     now?: Maybe<Date>;
     /**
-     * The base date or time number to calculate expirations from.
+     * The base date or epoch milliseconds to calculate expirations from. Combined with `expiresIn` to produce the expiration date.
      *
-     * If not defined, the expiresFromDate is considered to have never been run/set.
+     * If null/undefined and `expiresIn` is set, falls back to "now" unless `defaultExpiresFromDateToNow` is false.
      */
     expiresFromDate?: Maybe<DateOrUnixDateTimeMillisecondsNumber>;
     /**
-     * If true, the "expiresFromDate" will default to the calculated now time when calculating the expiration.
+     * If true (default), a missing `expiresFromDate` is treated as "now" when computing `expiresFromDate + expiresIn`.
+     *
+     * Set to false when a missing base date should mean "never run" (e.g. throttle predicates that should not consider a never-run action throttled).
      *
      * Defaults to true.
      */
     defaultExpiresFromDateToNow?: Maybe<boolean>;
     /**
-     * Time after "now" that expiration will occur.
+     * Offset added to `expiresFromDate` (or "now") to produce the expiration date. Negative values shift the expiration earlier, which is the canonical way to express a clock-skew/refresh buffer.
      */
     expiresIn?: Maybe<Milliseconds>;
 }
@@ -69,8 +82,20 @@ export interface ExpirationDetails<T extends Expires = Expires> {
     getExpirationDate(nowOverride?: Maybe<Date>): Maybe<Date>;
 }
 /**
- * Returns expiration details for the input configuration.
- * Creates an object that can determine when something expires based on various inputs.
+ * Returns an {@link ExpirationDetails} for the given input configuration.
+ *
+ * Use this when you need to ask whether something has expired or what its expiration date is. See {@link ExpirationDetailsInput} for how the expiration date is resolved (`expires` → `expiresAt` → `expiresFromDate + expiresIn`).
+ *
+ * Common patterns:
+ * - **Direct expiration**: `expirationDetails({ expiresAt }).hasExpired()`
+ * - **Wrap an existing object**: `expirationDetails({ expires: token }).hasExpired()`
+ * - **TTL / throttle**: `expirationDetails({ expiresFromDate: lastRunAt, expiresIn: throttleMs })` — see {@link isThrottled}
+ * - **Pre-emptive refresh**: `expirationDetails({ expiresFromDate: expiresAt, expiresIn: -bufferMs })` — treat as expired `bufferMs` before the real expiration, e.g. to refresh a token before it actually dies
+ *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags expiration, expires, expiry, ttl, throttle, refresh, time-to-live
+ * @dbxUtilRelated is-expired, is-throttled, calculate-expiration-date, is-under-threshold, check-atleast-one-not-expired, check-any-have-expired
  *
  * @template T - The type of Expires object
  * @param input - Configuration for calculating expiration
@@ -81,10 +106,34 @@ export declare function expirationDetails<T extends Expires = Expires>(input: Ex
  * Convenience function for calculating and returning the expiration date given the input.
  * This is a shorthand for expirationDetails(input).getExpirationDate().
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags expiration, expires, expiry, ttl, calculate, date
+ * @dbxUtilRelated expiration-details, is-expired
+ *
  * @param input - Input configuration used to calculate the expiration date
  * @returns The calculated expiration date, or null if no expiration is defined
  */
 export declare function calculateExpirationDate(input: ExpirationDetailsInput<Expires>): Maybe<Date>;
+/**
+ * Convenience wrapper around {@link expirationDetails}().hasExpired() that treats null/undefined input or no expiration date as expired.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags expiration, expires, expiry, expired, has-expired, is-expired, ttl
+ * @dbxUtilRelated expiration-details, is-throttled, calculate-expiration-date
+ *
+ * @param input - Expiration configuration. Null/undefined is treated as expired.
+ * @param now - Optional override for the current time. Defaults to the current time. Apply any buffer (e.g. for clock skew or pre-emptive refresh) by shifting this value forward.
+ * @returns True when the input is null/undefined or its expiration date has passed; otherwise false.
+ *
+ * @example
+ * isExpired(null); // true
+ * isExpired({ expiresAt: pastDate }); // true
+ * isExpired({ expiresAt: futureDate }); // false
+ * isExpired({ expiresAt: futureDate }, addMilliseconds(new Date(), 60_000)); // true (when within buffer)
+ */
+export declare function isExpired<T extends Expires = Expires>(input: Maybe<ExpirationDetailsInput<T>>, now?: Maybe<Date>): boolean;
 /**
  * Returns true if the threshold has not passed since the next run time, compared to now.
  *
@@ -93,6 +142,11 @@ export declare function calculateExpirationDate(input: ExpirationDetailsInput<Ex
  * Example:
  * - Should send a notification at max every 2 days. The threshold is 2 days in milliseconds, and "nextRunAt" is the previously calculated date that was originally "now" + "threshold".
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags threshold, throttle, ttl, time-window, rate-limit
+ * @dbxUtilRelated is-throttled, expiration-details
+ *
  * @param threshold The threshold time. Typically this is amount of time that was used to calculate the original "nextRunAt" time.
  * @param nextRunAt Time the next run will occur. If null/undefined, then this function will return false.
  * @param now Optional override for the current time. Defaults to the current time.
@@ -105,6 +159,11 @@ export declare function isUnderThreshold(threshold: Milliseconds, nextRunAt: May
  * Returns true if the throttle time has not passed since the last run time, compared to now.
  * This is useful for rate limiting operations (e.g., "only allow this action once every X milliseconds").
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags throttle, throttled, rate-limit, debounce, ttl, expiration
+ * @dbxUtilRelated expiration-details, is-under-threshold, is-expired
+ *
  * @param throttleTime - Minimum time in milliseconds that must pass between operations
  * @param lastRunAt - Timestamp when the operation was last performed
  * @param now - Optional override for the current time (defaults to the current time)
@@ -117,6 +176,11 @@ export declare function isThrottled(throttleTime: Maybe<Milliseconds>, lastRunAt
  *
  * If the list is empty, returns false.
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags expiration, valid, collection, any
+ * @dbxUtilRelated expiration-details, check-any-have-expired
+ *
  * @param details - Collection of ExpirationDetails to check
  * @returns True if at least one item has not expired, false otherwise
  */
@@ -127,6 +191,11 @@ export declare function checkAtleastOneNotExpired(details: ExpirationDetails<Exp
  *
  * If the list is empty, returns the value specified by defaultIfEmpty.
  *
+ * @dbxUtil
+ * @dbxUtilCategory date
+ * @dbxUtilTags expiration, refresh, collection, any
+ * @dbxUtilRelated expiration-details, check-atleast-one-not-expired
+ *
  * @param details - Collection of ExpirationDetails to check
  * @param defaultIfEmpty - Default value to return if the list is empty (defaults to true)
  * @returns True if any item has expired, or the defaultIfEmpty value for an empty list

package/src/lib/function/function.d.ts

@@ -4,3 +4,8 @@
  * Alias of MAP_IDENTITY, so `isMapIdentityFunction()` will return true for this function.
  */
 export { MAP_IDENTITY as passThrough } from '../value/map';
+/**
+ * No-op function. Useful as a default callback or as a yargs command's `handler` for parent
+ * commands that only register subcommands.
+ */
+export declare function noop(): void;

package/src/lib/getter/getter.d.ts

@@ -47,6 +47,11 @@ export type StringOrGetter = GetterOrValue<string>;
 /**
  * Returns true if the input value is a non-class function (i.e., likely a Getter).
  *
+ * @dbxUtil
+ * @dbxUtilCategory getter
+ * @dbxUtilTags getter, type-guard, function, callable, check
+ * @dbxUtilRelated as-getter, get-value-from-getter
+ *
  * @param value - The value to check
  * @returns True if the value is a non-class function
  */
@@ -54,6 +59,11 @@ export declare function isGetter<T = unknown>(value: unknown): value is Getter<T
 /**
  * If the input is a function, it is executed and the result returned. Otherwise, the value itself is returned.
  *
+ * @dbxUtil
+ * @dbxUtilCategory getter
+ * @dbxUtilTags getter, resolve, value, factory, normalize
+ * @dbxUtilRelated as-getter, is-getter
+ *
  * @param input - A value or a getter/factory function
  * @returns The resolved value
  */
@@ -65,6 +75,11 @@ export declare function getValueFromGetter<T extends GetterDistinctValue, A>(thi
 /**
  * Wraps the input as a Getter function. If it's already a function, returns it directly.
  *
+ * @dbxUtil
+ * @dbxUtilCategory getter
+ * @dbxUtilTags getter, factory, wrap, ensure, normalize
+ * @dbxUtilRelated get-value-from-getter, is-getter
+ *
  * @param input - A value or getter function
  * @returns A Getter function that returns the value
  */
@@ -76,6 +91,12 @@ export type ObjectCopyFactory<T> = Factory<T>;
 /**
  * Creates a factory that returns a shallow copy of the input value on each call.
  *
+ * @dbxUtil
+ * @dbxUtilCategory getter
+ * @dbxUtilKind factory
+ * @dbxUtilTags getter, factory, copy, clone, object
+ * @dbxUtilRelated as-object-copy-factory, copy-object
+ *
  * @param value - The object to copy
  * @param copyFunction - Optional custom copy function (defaults to copyObject)
  * @returns A factory that produces copies of the value

package/src/lib/grouping.d.ts

@@ -69,6 +69,11 @@ export type IndexedBatch<T> = T[] & Readonly<IndexRef>;
  * @param batchSize - Maximum number of items per batch.
  * @returns An array of {@link IndexedBatch} arrays.
  *
+ * @dbxUtil
+ * @dbxUtilCategory grouping
+ * @dbxUtilTags array, batch, chunk, split, group, partition, indexed
+ * @dbxUtilRelated batch-calc, item-count-for-batch-index
+ *
  * @example
  * ```ts
  * const result = batch(['a', 'b', 'c', 'd'], 2);
@@ -101,6 +106,11 @@ export interface BatchCalc extends BatchCount {
 /**
  * Calculates batch metrics (count, full batches, remainder) from a {@link BatchCount} configuration.
  *
+ * @dbxUtil
+ * @dbxUtilCategory grouping
+ * @dbxUtilTags batch, calculate, count, remainder, math
+ * @dbxUtilRelated batch, item-count-for-batch-index
+ *
  * @param input - The total items and items-per-batch configuration.
  * @returns A {@link BatchCalc} with computed batch counts and remainder.
  */
@@ -136,6 +146,11 @@ export declare function restoreOrderWithValues<T, K extends PrimativeKey = Prima
  * @param params.excludeNewItems - when true, values whose keys are not in `orderKeys` are omitted from the result; defaults to false
  * @returns The reordered values array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory grouping
+ * @dbxUtilTags array, order, restore, sort, key, reorder, dedupe
+ * @dbxUtilRelated restore-order-with-values, group-values
+ *
  * @example
  * ```ts
  * const items = [{ key: 'a' }, { key: 'b' }, { key: 'c' }];
@@ -176,6 +191,11 @@ export declare function makeKeyPairs<T, K extends string | number = string | num
 /**
  * Separates values into included and excluded groups based on a decision function.
  *
+ * @dbxUtil
+ * @dbxUtilCategory grouping
+ * @dbxUtilTags array, separate, partition, split, filter, group
+ * @dbxUtilRelated group-values, pair-group-values
+ *
  * @param values - Values to separate.
  * @param checkInclusion - Returns `true` for values that should be included.
  * @returns A {@link SeparateResult} with included and excluded arrays.
@@ -184,6 +204,11 @@ export declare function separateValues<T>(values: T[], checkInclusion: DecisionF
 /**
  * Groups values by key into a plain object. Convenience wrapper around {@link makeValuesGroupMap} that returns a POJO instead of a Map.
  *
+ * @dbxUtil
+ * @dbxUtilCategory grouping
+ * @dbxUtilTags array, group, partition, key, by, object, dictionary
+ * @dbxUtilRelated make-values-group-map, separate-values, pair-group-values
+ *
  * @param values - Values to group.
  * @param groupKeyFn - Extracts the grouping key from each value.
  * @returns A plain object mapping each key to its array of values.
@@ -199,6 +224,11 @@ export declare function groupValues<T, K extends PrimativeKey = PrimativeKey>(va
  * @param groupKeyFn - Extracts the grouping key from each value.
  * @returns A Map from each key to its array of values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory grouping
+ * @dbxUtilTags array, group, map, key, partition, by, dictionary
+ * @dbxUtilRelated group-values, separate-values, pair-group-values
+ *
  * @example
  * ```ts
  * const items = [{ type: 'a', v: 1 }, { type: 'b', v: 2 }, { type: 'a', v: 3 }];

package/src/lib/hash.d.ts

@@ -21,6 +21,11 @@ export type HashDecodeMap<H extends string = string, V extends string = string>
  * @param hashFn - A function that takes a string and returns its hashed representation.
  * @returns An array of decoded strings. Values that cannot be decoded are filtered out.
  *
+ * @dbxUtil
+ * @dbxUtilCategory hash
+ * @dbxUtilTags hash, decode, lookup, reverse, salt
+ * @dbxUtilRelated make-hash-decode-map, decode-hashed-values-with-decode-map
+ *
  * @example
  * ```ts
  * const hashed = [hashFn('apple'), hashFn('banana')];
@@ -33,6 +38,11 @@ export declare function decodeHashedValues(hashedValues: string[], decodeValues:
  * Creates a `HashDecodeMap` from a list of potential original string values and a hash function.
  * The map's keys are the hashed versions of the `decodeValues`, and the values are the original `decodeValues`.
  *
+ * @dbxUtil
+ * @dbxUtilCategory hash
+ * @dbxUtilTags hash, decode, map, lookup, reverse, factory
+ * @dbxUtilRelated decode-hashed-values, decode-hashed-values-with-decode-map
+ *
  * @param decodeValues - An array of potential original string values.
  * @param hashFn - A function that takes a string and returns its hashed representation.
  * @returns A {@link HashDecodeMap} for decoding hashed values.

package/src/lib/index.d.ts

@@ -1,6 +1,7 @@
 export * from './array';
 export * from './assertion';
 export * from './auth';
+export * from './cache';
 export * from './contact';
 export * from './error';
 export * from './file';

package/src/lib/iterable/iterable.d.ts

@@ -20,6 +20,11 @@ export declare function asIterable<T = unknown>(values: IterableOrValue<T>, trea
  *
  * By default treats strings as a non-iterable value, using the string as a single value.
  *
+ * @dbxUtil
+ * @dbxUtilCategory iterable
+ * @dbxUtilTags iterable, array, convert, normalize, ensure
+ * @dbxUtilRelated iterable-to-set, iterable-to-map, as-iterable
+ *
  * @param values - The value or iterable to convert
  * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
  * @returns An array containing the value(s)
@@ -30,6 +35,11 @@ export declare function iterableToArray<T = unknown>(values: IterableOrValue<T>,
  *
  * By default treats strings as a non-iterable value, using the string as a single value.
  *
+ * @dbxUtil
+ * @dbxUtilCategory iterable
+ * @dbxUtilTags iterable, set, convert, normalize, unique, dedupe
+ * @dbxUtilRelated iterable-to-array, iterable-to-map
+ *
  * @param values - The value or iterable to convert
  * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
  * @returns A Set containing the value(s)
@@ -47,6 +57,11 @@ export declare function iterableToMap<T, K extends PrimativeKey = PrimativeKey>(
  * Type guard that returns true if the input is an Iterable.
  * By default, strings are not treated as iterable.
  *
+ * @dbxUtil
+ * @dbxUtilCategory iterable
+ * @dbxUtilTags iterable, type-guard, check, symbol-iterator
+ * @dbxUtilRelated is-empty-iterable, as-iterable
+ *
  * @param values - The value to check
  * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
  * @returns True if the value is iterable
@@ -55,6 +70,11 @@ export declare function isIterable<T = unknown>(values: unknown, treatStringAsIt
 /**
  * Returns true if the iterable has no values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory iterable
+ * @dbxUtilTags iterable, empty, check, length
+ * @dbxUtilRelated is-iterable, first-value-from-iterable
+ *
  * @param values - The iterable to check
  * @returns True if the iterable is empty
  */

package/src/lib/iterate.d.ts

@@ -12,6 +12,11 @@ export type IteratePageFn<T> = (values: T[]) => void | Promise<void>;
  * @param values - Array of values to iterate over.
  * @param useFn - Callback invoked for each value.
  *
+ * @dbxUtil
+ * @dbxUtilCategory iterate
+ * @dbxUtilTags iterate, async, sequential, each, await, for-each
+ * @dbxUtilRelated perform-async-tasks
+ *
  * @example
  * ```ts
  * await iterate([1, 2, 3], async (value) => {

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

@@ -20,6 +20,12 @@ export type IsInNumberBoundFunction = (number: number) => boolean;
 /**
  * Creates a function that checks whether a number falls within the specified inclusive bounds.
  *
+ * @dbxUtil
+ * @dbxUtilCategory number
+ * @dbxUtilKind factory
+ * @dbxUtilTags number, bound, range, between, check, inclusive, factory
+ * @dbxUtilRelated bound-number-function, bound-number, is-valid-number-bound
+ *
  * @param bounds - The min/max bounds to test against
  * @returns A function that returns `true` if the input number is within bounds
  * @throws Error if the bounds are invalid (min > max)
@@ -41,6 +47,12 @@ export type WrapNumberFunction<T extends number = number> = MapFunction<number,
  *
  * When `fencePosts` is true, wraps to the nearest "fence post" value, extending the wrap range by one in each direction.
  *
+ * @dbxUtil
+ * @dbxUtilCategory number
+ * @dbxUtilKind factory
+ * @dbxUtilTags number, wrap, modulo, modular, range, factory, circular
+ * @dbxUtilRelated bound-number-function, bound-number, is-in-number-bound-function
+ *
  * @param wrapNumberFunctionConfig - Configuration with min, max, and optional fence post behavior
  * @returns A function that wraps input numbers into the bounded range
  */
@@ -59,6 +71,12 @@ export type BoundNumberFunction<T extends number = number> = MapFunction<number,
  *
  * When `wrap` is true, uses modular wrapping. Otherwise, clamps values to the min/max range.
  *
+ * @dbxUtil
+ * @dbxUtilCategory number
+ * @dbxUtilKind factory
+ * @dbxUtilTags number, bound, clamp, wrap, range, factory, constrain
+ * @dbxUtilRelated bound-number, wrap-number-function, is-in-number-bound-function
+ *
  * @param boundNumberFunctionConfig - Configuration with min, max, and optional wrap behavior
  * @returns A function that bounds input numbers into the configured range
  */
@@ -66,6 +84,11 @@ export declare function boundNumberFunction<T extends number = number>(boundNumb
 /**
  * Clamps the input number between the min and max values (inclusive).
  *
+ * @dbxUtil
+ * @dbxUtilCategory number
+ * @dbxUtilTags number, clamp, bound, min, max, range, constrain
+ * @dbxUtilRelated bound-number-function, wrap-number-function, is-in-number-bound-function
+ *
  * @param input - Number to clamp
  * @param min - Minimum allowed value
  * @param max - Maximum allowed value