main.js (6288B)
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 Transform = require( 'readable-stream' ).Transform; 24 var isFunction = require( '@stdlib/assert/is-function' ); 25 var copy = require( '@stdlib/utils/copy' ); 26 var inherit = require( '@stdlib/utils/inherit' ); 27 var setNonEnumerable = require( '@stdlib/utils/define-nonenumerable-property' ); 28 var setNonEnumerableReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' ); 29 var nextTick = require( '@stdlib/utils/next-tick' ); 30 var DEFAULTS = require( './defaults.json' ); 31 var validate = require( './validate.js' ); 32 var debug = require( './debug.js' ); 33 34 35 // FUNCTIONS // 36 37 /** 38 * Implements the `_transform` method. 39 * 40 * @private 41 * @param {(Uint8Array|Buffer|string)} chunk - streamed chunk 42 * @param {string} encoding - Buffer encoding 43 * @param {Callback} clbk - callback to invoke after transforming the streamed chunk 44 */ 45 function transform( chunk, encoding, clbk ) { 46 /* eslint-disable no-invalid-this */ 47 this._idx += 1; 48 debug( 'Received a new chunk. Chunk: %s. Encoding: %s. Index: %d.', chunk.toString(), encoding, this._idx ); 49 this._inspect.call( null, chunk, this._idx ); 50 this.push( chunk ); 51 clbk(); 52 53 /* eslint-enable no-invalid-this */ 54 } 55 56 /** 57 * Implements the `_flush` method. 58 * 59 * @private 60 * @param {Callback} clbk - callback to invoke after performing flush tasks 61 */ 62 function flush( clbk ) { 63 debug( 'Flushing the stream...' ); 64 clbk(); 65 } 66 67 /** 68 * Gracefully destroys a stream, providing backward compatibility. 69 * 70 * @private 71 * @param {Object} [error] - optional error message 72 * @returns {InspectStream} stream instance 73 */ 74 function destroy( error ) { 75 /* eslint-disable no-invalid-this */ 76 var self; 77 if ( this._destroyed ) { 78 debug( 'Attempted to destroy an already destroyed stream.' ); 79 return this; 80 } 81 self = this; 82 this._destroyed = true; 83 84 nextTick( close ); 85 86 return this; 87 88 /** 89 * Closes a stream. 90 * 91 * @private 92 */ 93 function close() { 94 if ( error ) { 95 debug( 'Stream was destroyed due to an error. Error: %s.', JSON.stringify( error ) ); 96 self.emit( 'error', error ); 97 } 98 debug( 'Closing the stream...' ); 99 self.emit( 'close' ); 100 } 101 102 /* eslint-enable no-invalid-this */ 103 } 104 105 106 // MAIN // 107 108 /** 109 * Inspect stream constructor. 110 * 111 * @constructor 112 * @param {Options} [options] - stream options 113 * @param {boolean} [options.objectMode=false] - specifies whether the stream should operate in object mode 114 * @param {NonNegativeNumber} [options.highWaterMark] - specifies the `Buffer` level for when `write()` starts returning `false` 115 * @param {boolean} [options.allowHalfOpen=false] - specifies whether the stream should remain open even if one side ends 116 * @param {boolean} [options.readableObjectMode=false] - specifies whether the readable side should be in object mode 117 * @param {Callback} clbk - callback to invoke upon receiving data 118 * @throws {TypeError} options argument must be an object 119 * @throws {TypeError} must provide valid options 120 * @throws {TypeError} must provide a callback function 121 * @returns {InspectStream} inspect stream 122 * 123 * @example 124 * function log( chunk, idx ) { 125 * console.log( 'index: %d', idx ); 126 * console.log( chunk ); 127 * } 128 * 129 * var stream = new InspectStream( log ); 130 * 131 * stream.write( 'a' ); 132 * stream.write( 'b' ); 133 * stream.write( 'c' ); 134 * 135 * stream.end(); 136 * 137 * // prints: index: 0 138 * // prints: a 139 * // prints: index: 1 140 * // prints: b 141 * // prints: index: 2 142 * // prints: c 143 */ 144 function InspectStream( options, clbk ) { 145 var inspect; 146 var opts; 147 var err; 148 if ( !(this instanceof InspectStream) ) { 149 if ( arguments.length > 1 ) { 150 return new InspectStream( options, clbk ); 151 } 152 return new InspectStream( options ); 153 } 154 opts = copy( DEFAULTS ); 155 if ( arguments.length > 1 ) { 156 inspect = clbk; 157 err = validate( opts, options ); 158 if ( err ) { 159 throw err; 160 } 161 } else { 162 inspect = options; 163 } 164 if ( !isFunction( inspect ) ) { 165 throw new TypeError( 'invalid argument. Callback argument must be a function. Value: `' + inspect + '`.' ); 166 } 167 // The stream's writable state should always be in object mode to prevent incoming data from being buffered (concatenated) and thus lose separation... 168 opts.writableObjectMode = true; 169 170 // Make the stream a Transform stream: 171 debug( 'Creating a transform stream configured with the following options: %s.', JSON.stringify( opts ) ); 172 Transform.call( this, opts ); 173 174 // The destruction state: 175 setNonEnumerable( this, '_destroyed', false ); 176 177 // Initialize a chunk counter: 178 setNonEnumerable( this, '_idx', -1 ); 179 180 // Cache a reference to the inspect callback: 181 setNonEnumerableReadOnly( this, '_inspect', inspect ); 182 183 return this; 184 } 185 186 /* 187 * Inherit from the `Transform` prototype. 188 */ 189 inherit( InspectStream, Transform ); 190 191 /** 192 * Implements the `_transform` method. 193 * 194 * @private 195 * @name _transform 196 * @memberof InspectStream.prototype 197 * @type {Function} 198 * @param {(Buffer|string)} chunk - streamed chunk 199 * @param {string} encoding - Buffer encoding 200 * @param {Callback} clbk - callback to invoke after transforming the streamed chunk 201 */ 202 setNonEnumerableReadOnly( InspectStream.prototype, '_transform', transform ); 203 204 /** 205 * Implements the `_flush` method. 206 * 207 * @private 208 * @name _flush 209 * @memberof InspectStream.prototype 210 * @type {Function} 211 * @param {Callback} clbk - callback to invoke after performing flush tasks 212 */ 213 setNonEnumerableReadOnly( InspectStream.prototype, '_flush', flush ); 214 215 /** 216 * Gracefully destroys a stream, providing backward compatibility. 217 * 218 * @name destroy 219 * @memberof InspectStream.prototype 220 * @type {Function} 221 * @param {Object} [error] - optional error message 222 * @returns {InspectStream} stream instance 223 */ 224 setNonEnumerableReadOnly( InspectStream.prototype, 'destroy', destroy ); 225 226 227 // EXPORTS // 228 229 module.exports = InspectStream;