cookbook?

[loveencounterflow]

i've started again with highland.js after becoming aware of it like six months ago. back then i had a hard time grasping the usefulness of the entire concept; in the meantime, i've building up pipedreams, a streaming library of my own that mainly provides utility stuff and ways to cope with some rough edges in the event-stream API. that said, it's in sort of a neglected state because deadline on other stuff. but streaming with pipes is great! this technique has greatly helped me, and when things went wrong and i was at a complete loss i struggled for days to fix that—always feeling the effort was worth the while. now i want to give that pipedreams thing a thorough overhaul (any maybe base it on highland.js); coming back i realize how difficult a lot of the highland sample code is for me to dig. it's also somewhat discouraging to search google for highland.js; you basically always get the same small set of URLs no matter what you asked for as long as the string highlandjs appears in the query.

so what i'd suggest is a cookbook of sorts that shows how to do things the streaming way. i have one single example for this in a note-to-myself style how-to; unfortunately, that code is pseudo, so i still want to make it so it becomes a self-contained minimal working example (MWE) which i think is what cookbooks should provide.

i think the first few paragraphs to The introduction to Reactive Programming you've been missing reflect my feelings here quite well. let's make it easier to get started!

[vjpr]

I had the exact same thought. In fact, I asked this question on Quora yesterday:

Is there a website showing a comparison between imperative and functional approaches to solving common programming problems?

Some similar concepts:

• CoffeeScript Cookbook
• Rosetta Code
• https://www.dartlang.org/docs/synonyms/

Rosetta Code uses MediaWiki, while the CoffeeScript Cookbook is hosted on Github.

For JS it would be cool to see comparisons between the popular functional streaming libraries including Bacon.js. Highland.js and event-stream, as well as LiveScript, Haskell, Scala, Clojure, etc.

[LewisJEllis]

'a cookbook of sorts that shows how to do things the streaming way' - yes, great idea! Would the thing you have in mind be general to streams, or tailored to highland specifically?

A couple related issues: #28 #34. In short - there exists a fair complaint that Highland's examples are often a bit thin, and there aren't many examples of how two or three or four different functions fit together nicely. There are quite a few decent examples floating around here from various discussions, but a place to bring them together and make new ones would be valuable.

One option I like is an examples/ folder on the repo, with fully-independent examples as described in this comment. We could then do a sort of 'Highland Cookbook', either completely auto-generated from that folder, or based heavily on it, pulling in source files etc.

I also like the idea of a comparison sheet, but I'm not sure if it makes sense to do that before we have a collection of examples/operations to compare; maybe something for down the road.

[loveencounterflow]

@LewisJEllis "Would the thing you have in mind be general to streams, or tailored to highland specifically?"—i'm thinking of highland specifically, but then i'm moving over from event-stream, and combining the two and maybe highlighting some API differences would be great.

[jeromew]

yes it would certainly be nice to have a cookbook for highland. The fact that highland works in the browser should make it easy.

it could probably start with a translation from async patterns to highland patterns since I understand that in @caolan's vision, highland should be (among other things) a tool for process orchestration like async. Probably a bit like 'async - new generation' ;-)

Is there a cookbook somewhere for async ?

[LewisJEllis]

I think this blog post is the closest thing.

I think an examples/ folder would be a good the first move on this. After it gets populated a bit, we can think about how to turn that into a nice web page to look at, or how to compare it to other libraries. I can work on this at some point, but it won't be in the next week, so if someone wants to get started, go for it.

[caolan]

Love the idea of adding an examples directory to the repo - I'm also happy to help add some async->highland examples if people think that would be useful? If anyone can point me at some async code that would be good to convert that would be nice.

[LewisJEllis]

171, #192, and this blog post are related. Not sure about any actual (not just examples) code, though, other than that async cookbook post from above.

[deitch]

+1

Yes, please, I have been a devotee of your async lib from pretty early on, and seeing how some common behaviours would be performed using async vs highland would be really helpful.

[brian-gates]

:+1:

[tinchogob]

+1 Highland is powerful and the world should know it

[jwerre]

:+1: