devongovett/pdfkit — pull request #212 by devongovett (2014-03-24 02:34:30+00:00)
Title: API Change Announcement: Streams instead of write/output methods

This change has been a long time coming, so I thought I'd make a pull request with the changes so I have a place to document this change. It's the first breaking API change I've had to make for this project.

**TL;DR**: The `write` and `output` methods are deprecated in 0.5, and are replaced with Node [stream](http://nodejs.org/api/stream.html) support. Here's how to use it:

```javascript
var PDFDocument = require('pdfkit');
var fs = require('fs');

var doc = new PDFDocument();
doc.pipe(fs.createWriteStream('output.pdf')); // or pipe to HTTP response or whatever here

// put stuff in the pdf here as before...

doc.end(); // finalize the document and end the stream
```

**Longer version**: `PDFDocument` instances are now Node readable streams that you just pipe to whatever destination you want, for example a file or HTTP response. This has the benefit that for large documents, the entire PDF file is not buffered in memory until it is written. It is now buffered on a page by page basis, and written to the output stream as each page is finalized. Assets like images are embedded immediately and not held in memory. Zip compression now happens as data is being written, not when the document is finalized. Also, no more binary strings (yes, this is a pretty old project, buffers weren't around when I started it)!

Currently, the old `write` and `output` methods log warning messages about deprecation. `write` has a backward compatibility shim for now, which will be removed in a future version. `output` is already removed as it would have been too difficult to shim.

If you have questions, please leave a comment here, and I will answer them as best I can.