binary-tree-typed 2.4.5 → 2.5.0

package/dist/types/data-structures/graph/undirected-graph.d.ts

@@ -66,65 +66,6 @@ export declare class UndirectedEdge<E = number> extends AbstractEdge<E> {
  *     console.log(neighborsA[0].key); // 'B';
  *     console.log(neighborsA[1].key); // 'C';
  * @example
- * // UndirectedGraph deleteEdge and vertex operations
- *  const graph = new UndirectedGraph<string>();
- *
- *     // Build a simple undirected graph
- *     graph.addVertex('X');
- *     graph.addVertex('Y');
- *     graph.addVertex('Z');
- *     graph.addEdge('X', 'Y', 1);
- *     graph.addEdge('Y', 'Z', 2);
- *     graph.addEdge('X', 'Z', 3);
- *
- *     // Delete an edge
- *     graph.deleteEdge('X', 'Y');
- *     console.log(graph.hasEdge('X', 'Y')); // false;
- *
- *     // Bidirectional deletion confirmed
- *     console.log(graph.hasEdge('Y', 'X')); // false;
- *
- *     // Other edges should remain
- *     console.log(graph.hasEdge('Y', 'Z')); // true;
- *     console.log(graph.hasEdge('Z', 'Y')); // true;
- *
- *     // Delete a vertex
- *     graph.deleteVertex('Y');
- *     console.log(graph.hasVertex('Y')); // false;
- *     console.log(graph.size); // 2;
- * @example
- * // UndirectedGraph connectivity and neighbors
- *  const graph = new UndirectedGraph<string>();
- *
- *     // Build a friendship network
- *     const people = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'];
- *     for (const person of people) {
- *       graph.addVertex(person);
- *     }
- *
- *     // Add friendships (undirected edges)
- *     graph.addEdge('Alice', 'Bob', 1);
- *     graph.addEdge('Alice', 'Charlie', 1);
- *     graph.addEdge('Bob', 'Diana', 1);
- *     graph.addEdge('Charlie', 'Eve', 1);
- *     graph.addEdge('Diana', 'Eve', 1);
- *
- *     // Get friends of each person
- *     const aliceFriends = graph.getNeighbors('Alice');
- *     console.log(aliceFriends[0].key); // 'Bob';
- *     console.log(aliceFriends[1].key); // 'Charlie';
- *     console.log(aliceFriends.length); // 2;
- *
- *     const dianaFriends = graph.getNeighbors('Diana');
- *     console.log(dianaFriends[0].key); // 'Bob';
- *     console.log(dianaFriends[1].key); // 'Eve';
- *     console.log(dianaFriends.length); // 2;
- *
- *     // Verify bidirectional friendship
- *     const bobFriends = graph.getNeighbors('Bob');
- *     console.log(bobFriends[0].key); // 'Alice'; // Alice -> Bob -> Alice ✓
- *     console.log(bobFriends[1].key); // 'Diana';
- * @example
  * // UndirectedGraph for social network connectivity analysis
  *  interface Person {
  *       id: number;
@@ -233,6 +174,21 @@ export declare class UndirectedGraph<V = any, E = any, VO extends UndirectedVert
      * @param v2 - The other vertex or key.
      * @returns Edge instance or `undefined`.
      * @remarks Time O(1) avg, Space O(1)
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Get edge between vertices
+   *  const g = new UndirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addEdge('A', 'B', 7);
+   *     console.log(g.getEdge('A', 'B')?.weight); // 7;
      */
     getEdge(v1: VO | VertexKey | undefined, v2: VO | VertexKey | undefined): EO | undefined;
     /**
@@ -249,6 +205,44 @@ export declare class UndirectedGraph<V = any, E = any, VO extends UndirectedVert
      * @param otherSideVertexKey - Required second endpoint when deleting by pair.
      * @returns Removed edge or `undefined`.
      * @remarks Time O(1) avg, Space O(1)
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // UndirectedGraph deleteEdge and vertex operations
+   *  const graph = new UndirectedGraph<string>();
+   *
+   *     // Build a simple undirected graph
+   *     graph.addVertex('X');
+   *     graph.addVertex('Y');
+   *     graph.addVertex('Z');
+   *     graph.addEdge('X', 'Y', 1);
+   *     graph.addEdge('Y', 'Z', 2);
+   *     graph.addEdge('X', 'Z', 3);
+   *
+   *     // Delete an edge
+   *     graph.deleteEdge('X', 'Y');
+   *     console.log(graph.hasEdge('X', 'Y')); // false;
+   *
+   *     // Bidirectional deletion confirmed
+   *     console.log(graph.hasEdge('Y', 'X')); // false;
+   *
+   *     // Other edges should remain
+   *     console.log(graph.hasEdge('Y', 'Z')); // true;
+   *     console.log(graph.hasEdge('Z', 'Y')); // true;
+   *
+   *     // Delete a vertex
+   *     graph.deleteVertex('Y');
+   *     console.log(graph.hasVertex('Y')); // false;
+   *     console.log(graph.size); // 2;
      */
     deleteEdge(edgeOrOneSideVertexKey: EO | VertexKey, otherSideVertexKey?: VertexKey): EO | undefined;
     /**
@@ -256,6 +250,22 @@ export declare class UndirectedGraph<V = any, E = any, VO extends UndirectedVert
      * @param vertexOrKey - Vertex or key.
      * @returns `true` if removed; otherwise `false`.
      * @remarks Time O(deg), Space O(1)
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Remove vertex and edges
+   *  const g = new UndirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addEdge('A', 'B');
+   *     g.deleteVertex('A');
+   *     console.log(g.hasVertex('A')); // false;
      */
     deleteVertex(vertexOrKey: VO | VertexKey): boolean;
     /**
@@ -276,8 +286,69 @@ export declare class UndirectedGraph<V = any, E = any, VO extends UndirectedVert
      * Unique set of undirected edges across endpoints.
      * @returns Array of edges.
      * @remarks Time O(E), Space O(E)
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Get all edges
+   *  const g = new UndirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addEdge('A', 'B');
+   *     console.log(g.edgeSet().length); // 1;
      */
     edgeSet(): EO[];
+    /**
+   * UndirectedGraph connectivity and neighbors
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // UndirectedGraph connectivity and neighbors
+ *  const graph = new UndirectedGraph<string>();
+ *
+ *     // Build a friendship network
+ *     const people = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'];
+ *     for (const person of people) {
+ *       graph.addVertex(person);
+ *     }
+ *
+ *     // Add friendships (undirected edges)
+ *     graph.addEdge('Alice', 'Bob', 1);
+ *     graph.addEdge('Alice', 'Charlie', 1);
+ *     graph.addEdge('Bob', 'Diana', 1);
+ *     graph.addEdge('Charlie', 'Eve', 1);
+ *     graph.addEdge('Diana', 'Eve', 1);
+ *
+ *     // Get friends of each person
+ *     const aliceFriends = graph.getNeighbors('Alice');
+ *     console.log(aliceFriends[0].key); // 'Bob';
+ *     console.log(aliceFriends[1].key); // 'Charlie';
+ *     console.log(aliceFriends.length); // 2;
+ *
+ *     const dianaFriends = graph.getNeighbors('Diana');
+ *     console.log(dianaFriends[0].key); // 'Bob';
+ *     console.log(dianaFriends[1].key); // 'Eve';
+ *     console.log(dianaFriends.length); // 2;
+ *
+ *     // Verify bidirectional friendship
+ *     const bobFriends = graph.getNeighbors('Bob');
+ *     console.log(bobFriends[0].key); // 'Alice'; // Alice -> Bob -> Alice ✓
+ *     console.log(bobFriends[1].key); // 'Diana';
+   */
     getNeighbors(vertexOrKey: VO | VertexKey): VO[];
     /**
      * Resolve an edge's two endpoints to vertex instances.
@@ -306,6 +377,24 @@ export declare class UndirectedGraph<V = any, E = any, VO extends UndirectedVert
      * Tarjan-based bridge and articulation point detection.
      * @returns `{ dfnMap, lowMap, bridges, cutVertices }`.
      * @remarks Time O(V + E), Space O(V + E)
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Find articulation points and bridges
+   *  const g = new UndirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addVertex('C');
+   *     g.addEdge('A', 'B');
+   *     g.addEdge('B', 'C');
+   *     const result = g.tarjan();
+   *     console.log(result); // defined;
      */
     tarjan(): {
         dfnMap: Map<VO, number>;
@@ -325,18 +414,74 @@ export declare class UndirectedGraph<V = any, E = any, VO extends UndirectedVert
      * Uses DFS with parent tracking.
      * @returns `true` if a cycle exists, `false` otherwise.
      * @remarks Time O(V + E), Space O(V)
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Detect cycle
+   *  const g = new UndirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addVertex('C');
+   *     g.addEdge('A', 'B');
+   *     g.addEdge('B', 'C');
+   *     console.log(g.hasCycle()); // false;
+   *     g.addEdge('C', 'A');
+   *     console.log(g.hasCycle()); // true;
      */
     hasCycle(): boolean;
     /**
      * Get bridges discovered by `tarjan()`.
      * @returns Array of edges that are bridges.
      * @remarks Time O(B), Space O(1)
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Find bridge edges
+   *  const g = new UndirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addVertex('C');
+   *     g.addEdge('A', 'B');
+   *     g.addEdge('B', 'C');
+   *     const bridges = g.getBridges();
+   *     console.log(bridges.length); // 2;
      */
     getBridges(): EO[];
     /**
      * Get articulation points discovered by `tarjan()`.
      * @returns Array of cut vertices.
      * @remarks Time O(C), Space O(1)
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Find articulation points
+   *  const g = new UndirectedGraph();
+   *     g.addVertex('A');
+   *     g.addVertex('B');
+   *     g.addVertex('C');
+   *     g.addEdge('A', 'B');
+   *     g.addEdge('B', 'C');
+   *     const cuts = g.getCutVertices();
+   *     console.log(cuts.length); // 1;
+   *     console.log(cuts[0].key); // 'B';
      */
     getCutVertices(): VO[];
     /**

package/dist/types/data-structures/hash/hash-map.d.ts

@@ -19,83 +19,6 @@ import { IterableEntryBase } from '../base';
  * If you try to insert another entry with the same key, the new one will replace the old entry.
  * 4. Unordered Collection: HashMap does not guarantee the order of entries, and the order may change over time.
  * @example
- * // should maintain insertion order
- *  const linkedHashMap = new LinkedHashMap<number, string>();
- *     linkedHashMap.set(1, 'A');
- *     linkedHashMap.set(2, 'B');
- *     linkedHashMap.set(3, 'C');
- *
- *     const result = Array.from(linkedHashMap);
- *     console.log(result); // [
- *  //      [1, 'A'],
- *  //      [2, 'B'],
- *  //      [3, 'C']
- *  //    ];
- * @example
- * // basic HashMap creation and set operation
- *  // Create a simple HashMap with key-value pairs
- *     const map = new HashMap<number, string>([
- *       [1, 'one'],
- *       [2, 'two'],
- *       [3, 'three']
- *     ]);
- *
- *     // Verify size
- *     console.log(map.size); // 3;
- *
- *     // Set a new key-value pair
- *     map.set(4, 'four');
- *     console.log(map.size); // 4;
- *
- *     // Verify entries
- *     console.log([...map.entries()]); // length: 4;
- * @example
- * // HashMap get and has operations
- *  const map = new HashMap<string, number>([
- *       ['apple', 1],
- *       ['banana', 2],
- *       ['cherry', 3]
- *     ]);
- *
- *     // Check if key exists
- *     console.log(map.has('apple')); // true;
- *     console.log(map.has('date')); // false;
- *
- *     // Get value by key
- *     console.log(map.get('banana')); // 2;
- *     console.log(map.get('grape')); // undefined;
- *
- *     // Get all keys and values
- *     const keys = [...map.keys()];
- *     const values = [...map.values()];
- *     console.log(keys); // contains 'apple';
- *     console.log(values); // contains 3;
- * @example
- * // HashMap iteration and filter operations
- *  const map = new HashMap<number, string>([
- *       [1, 'Alice'],
- *       [2, 'Bob'],
- *       [3, 'Charlie'],
- *       [4, 'Diana'],
- *       [5, 'Eve']
- *     ]);
- *
- *     // Iterate through entries
- *     const entries: [number, string][] = [];
- *     for (const [key, value] of map) {
- *       entries.push([key, value]);
- *     }
- *     console.log(entries); // length: 5;
- *
- *     // Filter operation (for iteration with collection methods)
- *     const filtered = [...map].filter(([key]) => key > 2);
- *     console.log(filtered.length); // 3;
- *
- *     // Map operation
- *     const values = [...map.values()].map(v => v.length);
- *     console.log(values); // contains 3; // 'Bob', 'Eve'
- *     console.log(values); // contains 7;
- * @example
  * // HashMap for user session caching O(1) performance
  *  interface UserSession {
  *       userId: number;
@@ -147,6 +70,19 @@ import { IterableEntryBase } from '../base';
  *     // Get all active sessions
  *     const activeCount = [...sessionCache.values()].length;
  *     console.log(activeCount); // 2;
+ * @example
+ * // Aggregate values
+ *  const counts = new HashMap<string, number>([['a', 5], ['b', 3], ['c', 8]]);
+ *
+ *     const total = counts.reduce((sum, v) => sum + (v ?? 0), 0);
+ *     console.log(total); // 16;
+ * @example
+ * // Iterate over entries
+ *  const map = new HashMap<string, number>([['x', 1], ['y', 2]]);
+ *     const keys: string[] = [];
+ *
+ *     map.forEach((v, k) => keys.push(k));
+ *     console.log(keys.sort()); // ['x', 'y'];
  */
 export declare class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K, V> {
     /**
@@ -200,12 +136,39 @@ export declare class HashMap<K = any, V = any, R = [K, V]> extends IterableEntry
      * Check whether the map is empty.
      * @remarks Time O(1), Space O(1)
      * @returns True if size is 0.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Check if empty
+   *  const map = new HashMap();
+   *     console.log(map.isEmpty()); // true;
      */
     isEmpty(): boolean;
     /**
      * Remove all entries and reset counters.
      * @remarks Time O(N), Space O(1)
      * @returns void
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Remove all entries
+   *  const map = new HashMap<string, number>([['a', 1], ['b', 2]]);
+   *     map.clear();
+   *     console.log(map.isEmpty()); // true;
      */
     clear(): void;
     /**
@@ -220,6 +183,46 @@ export declare class HashMap<K = any, V = any, R = [K, V]> extends IterableEntry
      * @param key - Key.
      * @param value - Value.
      * @returns True when the operation succeeds.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // basic HashMap creation and set operation
+   *  // Create a simple HashMap with key-value pairs
+   *     const map = new HashMap<number, string>([
+   *       [1, 'one'],
+   *       [2, 'two'],
+   *       [3, 'three']
+   *     ]);
+   *
+   *     // Verify size
+   *     console.log(map.size); // 3;
+   *
+   *     // Set a new key-value pair
+   *     map.set(4, 'four');
+   *     console.log(map.size); // 4;
+   *
+   *     // Verify entries
+   *     console.log([...map.entries()]); // length: 4;
      */
     set(key: K, value: V): boolean;
     /**
@@ -227,6 +230,20 @@ export declare class HashMap<K = any, V = any, R = [K, V]> extends IterableEntry
      * @remarks Time O(N), Space O(N)
      * @param entryOrRawElements - Iterable of entries or raw elements to insert.
      * @returns Array of per-entry results.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Add multiple entries
+   *  const map = new HashMap<string, number>();
+   *     map.setMany([['a', 1], ['b', 2], ['c', 3]]);
+   *     console.log(map.size); // 3;
      */
     setMany(entryOrRawElements: Iterable<R | [K, V]>): boolean[];
     /**
@@ -234,6 +251,38 @@ export declare class HashMap<K = any, V = any, R = [K, V]> extends IterableEntry
      * @remarks Time O(1), Space O(1)
      * @param key - Key to look up.
      * @returns Value or undefined.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // HashMap get and has operations
+   *  const map = new HashMap<string, number>([
+   *       ['apple', 1],
+   *       ['banana', 2],
+   *       ['cherry', 3]
+   *     ]);
+   *
+   *     // Check if key exists
+   *     console.log(map.has('apple')); // true;
+   *     console.log(map.has('date')); // false;
+   *
+   *     // Get value by key
+   *     console.log(map.get('banana')); // 2;
+   *     console.log(map.get('grape')); // undefined;
+   *
+   *     // Get all keys and values
+   *     const keys = [...map.keys()];
+   *     const values = [...map.values()];
+   *     console.log(keys); // contains 'apple';
+   *     console.log(values); // contains 3;
      */
     get(key: K): V | undefined;
     /**
@@ -241,6 +290,23 @@ export declare class HashMap<K = any, V = any, R = [K, V]> extends IterableEntry
      * @remarks Time O(1), Space O(1)
      * @param key - Key to test.
      * @returns True if present.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Check key existence
+   *  const map = new HashMap<string, number>([['a', 1], ['b', 2]]);
+   *
+   *     console.log(map.has('a')); // true;
+   *     console.log(map.has('z')); // false;
      */
     has(key: K): boolean;
     /**
@@ -248,6 +314,24 @@ export declare class HashMap<K = any, V = any, R = [K, V]> extends IterableEntry
      * @remarks Time O(1), Space O(1)
      * @param key - Key to delete.
      * @returns True if the key was found and removed.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Remove entries by key
+   *  const map = new HashMap<string, number>([['x', 10], ['y', 20], ['z', 30]]);
+   *
+   *     console.log(map.delete('y')); // true;
+   *     console.log(map.has('y')); // false;
+   *     console.log(map.size); // 2;
      */
     delete(key: K): boolean;
     /**
@@ -261,6 +345,21 @@ export declare class HashMap<K = any, V = any, R = [K, V]> extends IterableEntry
      * Deep clone this map, preserving hashing behavior.
      * @remarks Time O(N), Space O(N)
      * @returns A new map with the same content.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Create independent copy
+   *  const map = new HashMap<string, number>([['a', 1]]);
+   *     const copy = map.clone();
+   *     copy.set('a', 99);
+   *     console.log(map.get('a')); // 1;
      */
     clone(): this;
     /**
@@ -270,6 +369,24 @@ export declare class HashMap<K = any, V = any, R = [K, V]> extends IterableEntry
      * @param callbackfn - Mapping function (key, value, index, map) → newValue.
      * @param [thisArg] - Value for `this` inside the callback.
      * @returns A new map with transformed values.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Transform all values
+   *  const prices = new HashMap<string, number>([['apple', 1], ['banana', 2]]);
+   *
+   *     const doubled = prices.map(v => (v ?? 0) * 2);
+   *     console.log(doubled.get('apple')); // 2;
+   *     console.log(doubled.get('banana')); // 4;
      */
     map<VM>(callbackfn: EntryCallback<K, V, VM>, thisArg?: any): any;
     /**
@@ -278,6 +395,42 @@ export declare class HashMap<K = any, V = any, R = [K, V]> extends IterableEntry
      * @param predicate - Predicate (key, value, index, map) → boolean.
      * @param [thisArg] - Value for `this` inside the predicate.
      * @returns A new map containing entries that satisfied the predicate.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // HashMap iteration and filter operations
+   *  const map = new HashMap<number, string>([
+   *       [1, 'Alice'],
+   *       [2, 'Bob'],
+   *       [3, 'Charlie'],
+   *       [4, 'Diana'],
+   *       [5, 'Eve']
+   *     ]);
+   *
+   *     // Iterate through entries
+   *     const entries: [number, string][] = [];
+   *     for (const [key, value] of map) {
+   *       entries.push([key, value]);
+   *     }
+   *     console.log(entries); // length: 5;
+   *
+   *     // Filter operation (for iteration with collection methods)
+   *     const filtered = [...map].filter(([key]) => key > 2);
+   *     console.log(filtered.length); // 3;
+   *
+   *     // Map operation
+   *     const values = [...map.values()].map(v => v.length);
+   *     console.log(values); // contains 3; // 'Bob', 'Eve'
+   *     console.log(values); // contains 7;
      */
     filter(predicate: EntryCallback<K, V, boolean>, thisArg?: any): any;
     /**