🚴 perf(append): Avoid recording intermediate states.

This introduces more non-pure methods which can only be used with care.
Currently these are prefixed with _UNSAFE_ but maybe _NON_PURE_ would be
better?

The dev and user experience would certainly be better if we exploited
TypeScript types to ensure whatever is passed down to these methods is
marked as mutable (including `this`) and whatever comes out of the API
is immutable.

We could also expose these non-pure methods for special usage but with
extreme care. Maybe something like
`tree.mutable()._NON_PURE_push(x).immutable();` or
`tree.bulk((mutable) => mutable._NON_PURE_push(x));`. There are examples
on how to handle this in `funkia/list` and `immutable.js`. Is the
_NON_PURE_ prefix really necessary then?

The two previous points would allow and exploit the definition of a
`VolatileDeep` or `MutableDeep`, not sure on the name yet, whose right
and/or left digit is mutable ("or" because we could also settle on
`PushableDeep` and `ConsableDeep`). This would allow to replace digits
with either specialized mutable digit objects OR with JavaScript
Arrays depending on which solution is faster (member assignment + class
method table or Array push + switch on Array length).

Author: make-github-pseudonymous-again

src/0-core/_fast/_fill_right.js

@@ -47,7 +47,7 @@ export default function _fill_right(M, left, middle, x1, iterator) {
 
 		event = iterator.next();
 		if (event.done) return new Deep(M, left, middle, new Three(x1, x2, x3));
-		middle = middle.push(node3(M, x1, x2, x3));
+		middle = middle._UNSAFE_push(node3(M, x1, x2, x3));
 		x1 = event.value;
 	}
 }

src/1-digit/1-One.js

@@ -2,6 +2,7 @@ import assert from 'assert';
 import {node2, node3} from '../2-node/index.js';
 import {DigitSplit} from '../0-core/split/DigitSplit.js';
 import {Single} from '../3-tree/implementations/1-Single.js';
+import {Deep} from '../3-tree/implementations/2-Deep.js';
 import {Digit, Two, Three, Four} from './index.js';
 
 export function One(a) {
@@ -184,3 +185,14 @@ One.prototype._nodes_with_list_and_four = function (M, list, other) {
 One.prototype._list = function () {
 	return [this.a];
 };
+
+One.prototype._isolated_push = function (parent, value) {
+	assert(parent._right === this);
+	return new Deep(parent.M, parent._left, parent._middle, this.push(value));
+};
+
+One.prototype._UNSAFE_push = function (parent, value) {
+	assert(parent._right === this);
+	parent._right = this.push(value);
+	return parent;
+};

src/1-digit/2-Two.js

@@ -207,3 +207,14 @@ Two.prototype._nodes_with_list_and_four = function (M, list, other) {
 Two.prototype._list = function () {
 	return [this.a, this.b];
 };
+
+Two.prototype._isolated_push = function (parent, value) {
+	assert(parent._right === this);
+	return new Deep(parent.M, parent._left, parent._middle, this.push(value));
+};
+
+Two.prototype._UNSAFE_push = function (parent, value) {
+	assert(parent._right === this);
+	parent._right = this.push(value);
+	return parent;
+};

src/1-digit/3-Three.js

@@ -219,3 +219,17 @@ Three.prototype._nodes_with_list_and_four = function (M, list, other) {
 Three.prototype._list = function () {
 	return [this.a, this.b, this.c];
 };
+
+Three.prototype._isolated_push = function (parent, value) {
+	assert(parent._right === this);
+	return new Deep(parent.M, parent._left, parent._middle, this.push(value));
+};
+
+Three.prototype._UNSAFE_push = function (parent, value) {
+	assert(parent._right === this);
+	parent._middle = parent._middle._UNSAFE_push(this._node(parent.M));
+	// NOTE the following is dangerous if alternating push and init
+	parent._right = new One(value);
+	// TODO maybe final output can be fixed
+	return parent;
+};

src/1-digit/4-Four.js

@@ -251,3 +251,20 @@ Four.prototype._nodes_with_list_and_four = function (M, list, other) {
 Four.prototype._list = function () {
 	return [this.a, this.b, this.c, this.d];
 };
+
+Four.prototype._isolated_push = function (parent, value) {
+	assert(parent._right === this);
+	return new Deep(
+		parent.M,
+		parent._left,
+		parent._middle.push(this.init()._node(parent.M)),
+		new Two(this.last(), value),
+	);
+};
+
+Four.prototype._UNSAFE_push = function (parent, value) {
+	assert(parent._right === this);
+	parent._middle = parent._middle._UNSAFE_push(this.init()._node(parent.M));
+	parent._right = new Two(this.last(), value);
+	return parent;
+};

src/3-tree/implementations/0-Empty.js

@@ -38,9 +38,11 @@ Empty.prototype.init = function () {
 	return this;
 };
 
-Empty.prototype.push = function (value) {
-	return new Single(this.M, value);
-};
+Empty.prototype._UNSAFE_push =
+	// eslint-disable-next-line no-multi-assign
+	Empty.prototype.push = function (value) {
+		return new Single(this.M, value);
+	};
 
 Empty.prototype.cons = function (value) {
 	return new Single(this.M, value);
@@ -72,6 +74,10 @@ Empty.prototype.split = function (_p) {
 	return [this, this];
 };
 
+Empty.prototype._copy_spine = function () {
+	return this;
+};
+
 Empty.prototype._concat_with_deep = function (other) {
 	assert(other instanceof Deep);
 	assert(isSameMeasure(other.M, this.M));

src/3-tree/implementations/1-Single.js

@@ -49,14 +49,16 @@ Single.prototype.cons = function (value) {
 	);
 };
 
-Single.prototype.push = function (value) {
-	return new Deep(
-		this.M,
-		new One(this.a),
-		new Empty(cache(this.M)),
-		new One(value),
-	);
-};
+Single.prototype._UNSAFE_push =
+	// eslint-disable-next-line no-multi-assign
+	Single.prototype.push = function (value) {
+		return new Deep(
+			this.M,
+			new One(this.a),
+			new Empty(cache(this.M)),
+			new One(value),
+		);
+	};
 
 Single.prototype.append = function (iterable) {
 	const it = iterable[Symbol.iterator]();
@@ -95,6 +97,10 @@ Single.prototype.split = function (p) {
 		: [this, new Empty(this.M)];
 };
 
+Single.prototype._copy_spine = function () {
+	return this;
+};
+
 Single.prototype._concat_with_deep = function (other) {
 	assert(other instanceof Deep);
 	assert(isSameMeasure(other.M, this.M));

src/3-tree/implementations/2-Deep.js

@@ -112,16 +112,11 @@ Deep.prototype.cons = function (value) {
 };
 
 Deep.prototype.push = function (value) {
-	if (this._right instanceof Four) {
-		return new Deep(
-			this.M,
-			this._left,
-			this._middle.push(this._right.init()._node(this.M)),
-			new Two(this._right.last(), value),
-		);
-	}
+	return this._right._isolated_push(this, value);
+};
 
-	return new Deep(this.M, this._left, this._middle, this._right.push(value));
+Deep.prototype._UNSAFE_push = function (value) {
+	return this._right._UNSAFE_push(this, value);
 };
 
 Deep.prototype.append = function (iterable) {
@@ -139,7 +134,9 @@ Deep.prototype.append = function (iterable) {
 	const middle = _append_small_list(
 		this._middle,
 		this._right._nodes(this.M, new One(a)),
-	);
+	)._copy_spine();
+	// TODO _copy_spine should return a MutableDeep type on the spine
+	// TODO then _fill_right should only accept Empty, Single, or MutableDeep
 
 	return _fill_right(this.M, this._left, middle, b, it);
 };
@@ -225,6 +222,10 @@ Deep.prototype._concat_with_deep = function (other) {
 	);
 };
 
+Deep.prototype._copy_spine = function () {
+	return new Deep(this.M, this._left, this._middle._copy_spine(), this._right);
+};
+
 Deep.prototype._app3 = function (list, other) {
 	assert(other instanceof Tree);
 	return other._app3_with_deep(list, this);

src/4-lazy/0-Lazy.js

@@ -40,6 +40,10 @@ Lazy.prototype.push = function (value) {
 	return this._force().push(value);
 };
 
+Lazy.prototype._UNSAFE_push = function (value) {
+	return this._force()._UNSAFE_push(value);
+};
+
 Lazy.prototype.tail = function () {
 	return this._force().tail();
 };