@promistream/simple-queue 0.1.0 → 0.1.1

package/index.js

@@ -1,94 +1,67 @@
 "use strict";
 
-// DOCS: A basic in-memory queue, with no persistence capabilities. Typically useful for implementing recursive asynchronous operations as a stream, such as recursively walking a directory tree.
-// FIXME: Add to spec a suggestion to use the `foo.stream` pattern for things that return more than just a stream?
+const pushBuffer = require("push-buffer");
+const simpleSource = require("@promistream/simple-source");
+const EndOfStream = require("@promistream/end-of-stream");
+const makeDebug = require("debug-instanced")("promistream:simple-queue");
 
-const asExpression = require("as-expression");
-const matchValue = require("match-value");
-const errorChain = require("error-chain");
+const { validateArguments } = require("@validatem/core");
+const arrayOf = require("@validatem/array-of");
+const isBoolean = require("@validatem/is-boolean");
+const anything = require("@validatem/anything");
+const defaultTo = require("@validatem/default-to");
 
-const EndOfStream = require("@promistream/end-of-stream");
-const Aborted = require("@promistream/aborted");
+let currentDebugID = 0;
 
-module.exports = function simpleQueue(initialItems) {
-	// FIXME: Validatem
-	let items = initialItems.slice();
+module.exports = function createSimpleQueue(_initialItems, _options) {
+	let [ initialItems, { autoEnd }] = validateArguments(arguments, {
+		initialItems: [ defaultTo([]), arrayOf(anything) ],
+		options: [ defaultTo({}), {
+			autoEnd: [ defaultTo(true), isBoolean ]
+		}]
+	});
 
-	let peekPointer = 0;
-	let isEnded = false;
-	let errorReason;
+	// TODO: Add initialItems to instance description, if there's a sufficiently cheap way to serialize that
+	let debug = makeDebug(`ID ${currentDebugID++}`);
 
-	return {
-		push: function addItemToQueue(item) {
-			// TODO: Throw an error if stream has already ended?
-			items.push(item);
-		},
-		stream: {
-			_promistreamVersion: 0,
-			_promistreamIsSource: true,
-			description: `simple queue`,
-			peek: async function peekValue_simpleQueue() {
-				// NOTE: 0 items in the queue does *not* mean that the stream has ended, here! This may be a temporary state, and so only translates into an ended state if it is still true when a read is attempted, as per the spec's defined behaviour for parallelized streams.
-				if (errorReason != null || isEnded === true) {
-					return true;
-				} else if (items.length > 0 && peekPointer < items.length - 1) {
-					peekPointer += 1;
-					return true;
-				} else {
-					return false;
-				}
-			},
-			read: async function produceValue_simpleQueue() {
-				let action = asExpression(() => {
-					if (peekPointer > 0) {
-						return "readValue";
-					} else if (errorReason != null) {
-						return "readError";
-					} else if (items.length === 0 || isEnded) {
-						return "endOfStream";
-					} else {
-						return "readValue";
-					}
-				});
+	let buffer = pushBuffer({ mode: "push" });
+	let isEnded = false;
 
-				return matchValue(action, {
-					readValue: () => {
-						// NOTE: As per the spec, each peek corresponds to a later read, but reads are allowed to happen without preceding peeks. Therefore, we should only reduce the peekPointer when it's actually been incremented to begin with.
-						if (peekPointer > 0) {
-							peekPointer -= 1;
-						}
+	debug(`pushing ${initialItems.length} initial items`);
+	for (let item of initialItems) {
+		buffer.push(item);
+	}
 
-						return items.shift();
-					},
-					readError: () => {
-						// FIXME: Abstract out this logic, it's reusable across source streams
-						if (errorReason === true) {
-							throw new Aborted("Stream was aborted");
-						} else if (errorReason instanceof Error) {
-							throw new errorChain.chain(errorReason, Aborted, `Stream was aborted due to error: ${errorReason.message}`);
-						}
-					},
-					endOfStream: () => {
-						// This locks the queue into an 'ended' state for spec compliance, even if some misbehaving code pushes an item after the pipeline has already been torn down
-						isEnded = true;
+	let stream = simpleSource(() => {
+		if (isEnded === false && buffer.countLane().values > 0) {
+			debug(`values available; requesting one`);
+			return buffer.request();
+		} else if (autoEnd === false) {
+			// We will wait for an external end signal, and never end the stream ourselves
+			debug(`no values available, but autoEnd is disabled; waiting for value...`);
+			return buffer.request();
+		} else {
+			// Lock into ended state; this stream will never produce values again, even if values get pushed later
+			debug(`stream has ended`);
+			isEnded = true;
+			throw new EndOfStream();
+		}
+	});
 
-						throw new EndOfStream;
-					}
-				});
-			},
-			abort: async function abort_simpleQueue(reason, _source) {
-				// FIXME: Abstract out this logic, it's reusable across source streams
-				if (errorReason == null) {
-					if (reason === true || reason instanceof Error) {
-						errorReason = reason;
-					} else {
-						throw new Error("You must specify a reason (either `true` or an Error object) when aborting a stream");
-					}
-				} else {
-					// FIXME: Require this behaviour in the spec? Or is there a composability-related reason to permit/require quietly ignoring this, to make it idempotent?
-					throw new Error(`The stream is already aborted`);
-				}
+	return {
+		stream: stream,
+		push: async function (item) {
+			if (isEnded) {
+				throw new Error(`Queue has already ended`);
+			} else {
+				debug(`pushing item to queue`, item);
+				return buffer.push(item);
 			}
+		},
+		end: async function () {
+			debug(`marking queue as ended`);
+			isEnded = true;
+			return buffer.pushError(new EndOfStream("Queue was ended"));
 		}
 	};
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promistream/simple-queue",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "main": "index.js",
   "repository": "http://git.cryto.net/promistream/simple-queue.git",
   "author": "Sven Slootweg <admin@cryto.net>",
@@ -8,13 +8,20 @@
   "dependencies": {
     "@promistream/aborted": "^0.1.2",
     "@promistream/end-of-stream": "^0.1.0",
+    "@validatem/anything": "^0.1.0",
+    "@validatem/array-of": "^0.1.3",
+    "@validatem/core": "^0.6.0",
+    "@validatem/default-to": "^0.1.0",
+    "@validatem/is-boolean": "^0.1.1",
     "as-expression": "^1.0.0",
+    "debug-instanced": "^1.0.0",
     "error-chain": "^0.1.3",
-    "match-value": "^1.1.0"
+    "match-value": "^1.1.0",
+    "push-buffer": "^1.0.0"
   },
   "devDependencies": {
     "@promistream/collect": "^0.1.1",
-    "@promistream/parallelize": "^0.1.0",
+    "@promistream/parallelize": "^0.1.3",
     "@promistream/pipe": "^0.1.6",
     "@promistream/spy": "^0.1.0",
     "bluebird": "^3.7.2"

package/test.js

@@ -0,0 +1,63 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert");
+
+const simpleQueue = require("./");
+
+const pipe = require("@promistream/pipe");
+const spy = require("@promistream/spy");
+const parallelize = require("@promistream/parallelize");
+const collect = require("@promistream/collect");
+
+test("basic functioning", async () => {
+	let queue = simpleQueue([ 0, 1, 2, 3, 4, 5, 6, 7 ]);
+
+	let result = await pipe([
+		queue.stream,
+		spy((value) => {
+			if (value < 5) {
+				queue.push(value + 8);
+			}
+		}),
+		collect()
+	]).read();
+
+	assert(result, [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ]);
+});
+
+test("unbounded parallelism", async () => {
+	let queue = simpleQueue([ 0, 1, 2, 3, 4, 5, 6, 7 ]);
+
+	let result = await pipe([
+		queue.stream,
+		spy((value) => {
+			if (value < 5) {
+				queue.push(value + 8);
+			}
+		}),
+		parallelize(Infinity),
+		collect()
+	]).read();
+
+	assert(result, [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ]);
+});
+
+test("autoEnd = false", async () => {
+	let queue = simpleQueue([ 0, 1, 2, 3, 4, 5, 6, 7 ], { autoEnd: false });
+
+	setTimeout(() => queue.end(), 250); // Much longer than it would normally take to complete
+
+	let result = await pipe([
+		queue.stream,
+		spy((value) => {
+			if (value < 5) {
+				queue.push(value + 8);
+			}
+		}),
+		parallelize(300),
+		collect()
+	]).read();
+
+	assert(result, [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ]);
+});