Skip to content

Commit 1c7b6e2

Browse files
jasnellevanlucas
jasnell
authored and
evanlucas
committed
doc: improve zlib docs
General improvements to zlib doc copy PR-URL: #6746 Reviewed-By: Anna Henningsen <[email protected]>
1 parent 74582aa commit 1c7b6e2

File tree

1 file changed

+58
-56
lines changed

1 file changed

+58
-56
lines changed

‎doc/api/zlib.md‎

Lines changed: 58 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,15 @@
22

33
Stability: 2 - Stable
44

5-
You can access this module with:
5+
The `zlib` module provides compression functionality implemented using Gzip and
6+
Deflate/Inflate. It can be accessed using:
67

7-
const zlib = require('zlib');
8-
9-
This provides bindings to Gzip/Gunzip, Deflate/Inflate, and
10-
DeflateRaw/InflateRaw classes. Each class takes the same options, and
11-
is a readable/writable Stream.
12-
13-
## Examples
8+
```js
9+
const zlib = require('zlib');
10+
```
1411

15-
Compressing or decompressing a file can be done by piping an
16-
fs.ReadStream into a zlib stream, then into an fs.WriteStream.
12+
Compressing or decompressing a stream (such as a file) can be accomplished by
13+
piping the source stream data through a `zlib` stream into a destination stream:
1714

1815
```js
1916
const gzip = zlib.createGzip();
@@ -24,8 +21,7 @@ const out = fs.createWriteStream('input.txt.gz');
2421
inp.pipe(gzip).pipe(out);
2522
```
2623

27-
Compressing or decompressing data in one step can be done by using
28-
the convenience methods.
24+
It is also possible to compress or decompress data in a single step:
2925

3026
```js
3127
const input = '.................................';
@@ -47,25 +43,33 @@ zlib.unzip(buffer, (err, buffer) => {
4743
});
4844
```
4945

50-
To use this module in an HTTP client or server, use the [accept-encoding][]
51-
on requests, and the [content-encoding][] header on responses.
46+
## Compressing HTTP requests and responses
47+
48+
The `zlib` module can be used to implement support for the `gzip` and `deflate`
49+
content-encoding mechanisms defined by
50+
[HTTP](https://tools.ietf.org/html/rfc7230#section-4.2).
51+
52+
The HTTP [`Accept-Encoding`][] header is used within an http request to identify
53+
the compression encodings accepted by the client. The [`Content-Encoding`][]
54+
header is used to identify the compression encodings actually applied to a
55+
message.
5256

53-
**Note: these examples are drastically simplified to show
54-
the basic concept.** Zlib encoding can be expensive, and the results
57+
**Note: the examples given below are drastically simplified to show
58+
the basic concept.** Using `zlib` encoding can be expensive, and the results
5559
ought to be cached. See [Memory Usage Tuning][] for more information
56-
on the speed/memory/compression tradeoffs involved in zlib usage.
60+
on the speed/memory/compression tradeoffs involved in `zlib` usage.
5761

5862
```js
5963
// client request example
6064
const zlib = require('zlib');
6165
const http = require('http');
6266
const fs = require('fs');
63-
const request = http.get({ host: 'izs.me',
67+
const request = http.get({ host: 'example.com',
6468
path: '/',
6569
port: 80,
66-
headers: { 'accept-encoding': 'gzip,deflate' } });
70+
headers: { 'Accept-Encoding': 'gzip,deflate' } });
6771
request.on('response', (response) => {
68-
var output = fs.createWriteStream('izs.me_index.html');
72+
var output = fs.createWriteStream('example.com_index.html');
6973

7074
switch (response.headers['content-encoding']) {
7175
// or, just use zlib.createUnzip() to handle both cases
@@ -97,10 +101,10 @@ http.createServer((request, response) => {
97101
// Note: this is not a conformant accept-encoding parser.
98102
// See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
99103
if (acceptEncoding.match(/\bdeflate\b/)) {
100-
response.writeHead(200, { 'content-encoding': 'deflate' });
104+
response.writeHead(200, { 'Content-Encoding': 'deflate' });
101105
raw.pipe(zlib.createDeflate()).pipe(response);
102106
} else if (acceptEncoding.match(/\bgzip\b/)) {
103-
response.writeHead(200, { 'content-encoding': 'gzip' });
107+
response.writeHead(200, { 'Content-Encoding': 'gzip' });
104108
raw.pipe(zlib.createGzip()).pipe(response);
105109
} else {
106110
response.writeHead(200, {});
@@ -109,7 +113,7 @@ http.createServer((request, response) => {
109113
}).listen(1337);
110114
```
111115

112-
By default, the zlib methods with throw an error when decompressing
116+
By default, the `zlib` methods with throw an error when decompressing
113117
truncated data. However, if it is known that the data is incomplete, or
114118
the desire is to inspect only the beginning of a compressed file, it is
115119
possible to suppress the default error handling by changing the flushing
@@ -146,43 +150,43 @@ The memory requirements for deflate are (in bytes):
146150
(1 << (windowBits+2)) + (1 << (memLevel+9))
147151
```
148152

149-
that is: 128K for windowBits=15 + 128K for memLevel = 8
153+
That is: 128K for windowBits=15 + 128K for memLevel = 8
150154
(default values) plus a few kilobytes for small objects.
151155

152-
For example, if you want to reduce
153-
the default memory requirements from 256K to 128K, set the options to:
156+
For example, to reduce the default memory requirements from 256K to 128K, the
157+
options shoud be set to:
154158

155159
```
156160
{ windowBits: 14, memLevel: 7 }
157161
```
158162

159-
Of course this will generally degrade compression (there's no free lunch).
163+
This will, however, generally degrade compression.
160164

161165
The memory requirements for inflate are (in bytes)
162166

163167
```
164168
1 << windowBits
165169
```
166170

167-
that is, 32K for windowBits=15 (default value) plus a few kilobytes
171+
That is, 32K for windowBits=15 (default value) plus a few kilobytes
168172
for small objects.
169173

170174
This is in addition to a single internal output slab buffer of size
171175
`chunkSize`, which defaults to 16K.
172176

173-
The speed of zlib compression is affected most dramatically by the
177+
The speed of `zlib` compression is affected most dramatically by the
174178
`level` setting. A higher level will result in better compression, but
175179
will take longer to complete. A lower level will result in less
176180
compression, but will be much faster.
177181

178-
In general, greater memory usage options will mean that node.js has to make
179-
fewer calls to zlib, since it'll be able to process more data in a
180-
single `write` operation. So, this is another factor that affects the
182+
In general, greater memory usage options will mean that Node.js has to make
183+
fewer calls to `zlib` because it will be able to process more data on
184+
each `write` operation. So, this is another factor that affects the
181185
speed, at the cost of memory usage.
182186

183187
## Flushing
184188

185-
Calling [`.flush()`][] on a compression stream will make zlib return as much
189+
Calling [`.flush()`][] on a compression stream will make `zlib` return as much
186190
output as currently possible. This may come at the cost of degraded compression
187191
quality, but can be useful when data needs to be available as soon as possible.
188192

@@ -214,13 +218,11 @@ http.createServer((request, response) => {
214218

215219
<!--type=misc-->
216220

217-
All of the constants defined in zlib.h are also defined on
218-
`require('zlib')`.
219-
In the normal course of operations, you will not need to ever set any of
220-
these. They are documented here so that their presence is not
221-
surprising. This section is taken almost directly from the
222-
[zlib documentation][]. See <http://zlib.net/manual.html#Constants> for more
223-
details.
221+
All of the constants defined in `zlib.h` are also defined on `require('zlib')`.
222+
In the normal course of operations, it will not be necessary to use these
223+
constants. They are documented so that their presence is not surprising. This
224+
section is taken almost directly from the [zlib documentation][]. See
225+
<http://zlib.net/manual.html#Constants> for more details.
224226

225227
Allowed flush values.
226228

@@ -280,19 +282,19 @@ For initializing zalloc, zfree, opaque.
280282

281283
<!--type=misc-->
282284

283-
Each class takes an options object. All options are optional.
285+
Each class takes an `options` object. All options are optional.
284286

285287
Note that some options are only relevant when compressing, and are
286288
ignored by the decompression classes.
287289

288-
* flush (default: `zlib.Z_NO_FLUSH`)
289-
* finishFlush (default: `zlib.Z_FINISH`)
290-
* chunkSize (default: 16*1024)
291-
* windowBits
292-
* level (compression only)
293-
* memLevel (compression only)
294-
* strategy (compression only)
295-
* dictionary (deflate/inflate only, empty dictionary by default)
290+
* `flush` (default: `zlib.Z_NO_FLUSH`)
291+
* `finishFlush` (default: `zlib.Z_FINISH`)
292+
* `chunkSize` (default: 16*1024)
293+
* `windowBits`
294+
* `level` (compression only)
295+
* `memLevel` (compression only)
296+
* `strategy` (compression only)
297+
* `dictionary` (deflate/inflate only, empty dictionary by default)
296298

297299
See the description of `deflateInit2` and `inflateInit2` at
298300
<http://zlib.net/manual.html#Advanced> for more information on these.
@@ -303,7 +305,7 @@ Compress data using deflate.
303305

304306
## Class: zlib.DeflateRaw
305307

306-
Compress data using deflate, and do not append a zlib header.
308+
Compress data using deflate, and do not append a `zlib` header.
307309

308310
## Class: zlib.Gunzip
309311

@@ -338,7 +340,7 @@ class of the compressor/decompressor classes.
338340
Flush pending data. Don't call this frivolously, premature flushes negatively
339341
impact the effectiveness of the compression algorithm.
340342

341-
Calling this only flushes data from the internal zlib state, and does not
343+
Calling this only flushes data from the internal `zlib` state, and does not
342344
perform flushing of any kind on the streams level. Rather, it behaves like a
343345
normal call to `.write()`, i.e. it will be queued up behind other pending
344346
writes and will only produce output when data is being read from the stream.
@@ -385,9 +387,9 @@ Returns a new [Unzip][] object with an [options][].
385387

386388
<!--type=misc-->
387389

388-
All of these take a [Buffer][] or string as the first argument, an optional second
389-
argument to supply options to the zlib classes and will call the supplied
390-
callback with `callback(error, result)`.
390+
All of these take a [Buffer][] or string as the first argument, an optional
391+
second argument to supply options to the `zlib` classes and will call the
392+
supplied callback with `callback(error, result)`.
391393

392394
Every method has a `*Sync` counterpart, which accept the same arguments, but
393395
without a callback.
@@ -427,8 +429,8 @@ Decompress a Buffer or string with InflateRaw.
427429

428430
Decompress a Buffer or string with Unzip.
429431

430-
[accept-encoding]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
431-
[content-encoding]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11
432+
[`Accept-Encoding`]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
433+
[`Content-Encoding`]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11
432434
[Memory Usage Tuning]: #zlib_memory_usage_tuning
433435
[zlib documentation]: http://zlib.net/manual.html#Constants
434436
[options]: #zlib_class_options

0 commit comments

Comments
 (0)