Make random() iterable (#24)

Author: Richienb

.github/workflows/main.yml

@@ -11,7 +11,6 @@ jobs:
       matrix:
         node-version:
           - 14
-          - 12
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2

assert-in-range.js

@@ -0,0 +1,9 @@
+import chalk from 'chalk';
+import inRange from 'in-range';
+
+export default function assertInRange(t, value, {start = 0, end}) {
+	t.true(
+		inRange(value, {start, end}),
+		`${start} ${start <= value ? '≤' : chalk.red('≰')} ${chalk.yellow(value)} ${value <= end ? '≤' : chalk.red('≰')} ${end}`
+	);
+}

index.d.ts

@@ -1,7 +1,7 @@
 /**
 Generate random numbers that are consecutively unique.
 
-@returns A function, that when called, will return a random number that is never the same as the previous.
+@returns Returns a function, that when called, will return a random number that is never the same as the previous. The returned function is also an iterable which consumes from the same source as the function.
 
 @example
 ```
@@ -12,5 +12,21 @@ const random = uniqueRandom(1, 10);
 console.log(random(), random(), random());
 //=> 5 2 6
 ```
+
+@example
+```
+import uniqueRandom from 'unique-random';
+
+const random = uniqueRandom(1, 10);
+
+for (const number of random) {
+	console.log(number);
+
+	// The unique numbers will be iterated over infinitely
+	if (stopCondition) {
+		break;
+	}
+}
+```
 */
-export default function uniqueRandom(minimum: number, maximum: number): () => number;
+export default function uniqueRandom(minimum: number, maximum: number): (() => number) & {[Symbol.iterator](): Iterator<number>};

index.js

@@ -1,13 +1,21 @@
 export default function uniqueRandom(minimum, maximum) {
 	let previousValue;
 
-	return function random() {
+	function random() {
 		const number = Math.floor(
 			(Math.random() * (maximum - minimum + 1)) + minimum
 		);
 
 		previousValue = number === previousValue && minimum !== maximum ? random() : number;
 
 		return previousValue;
+	}
+
+	random[Symbol.iterator] = function * () {
+		while (true) {
+			yield random();
+		}
 	};
+
+	return random;
 }

index.test-d.ts

@@ -1,7 +1,11 @@
-import {expectType} from 'tsd';
+import {expectAssignable, expectType} from 'tsd';
 import uniqueRandom from './index.js';
 
 const random = uniqueRandom(1, 10);
 
-expectType<() => number>(random);
+expectAssignable<() => number>(random);
 expectType<number>(random());
+
+for (const number of random) {
+	expectType<number>(number);
+}

package.json

@@ -33,7 +33,9 @@
 	],
 	"devDependencies": {
 		"ava": "^3.15.0",
-		"tsd": "^0.14.0",
+		"chalk": "^5.3.0",
+		"in-range": "^3.0.0",
+		"tsd": "^0.30.7",
 		"xo": "^0.38.2"
 	}
 }

readme.md

@@ -25,7 +25,22 @@ console.log(random(), random(), random());
 
 ### uniqueRandom(minimum, maximum)
 
-Returns a function, that when called, will return a random number that is never the same as the previous.
+Returns a function, that when called, will return a random number that is never the same as the previous. The returned function is also an iterable which consumes from the same source as the function.
+
+```js
+import uniqueRandom from 'unique-random';
+
+const random = uniqueRandom(1, 10);
+
+for (const number of random) {
+	console.log(number);
+
+	// The unique numbers will be iterated over infinitely
+	if (stopCondition) {
+		break;
+	}
+}
+```
 
 ## Related
 

test.js

@@ -1,4 +1,5 @@
 import test from 'ava';
+import assertInRange from './assert-in-range.js';
 import uniqueRandom from './index.js';
 
 test('main', t => {
@@ -10,16 +11,29 @@ test('main', t => {
 	while (--count > 0) {
 		currentValue = random();
 
-		if (
-			currentValue === previousValue ||
-			currentValue > 10 ||
-			currentValue < 1
-		) {
-			t.fail();
+		assertInRange(t, currentValue, {start: 1, end: 10});
+		if (previousValue !== undefined) {
+			t.not(currentValue, previousValue);
 		}
 
 		previousValue = currentValue;
 	}
 
 	t.pass();
 });
+
+test('iterator', t => {
+	t.plan(3); // In case the for-of loop doesn't run
+
+	const random = uniqueRandom(1, 10);
+
+	for (const number of random) { // eslint-disable-line no-unreachable-loop
+		assertInRange(t, number, {start: 1, end: 10});
+		break;
+	}
+
+	const {value, done} = random[Symbol.iterator]().next();
+
+	assertInRange(t, value, {start: 1, end: 10});
+	t.false(done);
+});