From 3188cea926d13d5375cee0568e91949dd551843b Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Tue, 19 Apr 2016 10:04:07 +0200 Subject: [PATCH] doc: add full example for zlib.flush() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a full example using `zlib.flush()` for the common use case of writing partial compressed HTTP output to the client. PR-URL: https://github.com/nodejs/node/pull/6172 Reviewed-By: James M Snell Reviewed-By: Robert Jefe Lindstädt --- doc/api/zlib.markdown | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/api/zlib.markdown b/doc/api/zlib.markdown index da20024ca2109f..dd454ec60f818b 100644 --- a/doc/api/zlib.markdown +++ b/doc/api/zlib.markdown @@ -155,6 +155,36 @@ fewer calls to zlib, since it'll be able to process more data in a single `write` operation. So, this is another factor that affects the speed, at the cost of memory usage. +## Flushing + +Calling [`.flush()`][] on a compression stream will make zlib return as much +output as currently possible. This may come at the cost of degraded compression +quality, but can be useful when data needs to be available as soon as possible. + +In the following example, `flush()` is used to write a compressed partial +HTTP response to the client: +```js +const zlib = require('zlib'); +const http = require('http'); + +http.createServer((request, response) => { + // For the sake of simplicity, the Accept-Encoding checks are omitted. + response.writeHead(200, { 'content-encoding': 'gzip' }); + const output = zlib.createGzip(); + output.pipe(response); + + setInterval(() => { + output.write(`The current time is ${Date()}\n`, () => { + // The data has been passed to zlib, but the compression algorithm may + // have decided to buffer the data for more efficient compression. + // Calling .flush() will make the data available as soon as the client + // is ready to receive it. + output.flush(); + }); + }, 1000); +}).listen(1337); +``` + ## Constants @@ -378,4 +408,5 @@ Decompress a Buffer or string with Unzip. [Inflate]: #zlib_class_zlib_inflate [InflateRaw]: #zlib_class_zlib_inflateraw [Unzip]: #zlib_class_zlib_unzip +[`.flush()`]: #zlib_zlib_flush_kind_callback [Buffer]: buffer.html