✨ feat(shuffled): First draft.

This allows to shuffle iterables while consuming them. Fixes #59.

Author: make-github-pseudonymous-again

README.md

@@ -12,6 +12,10 @@ Randomness algorithms for JavaScript.
 See [docs](https://aureooms.github.io/js-random).
 Parent is [@aureooms/js-algorithms](https://aureooms.github.io/js-algorithms).
 
+> :warning: Depending on your environment, the code may require
+> `regeneratorRuntime` to be defined, for instance by importing
+> [regenerator-runtime/runtime](https://www.npmjs.com/package/regenerator-runtime).
+
 ```js
 import {
 	randint , // randint(i, j) -> [i, j[ \cap ZZ

doc/manual/usage.md

@@ -1,6 +1,9 @@
 # Usage
-The code needs a ES2015+ polyfill to work, for example
-[regenerator-runtime/runtime](https://babeljs.io/docs/usage/polyfill).
+
+> :warning: Depending on your environment, the code may require
+> `regeneratorRuntime` to be defined, for instance by importing
+> [regenerator-runtime/runtime](https://www.npmjs.com/package/regenerator-runtime).
+
 ```js
 require( 'regenerator-runtime/runtime' ) ;
 // or
@@ -9,7 +12,7 @@ import 'regenerator-runtime/runtime.js' ;
 
 Then
 ```js
-const random = require( '@aureooms/js-random' ) ;
+const { ... } = require( '@aureooms/js-random' ) ;
 // or
-import * as random from '@aureooms/js-random' ;
+import { ... } from '@aureooms/js-random' ;
 ```

src/api/shuffled.js

@@ -0,0 +1,13 @@
+import _fisheryates_inside_out from '../kernel/_fisheryates_inside_out.js';
+import randint from './randint.js';
+
+/**
+ * Given an input iterable, constructs an array containing the elements of the
+ * input shuffled uniformly at random.
+ *
+ * @function
+ * @param {Iterable} iterable The input iterable.
+ * @return {Array} The constructed array.
+ */
+const shuffled = _fisheryates_inside_out(randint);
+export default shuffled;

src/index.js

@@ -5,8 +5,10 @@ export {default as random} from './api/random.js';
 export {default as randrange} from './api/randrange.js';
 export {default as sample} from './api/sample.js';
 export {default as shuffle} from './api/shuffle.js';
+export {default as shuffled} from './api/shuffled.js';
 export {default as _choice} from './kernel/_choice.js';
 export {default as _fisheryates} from './kernel/_fisheryates.js';
+export {default as _fisheryates_inside_out} from './kernel/_fisheryates_inside_out.js';
 export {default as _randfloat} from './kernel/_randfloat.js';
 export {default as _randint} from './kernel/_randint.js';
 export {default as _shuffle} from './kernel/_shuffle.js';

src/kernel/_fisheryates_inside_out.js

@@ -0,0 +1,62 @@
+/**
+ * Shuffle elements of an iterable using an inside-out implementation of the
+ * Fisher-Yates method.
+ *
+ * One can observe that if the input contains n elements, the loop has exactly
+ * n! possible outcomes: one for the first iteration, two for the second, three
+ * for the third, etc., the number of outcomes of a loop being the product of
+ * the number of outcomes for each iteration. Given a perfect randint function,
+ * each iteration's outcomes are equally likely, and independent of other
+ * iterations outcomes.  The proof below shows that these outcomes are
+ * distinct.
+ *
+ * To see that this method yields the correct result (assume perfect randint):
+ *   1. Observe that it is correct when the input is empty.
+ *   2. By induction:
+ *     - Induction hypothesis: assume it is correct when the input consists of
+ *       n elements.
+ *     - We almost insert the (n+1)th element at one of the n+1 possible
+ *       insertion position in the output array. Almost because we move the
+ *       element that is at the insertion position at the end instead of
+ *       shifting the elements right of the insertion position to make room for
+ *       the inserted element.
+ *     - Ideally, since we inserted the last element at one of the n+1
+ *       positions, we would like that the elements inserted earlier form one
+ *       of n! permutations uniformly at random after moving the element under
+ *       the insertion position. This is true because the permutations that we
+ *       obtain after this move are in one-to-one correspondance with the n!
+ *       distinct permutations that can be obtained before the move. These are
+ *       equally likely to be produced by the induction hypothesis.
+ *
+ * @param {Function} randint The randint function.
+ * @return {Function} The sampling function.
+ */
+const _fisheryates_inside_out = (randint) => {
+	/**
+	 * Given an input iterable, constructs an array containing the elements of
+	 * the input shuffled uniformly at random.
+	 *
+	 * @param {Iterable} iterable The input iterable.
+	 * @param {Array} [output=[]] The constructed array.
+	 * @return {Array} The constructed array.
+	 */
+	const shuffled = (iterable, output = []) => {
+		let n = 0;
+		for (const item of iterable) {
+			const i = randint(-1, n);
+			if (i === -1) output.push(item);
+			else {
+				output.push(output[i]);
+				output[i] = item;
+			}
+
+			++n;
+		}
+
+		return output;
+	};
+
+	return shuffled;
+};
+
+export default _fisheryates_inside_out;

test/src/shuffled.js

@@ -0,0 +1,35 @@
+import test from 'ava';
+import {shuffled, _fisheryates_inside_out, randint} from '../../src/index.js';
+
+import {list, range, sorted} from '@aureooms/js-itertools';
+import {increasing} from '@aureooms/js-compare';
+
+const macro = (t, _, shuffle, i, j) => {
+	const input = list(range(i, j));
+	const output = shuffled(range(i, j));
+	t.is(output.length, input.length);
+	t.deepEqual(sorted(increasing, output), sorted(increasing, input));
+};
+
+macro.title = (title, shuffle_name, _, i, j) =>
+	title || `[${n}] shuffled ( ${shuffle_name}, ${i}, ${j} )`;
+
+const n = 100;
+
+const params = [
+	[0, n],
+	[20, n],
+	[0, n - 20],
+	[10, n - 10],
+];
+
+const algorithms = [
+	['inside-out Fisher-Yates', _fisheryates_inside_out(randint)],
+	['API', shuffled],
+];
+
+for (const [name, algorithm] of algorithms) {
+	for (const [i, j] of params) {
+		test(macro, name, algorithm, i, j);
+	}
+}