main.js (3627B)
1 /** 2 * @license Apache-2.0 3 * 4 * Copyright (c) 2018 The Stdlib Authors. 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 'use strict'; 20 21 // MODULES // 22 23 var logger = require( 'debug' ); 24 var Transform = require( 'readable-stream' ).Transform; 25 var inherit = require( '@stdlib/utils/inherit' ); 26 var copy = require( '@stdlib/utils/copy' ); 27 var DEFAULTS = require( './defaults.json' ); 28 var validate = require( './validate.js' ); 29 var destroy = require( './destroy.js' ); 30 var _transform = require( './_transform.js' ); // eslint-disable-line no-underscore-dangle 31 32 33 // VARIABLES // 34 35 var debug = logger( 'transform-stream:main' ); 36 37 38 // MAIN // 39 40 /** 41 * Transform stream constructor. 42 * 43 * @constructor 44 * @param {Options} [options] - stream options 45 * @param {Function} [options.transform] - callback to invoke upon receiving a new chunk 46 * @param {Function} [options.flush] - callback to invoke after receiving all chunks and prior to the stream closing 47 * @param {boolean} [options.objectMode=false] - specifies whether stream should operate in object mode 48 * @param {(string|null)} [options.encoding=null] - specifies how `Buffer` objects should be decoded to `strings` 49 * @param {NonNegativeNumber} [options.highWaterMark] - specifies the `Buffer` level for when `write()` starts returning `false` 50 * @param {boolean} [options.allowHalfOpen=false] - specifies whether the stream should remain open even if one side ends 51 * @param {boolean} [options.decodeStrings=true] - specifies whether to decode `strings` into `Buffer` objects when writing 52 * @throws {TypeError} must provide valid options 53 * @returns {TransformStream} transform stream 54 * 55 * @example 56 * var stdout = require( '@stdlib/streams/node/stdout' ); 57 * 58 * function transform( chunk, enc, clbk ) { 59 * clbk( null, chunk.toString()+'\n' ); 60 * } 61 * 62 * var opts = { 63 * 'transform': transform 64 * }; 65 * var stream = new TransformStream( opts ); 66 * 67 * stream.pipe( stdout ); 68 * 69 * stream.write( '1' ); 70 * stream.write( '2' ); 71 * stream.write( '3' ); 72 * 73 * stream.end(); 74 * 75 * // prints: '1\n2\n3\n' 76 */ 77 function TransformStream( options ) { 78 var opts; 79 var err; 80 if ( !( this instanceof TransformStream ) ) { 81 if ( arguments.length ) { 82 return new TransformStream( options ); 83 } 84 return new TransformStream(); 85 } 86 opts = copy( DEFAULTS ); 87 if ( arguments.length ) { 88 err = validate( opts, options ); 89 if ( err ) { 90 throw err; 91 } 92 } 93 debug( 'Creating a transform stream configured with the following options: %s.', JSON.stringify( opts ) ); 94 Transform.call( this, opts ); 95 this._destroyed = false; 96 if ( opts.transform ) { 97 this._transform = opts.transform; 98 } else { 99 this._transform = _transform; 100 } 101 if ( opts.flush ) { 102 this._flush = opts.flush; 103 } 104 return this; 105 } 106 107 /* 108 * Inherit from the `Transform` prototype. 109 */ 110 inherit( TransformStream, Transform ); 111 112 /** 113 * Gracefully destroys a stream, providing backward compatibility. 114 * 115 * @name destroy 116 * @memberof TransformStream.prototype 117 * @type {Function} 118 * @param {Object} [error] - optional error message 119 * @returns {TransformStream} stream instance 120 */ 121 TransformStream.prototype.destroy = destroy; 122 123 124 // EXPORTS // 125 126 module.exports = TransformStream;