dubc-ds-tmap 1.0.0 → 1.0.2

package/README.md

@@ -1,3 +1,271 @@
 # dubc-ds-tmap
 
-Observable sorted map based on a weighted binary search tree.
+A map (dictionary) of key/value pairs that is sorted using a weighted
+binary search tree. 
+
+Note that this data structure maps _arbitrary_ keys to _arbitrary_
+values. When doing front-end development, that's usually not what
+you actually need. Consider using `dubc-ds-tindex` instead, which
+provides a dictionary where the keys are a function of the values.
+
+## Constructor
+
+```TypeScript
+constructor(conf:Conf<K,V>, pairs:Pairs<K,V>)
+```
+
+To construct a `TMap`, you need a configuration object that supplies
+three things:
+
+1. A `compare` function that determines how to sort the keys in the map.
+2. A `unique` flag that determines whether the map can contain duplicate keys.
+3. A `valueEq` function that determines how values should be compared.
+
+You also can supply initial key/value pairs to populate the map. The
+pairs can be specified in three ways:
+
+1. You can specify an iterable of objects with `key` and `value` fields;
+2. Or an iterable of key/value tuples, where the first part of the tuple
+   is the key and the second part of the tuplie is the value;
+3. Or, if the keys are strings, you can use a plain JavaScript object.
+
+If you want unique keys and can use `Object.is` for your `valueEq` function,
+you can use the static `of` method to construct a `TMap` with variadic 
+key/value pairs.
+
+Example:
+
+```TypeScript
+import { Conf, TMap } from "dubc-ds-tmap"
+
+const compare = (a:string, b:string) => a.localeCompare(b)
+
+const conf:Conf<string,number> = {
+  compare, unique:false, valueEq:Object.is,
+}
+
+// These five statements all do the same thing.
+const map1 = new TMap(conf, [{key:"1", value:1}, {key:"2", value:2}])
+const map2 = new TMap(conf, [["1", 1], ["2", 2]])
+const map3 = new TMap(conf, {"1":1, "2":2})
+const map4 = TMap.of(compare, {key:"1", value:1}, {key:"2", value:2})
+const map5 = TMap.of(compare, ["1", 1], ["2", 2])
+```
+
+## Properties
+
+### `.compare` O(1)
+
+Returns the current function used to compare keys. This property is
+mutable: If you change it, the map will re-sort (and fire a notification
+to any listeners that the map has changed.)
+
+### `.first` O(log n)
+
+Returns the first key/value pair in the map, or `undefined` if the map
+is empty.
+
+### `.i` O(1)
+
+Returns an iterator over the key/value pairs in the map. Each value
+returned by the iterator will be an immutable object in the form `{key:k, value:v}`. (This property is inherited from `Base`.)
+
+### `.last` O(log n)
+
+Returns the last key/value pair in the map, or `undefined` if the map
+is empty.
+
+### `.only` O(1)
+
+Returns the only key/value pair in the map. If the map doesn't have
+exactly one element, throws an `Error`.
+
+### `.size` O(1)
+
+Returns the number of key/value pairs in the map.
+
+## Methods
+
+### `.after(k:K)` O(log n)
+
+Returns the key/value pair whose key is strictly greater than the provided
+key, or `undefined` if no such pair exists in the map.
+
+### `.at(index:number)` O(log n)
+
+Returns the key/value pair at the specified index in the sort order.
+Throws a `TypeError` if the index is out of bounds.
+
+### `.before(k:K)` O(log n)
+
+Returns the key/value pair whose key is strictly less than the provided
+key, or `undefined` if no such pair exists in the map.
+
+### `.delete(k:K)` O(log n)
+
+Removes the given key from the map. Returns the value that was mapped
+to the key, or `undefined` if the key was not in the map.
+
+### `.deleteAll(i:Iterable<K>)` O(k * log n)
+
+Removes every key provided by the given iterable from the map.
+Returns the number of pairs that were deleted.
+
+### `.drop(f:(pair:Pair<K,V>)=>boolean)` O(n)
+
+Safely removes all key/value pairs that match the provided predicate
+function from the map. Use this instead of calling `delete` from within
+an iteration. Returns the number of pairs that were dropped.
+
+### `.from(k:K)` O(log n)
+
+Returns the key/value pair whose key is greater than or equal to the provided
+key, or `undefined` if no such pair exists in the map.
+
+### `.get(k:K)` O(log n)
+
+Returns the value for the given key, or `undefined` if no such key exists
+in the map.
+
+### `.has(k:K)` O(log n)
+
+Returns true if the map contains the given key, or false if it doesn't.
+
+### `.hasAll(i:Iterable<K>)` O(k * log n)
+
+Returns true if the map contains every key produced by the given iterable,
+or false if it doesn't.
+
+### `.hear(f:(event:DSEvent<Pair<K,V>>))` O(1)
+
+Adds a listener to the map. Any time the map changes (and _only_ when
+the map actually changes), the listener function will be called.
+
+Returns a number that can be sent to `unhear` to stop receiving events.
+
+### `.keys()` O(1)
+
+Returns an iterable iterator over the keys in the map.
+
+### `.range(start:K, end:K, include?:Include)` O(1)
+
+Returns an iterable over a range of keys in the map. The 
+iterator will produce key/value pairs.
+
+The optional third parameter specifies whether the range is inclusive
+or exclusive, and must be one of the following four constants:
+
+1. `IN_EX`: Start is inclusive, end is exclusive. This is the default.
+2. `IN_IN`: Both start and end are inclusive.
+3. `EX_IN`: Start is exclusive, end is inclusive.
+4. `EX_EX`: Both start and end are exclusive.
+
+### `.rank(k:K)` O(log n)
+
+Returns the index of the given key in the map's sort order, or
+`undefined` if the key is not in the map.
+
+### `.replace(pairs:Pairs<K,V>)` O(k * log n)
+
+Replaces the content of this map with new key/value pairs.
+
+The provided pairs can be in one of the three forms accepted by
+`TMap`'s constructor (objects with key and value fields, tuples of
+keys and values, or, for string keys, a JavaScript object.)
+
+### `.reversed()` O(1)
+
+Returns an iterable iterator over the pairs in the map, in reverse
+sort order.
+
+### `.set(key:K, value:V)` O(log n)
+
+Adds a pair to the map.
+
+If the map uses unique keys and the key already exists in the map,
+then `set` will replace the value for that key and return the old key.
+
+Otherwise, `set` will add a new pair to the map and return `undefined`.
+
+### `.setAll(pairs:Pairs<K,V>)` O(k * log n)
+
+Adds many pairs to the map. Returns the number of pairs that were newly
+added. (The number returned does not include any keys that were 
+already in a unique map.)
+
+The provided pairs can be in one of the three forms accepted by
+`TMap`'s constructor (objects with key and value fields, tuples of
+keys and values, or, for string keys, a JavaScript object.)
+
+### `.slice(start:number, end:number)`
+
+Returns an iterable over a range of indices. `end` is always exclusive.
+
+### `.to(k:K)` O(log n)
+
+Returns the key/value pair whose key is less than or equal to the provided
+key, or `undefined` if no such pair exists in the map.
+
+### `.unhear(n:number)` O(1)
+
+Removes the listener registered with the specified number.
+
+### `.values()` O(1)
+
+Returns an iterable iterator over the values in the map.
+
+## Operations by Kind
+
+### Listeners
+
+* `hear(eventHandler)` to get events when the map changes
+* `unhear(n)` to stop listening for changes
+
+### Iterators
+
+* `TMap` itself is an iterable, so you can use it directly in `for...of`
+* `i` to get an iterator 
+* `keys()` if you just want the keys
+* `range(start,end,include)` for partial iteration over a range of keys
+* `reversed()` to iterate backwards
+* `slice(start,end)` for partial iteration over a range of indices
+* `values()` if you just want the values
+
+### Keys
+
+* `get(key)` to get the value for a key
+* `has(key)` to determine if the key exists
+* `hasAll(iterable)` to determin if all the keys exist
+* `only` to get the only pair
+
+### Ordering
+
+* `get compare` for the sort function
+
+* `first` to get the first pair
+* `last` to get the last pair
+
+* `after(key)` to get the pair > key
+* `before(key)` to get the pair < key
+* `from(key)` to get the pair >= key
+* `to(key)` to get the pair <= key
+
+### Indices
+
+* `at(index)` to get the key at an index
+* `rank(key)` to get the index of a key
+* `size` to get the number of pairs
+
+### Adding/Changing
+
+* `set compare` to re-sort the map
+* `set(key,value)` add a pair to the map
+* `setAll(pairs)` add many pairs to the map
+* `replace(pairs)` clear the map then add many pairs
+
+### Deleting
+
+* `clear()` delete everything
+* `delete(key)` delete a specific key
+* `deleteAll(iterable)` delete many keys
+* `drop(predicate)` delete pairs that match a predicate

package/dist/index.d.ts

@@ -21,7 +21,7 @@ export declare const EX_EX: {
     end: boolean;
 };
 type N<K extends {}, V> = Node<K, V> | undefined;
-declare class Node<K extends {}, V> {
+declare class Node<K extends {}, V> implements Pair<K, V> {
     readonly key: K;
     value: V;
     weight: number;
@@ -42,6 +42,7 @@ export interface Conf<K extends {}, V> {
     readonly valueEq: (a: V, b: V) => boolean;
 }
 export declare class TMap<K extends {}, V> extends Base<Pair<K, V>> {
+    #private;
     private root;
     private _compare;
     protected conf: Conf<K, V>;
@@ -50,23 +51,20 @@ export declare class TMap<K extends {}, V> extends Base<Pair<K, V>> {
     toEmpty(): TMap<K, V>;
     get size(): number;
     clear(): void;
-    replace(i: Pairs<K, V>): void;
-    drop(f: (pair: Pair<K, V>) => boolean): void;
+    replace(i: Pairs<K, V>): boolean;
+    drop(f: (pair: Pair<K, V>) => boolean): number;
     get compare(): (a: K, b: K) => number;
     set compare(cmp: (a: K, b: K) => number);
-    get keyEq(): (a: K, b: K) => boolean;
-    get unique(): boolean;
     at(i: number): Pair<K, V>;
     get only(): Pair<K, V>;
     get first(): Pair<K, V> | undefined;
     get last(): Pair<K, V> | undefined;
-    [Symbol.iterator](): Generator<Node<K, V>, void, unknown>;
-    private keys2;
-    get keys(): Iterable<K>;
-    private values2;
-    get values(): Iterable<V>;
-    reversed(): Generator<Pair<K, V>, void, unknown>;
-    range(startKey: K, endKey: K, inc?: Include): Generator<Pair<K, V>, void, unknown>;
+    [Symbol.iterator](): Generator<Pair<K, V>>;
+    keys(): Iterable<K>;
+    values(): Iterable<V>;
+    reversed(): Iterable<Pair<K, V>>;
+    range(startKey: K, endKey: K, inc?: Include): Iterable<Pair<K, V>>;
+    slice(start: number, end: number): Iterable<Pair<K, V>>;
     private find;
     get(key: K): V | undefined;
     has(key: K): boolean;
@@ -74,6 +72,7 @@ export declare class TMap<K extends {}, V> extends Base<Pair<K, V>> {
     to(key: K): Pair<K, V> | undefined;
     after(key: K): Pair<K, V> | undefined;
     before(key: K): Pair<K, V> | undefined;
+    hasAll(keys: Iterable<K>): boolean;
     rank(key: K): number | undefined;
     protected rawPut(key: K, value: V): {
         node: Node<K, V>;
@@ -82,7 +81,9 @@ export declare class TMap<K extends {}, V> extends Base<Pair<K, V>> {
     set(key: K, value: V): V | undefined;
     setAll(entries: Pairs<K, V>): number;
     delete(key: K): V | undefined;
-    private remove;
+    private delete2;
+    deleteAll(i: Iterable<K>): number;
+    private rawDelete;
     private weigh;
 }
 export {};

package/dist/index.js

@@ -1,18 +1,23 @@
 import { Base } from "dubc-ds-base";
+import { iterable } from "dubc-ds-iterables";
 import { forEach } from "dubc-ds-pairs";
 export const IN_IN = { start: true, end: true };
 export const IN_EX = { start: true, end: false };
 export const EX_IN = { start: false, end: true };
 export const EX_EX = { start: false, end: false };
 class Node {
+    key;
+    value;
+    weight = 1;
+    parent;
+    left;
+    right;
     constructor(key, value) {
         this.key = key;
         this.value = value;
-        this.weight = 1;
     }
     weigh() {
-        var _a, _b, _c, _d;
-        this.weight = 1 + ((_b = (_a = this.left) === null || _a === void 0 ? void 0 : _a.weight) !== null && _b !== void 0 ? _b : 0) + ((_d = (_c = this.right) === null || _c === void 0 ? void 0 : _c.weight) !== null && _d !== void 0 ? _d : 0);
+        this.weight = 1 + (this.left?.weight ?? 0) + (this.right?.weight ?? 0);
     }
     index() {
         let i = -1;
@@ -60,7 +65,7 @@ class Node {
     rotateLeft() {
         let a = this;
         let b = a.right;
-        let r = b === null || b === void 0 ? void 0 : b.left;
+        let r = b?.left;
         b.parent = a.parent;
         b.left = a;
         a.parent = b;
@@ -68,13 +73,13 @@ class Node {
         if (r)
             r.parent = a;
         a.weigh();
-        b === null || b === void 0 ? void 0 : b.weigh();
+        b?.weigh();
         return b;
     }
     rotateRight() {
         let a = this;
         let b = a.left;
-        let l = b === null || b === void 0 ? void 0 : b.right;
+        let l = b?.right;
         b.parent = a.parent;
         b.right = a;
         a.parent = b;
@@ -82,7 +87,7 @@ class Node {
         if (l)
             l.parent = a;
         a.weigh();
-        b === null || b === void 0 ? void 0 : b.weigh();
+        b?.weigh();
         return b;
     }
 }
@@ -93,6 +98,9 @@ const LE = { lset: true, rset: false, eset: true, eright: true };
 const GT = { lset: false, rset: true, eset: false, eright: true };
 const GE = { lset: false, rset: true, eset: true, eright: false };
 export class TMap extends Base {
+    root;
+    _compare;
+    conf;
     constructor(input, c) {
         super();
         this._compare = c.compare;
@@ -104,15 +112,9 @@ export class TMap extends Base {
         return new TMap(pairs, conf);
     }
     toEmpty() {
-        const conf2 = {
-            unique: this.conf.unique,
-            valueEq: this.conf.valueEq,
-            compare: this._compare,
-        };
-        const r = new TMap(this, conf2);
-        return r;
-    }
-    get size() { var _a, _b; return (_b = (_a = this.root) === null || _a === void 0 ? void 0 : _a.weight) !== null && _b !== void 0 ? _b : 0; }
+        return new TMap([], this.conf);
+    }
+    get size() { return this.root?.weight ?? 0; }
     clear() {
         const sz = this.size;
         this.root = undefined;
@@ -128,23 +130,32 @@ export class TMap extends Base {
                 this.fire({ cleared: sz });
             else
                 this.fire({ cleared: sz, added: { items: this, at: 0 } });
+            return true;
         }
-        else if (this.root !== undefined)
+        else if (this.root !== undefined) {
             this.fire({ added: { items: this, at: 0 } });
+            return true;
+        }
+        else {
+            return false;
+        }
     }
     drop(f) {
         let n = this.first;
         let at = 0;
+        let c = 0;
         while (n !== undefined) {
             const x = n;
             n = n.next();
             if (f(x)) {
-                this.remove(x);
+                this.rawDelete(x);
                 this.fire({ deleted: { items: [x], at: at } });
+                c++;
             }
             else
                 at++;
         }
+        return c;
     }
     get compare() { return this._compare; }
     set compare(cmp) {
@@ -159,21 +170,19 @@ export class TMap extends Base {
         }
         this.fire({ cleared: this.size, added: { items: this, at: 0 } });
     }
-    get keyEq() { return (a, b) => this._compare(a, b) === 0; }
-    get unique() { return this.conf.unique; }
     at(i) {
-        var _a;
         let node = this.root;
         let weight = this.size;
-        // if (i < 0) i += weight // TODO
+        if (!Number.isSafeInteger(i))
+            throw new TypeError("index must be an integer");
         if (i < 0 || i >= weight)
             throw new TypeError("bounds");
         while (true) {
-            const left = node === null || node === void 0 ? void 0 : node.left;
-            const lw = (_a = left === null || left === void 0 ? void 0 : left.weight) !== null && _a !== void 0 ? _a : 0;
+            const left = node?.left;
+            const lw = left?.weight ?? 0;
             if (i > lw) {
                 i -= lw + 1;
-                node = node === null || node === void 0 ? void 0 : node.right;
+                node = node?.right;
             }
             else if (i < lw) {
                 node = left;
@@ -213,28 +222,31 @@ export class TMap extends Base {
             n = n.next();
         }
     }
-    *keys2() {
+    *#keys() {
         for (const x of this)
             yield x.key;
     }
-    get keys() {
-        return this.keys2();
+    keys() {
+        return iterable(() => this.#keys());
     }
-    *values2() {
+    *#values() {
         for (const x of this)
             yield x.value;
     }
-    get values() {
-        return this.values2();
+    values() {
+        return iterable(() => this.#values());
     }
-    *reversed() {
+    *#reversed() {
         let n = this.last;
         while (n) {
             yield n;
             n = n.prev();
         }
     }
-    *range(startKey, endKey, inc = IN_EX) {
+    reversed() {
+        return iterable(() => this.#reversed());
+    }
+    *#range(startKey, endKey, inc) {
         const start = this.find(startKey, inc.start ? GE : GT);
         const cmp = this.compare;
         if (inc.end)
@@ -246,10 +258,25 @@ export class TMap extends Base {
                 yield n;
             }
     }
+    range(startKey, endKey, inc = IN_EX) {
+        return iterable(() => this.#range(startKey, endKey, inc));
+    }
+    slice(start, end) {
+        if (end <= start)
+            throw new TypeError("end <= start");
+        const s = this.at(start);
+        if (end === this.size) {
+            return this.range(s.key, this.last.key, IN_IN);
+        }
+        else {
+            const e = this.at(end);
+            return this.range(s.key, e.key, IN_EX);
+        }
+    }
     find(key, op = EQ) {
         let node = this.root;
         let ret;
-        const unique = this.unique;
+        const unique = this.conf.unique;
         const cmp = this.compare;
         while (node) {
             const c = cmp(node.key, key);
@@ -275,19 +302,24 @@ export class TMap extends Base {
         }
         return ret;
     }
-    get(key) { var _a; return (_a = this.find(key, EQ)) === null || _a === void 0 ? void 0 : _a.value; }
+    get(key) { return this.find(key, EQ)?.value; }
     has(key) { return this.find(key, EQ) !== undefined; }
     from(key) { return this.find(key, GE); }
     to(key) { return this.find(key, LE); }
     after(key) { return this.find(key, GT); }
     before(key) { return this.find(key, LT); }
+    hasAll(keys) {
+        for (const x of keys)
+            if (!this.has(x))
+                return false;
+        return true;
+    }
     rank(key) {
-        var _a;
-        return (_a = this.find(key, EQ)) === null || _a === void 0 ? void 0 : _a.index();
+        return this.find(key, EQ)?.index();
     }
     rawPut(key, value) {
         let previous = undefined, node = this.root;
-        let unique = this.unique ? 0 : undefined;
+        let unique = this.conf.unique ? 0 : undefined;
         let c = 0, cmp = this.compare;
         while (node) {
             c = cmp(node.key, key);
@@ -347,12 +379,26 @@ export class TMap extends Base {
         const node = this.find(key);
         if (node === undefined)
             return undefined;
+        return this.delete2(node);
+    }
+    delete2(node) {
         const at = node.index();
-        this.remove(node);
+        this.rawDelete(node);
         this.fire({ deleted: { items: [node], at } });
         return node.value;
     }
-    remove(node) {
+    deleteAll(i) {
+        let c = 0;
+        for (const x of i) {
+            const node = this.find(x);
+            if (node !== undefined) {
+                c++;
+                this.delete2(node);
+            }
+        }
+        return c;
+    }
+    rawDelete(node) {
         const p = node.parent;
         let left = node.left, right = node.right;
         let bal;
@@ -404,13 +450,13 @@ export class TMap extends Base {
             let lw = weight(left);
             let rw = weight(right);
             if (rw * 5 + 2 < lw * 2) {
-                if (weight(left === null || left === void 0 ? void 0 : left.left) * 5 < lw * 2)
-                    node.left = left === null || left === void 0 ? void 0 : left.rotateLeft();
+                if (weight(left?.left) * 5 < lw * 2)
+                    node.left = left?.rotateLeft();
                 node = node.rotateRight();
             }
             else if (lw * 5 + 2 < rw * 2) {
-                if (weight(right === null || right === void 0 ? void 0 : right.right) * 5 < rw * 2)
-                    node.right = right === null || right === void 0 ? void 0 : right.rotateRight();
+                if (weight(right?.right) * 5 < rw * 2)
+                    node.right = right?.rotateRight();
                 node = node.rotateLeft();
             }
             else {
@@ -427,7 +473,6 @@ export class TMap extends Base {
     }
 }
 function weight(n) {
-    var _a;
-    return (_a = n === null || n === void 0 ? void 0 : n.weight) !== null && _a !== void 0 ? _a : 0;
+    return n?.weight ?? 0;
 }
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dubc-ds-tmap",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Observable map based on a weighted binary search tree.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,14 +26,15 @@
   },
   "homepage": "https://github.com/p-jack/dubc#readme",
   "dependencies": {
-    "dubc-ds-base": "^1.0.2",
-    "dubc-ds-pairs": "^1.0.0"
+    "@vitest/coverage-v8": "^4.1.8",
+    "dubc-ds-base": "^1.0.3",
+    "dubc-ds-iterables": "^1.0.0",
+    "dubc-ds-pairs": "^1.0.2",
+    "vitest": "^4.1.8"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^3.2.4",
-    "dubc-ds-test": "^1.0.1",
+    "dubc-ds-test": "^1.0.2",
     "jsdom": "^27.0.1",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "typescript": "^5.9.3"
   }
 }