zlib documentation & wish for zlib.*Sync calls

[axkibe]

a) The links at:
Returns a new Gzip object with an options.to

http://nodejs.org/docs/latest/api/zlib.html#zlib.Gzip

do not resolve, because it is

http://nodejs.org/docs/latest/api/zlib.html#zlib_class_zlib_gzip

b) The documentation of the Gzip project is practically non existent.
Class: zlib.Gzip# Compress data using gzip. <-- what methods does it have? what steams, events, etc?

c) Wishing for a zlib.gzipSync since I want to zip and cache one big client side javascript file at startup and not clutter startup sequence with additional callbacks.

[bnoordhuis]

The links have been fixed in 540a441.

If you feel that the documentation is lacking, please submit a pull request. Ping me on IRC if you want pointers.

As to adding synchronous functions, making the API fully asynchronous was a conscious decision. Compression/decompression is computationally expensive. Doing it synchronously has the potential to stall the event loop for prolonged periods of time.

There is a legitimate use case for doing one-time compression/decompression at start-up but the potential for misuse is too great, hence it won't be added.

[isaacs]

making the API fully asynchronous was a conscious decision.

Well, it was as much a matter of priorities and time as anything else. We'd accept a patch for zlib.*Sync helper methods, if it was done cleanly and there was a lot of people asking for it. It's not significantly more hazardous than synchronous fs functions.

Class: zlib.Gzip# Compress data using gzip. <-- what methods does it have? what steams, events, etc?

The zlib classes are all filter streams. That's explained at the top of the page. Doc patches are always welcome.

[bnoordhuis]

We'd accept a patch for zlib.*Sync helper methods, if it was done cleanly and there was a lot of people asking for it. It's not significantly more hazardous than synchronous fs functions.

I don't want that. There are already enough people who think that that the fs.*Sync() methods are instantaneous enough that it doesn't hurt to slip one in.

[isaacs]

@bnoordhuis It's good that we'll have some opposing voices, then :) In practice, this isn't asked for very often, and would be tricky to do in a clean way that doesn't muddy up the streaming logic, so my guess is that it'll never actually happen.