I am currently re-writing @cycle/collection in typescript (#28). In the process, I am asking myself a few questions about the API design. The main question I have is: do we really have to distinguish Collection and Collection.gather?

They both have different behavior that I don't really understand: Collection.gather will wrap additional sources in streams while Collection won't. Why is that exactly? I find it pretty confusing, even more because those streams are created inside cycle/collection so cannot change over time (except with a shamefullySendNext of course).
In fact, I don't really see any real use cases for the Collection function, most of the time collections are tied to a model that evolves over time (I might be wrong about this!)

My suggestion would be to remove the gather method and make Collection behave like gather. This would induce some breaking changes, but I think we can be smart about default values and try to have the smallest footprint possible.
It might be also time to implement the sort function to be able to reorder items of the collection (#3).

This could be the signature of the new Collection function (actually the same as the gather method):

function Collection(Component, sources, items$, idAttr, transformKey)

This means that the user will have to implement the remove case (by updating the item$ stream) be we would benefit form a simpler API and it would remove the confusion about the add$ https://stackoverflow.com/questions/41910459/in-cycle-js-collections-how-does-the-second-sources-stream-relate-to-the-first/41915677

What do you think? I'd be happy to implement this.