You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
93 lines
2.9 KiB
Markdown
93 lines
2.9 KiB
Markdown
# @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.
|
|
-->
|