[Umbrella] collections APIs

[LionC]

collections

This is an umbrella issue for the collections module, which has landed in std with this initial PR and a lot of new contributions since. The goal of this issue is to give an overview about functions that have alreayd been implemented, are being worked on and have not been started yet.

For more details on the idea behind the module, check out its Readme and contribution guide. For more details on the history of the module and its proposed signatures, see the original proposal PR.

If you want to implement one of the missing functions, please open a separate PR for it and keep discussion in that PR. Please read the contribution guide and make sure to keep the checklist in mind before opening your PR / marking it ready for review.

If you want to add onto or discuss the list, please do that here.

Unstarted / Suggestions

None right now

In Progress

• filterNotNullish feat(collections): add filterNotNullish #1168
• filterValuesNotNullish feat(collections): add filterValuesNotNullish #1186
• without feat(collections): Returns an array excluding single given value #1074

Done

• aggregateGroups feat(collections): add aggregateGroups #1553
• associateBy Implement collections/associateBy #1071
• associateWith feat(collections): Add associatewith #1213
• chunk Proposal: std/collections - first part #993
• deepMerge feat(collections): add deepMerge #1075
• distinct Proposal: std/collections - first part #993
• distinctBy Proposal: std/collections - first part #993
• dropLastWhile feat(collections): add dropLastWhile #1193
• dropWhile feat(collections): add dropWhile #1185
• filterEntries Proposal: std/collections - first part #993
• filterKeys Proposal: std/collections - first part #993
• filterValues Proposal: std/collections - first part #993
• findLast Proposal: std/collections - first part #993
• findLastIndex feat(collections): Returns the index of the last element in the given array matching the given predicate #1062
• firstNotNullishOf feat(collections): add firstNotNullishOf #1167
• groupBy Proposal: std/collections - first part #993
• includesValue feat(collections): add includesValue #1184
• intersect Proposal: std/collections - first part #993
• joinToString feat(collections): add joinToString #1223
• mapEntries Proposal: std/collections - first part #993
• mapKeys Proposal: std/collections - first part #993
• mapNotNullish Add mapNotNullish to collections #1103
• mapValues Proposal: std/collections - first part #993
• maxBy feat(collections): add maxBy #1156
• maxOf feat(collections): add maxOf #1144
• maxWith feat(collections): add maxWith #1170
• minBy feat(collections): add minBy #1157
• minOf feat(collections): add minOf  #1164
• minWith feat(collections): add minWith #1169
• partition Proposal: std/collections - first part #993
• permutations Proposal: std/collections - first part #993
• reduceGroups feat(collections): add reduceGroups #1187
• runningReduce feat (collections): add runningReduce #1226
• sample feat(collections): add sample #1212
• single feat(collection): add findSingle #1166
• sortBy Implement collections/sortBy ( closes #1061 ) #1069
• sumOf feat(collections): add sumOf #1108
• takeLastWhile feat(collections): adds takeLastWhile #1179
• takeWhile feat(collections): add takeWhile #1175
• union Proposal: std/collections - first part #993
• unzip Proposal: std/collections - first part #993
• windowed feat(collections): add slidingWindows #1191
• withoutAll feat(collections): Add withoutAll that returns an array excluding all given values #1100
• zip initial PR

[LionC]

I offered @kt3k to open and maintain this so he does not have to :-) @kt3k you can close the old issue

[kt3k]

Note: we sometimes drop the items from proposal when the implementation is too trivial.

This Luca's comment describes the reasoning behind it well.
#1168 (review)

[LionC]

Note: we sometimes drop the items from proposal when the implementation is too trivial.

This Luca's comment describes the reasoning behind it well.
#1168 (review)

I will keep them in the list striked out as seen above.

[LionC]

As we approach being pretty much API complete compared to the Kotlin package that inspired this (and removing the ones that we have deemed not fitting for JS right now), I would like to propose three last functions to complete the modules API for now. All three are taken mostly directly from kotlin/std/collections and lodash.

Comments welcome, I will add them to the list above soon :-)

associateWith

/**
* Builds a new Record using the given array as keys and choosing a value for each
* key using the given selector.
*/
export function associateWith<T>(array: readonly string[], selector: (key: string) => T): Record<string, T>

Missing sister function to the already implemented associateBy, used if you have an array of keys that you need to transform to a record.

joinToString

export type JoinToStringOptions = { separator?: string, prefix?: string, suffix?: string }
/**
* Transforms the elements in the given array to strings using the given selector. Joins
* the produced strings into one using the given separator and applying the given prefix
* and suffix to the whole string afterwards. Returns the resulting string.
*/
export function joinToString<T>(
    array: readonly T[],
    selector: (el: T) => string,
    {
        separator = ", ",
        prefix = "",
        suffix = "",
    }: JoinToStringOptions = {},
): string

This is straight up a more efficient version of use cases around .map().join() chains (and some postprocessing). I talked briefly about this on Discord before and some though it to bee too specific, but in my experience this happens quite a lot (.join() follows .map() more often than not in boring business applications) and we even have four .map().join() calls in non-test code in std itself (in std/http among others).

This also adds convenience to the process by allowing for an optional prefix or suffix. Kotlin also adds the option to truncate by only iterating an optional set number of elements before stopping and adding an optional truncation string. Seemed specific to me, but they also reject things they think to be too narrow, so I am unsure. Input would be welcome.

sample

/**
* Selects an element randomly from the given array and returns it.
*/
export function sample<T>(array: readonly T[]): T | undefined

Useful for all kinds of random cases like random quotes, websites, task distribution logic etc. Even though we have an (in-place) shuffle function in JS, there is no way to just get a random element. Shuffling to get one is really inefficient and the probably correct way to do it with Math.random is something people need to look up and get wrong with off-by-one errors all the time.

[LionC]

I added the above functions to the list and will shamelessly ping the recent contributors to the module, maybe someone wants do implement one of them :-) CC @grian32 @majidsajadi @ayame113 @getspooky

[getspooky]

@LionC good , i will look into associateWith function.

[majidsajadi]

so I take sample and joinToString. @LionC @getspooky

[getspooky]

@LionC can you please confirm this example:

const users = [
   { id: 'a2e', userName: 'Anna' },
   { id: '5f8', userName: 'Arnold' },
   { id: 'd2c', userName: 'Kim' },
]
const usersByLength = associateWith(users, it => it.userName.length)
assertEquals(usersByLength, {
  '4': { id: 'a2e', userName: 'Anna' },
  '6': { id: '5f8', userName: 'Arnold' },
  '3': { id: 'd2c', userName: 'Kim' },
})

[LionC]

@LionC can you please confirm this example:

const users = [
   { id: 'a2e', userName: 'Anna' },
   { id: '5f8', userName: 'Arnold' },
   { id: 'd2c', userName: 'Kim' },
]
const usersByLength = associateWith(users, it => it.userName.length)
assertEquals(usersByLength, {
  '4': { id: 'a2e', userName: 'Anna' },
  '6': { id: '5f8', userName: 'Arnold' },
  '3': { id: 'd2c', userName: 'Kim' },
})

That is associateBy - we already have that in the module :-)

A correct example would be:

const names = [ 'Kim', 'Lara', 'Jonathan' ]
const namesToLength = associateWith(names, it => it.length)

assertEquals(namesToLength, {
    'Kim': 3,
    'Lara': 4,
    'Jonathan': 8,
})

[bartlomieju]

@LionC great work on seeing this proposal through in full! Also thanks to @getspooky, @majidsajadi, @grian32, @ayame113 and other contributors for help implementing all the APIs. This module is a very valuable addition to the standard library!