_stream_transform.js 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214
  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 Duplex = require('./_stream_duplex');
  65. /*<replacement>*/
  66. var util = Object.create(require('core-util-is'));
  67. util.inherits = require('inherits');
  68. /*</replacement>*/
  69. util.inherits(Transform, Duplex);
  70. function afterTransform(er, data) {
  71. var ts = this._transformState;
  72. ts.transforming = false;
  73. var cb = ts.writecb;
  74. if (!cb) {
  75. return this.emit('error', new Error('write callback called multiple times'));
  76. }
  77. ts.writechunk = null;
  78. ts.writecb = null;
  79. if (data != null) // single equals check for both `null` and `undefined`
  80. this.push(data);
  81. cb(er);
  82. var rs = this._readableState;
  83. rs.reading = false;
  84. if (rs.needReadable || rs.length < rs.highWaterMark) {
  85. this._read(rs.highWaterMark);
  86. }
  87. }
  88. function Transform(options) {
  89. if (!(this instanceof Transform)) return new Transform(options);
  90. Duplex.call(this, options);
  91. this._transformState = {
  92. afterTransform: afterTransform.bind(this),
  93. needTransform: false,
  94. transforming: false,
  95. writecb: null,
  96. writechunk: null,
  97. writeencoding: null
  98. };
  99. // start out asking for a readable event once data is transformed.
  100. this._readableState.needReadable = true;
  101. // we have implemented the _read method, and done the other things
  102. // that Readable wants before the first _read call, so unset the
  103. // sync guard flag.
  104. this._readableState.sync = false;
  105. if (options) {
  106. if (typeof options.transform === 'function') this._transform = options.transform;
  107. if (typeof options.flush === 'function') this._flush = options.flush;
  108. }
  109. // When the writable side finishes, then flush out anything remaining.
  110. this.on('prefinish', prefinish);
  111. }
  112. function prefinish() {
  113. var _this = this;
  114. if (typeof this._flush === 'function') {
  115. this._flush(function (er, data) {
  116. done(_this, er, data);
  117. });
  118. } else {
  119. done(this, null, null);
  120. }
  121. }
  122. Transform.prototype.push = function (chunk, encoding) {
  123. this._transformState.needTransform = false;
  124. return Duplex.prototype.push.call(this, chunk, encoding);
  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('_transform() is not implemented');
  138. };
  139. Transform.prototype._write = function (chunk, encoding, cb) {
  140. var ts = this._transformState;
  141. ts.writecb = cb;
  142. ts.writechunk = chunk;
  143. ts.writeencoding = encoding;
  144. if (!ts.transforming) {
  145. var rs = this._readableState;
  146. if (ts.needTransform || rs.needReadable || rs.length < rs.highWaterMark) this._read(rs.highWaterMark);
  147. }
  148. };
  149. // Doesn't matter what the args are here.
  150. // _transform does all the work.
  151. // That we got here means that the readable side wants more data.
  152. Transform.prototype._read = function (n) {
  153. var ts = this._transformState;
  154. if (ts.writechunk !== null && ts.writecb && !ts.transforming) {
  155. ts.transforming = true;
  156. this._transform(ts.writechunk, ts.writeencoding, ts.afterTransform);
  157. } else {
  158. // mark that we need a transform, so that any data that comes in
  159. // will get processed, now that we've asked for it.
  160. ts.needTransform = true;
  161. }
  162. };
  163. Transform.prototype._destroy = function (err, cb) {
  164. var _this2 = this;
  165. Duplex.prototype._destroy.call(this, err, function (err2) {
  166. cb(err2);
  167. _this2.emit('close');
  168. });
  169. };
  170. function done(stream, er, data) {
  171. if (er) return stream.emit('error', er);
  172. if (data != null) // single equals check for both `null` and `undefined`
  173. stream.push(data);
  174. // if there's nothing in the write buffer, then that means
  175. // that nothing more will ever be provided
  176. if (stream._writableState.length) throw new Error('Calling transform done when ws.length != 0');
  177. if (stream._transformState.transforming) throw new Error('Calling transform done when still transforming');
  178. return stream.push(null);
  179. }