@dereekb/util 13.10.9 → 13.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util",
-  "version": "13.10.9",
+  "version": "13.11.0",
   "sideEffects": false,
   "exports": {
     "./test": {

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

@@ -11,6 +11,11 @@ export type ArrayOrValue<T> = T | T[];
 /**
  * Converts the input value to an array containing itself, or returns itself if it is a non-empty array. Returns undefined if the input is nullish or results in an empty array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, non-empty, convert, ensure, normalize
+ * @dbxUtilRelated convert-maybe-to-array, convert-to-array
+ *
  * @param arrayOrValue - single value or array to convert
  * @returns an array with at least one element, or undefined if the result would be empty
  */
@@ -18,6 +23,11 @@ export declare function convertMaybeToNonEmptyArray<T>(arrayOrValue: Maybe<Array
 /**
  * Converts the input value to an array containing itself, or returns itself if it is an array. Returns an empty array if the input is nullish.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, convert, ensure, normalize, maybe, nullish
+ * @dbxUtilRelated convert-maybe-to-non-empty-array, convert-to-array, as-array
+ *
  * @param arrayOrValue - single value, array, or nullish value to convert
  * @returns the input wrapped in an array, the input array itself, or an empty array if nullish
  */
@@ -33,6 +43,11 @@ export declare const asNonEmptyArray: typeof convertMaybeToNonEmptyArray;
 /**
  * Converts the input value to an array containing itself, or returns itself if it is already an array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, convert, ensure, wrap, normalize
+ * @dbxUtilRelated convert-maybe-to-array, convert-maybe-to-non-empty-array
+ *
  * @param arrayOrValue - single value or array to convert
  * @returns the input array unchanged, or a new single-element array wrapping the input value
  */
@@ -40,6 +55,11 @@ export declare function convertToArray<T>(arrayOrValue: ArrayOrValue<T>): T[];
 /**
  * Returns the first value from the array, or the value itself if not an array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, first, head, get, value
+ * @dbxUtilRelated last-value, value-at-index, first-and-last-value
+ *
  * @param input - single value or array to retrieve from
  * @returns the first element of the array, or the input value itself
  */
@@ -47,6 +67,11 @@ export declare function firstValue<T>(input: ArrayOrValue<T>): T;
 /**
  * Returns the last value from the array, or the value itself if not an array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, last, tail, get, value
+ * @dbxUtilRelated first-value, value-at-index, first-and-last-value
+ *
  * @param input - single value or array to retrieve from
  * @returns the last element of the array, or the input value itself
  */
@@ -56,6 +81,11 @@ export declare function lastValue<T>(input: ArrayOrValue<T>): T;
  *
  * If the input is not an array, returns that value as both the first and last value.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, first, last, head, tail, tuple, endpoints
+ * @dbxUtilRelated first-value, last-value, value-at-index
+ *
  * @param input - single value or array to retrieve from
  * @returns a two-element tuple of the first and last values
  */
@@ -63,6 +93,11 @@ export declare function firstAndLastValue<T>(input: ArrayOrValue<T>): [T, T];
 /**
  * Returns the value at the given index from an array, or the value itself if not an array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, index, get, value, at
+ * @dbxUtilRelated first-value, last-value, first-and-last-value
+ *
  * @param input - single value or array to retrieve from
  * @param index - zero-based index of the element to retrieve
  * @returns the element at the specified index, or the input value itself if not an array
@@ -71,6 +106,11 @@ export declare function valueAtIndex<T>(input: ArrayOrValue<T>, index: number):
 /**
  * Concatenates the input arrays into a single array, filtering out nullish entries.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, concat, concatenate, combine, flatten, merge
+ * @dbxUtilRelated flatten-array, merge-arrays
+ *
  * @param arrays - arrays to concatenate; nullish entries are ignored
  * @returns a single flattened array containing all elements from the non-nullish input arrays
  */
@@ -78,6 +118,11 @@ export declare function concatArrays<T>(...arrays: Maybe<T[]>[]): T[];
 /**
  * Flattens a two-dimensional array into a single-dimensional array. Any null/undefined entries in the outer dimension are filtered out.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, flatten, flat, nested, two-dimensional, concat
+ * @dbxUtilRelated concat-arrays, flatten-array-or-value-array, merge-arrays
+ *
  * @param array - two-dimensional array to flatten, may contain nullish entries
  * @returns a single-dimensional array with all elements from the non-nullish inner arrays
  */
@@ -92,6 +137,11 @@ export declare function flattenArrayOrValueArray<T>(array: ArrayOrValue<Maybe<T>
 /**
  * Creates a shallow copy of the input array. Returns an empty array if the input is nullish.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, copy, clone, shallow, duplicate
+ * @dbxUtilRelated convert-maybe-to-array
+ *
  * @param input - array to copy, or nullish
  * @returns a new array with the same elements, or an empty array if input is nullish
  */
@@ -108,6 +158,11 @@ export declare function pushElementOntoArray<T>(target: T[], element: T, times:
 /**
  * Merges all input arrays into a single new array. Nullish entries are ignored.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, merge, concat, flatten, combine
+ * @dbxUtilRelated merge-arrays-into-array
+ *
  * @param arrays - arrays to merge; nullish entries are skipped
  * @returns a new array containing all elements from the provided arrays
  */
@@ -141,6 +196,11 @@ export declare function pushArrayItemsIntoArray<T>(target: T[], array: T[]): T[]
 /**
  * Copies/takes the elements from the front of the array up to the specified maximum.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, take, front, head, slice, limit
+ * @dbxUtilRelated take-last, split-front
+ *
  * @param values - source array to take from
  * @param maxToTake - maximum number of elements to take from the front
  * @returns a new array containing at most maxToTake elements from the front
@@ -166,6 +226,11 @@ export interface SplitFrontResult<T> {
 /**
  * Splits the array into two arrays, the first being the front of the array up to the maxToTake, and the second being the remaining values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, split, partition, front, slice
+ * @dbxUtilRelated take-front, take-last
+ *
  * @param values The array to split.
  * @param maxToTake The maximum number of values to take from the front of the array.
  * @returns The front and remaining values.
@@ -174,6 +239,11 @@ export declare function splitFront<T>(values: T[], maxToTake: number): SplitFron
 /**
  * Copies/takes as many elements as possible from the end.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, take, last, tail, end, slice, limit
+ * @dbxUtilRelated take-front, split-front
+ *
  * @param values Values to take from.
  * @param maxToTake Max number of values to take from the end of the input array.
  * @param keepFromFront Number of values to retain in the front of the array. These are not taken.
@@ -191,6 +261,11 @@ export declare function forEachWithArray<T>(array: Maybe<ArrayOrValue<T>>, forEa
 /**
  * Counts the total number of elements across all inner arrays of a nested array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, count, nested, total, length, two-dimensional
+ * @dbxUtilRelated flatten-array
+ *
  * @param array - two-dimensional array whose elements are counted
  * @returns the total number of elements across all inner arrays
  */
@@ -198,6 +273,10 @@ export declare function countAllInNestedArray<T>(array: T[][]): number;
 /**
  * Creates a copy of the array with the items at the specified indexes removed.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, remove, exclude, indexes, filter, copy
+ *
  * @param array - source array to copy from
  * @param removeIndexes - indexes of elements to exclude from the copy
  * @returns a new array without the elements at the specified indexes

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

@@ -21,6 +21,12 @@ export type AsyncArrayInputFactory<I, O> = AsyncMapFunction<ArrayInputFactory<I,
 /**
  * Creates a new ArrayFactory that generates multiple values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, factory, generate, make, build, create
+ * @dbxUtilRelated array-input-factory, terminating-factory-from-array
+ *
  * @param factory - The factory function used to generate each item
  * @returns A function that takes a count parameter and returns an array of generated items
  */
@@ -28,6 +34,12 @@ export declare function arrayFactory<T>(factory: Factory<T> | FactoryWithIndex<T
 /**
  * Creates an ArrayInputFactory that transforms input values into output values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, factory, transform, map, generate, build
+ * @dbxUtilRelated array-factory
+ *
  * @param factory - The factory function used to transform each input value
  * @returns A function that takes an array of input values and returns an array of output values
  */

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

@@ -13,6 +13,12 @@ export type ArrayDecisionFunction<T> = (values: T[]) => boolean;
  * When mode is `'any'`, the resulting function returns `true` if at least one element satisfies the predicate.
  * When mode is `'all'`, it returns `true` only if every element satisfies the predicate.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, decision, predicate, find, every, some, all, any, factory
+ * @dbxUtilRelated array-decision
+ *
  * @param decision - Predicate used to test individual elements.
  * @param mode - Whether all or any elements must satisfy the predicate.
  * @returns A function that evaluates an array against the configured decision criteria.
@@ -21,6 +27,11 @@ export declare function arrayDecisionFunction<T>(decision: ArrayFindDecisionFunc
 /**
  * Convenience wrapper that creates and immediately invokes an {@link ArrayDecisionFunction}.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, decision, predicate, find, every, some, all, any
+ * @dbxUtilRelated array-decision-function
+ *
  * @param values - Array to evaluate.
  * @param decision - Predicate used to test individual elements.
  * @param mode - Whether all or any elements must satisfy the predicate.

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

@@ -16,6 +16,11 @@ export interface LimitArrayConfig {
  * Limits the number of items in an array based on the provided configuration.
  * Items are taken from the front of the array by default, or from the end if configured.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, limit, slice, truncate, take, cap
+ * @dbxUtilRelated take-front, take-last
+ *
  * @param array - source array to limit
  * @param inputConfig - configuration controlling the limit count and direction
  * @param inputConfig.limit - maximum number of items to include in the result

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

@@ -11,6 +11,12 @@ export type RandomPickFactory<T> = (() => T) & {
 /**
  * Creates a {@link RandomPickFactory} from the input values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, random, pick, sample, choose, factory
+ * @dbxUtilRelated pick-one-randomly, random-array-index
+ *
  * @param values - array of values to randomly pick from
  * @returns a callable factory that returns a random value from the array on each invocation
  * @throws Error if the input array is empty
@@ -19,6 +25,11 @@ export declare function randomPickFactory<T>(values: T[]): RandomPickFactory<T>;
 /**
  * Returns a random index from the input array. Returns 0 if the array is empty.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, random, index, position
+ * @dbxUtilRelated pick-one-randomly, random-pick-factory
+ *
  * @param values - array to generate a random index for
  * @returns a random valid index within the array, or 0 if the array is empty
  */
@@ -26,6 +37,11 @@ export declare function randomArrayIndex<T>(values: T[]): IndexNumber;
 /**
  * Picks a single item randomly from the input array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, random, pick, sample, choose
+ * @dbxUtilRelated random-pick-factory, random-array-index
+ *
  * @param values - array to pick a random item from
  * @returns a randomly selected item from the array
  * @throws Error if the input array is empty

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

@@ -1,6 +1,11 @@
 /**
  * Returns items that exist in both arrays (intersection).
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, set, intersection, intersect, keep, common, both
+ * @dbxUtilRelated exclude-values-from-array
+ *
  * @param values - The source array to filter.
  * @param secondArray - The array of values to keep.
  * @returns A new array containing only the values from `values` that also exist in `secondArray`.
@@ -9,6 +14,11 @@ export declare function keepValuesFromArray<T>(values: T[], secondArray: T[]): T
 /**
  * Returns items from the first array that do not exist in the second array (difference).
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, set, difference, exclude, subtract, diff
+ * @dbxUtilRelated keep-values-from-array
+ *
  * @param values - The source array to filter.
  * @param secondArray - The array of values to exclude.
  * @returns A new array containing only the values from `values` that do not exist in `secondArray`.
@@ -17,6 +27,11 @@ export declare function excludeValuesFromArray<T>(values: T[], secondArray: T[])
 /**
  * Checks whether the given array contains any duplicate values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, duplicate, check, validation, set
+ * @dbxUtilRelated find-index-of-first-duplicate-value, unique
+ *
  * @param values - The array to check for duplicates.
  * @returns `true` if the array contains at least one duplicate value, `false` otherwise.
  */
@@ -24,6 +39,11 @@ export declare function arrayContainsDuplicateValue<T>(values: T[]): boolean;
 /**
  * Finds the index of the first duplicate value in the given array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, duplicate, find, index, search
+ * @dbxUtilRelated array-contains-duplicate-value, unique
+ *
  * @param values - The array to search for duplicates.
  * @returns The index of the first value that is a duplicate of an earlier value, or `-1` if no duplicates exist.
  */

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

@@ -4,6 +4,11 @@ import { type DecisionFunction } from '../value/decision';
 /**
  * Concatenates multiple arrays and returns only unique values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, unique, concat, distinct, dedupe, deduplicate
+ * @dbxUtilRelated unique, flatten-array-unique, concat-arrays
+ *
  * @param arrays - Arrays to concatenate. Null/undefined arrays are ignored.
  * @returns Array containing only unique values from all input arrays.
  */
@@ -11,6 +16,11 @@ export declare function concatArraysUnique<T extends PrimativeKey = PrimativeKey
 /**
  * Flattens a 2D array and returns only unique values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, flatten, unique, distinct, dedupe, nested
+ * @dbxUtilRelated unique, concat-arrays-unique, flatten-array
+ *
  * @param array - Two-dimensional array to flatten and deduplicate.
  * @returns Array containing only unique values from the flattened input.
  */
@@ -18,6 +28,11 @@ export declare function flattenArrayUnique<T extends PrimativeKey = PrimativeKey
 /**
  * Filters the input values and only returns unique values.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, unique, distinct, dedupe, deduplicate, set
+ * @dbxUtilRelated filter-unique-values, filter-unique-function, concat-arrays-unique
+ *
  * @param values - Array of primitive-key values to deduplicate.
  * @param excludeInput - Optional keys or values to exclude from the result.
  * @returns Array containing only unique values with exclusions removed.
@@ -63,6 +78,12 @@ export declare function readKeysFromFilterUniqueFunctionAdditionalKeys<T, K exte
 /**
  * Creates a {@link FilterUniqueFunction} that deduplicates items by their computed key.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, unique, distinct, dedupe, factory, key, filter
+ * @dbxUtilRelated filter-unique-values, unique, allow-value-once-filter
+ *
  * @param readKey - Function to extract a unique key from each item.
  * @param additionalKeysInput - Optional keys or values to pre-seed as already seen, causing them to be excluded.
  * @returns A reusable filter function that removes duplicate items from arrays.
@@ -71,6 +92,11 @@ export declare function filterUniqueFunction<T, K extends PrimativeKey = Primati
 /**
  * Filters an array to contain only items with unique keys.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, unique, filter, dedupe, key, distinct
+ * @dbxUtilRelated filter-unique-function, unique, is-unique-keyed-function
+ *
  * @param values - Array of items to deduplicate.
  * @param readKey - Function to extract a unique key from each item.
  * @param additionalKeys - Optional keys to pre-seed as already seen, excluding matching items.
@@ -84,6 +110,12 @@ export type IsUniqueKeyedFunction<T> = DecisionFunction<T[]>;
 /**
  * Creates an {@link IsUniqueKeyedFunction} that checks whether all items in an array have unique keys.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, unique, validation, distinct, key, decision, factory
+ * @dbxUtilRelated filter-unique-function, unique
+ *
  * @param readKey - Function to extract a unique key from each item.
  * @returns A decision function that returns true if all items have distinct keys.
  */
@@ -104,6 +136,12 @@ export type AllowValueOnceFilter<T, K extends PrimativeKey = PrimativeKey> = Dec
 /**
  * Creates a new {@link AllowValueOnceFilter} that permits each unique key only on its first encounter.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilKind factory
+ * @dbxUtilTags array, unique, filter, factory, stateful, once, dedupe
+ * @dbxUtilRelated filter-unique-function, unique
+ *
  * @param inputReadKey - Optional function to extract a key from each value. Defaults to identity.
  * @returns A stateful filter function that returns true only for the first occurrence of each key.
  */

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

@@ -17,6 +17,11 @@ export declare function filterMaybeArrayFunction<T>(filterFn: Parameters<Array<M
 /**
  * Filters all maybe values from the input array. If a maybe value is input, returns an empty array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, filter, maybe, nullish, non-null, defined, compact
+ * @dbxUtilRelated filter-empty-array-values, filter-maybe-array-function
+ *
  * @param values - Optional array of optional values to filter.
  * @returns An array containing only non-null and non-undefined values.
  */
@@ -24,6 +29,11 @@ export declare const filterMaybeArrayValues: UniversalFilterMaybeArrayFunction;
 /**
  * Filters all empty and maybe values from the input array. If a maybe value is input, returns an empty array.
  *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, filter, empty, maybe, nullish, non-empty, compact
+ * @dbxUtilRelated filter-maybe-array-values, filter-maybe-array-function
+ *
  * @param values - Optional array of optional values to filter.
  * @returns An array containing only non-null, non-undefined, and non-empty values.
  */

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

@@ -1,2 +1,4 @@
 export * from './auth.role';
 export * from './auth.role.claims';
+export * from './oauth';
+export * from './pkce';

package/src/lib/auth/oauth.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Standard "out-of-band" OAuth 2.0 redirect URI URN.
+ *
+ * Defined by RFC 6749 §1.3 / draft-ietf-oauth-native-apps. Used by native and CLI clients that
+ * have no HTTP server to receive the redirect — the authorization server displays the
+ * authorization code on a final page and the user pastes it back into the application.
+ *
+ * Many providers have deprecated this in favor of loopback redirects (e.g.
+ * `http://127.0.0.1:<port>/callback`), but it remains in use as a fallback for tools that cannot
+ * bind a local port.
+ */
+export declare const OAUTH_OOB_REDIRECT_URI = "urn:ietf:wg:oauth:2.0:oob";

package/src/lib/auth/pkce.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generates a random PKCE code verifier string (43 characters, base64url-encoded).
+ *
+ * @returns A cryptographically random base64url string suitable for use as a PKCE code_verifier.
+ */
+export declare function generatePkceCodeVerifier(): string;
+/**
+ * Generates a PKCE code challenge from a code verifier using SHA-256.
+ *
+ * @param verifier - The code verifier string to hash
+ * @returns A base64url-encoded SHA-256 hash of the verifier
+ */
+export declare function generatePkceCodeChallenge(verifier: string): Promise<string>;

package/src/lib/boolean.d.ts

@@ -19,6 +19,11 @@ export type TrueOrFalseString = 'true' | 'false';
 /**
  * If a non-null boolean value is provided, returns the opposite.
  *
+ * @dbxUtil
+ * @dbxUtilCategory boolean
+ * @dbxUtilTags boolean, invert, negate, not, maybe, nullish
+ * @dbxUtilRelated reduce-booleans-with-and, reduce-booleans-with-or
+ *
  * @param x - the boolean value to invert, or a nullish value
  * @returns the inverted boolean, or the original nullish value if input was null/undefined
  */
@@ -35,6 +40,11 @@ export declare function invertMaybeBoolean(x: Maybe<boolean>): Maybe<boolean>;
  * @returns The result of ANDing all boolean values in the array.
  * @throws {TypeError} If the array is empty and no emptyArrayValue is provided.
  *
+ * @dbxUtil
+ * @dbxUtilCategory boolean
+ * @dbxUtilTags boolean, reduce, and, every, all, conjunction, aggregate
+ * @dbxUtilRelated reduce-booleans-with-or, reduce-booleans-with-and-fn
+ *
  * @example
  * ```ts
  * reduceBooleansWithAnd([true, true, true]);   // true
@@ -46,6 +56,11 @@ export declare function reduceBooleansWithAnd(array: boolean[], emptyArrayValue?
 /**
  * Reduces an array of booleans with the logical OR operation.
  *
+ * @dbxUtil
+ * @dbxUtilCategory boolean
+ * @dbxUtilTags boolean, reduce, or, some, any, disjunction, aggregate
+ * @dbxUtilRelated reduce-booleans-with-and, reduce-booleans-with-or-fn
+ *
  * @param array - Array of boolean values to reduce.
  * @param emptyArrayValue - Value to return if the array is empty. If not provided and the array is empty, a TypeError will be thrown.
  * @returns The result of ORing all boolean values in the array.
@@ -125,6 +140,12 @@ export interface BooleanFactoryConfig {
  * @param config - Configuration for the boolean factory, including the chance of returning true.
  * @returns A factory function (`BooleanFactory`) that generates random boolean values based on the configured chance.
  *
+ * @dbxUtil
+ * @dbxUtilCategory boolean
+ * @dbxUtilKind factory
+ * @dbxUtilTags boolean, factory, random, chance, probability, generate
+ * @dbxUtilRelated random-boolean
+ *
  * @example
  * ```ts
  * const alwaysTrue = booleanFactory({ chance: 100 });
@@ -138,6 +159,11 @@ export declare function booleanFactory(config: BooleanFactoryConfig): BooleanFac
 /**
  * Returns a random boolean based on the specified chance.
  *
+ * @dbxUtil
+ * @dbxUtilCategory boolean
+ * @dbxUtilTags boolean, random, chance, probability, coin-flip
+ * @dbxUtilRelated boolean-factory
+ *
  * @param chance - Number between 0.0 and 100.0 representing the percentage chance of returning true (default: 50, i.e., 50%).
  * @returns A random boolean value with the specified probability of being true.
  */
@@ -151,6 +177,11 @@ export declare function randomBoolean(chance?: BooleanTrueChance): boolean;
  * @param defaultValue - The default value to return if the string cannot be converted to a boolean (default: undefined).
  * @returns The boolean value corresponding to the string, or the default value if the string cannot be converted.
  *
+ * @dbxUtil
+ * @dbxUtilCategory boolean
+ * @dbxUtilTags boolean, string, parse, convert, true, false, yes, no
+ * @dbxUtilRelated true-or-false-string
+ *
  * @example
  * ```ts
  * stringToBoolean('yes');          // true
@@ -166,6 +197,11 @@ export declare function stringToBoolean(value: Maybe<string>, defaultValue?: May
  * Converts a boolean to its `'true'` or `'false'` string representation.
  * Returns null/undefined if the input is nullish.
  *
+ * @dbxUtil
+ * @dbxUtilCategory boolean
+ * @dbxUtilTags boolean, string, convert, serialize, format
+ * @dbxUtilRelated string-to-boolean
+ *
  * @param value - The boolean value to convert.
  * @returns The string `'true'` or `'false'`, or the nullish input unchanged.
  */

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

@@ -0,0 +1,48 @@
+import { type Maybe } from '../value/maybe.type';
+/**
+ * Async cache for a single value of type T.
+ *
+ * Implementations may be in-memory, file-backed, network-backed, or composed via
+ * {@link memoizeAsyncValueCache} / {@link mergeAsyncValueCaches}.
+ */
+export interface AsyncValueCache<T> {
+    /**
+     * Loads the value from the cache, or returns null/undefined when no value is stored.
+     */
+    load(): Promise<Maybe<T>>;
+    /**
+     * Stores the value in the cache, replacing any previously stored value.
+     */
+    update(value: T): Promise<void>;
+    /**
+     * Removes the stored value and any persistent backing.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Async cache for a record of T entries keyed by string.
+ *
+ * Implementations may be in-memory, file-backed (one file holds all keys), or composed.
+ */
+export interface AsyncKeyedValueCache<T> {
+    /**
+     * Loads the full record from the cache. Returns an empty object when the cache is empty.
+     */
+    load(): Promise<Record<string, T>>;
+    /**
+     * Returns the entry for the given key, or null/undefined when no entry is stored.
+     */
+    get(key: string): Promise<Maybe<T>>;
+    /**
+     * Stores the entry for the given key, replacing any previous entry at that key.
+     */
+    set(key: string, value: T): Promise<void>;
+    /**
+     * Removes the entry for the given key, leaving other keys intact.
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Removes all entries and any persistent backing.
+     */
+    clear(): Promise<void>;
+}

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

@@ -0,0 +1,59 @@
+import { type AsyncKeyedValueCache, type AsyncValueCache } from './cache';
+/**
+ * Wraps an inner {@link AsyncValueCache} with a single-load in-memory memoization layer.
+ *
+ * The first {@link AsyncValueCache.load} call delegates to the inner cache and stores the
+ * result; subsequent calls return the memoized value without touching the inner cache again.
+ * {@link AsyncValueCache.update} writes through to the inner cache and refreshes the memo.
+ * {@link AsyncValueCache.clear} clears both layers.
+ *
+ * Note: the memoized value is per-process. Long-running processes will not observe writes
+ * made by other processes to the inner backing once the memo is populated.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory cache
+ * @dbxUtilTags memoize, memo, cache, async, single-load, async-value
+ * @dbxUtilRelated memoize-async-keyed-value-cache
+ *
+ * @param inner - The backing cache to memoize. Reads are delegated once and cached; writes are forwarded through and refresh the memo.
+ * @returns An {@link AsyncValueCache} that proxies the inner cache with a single-load memoization layer.
+ *
+ * @example
+ * ```ts
+ * const memo = memoizeAsyncValueCache(inMemoryAsyncValueCache<string>('initial'));
+ * await memo.load();           // delegates to inner.load() once
+ * await memo.load();           // returns memoized value without hitting inner
+ * await memo.update('next');   // writes through to inner and refreshes memo
+ * ```
+ */
+export declare function memoizeAsyncValueCache<T>(inner: AsyncValueCache<T>): AsyncValueCache<T>;
+/**
+ * Wraps an inner {@link AsyncKeyedValueCache} with a single-load in-memory memoization layer
+ * over the full record.
+ *
+ * The first call to any read method ({@link AsyncKeyedValueCache.load} or {@link AsyncKeyedValueCache.get})
+ * delegates to the inner cache and stores the loaded record; subsequent reads return entries
+ * from the memoized record without re-hitting the inner cache. Writes ({@link AsyncKeyedValueCache.set} /
+ * {@link AsyncKeyedValueCache.remove}) update the memoized record and write through to the inner cache.
+ * {@link AsyncKeyedValueCache.clear} clears both layers.
+ *
+ * Note: the memoized record is per-process. Long-running processes will not observe writes
+ * made by other processes to the inner backing once the memo is populated.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory cache
+ * @dbxUtilTags memoize, memo, cache, async, keyed, record
+ * @dbxUtilRelated memoize-async-value-cache
+ *
+ * @param inner - The backing keyed cache to memoize. The full record is loaded once and cached; writes are forwarded through and applied to the memo.
+ * @returns An {@link AsyncKeyedValueCache} that proxies the inner cache with a record-level memoization layer.
+ *
+ * @example
+ * ```ts
+ * const memo = memoizeAsyncKeyedValueCache(inMemoryAsyncKeyedValueCache<number>({ a: 1 }));
+ * await memo.get('a');           // delegates to inner.load() once
+ * await memo.get('a');           // returns memoized entry without hitting inner
+ * await memo.set('b', 2);        // writes through to inner and updates memo
+ * ```
+ */
+export declare function memoizeAsyncKeyedValueCache<T>(inner: AsyncKeyedValueCache<T>): AsyncKeyedValueCache<T>;