/ We need to use SymbolFor to make these globally available // for interopt with readable-stream, i.e. readable-stream // and node core needs to be able to read/write private state // from each other for proper interoperability. const kIsDestroyed = SymbolFor('nodejs.stream.destroyed'); const kIsErrored = SymbolFor('nodejs.stream.errored'); const kIsReadable = SymbolFor('nodejs.stream.readable'); const kIsWritable = SymbolFor('nodejs.stream.writable'); const kIsDisturbed = SymbolFor('nodejs.stream.disturbed'); const kIsClosedPromise = SymbolFor('nodejs.webstream.isClosedPromise'); const kControllerErrorFunction = SymbolFor('nodejs.webstream.controllerErrorFunction'); function isReadableNodeStream(obj, strict = false) { return !!( obj && typeof obj.pipe === 'function' && typeof obj.on === 'function' && ( !strict || (typeof obj.pause === 'function' && typeof obj.resume === 'function') ) && (!obj._writableState || obj._readableState?.readable !== false) && // Duplex (!obj._writableState || obj._readableState) // Writable has .pipe. ); } function isWritableNodeStream(obj) { return !!( obj && typeof obj.write === 'function' && typeof obj.on === 'function' && (!obj._readableState || obj._writableState?.writable !== false) // Duplex ); } function isDuplexNodeStream(obj) { return !!( obj && (typeof obj.pipe === 'function' && obj._readableState) && typeof obj.on === 'function' && typeof obj.write === 'function' ); } function isNodeStream(obj) { return ( obj && ( obj._readableState || obj._writableState || (typeof obj.write === 'function' && typeof obj.on === 'function') || (typeof obj.pipe === 'function' && typeof obj.on === 'function') ) ); } function isReadableStream(obj) { return !!( obj && !isNodeStream(obj) && typeof obj.pipeThrough === 'function' && typeof obj.getReader === 'function' && typeof obj.cancel === 'function' ); } function isWritableStream(obj) { return !!( obj && !isNodeStream(obj) && typeof obj.getWriter === 'function' && typeof obj.abort === 'function' ); } function isTransformStream(obj) { return !!( obj && !isNodeStream(obj) && typeof obj.readable === 'object' && typeof obj.writable === 'object' ); } function isWebStream(obj) { return isReadableStream(obj) || isWritableStream(obj) || isTransformStream(obj); } function isIterable(obj, isAsync) { if (obj == null) return false; if (isAsync === true) return typeof obj[SymbolAsyncIterator] === 'function'; if (isAsync === false) return typeof obj[SymbolIterator] === 'function'; return typeof obj[SymbolAsyncIterator] === 'function' || typeof obj[SymbolIterator] === 'function'; } function isDestroyed(stream) { if (!isNodeStream(stream)) return null; const wState = stream._writableState; const rState = stream._readableState; const state = wState || rState; return !!(stream.destroyed || stream[kIsDestroyed] || state?.destroyed); } // Have been end():d. function isWritableEnded(stream) { if (!isWritableNodeStream(stream)) return null; if (stream.writableEnded === true) return true; const wState = stream._writableState; if (wState?.errored) return false; if (typeof wState?.ended !== 'boolean') return null; return wState.ended; } // Have emitted 'finish'. function isWritableFinished(stream, strict) { if (!isWritableNodeStream(stream)) return null; if (stream.writableFinished === true) return true; const wState = stream._writableState; if (wState?.errored) return false; if (typeof wState?.finished !== 'boolean') return null; return !!( wState.finished || (strict === false && wState.ended === true && wState.length === 0) ); } // Have been push(null):d. function isReadableEnded(stream) { if (!isReadableNodeStream(stream)) return null; if (stream.readableEnded === true) return true; const rState = stream._readableState; if (!rState || rState.errored) return false; if (typeof rState?.ended !== 'boolean') return null; return rState.ended; } // Have emitted 'end'. function isReadableFinished(stream, strict) { if (!isReadableNodeStream(stream)) return null; const rState = stream._readableState; if (rState?.errored) return false; if (typeof rState?.endEmitted !== 'boolean') return null; return !!( rState.endEmitted || (strict === false && rState.ended === true && rState.length === 0) ); } function isReadable(stream) { if (stream && stream[kIsReadable] != null) return stream[kIsReadable]; if (typeof stream?.readable !== 'boolean') return null; if (isDestroyed(stream)) return false; return isReadableNodeStream(stream) && stream.readable && !isReadableFinished(stream); } function isWritable(stream) { if (stream && stream[kIsWritable] != null) return stream[kIsWritable]; if (typeof stream?.writable !== 'boolean') return null; if (isDestroyed(stream)) return false; return isWritableNodeStream(stream) && stream.writable && !isWritableEnded(stream); } function isFinished(stream, opts) { if (!isNodeStream(stream)) { return null; } if (isDestroyed(stream)) { return true; } if (opts?.readable !== false && isReadable(stream)) { return false; } if (opts?.writable !== false && isWritable(stream)) { return false; } return true; } function isWritableErrored(stream) { if (!isNodeStream(stream)) { return null; } if (stream.writableErrored) { return stream.writableErrored; } return stream._writableState?.errored ?? null; } function isReadableErrored(stream) { if (!isNodeStream(stream)) { return null; } if (stream.readableErrored) { return stream.readableErrored; } return stream._readableState?.errored ?? null; } function isClosed(stream) { if (!isNodeStream(stream)) { return null; } if (typeof stream.closed === 'boolean') { return stream.closed; } const wState = stream._writableState; const rState = stream._readableState; if ( typeof wState?.closed === 'boolean' || typeof rState?.closed === 'boolean' ) { return wState?.closed || rState?.closed; } if (typeof stream._closed === 'boolean' && isOutgoingMessage(stream)) { return stream._closed; } return null; } function isOutgoingMessage(stream) { return ( typeof stream._closed === 'boolean' && typeof stream._defaultKeepAlive === 'boolean' && typeof stream._removedConnection === 'boolean' && typeof stream._removedContLen === 'boolean' ); } function isServerResponse(stream) { return ( typeof stream._sent100 === 'boolean' && isOutgoingMessage(stream) ); } function isServerRequest(stream) { return ( typeof stream._consuming === 'boolean' && typeof stream._dumped === 'boolean' && stream.req?.upgradeOrConnect === undefined ); } function willEmitClose(stream) { if (!isNodeStream(stream)) return null; const wState = stream._writableState; const rState = stream._readableState; const state = wState || rState; return (!state && isServerResponse(stream)) || !!( state && state.autoDestroy && state.emitClose && state.closed === false ); } function isDisturbed(stream) { return !!(stream && ( stream[kIsDisturbed] ?? (stream.readableDidRead || stream.readableAborted) )); } function isErrored(stream) { return !!(stream && ( stream[kIsErrored] ?? stream.readableErrored ?? stream.writableErrored ?? stream._readableState?.errorEmitted ?? stream._writableState?.errorEmitted ?? stream._readableState?.errored ?? stream._writableState?.errored )); } module.exports = { isDestroyed, kIsDestroyed, isDisturbed, kIsDisturbed, isErrored, kIsErrored, isReadable, kIsReadable, kIsClosedPromise, kControllerErrorFunction, kIsWritable, isClosed, isDuplexNodeStream, isFinished, isIterable, isReadableNodeStream, isReadableStream, isReadableEnded, isReadableFinished, isReadableErrored, isNodeStream, isWebStream, isWritable, isWritableNodeStream, isWritableStream, isWritableEnded, isWritableFinished, isWritableErrored, isServerRequest, isServerResponse, willEmitClose, isTransformStream, }; // Copyright Joyent, Inc. and other Node contributors. // // Permission is hereby granted, free of charge, to any person obtaining a // copy of this software and associated documentation files (the // "Software"), to deal in the Software without restriction, including // without limitation the rights to use, copy, modify, merge, publish, // distribute, sublicense, and/or sell copies of the Software, and to permit // persons to whom the Software is furnished to do so, subject to the // following conditions: // // The above copyright notice and this permission notice shall be included // in all copies or substantial portions of the Software. // // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN // NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, // DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE // USE OR OTHER DEALINGS IN THE SOFTWARE. // a transform stream is a readable/writable stream where you do // something with the data. Sometimes it's called a "filter", // but that's not a great name for it, since that implies a thing where // some bits pass through, and others are simply ignored. (That would // be a valid example of a transform, of course.) // // While the output is causally related to the input, it's not a // necessarily symmetric or synchronous transformation. For example, // a zlib stream might take multiple plain-text writes(), and then // emit a single compressed chunk some time in the future. // // Here's how this works: // // The Transform stream has all the aspects of the readable and writable // stream classes. When you write(chunk), that calls _write(chunk,cb) // internally, and returns false if there's a lot of pending writes // buffered up. When you call read(), that calls _read(n) until // there's enough pending readable data buffered up. // // In a transform stream, the written data is placed in a buffer. When // _read(n) is called, it transforms the queued up data, calling the // buffered _write cb's as it consumes chunks. If consuming a single // written chunk would result in multiple output chunks, then the first // outputted bit calls the readcb, and subsequent chunks just go into // the read buffer, and will cause it to emit 'readable' if necessary. // // This way, back-pressure is actually determined by the reading side, // since _read has to be called to start processing a new chunk. However, // a pathological inflate type of transform can cause excessive buffering // here. For example, imagine a stream where every byte of input is // interpreted as an integer from 0-255, and then results in that many // bytes of output. Writing the 4 bytes {ff,ff,ff,ff} would result in // 1kb of data being output. In this case, you could write a very small // amount of input, and end up with a very large amount of output. In // such a pathological inflating mechanism, there'd be no way to tell // the system to stop doing the transform. A single 4MB write could // cause the system to run out of memory. // // However, even in such a pathological case, only a single written chunk // would be consumed, and then the rest would wait (un-transformed) until // the results of the previous transformed chunk were consumed. 'use strict'; const { ObjectSetPrototypeOf, Symbol, } = primordials; module.exports = Transform; const { ERR_METHOD_NOT_IMPLEMENTED, } = require('internal/errors').codes; const Duplex = require('internal/streams/duplex'); const { getHighWaterMark } = require('internal/streams/state'); ObjectSetPrototypeOf(Transform.prototype, Duplex.prototype); ObjectSetPrototypeOf(Transform, Duplex); const kCallback = Symbol('kCallback'); function Transform(options) { if (!(this instanceof Transform)) return new Transform(options); // TODO (ronag): This should preferably always be // applied but would be semver-major. Or even better; // make Transform a Readable with the Writable interface. const readableHighWaterMark = options ? getHighWaterMark(this, options, 'readableHighWaterMark', true) : null; if (readableHighWaterMark === 0) { // A Duplex will buffer both on the writable and readable side while // a Transform just wants to buffer hwm number of elements. To avoid // buffering twice we disable buffering on the writable side. options = { ...options, highWaterMark: null, readableHighWaterMark, // TODO (ronag): 0 is not optimal since we have // a "bug" where we check needDrain before calling _write and not after. // Refs: https://github.com/nodejs/node/pull/32887 // Refs: https://github.com/nodejs/node/pull/35941 writableHighWaterMark: options.writableHighWaterMark || 0, }; } Duplex.call(this, options); // We have implemented the _read method, and done the other things // that Readable wants before the first _read call, so unset the // sync guard flag. this._readableState.sync = false; this[kCallback] = null; if (options) { if (typeof options.transform === 'function') this._transform = options.transform; if (typeof options.flush === 'function') this._flush = options.flush; } // When the writable side finishes, then flush out anything remaining. // Backwards compat. Some Transform streams incorrectly implement _final // instead of or in addition to _flush. By using 'prefinish' instead of // implementing _final we continue supporting this unfortunate use case. this.on('prefinish', prefinish); } function final(cb) { if (typeof this._flush === 'function' && !this.destroyed) { this._flush((er, data) => { if (er) { if (cb) { cb(er); } else { this.destroy(er); } return; } if (data != null) { this.push(data); } this.push(null); if (cb) { cb(); } }); } else { this.push(null); if (cb) { cb(); } } } function prefinish() { if (this._final !== final) { final.call(this); } } Transform.prototype._final = final; Transform.prototype._transform = function(chunk, encoding, callback) { throw new ERR_METHOD_NOT_IMPLEMENTED('_transform()'); }; Transform.prototype._write = function(chunk, encoding, callback) { const rState = this._readableState; const wState = this._writableState; const length = rState.length; this._transform(chunk, encoding, (err, val) => { if (err) { callback(err); return; } if (val != null) { this.push(val); } if ( wState.ended || // Backwards compat. length === rState.length || // Backwards compat. rState.length < rState.highWaterMark ) { callback(); } else { this[kCallback] = callback; } }); }; Transform.prototype._read = function() { if (this[kCallback]) { const callback = this[kCallback]; this[kCallback] = null; callback(); } };