speak javascript

[dominictarr]

I am very confused by the meaning of the type stuff in the readme. it's like another language.

can we have documentation in javascript please?

I like continuable, but this just confuses me more, and probably puts most people who are not haskellians (i.e. most people) off.

[dominictarr]

what if this: readFile := (String) => Continuable<Buffer> instead was

readFile(filePath) (function (err, buffer) {...})

I think that is A LOT more obvious. just ordinary javascript syntax, but also implies all the types.

it shows that readFile takes a filePath (obviously a string) and it returns a function, (because you are calling it's return value, which expects a normal callback.

This is much more obvious to javascript-wired brains but still implies the haskell types.

[pirfalt]

I also like continuable. If a more javascripty doc is wanted I could help out with some typing, but I won't do it just for fun.

[Raynos]

@dominictarr

So the documentation hints are based on https://github.com/jden/jsig which is a natural javascript way of defining signatures of functions. its not a haskell based thing and it is designed to be readable. Previously the documentation was literally using haskell type signatures which was hard to read.

Any general feedback of making jsig more readable would be appreciated on the jsig repo. Maybe a disclaimer at the top of the documentation mentioning jsig would be useful.

Having thought about this module for a while it doesn't do anything useful other then both which I might break out to a seperate repo / package / module.

[Raynos]

I did actually place both in gens so I guess I don't need this module anymore if I use gens.

[dominictarr]

well, in the very least, you need to have a link to jsig. it's not natural, nor is it javascript. It's not that it's unreadable, it's that it's not understandable. If i'm evaluating a module I'm not gonna read all that documentation. too much documentation is as bad as too much code.

I'd move the types into a separate file, as they are, too confusing. would you take a documentation pull request to make things more javascript friendly?

[Raynos]

@dominictarr i'll take a PR. I'll move the types into a docs.mli file aswell.

[dominictarr]

what is .mli ?

[Raynos]

it's the extension for ocaml which is the syntax highlighting which most closely matches jsig and is supported by github.

[Raynos]

@dominictarr tbh the most important thing this README should do is explain continuables and why to use them.

Documenting the actual functions in this repo can go somewhere else if needed or be made simpler.

Also the first examples of continuables should really use continuable-para & continuable-series as they are more useful.

[pirfalt]

My understanding is that you should use continuables for the same reason you should use promises, to get a standardised api for async code. Difference is that continuables don't cache results or catch thrown errors, also they use the node cb(err, val) pattern instead of coming up with something else, by recognising that.

Having that api you can get higher order functions like map and chain that does error propagation, which in turn allows for things like para and series.

[Raynos]

continuables are great as the simplest interface as close to callbacks as possible to use with para & series which are minimal flow control.

continuables are also great for applying operations on lazy async values. for example continuable-cache is hard to implement with callbacks.

Continuables do not replace callbacks, they could but i dont see the value in it. they are however better flow control then async.js

[dominictarr]

and a another great example how you can do complex stuff like promises without specs and loads of documentation and just using functions.

[Raynos]

@dominictarr

that may be true however I think the LISPY style combinators that I have in this module are not very good in a team environment. I don't think map, join & friends are the way to write async code, too DSL.

I wouldn't personally recommend it.

However I do agree. its a great example how a small composable interface allows you to build really complex things cleanly without having to do bullshit spec, thenables & interop nightmares. Its a great example of functional programming.

[dominictarr]

it's not worth using an abstraction like this unless you are doing something quite complex, a good example is npmd-install, where it's complicated and you have to understand what is going on...

If you are just building an web app, the need for this stuff is greatly reduced...

[Raynos]

That might be what it is. If your doing something trivial there is no point.

If your building a complex distributed asynchronous thing then learn a composable building block abstraction and apply it everywhere for simplificiation.

[Raynos]

Closing this issue due to lack of activity.

Let me know if this is still an issue.