search

montagejs / joey

An HTTP content negotiation client and server JavaScript library, inspired by Sinatra and JSGI, and using Q promises.
Other
40 stars 7 forks source link

Documentation woes #4

Open wmertens opened 11 years ago

wmertens commented 11 years ago

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 :confused:

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:

kriskowal commented 11 years ago

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

wmertens commented 11 years ago

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 commented 10 years ago

+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 commented 10 years ago

@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 commented 10 years ago

@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 commented 10 years ago

No problem.

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

wmertens commented 10 years ago

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 commented 10 years ago

@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.