deps/npm/node_modules/sha/node_modules/readable-stream/lib/_stream_transform.js

   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.)
   6 //
   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.
  11 //
  12 // Here's how this works:
  13 //
  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.
  19 //
  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.
  26 //
  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.
  38 //
  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.
  42
  43 module.exports = Transform;
  44
  45 var Duplex = require('./_stream_duplex');
  46
  47 /*<replacement>*/
  48 var util = require('core-util-is');
  49 util.inherits = require('inherits');
  50 /*</replacement>*/
  51
  52 util.inherits(Transform, Duplex);
  53
  54
  55 function TransformState(options, stream) {
  56   this.afterTransform = function(er, data) {
  57     return afterTransform(stream, er, data);
  58   };
  59
  60   this.needTransform = false;
  61   this.transforming = false;
  62   this.writecb = null;
  63   this.writechunk = null;
  64 }
  65
  66 function afterTransform(stream, er, data) {
  67   var ts = stream._transformState;
  68   ts.transforming = false;
  69
  70   var cb = ts.writecb;
  71
  72   if (!cb)
  73     return stream.emit('error', new Error('no writecb in Transform class'));
  74
  75   ts.writechunk = null;
  76   ts.writecb = null;
  77
  78   if (!util.isNullOrUndefined(data))
  79     stream.push(data);
  80
  81   if (cb)
  82     cb(er);
  83
  84   var rs = stream._readableState;
  85   rs.reading = false;
  86   if (rs.needReadable || rs.length < rs.highWaterMark) {
  87     stream._read(rs.highWaterMark);
  88   }
  89 }
  90
  91
  92 function Transform(options) {
  93   if (!(this instanceof Transform))
  94     return new Transform(options);
  95
  96   Duplex.call(this, options);
  97
  98   this._transformState = new TransformState(options, this);
  99
 100   // when the writable side finishes, then flush out anything remaining.
 101   var stream = this;
 102
 103   // start out asking for a readable event once data is transformed.
 104   this._readableState.needReadable = true;
 105
 106   // we have implemented the _read method, and done the other things
 107   // that Readable wants before the first _read call, so unset the
 108   // sync guard flag.
 109   this._readableState.sync = false;
 110
 111   this.once('prefinish', function() {
 112     if (util.isFunction(this._flush))
 113       this._flush(function(er) {
 114         done(stream, er);
 115       });
 116     else
 117       done(stream);
 118   });
 119 }
 120
 121 Transform.prototype.push = function(chunk, encoding) {
 122   this._transformState.needTransform = false;
 123   return Duplex.prototype.push.call(this, chunk, encoding);
 124 };
 125
 126 // This is the part where you do stuff!
 127 // override this function in implementation classes.
 128 // 'chunk' is an input chunk.
 129 //
 130 // Call `push(newChunk)` to pass along transformed output
 131 // to the readable side.  You may call 'push' zero or more times.
 132 //
 133 // Call `cb(err)` when you are done with this chunk.  If you pass
 134 // an error, then that'll put the hurt on the whole operation.  If you
 135 // never call cb(), then you'll never get another chunk.
 136 Transform.prototype._transform = function(chunk, encoding, cb) {
 137   throw new Error('not implemented');
 138 };
 139
 140 Transform.prototype._write = function(chunk, encoding, cb) {
 141   var ts = this._transformState;
 142   ts.writecb = cb;
 143   ts.writechunk = chunk;
 144   ts.writeencoding = encoding;
 145   if (!ts.transforming) {
 146     var rs = this._readableState;
 147     if (ts.needTransform ||
 148         rs.needReadable ||
 149         rs.length < rs.highWaterMark)
 150       this._read(rs.highWaterMark);
 151   }
 152 };
 153
 154 // Doesn't matter what the args are here.
 155 // _transform does all the work.
 156 // That we got here means that the readable side wants more data.
 157 Transform.prototype._read = function(n) {
 158   var ts = this._transformState;
 159
 160   if (!util.isNull(ts.writechunk) && ts.writecb && !ts.transforming) {
 161     ts.transforming = true;
 162     this._transform(ts.writechunk, ts.writeencoding, ts.afterTransform);
 163   } else {
 164     // mark that we need a transform, so that any data that comes in
 165     // will get processed, now that we've asked for it.
 166     ts.needTransform = true;
 167   }
 168 };
 169
 170
 171 function done(stream, er) {
 172   if (er)
 173     return stream.emit('error', er);
 174
 175   // if there's nothing in the write buffer, then that means
 176   // that nothing more will ever be provided
 177   var ws = stream._writableState;
 178   var ts = stream._transformState;
 179
 180   if (ws.length)
 181     throw new Error('calling transform done when ws.length != 0');
 182
 183   if (ts.transforming)
 184     throw new Error('calling transform done when still transforming');
 185
 186   return stream.push(null);
 187 }