sorted-btree
Version:
A sorted list of key-value pairs in a fast, typed in-memory B+ tree with a powerful API.
954 lines • 84.1 kB
JavaScript
"use strict";
var __extends = (this && this.__extends) || (function () {
var extendStatics = function (d, b) {
extendStatics = Object.setPrototypeOf ||
({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
return extendStatics(d, b);
};
return function (d, b) {
if (typeof b !== "function" && b !== null)
throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
extendStatics(d, b);
function __() { this.constructor = d; }
d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
};
})();
Object.defineProperty(exports, "__esModule", { value: true });
exports.EmptyBTree = exports.asSet = exports.simpleComparator = exports.defaultComparator = void 0;
/**
* Compares DefaultComparables to form a strict partial ordering.
*
* Handles +/-0 and NaN like Map: NaN is equal to NaN, and -0 is equal to +0.
*
* Arrays are compared using '<' and '>', which may cause unexpected equality:
* for example [1] will be considered equal to ['1'].
*
* Two objects with equal valueOf compare the same, but compare unequal to
* primitives that have the same value.
*/
function defaultComparator(a, b) {
// Special case finite numbers first for performance.
// Note that the trick of using 'a - b' and checking for NaN to detect non-numbers
// does not work if the strings are numeric (ex: "5"). This would leading most
// comparison functions using that approach to fail to have transitivity.
if (Number.isFinite(a) && Number.isFinite(b)) {
return a - b;
}
// The default < and > operators are not totally ordered. To allow types to be mixed
// in a single collection, compare types and order values of different types by type.
var ta = typeof a;
var tb = typeof b;
if (ta !== tb) {
return ta < tb ? -1 : 1;
}
if (ta === 'object') {
// standardized JavaScript bug: null is not an object, but typeof says it is
if (a === null)
return b === null ? 0 : -1;
else if (b === null)
return 1;
a = a.valueOf();
b = b.valueOf();
ta = typeof a;
tb = typeof b;
// Deal with the two valueOf()s producing different types
if (ta !== tb) {
return ta < tb ? -1 : 1;
}
}
// a and b are now the same type, and will be a number, string or array
// (which we assume holds numbers or strings), or something unsupported.
if (a < b)
return -1;
if (a > b)
return 1;
if (a === b)
return 0;
// Order NaN less than other numbers
if (Number.isNaN(a))
return Number.isNaN(b) ? 0 : -1;
else if (Number.isNaN(b))
return 1;
// This could be two objects (e.g. [7] and ['7']) that aren't ordered
return Array.isArray(a) ? 0 : Number.NaN;
}
exports.defaultComparator = defaultComparator;
;
function simpleComparator(a, b) {
return a > b ? 1 : a < b ? -1 : 0;
}
exports.simpleComparator = simpleComparator;
;
/**
* A reasonably fast collection of key-value pairs with a powerful API.
* Largely compatible with the standard Map. BTree is a B+ tree data structure,
* so the collection is sorted by key.
*
* B+ trees tend to use memory more efficiently than hashtables such as the
* standard Map, especially when the collection contains a large number of
* items. However, maintaining the sort order makes them modestly slower:
* O(log size) rather than O(1). This B+ tree implementation supports O(1)
* fast cloning. It also supports freeze(), which can be used to ensure that
* a BTree is not changed accidentally.
*
* Confusingly, the ES6 Map.forEach(c) method calls c(value,key) instead of
* c(key,value), in contrast to other methods such as set() and entries()
* which put the key first. I can only assume that the order was reversed on
* the theory that users would usually want to examine values and ignore keys.
* BTree's forEach() therefore works the same way, but a second method
* `.forEachPair((key,value)=>{...})` is provided which sends you the key
* first and the value second; this method is slightly faster because it is
* the "native" for-each method for this class.
*
* Out of the box, BTree supports keys that are numbers, strings, arrays of
* numbers/strings, Date, and objects that have a valueOf() method returning a
* number or string. Other data types, such as arrays of Date or custom
* objects, require a custom comparator, which you must pass as the second
* argument to the constructor (the first argument is an optional list of
* initial items). Symbols cannot be used as keys because they are unordered
* (one Symbol is never "greater" or "less" than another).
*
* @example
* Given a {name: string, age: number} object, you can create a tree sorted by
* name and then by age like this:
*
* var tree = new BTree(undefined, (a, b) => {
* if (a.name > b.name)
* return 1; // Return a number >0 when a > b
* else if (a.name < b.name)
* return -1; // Return a number <0 when a < b
* else // names are equal (or incomparable)
* return a.age - b.age; // Return >0 when a.age > b.age
* });
*
* tree.set({name:"Bill", age:17}, "happy");
* tree.set({name:"Fran", age:40}, "busy & stressed");
* tree.set({name:"Bill", age:55}, "recently laid off");
* tree.forEachPair((k, v) => {
* console.log(`Name: ${k.name} Age: ${k.age} Status: ${v}`);
* });
*
* @description
* The "range" methods (`forEach, forRange, editRange`) will return the number
* of elements that were scanned. In addition, the callback can return {break:R}
* to stop early and return R from the outer function.
*
* - TODO: Test performance of preallocating values array at max size
* - TODO: Add fast initialization when a sorted array is provided to constructor
*
* For more documentation see https://github.com/qwertie/btree-typescript
*
* Are you a C# developer? You might like the similar data structures I made for C#:
* BDictionary, BList, etc. See http://core.loyc.net/collections/
*
* @author David Piepgrass
*/
var BTree = /** @class */ (function () {
/**
* Initializes an empty B+ tree.
* @param compare Custom function to compare pairs of elements in the tree.
* If not specified, defaultComparator will be used which is valid as long as K extends DefaultComparable.
* @param entries A set of key-value pairs to initialize the tree
* @param maxNodeSize Branching factor (maximum items or children per node)
* Must be in range 4..256. If undefined or <4 then default is used; if >256 then 256.
*/
function BTree(entries, compare, maxNodeSize) {
this._root = EmptyLeaf;
this._size = 0;
this._maxNodeSize = maxNodeSize >= 4 ? Math.min(maxNodeSize, 256) : 32;
this._compare = compare || defaultComparator;
if (entries)
this.setPairs(entries);
}
Object.defineProperty(BTree.prototype, "size", {
/////////////////////////////////////////////////////////////////////////////
// ES6 Map<K,V> methods /////////////////////////////////////////////////////
/** Gets the number of key-value pairs in the tree. */
get: function () { return this._size; },
enumerable: false,
configurable: true
});
Object.defineProperty(BTree.prototype, "length", {
/** Gets the number of key-value pairs in the tree. */
get: function () { return this._size; },
enumerable: false,
configurable: true
});
Object.defineProperty(BTree.prototype, "isEmpty", {
/** Returns true iff the tree contains no key-value pairs. */
get: function () { return this._size === 0; },
enumerable: false,
configurable: true
});
/** Releases the tree so that its size is 0. */
BTree.prototype.clear = function () {
this._root = EmptyLeaf;
this._size = 0;
};
/** Runs a function for each key-value pair, in order from smallest to
* largest key. For compatibility with ES6 Map, the argument order to
* the callback is backwards: value first, then key. Call forEachPair
* instead to receive the key as the first argument.
* @param thisArg If provided, this parameter is assigned as the `this`
* value for each callback.
* @returns the number of values that were sent to the callback,
* or the R value if the callback returned {break:R}. */
BTree.prototype.forEach = function (callback, thisArg) {
var _this = this;
if (thisArg !== undefined)
callback = callback.bind(thisArg);
return this.forEachPair(function (k, v) { return callback(v, k, _this); });
};
/** Runs a function for each key-value pair, in order from smallest to
* largest key. The callback can return {break:R} (where R is any value
* except undefined) to stop immediately and return R from forEachPair.
* @param onFound A function that is called for each key-value pair. This
* function can return {break:R} to stop early with result R.
* The reason that you must return {break:R} instead of simply R
* itself is for consistency with editRange(), which allows
* multiple actions, not just breaking.
* @param initialCounter This is the value of the third argument of
* `onFound` the first time it is called. The counter increases
* by one each time `onFound` is called. Default value: 0
* @returns the number of pairs sent to the callback (plus initialCounter,
* if you provided one). If the callback returned {break:R} then
* the R value is returned instead. */
BTree.prototype.forEachPair = function (callback, initialCounter) {
var low = this.minKey(), high = this.maxKey();
return this.forRange(low, high, true, callback, initialCounter);
};
/**
* Finds a pair in the tree and returns the associated value.
* @param defaultValue a value to return if the key was not found.
* @returns the value, or defaultValue if the key was not found.
* @description Computational complexity: O(log size)
*/
BTree.prototype.get = function (key, defaultValue) {
return this._root.get(key, defaultValue, this);
};
/**
* Adds or overwrites a key-value pair in the B+ tree.
* @param key the key is used to determine the sort order of
* data in the tree.
* @param value data to associate with the key (optional)
* @param overwrite Whether to overwrite an existing key-value pair
* (default: true). If this is false and there is an existing
* key-value pair then this method has no effect.
* @returns true if a new key-value pair was added.
* @description Computational complexity: O(log size)
* Note: when overwriting a previous entry, the key is updated
* as well as the value. This has no effect unless the new key
* has data that does not affect its sort order.
*/
BTree.prototype.set = function (key, value, overwrite) {
if (this._root.isShared)
this._root = this._root.clone();
var result = this._root.set(key, value, overwrite, this);
if (result === true || result === false)
return result;
// Root node has split, so create a new root node.
this._root = new BNodeInternal([this._root, result]);
return true;
};
/**
* Returns true if the key exists in the B+ tree, false if not.
* Use get() for best performance; use has() if you need to
* distinguish between "undefined value" and "key not present".
* @param key Key to detect
* @description Computational complexity: O(log size)
*/
BTree.prototype.has = function (key) {
return this.forRange(key, key, true, undefined) !== 0;
};
/**
* Removes a single key-value pair from the B+ tree.
* @param key Key to find
* @returns true if a pair was found and removed, false otherwise.
* @description Computational complexity: O(log size)
*/
BTree.prototype.delete = function (key) {
return this.editRange(key, key, true, DeleteRange) !== 0;
};
BTree.prototype.with = function (key, value, overwrite) {
var nu = this.clone();
return nu.set(key, value, overwrite) || overwrite ? nu : this;
};
/** Returns a copy of the tree with the specified key-value pairs set. */
BTree.prototype.withPairs = function (pairs, overwrite) {
var nu = this.clone();
return nu.setPairs(pairs, overwrite) !== 0 || overwrite ? nu : this;
};
/** Returns a copy of the tree with the specified keys present.
* @param keys The keys to add. If a key is already present in the tree,
* neither the existing key nor the existing value is modified.
* @param returnThisIfUnchanged if true, returns this if all keys already
* existed. Performance note: due to the architecture of this class, all
* node(s) leading to existing keys are cloned even if the collection is
* ultimately unchanged.
*/
BTree.prototype.withKeys = function (keys, returnThisIfUnchanged) {
var nu = this.clone(), changed = false;
for (var i = 0; i < keys.length; i++)
changed = nu.set(keys[i], undefined, false) || changed;
return returnThisIfUnchanged && !changed ? this : nu;
};
/** Returns a copy of the tree with the specified key removed.
* @param returnThisIfUnchanged if true, returns this if the key didn't exist.
* Performance note: due to the architecture of this class, node(s) leading
* to where the key would have been stored are cloned even when the key
* turns out not to exist and the collection is unchanged.
*/
BTree.prototype.without = function (key, returnThisIfUnchanged) {
return this.withoutRange(key, key, true, returnThisIfUnchanged);
};
/** Returns a copy of the tree with the specified keys removed.
* @param returnThisIfUnchanged if true, returns this if none of the keys
* existed. Performance note: due to the architecture of this class,
* node(s) leading to where the key would have been stored are cloned
* even when the key turns out not to exist.
*/
BTree.prototype.withoutKeys = function (keys, returnThisIfUnchanged) {
var nu = this.clone();
return nu.deleteKeys(keys) || !returnThisIfUnchanged ? nu : this;
};
/** Returns a copy of the tree with the specified range of keys removed. */
BTree.prototype.withoutRange = function (low, high, includeHigh, returnThisIfUnchanged) {
var nu = this.clone();
if (nu.deleteRange(low, high, includeHigh) === 0 && returnThisIfUnchanged)
return this;
return nu;
};
/** Returns a copy of the tree with pairs removed whenever the callback
* function returns false. `where()` is a synonym for this method. */
BTree.prototype.filter = function (callback, returnThisIfUnchanged) {
var nu = this.greedyClone();
var del;
nu.editAll(function (k, v, i) {
if (!callback(k, v, i))
return del = Delete;
});
if (!del && returnThisIfUnchanged)
return this;
return nu;
};
/** Returns a copy of the tree with all values altered by a callback function. */
BTree.prototype.mapValues = function (callback) {
var tmp = {};
var nu = this.greedyClone();
nu.editAll(function (k, v, i) {
return tmp.value = callback(v, k, i), tmp;
});
return nu;
};
BTree.prototype.reduce = function (callback, initialValue) {
var i = 0, p = initialValue;
var it = this.entries(this.minKey(), ReusedArray), next;
while (!(next = it.next()).done)
p = callback(p, next.value, i++, this);
return p;
};
/////////////////////////////////////////////////////////////////////////////
// Iterator methods /////////////////////////////////////////////////////////
/** Returns an iterator that provides items in order (ascending order if
* the collection's comparator uses ascending order, as is the default.)
* @param lowestKey First key to be iterated, or undefined to start at
* minKey(). If the specified key doesn't exist then iteration
* starts at the next higher key (according to the comparator).
* @param reusedArray Optional array used repeatedly to store key-value
* pairs, to avoid creating a new array on every iteration.
*/
BTree.prototype.entries = function (lowestKey, reusedArray) {
var info = this.findPath(lowestKey);
if (info === undefined)
return iterator();
var nodequeue = info.nodequeue, nodeindex = info.nodeindex, leaf = info.leaf;
var state = reusedArray !== undefined ? 1 : 0;
var i = (lowestKey === undefined ? -1 : leaf.indexOf(lowestKey, 0, this._compare) - 1);
return iterator(function () {
jump: for (;;) {
switch (state) {
case 0:
if (++i < leaf.keys.length)
return { done: false, value: [leaf.keys[i], leaf.values[i]] };
state = 2;
continue;
case 1:
if (++i < leaf.keys.length) {
reusedArray[0] = leaf.keys[i], reusedArray[1] = leaf.values[i];
return { done: false, value: reusedArray };
}
state = 2;
case 2:
// Advance to the next leaf node
for (var level = -1;;) {
if (++level >= nodequeue.length) {
state = 3;
continue jump;
}
if (++nodeindex[level] < nodequeue[level].length)
break;
}
for (; level > 0; level--) {
nodequeue[level - 1] = nodequeue[level][nodeindex[level]].children;
nodeindex[level - 1] = 0;
}
leaf = nodequeue[0][nodeindex[0]];
i = -1;
state = reusedArray !== undefined ? 1 : 0;
continue;
case 3:
return { done: true, value: undefined };
}
}
});
};
/** Returns an iterator that provides items in reversed order.
* @param highestKey Key at which to start iterating, or undefined to
* start at maxKey(). If the specified key doesn't exist then iteration
* starts at the next lower key (according to the comparator).
* @param reusedArray Optional array used repeatedly to store key-value
* pairs, to avoid creating a new array on every iteration.
* @param skipHighest Iff this flag is true and the highestKey exists in the
* collection, the pair matching highestKey is skipped, not iterated.
*/
BTree.prototype.entriesReversed = function (highestKey, reusedArray, skipHighest) {
if (highestKey === undefined) {
highestKey = this.maxKey();
skipHighest = undefined;
if (highestKey === undefined)
return iterator(); // collection is empty
}
var _a = this.findPath(highestKey) || this.findPath(this.maxKey()), nodequeue = _a.nodequeue, nodeindex = _a.nodeindex, leaf = _a.leaf;
check(!nodequeue[0] || leaf === nodequeue[0][nodeindex[0]], "wat!");
var i = leaf.indexOf(highestKey, 0, this._compare);
if (!skipHighest && i < leaf.keys.length && this._compare(leaf.keys[i], highestKey) <= 0)
i++;
var state = reusedArray !== undefined ? 1 : 0;
return iterator(function () {
jump: for (;;) {
switch (state) {
case 0:
if (--i >= 0)
return { done: false, value: [leaf.keys[i], leaf.values[i]] };
state = 2;
continue;
case 1:
if (--i >= 0) {
reusedArray[0] = leaf.keys[i], reusedArray[1] = leaf.values[i];
return { done: false, value: reusedArray };
}
state = 2;
case 2:
// Advance to the next leaf node
for (var level = -1;;) {
if (++level >= nodequeue.length) {
state = 3;
continue jump;
}
if (--nodeindex[level] >= 0)
break;
}
for (; level > 0; level--) {
nodequeue[level - 1] = nodequeue[level][nodeindex[level]].children;
nodeindex[level - 1] = nodequeue[level - 1].length - 1;
}
leaf = nodequeue[0][nodeindex[0]];
i = leaf.keys.length;
state = reusedArray !== undefined ? 1 : 0;
continue;
case 3:
return { done: true, value: undefined };
}
}
});
};
/* Used by entries() and entriesReversed() to prepare to start iterating.
* It develops a "node queue" for each non-leaf level of the tree.
* Levels are numbered "bottom-up" so that level 0 is a list of leaf
* nodes from a low-level non-leaf node. The queue at a given level L
* consists of nodequeue[L] which is the children of a BNodeInternal,
* and nodeindex[L], the current index within that child list, such
* such that nodequeue[L-1] === nodequeue[L][nodeindex[L]].children.
* (However inside this function the order is reversed.)
*/
BTree.prototype.findPath = function (key) {
var nextnode = this._root;
var nodequeue, nodeindex;
if (nextnode.isLeaf) {
nodequeue = EmptyArray, nodeindex = EmptyArray; // avoid allocations
}
else {
nodequeue = [], nodeindex = [];
for (var d = 0; !nextnode.isLeaf; d++) {
nodequeue[d] = nextnode.children;
nodeindex[d] = key === undefined ? 0 : nextnode.indexOf(key, 0, this._compare);
if (nodeindex[d] >= nodequeue[d].length)
return; // first key > maxKey()
nextnode = nodequeue[d][nodeindex[d]];
}
nodequeue.reverse();
nodeindex.reverse();
}
return { nodequeue: nodequeue, nodeindex: nodeindex, leaf: nextnode };
};
/**
* Computes the differences between `this` and `other`.
* For efficiency, the diff is returned via invocations of supplied handlers.
* The computation is optimized for the case in which the two trees have large amounts
* of shared data (obtained by calling the `clone` or `with` APIs) and will avoid
* any iteration of shared state.
* The handlers can cause computation to early exit by returning {break: R}.
* Neither of the collections should be changed during the comparison process (in your callbacks), as this method assumes they will not be mutated.
* @param other The tree to compute a diff against.
* @param onlyThis Callback invoked for all keys only present in `this`.
* @param onlyOther Callback invoked for all keys only present in `other`.
* @param different Callback invoked for all keys with differing values.
*/
BTree.prototype.diffAgainst = function (other, onlyThis, onlyOther, different) {
if (other._compare !== this._compare) {
throw new Error("Tree comparators are not the same.");
}
if (this.isEmpty || other.isEmpty) {
if (this.isEmpty && other.isEmpty)
return undefined;
// If one tree is empty, everything will be an onlyThis/onlyOther.
if (this.isEmpty)
return onlyOther === undefined ? undefined : BTree.stepToEnd(BTree.makeDiffCursor(other), onlyOther);
return onlyThis === undefined ? undefined : BTree.stepToEnd(BTree.makeDiffCursor(this), onlyThis);
}
// Cursor-based diff algorithm is as follows:
// - Until neither cursor has navigated to the end of the tree, do the following:
// - If the `this` cursor is "behind" the `other` cursor (strictly <, via compare), advance it.
// - Otherwise, advance the `other` cursor.
// - Any time a cursor is stepped, perform the following:
// - If either cursor points to a key/value pair:
// - If thisCursor === otherCursor and the values differ, it is a Different.
// - If thisCursor > otherCursor and otherCursor is at a key/value pair, it is an OnlyOther.
// - If thisCursor < otherCursor and thisCursor is at a key/value pair, it is an OnlyThis as long as the most recent
// cursor step was *not* otherCursor advancing from a tie. The extra condition avoids erroneous OnlyOther calls
// that would occur due to otherCursor being the "leader".
// - Otherwise, if both cursors point to nodes, compare them. If they are equal by reference (shared), skip
// both cursors to the next node in the walk.
// - Once one cursor has finished stepping, any remaining steps (if any) are taken and key/value pairs are logged
// as OnlyOther (if otherCursor is stepping) or OnlyThis (if thisCursor is stepping).
// This algorithm gives the critical guarantee that all locations (both nodes and key/value pairs) in both trees that
// are identical by value (and possibly by reference) will be visited *at the same time* by the cursors.
// This removes the possibility of emitting incorrect diffs, as well as allowing for skipping shared nodes.
var _compare = this._compare;
var thisCursor = BTree.makeDiffCursor(this);
var otherCursor = BTree.makeDiffCursor(other);
// It doesn't matter how thisSteppedLast is initialized.
// Step order is only used when either cursor is at a leaf, and cursors always start at a node.
var thisSuccess = true, otherSuccess = true, prevCursorOrder = BTree.compare(thisCursor, otherCursor, _compare);
while (thisSuccess && otherSuccess) {
var cursorOrder = BTree.compare(thisCursor, otherCursor, _compare);
var thisLeaf = thisCursor.leaf, thisInternalSpine = thisCursor.internalSpine, thisLevelIndices = thisCursor.levelIndices;
var otherLeaf = otherCursor.leaf, otherInternalSpine = otherCursor.internalSpine, otherLevelIndices = otherCursor.levelIndices;
if (thisLeaf || otherLeaf) {
// If the cursors were at the same location last step, then there is no work to be done.
if (prevCursorOrder !== 0) {
if (cursorOrder === 0) {
if (thisLeaf && otherLeaf && different) {
// Equal keys, check for modifications
var valThis = thisLeaf.values[thisLevelIndices[thisLevelIndices.length - 1]];
var valOther = otherLeaf.values[otherLevelIndices[otherLevelIndices.length - 1]];
if (!Object.is(valThis, valOther)) {
var result = different(thisCursor.currentKey, valThis, valOther);
if (result && result.break)
return result.break;
}
}
}
else if (cursorOrder > 0) {
// If this is the case, we know that either:
// 1. otherCursor stepped last from a starting position that trailed thisCursor, and is still behind, or
// 2. thisCursor stepped last and leapfrogged otherCursor
// Either of these cases is an "only other"
if (otherLeaf && onlyOther) {
var otherVal = otherLeaf.values[otherLevelIndices[otherLevelIndices.length - 1]];
var result = onlyOther(otherCursor.currentKey, otherVal);
if (result && result.break)
return result.break;
}
}
else if (onlyThis) {
if (thisLeaf && prevCursorOrder !== 0) {
var valThis = thisLeaf.values[thisLevelIndices[thisLevelIndices.length - 1]];
var result = onlyThis(thisCursor.currentKey, valThis);
if (result && result.break)
return result.break;
}
}
}
}
else if (!thisLeaf && !otherLeaf && cursorOrder === 0) {
var lastThis = thisInternalSpine.length - 1;
var lastOther = otherInternalSpine.length - 1;
var nodeThis = thisInternalSpine[lastThis][thisLevelIndices[lastThis]];
var nodeOther = otherInternalSpine[lastOther][otherLevelIndices[lastOther]];
if (nodeOther === nodeThis) {
prevCursorOrder = 0;
thisSuccess = BTree.step(thisCursor, true);
otherSuccess = BTree.step(otherCursor, true);
continue;
}
}
prevCursorOrder = cursorOrder;
if (cursorOrder < 0) {
thisSuccess = BTree.step(thisCursor);
}
else {
otherSuccess = BTree.step(otherCursor);
}
}
if (thisSuccess && onlyThis)
return BTree.finishCursorWalk(thisCursor, otherCursor, _compare, onlyThis);
if (otherSuccess && onlyOther)
return BTree.finishCursorWalk(otherCursor, thisCursor, _compare, onlyOther);
};
///////////////////////////////////////////////////////////////////////////
// Helper methods for diffAgainst /////////////////////////////////////////
BTree.finishCursorWalk = function (cursor, cursorFinished, compareKeys, callback) {
var compared = BTree.compare(cursor, cursorFinished, compareKeys);
if (compared === 0) {
if (!BTree.step(cursor))
return undefined;
}
else if (compared < 0) {
check(false, "cursor walk terminated early");
}
return BTree.stepToEnd(cursor, callback);
};
BTree.stepToEnd = function (cursor, callback) {
var canStep = true;
while (canStep) {
var leaf = cursor.leaf, levelIndices = cursor.levelIndices, currentKey = cursor.currentKey;
if (leaf) {
var value = leaf.values[levelIndices[levelIndices.length - 1]];
var result = callback(currentKey, value);
if (result && result.break)
return result.break;
}
canStep = BTree.step(cursor);
}
return undefined;
};
BTree.makeDiffCursor = function (tree) {
var _root = tree._root, height = tree.height;
return { height: height, internalSpine: [[_root]], levelIndices: [0], leaf: undefined, currentKey: _root.maxKey() };
};
/**
* Advances the cursor to the next step in the walk of its tree.
* Cursors are walked backwards in sort order, as this allows them to leverage maxKey() in order to be compared in O(1).
* @param cursor The cursor to step
* @param stepToNode If true, the cursor will be advanced to the next node (skipping values)
* @returns true if the step was completed and false if the step would have caused the cursor to move beyond the end of the tree.
*/
BTree.step = function (cursor, stepToNode) {
var internalSpine = cursor.internalSpine, levelIndices = cursor.levelIndices, leaf = cursor.leaf;
if (stepToNode === true || leaf) {
var levelsLength = levelIndices.length;
// Step to the next node only if:
// - We are explicitly directed to via stepToNode, or
// - There are no key/value pairs left to step to in this leaf
if (stepToNode === true || levelIndices[levelsLength - 1] === 0) {
var spineLength = internalSpine.length;
// Root is leaf
if (spineLength === 0)
return false;
// Walk back up the tree until we find a new subtree to descend into
var nodeLevelIndex = spineLength - 1;
var levelIndexWalkBack = nodeLevelIndex;
while (levelIndexWalkBack >= 0) {
if (levelIndices[levelIndexWalkBack] > 0) {
if (levelIndexWalkBack < levelsLength - 1) {
// Remove leaf state from cursor
cursor.leaf = undefined;
levelIndices.pop();
}
// If we walked upwards past any internal node, slice them out
if (levelIndexWalkBack < nodeLevelIndex)
cursor.internalSpine = internalSpine.slice(0, levelIndexWalkBack + 1);
// Move to new internal node
cursor.currentKey = internalSpine[levelIndexWalkBack][--levelIndices[levelIndexWalkBack]].maxKey();
return true;
}
levelIndexWalkBack--;
}
// Cursor is in the far left leaf of the tree, no more nodes to enumerate
return false;
}
else {
// Move to new leaf value
var valueIndex = --levelIndices[levelsLength - 1];
cursor.currentKey = leaf.keys[valueIndex];
return true;
}
}
else { // Cursor does not point to a value in a leaf, so move downwards
var nextLevel = internalSpine.length;
var currentLevel = nextLevel - 1;
var node = internalSpine[currentLevel][levelIndices[currentLevel]];
if (node.isLeaf) {
// Entering into a leaf. Set the cursor to point at the last key/value pair.
cursor.leaf = node;
var valueIndex = levelIndices[nextLevel] = node.values.length - 1;
cursor.currentKey = node.keys[valueIndex];
}
else {
var children = node.children;
internalSpine[nextLevel] = children;
var childIndex = children.length - 1;
levelIndices[nextLevel] = childIndex;
cursor.currentKey = children[childIndex].maxKey();
}
return true;
}
};
/**
* Compares the two cursors. Returns a value indicating which cursor is ahead in a walk.
* Note that cursors are advanced in reverse sorting order.
*/
BTree.compare = function (cursorA, cursorB, compareKeys) {
var heightA = cursorA.height, currentKeyA = cursorA.currentKey, levelIndicesA = cursorA.levelIndices;
var heightB = cursorB.height, currentKeyB = cursorB.currentKey, levelIndicesB = cursorB.levelIndices;
// Reverse the comparison order, as cursors are advanced in reverse sorting order
var keyComparison = compareKeys(currentKeyB, currentKeyA);
if (keyComparison !== 0) {
return keyComparison;
}
// Normalize depth values relative to the shortest tree.
// This ensures that concurrent cursor walks of trees of differing heights can reliably land on shared nodes at the same time.
// To accomplish this, a cursor that is on an internal node at depth D1 with maxKey X is considered "behind" a cursor on an
// internal node at depth D2 with maxKey Y, when D1 < D2. Thus, always walking the cursor that is "behind" will allow the cursor
// at shallower depth (but equal maxKey) to "catch up" and land on shared nodes.
var heightMin = heightA < heightB ? heightA : heightB;
var depthANormalized = levelIndicesA.length - (heightA - heightMin);
var depthBNormalized = levelIndicesB.length - (heightB - heightMin);
return depthANormalized - depthBNormalized;
};
// End of helper methods for diffAgainst //////////////////////////////////
///////////////////////////////////////////////////////////////////////////
/** Returns a new iterator for iterating the keys of each pair in ascending order.
* @param firstKey: Minimum key to include in the output. */
BTree.prototype.keys = function (firstKey) {
var it = this.entries(firstKey, ReusedArray);
return iterator(function () {
var n = it.next();
if (n.value)
n.value = n.value[0];
return n;
});
};
/** Returns a new iterator for iterating the values of each pair in order by key.
* @param firstKey: Minimum key whose associated value is included in the output. */
BTree.prototype.values = function (firstKey) {
var it = this.entries(firstKey, ReusedArray);
return iterator(function () {
var n = it.next();
if (n.value)
n.value = n.value[1];
return n;
});
};
Object.defineProperty(BTree.prototype, "maxNodeSize", {
/////////////////////////////////////////////////////////////////////////////
// Additional methods ///////////////////////////////////////////////////////
/** Returns the maximum number of children/values before nodes will split. */
get: function () {
return this._maxNodeSize;
},
enumerable: false,
configurable: true
});
/** Gets the lowest key in the tree. Complexity: O(log size) */
BTree.prototype.minKey = function () { return this._root.minKey(); };
/** Gets the highest key in the tree. Complexity: O(1) */
BTree.prototype.maxKey = function () { return this._root.maxKey(); };
/** Quickly clones the tree by marking the root node as shared.
* Both copies remain editable. When you modify either copy, any
* nodes that are shared (or potentially shared) between the two
* copies are cloned so that the changes do not affect other copies.
* This is known as copy-on-write behavior, or "lazy copying". */
BTree.prototype.clone = function () {
this._root.isShared = true;
var result = new BTree(undefined, this._compare, this._maxNodeSize);
result._root = this._root;
result._size = this._size;
return result;
};
/** Performs a greedy clone, immediately duplicating any nodes that are
* not currently marked as shared, in order to avoid marking any
* additional nodes as shared.
* @param force Clone all nodes, even shared ones.
*/
BTree.prototype.greedyClone = function (force) {
var result = new BTree(undefined, this._compare, this._maxNodeSize);
result._root = this._root.greedyClone(force);
result._size = this._size;
return result;
};
/** Gets an array filled with the contents of the tree, sorted by key */
BTree.prototype.toArray = function (maxLength) {
if (maxLength === void 0) { maxLength = 0x7FFFFFFF; }
var min = this.minKey(), max = this.maxKey();
if (min !== undefined)
return this.getRange(min, max, true, maxLength);
return [];
};
/** Gets an array of all keys, sorted */
BTree.prototype.keysArray = function () {
var results = [];
this._root.forRange(this.minKey(), this.maxKey(), true, false, this, 0, function (k, v) { results.push(k); });
return results;
};
/** Gets an array of all values, sorted by key */
BTree.prototype.valuesArray = function () {
var results = [];
this._root.forRange(this.minKey(), this.maxKey(), true, false, this, 0, function (k, v) { results.push(v); });
return results;
};
/** Gets a string representing the tree's data based on toArray(). */
BTree.prototype.toString = function () {
return this.toArray().toString();
};
/** Stores a key-value pair only if the key doesn't already exist in the tree.
* @returns true if a new key was added
*/
BTree.prototype.setIfNotPresent = function (key, value) {
return this.set(key, value, false);
};
/** Returns the next pair whose key is larger than the specified key (or undefined if there is none).
* If key === undefined, this function returns the lowest pair.
* @param key The key to search for.
* @param reusedArray Optional array used repeatedly to store key-value pairs, to
* avoid creating a new array on every iteration.
*/
BTree.prototype.nextHigherPair = function (key, reusedArray) {
reusedArray = reusedArray || [];
if (key === undefined) {
return this._root.minPair(reusedArray);
}
return this._root.getPairOrNextHigher(key, this._compare, false, reusedArray);
};
/** Returns the next key larger than the specified key, or undefined if there is none.
* Also, nextHigherKey(undefined) returns the lowest key.
*/
BTree.prototype.nextHigherKey = function (key) {
var p = this.nextHigherPair(key, ReusedArray);
return p && p[0];
};
/** Returns the next pair whose key is smaller than the specified key (or undefined if there is none).
* If key === undefined, this function returns the highest pair.
* @param key The key to search for.
* @param reusedArray Optional array used repeatedly to store key-value pairs, to
* avoid creating a new array each time you call this method.
*/
BTree.prototype.nextLowerPair = function (key, reusedArray) {
reusedArray = reusedArray || [];
if (key === undefined) {
return this._root.maxPair(reusedArray);
}
return this._root.getPairOrNextLower(key, this._compare, false, reusedArray);
};
/** Returns the next key smaller than the specified key, or undefined if there is none.
* Also, nextLowerKey(undefined) returns the highest key.
*/
BTree.prototype.nextLowerKey = function (key) {
var p = this.nextLowerPair(key, ReusedArray);
return p && p[0];
};
/** Returns the key-value pair associated with the supplied key if it exists
* or the pair associated with the next lower pair otherwise. If there is no
* next lower pair, undefined is returned.
* @param key The key to search for.
* @param reusedArray Optional array used repeatedly to store key-value pairs, to
* avoid creating a new array each time you call this method.
* */
BTree.prototype.getPairOrNextLower = function (key, reusedArray) {
return this._root.getPairOrNextLower(key, this._compare, true, reusedArray || []);
};
/** Returns the key-value pair associated with the supplied key if it exists
* or the pair associated with the next lower pair otherwise. If there is no
* next lower pair, undefined is returned.
* @param key The key to search for.
* @param reusedArray Optional array used repeatedly to store key-value pairs, to
* avoid creating a new array each time you call this method.
* */
BTree.prototype.getPairOrNextHigher = function (key, reusedArray) {
return this._root.getPairOrNextHigher(key, this._compare, true, reusedArray || []);
};
/** Edits the value associated with a key in the tree, if it already exists.
* @returns true if the key existed, false if not.
*/
BTree.prototype.changeIfPresent = function (key, value) {
return this.editRange(key, key, true, function (k, v) { return ({ value: value }); }) !== 0;
};
/**
* Builds an array of pairs from the specified range of keys, sorted by key.
* Each returned pair is also an array: pair[0] is the key, pair[1] is the value.
* @param low The first key in the array will be greater than or equal to `low`.
* @param high This method returns when a key larger than this is reached.
* @param includeHigh If the `high` key is present, its pair will be included
* in the output if and only if this parameter is true. Note: if the
* `low` key is present, it is always included in the output.
* @param maxLength Length limit. getRange will stop scanning the tree when
* the array reaches this size.
* @description Computational complexity: O(result.length + log size)
*/
BTree.prototype.getRange = function (low, high, includeHigh, maxLength) {
if (maxLength === void 0) { maxLength = 0x3FFFFFF; }
var results = [];
this._root.forRange(low, high, includeHigh, false, this, 0, function (k, v) {
results.push([k, v]);
return results.length > maxLength ? Break : undefined;
});
return results;
};
/** Adds all pairs from a list of key-value pairs.
* @param pairs Pairs to add to this tree. If there are duplicate keys,
* later pairs currently overwrite earlier ones (e.g. [[0,1],[0,7]]
* associates 0 with 7.)
* @param overwrite Whether to overwrite pairs that already exist (if false,
* pairs[i] is ignored when the key pairs[i][0] already exists.)
* @returns The number of pairs added to the collection.
* @description Computational complexity: O(pairs.length * log(size + pairs.length))
*/
BTree.prototype.setPairs = function (pairs, overwrite) {
var added = 0;
for (var i = 0; i < pairs.length; i++)
if (this.set(pairs[i][0], pairs[i][1], overwrite))
added++;
return added;
};
/**
* Scans the specified range of keys, in ascending order by key.
* Note: the callback `onFound` must not insert or remove items in the
* collection. Doing so may cause incorrect data to be sent to the
* callback afterward.
* @param low The first key scanned will be greater than or equal to `low`.
* @param high Scanning stops when a key larger than this is reached.
* @param includeHigh If the `high` key is present, `onFound` is called for
* that final pair if and only if this parameter is true.
* @param onFound A function that is called for each key-value pair. This
* function can return {break:R} to stop early with result R.
* @param initialCounter Initial third argument of onFound. This value
* increases by one each time `onFound` is called. Default: 0
* @returns The number of values found, or R if the callback returned
* `{break:R}` to stop early.
* @description Computational complexity: O(number of items scanned + log size)
*/
BTree.prototype.forRange = function (low, high, includeHigh, onFound, initialCounter) {
var r = this._root.forRange(low, high, includeHigh, false, this, initialCounter || 0, onFound);
return typeof r === "number" ? r : r.break;
};
/**
* Scans and potentially modifies values for a subsequence of keys.
* Note: the callback `onFound` should ideally be a pure function.
* Specfically, it must not insert items, call clone(), or change
* the collection except via return value; out-of-band editing may
* cause an exception or may cause incorrect data to be sent to
* the callback (duplicate or missed items). It must not cause a
* clone() of the collection, otherwise the clone could be modified
* by changes reque