1 // a transform stream is a readable/writable stream where you do
2 // something with the data. Sometimes it's called a "filter",
3 // but that's not a great name for it, since that implies a thing where
4 // some bits pass through, and others are simply ignored. (That would
5 // be a valid example of a transform, of course.)
7 // While the output is causally related to the input, it's not a
8 // necessarily symmetric or synchronous transformation. For example,
9 // a zlib stream might take multiple plain-text writes(), and then
10 // emit a single compressed chunk some time in the future.
12 // Here's how this works:
14 // The Transform stream has all the aspects of the readable and writable
15 // stream classes. When you write(chunk), that calls _write(chunk,cb)
16 // internally, and returns false if there's a lot of pending writes
17 // buffered up. When you call read(), that calls _read(n) until
18 // there's enough pending readable data buffered up.
20 // In a transform stream, the written data is placed in a buffer. When
21 // _read(n) is called, it transforms the queued up data, calling the
22 // buffered _write cb's as it consumes chunks. If consuming a single
23 // written chunk would result in multiple output chunks, then the first
24 // outputted bit calls the readcb, and subsequent chunks just go into
25 // the read buffer, and will cause it to emit 'readable' if necessary.
27 // This way, back-pressure is actually determined by the reading side,
28 // since _read has to be called to start processing a new chunk. However,
29 // a pathological inflate type of transform can cause excessive buffering
30 // here. For example, imagine a stream where every byte of input is
31 // interpreted as an integer from 0-255, and then results in that many
32 // bytes of output. Writing the 4 bytes {ff,ff,ff,ff} would result in
33 // 1kb of data being output. In this case, you could write a very small
34 // amount of input, and end up with a very large amount of output. In
35 // such a pathological inflating mechanism, there'd be no way to tell
36 // the system to stop doing the transform. A single 4MB write could
37 // cause the system to run out of memory.
39 // However, even in such a pathological case, only a single written chunk
40 // would be consumed, and then the rest would wait (un-transformed) until
41 // the results of the previous transformed chunk were consumed.
45 module.exports = Transform;
47 var Duplex = require('./_stream_duplex');
50 var util = require('core-util-is');
51 util.inherits = require('inherits');
54 util.inherits(Transform, Duplex);
57 function TransformState(stream) {
58 this.afterTransform = function(er, data) {
59 return afterTransform(stream, er, data);
62 this.needTransform = false;
63 this.transforming = false;
65 this.writechunk = null;
68 function afterTransform(stream, er, data) {
69 var ts = stream._transformState;
70 ts.transforming = false;
75 return stream.emit('error', new Error('no writecb in Transform class'));
80 if (data !== null && data !== undefined)
86 var rs = stream._readableState;
88 if (rs.needReadable || rs.length < rs.highWaterMark) {
89 stream._read(rs.highWaterMark);
94 function Transform(options) {
95 if (!(this instanceof Transform))
96 return new Transform(options);
98 Duplex.call(this, options);
100 this._transformState = new TransformState(this);
102 // when the writable side finishes, then flush out anything remaining.
105 // start out asking for a readable event once data is transformed.
106 this._readableState.needReadable = true;
108 // we have implemented the _read method, and done the other things
109 // that Readable wants before the first _read call, so unset the
111 this._readableState.sync = false;
114 if (typeof options.transform === 'function')
115 this._transform = options.transform;
117 if (typeof options.flush === 'function')
118 this._flush = options.flush;
121 this.once('prefinish', function() {
122 if (typeof this._flush === 'function')
123 this._flush(function(er) {
131 Transform.prototype.push = function(chunk, encoding) {
132 this._transformState.needTransform = false;
133 return Duplex.prototype.push.call(this, chunk, encoding);
136 // This is the part where you do stuff!
137 // override this function in implementation classes.
138 // 'chunk' is an input chunk.
140 // Call `push(newChunk)` to pass along transformed output
141 // to the readable side. You may call 'push' zero or more times.
143 // Call `cb(err)` when you are done with this chunk. If you pass
144 // an error, then that'll put the hurt on the whole operation. If you
145 // never call cb(), then you'll never get another chunk.
146 Transform.prototype._transform = function(chunk, encoding, cb) {
147 throw new Error('not implemented');
150 Transform.prototype._write = function(chunk, encoding, cb) {
151 var ts = this._transformState;
153 ts.writechunk = chunk;
154 ts.writeencoding = encoding;
155 if (!ts.transforming) {
156 var rs = this._readableState;
157 if (ts.needTransform ||
159 rs.length < rs.highWaterMark)
160 this._read(rs.highWaterMark);
164 // Doesn't matter what the args are here.
165 // _transform does all the work.
166 // That we got here means that the readable side wants more data.
167 Transform.prototype._read = function(n) {
168 var ts = this._transformState;
170 if (ts.writechunk !== null && ts.writecb && !ts.transforming) {
171 ts.transforming = true;
172 this._transform(ts.writechunk, ts.writeencoding, ts.afterTransform);
174 // mark that we need a transform, so that any data that comes in
175 // will get processed, now that we've asked for it.
176 ts.needTransform = true;
181 function done(stream, er) {
183 return stream.emit('error', er);
185 // if there's nothing in the write buffer, then that means
186 // that nothing more will ever be provided
187 var ws = stream._writableState;
188 var ts = stream._transformState;
191 throw new Error('calling transform done when ws.length != 0');
194 throw new Error('calling transform done when still transforming');
196 return stream.push(null);