✨ feat: Settle on API.

Author: make-github-pseudonymous-again

README.md

@@ -1,11 +1,16 @@
-[@aureooms/js-maximum-matching](https://aureooms.github.io/js-maximum-matching)
+:cherry_blossom: [@aureooms/js-maximum-matching](https://aureooms.github.io/js-maximum-matching)
 ==
 
-Graphs and networks code bricks for JavaScript.
-Parents are
-[@aureooms/js-algorithms](https://github.com/aureooms/js-algorithms)
-and
-[@aureooms/js-data-structures](https://github.com/aureooms/js-data-structures).
+Maximum matching algorithms for JavaScript.
+Parent is [@aureooms/js-gn](https://github.com/aureooms/js-gn).
+See [docs](https://aureooms.github.io/js-maximum-matching/index.html).
+
+```js
+import maximumMatching, {iter} from '@aureooms/js-maximum-matching';
+const edges = [[1, 2, 10], [2, 3, 11]] ;
+const matching = maximumMatching(edges) ; // [-1, -1, 3, 2]
+iter(matching); // [ [2, 3] ]
+```
 
 [![License](https://img.shields.io/github/license/aureooms/js-maximum-matching.svg)](https://raw.githubusercontent.com/aureooms/js-maximum-matching/master/LICENSE)
 [![Version](https://img.shields.io/npm/v/@aureooms/js-maximum-matching.svg)](https://www.npmjs.org/package/@aureooms/js-maximum-matching)

src/cardinality/approx/bipartite.js

@@ -0,0 +1,3 @@
+import general from './general';
+
+export default general;

src/cardinality/approx/general.js

@@ -0,0 +1,4 @@
+import general from '../opt/general';
+
+const generalApprox = (edges, _eps) => general(edges);
+export default generalApprox;

src/cardinality/approx/index.js

@@ -0,0 +1,6 @@
+import bipartite from './bipartite';
+import general from './general';
+
+export default general;
+
+export {bipartite, general};

src/cardinality/index.js

@@ -0,0 +1,6 @@
+import approx from './approx';
+import opt from './opt';
+
+export default opt;
+
+export {approx, opt};

src/cardinality/opt/bipartite.js

@@ -0,0 +1,3 @@
+import general from './general';
+
+export default general;

src/cardinality/opt/general.js

@@ -0,0 +1,5 @@
+import blossomNoChecks from '../../core/blossomNoChecks';
+
+const general = (edges) => blossomNoChecks(edges, true);
+
+export default general;

src/cardinality/opt/index.js

@@ -0,0 +1,6 @@
+import bipartite from './bipartite';
+import general from './general';
+
+export default general;
+
+export {bipartite, general};

src/exact/blossom.js renamed to src/core/blossom.js

@@ -32,16 +32,14 @@ export default function blossom(CHECK_OPTIMUM, CHECK_DELTA) {
 	// Check optimality of solution before returning; only works on integer weights.
 	if (CHECK_OPTIMUM === undefined) CHECK_OPTIMUM = true;
 
-	const maxWeightMatching = function (edges, maxcardinality) {
+	const maxWeightMatching = function (edges, maxcardinality = false) {
 		let i;
 		let j;
 		let k;
 		let p;
 		let w;
 		let length;
 
-		if (maxcardinality === undefined) maxcardinality = false;
-
 		/**
 		 *
 		 * Compute a maximum-weighted matching in the general undirected

src/core/blossomNoChecks.js

@@ -0,0 +1,5 @@
+import blossom from './blossom';
+
+const blossomNoChecks = blossom(false, false);
+
+export default blossomNoChecks;

src/core/index.js

@@ -0,0 +1,10 @@
+import blossom from './blossom';
+import blossomNoChecks from './blossomNoChecks';
+
+/* eslint import/no-anonymous-default-export: [2, {"allowObject": true}] */
+export default {
+	blossom,
+	blossomNoChecks
+};
+
+export {blossom, blossomNoChecks};

src/index.js

@@ -0,0 +1,8 @@
+import cardinality from './cardinality';
+import core from './core';
+import weight from './weight';
+import iter from './iter';
+
+export default weight;
+
+export {cardinality, core, weight, iter};

src/iter.js

@@ -0,0 +1,8 @@
+export default function* iter(matching) {
+	let i = 0;
+	for (const j of matching) {
+		// This takes care of j === -1
+		if (i < j) yield [i, j];
+		++i;
+	}
+}

src/weight/approx/bipartite.js

@@ -0,0 +1,3 @@
+import general from './general';
+
+export default general;

src/weight/approx/general.js

@@ -0,0 +1,4 @@
+import general from '../opt/general';
+
+const generalApprox = (edges, _eps) => general(edges);
+export default generalApprox;

src/weight/approx/index.js

@@ -0,0 +1,6 @@
+import bipartite from './bipartite';
+import general from './general';
+
+export default general;
+
+export {bipartite, general};

src/weight/index.js

@@ -0,0 +1,6 @@
+import approx from './approx';
+import opt from './opt';
+
+export default opt;
+
+export {approx, opt};

src/weight/opt/bipartite.js

@@ -0,0 +1,3 @@
+import general from './general';
+
+export default general;

src/weight/opt/general.js

@@ -0,0 +1,5 @@
+import blossomNoChecks from '../../core/blossomNoChecks';
+
+const general = (edges) => blossomNoChecks(edges);
+
+export default general;

src/weight/opt/index.js

@@ -0,0 +1,6 @@
+import bipartite from './bipartite';
+import general from './general';
+
+export default general;
+
+export {bipartite, general};

test/src/cardinality.js

@@ -0,0 +1,51 @@
+import test from 'ava';
+import {enumerate} from '@aureooms/js-itertools';
+
+import maximumCardinalityMatching from '../../src/cardinality';
+import blossom from '../../src/core/blossom';
+
+const macro = (t, algorithm, edges, expected) => {
+	const input = edges.map((edge) => edge.slice()); // Deepcopy
+	const result = algorithm(edges);
+	t.deepEqual(expected, result);
+	t.deepEqual(input, edges);
+};
+
+macro.title = (title, algorithm, edges, expected) =>
+	title ||
+	`${algorithm.name}(${JSON.stringify(edges)}) = ${JSON.stringify(expected)}`;
+
+const tests = {
+	test14_maxcard: {
+		edges: [
+			[1, 2, 5],
+			[2, 3, 11],
+			[3, 4, 5]
+		],
+		expected: [-1, 2, 1, 4, 3]
+	},
+
+	test16_negative_maxCardinality: {
+		edges: [
+			[1, 2, 2],
+			[1, 3, -2],
+			[2, 3, 1],
+			[2, 4, -1],
+			[3, 4, -6]
+		],
+		expected: [-1, 3, 4, 1, 2]
+	}
+};
+
+const btt = blossom(true, true);
+const bdflt = blossom();
+
+const algorithms = [
+	maximumCardinalityMatching,
+	(edges) => btt(edges, true),
+	(edges) => bdflt(edges, true)
+];
+
+for (const [i, algorithm] of enumerate(algorithms))
+	for (const [key, {edges, expected}] of Object.entries(tests))
+		test(`${key} ${i}`, macro, algorithm, edges, expected);

test/src/readme.js

@@ -0,0 +1,13 @@
+import test from 'ava';
+
+import maximumMatching, {iter} from '../../src';
+
+test('README', (t) => {
+	const edges = [
+		[1, 2, 10],
+		[2, 3, 11]
+	];
+	const matching = maximumMatching(edges); // [-1, -1, 3, 2]
+	t.deepEqual([-1, -1, 3, 2], matching);
+	t.deepEqual([[2, 3]], [...iter(matching)]);
+});

test/src/exact/blossom.js renamed to test/src/weight.js

@@ -1,20 +1,19 @@
 import test from 'ava';
 import {enumerate} from '@aureooms/js-itertools';
 
-import blossom from '../../../src/exact/blossom';
+import maximumMatching from '../../src';
+import blossom from '../../src/core/blossom';
 
-const macro = (t, algorithm, edges, maxCardinality, expected) => {
+const macro = (t, algorithm, edges, expected) => {
 	const input = edges.map((edge) => edge.slice()); // Deepcopy
-	const result = algorithm(edges, maxCardinality);
+	const result = algorithm(edges);
 	t.deepEqual(expected, result);
 	t.deepEqual(input, edges);
 };
 
-macro.title = (title, algorithm, edges, maxCardinality, expected) =>
+macro.title = (title, algorithm, edges, expected) =>
 	title ||
-	`${algorithm.name}(${JSON.stringify(
-		edges
-	)}, ${maxCardinality}) = ${JSON.stringify(expected)}`;
+	`${algorithm.name}(${JSON.stringify(edges)}) = ${JSON.stringify(expected)}`;
 
 const tests = {
 	// Empty input graph
@@ -40,17 +39,6 @@ const tests = {
 		expected: [-1, -1, 3, 2, -1]
 	},
 
-	// Maximum cardinality
-	test14_maxcard: {
-		edges: [
-			[1, 2, 5],
-			[2, 3, 11],
-			[3, 4, 5]
-		],
-		maxCardinality: true,
-		expected: [-1, 2, 1, 4, 3]
-	},
-
 	// Floating point weigths
 	test15_float: {
 		edges: [
@@ -71,20 +59,8 @@ const tests = {
 			[2, 4, -1],
 			[3, 4, -6]
 		],
-		maxCardinality: false,
 		expected: [-1, 2, 1, -1, -1]
 	},
-	test16_negative_maxCardinality: {
-		edges: [
-			[1, 2, 2],
-			[1, 3, -2],
-			[2, 3, 1],
-			[2, 4, -1],
-			[3, 4, -6]
-		],
-		maxCardinality: true,
-		expected: [-1, 3, 4, 1, 2]
-	},
 
 	// Create S-blossom and use it for augmentation
 	test20_sblossom_1: {
@@ -311,8 +287,15 @@ const tests = {
 	}
 };
 
-const algorithms = [blossom(true, true), blossom(false, false), blossom()];
+const btt = blossom(true, true);
+const bdflt = blossom();
+
+const algorithms = [
+	maximumMatching,
+	(edges) => btt(edges),
+	(edges) => bdflt(edges)
+];
 
 for (const [i, algorithm] of enumerate(algorithms))
-	for (const [key, {edges, maxCardinality, expected}] of Object.entries(tests))
-		test(`${key} ${i}`, macro, algorithm, edges, maxCardinality, expected);
+	for (const [key, {edges, expected}] of Object.entries(tests))
+		test(`${key} ${i}`, macro, algorithm, edges, expected);