🎨 refactor: Use flat export style and improve documentation.

Author: make-github-pseudonymous-again

src/api/decide.js

@@ -1,5 +1,20 @@
-import {solve} from './solve.js';
+import assert from 'assert';
+import ParitiesInstance from '../core/convert/ParitiesInstance.js';
+import SignsInstance from '../core/convert/SignsInstance.js';
+import KeysInstance from '../core/convert/KeysInstance.js';
+import solve from './solve.js';
 
-export function decide(instance) {
+/**
+ * Decide whether the given instance has a satisfying assignment.
+ *
+ * @param {ParitiesInstance|SignsInstance|KeysInstance} instance
+ * @return {boolean} Whether the instance has a satisfying assignment.
+ */
+export default function decide(instance) {
+	assert(
+		instance instanceof ParitiesInstance ||
+			instance instanceof SignsInstance ||
+			instance instanceof KeysInstance,
+	);
 	return !solve(instance).next().done;
 }

src/api/from.js

@@ -1,36 +1,50 @@
-import {
-	ParitiesInstance,
-	_sign_to_parity,
-	_keys_to_parity,
-	_parse_DIMACS_CNF,
-} from '../core/index.js';
+import ParitiesInstance from '../core/convert/ParitiesInstance.js';
+import _sign_to_parity from '../core/convert/_sign_to_parity.js';
+import _keys_to_parity from '../core/convert/_keys_to_parity.js';
+import _parse_DIMACS_CNF from '../core/parse/_parse_DIMACS_CNF.js';
 
 /**
  * The input is converted to parity format in each case.
  */
-export const from = {
+const from = {
 	/**
 	 * The input is in parity format where variables are given integer labels
 	 * 0 to n-1, a positive literal is represented by the double of its
 	 * variable's label, and a negative literal is represented by the successor
 	 * of the double of its variable's label.
+	 *
+	 * @param {number[][]} clauses The clauses in parity format.
+	 * @return {ParitiesInstance}
 	 */
 	parities: (clauses) => new ParitiesInstance(clauses),
 	/**
 	 * The input is in signs format where variables are given integer labels
 	 * 1 to n, a positive literal is represented by its variable's label, and a
 	 * negative literal is represented by the opposite of its variable's label.
+	 *
+	 * @function
+	 * @param {number[][]} clauses
+	 * @return {SignsInstance}
 	 */
 	signs: _sign_to_parity,
 	/**
 	 * The input is in keys format where variables are given arbitrary object labels,
 	 * a literal is represented by a pair from the set {true, false} x
 	 * labels, where the first item in the pair is true if the literal is positive,
 	 * and false otherwise.
+	 *
+	 * @function
+	 * @param {[any,any][][]} clauses
+	 * @return {KeysInstance}
 	 */
 	keys: _keys_to_parity,
 	/**
 	 * Parses a character iterable in DIMACS CNF format.
+	 *
+	 * @param {Iterable<string>} iterable
+	 * @return {ParitiesInstance}
 	 */
 	dcnf: (iterable) => new ParitiesInstance(_parse_DIMACS_CNF(iterable)),
 };
+
+export default from;

src/api/index.js

@@ -1,11 +1,14 @@
-import {SAT0W, setup_watchlist, setup_assignment} from '../core/index.js';
+import setup_assignment from '../core/setup_assignment.js';
+import setup_watchlist from '../core/SAT0W/setup_watchlist.js';
+import SAT0W from '../core/SAT0W/SAT0W.js';
 
 /**
  * Yields all satisfying assignments for the input instance.
  *
- * @returns {Iterable} Generator of the satisfying assignments.
+ * @param {ParitiesInstance|SignsInstance|KeysInstance} instance
+ * @returns {IterableIterator<number[]>} Generator of the satisfying assignments.
  */
-export function* solve({clauses, n}) {
+export default function solve({clauses, n}) {
 	// eslint-disable-next-line new-cap
-	yield* SAT0W(n, clauses, setup_watchlist(n, clauses), setup_assignment(n), 0);
+	return SAT0W(n, clauses, setup_watchlist(n, clauses), setup_assignment(n), 0);
 }

src/api/solve.js

@@ -1,2 +1,3 @@
-import {_verify} from '../core/index.js';
-export const verify = ({clauses}, certificate) => _verify(clauses, certificate);
+import _verify from '../core/_verify.js';
+const verify = ({clauses}, certificate) => _verify(clauses, certificate);
+export default verify;

src/api/verify.js

@@ -1,11 +1,20 @@
-import {update_watchlist} from './update_watchlist.js';
+import update_watchlist from './update_watchlist.js';
 
-export function* SAT0W(n, clauses, watchlist, assignment, d) {
-	/**
-	 * Recursively solve SAT by assigning to variables d, d+1, ..., n-1. Assumes
-	 * variables 0, ..., d-1 are assigned so far. A generator for all the
-	 * satisfying assignments is returned.
-	 */
+/**
+ * SAT0W.
+ *
+ * Recursively solve SAT by assigning to variables d, d+1, ..., n-1. Assumes
+ * variables 0, ..., d-1 are assigned so far. A generator for all the
+ * satisfying assignments is returned.
+ *
+ * @param {number} n
+ * @param {number[][]} clauses
+ * @param {number[][][]} watchlist
+ * @param {number[]} assignment
+ * @param {number} d
+ * @return {IterableIterator<number[]>} Yields satisfying assignments.
+ */
+export default function* SAT0W(n, clauses, watchlist, assignment, d) {
 	if (d === n) {
 		yield assignment;
 		return;

src/core/SAT0W/SAT0W.js

@@ -1,4 +1,11 @@
-export function setup_watchlist(n, clauses) {
+/**
+ * Setup_watchlist.
+ *
+ * @param {number} n
+ * @param {number[][]} clauses
+ * @return {number[][][]} The literal watch list.
+ */
+export default function setup_watchlist(n, clauses) {
 	const watchlist = [];
 
 	for (let i = 0; i < 2 * n; ++i) watchlist.push([]);

src/core/SAT0W/index.js

@@ -1,10 +1,14 @@
-export function update_watchlist(watchlist, false_literal, assignment) {
-	/**
-	 * Updates the watch list after literal 'false_literal' was just assigned
-	 * False, by making any clause watching false_literal watch something else.
-	 * Returns False it is impossible to do so, meaning a clause is contradicted
-	 * by the current assignment.
-	 */
+/**
+ * Updates the watch list after literal 'false_literal' was just assigned
+ * False, by making any clause watching false_literal watch something else.
+ * Returns False it is impossible to do so, meaning a clause is contradicted
+ * by the current assignment.
+ *
+ * @param {number[][][]} watchlist
+ * @param {number} false_literal
+ * @param {number[]} assignment
+ */
+export default function update_watchlist(watchlist, false_literal, assignment) {
 	while (watchlist[false_literal].length > 0) {
 		const clause =
 			watchlist[false_literal][watchlist[false_literal].length - 1];

src/core/SAT0W/setup_watchlist.js

@@ -8,7 +8,7 @@
  * @returns {Boolean} Whether the assignment satisfies the k-CNF formula
  * represented by the list of clauses.
  */
-export function _verify(clauses, assignment) {
+export default function _verify(clauses, assignment) {
 	// eslint-disable-next-line no-labels
 	loop: for (const clause of clauses) {
 		for (const literal of clause) {