My two cents: examples should be standard javascript without streamline. I had to look up the documentation for what streamline does to understand your docs.

Also worth asking: what about streaming the response JSON? It looks like Oboe.js supports reading an existing HTTP stream (docs), but not in the browser. Is that fine?

Oboe.js does work in the browser :)

It seems to be implied that transaction requests immediately (i.e. synchronously) return a stream. This is not technically correct. Due to buffering and batching it is currently asynchronous.

tx.cypher {query, params, headers, raw, commit}, _

I also would prefer that headers, raw, and commit were bundled into an options param. That way you aren't forced to use null params if you want to commit without headers or raw.

My two cents: examples should be standard javascript without streamline.

Great point. Will fix.

Oboe.js does work in the browser :)

Does it have to be the one making the HTTP request though? The API docs seem to imply that the "bring your own stream" feature is only in Node — but do you know if that's actually true in practice?

http://oboejs.com/api#byo-stream

It seems to be implied that transaction requests immediately (i.e. synchronously) return a stream. This is not technically correct. Due to buffering and batching it is currently asynchronous.

Really? This example shows cypher.transaction() returning a stream right away:

https://github.com/brian-gates/cypher-stream#query-batching

I also would prefer that headers, raw, and commit were bundled into an options param. That way you aren't forced to use null params if you want to commit without headers or raw.

I'm not sure if I'm misunderstanding you, but typically, options in options objects can simply be omitted if they're not needed. So you'd never be forced to pass null params.

E.g. see jQuery.ajax(settings): http://api.jquery.com/jquery.ajax/

I'll clarify this in the doc though. And the current doc is just a rough outline of the API, but the final/proper API docs will definitely specify precisely which options are needed vs. which are optional. =)

Does it have to be the one making the HTTP request though? The API docs seem to imply that the "bring your own stream" feature is only in Node — but do you know if that's actually true in practice?

I've only ever tested it where Oboe is making the request. That works. Not sure about anything else.

Really? This example shows cypher.transaction() returning a stream right away:
https://github.com/brian-gates/cypher-stream#query-batching

The transaction stream is synchronous. Streams per statement are asynchronous, which is what your documentation appears to be referring to.

https://github.com/brian-gates/cypher-stream#stream-per-statement

I'm not sure if I'm misunderstanding you, but typically, options in options objects can simply be omitted if they're not needed. So you'd never be forced to pass null params.

Oh, ignore me, that's just CoffeeScript throwing me for a loop :)

Cool, thanks. I won't worry about Oboe in the browser then. Non-"mainline" scenario aside, there's also nothing fundamentally limiting; it should always be theoretically possible to still stream the JSON parsing even if you're not the one making the HTTP request.

Great point about statement streams. Any reason though that a stream couldn't be returned immediately, and "wired up" under the hood later whenever the underlying CypherStream is emitted?

(This assumes that we'd provide our own wrapper stream rather than the underlying CypherStream directly, but I think that's probably a wise API thing to do anyway. Or maybe we document that we're returning a CypherStream directly, and we just proxy all events, etc.)

Thanks for all the great feedback again!

Any reason though that a stream couldn't be returned immediately, and "wired up" under the hood later whenever the underlying CypherStream is emitted?

The streams API prevents me from returning anything synchronously from my write.

That said, I was planning on adding support for accepting a stream to pipe to as an alternative to callbacks. This would allow your library to generate and return a proxy stream immediately:

var stream = new require('stream').PassThrough(); // or you could use highland.
cypher({ statement: statement, pipe: stream });
return stream;

Nice. An API like that would be great. Thanks Brian.

I'm all with @gasi ! We've been using this in prod for a while too.