From 000ac8c49cde942b3c8332dddd636d6508e8ad82 Mon Sep 17 00:00:00 2001
From: Sven Slootweg <admin@cryto.net>
Date: Sun, 19 Jul 2020 21:10:21 +0200
Subject: [PATCH] Initial commit

---
 .gitignore   |  1 +
 README.md    | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 index.js     |  9 +++++
 package.json | 11 +++++++
 yarn.lock    |  8 +++++
 5 files changed, 121 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 index.js
 create mode 100644 package.json
 create mode 100644 yarn.lock

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..3c3629e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+node_modules
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a439530
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+# @ppstreams/end-of-stream-marker
+
+<!-- FIXME: Uncomment the below when 1.0.0 is hit -->
+<!-- __This module is compatible with the [ppstreams](https://ppstreams.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 [ppstreams](https://ppstreams.cryto.net/) stream. 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/@ppstreams/range-numbers) module, which is a source stream that produces numbers within a range:
+
+```js
+"use strict";
+
+const simpleSource = require("@ppstreams/simple-source");
+const EndOfStream = require("@ppstreams/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/ppstreams/simple-sink) module, which just keeps pulling values until the end of the stream:
+
+```js
+"use strict";
+
+const Promise = require("bluebird");
+const propagateAbort = require("@ppstreams/propagate-abort");
+const { isEndOfStream } = require("@ppstreams/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.
+-->
diff --git a/index.js b/index.js
new file mode 100644
index 0000000..f07398c
--- /dev/null
+++ b/index.js
@@ -0,0 +1,9 @@
+"use strict";
+
+const createError = require("create-error");
+
+// MARKER: Update everything that uses end-of-stream-marker or aborted-marker to the new split-module API
+module.exports =  createError("EndOfStream", {
+	__ppstreams_isEndOfStreamMarker: true,
+	__ppstreams_specVersion: 1
+});
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..b4ae8f5
--- /dev/null
+++ b/package.json
@@ -0,0 +1,11 @@
+{
+  "name": "@ppstreams/end-of-stream",
+  "version": "0.1.0",
+  "main": "index.js",
+  "repository": "http://git.cryto.net/ppstreams/end-of-stream.git",
+  "author": "Sven Slootweg <admin@cryto.net>",
+  "license": "WTFPL OR CC0-1.0",
+  "dependencies": {
+    "create-error": "^0.3.1"
+  }
+}
diff --git a/yarn.lock b/yarn.lock
new file mode 100644
index 0000000..18fdc6d
--- /dev/null
+++ b/yarn.lock
@@ -0,0 +1,8 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+create-error@^0.3.1:
+  version "0.3.1"
+  resolved "https://registry.yarnpkg.com/create-error/-/create-error-0.3.1.tgz#69810245a629e654432bf04377360003a5351a23"
+  integrity sha1-aYECRaYp5lRDK/BDdzYAA6U1GiM=