# @promistream/end-of-stream

<!-- FIXME: Uncomment the below when 1.0.0 is hit -->
<!-- __This module is compatible with the [Promistream](https://promistream.cryto.net/) standard, version 1.0.0 - the latest at the time of writing.__ -->

A simple custom error type for marking the end of a [Promistream](https://promistream.cryto.net/). You'd usually only need this module when you're implementing a source stream.

## Example

An example of *producing* an `EndOfStream` marker, from the [range-numbers](https://www.npmjs.com/package/@promistream/range-numbers) module, which is a source stream that produces numbers within a range:

```js
"use strict";

const simpleSource = require("@promistream/simple-source");
const EndOfStream = require("@promistream/end-of-stream");

module.exports = function rangeNumbers(start, end, step = 1) {
	let i = start;

	return simpleSource({
		onRequest: () => {
			if (i >= end) {
				throw new EndOfStream();
			} else {
				let number = i;
				i += step;
				return number;
			}
		}
	});
}
```

<!-- FIXME: Move below to is-end-of-stream and link from here, also update the example code to use the newer APIs
An example of *detecting* an `EndOfStream` marker, from the [simple-sink](https://git.cryto.net/promistream/simple-sink) module, which just keeps pulling values until the end of the stream:

```js
"use strict";

const Promise = require("bluebird");
const propagateAbort = require("@promistream/propagate-abort");
const { isEndOfStream } = require("@promistream/is-end-of-stream");

module.exports = function greedySinkStream(description, callback) {
	return {
		description: `greedy sink stream (${description})`,
		abort: propagateAbort,
		read: function produceValue_greedySinkStream(source) {
			let lastResult;

			function attemptRead() {
				return Promise.try(() => {
					return source.read();
				}).then((value) => {
					return callback(value);
				}).then((result) => {
					lastResult = result;

					return attemptRead();
				}).catch(isEndOfStream, () => {
					/* Don't attempt to do another read, we're done. We return whatever value we got last from the specified callback. */
					return lastResult;
				});
			}

			return attemptRead();
		}
	};
};
```
-->

## API

### EndOfStream()

A custom Error constructor, that produces an 'end of stream' marker; that is, a special kind of error to signal that the end of the source stream has been reached, and no further values should be requested.

Takes no arguments.

<!-- FIXME: Move below to is-end-of-stream
### isEndOfStream(value)

A function that checks whether the specified `value` is an `EndOfStream` marker, or not.

This function can also be used as a 'predicate function', eg. in a Bluebird `.catch` call (like demonstrated in the example above), or as a `.filter` callback for an array of values.

* __value:__ The value to check.

__Returns:__ `true` or `false`, indicating whether the specified value was an `EndOfStream` marker.
-->