_stream_transform.js 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201
  1. // Copyright Joyent, Inc. and other Node contributors.
  2. //
  3. // Permission is hereby granted, free of charge, to any person obtaining a
  4. // copy of this software and associated documentation files (the
  5. // "Software"), to deal in the Software without restriction, including
  6. // without limitation the rights to use, copy, modify, merge, publish,
  7. // distribute, sublicense, and/or sell copies of the Software, and to permit
  8. // persons to whom the Software is furnished to do so, subject to the
  9. // following conditions:
  10. //
  11. // The above copyright notice and this permission notice shall be included
  12. // in all copies or substantial portions of the Software.
  13. //
  14. // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  15. // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16. // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
  17. // NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
  18. // DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  19. // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
  20. // USE OR OTHER DEALINGS IN THE SOFTWARE.
  21. // a transform stream is a readable/writable stream where you do
  22. // something with the data. Sometimes it's called a "filter",
  23. // but that's not a great name for it, since that implies a thing where
  24. // some bits pass through, and others are simply ignored. (That would
  25. // be a valid example of a transform, of course.)
  26. //
  27. // While the output is causally related to the input, it's not a
  28. // necessarily symmetric or synchronous transformation. For example,
  29. // a zlib stream might take multiple plain-text writes(), and then
  30. // emit a single compressed chunk some time in the future.
  31. //
  32. // Here's how this works:
  33. //
  34. // The Transform stream has all the aspects of the readable and writable
  35. // stream classes. When you write(chunk), that calls _write(chunk,cb)
  36. // internally, and returns false if there's a lot of pending writes
  37. // buffered up. When you call read(), that calls _read(n) until
  38. // there's enough pending readable data buffered up.
  39. //
  40. // In a transform stream, the written data is placed in a buffer. When
  41. // _read(n) is called, it transforms the queued up data, calling the
  42. // buffered _write cb's as it consumes chunks. If consuming a single
  43. // written chunk would result in multiple output chunks, then the first
  44. // outputted bit calls the readcb, and subsequent chunks just go into
  45. // the read buffer, and will cause it to emit 'readable' if necessary.
  46. //
  47. // This way, back-pressure is actually determined by the reading side,
  48. // since _read has to be called to start processing a new chunk. However,
  49. // a pathological inflate type of transform can cause excessive buffering
  50. // here. For example, imagine a stream where every byte of input is
  51. // interpreted as an integer from 0-255, and then results in that many
  52. // bytes of output. Writing the 4 bytes {ff,ff,ff,ff} would result in
  53. // 1kb of data being output. In this case, you could write a very small
  54. // amount of input, and end up with a very large amount of output. In
  55. // such a pathological inflating mechanism, there'd be no way to tell
  56. // the system to stop doing the transform. A single 4MB write could
  57. // cause the system to run out of memory.
  58. //
  59. // However, even in such a pathological case, only a single written chunk
  60. // would be consumed, and then the rest would wait (un-transformed) until
  61. // the results of the previous transformed chunk were consumed.
  62. 'use strict';
  63. module.exports = Transform;
  64. var _require$codes = require('../errors').codes,
  65. ERR_METHOD_NOT_IMPLEMENTED = _require$codes.ERR_METHOD_NOT_IMPLEMENTED,
  66. ERR_MULTIPLE_CALLBACK = _require$codes.ERR_MULTIPLE_CALLBACK,
  67. ERR_TRANSFORM_ALREADY_TRANSFORMING = _require$codes.ERR_TRANSFORM_ALREADY_TRANSFORMING,
  68. ERR_TRANSFORM_WITH_LENGTH_0 = _require$codes.ERR_TRANSFORM_WITH_LENGTH_0;
  69. var Duplex = require('./_stream_duplex');
  70. require('inherits')(Transform, Duplex);
  71. function afterTransform(er, data) {
  72. var ts = this._transformState;
  73. ts.transforming = false;
  74. var cb = ts.writecb;
  75. if (cb === null) {
  76. return this.emit('error', new ERR_MULTIPLE_CALLBACK());
  77. }
  78. ts.writechunk = null;
  79. ts.writecb = null;
  80. if (data != null) // single equals check for both `null` and `undefined`
  81. this.push(data);
  82. cb(er);
  83. var rs = this._readableState;
  84. rs.reading = false;
  85. if (rs.needReadable || rs.length < rs.highWaterMark) {
  86. this._read(rs.highWaterMark);
  87. }
  88. }
  89. function Transform(options) {
  90. if (!(this instanceof Transform)) return new Transform(options);
  91. Duplex.call(this, options);
  92. this._transformState = {
  93. afterTransform: afterTransform.bind(this),
  94. needTransform: false,
  95. transforming: false,
  96. writecb: null,
  97. writechunk: null,
  98. writeencoding: null
  99. }; // start out asking for a readable event once data is transformed.
  100. this._readableState.needReadable = true; // we have implemented the _read method, and done the other things
  101. // that Readable wants before the first _read call, so unset the
  102. // sync guard flag.
  103. this._readableState.sync = false;
  104. if (options) {
  105. if (typeof options.transform === 'function') this._transform = options.transform;
  106. if (typeof options.flush === 'function') this._flush = options.flush;
  107. } // When the writable side finishes, then flush out anything remaining.
  108. this.on('prefinish', prefinish);
  109. }
  110. function prefinish() {
  111. var _this = this;
  112. if (typeof this._flush === 'function' && !this._readableState.destroyed) {
  113. this._flush(function (er, data) {
  114. done(_this, er, data);
  115. });
  116. } else {
  117. done(this, null, null);
  118. }
  119. }
  120. Transform.prototype.push = function (chunk, encoding) {
  121. this._transformState.needTransform = false;
  122. return Duplex.prototype.push.call(this, chunk, encoding);
  123. }; // This is the part where you do stuff!
  124. // override this function in implementation classes.
  125. // 'chunk' is an input chunk.
  126. //
  127. // Call `push(newChunk)` to pass along transformed output
  128. // to the readable side. You may call 'push' zero or more times.
  129. //
  130. // Call `cb(err)` when you are done with this chunk. If you pass
  131. // an error, then that'll put the hurt on the whole operation. If you
  132. // never call cb(), then you'll never get another chunk.
  133. Transform.prototype._transform = function (chunk, encoding, cb) {
  134. cb(new ERR_METHOD_NOT_IMPLEMENTED('_transform()'));
  135. };
  136. Transform.prototype._write = function (chunk, encoding, cb) {
  137. var ts = this._transformState;
  138. ts.writecb = cb;
  139. ts.writechunk = chunk;
  140. ts.writeencoding = encoding;
  141. if (!ts.transforming) {
  142. var rs = this._readableState;
  143. if (ts.needTransform || rs.needReadable || rs.length < rs.highWaterMark) this._read(rs.highWaterMark);
  144. }
  145. }; // Doesn't matter what the args are here.
  146. // _transform does all the work.
  147. // That we got here means that the readable side wants more data.
  148. Transform.prototype._read = function (n) {
  149. var ts = this._transformState;
  150. if (ts.writechunk !== null && !ts.transforming) {
  151. ts.transforming = true;
  152. this._transform(ts.writechunk, ts.writeencoding, ts.afterTransform);
  153. } else {
  154. // mark that we need a transform, so that any data that comes in
  155. // will get processed, now that we've asked for it.
  156. ts.needTransform = true;
  157. }
  158. };
  159. Transform.prototype._destroy = function (err, cb) {
  160. Duplex.prototype._destroy.call(this, err, function (err2) {
  161. cb(err2);
  162. });
  163. };
  164. function done(stream, er, data) {
  165. if (er) return stream.emit('error', er);
  166. if (data != null) // single equals check for both `null` and `undefined`
  167. stream.push(data); // TODO(BridgeAR): Write a test for these two error cases
  168. // if there's nothing in the write buffer, then that means
  169. // that nothing more will ever be provided
  170. if (stream._writableState.length) throw new ERR_TRANSFORM_WITH_LENGTH_0();
  171. if (stream._transformState.transforming) throw new ERR_TRANSFORM_ALREADY_TRANSFORMING();
  172. return stream.push(null);
  173. }