Module: collection_helpers

Various helper methods for dealing with collections (arrays, objects, etc.)

Methods

(inner) addDicts(…dicts) → {StringNumberDict}

Adds up an arbitrary number of StringNumberDicts, returning a new dict.
Parameters:
Name Type Attributes Description
dicts Array.<StringNumberDict> <repeatable>
 Dictionaries to sum.
Returns:
The summed dictionary.
Type
StringNumberDict

(inner) asOptionalArray(value) → {ArArray}

Returns an array containing the value if defined, otherwise an empty array.
Parameters:
Name Type Description
value T | undefined | null The value to wrap.
Returns:
The optional array.
Type
ArArray

(inner) atLeastValues(obj, minValue) → {StringNumberDict}

Returns a new object with only the key/value pairs that have a value greater than minValue.
Parameters:
Name Type Description
obj StringNumberDict The input dictionary.
minValue number The minimum value to include.
Returns:
The filtered dictionary.
Type
StringNumberDict

(inner) average(values) → {number}

Calculates the average of an array of numbers, ignoring null/undefined completely.
Parameters:
Name Type Description
values Array.<number> The array of numbers.
Returns:
The average, or NaN if the array is empty.
Type
number

(async, inner) batchMap(array, fxn, optionsopt) → {Promise.<Array.<any>>}

Processes an array asynchronously in batches.
Parameters:
Name Type Attributes Description
array Array.<T> The array to process.
fxn function The async function to apply.
options object <optional>
 Batch options.
Properties
Name Type Attributes Description
batchSize number <optional>
 Batch size.
logger Logger <optional>
 Logger instance.
sleepBetweenMS number <optional>
 Sleep between batches in ms.
Returns:
The results of mapping items with fxn() argument.
Type
Promise.<Array.<any>>

(inner) checkUniqueRows(array, logger)

Checks if the elements of an array have unique IDs and logs a warning if not.
Parameters:
Name Type Description
array Array.<ApiObjWithID> Array of objects with IDs.
logger Logger Logger to use for warnings.

(inner) computeMinMax(array, valueFxn) → {Optional.<MinMax>}

Computes the minimum and maximum values from an array using a value function.
Parameters:
Name Type Description
array Array.<T> The array to process.
valueFxn function Function to extract value.
Returns:
The min and max values, or null if array is empty.
Type
Optional.<MinMax>

(inner) countValues(items, getKeyopt, countNullsopt) → {StringNumberDict}

Returns a dictionary keyed by the result of getKey() with the count of each key.
Parameters:
Name Type Attributes Description
items Array.<T> The items to count.
getKey function <optional>
 Function to get key.
countNulls boolean <optional>
 Whether to count null keys.
Returns:
The counts dictionary.
Type
StringNumberDict

(inner) decrementCount(counts, kopt, incrementopt) → {StringNumberDict}

Decrements the count for a key in a dictionary.
Parameters:
Name Type Attributes Default Description
counts StringNumberDict The counts dictionary.
k CountKey | null <optional>
 The key to decrement.
increment number <optional>
 1 The decrement amount.
Returns:
The updated dictionary.
Type
StringNumberDict

(inner) filterWithLog(array, filterFxn, logger, reason, objTypeopt) → {Array.<T>}

Filters an array and logs the number of elements removed.
Parameters:
Name Type Attributes Description
array Array.<T> The array to filter.
filterFxn function The filter function.
logger Logger Logger instance.
reason string Reason for filtering.
objType string <optional>
 Object type for logging.
Returns:
The filtered array.
Type
Array.<T>

(inner) findMinMaxId(array) → {MinMaxID|null}

Finds the minimum and maximum id property in an array of objects. TODO: Note that this isn't always safe to use - there can be outliers in the data that result in the minimum ID in a set of toots being wildly out of step with the rest of the IDs. If that happens trying to use the min ID as the maxId param for a fetch will fail (no results). This is an unfixable server side problem that we used to work around with this: static findMinIdForMaxIdParam(toots: Toot[]): string | null { if (toots.length == 0) return null; const idx = Math.min(toots.length - 1, MAX_ID_IDX); return sortByCreatedAt(toots)[idx].id; }
Parameters:
Name Type Description
array Array.<ApiObjWithID> Array of objects with IDs.
Returns:
The min and max IDs, or null if invalid.
Type
MinMaxID | null

(async, inner) getPromiseResults(promises) → {Promise.<PromisesResults.<T>>}

Collates the fulfilled and rejected results from Promise.allSettled() into an easier to handle format.
Parameters:
Name Type Description
promises Array Array of promises.
Returns:
The results object.
Type
Promise.<PromisesResults.<T>>

(inner) groupBy(array, makeKey) → {Record.<string, Array.<T>>}

Groups an array by the result of makeKey(). TODO: Standard library Object.groupBy() requires some tsconfig setting that i don't understand
Parameters:
Name Type Description
array Array.<T> The array to group.
makeKey function Function to get group key.
Returns:
The grouped object.
Type
Record.<string, Array.<T>>

(inner) incrementCount(counts, kopt, incrementopt) → {StringNumberDict}

Increments the count for a key in a dictionary by increment.
Parameters:
Name Type Attributes Default Description
counts StringNumberDict The counts dictionary.
k CountKey | null <optional>
 The key to increment.
increment number <optional>
 1 The increment amount.
Returns:
The updated dictionary.
Type
StringNumberDict

(inner) isRecord(obj) → {boolean}

Return true if the object is a non-null object (not an array, function, etc.).
Parameters:
Name Type Description
obj unknown The object to check.
Returns:
True if it's a non-null object
Type
boolean

(inner) keyById(array) → {Record.<string, T>}

Builds a dictionary from an array keyed by id.
Parameters:
Name Type Description
array Array.<T> Array of objects with id property.
Returns:
The keyed dictionary.
Type
Record.<string, T>

(inner) keyByProperty(array, keyFxn) → {Record.<string, T>}

Builds a dictionary from an array keyed by a property.
Parameters:
Name Type Description
array Array.<T> Array of objects.
keyFxn function Function to get key.
Returns:
The keyed dictionary.
Type
Record.<string, T>

(inner) makeChunks(array, options) → {Array.<Array.<T>>}

Splits an array into chunks of a given size or number of chunks.
Parameters:
Name Type Description
array Array.<T> The array to chunk.
options object Chunk options.
Properties
Name Type Attributes Description
chunkSize number <optional>
 Size of each chunk.
logger Logger <optional>
 Logger instance.
numChunks number <optional>
 Number of chunks.
Returns:
The array of chunks.
Type
Array.<Array.<T>>

(inner) makePercentileChunks(array, fxn, numPercentiles) → {Array.<Array.<T>>}

Sorts an array by a function and divides into numPercentile chunks.
Parameters:
Name Type Description
array Array.<T> The array to sort and chunk.
fxn function Function to get value.
numPercentiles number Number of percentiles.
Returns:
The percentile chunks.
Type
Array.<Array.<T>>

(inner) reduceToCounts(objs, updateCounts) → {StringNumberDict}

Reduces an array to a StringNumberDict using an update function.
Parameters:
Name Type Description
objs Array.<T> The array to reduce.
updateCounts function Update function.
Returns:
The reduced dictionary.
Type
StringNumberDict

(inner) removeKeys(obj, keysToRemoveopt, keysToRemoveIfFalseopt) → {Partial.<T>}

Removes keys from an object if their value is null or in keysToRemove array.
Parameters:
Name Type Attributes Description
obj T The object to clean.
keysToRemove Array.<K> <optional>
 Keys to remove.
keysToRemoveIfFalse Array.<K> <optional>
 Keys to remove if value is false.
Returns:
The cleaned object.
Type
Partial.<T>

(async, inner) resolvePromiseDict(dict, logger) → {Promise.<Record.<string, any>>}

Use Promise.allSettled() to resolve a dictionary of promises in parallel.
Parameters:
Name Type Description
dict PromiseDict Dictionary of promises to resolve.
logger Logger Logger instance for logging errors.
Returns:
The cleaned object.
Type
Promise.<Record.<string, any>>

(inner) shuffle(array) → {Array.<T>}

Randomizes the order of an array.
Parameters:
Name Type Description
array Array.<T> The array to shuffle.
Returns:
The shuffled array.
Type
Array.<T>

(inner) sortKeysByValue(dict) → {Array.<string>}

Sorts the keys of a dictionary by their values in descending order.
Parameters:
Name Type Description
dict StringNumberDict The dictionary to sort.
Returns:
The sorted keys.
Type
Array.<string>

(inner) sortObjsByCreatedAt(array) → {Array.<T>}

Sorts an array of objects by the createdAt property.
Parameters:
Name Type Description
array Array.<T> The array to sort.
Returns:
The sorted array.
Type
Array.<T>

(inner) sortObjsByProps(array, prop, ascendingopt, ignoreCaseopt) → {Array.<T>}

Sorts an array of objects by one or two properties.
Parameters:
Name Type Attributes Description
array Array.<T> The array to sort.
prop Array Property or properties to sort by.
ascending boolean | Array.<boolean> <optional>
 Sort order(s).
ignoreCase boolean <optional>
 Ignore case for string properties.
Returns:
The sorted array.
Type
Array.<T>

(inner) sortedDictString(dict) → {string}

Create a string representation of a dictionary with the keys sorted by their values.
Parameters:
Name Type Description
dict StringNumberDict The dictionary to sort and format.
Returns:
The sorted dictionary as a string.
Type
string

(inner) split(array, condition) → {Array.<Array.<T>>}

Splits an array into two arrays based on a condition.
Parameters:
Name Type Description
array Array.<T> The array to split.
condition function The condition function.
Returns:
The two arrays.
Type
Array.<Array.<T>>

(inner) subtractConstant(dict, constant) → {StringNumberDict}

Subtracts a constant from all values in a dictionary.
Parameters:
Name Type Description
dict StringNumberDict The dictionary.
constant number The constant to subtract.
Returns:
The updated dictionary.
Type
StringNumberDict

(inner) sumArray(array) → {number}

Sums the elements of an array. null and undefined count as 0.
Parameters:
Name Type Description
array Array.<OptionalNumber> The array to sum.
Returns:
The sum (0 if empty)
Type
number

(inner) sumValues(obj) → {number}

Sums the values of a dictionary. null and undefined count as 0.
Parameters:
Name Type Description
obj StringNumberDict | Weights The dictionary.
Returns:
The sum.
Type
number

(inner) swapKeysAndValues(dict) → {StringDict}

Swaps the keys and values of a dictionary.
Parameters:
Name Type Description
dict T The dictionary.
Returns:
The swapped dictionary.
Type
StringDict

(inner) transformKeys(data, transform) → {T}

Recursively applies a transform() function to all keys in a nested object.
Parameters:
Name Type Description
data T The data to transform.
transform function The transform function.
Returns:
The transformed data.
Type
T

(inner) truncateToLength(array, maxRecords, loggeropt) → {Array.<T>}

Truncates an array to a maximum length, logging if truncated.
Parameters:
Name Type Attributes Description
array Array.<T> The array to truncate.
maxRecords number The maximum length.
logger Logger <optional>
 Logger instance.
Returns:
The truncated array.
Type
Array.<T>

(inner) uniquify(array) → {Array.<string>|undefined}

Returns a new array with only unique, non-null string values.
Parameters:
Name Type Description
array Array.<OptionalString> The array to uniquify.
Returns:
The unique array or undefined if empty.
Type
Array.<string> | undefined

(inner) uniquifyApiObjs(cacheKey, array, logger)

Uniquify an array of API objects by the appropriate property. This is a no-op for API objects that don't have a property that can be used to uniquely identify them.
Parameters:
Name Type Description
cacheKey ApiCacheKey The cache key to determine the unique property.
array Array.<T> Array of API objects.
logger Logger Logger to use for warnings.

(inner) uniquifyByProp(rows, transform, logPrefixopt) → {Array.<T>}

Removes elements of an array with duplicate values for a given property.
Parameters:
Name Type Attributes Description
rows Array.<T> The array to uniquify.
transform function Function to get property.
logPrefix string <optional>
 Log prefix.
Returns:
The uniquified array.
Type
Array.<T>

(inner) zipArrays(array1, array2) → {Record.<string, T>}

Zips two arrays into a dictionary
Parameters:
Name Type Description
array1 Array.<string> Keys array.
array2 Array.<T> Values array.
Returns:
The zipped dictionary.
Type
Record.<string, T>
Example
zipArrays([ 'a', 'b', 'c' ], [ 1, 2, 3 ]) -> { a: 1, b: 2, c: 3 }

(async, inner) zipPromiseCalls(args, promiser, loggeropt) → {Promise.<Record.<string, T>>}

Runs a list of Promises in parallel, each generated by a call to promiser(arg), and returns a dict of results keyed by input. Raises error on api_errors:isAccessTokenRevokedError, otherwise just logs a warning and moves on.
Parameters:
Name Type Attributes Description
args Array.<string> The keys.
promiser function The promise function.
logger Logger <optional>
 Logger instance.
Returns:
The results dictionary.
Type
Promise.<Record.<string, T>>