@dereekb/util 12.1.0 → 12.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5877,7 +5877,8 @@ function rateLimitedFetchHandler(config) {
5877
5877
  fetchResponseError = e;
5878
5878
  response = fetchResponseError.response;
5879
5879
  }
5880
- const shouldRetry = await updateWithResponse(response, fetchResponseError);
5880
+ // response could be null in some cases
5881
+ const shouldRetry = response ? await updateWithResponse(response, fetchResponseError) : false;
5881
5882
  if (shouldRetry && retriesAttempted < maxRetries) {
5882
5883
  response = await tryFetch(retriesAttempted + 1);
5883
5884
  } else {
@@ -5886,6 +5887,10 @@ function rateLimitedFetchHandler(config) {
5886
5887
  throw fetchResponseError;
5887
5888
  }
5888
5889
  }
5890
+ // if response is null at this point but fetchResponseError is not, rethrow the error
5891
+ if (response == null && fetchResponseError != null) {
5892
+ throw fetchResponseError;
5893
+ }
5889
5894
  return response;
5890
5895
  }
5891
5896
  return tryFetch(0);
@@ -5875,7 +5875,8 @@ function rateLimitedFetchHandler(config) {
5875
5875
  fetchResponseError = e;
5876
5876
  response = fetchResponseError.response;
5877
5877
  }
5878
- const shouldRetry = await updateWithResponse(response, fetchResponseError);
5878
+ // response could be null in some cases
5879
+ const shouldRetry = response ? await updateWithResponse(response, fetchResponseError) : false;
5879
5880
  if (shouldRetry && retriesAttempted < maxRetries) {
5880
5881
  response = await tryFetch(retriesAttempted + 1);
5881
5882
  } else {
@@ -5884,6 +5885,10 @@ function rateLimitedFetchHandler(config) {
5884
5885
  throw fetchResponseError;
5885
5886
  }
5886
5887
  }
5888
+ // if response is null at this point but fetchResponseError is not, rethrow the error
5889
+ if (response == null && fetchResponseError != null) {
5890
+ throw fetchResponseError;
5891
+ }
5887
5892
  return response;
5888
5893
  }
5889
5894
  return tryFetch(0);
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dereekb/util/fetch",
3
- "version": "12.1.0",
3
+ "version": "12.1.2",
4
4
  ".": {
5
5
  "types": "./src/index.d.ts",
6
6
  "node": {
package/index.cjs.js CHANGED
@@ -8046,20 +8046,57 @@ $$8({ target: 'String', proto: true, forced: !MDN_POLYFILL_BUG && !CORRECT_IS_RE
8046
8046
  }
8047
8047
  });
8048
8048
 
8049
+ /**
8050
+ * Trims leading and trailing whitespace from a string.
8051
+ * @param input The string to trim.
8052
+ * @returns The trimmed string.
8053
+ */
8049
8054
  function stringTrimFunction(input) {
8050
8055
  return input.trim();
8051
8056
  }
8057
+ /**
8058
+ * Converts a string to uppercase.
8059
+ * @param input The string to convert.
8060
+ * @returns The uppercase string.
8061
+ */
8052
8062
  function stringToUppercaseFunction(input) {
8053
8063
  return input.toUpperCase();
8054
8064
  }
8065
+ /**
8066
+ * Converts a string to lowercase.
8067
+ * @param input The string to convert.
8068
+ * @returns The lowercase string.
8069
+ */
8055
8070
  function stringToLowercaseFunction(input) {
8056
8071
  return input.toLowerCase();
8057
8072
  }
8073
+ /**
8074
+ * Normalizes a `TransformStringFunctionConfigInput` into a `TransformStringFunctionConfig` object.
8075
+ * If the input is a function, it's wrapped into a config object with that function as the `transform` property.
8076
+ * If the input is undefined, it returns undefined.
8077
+ *
8078
+ * @template S The specific string type, defaults to `string`.
8079
+ * @param config The configuration input to normalize.
8080
+ * @returns A `TransformStringFunctionConfig` object, or `undefined` if the input config is undefined.
8081
+ */
8058
8082
  function transformStringFunctionConfig(config) {
8059
8083
  return config ? typeof config === 'function' ? {
8060
8084
  transform: config
8061
8085
  } : config : undefined;
8062
8086
  }
8087
+ /**
8088
+ * Creates a string transformation function based on the provided configuration.
8089
+ * The resulting function will apply transformations in a specific order:
8090
+ * 1. Trimming (if `config.trim` is true).
8091
+ * 2. Custom `config.transform` function (if provided).
8092
+ * 3. Uppercase conversion (if `config.toUppercase` is true and no `config.transform`).
8093
+ * 4. Lowercase conversion (if `config.toLowercase` is true and no `config.transform` or `config.toUppercase`).
8094
+ * If no transformations are specified, the identity function is returned.
8095
+ *
8096
+ * @template S The specific string type, defaults to `string`.
8097
+ * @param config The `TransformStringFunctionConfig` detailing the transformations.
8098
+ * @returns A `TransformStringFunction` that applies the configured transformations.
8099
+ */
8063
8100
  function transformStringFunction(config) {
8064
8101
  let baseTransform;
8065
8102
  if (config.transform) {
@@ -8086,28 +8123,28 @@ function addPrefix(prefix, input) {
8086
8123
  return addPrefixFunction(prefix)(input);
8087
8124
  }
8088
8125
  /**
8089
- * Creates an AddPrefixFunction
8090
- *
8091
- * @param input
8092
- * @param replacement
8093
- * @param is
8094
- * @returns
8126
+ * Creates a function that adds a configured prefix to the input string if it does not exist on that string.
8127
+ * @param prefix The prefix to add.
8128
+ * @returns A function that adds the prefix to a string.
8095
8129
  */
8096
8130
  function addPrefixFunction(prefix) {
8097
8131
  return input => {
8098
8132
  return input.startsWith(prefix) ? input : prefix + input;
8099
8133
  };
8100
8134
  }
8135
+ /**
8136
+ * Adds a suffix to a string if it does not already end with that suffix.
8137
+ * @param suffix The suffix to add.
8138
+ * @param input The string to modify.
8139
+ * @returns The modified string.
8140
+ */
8101
8141
  function addSuffix(suffix, input) {
8102
8142
  return addSuffixFunction(suffix)(input);
8103
8143
  }
8104
8144
  /**
8105
- * Creates an AddSuffixFunction
8106
- *
8107
- * @param input
8108
- * @param replacement
8109
- * @param is
8110
- * @returns
8145
+ * Creates a function that adds a configured suffix to the input string if it does not exist on that string.
8146
+ * @param suffix The suffix to add.
8147
+ * @returns A function that adds the suffix to a string.
8111
8148
  */
8112
8149
  function addSuffixFunction(suffix) {
8113
8150
  return input => {
@@ -8115,10 +8152,10 @@ function addSuffixFunction(suffix) {
8115
8152
  };
8116
8153
  }
8117
8154
  /**
8118
- *
8119
- * @param minLength
8120
- * @param padCharacter
8121
- * @returns
8155
+ * Pads the start of a string to a minimum length.
8156
+ * @param minLength The minimum length of the string.
8157
+ * @param padCharacter The character to use for padding.
8158
+ * @returns A function that pads the start of a string.
8122
8159
  */
8123
8160
  function padStartFunction(minLength, padCharacter) {
8124
8161
  return input => input.padStart(minLength, padCharacter);
@@ -11059,7 +11096,8 @@ const MS_IN_HOUR = MS_IN_MINUTE * 60;
11059
11096
  */
11060
11097
  const MS_IN_DAY = MS_IN_HOUR * HOURS_IN_DAY;
11061
11098
  /**
11062
- * Retrieves the MonthOfYear value (1-12) from the input Date.
11099
+ * Retrieves the MonthOfYear value (1-12) from the input Date in the current system timezone.
11100
+ *
11063
11101
  * Converts JavaScript's 0-based month (0-11) to a 1-based month (1-12).
11064
11102
  *
11065
11103
  * @param date - The date to extract the month from
@@ -11068,6 +11106,17 @@ const MS_IN_DAY = MS_IN_HOUR * HOURS_IN_DAY;
11068
11106
  function monthOfYearFromDate(date) {
11069
11107
  return monthOfYearFromDateMonth(date.getMonth());
11070
11108
  }
11109
+ /**
11110
+ * Retrieves the MonthOfYear value (1-12) from the input Date in the UTC timezone.
11111
+ *
11112
+ * Converts JavaScript's 0-based month (0-11) to a 1-based month (1-12).
11113
+ *
11114
+ * @param date - The date to extract the month from
11115
+ * @returns The month of year as a number from 1-12
11116
+ */
11117
+ function monthOfYearFromUTCDate(date) {
11118
+ return monthOfYearFromDateMonth(date.getUTCMonth());
11119
+ }
11071
11120
  /**
11072
11121
  * Converts a JavaScript Date month (0-11) to a MonthOfYear (1-12).
11073
11122
  *
@@ -14866,19 +14915,27 @@ function makeTimer(duration, startImmediately = true) {
14866
14915
  let currentDuration = duration;
14867
14916
  const promiseRef = promiseReference();
14868
14917
  const getDurationRemaining = () => {
14918
+ let result;
14869
14919
  switch (state) {
14870
14920
  case 'complete':
14871
- return 0;
14921
+ result = 0;
14922
+ break;
14872
14923
  case 'running':
14873
- return Math.max(0, currentDuration - (new Date().getTime() - startedAt.getTime()));
14924
+ result = Math.max(0, currentDuration - (new Date().getTime() - startedAt.getTime()));
14925
+ break;
14874
14926
  case 'paused':
14875
- return null;
14927
+ result = null;
14928
+ break;
14876
14929
  }
14930
+ return result;
14931
+ };
14932
+ const completeNow = () => {
14933
+ state = 'complete';
14934
+ promiseRef.resolve();
14877
14935
  };
14878
14936
  const checkComplete = () => {
14879
14937
  if (state !== 'complete' && getDurationRemaining() === 0) {
14880
- state = 'complete';
14881
- promiseRef.resolve();
14938
+ completeNow();
14882
14939
  }
14883
14940
  };
14884
14941
  const enqueueCheck = () => {
@@ -14915,9 +14972,9 @@ function makeTimer(duration, startImmediately = true) {
14915
14972
  };
14916
14973
  const destroy = () => {
14917
14974
  checkComplete();
14918
- if (state === 'running') {
14975
+ if (state !== 'complete') {
14976
+ state = 'cancelled';
14919
14977
  promiseRef.reject(new TimerCancelledError());
14920
- state = 'complete';
14921
14978
  }
14922
14979
  };
14923
14980
  if (startImmediately) {
@@ -14946,6 +15003,7 @@ function makeTimer(duration, startImmediately = true) {
14946
15003
  get durationRemaining() {
14947
15004
  return getDurationRemaining();
14948
15005
  },
15006
+ completeNow,
14949
15007
  start,
14950
15008
  stop,
14951
15009
  reset,
@@ -15475,6 +15533,12 @@ function readableStreamToBuffer(stream) {
15475
15533
  });
15476
15534
  }
15477
15535
 
15536
+ /**
15537
+ * Joins the host and port into a string.
15538
+ *
15539
+ * @param config
15540
+ * @returns
15541
+ */
15478
15542
  function joinHostAndPort(config) {
15479
15543
  if (config) {
15480
15544
  return `${config.host}:${config.port}`;
@@ -15863,43 +15927,95 @@ function typedServiceRegistry(config) {
15863
15927
  return instance;
15864
15928
  }
15865
15929
 
15930
+ /**
15931
+ * Base error class for storage-related issues.
15932
+ */
15866
15933
  class StoredDataError extends makeError.BaseError {
15934
+ /**
15935
+ * Creates an instance of StoredDataError.
15936
+ * @param message Optional error message.
15937
+ */
15867
15938
  constructor(message) {
15868
15939
  super(message);
15869
15940
  }
15870
15941
  }
15942
+ /**
15943
+ * Error thrown when requested data does not exist in storage.
15944
+ */
15871
15945
  class DataDoesNotExistError extends StoredDataError {
15946
+ /**
15947
+ * Creates an instance of DataDoesNotExistError.
15948
+ * @param message Optional error message.
15949
+ */
15872
15950
  constructor(message) {
15873
15951
  super(message);
15874
15952
  }
15875
15953
  }
15954
+ /**
15955
+ * Error thrown when data exists in storage but is considered expired.
15956
+ *
15957
+ * @template T The type of the data that is expired.
15958
+ */
15876
15959
  class DataIsExpiredError extends StoredDataError {
15960
+ /**
15961
+ * Creates an instance of DataIsExpiredError.
15962
+ * @param data The expired data, including metadata.
15963
+ * @param message Optional error message. If not provided, a default message will be used.
15964
+ */
15877
15965
  constructor(data, message) {
15878
- super(message);
15966
+ super(message != null ? message : 'Data has expired.');
15879
15967
  this.data = void 0;
15880
15968
  this.data = data;
15881
15969
  }
15882
15970
  }
15883
15971
 
15972
+ /**
15973
+ * A StorageObject implementation that stores data in memory.
15974
+ * This is not persistent and will be cleared when the JavaScript context is lost.
15975
+ */
15884
15976
  class MemoryStorageInstance {
15885
15977
  constructor() {
15886
15978
  this._length = 0;
15887
15979
  this._storage = {};
15888
15980
  }
15981
+ /**
15982
+ * The number of items stored.
15983
+ */
15889
15984
  get length() {
15890
15985
  return this._length;
15891
15986
  }
15987
+ /**
15988
+ * Returns the key at the given index.
15989
+ * @param index The index of the key to retrieve.
15990
+ * @returns The key string if found, otherwise null.
15991
+ */
15892
15992
  key(index) {
15893
15993
  var _Object$keys$index;
15894
15994
  return (_Object$keys$index = Object.keys(this._storage)[index]) != null ? _Object$keys$index : null;
15895
15995
  }
15996
+ /**
15997
+ * Checks if a key exists in the storage.
15998
+ * @param key The key to check.
15999
+ * @returns True if the key exists, false otherwise.
16000
+ */
15896
16001
  hasKey(key) {
15897
16002
  return objectHasKey(this._storage, key);
15898
16003
  }
16004
+ /**
16005
+ * Retrieves an item from storage.
16006
+ * @param key The key of the item to retrieve.
16007
+ * @returns The item string if found, otherwise null or undefined.
16008
+ */
15899
16009
  getItem(key) {
15900
16010
  var _this$_storage$key;
15901
16011
  return (_this$_storage$key = this._storage[key]) != null ? _this$_storage$key : null;
15902
16012
  }
16013
+ /**
16014
+ * Sets an item in storage.
16015
+ * If the item is null or undefined, the key will be removed.
16016
+ * @param key The key of the item to set.
16017
+ * @param item The item string to store.
16018
+ */
15903
16019
  setItem(key, item) {
15904
16020
  if (item == null) {
15905
16021
  this.removeItem(key);
@@ -15910,17 +16026,28 @@ class MemoryStorageInstance {
15910
16026
  this._storage[key] = String(item);
15911
16027
  }
15912
16028
  }
16029
+ /**
16030
+ * Removes an item from storage.
16031
+ * @param key The key of the item to remove.
16032
+ */
15913
16033
  removeItem(key) {
15914
16034
  if (this.hasKey(key)) {
15915
16035
  delete this._storage[key]; // Remove the property
15916
16036
  this._length = this._length - 1;
15917
16037
  }
15918
16038
  }
16039
+ /**
16040
+ * Clears all items from the storage.
16041
+ */
15919
16042
  clear() {
15920
16043
  this._storage = {};
15921
16044
  this._length = 0;
15922
16045
  }
15923
16046
  }
16047
+ /**
16048
+ * A shared, global instance of MemoryStorageInstance.
16049
+ * Useful for singleton-like access to an in-memory store throughout an application.
16050
+ */
15924
16051
  const SHARED_MEMORY_STORAGE = new MemoryStorageInstance();
15925
16052
 
15926
16053
  /**
@@ -15933,8 +16060,21 @@ class SimpleStorageObject {}
15933
16060
  * Has the same interface as localStorage for the web.
15934
16061
  */
15935
16062
  class StorageObject extends SimpleStorageObject {}
16063
+ /**
16064
+ * Extended synchronous Class/Interface for storing string values with additional properties.
16065
+ */
15936
16066
  class FullStorageObject extends StorageObject {}
16067
+ /**
16068
+ * Utility class for working with StorageObject instances.
16069
+ */
15937
16070
  class StorageObjectUtility {
16071
+ /**
16072
+ * Retrieves all keys from a StorageObject, optionally filtering by a prefix.
16073
+ *
16074
+ * @param storageObject The StorageObject to retrieve keys from.
16075
+ * @param prefix Optional prefix to filter keys by.
16076
+ * @returns An array of StoredDataStorageKey.
16077
+ */
15938
16078
  static allKeysFromStorageObject(storageObject, prefix) {
15939
16079
  const length = storageObject.length;
15940
16080
  let result;
@@ -16268,29 +16408,46 @@ function findBestSplitStringTreeChildMatchPath(tree, value) {
16268
16408
 
16269
16409
  /*eslint @typescript-eslint/no-explicit-any:"off"*/
16270
16410
  // any is used with intent here, as the recursive TreeNode value requires its use to terminate.
16411
+ /**
16412
+ * Implementation for expandTreeFunction. Creates a function that can expand a single value into a tree structure.
16413
+ *
16414
+ * This factory function takes a configuration object that specifies how to retrieve children for any given value (`getChildren`)
16415
+ * and optionally, how to construct the nodes themselves (`makeNode`). If `makeNode` is not provided, a default node structure is used.
16416
+ * The returned function recursively builds a tree from a root value.
16417
+ *
16418
+ * @template T The type of the value being processed at each node.
16419
+ * @template N The type of the TreeNode to be created. Defaults to TreeNode<T, any> if not specified by ExpandTreeWithNodeBuilder.
16420
+ * @param config An ExpandTree<T> or ExpandTreeWithNodeBuilder<T, N> configuration object.
16421
+ * @returns An ExpandTreeFunction<T, N> that takes a root value and returns its corresponding tree structure.
16422
+ */
16271
16423
  function expandTreeFunction(config) {
16272
16424
  var _config$makeNode;
16273
- const makeNode = (_config$makeNode = config.makeNode) != null ? _config$makeNode : node => node;
16425
+ const makeNodeFromConfig = (_config$makeNode = config.makeNode) != null ? _config$makeNode : basicNode => basicNode;
16274
16426
  const expandFn = (value, parent) => {
16275
16427
  const depth = parent ? parent.depth + 1 : 0;
16276
- const treeNode = {
16428
+ const treeNodeWithoutChildren = {
16277
16429
  depth,
16278
16430
  parent,
16279
16431
  value
16280
16432
  };
16281
- const node = makeNode(treeNode);
16433
+ // Use Omit<N, 'children'> here as makeNodeFromConfig returns the node without children initially.
16434
+ // The children are attached in the next step.
16435
+ const node = makeNodeFromConfig(treeNodeWithoutChildren); // Cast is necessary because children are added after
16282
16436
  const childrenValues = config.getChildren(value);
16283
16437
  node.children = childrenValues ? childrenValues.map(x => expandFn(x, node)) : undefined;
16284
16438
  return node;
16285
16439
  };
16286
- return root => expandFn(root);
16440
+ return rootValue => expandFn(rootValue);
16287
16441
  }
16288
16442
  /**
16289
- * Convenience function for expanding multiple values into trees then merging them together into a single array.
16443
+ * Convenience function for expanding multiple root values into an array of trees.
16444
+ * Each value in the input array is treated as a root for a new tree.
16290
16445
  *
16291
- * @param values
16292
- * @param expandFn
16293
- * @returns
16446
+ * @template T The type of the input values.
16447
+ * @template N The type of the TreeNode in the resulting trees. Must extend TreeNode<T, N>.
16448
+ * @param values An array of root values of type T to expand.
16449
+ * @param expandFn An ExpandTreeFunction<T, N> used to expand each value into a tree.
16450
+ * @returns An array of N, where each N is the root node of an expanded tree.
16294
16451
  */
16295
16452
  function expandTrees(values, expandFn) {
16296
16453
  return values.map(expandFn);
@@ -16312,6 +16469,18 @@ function flattenTree(tree) {
16312
16469
  function flattenTreeToArray(tree, array) {
16313
16470
  return flattenTreeToArrayFunction()(tree, array);
16314
16471
  }
16472
+ /**
16473
+ * Implementation for flattenTreeToArrayFunction.
16474
+ *
16475
+ * This function serves as a factory to produce a flattening function. The produced function
16476
+ * will traverse a tree and collect either the nodes themselves or a mapped value from each node
16477
+ * into an array.
16478
+ *
16479
+ * @template N The type of the tree node, must extend TreeNode.
16480
+ * @template V The type of the values to be collected in the output array.
16481
+ * @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).
16482
+ * @returns A FlattenTreeFunction<N, V> that performs the tree flattening.
16483
+ */
16315
16484
  function flattenTreeToArrayFunction(mapNodeFn) {
16316
16485
  const mapNode = mapNodeFn != null ? mapNodeFn : x => x;
16317
16486
  const flattenFn = (tree, array = []) => {
@@ -16339,11 +16508,17 @@ function flattenTrees(trees, flattenFn) {
16339
16508
  /*eslint @typescript-eslint/no-explicit-any:"off"*/
16340
16509
  // any is used with intent here, as the recursive TreeNode value requires its use to terminate.
16341
16510
  /**
16342
- * Creates an ExpandFlattenTree function.
16511
+ * Creates an ExpandFlattenTreeFunction by composing an expansion function and a flattening function.
16343
16512
  *
16344
- * @param expand
16345
- * @param flatten
16346
- * @returns
16513
+ * 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)
16514
+ * and another function to flatten these trees into a single array of values `V`.
16515
+ *
16516
+ * @template T The type of the initial input values.
16517
+ * @template V The type of the values in the final flattened output array.
16518
+ * @template N The type of the intermediate tree nodes. Must extend TreeNode with value T and children of type N.
16519
+ * @param expand An ExpandTreeFunction (values: T[]) => N[] that converts an array of T into an array of tree nodes N.
16520
+ * @param flatten A FlattenTreeFunction (tree: N, array?: V[]) => V[] that flattens a tree of N nodes into an array of V values.
16521
+ * @returns An ExpandFlattenTreeFunction (values: T[]) => V[] that performs the combined expansion and flattening.
16347
16522
  */
16348
16523
  function expandFlattenTreeFunction(expand, flatten) {
16349
16524
  return values => {
@@ -16355,9 +16530,9 @@ function expandFlattenTreeFunction(expand, flatten) {
16355
16530
  /**
16356
16531
  * Reduces an array of booleans with the logical AND operation.
16357
16532
  *
16358
- * @param array - Array of boolean values to reduce
16359
- * @param emptyArrayValue - Value to return if the array is empty (default: undefined which becomes false)
16360
- * @returns The result of ANDing all boolean values in the array
16533
+ * @param array - Array of boolean values to reduce.
16534
+ * @param emptyArrayValue - Value to return if the array is empty. If not provided and the array is empty, a TypeError will be thrown.
16535
+ * @returns The result of ANDing all boolean values in the array.
16361
16536
  */
16362
16537
  function reduceBooleansWithAnd(array, emptyArrayValue) {
16363
16538
  return reduceBooleansWithAndFn(emptyArrayValue)(array);
@@ -16365,9 +16540,9 @@ function reduceBooleansWithAnd(array, emptyArrayValue) {
16365
16540
  /**
16366
16541
  * Reduces an array of booleans with the logical OR operation.
16367
16542
  *
16368
- * @param array - Array of boolean values to reduce
16369
- * @param emptyArrayValue - Value to return if the array is empty (default: undefined which becomes false)
16370
- * @returns The result of ORing all boolean values in the array
16543
+ * @param array - Array of boolean values to reduce.
16544
+ * @param emptyArrayValue - Value to return if the array is empty. If not provided and the array is empty, a TypeError will be thrown.
16545
+ * @returns The result of ORing all boolean values in the array.
16371
16546
  */
16372
16547
  function reduceBooleansWithOr(array, emptyArrayValue) {
16373
16548
  return reduceBooleansWithOrFn(emptyArrayValue)(array);
@@ -16375,8 +16550,8 @@ function reduceBooleansWithOr(array, emptyArrayValue) {
16375
16550
  /**
16376
16551
  * Creates a function that reduces an array of booleans with the logical AND operation.
16377
16552
  *
16378
- * @param emptyArrayValue - Value to return if the array is empty (default: undefined which becomes false)
16379
- * @returns A function that takes an array of booleans and returns the result of ANDing them
16553
+ * @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.
16554
+ * @returns A function that takes an array of booleans and returns the result of ANDing them.
16380
16555
  */
16381
16556
  function reduceBooleansWithAndFn(emptyArrayValue) {
16382
16557
  return reduceBooleansFn((a, b) => a && b, emptyArrayValue);
@@ -16384,8 +16559,8 @@ function reduceBooleansWithAndFn(emptyArrayValue) {
16384
16559
  /**
16385
16560
  * Creates a function that reduces an array of booleans with the logical OR operation.
16386
16561
  *
16387
- * @param emptyArrayValue - Value to return if the array is empty (default: undefined which becomes false)
16388
- * @returns A function that takes an array of booleans and returns the result of ORing them
16562
+ * @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.
16563
+ * @returns A function that takes an array of booleans and returns the result of ORing them.
16389
16564
  */
16390
16565
  function reduceBooleansWithOrFn(emptyArrayValue) {
16391
16566
  return reduceBooleansFn((a, b) => a || b, emptyArrayValue);
@@ -16393,9 +16568,9 @@ function reduceBooleansWithOrFn(emptyArrayValue) {
16393
16568
  /**
16394
16569
  * Creates a function that reduces an array of booleans using a custom reduce function.
16395
16570
  *
16396
- * @param reduceFn - Function that takes two boolean values and returns a single boolean
16397
- * @param emptyArrayValue - Value to return if the array is empty (default: undefined which uses the standard reduce behavior)
16398
- * @returns A function that takes an array of booleans and returns the result of reducing them
16571
+ * @param reduceFn - Function that takes two boolean values and returns a single boolean.
16572
+ * @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.
16573
+ * @returns A function that takes an array of booleans and returns the result of reducing them.
16399
16574
  */
16400
16575
  function reduceBooleansFn(reduceFn, emptyArrayValue) {
16401
16576
  const rFn = array => Boolean(array.reduce(reduceFn));
@@ -16408,8 +16583,8 @@ function reduceBooleansFn(reduceFn, emptyArrayValue) {
16408
16583
  /**
16409
16584
  * Creates a new BooleanFactory that generates random boolean values based on chance.
16410
16585
  *
16411
- * @param config - Configuration for the boolean factory, including the chance of returning true
16412
- * @returns A factory function that generates random boolean values
16586
+ * @param config - Configuration for the boolean factory, including the chance of returning true.
16587
+ * @returns A factory function (`BooleanFactory`) that generates random boolean values based on the configured chance.
16413
16588
  */
16414
16589
  function booleanFactory(config) {
16415
16590
  const {
@@ -16425,8 +16600,8 @@ function booleanFactory(config) {
16425
16600
  /**
16426
16601
  * Returns a random boolean based on the specified chance.
16427
16602
  *
16428
- * @param chance - Number between 0 and 100 representing the percentage chance of returning true (default: 50)
16429
- * @returns A random boolean value with the specified probability of being true
16603
+ * @param chance - Number between 0.0 and 100.0 representing the percentage chance of returning true (default: 50, i.e., 50%).
16604
+ * @returns A random boolean value with the specified probability of being true.
16430
16605
  */
16431
16606
  function randomBoolean(chance = 50) {
16432
16607
  return booleanFactory({
@@ -16465,15 +16640,38 @@ class DestroyFunctionObject {
16465
16640
  }
16466
16641
  }
16467
16642
 
16643
+ /**
16644
+ * Decodes a list of hashed string values using a provided list of potential original values and a hash function.
16645
+ *
16646
+ * @param hashedValues An array of hashed strings to decode.
16647
+ * @param decodeValues An array of potential original string values.
16648
+ * @param hashFn A function that takes a string and returns its hashed representation.
16649
+ * @returns An array of decoded strings. Values that cannot be decoded are filtered out.
16650
+ */
16468
16651
  function decodeHashedValues(hashedValues, decodeValues, hashFn) {
16469
16652
  const hashDecodeMap = makeHashDecodeMap(decodeValues, hashFn);
16470
16653
  return decodeHashedValuesWithDecodeMap(hashedValues, hashDecodeMap);
16471
16654
  }
16655
+ /**
16656
+ * Creates a `HashDecodeMap` from a list of potential original string values and a hash function.
16657
+ * The map's keys are the hashed versions of the `decodeValues`, and the values are the original `decodeValues`.
16658
+ *
16659
+ * @param decodeValues An array of potential original string values.
16660
+ * @param hashFn A function that takes a string and returns its hashed representation.
16661
+ * @returns A `HashDecodeMap` for decoding hashed values.
16662
+ */
16472
16663
  function makeHashDecodeMap(decodeValues, hashFn) {
16473
16664
  const keyValuePairs = decodeValues.map(x => [hashFn(x), x]);
16474
16665
  const map = new Map(keyValuePairs);
16475
16666
  return map;
16476
16667
  }
16668
+ /**
16669
+ * Decodes a list of hashed string values using a pre-built `HashDecodeMap`.
16670
+ *
16671
+ * @param hashedValues An array of hashed strings to decode.
16672
+ * @param decodeMap A `HashDecodeMap` to use for looking up original values.
16673
+ * @returns An array of decoded strings. Values that cannot be decoded are filtered out.
16674
+ */
16477
16675
  function decodeHashedValuesWithDecodeMap(hashedValues, decodeMap) {
16478
16676
  const values = hashedValues.map(x => decodeMap.get(x));
16479
16677
  return filterMaybeArrayValues(values);
@@ -17199,6 +17397,7 @@ exports.modifyModelMapFunctions = modifyModelMapFunctions;
17199
17397
  exports.monthDaySlashDateToDateString = monthDaySlashDateToDateString;
17200
17398
  exports.monthOfYearFromDate = monthOfYearFromDate;
17201
17399
  exports.monthOfYearFromDateMonth = monthOfYearFromDateMonth;
17400
+ exports.monthOfYearFromUTCDate = monthOfYearFromUTCDate;
17202
17401
  exports.multiKeyValueMapFactory = multiKeyValueMapFactory;
17203
17402
  exports.multiValueMapBuilder = multiValueMapBuilder;
17204
17403
  exports.neMostLatLngPoint = neMostLatLngPoint;