# Constant Stream
> Create a [readable stream][readable-stream] which always streams the same value.
## Usage
```javascript
var constantStream = require( '@stdlib/streams/node/from-constant' );
```
#### constantStream( value\[, options] )
Returns a [readable stream][readable-stream] which **always** streams the **same** `value`.
```javascript
var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
var iStream;
var stream;
function log( chunk, i ) {
console.log( chunk.toString() );
if ( i === 10 ) {
stream.destroy();
}
}
stream = constantStream( 'beep' );
iStream = inspectStream( log );
stream.pipe( iStream );
```
The function accepts the following `options`:
- **objectMode**: specifies whether a [stream][stream] should operate in [objectMode][object-mode]. Default: `false`.
- **encoding**: specifies how `Buffer` objects should be decoded to `strings`. Default: `null`.
- **highWaterMark**: specifies the maximum number of bytes to store in an internal buffer before pausing streaming.
- **sep**: separator used to join streamed data. This option is only applicable when a stream is **not** in [objectMode][object-mode]. Default: `'\n'`.
- **iter**: number of iterations.
To set [stream][stream] `options`,
```javascript
var opts = {
'objectMode': true,
'encoding': 'utf8',
'highWaterMark': 64
};
var stream = constantStream( 'beep', opts );
```
By default, the function returns a [stream][stream] which streams an infinite number of values (i.e., the [stream][stream] will **never** end). To limit the number of streamed values, set the `iter` option.
```javascript
var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
function log( chunk ) {
console.log( chunk.toString() );
}
var opts = {
'iter': 10
};
var stream = constantStream( 'beep', opts );
var iStream = inspectStream( log );
stream.pipe( iStream );
```
By default, when not operating in [objectMode][object-mode], a returned [stream][stream] delineates streamed values using a newline character. To specify an alternative separator, set the `sep` option.
```javascript
var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
function log( chunk ) {
console.log( chunk.toString() );
}
var opts = {
'iter': 10,
'sep': ','
};
var stream = constantStream( 'beep', opts );
var iStream = inspectStream( log );
stream.pipe( iStream );
```
* * *
#### constantStream.factory( \[value, ]\[options] )
Returns a `function` for creating [readable streams][readable-stream] which **always** stream the **same** provided `value`.
```javascript
var opts = {
'objectMode': true,
'encoding': 'utf8',
'highWaterMark': 64
};
var createStream = constantStream.factory( opts );
```
If provided a `value` to stream, the returned function returns [readable streams][readable-stream] which **always** stream the **same** `value`.
```javascript
var createStream = constantStream.factory( 'beep' );
var stream1 = createStream();
var stream2 = createStream();
// ...
```
If not provided a `value` to stream, the returned function requires that a `value` be provided at each invocation.
```javascript
var createStream = constantStream.factory();
var stream1 = createStream( 'beep' );
var stream2 = createStream( 'boop' );
// ...
```
The method accepts the same `options` as [`constantStream()`](#constant-stream).
* * *
#### constantStream.objectMode( value\[, options] )
This method is a convenience function to create [streams][stream] which **always** operate in [objectMode][object-mode].
```javascript
var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
function log( v ) {
console.log( v );
}
var value = {
'beep': 'boop'
};
var opts = {
'iter': 10
};
var stream = constantStream.objectMode( value, opts );
opts = {
'objectMode': true
};
var iStream = inspectStream( opts, log );
stream.pipe( iStream );
```
This method accepts the same `options` as [`constantStream()`](#constant-stream); however, the method will **always** override the [`objectMode`][object-mode] option in `options`.
* * *
## Notes
- In binary mode, a provided `value` must be a `string`, `Buffer`, or `Uint8Array`.
- In [`objectMode`][object-mode], `null` is a reserved value. If provided `null`, the returned [stream][stream] will prematurely end.
- If provided an `object` reference, the `value` is **not** copied. To avoid unwanted mutation, copy the `value` **before** creating a [stream][stream].
- In older Node.js environments, `Uint8Array` contents may be copied to a new `Buffer` object due to changes in the underlying Node.js APIs.
- If the `factory` method is provided only one argument and that argument is an `object` (either empty or not containing any recognized `options` properties), the method treats the argument as a value to be streamed, **not** as an `options` argument.
* * *
## Examples
```javascript
var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
var constantStream = require( '@stdlib/streams/node/from-constant' );
function log( v ) {
console.log( v.toString() );
}
var opts = {
'objectMode': true,
'iter': 10
};
var stream = constantStream( 3.14, opts );
opts = {
'objectMode': true
};
var iStream = inspectStream( opts, log );
stream.pipe( iStream );
```
* * *
## CLI
### Usage
```text
Usage: constant-stream [options]
Options:
-h, --help Print this message.
-V, --version Print the package version.
--sep sep Separator used to join streamed data. Default: '\n'.
-n, --iter iterations Number of iterations.
```
### Notes
- In accordance with POSIX convention, a trailing newline is **always** appended to generated output prior to exit.
### Examples
```bash
$ constant-stream 'beep' -n 10
```
[stream]: https://nodejs.org/api/stream.html
[object-mode]: https://nodejs.org/api/stream.html#stream_object_mode
[readable-stream]: https://nodejs.org/api/stream.html