@dereekb/util 12.1.0 → 12.1.1

package/fetch/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util/fetch",
-  "version": "12.1.0",
+  "version": "12.1.1",
   ".": {
     "types": "./src/index.d.ts",
     "node": {

package/index.cjs.js

@@ -8046,20 +8046,57 @@ $$8({ target: 'String', proto: true, forced: !MDN_POLYFILL_BUG && !CORRECT_IS_RE
   }
 });
 
+/**
+ * Trims leading and trailing whitespace from a string.
+ * @param input The string to trim.
+ * @returns The trimmed string.
+ */
 function stringTrimFunction(input) {
   return input.trim();
 }
+/**
+ * Converts a string to uppercase.
+ * @param input The string to convert.
+ * @returns The uppercase string.
+ */
 function stringToUppercaseFunction(input) {
   return input.toUpperCase();
 }
+/**
+ * Converts a string to lowercase.
+ * @param input The string to convert.
+ * @returns The lowercase string.
+ */
 function stringToLowercaseFunction(input) {
   return input.toLowerCase();
 }
+/**
+ * Normalizes a `TransformStringFunctionConfigInput` into a `TransformStringFunctionConfig` object.
+ * If the input is a function, it's wrapped into a config object with that function as the `transform` property.
+ * If the input is undefined, it returns undefined.
+ *
+ * @template S The specific string type, defaults to `string`.
+ * @param config The configuration input to normalize.
+ * @returns A `TransformStringFunctionConfig` object, or `undefined` if the input config is undefined.
+ */
 function transformStringFunctionConfig(config) {
   return config ? typeof config === 'function' ? {
     transform: config
   } : config : undefined;
 }
+/**
+ * Creates a string transformation function based on the provided configuration.
+ * The resulting function will apply transformations in a specific order:
+ * 1. Trimming (if `config.trim` is true).
+ * 2. Custom `config.transform` function (if provided).
+ * 3. Uppercase conversion (if `config.toUppercase` is true and no `config.transform`).
+ * 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.
+ *
+ * @template S The specific string type, defaults to `string`.
+ * @param config The `TransformStringFunctionConfig` detailing the transformations.
+ * @returns A `TransformStringFunction` that applies the configured transformations.
+ */
 function transformStringFunction(config) {
   let baseTransform;
   if (config.transform) {
@@ -8086,28 +8123,28 @@ function addPrefix(prefix, input) {
   return addPrefixFunction(prefix)(input);
 }
 /**
- * Creates an AddPrefixFunction
- *
- * @param input
- * @param replacement
- * @param is
- * @returns
+ * Creates a function that adds a configured prefix to the input string if it does not exist on that string.
+ * @param prefix The prefix to add.
+ * @returns A function that adds the prefix to a string.
  */
 function addPrefixFunction(prefix) {
   return input => {
     return input.startsWith(prefix) ? input : prefix + input;
   };
 }
+/**
+ * Adds a suffix to a string if it does not already end with that suffix.
+ * @param suffix The suffix to add.
+ * @param input The string to modify.
+ * @returns The modified string.
+ */
 function addSuffix(suffix, input) {
   return addSuffixFunction(suffix)(input);
 }
 /**
- * Creates an AddSuffixFunction
- *
- * @param input
- * @param replacement
- * @param is
- * @returns
+ * Creates a function that adds a configured suffix to the input string if it does not exist on that string.
+ * @param suffix The suffix to add.
+ * @returns A function that adds the suffix to a string.
  */
 function addSuffixFunction(suffix) {
   return input => {
@@ -8115,10 +8152,10 @@ function addSuffixFunction(suffix) {
   };
 }
 /**
- *
- * @param minLength
- * @param padCharacter
- * @returns
+ * Pads the start of a string to a minimum length.
+ * @param minLength The minimum length of the string.
+ * @param padCharacter The character to use for padding.
+ * @returns A function that pads the start of a string.
  */
 function padStartFunction(minLength, padCharacter) {
   return input => input.padStart(minLength, padCharacter);
@@ -11059,7 +11096,8 @@ const MS_IN_HOUR = MS_IN_MINUTE * 60;
  */
 const MS_IN_DAY = MS_IN_HOUR * HOURS_IN_DAY;
 /**
- * Retrieves the MonthOfYear value (1-12) from the input Date.
+ * Retrieves the MonthOfYear value (1-12) from the input Date in the current system timezone.
+ *
  * Converts JavaScript's 0-based month (0-11) to a 1-based month (1-12).
  *
  * @param date - The date to extract the month from
@@ -11068,6 +11106,17 @@ const MS_IN_DAY = MS_IN_HOUR * HOURS_IN_DAY;
 function monthOfYearFromDate(date) {
   return monthOfYearFromDateMonth(date.getMonth());
 }
+/**
+ * Retrieves the MonthOfYear value (1-12) from the input Date in the UTC timezone.
+ *
+ * Converts JavaScript's 0-based month (0-11) to a 1-based month (1-12).
+ *
+ * @param date - The date to extract the month from
+ * @returns The month of year as a number from 1-12
+ */
+function monthOfYearFromUTCDate(date) {
+  return monthOfYearFromDateMonth(date.getUTCMonth());
+}
 /**
  * Converts a JavaScript Date month (0-11) to a MonthOfYear (1-12).
  *
@@ -14866,19 +14915,27 @@ function makeTimer(duration, startImmediately = true) {
   let currentDuration = duration;
   const promiseRef = promiseReference();
   const getDurationRemaining = () => {
+    let result;
     switch (state) {
       case 'complete':
-        return 0;
+        result = 0;
+        break;
       case 'running':
-        return Math.max(0, currentDuration - (new Date().getTime() - startedAt.getTime()));
+        result = Math.max(0, currentDuration - (new Date().getTime() - startedAt.getTime()));
+        break;
       case 'paused':
-        return null;
+        result = null;
+        break;
     }
+    return result;
+  };
+  const completeNow = () => {
+    state = 'complete';
+    promiseRef.resolve();
   };
   const checkComplete = () => {
     if (state !== 'complete' && getDurationRemaining() === 0) {
-      state = 'complete';
-      promiseRef.resolve();
+      completeNow();
     }
   };
   const enqueueCheck = () => {
@@ -14915,9 +14972,9 @@ function makeTimer(duration, startImmediately = true) {
   };
   const destroy = () => {
     checkComplete();
-    if (state === 'running') {
+    if (state !== 'complete') {
+      state = 'cancelled';
       promiseRef.reject(new TimerCancelledError());
-      state = 'complete';
     }
   };
   if (startImmediately) {
@@ -14946,6 +15003,7 @@ function makeTimer(duration, startImmediately = true) {
     get durationRemaining() {
       return getDurationRemaining();
     },
+    completeNow,
     start,
     stop,
     reset,
@@ -15475,6 +15533,12 @@ function readableStreamToBuffer(stream) {
   });
 }
 
+/**
+ * Joins the host and port into a string.
+ *
+ * @param config
+ * @returns
+ */
 function joinHostAndPort(config) {
   if (config) {
     return `${config.host}:${config.port}`;
@@ -15863,43 +15927,95 @@ function typedServiceRegistry(config) {
   return instance;
 }
 
+/**
+ * Base error class for storage-related issues.
+ */
 class StoredDataError extends makeError.BaseError {
+  /**
+   * Creates an instance of StoredDataError.
+   * @param message Optional error message.
+   */
   constructor(message) {
     super(message);
   }
 }
+/**
+ * Error thrown when requested data does not exist in storage.
+ */
 class DataDoesNotExistError extends StoredDataError {
+  /**
+   * Creates an instance of DataDoesNotExistError.
+   * @param message Optional error message.
+   */
   constructor(message) {
     super(message);
   }
 }
+/**
+ * Error thrown when data exists in storage but is considered expired.
+ *
+ * @template T The type of the data that is expired.
+ */
 class DataIsExpiredError extends StoredDataError {
+  /**
+   * Creates an instance of DataIsExpiredError.
+   * @param data The expired data, including metadata.
+   * @param message Optional error message. If not provided, a default message will be used.
+   */
   constructor(data, message) {
-    super(message);
+    super(message != null ? message : 'Data has expired.');
     this.data = void 0;
     this.data = data;
   }
 }
 
+/**
+ * A StorageObject implementation that stores data in memory.
+ * This is not persistent and will be cleared when the JavaScript context is lost.
+ */
 class MemoryStorageInstance {
   constructor() {
     this._length = 0;
     this._storage = {};
   }
+  /**
+   * The number of items stored.
+   */
   get length() {
     return this._length;
   }
+  /**
+   * Returns the key at the given index.
+   * @param index The index of the key to retrieve.
+   * @returns The key string if found, otherwise null.
+   */
   key(index) {
     var _Object$keys$index;
     return (_Object$keys$index = Object.keys(this._storage)[index]) != null ? _Object$keys$index : null;
   }
+  /**
+   * Checks if a key exists in the storage.
+   * @param key The key to check.
+   * @returns True if the key exists, false otherwise.
+   */
   hasKey(key) {
     return objectHasKey(this._storage, key);
   }
+  /**
+   * Retrieves an item from storage.
+   * @param key The key of the item to retrieve.
+   * @returns The item string if found, otherwise null or undefined.
+   */
   getItem(key) {
     var _this$_storage$key;
     return (_this$_storage$key = this._storage[key]) != null ? _this$_storage$key : null;
   }
+  /**
+   * Sets an item in storage.
+   * If the item is null or undefined, the key will be removed.
+   * @param key The key of the item to set.
+   * @param item The item string to store.
+   */
   setItem(key, item) {
     if (item == null) {
       this.removeItem(key);
@@ -15910,17 +16026,28 @@ class MemoryStorageInstance {
       this._storage[key] = String(item);
     }
   }
+  /**
+   * Removes an item from storage.
+   * @param key The key of the item to remove.
+   */
   removeItem(key) {
     if (this.hasKey(key)) {
       delete this._storage[key]; // Remove the property
       this._length = this._length - 1;
     }
   }
+  /**
+   * Clears all items from the storage.
+   */
   clear() {
     this._storage = {};
     this._length = 0;
   }
 }
+/**
+ * A shared, global instance of MemoryStorageInstance.
+ * Useful for singleton-like access to an in-memory store throughout an application.
+ */
 const SHARED_MEMORY_STORAGE = new MemoryStorageInstance();
 
 /**
@@ -15933,8 +16060,21 @@ class SimpleStorageObject {}
  * Has the same interface as localStorage for the web.
  */
 class StorageObject extends SimpleStorageObject {}
+/**
+ * Extended synchronous Class/Interface for storing string values with additional properties.
+ */
 class FullStorageObject extends StorageObject {}
+/**
+ * Utility class for working with StorageObject instances.
+ */
 class StorageObjectUtility {
+  /**
+   * Retrieves all keys from a StorageObject, optionally filtering by a prefix.
+   *
+   * @param storageObject The StorageObject to retrieve keys from.
+   * @param prefix Optional prefix to filter keys by.
+   * @returns An array of StoredDataStorageKey.
+   */
   static allKeysFromStorageObject(storageObject, prefix) {
     const length = storageObject.length;
     let result;
@@ -16268,29 +16408,46 @@ function findBestSplitStringTreeChildMatchPath(tree, value) {
 
 /*eslint @typescript-eslint/no-explicit-any:"off"*/
 // any is used with intent here, as the recursive TreeNode value requires its use to terminate.
+/**
+ * Implementation for expandTreeFunction. Creates a function that can expand a single value into a tree structure.
+ *
+ * This factory function takes a configuration object that specifies how to retrieve children for any given value (`getChildren`)
+ * and optionally, how to construct the nodes themselves (`makeNode`). If `makeNode` is not provided, a default node structure is used.
+ * The returned function recursively builds a tree from a root value.
+ *
+ * @template T The type of the value being processed at each node.
+ * @template N The type of the TreeNode to be created. Defaults to TreeNode<T, any> if not specified by ExpandTreeWithNodeBuilder.
+ * @param config An ExpandTree<T> or ExpandTreeWithNodeBuilder<T, N> configuration object.
+ * @returns An ExpandTreeFunction<T, N> that takes a root value and returns its corresponding tree structure.
+ */
 function expandTreeFunction(config) {
   var _config$makeNode;
-  const makeNode = (_config$makeNode = config.makeNode) != null ? _config$makeNode : node => node;
+  const makeNodeFromConfig = (_config$makeNode = config.makeNode) != null ? _config$makeNode : basicNode => basicNode;
   const expandFn = (value, parent) => {
     const depth = parent ? parent.depth + 1 : 0;
-    const treeNode = {
+    const treeNodeWithoutChildren = {
       depth,
       parent,
       value
     };
-    const node = makeNode(treeNode);
+    // Use Omit<N, 'children'> here as makeNodeFromConfig returns the node without children initially.
+    // The children are attached in the next step.
+    const node = makeNodeFromConfig(treeNodeWithoutChildren); // Cast is necessary because children are added after
     const childrenValues = config.getChildren(value);
     node.children = childrenValues ? childrenValues.map(x => expandFn(x, node)) : undefined;
     return node;
   };
-  return root => expandFn(root);
+  return rootValue => expandFn(rootValue);
 }
 /**
- * Convenience function for expanding multiple values into trees then merging them together into a single array.
+ * Convenience function for expanding multiple root values into an array of trees.
+ * Each value in the input array is treated as a root for a new tree.
  *
- * @param values
- * @param expandFn
- * @returns
+ * @template T The type of the input values.
+ * @template N The type of the TreeNode in the resulting trees. Must extend TreeNode<T, N>.
+ * @param values An array of root values of type T to expand.
+ * @param expandFn An ExpandTreeFunction<T, N> used to expand each value into a tree.
+ * @returns An array of N, where each N is the root node of an expanded tree.
  */
 function expandTrees(values, expandFn) {
   return values.map(expandFn);
@@ -16312,6 +16469,18 @@ function flattenTree(tree) {
 function flattenTreeToArray(tree, array) {
   return flattenTreeToArrayFunction()(tree, array);
 }
+/**
+ * Implementation for flattenTreeToArrayFunction.
+ *
+ * This function serves as a factory to produce a flattening function. The produced function
+ * will traverse a tree and collect either the nodes themselves or a mapped value from each node
+ * into an array.
+ *
+ * @template N The type of the tree node, must extend TreeNode.
+ * @template V The type of the values to be collected in the output array.
+ * @param mapNodeFn An optional function to transform each node N to a value V. If omitted, nodes are cast to V (effectively N if V is N).
+ * @returns A FlattenTreeFunction<N, V> that performs the tree flattening.
+ */
 function flattenTreeToArrayFunction(mapNodeFn) {
   const mapNode = mapNodeFn != null ? mapNodeFn : x => x;
   const flattenFn = (tree, array = []) => {
@@ -16339,11 +16508,17 @@ function flattenTrees(trees, flattenFn) {
 /*eslint @typescript-eslint/no-explicit-any:"off"*/
 // any is used with intent here, as the recursive TreeNode value requires its use to terminate.
 /**
- * Creates an ExpandFlattenTree function.
+ * Creates an ExpandFlattenTreeFunction by composing an expansion function and a flattening function.
  *
- * @param expand
- * @param flatten
- * @returns
+ * This higher-order function takes a function to expand an array of values `T` into a list of trees (`N[]` where `N` is a TreeNode)
+ * and another function to flatten these trees into a single array of values `V`.
+ *
+ * @template T The type of the initial input values.
+ * @template V The type of the values in the final flattened output array.
+ * @template N The type of the intermediate tree nodes. Must extend TreeNode with value T and children of type N.
+ * @param expand An ExpandTreeFunction (values: T[]) => N[] that converts an array of T into an array of tree nodes N.
+ * @param flatten A FlattenTreeFunction (tree: N, array?: V[]) => V[] that flattens a tree of N nodes into an array of V values.
+ * @returns An ExpandFlattenTreeFunction (values: T[]) => V[] that performs the combined expansion and flattening.
  */
 function expandFlattenTreeFunction(expand, flatten) {
   return values => {
@@ -16355,9 +16530,9 @@ function expandFlattenTreeFunction(expand, flatten) {
 /**
  * Reduces an array of booleans with the logical AND operation.
  *
- * @param array - Array of boolean values to reduce
- * @param emptyArrayValue - Value to return if the array is empty (default: undefined which becomes false)
- * @returns The result of ANDing all boolean values in the array
+ * @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 ANDing all boolean values in the array.
  */
 function reduceBooleansWithAnd(array, emptyArrayValue) {
   return reduceBooleansWithAndFn(emptyArrayValue)(array);
@@ -16365,9 +16540,9 @@ function reduceBooleansWithAnd(array, emptyArrayValue) {
 /**
  * Reduces an array of booleans with the logical OR operation.
  *
- * @param array - Array of boolean values to reduce
- * @param emptyArrayValue - Value to return if the array is empty (default: undefined which becomes false)
- * @returns The result of ORing all boolean values in the array
+ * @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.
  */
 function reduceBooleansWithOr(array, emptyArrayValue) {
   return reduceBooleansWithOrFn(emptyArrayValue)(array);
@@ -16375,8 +16550,8 @@ function reduceBooleansWithOr(array, emptyArrayValue) {
 /**
  * Creates a function that reduces an array of booleans with the logical AND operation.
  *
- * @param emptyArrayValue - Value to return if the array is empty (default: undefined which becomes false)
- * @returns A function that takes an array of booleans and returns the result of ANDing them
+ * @param emptyArrayValue - Value to return if the array is empty. If not provided and the array is empty, the returned function will throw a TypeError.
+ * @returns A function that takes an array of booleans and returns the result of ANDing them.
  */
 function reduceBooleansWithAndFn(emptyArrayValue) {
   return reduceBooleansFn((a, b) => a && b, emptyArrayValue);
@@ -16384,8 +16559,8 @@ function reduceBooleansWithAndFn(emptyArrayValue) {
 /**
  * Creates a function that reduces an array of booleans with the logical OR operation.
  *
- * @param emptyArrayValue - Value to return if the array is empty (default: undefined which becomes false)
- * @returns A function that takes an array of booleans and returns the result of ORing them
+ * @param emptyArrayValue - Value to return if the array is empty. If not provided and the array is empty, the returned function will throw a TypeError.
+ * @returns A function that takes an array of booleans and returns the result of ORing them.
  */
 function reduceBooleansWithOrFn(emptyArrayValue) {
   return reduceBooleansFn((a, b) => a || b, emptyArrayValue);
@@ -16393,9 +16568,9 @@ function reduceBooleansWithOrFn(emptyArrayValue) {
 /**
  * Creates a function that reduces an array of booleans using a custom reduce function.
  *
- * @param reduceFn - Function that takes two boolean values and returns a single boolean
- * @param emptyArrayValue - Value to return if the array is empty (default: undefined which uses the standard reduce behavior)
- * @returns A function that takes an array of booleans and returns the result of reducing them
+ * @param reduceFn - Function that takes two boolean values and returns a single boolean.
+ * @param emptyArrayValue - Value to return if the array is empty. If not provided and the array is empty, the returned function will throw a TypeError because `Array.prototype.reduce` on an empty array without an initial value throws.
+ * @returns A function that takes an array of booleans and returns the result of reducing them.
  */
 function reduceBooleansFn(reduceFn, emptyArrayValue) {
   const rFn = array => Boolean(array.reduce(reduceFn));
@@ -16408,8 +16583,8 @@ function reduceBooleansFn(reduceFn, emptyArrayValue) {
 /**
  * Creates a new BooleanFactory that generates random boolean values based on chance.
  *
- * @param config - Configuration for the boolean factory, including the chance of returning true
- * @returns A factory function that generates random boolean values
+ * @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.
  */
 function booleanFactory(config) {
   const {
@@ -16425,8 +16600,8 @@ function booleanFactory(config) {
 /**
  * Returns a random boolean based on the specified chance.
  *
- * @param chance - Number between 0 and 100 representing the percentage chance of returning true (default: 50)
- * @returns A random boolean value with the specified probability of being true
+ * @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.
  */
 function randomBoolean(chance = 50) {
   return booleanFactory({
@@ -16465,15 +16640,38 @@ class DestroyFunctionObject {
   }
 }
 
+/**
+ * Decodes a list of hashed string values using a provided list of potential original values and a hash function.
+ *
+ * @param hashedValues An array of hashed strings to decode.
+ * @param decodeValues An array of potential original string values.
+ * @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.
+ */
 function decodeHashedValues(hashedValues, decodeValues, hashFn) {
   const hashDecodeMap = makeHashDecodeMap(decodeValues, hashFn);
   return decodeHashedValuesWithDecodeMap(hashedValues, hashDecodeMap);
 }
+/**
+ * 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`.
+ *
+ * @param decodeValues An array of potential original string values.
+ * @param hashFn A function that takes a string and returns its hashed representation.
+ * @returns A `HashDecodeMap` for decoding hashed values.
+ */
 function makeHashDecodeMap(decodeValues, hashFn) {
   const keyValuePairs = decodeValues.map(x => [hashFn(x), x]);
   const map = new Map(keyValuePairs);
   return map;
 }
+/**
+ * Decodes a list of hashed string values using a pre-built `HashDecodeMap`.
+ *
+ * @param hashedValues An array of hashed strings to decode.
+ * @param decodeMap A `HashDecodeMap` to use for looking up original values.
+ * @returns An array of decoded strings. Values that cannot be decoded are filtered out.
+ */
 function decodeHashedValuesWithDecodeMap(hashedValues, decodeMap) {
   const values = hashedValues.map(x => decodeMap.get(x));
   return filterMaybeArrayValues(values);
@@ -17199,6 +17397,7 @@ exports.modifyModelMapFunctions = modifyModelMapFunctions;
 exports.monthDaySlashDateToDateString = monthDaySlashDateToDateString;
 exports.monthOfYearFromDate = monthOfYearFromDate;
 exports.monthOfYearFromDateMonth = monthOfYearFromDateMonth;
+exports.monthOfYearFromUTCDate = monthOfYearFromUTCDate;
 exports.multiKeyValueMapFactory = multiKeyValueMapFactory;
 exports.multiValueMapBuilder = multiValueMapBuilder;
 exports.neMostLatLngPoint = neMostLatLngPoint;