♻️ refactor: Fix docs, sprinkle asserts.

The entire thing is now sort-of type-checked. `tsc` does not report any
errors.

Author: make-github-pseudonymous-again

src/adt/Leaf.js

@@ -1,14 +1,18 @@
+import assert from 'assert';
 import {BLACK} from '../color/BLACK.js';
+import {Node} from './Node.js';
 
 /**
  * A black leaf node.
  *
- * @constructor
+ * @class
  * @param {Node} parent - The parent node in the tree.
- * @returns {Leaf}
  */
 export function Leaf(parent) {
+	assert(parent instanceof Node);
+	/** @constant {number} The color of the node. */
 	this._color = BLACK;
+	/** @member {Node} The parent node. */
 	this.parent = parent;
 }
 

src/adt/Node.js

@@ -3,16 +3,20 @@ import {Leaf} from './Leaf.js';
 /**
  * An internal node. This node can be red or black.
  *
- * @constructor
- * @param {Number} color - The color of the node.
- * @param {Key} key - The key of the node.
- * @returns {Node}
+ * @class
+ * @param {number} color - The color of the node.
+ * @param {any} key - The key of the node.
  */
 export function Node(color, key) {
+	/** @member {number} The color of the node. */
 	this._color = color;
+	/** @member {Node|Leaf} The left child */
 	this.left = new Leaf(this);
+	/** @member {Node|Leaf} The right child */
 	this.right = new Leaf(this);
+	/** @member {Node} The parent node. */
 	this.parent = null;
+	/** @member {any} The key held by this node. */
 	this.key = key;
 }
 

src/adt/RedBlackTree.js

@@ -1,3 +1,4 @@
+import assert from 'assert';
 import {Node} from './Node.js';
 import {BLACK, RED} from '../color/index.js';
 import {predecessor} from '../family/predecessor.js';
@@ -15,10 +16,11 @@ export class RedBlackTree {
 	 * Constructs a new empty red-black tree.
 	 *
 	 * @param {Function} compare - The comparison function for node keys.
-	 * @returns {RedBlackTree}
 	 */
 	constructor(compare) {
+		/** @member {Function} The comparison function for node keys. */
 		this.compare = compare;
+		/** @member {Node} The root of the tree. */
 		this.root = null;
 	}
 
@@ -34,7 +36,7 @@ export class RedBlackTree {
 	/**
 	 * Adds a key to the tree.
 	 *
-	 * @param {Key} key - The key to add.
+	 * @param {any} key - The key to add.
 	 */
 	add(key) {
 		if (this.root === null) {
@@ -51,7 +53,7 @@ export class RedBlackTree {
 	 * Returns the first node whose key equals the input key.
 	 * If no such node exists, returns <code>null</code>.
 	 *
-	 * @param {Key} key - The input key.
+	 * @param {any} key - The input key.
 	 * @returns {Node}
 	 */
 	_search(key) {
@@ -64,8 +66,8 @@ export class RedBlackTree {
 	 * in this way (with {@link RedBlackTree#_search}. If no such key exists
 	 * in the tree, returns <code>null</code>.
 	 *
-	 * @param {Key} key - The input key.
-	 * @returns {Key}
+	 * @param {any} key - The input key.
+	 * @returns {any}
 	 */
 	get(key) {
 		const node = this._search(key);
@@ -76,7 +78,7 @@ export class RedBlackTree {
 	 * Returns <code>true</code> if and only if the tree contains the input
 	 * key.
 	 *
-	 * @param {Key} key - The input key.
+	 * @param {any} key - The input key.
 	 * @returns {Boolean}
 	 */
 	has(key) {
@@ -102,6 +104,7 @@ export class RedBlackTree {
 			// If there is no left child, then there can only be one right
 			// child.
 			const succ = node.right;
+			assert(succ instanceof Node);
 			node.key = succ.key;
 			// Delete successor node
 			// note: this node can only have one non-leaf child
@@ -120,7 +123,7 @@ export class RedBlackTree {
 	 * (with {@link RedBlackTree#_delete}). If such a node is found and deleted
 	 * then return <code>true</code>. Return <code>false</code> otherwise.
 	 *
-	 * @param {Key} key - The input key.
+	 * @param {any} key - The input key.
 	 * @returns {Boolean} - Whether the key existed in the tree before removal.
 	 */
 	remove(key) {
@@ -134,9 +137,9 @@ export class RedBlackTree {
 	/**
 	 * Returns an in order iterator over the keys of the tree that lie in the
 	 * interval [left, right[.
-	 * @param {Key} left - The left bound of the interval.
-	 * @param {Key} right - The right bound of the interval.
-	 * @returns {Iterator}
+	 * @param {any} left - The left bound of the interval.
+	 * @param {any} right - The right bound of the interval.
+	 * @returns {IterableIterator}
 	 */
 	*range(left, right) {
 		if (this.root !== null)
@@ -146,7 +149,7 @@ export class RedBlackTree {
 	/**
 	 * Returns an in order iterator over the keys of the tree.
 	 *
-	 * @returns {Iterator}
+	 * @returns {IterableIterator}
 	 */
 	*items() {
 		if (this.root !== null) yield* inordertraversal(this.root);
@@ -163,7 +166,7 @@ export class RedBlackTree {
 	 * Constructs a red-black tree from an input iterable.
 	 *
 	 * @param {Function} compare - The comparison function to use.
-	 * @param {Iterbale} iterable - The input iterable.
+	 * @param {Iterable} iterable - The input iterable.
 	 * @returns {RedBlackTree}
 	 */
 	static from(compare, iterable) {

src/debug/debug.js

@@ -1,3 +1,6 @@
+import assert from 'assert';
+import {Node} from '../adt/Node.js';
+import {Leaf} from '../adt/Leaf.js';
 import {BLACK} from '../color/BLACK.js';
 
 /**
@@ -11,11 +14,17 @@ export const _debug = ({red, black}) => {
 	 * Recursively constructs a prettyprint string for the red-black tree rooted at
 	 * <code>root</code>.
 	 *
-	 * @param {Node} root - The root of the tree.
+	 * @param {Node|Leaf} root - The root of the tree.
 	 * @returns {string}
 	 */
 	const debug = (root) => {
-		if (root.isLeaf()) return black('L');
+		assert(root instanceof Node || root instanceof Leaf);
+		if (root.isLeaf()) {
+			assert(root instanceof Leaf);
+			return black('L');
+		}
+
+		assert(root instanceof Node);
 
 		const repr = root._color === BLACK ? black(root.key) : red(root.key);
 

src/deletion/delete_case1.js

@@ -1,3 +1,7 @@
+import assert from 'assert';
+import {BLACK} from '../color/BLACK.js';
+import {Node} from '../adt/Node.js';
+import {Leaf} from '../adt/Leaf.js';
 import {delete_case2} from './delete_case2.js';
 
 /**
@@ -6,10 +10,13 @@ import {delete_case2} from './delete_case2.js';
  *   - all root-leaf paths going through n have a black height of b - 1
  *   - all other root-leaf paths have a black height of b
  *
- * @param {Node} n - The input node.
+ * @param {Node|Leaf} n - The input node.
  */
 export const delete_case1 = (n) => {
-	// If n is the root, there is nothing to do: all paths go through n, and n
-	// is black.
+	assert(n instanceof Node || n instanceof Leaf);
+	assert(n._color === BLACK);
+	// If n is the root, there is nothing to do:
+	//   - all paths go through n, and
+	//   - n is black.
 	if (n.parent !== null) delete_case2(n);
 };

src/deletion/delete_case2.js

@@ -1,4 +1,7 @@
+import assert from 'assert';
 import {BLACK, RED} from '../color/index.js';
+import {Node} from '../adt/Node.js';
+import {Leaf} from '../adt/Leaf.js';
 import {rotate_left, rotate_right} from '../rotate/index.js';
 import {sibling} from '../family/sibling.js';
 
@@ -12,9 +15,13 @@ import {delete_case4} from './delete_case4.js';
  *   - all other root-leaf paths have a black height of b
  *   - n is not the root
  *
- * @param {Node} n - The input node.
+ * @param {Node|Leaf} n - The input node.
  */
 export const delete_case2 = (n) => {
+	assert(n instanceof Node || n instanceof Leaf);
+	assert(n._color === BLACK);
+	assert(n.parent !== null);
+
 	const s = sibling(n);
 
 	/**

src/deletion/delete_case3.js

@@ -1,4 +1,7 @@
+import assert from 'assert';
 import {BLACK, RED} from '../color/index.js';
+import {Node} from '../adt/Node.js';
+import {Leaf} from '../adt/Leaf.js';
 import {sibling} from '../family/sibling.js';
 
 import {delete_case1} from './delete_case1.js';
@@ -12,10 +15,15 @@ import {delete_case4} from './delete_case4.js';
  *   - n is not the root
  *   - n's sibling is black
  *
- * @param {Node} n - The input node.
+ * @param {Node|Leaf} n - The input node.
  */
 export const delete_case3 = (n) => {
+	assert(n instanceof Node || n instanceof Leaf);
+	assert(n._color === BLACK);
+	assert(n.parent !== null);
 	const s = sibling(n);
+	assert(s instanceof Node);
+	assert(s._color === BLACK);
 
 	/**
 	 * If n's parent is black and n's sibling's children are black, then

src/deletion/delete_case4.js

@@ -1,4 +1,7 @@
+import assert from 'assert';
 import {BLACK, RED} from '../color/index.js';
+import {Node} from '../adt/Node.js';
+import {Leaf} from '../adt/Leaf.js';
 import {sibling} from '../family/sibling.js';
 
 import {delete_case5} from './delete_case5.js';
@@ -12,10 +15,18 @@ import {delete_case5} from './delete_case5.js';
  *   - n's sibling is black
  *   - n's parent and n's sibling's children cannot all be black
  *
- * @param {Node} n - The input node.
+ * @param {Node|Leaf} n - The input node.
  */
 export const delete_case4 = (n) => {
+	assert(n instanceof Node || n instanceof Leaf);
+	assert(n._color === BLACK);
+	assert(n.parent !== null);
 	const s = sibling(n);
+	assert(s instanceof Node);
+	assert(s._color === BLACK);
+	assert(
+		n.parent._color === RED || s.left._color === RED || s.right._color === RED,
+	);
 
 	/**
 	 * If n's parent is red and n's sibling's children are black, then swap n's

src/deletion/delete_case5.js

@@ -1,4 +1,7 @@
+import assert from 'assert';
 import {BLACK, RED} from '../color/index.js';
+import {Node} from '../adt/Node.js';
+import {Leaf} from '../adt/Leaf.js';
 import {rotate_left, rotate_right} from '../rotate/index.js';
 import {sibling} from '../family/sibling.js';
 
@@ -13,10 +16,16 @@ import {delete_case6} from './delete_case6.js';
  *   - n's sibling is black
  *   - at least one of n's sibling's children is red
  *
- * @param {Node} n - The input node.
+ * @param {Node|Leaf} n - The input node.
  */
 export const delete_case5 = (n) => {
+	assert(n instanceof Node || n instanceof Leaf);
+	assert(n._color === BLACK);
+	assert(n.parent !== null);
 	const s = sibling(n);
+	assert(s instanceof Node);
+	assert(s._color === BLACK);
+	assert(s.left._color === RED || s.right._color === RED);
 
 	// The following statements just force the red n's sibling child to be on
 	// the left of the left of the parent, or right of the right, so case 6

src/deletion/delete_case6.js

@@ -1,4 +1,8 @@
+import assert from 'assert';
 import {BLACK} from '../color/BLACK.js';
+import {RED} from '../color/RED.js';
+import {Node} from '../adt/Node.js';
+import {Leaf} from '../adt/Leaf.js';
 import {rotate_left, rotate_right} from '../rotate/index.js';
 import {sibling} from '../family/sibling.js';
 
@@ -12,10 +16,15 @@ import {sibling} from '../family/sibling.js';
  *   - if n is a left child, the right child of n's sibling is red
  *   - if n is a right child, the left child of n's sibling is red
  *
- * @param {Node} n - The input node.
+ * @param {Node|Leaf} n - The input node.
  */
 export const delete_case6 = (n) => {
+	assert(n instanceof Node || n instanceof Leaf);
+	assert(n._color === BLACK);
+	assert(n.parent !== null);
 	const s = sibling(n);
+	assert(s instanceof Node);
+	assert(s._color === BLACK);
 
 	/**
 	 * Increment the black height of all root-leaf paths going through n by
@@ -39,12 +48,14 @@ export const delete_case6 = (n) => {
 	n.parent._color = BLACK;
 
 	if (n === n.parent.left) {
+		assert(s.right._color === RED);
 		s.right._color = BLACK;
 		rotate_left(n.parent);
 	}
 
 	// Symmetric case
 	else {
+		assert(s.left._color === RED);
 		s.left._color = BLACK;
 		rotate_right(n.parent);
 	}

src/deletion/delete_one_child.js

@@ -1,4 +1,7 @@
+import assert from 'assert';
 import {BLACK, RED} from '../color/index.js';
+import {Node} from '../adt/Node.js';
+import {Leaf} from '../adt/Leaf.js';
 
 import {replace_node} from './replace_node.js';
 import {delete_case1} from './delete_case1.js';
@@ -9,16 +12,18 @@ import {delete_case1} from './delete_case1.js';
  * Precondition:
  *   - n has at most one non-leaf child.
  *   - if n has a non-leaf child, then it is its left child.
+ *   - hence, n's right child is a leaf
  *
  * @param {Node} n - The node to delete.
  */
 export const delete_one_child = (n) => {
-	// Precondition: n has at most one non-leaf child.
-	// assert( n.right.isLeaf() || n.left.isLeaf());
+	assert(n instanceof Node);
+	// Precondition: n's right child is a leaf.
+	// The right child of n is always a LEAF because either n is a subtree
+	// predecessor or it is the only child of its parent by the red-black tree
+	// properties
+	assert(n.right instanceof Leaf);
 
-	// const child = n.right.isLeaf() ? n.left : n.right;
-	// n.right is always a LEAF because either n is a subtree predecessor or it
-	// is the only child of its parent by the red-black tree properties
 	const child = n.left;
 
 	// Replace n with its left child
@@ -32,7 +37,9 @@ export const delete_one_child = (n) => {
 		// replace n with it.
 		if (child._color === RED) child._color = BLACK;
 		// Otherwise, there are more things to fix.
-		else delete_case1(child);
+		else {
+			delete_case1(child);
+		}
 	}
 
 	// Else {