🚧 progress: Import existing sources, test, and code samples.

Author: make-github-pseudonymous-again

README.md

@@ -4,13 +4,16 @@
 Iterable items grouping for JavaScript.
 See [docs](https://iterable-iterator.github.io/group/index.html).
 
-> :building_construction: Caveat emptor! This is work in progress. Code may be
-> working. Documentation may be present. Coherence may be. Maybe.
-
 > :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 {group} from '@iterable-iterator/group';
+import {identity} from '@functional-abstraction/operator';
+group( identity , "AAAABBBCCAABB" ) ; // [ A AAAA ] [ B BBB ] [ C CC ] [ A AA ] [ B BB ]
+```
+
 [![License](https://img.shields.io/github/license/iterable-iterator/group.svg)](https://raw.githubusercontent.com/iterable-iterator/group/main/LICENSE)
 [![Version](https://img.shields.io/npm/v/@iterable-iterator/group.svg)](https://www.npmjs.org/package/@iterable-iterator/group)
 [![Tests](https://img.shields.io/github/workflow/status/iterable-iterator/group/ci:test?event=push&label=tests)](https://github.com/iterable-iterator/group/actions/workflows/ci:test.yml?query=branch:main)

package.json

@@ -60,12 +60,24 @@
     "release": "np --message ':hatching_chick: release: Bumping to v%s.'",
     "test": "ava"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@iterable-iterator/iter": "^0.0.2",
+    "@iterable-iterator/range": "^1.0.0"
+  },
   "devDependencies": {
     "@babel/core": "7.14.0",
     "@babel/preset-env": "7.14.0",
     "@babel/register": "7.13.16",
     "@commitlint/cli": "12.1.1",
+    "@functional-abstraction/operator": "^1.0.4",
+    "@iterable-iterator/count": "^0.0.1",
+    "@iterable-iterator/cycle": "^0.0.1",
+    "@iterable-iterator/list": "^0.0.2",
+    "@iterable-iterator/map": "^0.0.1",
+    "@iterable-iterator/next": "^1.0.0",
+    "@iterable-iterator/repeat": "^0.0.1",
+    "@iterable-iterator/slice": "^0.0.1",
+    "@iterable-iterator/zip": "^0.0.1",
     "@js-library/commitlint-config": "0.0.4",
     "ava": "3.15.0",
     "babel-plugin-transform-remove-console": "6.9.4",

src/by.js

@@ -0,0 +1,41 @@
+import {iter} from '@iterable-iterator/iter';
+import {range} from '@iterable-iterator/range';
+
+/**
+ * Yields elements of the input iterable by grouping them into tuples of a
+ * given size.
+ *
+ * @param {Iterable} iterable - The input iterable.
+ * @param {Number} n - The size of the yielded tuples.
+ * @returns {Iterator}
+ */
+export default function* by(iterable, n) {
+	const iterator = iter(iterable);
+
+	while (true) {
+		const tuple = [];
+
+		for (const i of range(n)) {
+			const current = iterator.next();
+
+			if (current.done) {
+				if (i === 0) {
+					return;
+				}
+
+				// eslint-disable-next-line no-unused-vars
+				for (const j of range(n - i)) {
+					tuple.push(undefined);
+				}
+
+				yield tuple;
+
+				return;
+			}
+
+			tuple.push(current.value);
+		}
+
+		yield tuple;
+	}
+}

src/group.js

@@ -0,0 +1,67 @@
+import {iter} from '@iterable-iterator/iter';
+
+/**
+ * Yields elements of the input iterable by grouping them into tuples
+ * consecutive elements from the same equivalence class.
+ *
+ * @example
+ * // A B C D A B
+ * list( map( ( [ k , g ] ) => k , group( x => x , 'AAAABBBCCDAABBB' ) ) )
+ *
+ * @example
+ * // AAAA BBB CC D
+ * list( map( ( [ k , g ] ) => list( g ) , group( x => x , 'AAAABBBCCD' ) ) )
+ *
+ * @param {Function} key - The function used to determine the equivalence class
+ * of an element.
+ * @param {Iterable} iterable - The input iterable.
+ * @returns {Iterator}
+ */
+export default function* group(key, iterable) {
+	const iterator = iter(iterable);
+
+	const first = iterator.next();
+
+	if (first.done) {
+		return;
+	}
+
+	let currval = first.value;
+	let currkey = key(currval);
+
+	const grouper = function* (tgtkey) {
+		while (true) {
+			yield currval;
+
+			const event = iterator.next();
+			if (event.done) {
+				return;
+			}
+
+			currval = event.value;
+			currkey = key(currval);
+
+			if (currkey !== tgtkey) {
+				return;
+			}
+		}
+	};
+
+	while (true) {
+		const tgtkey = currkey;
+
+		const g = grouper(tgtkey);
+
+		yield [tgtkey, g];
+
+		while (currkey === tgtkey) {
+			const event = iterator.next();
+			if (event.done) {
+				return;
+			}
+
+			currval = event.value;
+			currkey = key(currval);
+		}
+	}
+}

src/groupby.js

@@ -0,0 +1,8 @@
+import group from './group.js';
+
+/**
+ * Same as {@link group}.
+ * @function groupby
+ */
+const groupby = group;
+export default groupby;

src/index.js

@@ -1,2 +1,3 @@
-const answer = 42;
-export default answer;
+export {default as by} from './by.js';
+export {default as group} from './group.js';
+export {default as groupby} from './groupby.js';

test/src/api.js

@@ -0,0 +1,42 @@
+import test from 'ava';
+
+import {range} from '@iterable-iterator/range';
+import {zip} from '@iterable-iterator/zip';
+import {list} from '@iterable-iterator/list';
+import {count} from '@iterable-iterator/count';
+import {head} from '@iterable-iterator/slice';
+
+import {by} from '../../src/index.js';
+
+test('by', (t) => {
+	const A = by(range(100), 2);
+	const B = zip(range(0, 100, 2), range(1, 100, 2));
+
+	t.deepEqual(list(A), list(B), 'compare to zip output');
+
+	const C = by(range(4), 3);
+
+	t.deepEqual(
+		list(C),
+		[
+			[0, 1, 2],
+			[3, undefined, undefined],
+		],
+		'n !| N',
+	);
+
+	const D = by('', 3);
+
+	t.deepEqual(list(D), [], 'empty');
+});
+
+test('by (infinite sequences)', (t) => {
+	const A = by(count(), 2);
+	const B = zip(count(0, 2), count(1, 2));
+
+	t.deepEqual(
+		list(head(A, 1000)),
+		list(head(B, 1000)),
+		'compare to zip output',
+	);
+});

test/src/by.js

@@ -0,0 +1,103 @@
+import test from 'ava';
+
+import {identity} from '@functional-abstraction/operator';
+
+import {range} from '@iterable-iterator/range';
+import {map} from '@iterable-iterator/map';
+import {repeat} from '@iterable-iterator/repeat';
+import {ncycle} from '@iterable-iterator/cycle';
+import {next} from '@iterable-iterator/next';
+import {list} from '@iterable-iterator/list';
+
+import {group, groupby} from '../../src/index.js';
+
+test('groupby is group', (t) => {
+	t.is(groupby, group);
+});
+
+test('group', (t) => {
+	const x = (key, iterable, expected) => {
+		t.deepEqual(
+			list(map(([k, g]) => [k, list(g)], group(key, iterable))),
+			expected,
+		);
+	};
+
+	x(identity, '', []);
+
+	x(identity, 'AAAAAABBBBCCCCAABBCC', [
+		['A', ['A', 'A', 'A', 'A', 'A', 'A']],
+		['B', ['B', 'B', 'B', 'B']],
+		['C', ['C', 'C', 'C', 'C']],
+		['A', ['A', 'A']],
+		['B', ['B', 'B']],
+		['C', ['C', 'C']],
+	]);
+
+	x(
+		(item) => {
+			return item.charCodeAt(0) - 65;
+		},
+		'AAAAAABBBBCCCCAABBCC',
+		[
+			[0, ['A', 'A', 'A', 'A', 'A', 'A']],
+			[1, ['B', 'B', 'B', 'B']],
+			[2, ['C', 'C', 'C', 'C']],
+			[0, ['A', 'A']],
+			[1, ['B', 'B']],
+			[2, ['C', 'C']],
+		],
+	);
+
+	x(
+		(item) => {
+			return Math.floor((item.charCodeAt(0) - 65) / 2);
+		},
+		'AAAAAABBBBCCCCAABBCC',
+		[
+			[0, ['A', 'A', 'A', 'A', 'A', 'A', 'B', 'B', 'B', 'B']],
+			[1, ['C', 'C', 'C', 'C']],
+			[0, ['A', 'A', 'B', 'B']],
+			[1, ['C', 'C']],
+		],
+	);
+});
+
+test('group keys', (t) => {
+	const x = (key, iterable, expected) => {
+		t.deepEqual(list(map(([k, _]) => k, group(key, iterable))), expected);
+	};
+
+	x(identity, '', []);
+
+	x(identity, 'AAAAAABBBBCCCCAABBCC', list('ABCABC'));
+
+	x(
+		(item) => {
+			return item.charCodeAt(0) - 65;
+		},
+		'AAAAAABBBBCCCCAABBCC',
+		list(ncycle(range(3), 2)),
+	);
+
+	x(
+		(item) => {
+			return Math.floor((item.charCodeAt(0) - 65) / 2);
+		},
+		'AAAAAABBBBCCCCAABBCC',
+		list(ncycle(range(2), 2)),
+	);
+});
+
+test('group for infinite sequence of something', (t) => {
+	const v = Math.random();
+
+	const [k, g] = next(group(identity, repeat(v)));
+
+	t.deepEqual(k, v);
+
+	// eslint-disable-next-line no-unused-vars
+	for (const _ of range(1000)) {
+		t.deepEqual(next(g), v);
+	}
+});