Documentation woes

[wmertens]

I really like JSGI, I really like promises and therefore I want to really like Joey, but it's hard to get going with it 😕

I'm requesting a more thorough documentation than the set of examples that the readme has. Obviously, many functions are missing documentation altogether, but it goes deeper.

I understand the basics, but a definition for Joey applications and middleware would be nice. http://jackjs.org/writing-jsgi-applications.html and http://jackjs.org/writing-jsgi-middleware.html were somewhat helpful but still different from Joey. For example, the q-io middleware factories seem to return fn(request, response) but I don't understand why the response would ever be used.

The way a Joey chain is built is also quite peculiar. I think it would be helpful to show what the call tree looks like for a simple Joey app and how it gets built up.

(When I make a middleware that works with .use(myMW) and do joey.install({mw: myMW})...mw()... it will crash when trying to apply on undefined. Is that supposed to work? It doesn't reference next on the applied function?)

Others:

• I think a FAQ would be "why should I use this instead of Express". I think the answer would be something involving promises, being able to change/transform an answer in middleware, never confusing request and result, ...
• the Readme.md still mentions Jaque while that's no longer used
• there is no mention of where to go with questions.
• any projects or non-trivial examples that use Joey would be good too

[kriskowal]

This is all great feedback. I will leave the issue open as a hub for taking care of each of these points.

• Document functions that lack documentation
• Full reference in addition to the graduated tutorial
• Type specification for request, response, app, and chaining
• Remove "response" argument from "app" across the board. This was an experiment in an attempt to make it easier to bridge to and from Connect/Express/Node style middleware, but I went with another approach in the implementation of nap.
• illustrate the algebra for composing middleware with chains
• compare to express/connect
• elimintate references to Jaque. All that is now in Q-IO HTTP Apps
• make a note to direct questions to q-continuum at googlegroups, or come up with another forum for Q&A, perhaps a preferred tag on Stack Exchange
• lets file a separate issue for the problem with install—that looks like it should work
• I am not certain that there are any noteworthy apps using Joey today. It is still in the pariah phase and there is a lot of room for a killer app to guide its evolution.

[wmertens]

• filed an issue for install()

Another thing to document would be what Joey tries to be and its design philosophy. As far as I can tell it tries to be a reasonably thin chain creator leveraging q-io for the JSGI heavy lifting.

[rohni]

+1. Perhaps this is a really stupid question but I am completely stuck trying to get my hands on the body of a POST, PUT etc.
So far I have managed to get my hands on a promise of a Buffer. But to get there I have had to wade through the code, which lead to q-io, and then more code which lead me back to the docs etc.

Just adding an example (unless I missed it) of here comes a POST request, and here is how to get at the body. I am still new to the world of nodejs, and have just been figuring out promises, so something obvious would be really great.

[Stuk]

@rohni Here's an example of parsing the values from a POST request: https://gist.github.com/Stuk/6861192. Note: this doesn't handle file uploads.

[rohni]

@Stuk Thanks, that is actually really helpful. I actually worked it out over the weekend. Part of the problem was getting used to promises.

Actually the next question was how to use joey as a client to send a post request to a web service. I finally gave up and just used node's http module.

Interesting side track, was seeing how it would be pretty much impossible to use promises with http.request, as it expects a callback, and then you add your data to the request stream after it has been created. So, using something like q.nbind to tame it, will not work as you still need to get at the request object in order to add data to its stream. I am probably missing something.

I put the code here:
https://gist.github.com/rohni/6934986

I guess, I am wondering how you would do this in joey, and/or failing that, make it promisified. I know you can use q.deferred on the returns from the callback, but that seems a bit like cheating. :)

[Stuk]

No problem.

Take a look at @kriskowal's latest exciting work in the world of promise streams: kriskowal/q-io#57. As Joey is based on Q-IO this should solve your problem when it makes its way in.

[wmertens]

Yeah I couldn't quite figure out joey as a http client either, so I use q-io/http.

var HTTP = require('q-io/http');
HTTP.read({
url: ...
method: 'POST',
body: [<form-encoded things, there's some sugar missing here>],
headers: {
"Content-Type": "application/x-www-form-urlencoded"
}
})
.timeout(60000)
.then(function(body) {
...
})

Wout.

On Oct 11, 2013, at 15:54 , rohni notifications@github.com wrote:

@Stuk Thanks, that is actually really helpful. I actually worked it out over the weekend. Part of the problem was getting used to promises.

Actually the next question was how to use joey as a client to send a post request to a web service. I finally gave up and just used node's http module.

Interesting side track, was seeing how it would be pretty much impossible to use promises with http.request, as it expects a callback, and then you add your data to the request stream after it has been created. So, using something like q.nbind to tame it, will not work as you still need to get at the request object in order to add data to its stream. I am probably missing something.

I put the code here:
https://gist.github.com/rohni/6934986

I guess, I am wondering how you would do this in joey, and/or failing that, make it promisified. I know you can use q.deferred on the returns from the callback, but that seems a bit like cheating. :)

—
Reply to this email directly or view it on GitHub.

[rohni]

@wmertens Cool thanks. I messed around with node's http.request and it took some puzzling, because you have a stream with events as well as the callback (which seems to just be another event underneath).

Next time I am having to send post/put requests I will give it a shot.

In the end I came up with this, which assumes you are dealing with json i.e. a json based web service:
https://gist.github.com/rohni/6974132

It works for what I need, and being able to use promises makes the other bits of my code much simpler. And I finally have a clue how to use q.defer(), which was the last big hole in my understanding. :)

@Stuk I look forward to the new promise streams. They would make things very nice.