typescript-dsa-stl 2.6.0 → 2.7.0

package/README.md

@@ -1,17 +1,58 @@
 # TypeScript_DSA
 
-**This is the GitHub repository** for the npm package **[typescript-dsa-stl](https://www.npmjs.com/package/typescript-dsa-stl)**.
+**Repository** for the npm package **[typescript-dsa-stl](https://www.npmjs.com/package/typescript-dsa-stl)** · [GitHub](https://github.com/SajidAbdullah729/TypeScript_DSA)
 
-STL-style data structures and algorithms for TypeScript: **Vector**, **Stack**, **Queue**, **Deque**, **List**, **PriorityQueue**, **OrderedMap** (Map), **UnorderedMap**, **OrderedSet** (Set), **UnorderedSet**, **OrderedMultiMap**, **OrderedMultiSet**, **segment trees** (`SegmentTreeSum`, `SegmentTreeMin`, `SegmentTreeMax`, `SegmentTree`, `GeneralSegmentTree`, `LazySegmentTreeSum`), and algorithms (`sort`, `binarySearch`, `lowerBound`, `min`, `max`, **KnuthMorrisPratt**, **RabinKarp**, **StringRollingHash**, etc.). Install from npm to use in your project; this repo holds the source code.
+STL-style data structures and algorithms for TypeScript: **Vector**, **Stack**, **Queue**, **Deque**, **List**, **PriorityQueue**, ordered/unordered **Map** and **Set**, **OrderedMultiMap** / **OrderedMultiSet**, **segment trees**, **graph** helpers (BFS, DFS, Dijkstra, Kruskal, DSU), and **string** algorithms (KMP, Rabin–Karp, rolling hash). Install from npm for your app; this repo is the source.
 
 ---
 
-## Install
+## Table of contents
+
+| Section | What you’ll find |
+|--------|-------------------|
+| [Installation](#installation) | npm install |
+| [Package layout & imports](#package-layout--imports) | Barrel vs subpaths (tree-shaking) |
+| [Quick start](#quick-start) | One file showing main APIs |
+| [API reference](#api-reference) | Export tables |
+| [Complexity](#complexity) | Big-O for collections and segment trees |
+| [Collections](#collections) | Deque, nested vectors, multi-map / multi-set |
+| [Segment trees](#segment-trees) | Sum/min/max, generic, lazy |
+| [Graph algorithms](#graph-algorithms) | Adjacency lists, BFS/DFS, components, MST, shortest paths |
+| [String algorithms](#string-algorithms) | KMP, Rabin–Karp, rolling hash |
+| [For maintainers](#for-maintainers) | Build and publish |
+| [License](#license) | MIT |
+
+---
+
+## Installation
 
 ```bash
 npm install typescript-dsa-stl
 ```
 
+**Runtime:** Node **18+** (see `package.json` `engines`).
+
+---
+
+## Package layout & imports
+
+Import everything from the root, or use subpaths for smaller bundles:
+
+```ts
+import { Vector, Stack, Queue, Deque } from 'typescript-dsa-stl/collections';
+import {
+  sort,
+  binarySearch,
+  breadthFirstSearch,
+  depthFirstSearch,
+  KnuthMorrisPratt,
+  RabinKarp,
+  StringRollingHash,
+} from 'typescript-dsa-stl/algorithms';
+import { clamp, range } from 'typescript-dsa-stl/utils';
+import type { Comparator } from 'typescript-dsa-stl/types';
+```
+
 ---
 
 ## Quick start
@@ -33,6 +74,8 @@ import {
   sort,
   find,
   binarySearch,
+  lowerBound,
+  upperBound,
   min,
   max,
   clamp,
@@ -112,6 +155,63 @@ clamp(42, 0, 10);       // 10
 range(0, 5);            // [0, 1, 2, 3, 4]
 ```
 
+---
+
+## API reference
+
+### Main export map
+
+| Area | Exports |
+|------|---------|
+| **Collections** | `Vector`, `Stack`, `Queue`, `Deque`, `List`, `ListNode`, `PriorityQueue`, `OrderedMap`, `UnorderedMap`, `OrderedSet`, `UnorderedSet`, `OrderedMultiMap`, `OrderedMultiSet`, `GeneralSegmentTree`, `SegmentTree`, `SegmentTreeSum`, `SegmentTreeMin`, `SegmentTreeMax`, `LazySegmentTreeSum`, `WeightedEdge`, `AdjacencyList`, `WeightedAdjacencyList`, `createAdjacencyList`, `createWeightedAdjacencyList`, `addEdge`, `deleteEdge` |
+| **Algorithms** | `sort`, `find`, `findIndex`, `transform`, `filter`, `reduce`, `reverse`, `unique`, `binarySearch`, `lowerBound`, `upperBound`, `min`, `max`, `partition`, `DisjointSetUnion`, `KnuthMorrisPratt`, `RabinKarp`, `RABIN_KARP_DEFAULT_MODS`, `StringRollingHash`, `breadthFirstSearch`, `depthFirstSearch`, `connectedComponents`, `kruskalMST`, `dijkstra`, `reconstructPath` |
+| **Utils** | `clamp`, `range`, `noop`, `identity`, `swap` |
+| **Types** | `Comparator`, `Predicate`, `UnaryFn`, `Reducer`, `IterableLike`, `toArray`, `RabinKarpTripleMods`, `WeightedUndirectedEdge`, `GeneralSegmentTreeConfig`, `SegmentCombine`, `SegmentMerge`, `SegmentLeafBuild` |
+
+### Subpath imports (tree-shaking)
+
+```ts
+import { Vector, Stack, Queue, Deque } from 'typescript-dsa-stl/collections';
+import { sort, binarySearch, breadthFirstSearch, depthFirstSearch, KnuthMorrisPratt, RabinKarp, StringRollingHash } from 'typescript-dsa-stl/algorithms';
+import { clamp, range } from 'typescript-dsa-stl/utils';
+import type { Comparator } from 'typescript-dsa-stl/types';
+```
+
+---
+
+## Complexity
+
+### Linear and associative structures
+
+| Structure | Access | Insert end | Insert middle | Remove end | Remove middle |
+|-----------|--------|------------|---------------|------------|---------------|
+| **Vector** | O(1) | O(1)* | O(n) | O(1) | O(n) |
+| **Stack** | — | O(1) | — | O(1) | — |
+| **Queue** | — | O(1)* | — | O(1)* | — |
+| **Deque** | O(1) | O(1)* (front/back) | — | O(1)* (front/back) | — |
+| **List** | O(n) | O(1) | O(1)** | O(1) | O(1)** |
+| **PriorityQueue** | — | O(log n) | — | O(log n) | — |
+| **OrderedMap** (Map) | O(log n) get | O(log n) set | — | O(log n) delete | — |
+| **UnorderedMap** | O(1)* get/set | O(1)* | — | O(1)* delete | — |
+| **OrderedSet** (Set) | O(log n) has | O(log n) add | — | O(log n) delete | — |
+| **UnorderedSet** | O(1)* has/add | O(1)* | — | O(1)* delete | — |
+| **OrderedMultiMap** | O(log n) get | O(log n) set | — | O(log n) delete | — |
+| **OrderedMultiSet** | O(log n) has/count | O(log n) add | — | O(log n) delete | — |
+
+\* Amortized (hash).  
+\** At a known node.
+
+### Segment trees
+
+| Structure | Build | Point update | Range query | Extra |
+|-----------|-------|--------------|-------------|--------|
+| **GeneralSegmentTree**, **SegmentTree**, **SegmentTreeSum** / **Min** / **Max** | O(n) | O(log n) | O(log n) | Inclusive `[l, r]`; **GeneralSegmentTree** keeps raw `V` and uses `merge` + `buildLeaf` |
+| **LazySegmentTreeSum** | O(n) | `set`: O(log n) | `rangeSum`: O(log n) | `rangeAdd` on a range: O(log n) |
+
+---
+
+## Collections
+
 ### Deque (like C++ `std::deque`)
 
 A **double-ended queue**: amortized **O(1)** `pushFront` / `pushBack` / `popFront` / `popBack`, and **O(1)** random access via `at` / `set`. Implemented as a growable circular buffer (same asymptotics as a typical `std::deque` for these operations).
@@ -178,136 +278,348 @@ cube.push(layer0);
 cube.at(0).at(1).at(0);  // 3  (layer 0, row 1, col 0)
 ```
 
-### Graph adjacency list (like C++ `vector<vector<type>> graph(n)`)
+### OrderedMultiMap and OrderedMultiSet — use cases
 
-You can model C++-style adjacency lists using the graph types and helpers exported from `typescript-dsa-stl/collections` (or the main package).
+**OrderedMultiSet** is a sorted collection that allows duplicate elements (like C++ `std::multiset`). Use it when you need ordering and multiple copies of the same value.
 
-#### Unweighted adjacency list
+| Use case | Example |
+|----------|---------|
+| **Sorted runs / leaderboard with ties** | Store scores; multiple users can have the same score. Iterate in sorted order, use `count(score)` for ties. |
+| **Event timeline with repeated timestamps** | Add events by time; several events can share the same time. `add(timestamp)`, iterate in order. |
+| **K-th smallest in a multiset** | Keep elements sorted; k-th element is at index `k - 1` in iteration. |
+| **Range counts** | Combined with binary search ideas: count elements in `[low, high]` using `count` and iteration. |
 
-C++:
+**OrderedMultiMap** maps one key to multiple values while keeping keys sorted (like C++ `std::multimap`). Use it when a key can have several associated values and you need key order.
 
-```cpp
-int n = 5;
-vector<vector<int>> graph(n);
-graph[u].push_back(v);   // or graph[u].pb(v);
-```
+| Use case | Example |
+|----------|---------|
+| **Inverted index** | Key = term, values = document IDs containing that term. `set(term, docId)` for each occurrence; `getAll(term)` returns all doc IDs. |
+| **Grouping by key** | Key = category, values = items. `set(category, item)`; iterate keys in order, use `getAll(key)` per group. |
+| **One-to-many relations** | Key = user ID, values = session IDs. `set(userId, sessionId)`; `getAll(userId)` lists all sessions. |
+| **Time-series by bucket** | Key = time bucket, values = events. Sorted keys give chronological buckets; `getAll(bucket)` gets events in that bucket. |
 
-TypeScript (easy declaration with `createAdjacencyList`):
+**OrderedMultiSet example:**
 
 ```ts
-import { createAdjacencyList } from 'typescript-dsa-stl/collections';
-
-const n = 5;
-const graph = createAdjacencyList(n);   // empty graph with n vertices
-
-// C++: graph[u].push_back(v);
-graph[u].push(v);
+import { OrderedMultiSet } from 'typescript-dsa-stl';
 
-// Iteration is the same idea as in C++
-for (const v of graph[u]) {
-  // neighbor v
-}
+const scores = new OrderedMultiSet<number>();
+scores.add(85); scores.add(92); scores.add(85); scores.add(78);
+console.log(scores.toArray());   // [78, 85, 85, 92]
+console.log(scores.count(85));   // 2
+scores.delete(85);               // remove one 85
+console.log(scores.count(85));   // 1
+scores.deleteAll(85);            // remove all 85s
 ```
 
-Or with helpers `addEdge` / `deleteEdge`:
+**OrderedMultiMap example:**
 
 ```ts
-import { createAdjacencyList, addEdge, deleteEdge } from 'typescript-dsa-stl/collections';
-
-const graph = createAdjacencyList(5);
+import { OrderedMultiMap } from 'typescript-dsa-stl';
 
-addEdge(graph, u, v);        // add u -> v
-deleteEdge(graph, u, v);     // remove all edges u -> v
+const index = new OrderedMultiMap<string, number>();  // term -> doc IDs
+index.set('typescript', 1); index.set('typescript', 3); index.set('stl', 2);
+console.log(index.getAll('typescript'));  // [1, 3]
+console.log(index.get('stl'));            // 2
+for (const [key, value] of index) {
+  console.log(key, value);               // keys in sorted order
+}
 ```
 
-#### Weighted adjacency list
+---
 
-In C++ you might write:
+## Segment trees
 
-```cpp
-int n = 5;
-vector<vector<pair<int,int>>> graph(n);
-graph[u].push_back({v, w});   // edge u -> v with weight w
-```
+Segment trees support **range queries** and **point updates** in **O(log n)**. Range endpoints are **inclusive**: `query(l, r)` covers indices `l` through `r`.
 
-In TypeScript, use `createWeightedAdjacencyList` for easy declaration:
+### Ready-made variants (`SegmentTreeSum`, `SegmentTreeMin`, `SegmentTreeMax`)
 
 ```ts
-import { createWeightedAdjacencyList } from 'typescript-dsa-stl/collections';
+import {
+  SegmentTreeSum,
+  SegmentTreeMin,
+  SegmentTreeMax,
+} from 'typescript-dsa-stl';
 
-const n = 5;
-const graph = createWeightedAdjacencyList(n);   // empty weighted graph with n vertices
+const sum = new SegmentTreeSum([1, 2, 3, 4]);
+console.log(sum.query(0, 3)); // 10
+sum.update(1, 10);
+console.log(sum.query(0, 3)); // 1 + 10 + 3 + 4 = 18
 
-// C++: graph[u].push_back({v, w});
-graph[u].push({ to: v, weight: w });
+const mn = new SegmentTreeMin([5, 2, 8, 1]);
+console.log(mn.query(0, 3)); // 1
 
-// When iterating, you get both neighbor and weight
-for (const { to, weight } of graph[u]) {
-  // edge u -> to with cost = weight
-}
+const mx = new SegmentTreeMax([5, 2, 8, 1]);
+console.log(mx.query(0, 3)); // 8
 ```
 
-Or with the helper functions `addEdge` / `deleteEdge`:
+### Generic `SegmentTree<T>` (custom combine + neutral)
+
+Use the same type for array elements and aggregates. Pass an **associative** `combine` and a **neutral** value for query ranges that miss a segment (e.g. `0` for sum, `Infinity` for min).
 
 ```ts
-import { createWeightedAdjacencyList, addEdge, deleteEdge } from 'typescript-dsa-stl/collections';
+import { SegmentTree } from 'typescript-dsa-stl';
 
-const graph = createWeightedAdjacencyList(5);
+const gcdTree = new SegmentTree<number>(
+  [12, 18, 24],
+  (a, b) => {
+    let x = a;
+    let y = b;
+    while (y !== 0) {
+      const t = y;
+      y = x % y;
+      x = t;
+    }
+    return x;
+  },
+  0
+);
+console.log(gcdTree.query(0, 2)); // gcd(12, 18, 24) === 6
 
-addEdge(graph, u, v, w);         // add u -> v with weight w
-deleteEdge(graph, u, v, w);      // delete all edges u -> v with weight w
+// Non-numeric example: concatenate strings
+const strTree = new SegmentTree<string>(
+  ['a', 'b', 'c'],
+  (a, b) => a + b,
+  ''
+);
+console.log(strTree.query(0, 2)); // 'abc'
 ```
 
-#### Graph adjacency list — use cases
-
-Use an **unweighted** graph (adjacency list) when you only care about connectivity; use a **weighted** graph when edges have costs (distance, time, capacity).
-
-| Use case | When to use |
-|----------|-------------|
-| **BFS / DFS, connectivity** | Unweighted: shortest path in terms of hop count, connected components, cycle detection. |
-| **Shortest path (Dijkstra), MST** | Weighted: edge weights as distances or costs; run Dijkstra, Prim, or Kruskal on the list. |
-| **Social / dependency graphs** | Unweighted or weighted: followers, dependencies (e.g. build order), recommendation graphs. |
-| **Grid / game graphs** | Unweighted: 4- or 8-neighbor grids; weighted if movement costs differ per cell. |
-| **Network / flow** | Weighted: capacities or latencies on edges for max-flow or routing. |
+### `GeneralSegmentTree<T, V>` (custom merge + buildLeaf)
 
-#### Breadth-first search (BFS) and depth-first search (DFS)
+Use when **raw** values `V` differ from the **aggregate** type `T`:
 
-`breadthFirstSearch` and `depthFirstSearch` take the number of vertices `n`, an unweighted `AdjacencyList`, and a `start` vertex. They return the **visit order** for all vertices **reachable** from `start` (vertices outside that component are not included). For an undirected graph, add each edge in **both** directions (see `addEdge` below).
+- **`merge(left, right)`** — combine two child aggregates (internal nodes).
+- **`neutral`** — identity for `merge` when a query does not overlap a segment.
+- **`buildLeaf(value, index)`** — build the leaf from the raw array on initial construction and on every `update`.
 
-**Example graph (diamond):** edges `0—1`, `0—2`, `1—3`, `2—3`.
+```ts
+import { GeneralSegmentTree } from 'typescript-dsa-stl';
 
-```text
-      0
-     / \
-    1   2
-     \ /
-      3
+// Store sum of squares; raw array is plain numbers
+const st = new GeneralSegmentTree<number, number>([1, 2, 3], {
+  merge: (a, b) => a + b,
+  neutral: 0,
+  buildLeaf: (v, i) => v * v + i,
+});
+console.log(st.query(0, 2)); // (1+0) + (4+1) + (9+2) = 17
+st.update(1, 4);
+console.log(st.rawAt(1)); // 4 — current raw value at index 1
 ```
 
-With neighbors listed in ascending vertex id (`0: [1,2]`, `1: [0,3]`, …), **BFS** from `0` visits by increasing distance from `0`: first `0`, then `1` and `2`, then `3` → order `[0, 1, 2, 3]`. **DFS** (preorder, first neighbor in each list first) goes `0 → 1 → 3` then `2` → order `[0, 1, 3, 2]`. The exact DFS order depends on how you order each adjacency list.
+### `LazySegmentTreeSum` (range add + range sum)
+
+**`rangeAdd(l, r, delta)`** adds `delta` to every element in the inclusive range. **`rangeSum(l, r)`** returns the sum. **`set(i, value)`** assigns one position (lazy tags are applied along the path). All are **O(log n)**.
 
 ```ts
-import {
-  createAdjacencyList,
-  addEdge,
-  breadthFirstSearch,
-  depthFirstSearch,
-} from 'typescript-dsa-stl';
+import { LazySegmentTreeSum } from 'typescript-dsa-stl';
 
-const n = 4;
-const graph = createAdjacencyList(n);
+const lazy = new LazySegmentTreeSum([0, 0, 0, 0]);
+lazy.rangeAdd(1, 2, 5); // indices 1 and 2 get +5
+console.log(lazy.rangeSum(0, 3)); // 10
+lazy.set(0, 100);
+console.log(lazy.rangeSum(0, 3)); // 100 + 5 + 5 + 0
+```
 
-// Undirected diamond: add both directions for each edge
-addEdge(graph, 0, 1);
-addEdge(graph, 1, 0);
-addEdge(graph, 0, 2);
-addEdge(graph, 2, 0);
-addEdge(graph, 1, 3);
-addEdge(graph, 3, 1);
-addEdge(graph, 2, 3);
-addEdge(graph, 3, 2);
+### Real-world use cases
 
-const start = 0;
+These patterns show up in backends and internal tools when you need **many** range queries and updates on a fixed sequence (length known up front), without scanning the whole array each time.
+
+#### 1. Analytics or reporting: totals over a time window (with corrections)
+
+Each index is a **fixed bucket** (hour of day, day of month, version slot, etc.). You repeatedly ask “what is the **sum** from bucket `a` through `b`?” and sometimes **fix one bucket** after late data or a reconciliation.
+
+```ts
+import { SegmentTreeSum } from 'typescript-dsa-stl';
+
+/** Revenue (or events, page views, API calls) per calendar day; index 0 = first day of period. */
+class PeriodMetrics {
+  private readonly tree: SegmentTreeSum;
+
+  constructor(dailyValues: readonly number[]) {
+    this.tree = new SegmentTreeSum(dailyValues);
+  }
+
+  /** Total for an inclusive day range — e.g. chart drill-down or export row. */
+  totalBetweenDay(firstDayIndex: number, lastDayIndex: number): number {
+    return this.tree.query(firstDayIndex, lastDayIndex);
+  }
+
+  /** Backfill or correct one day without rebuilding the whole series. */
+  setDay(dayIndex: number, amount: number): void {
+    this.tree.update(dayIndex, amount);
+  }
+}
+
+const january = new PeriodMetrics([1200, 980, 1100, 1050, 1300]);
+console.log(january.totalBetweenDay(0, 4)); // full period
+january.setDay(2, 1150); // corrected day 2
+console.log(january.totalBetweenDay(1, 3)); // sum over days 1..3
+```
+
+In production you would usually **persist** the underlying series in a database and **rebuild** the tree when the period reloads; the tree stays useful in memory for dashboards, simulations, or request handlers that see heavy read/update traffic on the same window.
+
+#### 2. Operations or finance: bulk adjustment on a slice, then aggregate
+
+You apply the **same delta** to **every** element in an index range (tiered bonuses, prorated credits, simulation shocks), then need **range sums** for reporting. A lazy sum tree avoids touching each cell one by one.
+
+```ts
+import { LazySegmentTreeSum } from 'typescript-dsa-stl';
+
+/** Example: per-seat or per-row amounts; apply a flat bonus to ranks 10–50 (0-based 9..49), then sum a sub-range for a sub-team. */
+function simulateBulkBonusAndSubtotal(seatCount: number): void {
+  // Initial per-seat values (e.g. base commission), built once
+  const base = Array.from({ length: seatCount }, (_, i) => 100 + i);
+  const amounts = new LazySegmentTreeSum(base);
+
+  // HR: +250 to everyone in seats 10–50 inclusive (indices 9..49)
+  amounts.rangeAdd(9, 49, 250);
+
+  // Finance: subtotal for seats 20–30 only
+  console.log(amounts.rangeSum(19, 29));
+}
+
+simulateBulkBonusAndSubtotal(100);
+```
+
+The same idea applies to **inventory deltas** across bin ranges, **loyalty points** batch credits by user-ID band (when IDs map to contiguous indices), or **game/simulation** state where many cells gain the same buff and you query partial totals.
+
+---
+
+## Graph algorithms
+
+Graph helpers live on the main package and under `typescript-dsa-stl/collections` for adjacency types and factories.
+
+### Adjacency list (like C++ `vector<vector<type>> graph(n)`)
+
+You can model C++-style adjacency lists using the graph types and helpers exported from `typescript-dsa-stl/collections` (or the main package).
+
+#### Unweighted adjacency list
+
+C++:
+
+```cpp
+int n = 5;
+vector<vector<int>> graph(n);
+graph[u].push_back(v);   // or graph[u].pb(v);
+```
+
+TypeScript (easy declaration with `createAdjacencyList`):
+
+```ts
+import { createAdjacencyList } from 'typescript-dsa-stl/collections';
+
+const n = 5;
+const graph = createAdjacencyList(n);   // empty graph with n vertices
+
+// C++: graph[u].push_back(v);
+graph[u].push(v);
+
+// Iteration is the same idea as in C++
+for (const v of graph[u]) {
+  // neighbor v
+}
+```
+
+Or with helpers `addEdge` / `deleteEdge`:
+
+```ts
+import { createAdjacencyList, addEdge, deleteEdge } from 'typescript-dsa-stl/collections';
+
+const graph = createAdjacencyList(5);
+
+addEdge(graph, u, v);        // add u -> v
+deleteEdge(graph, u, v);     // remove all edges u -> v
+```
+
+#### Weighted adjacency list
+
+In C++ you might write:
+
+```cpp
+int n = 5;
+vector<vector<pair<int,int>>> graph(n);
+graph[u].push_back({v, w});   // edge u -> v with weight w
+```
+
+In TypeScript, use `createWeightedAdjacencyList` for easy declaration:
+
+```ts
+import { createWeightedAdjacencyList } from 'typescript-dsa-stl/collections';
+
+const n = 5;
+const graph = createWeightedAdjacencyList(n);   // empty weighted graph with n vertices
+
+// C++: graph[u].push_back({v, w});
+graph[u].push({ to: v, weight: w });
+
+// When iterating, you get both neighbor and weight
+for (const { to, weight } of graph[u]) {
+  // edge u -> to with cost = weight
+}
+```
+
+Or with the helper functions `addEdge` / `deleteEdge`:
+
+```ts
+import { createWeightedAdjacencyList, addEdge, deleteEdge } from 'typescript-dsa-stl/collections';
+
+const graph = createWeightedAdjacencyList(5);
+
+addEdge(graph, u, v, w);         // add u -> v with weight w
+deleteEdge(graph, u, v, w);      // delete all edges u -> v with weight w
+```
+
+#### Graph adjacency list — use cases
+
+Use an **unweighted** graph (adjacency list) when you only care about connectivity; use a **weighted** graph when edges have costs (distance, time, capacity).
+
+| Use case | When to use |
+|----------|-------------|
+| **BFS / DFS, connectivity** | Unweighted: shortest path in terms of hop count, connected components, cycle detection. |
+| **Shortest path (Dijkstra), MST** | Weighted: edge weights as distances or costs; run Dijkstra, Prim, or Kruskal on the list. |
+| **Social / dependency graphs** | Unweighted or weighted: followers, dependencies (e.g. build order), recommendation graphs. |
+| **Grid / game graphs** | Unweighted: 4- or 8-neighbor grids; weighted if movement costs differ per cell. |
+| **Network / flow** | Weighted: capacities or latencies on edges for max-flow or routing. |
+
+### Breadth-first search (BFS) and depth-first search (DFS)
+
+`breadthFirstSearch` and `depthFirstSearch` take the number of vertices `n`, an unweighted `AdjacencyList`, and a `start` vertex. They return the **visit order** for all vertices **reachable** from `start` (vertices outside that component are not included). For an undirected graph, add each edge in **both** directions (see `addEdge` below).
+
+**Example graph (diamond):** edges `0—1`, `0—2`, `1—3`, `2—3`.
+
+```text
+      0
+     / \
+    1   2
+     \ /
+      3
+```
+
+With neighbors listed in ascending vertex id (`0: [1,2]`, `1: [0,3]`, …), **BFS** from `0` visits by increasing distance from `0`: first `0`, then `1` and `2`, then `3` → order `[0, 1, 2, 3]`. **DFS** (preorder, first neighbor in each list first) goes `0 → 1 → 3` then `2` → order `[0, 1, 3, 2]`. The exact DFS order depends on how you order each adjacency list.
+
+```ts
+import {
+  createAdjacencyList,
+  addEdge,
+  breadthFirstSearch,
+  depthFirstSearch,
+} from 'typescript-dsa-stl';
+
+const n = 4;
+const graph = createAdjacencyList(n);
+
+// Undirected diamond: add both directions for each edge
+addEdge(graph, 0, 1);
+addEdge(graph, 1, 0);
+addEdge(graph, 0, 2);
+addEdge(graph, 2, 0);
+addEdge(graph, 1, 3);
+addEdge(graph, 3, 1);
+addEdge(graph, 2, 3);
+addEdge(graph, 3, 2);
+
+const start = 0;
 
 // BFS: level-by-level from start (hop count); output: [0, 1, 2, 3]
 console.log(breadthFirstSearch(n, graph, start));
@@ -334,7 +646,7 @@ console.log(breadthFirstSearch(5, withIsolated, 0)); // [0, 1] — not [0,1,2,3,
 - **Disconnected graphs:** run again from another unvisited `start`, or use `connectedComponents` to enumerate components first.
 - **Weighted graphs:** for traversal ignoring weights, use the same vertex lists as the unweighted graph (weights are ignored by these two functions).
 
-#### Disjoint Set Union (Union-Find)
+### Disjoint Set Union (Union-Find)
 
 Use Union-Find (DSU) to compute connected components efficiently. It merges endpoints of every edge in the adjacency list, so for directed graphs it returns weak connectivity components.
 
@@ -352,7 +664,7 @@ const comps = connectedComponents(n, graph);
 // e.g. [[0, 1], [2], [3, 4]]
 ```
 
-##### Traverse the result
+#### Traverse the result
 
 `connectedComponents(n, adj)` returns `number[][]` where each inner array is a component (list of vertices).
 
@@ -369,7 +681,7 @@ for (const comp of comps) {
 const sizes = comps.map(comp => comp.length);
 ```
 
-#### Kruskal MST (uses DSU)
+### Kruskal MST (uses DSU)
 
 For a weighted graph, `kruskalMST` builds a Minimum Spanning Tree (MST) using DSU.
 
@@ -393,7 +705,28 @@ const { edges, totalWeight } = kruskalMST(n, wGraph, { undirected: true });
 // edges: MST edges (chosen by weight), totalWeight: sum of weights
 ```
 
-#### Dijkstra shortest paths
+#### Traverse the MST
+
+`kruskalMST(...)` returns `{ edges, totalWeight }`. To traverse the MST like a graph, convert `edges` into an adjacency list:
+
+```ts
+import { createWeightedAdjacencyList } from 'typescript-dsa-stl/collections';
+
+const mstAdj = createWeightedAdjacencyList(n);
+
+for (const { u, v, weight } of edges) {
+  // MST is undirected (we used { undirected: true })
+  mstAdj[u].push({ to: v, weight });
+  mstAdj[v].push({ to: u, weight });
+}
+
+// Example: iterate neighbors of vertex 0 in the MST
+for (const { to, weight } of mstAdj[0]) {
+  // visit edge 0 -> to (weight)
+}
+```
+
+### Dijkstra shortest paths
 
 `dijkstra` computes single-source shortest paths on a **weighted** graph with **non-negative** edge weights.
 It returns:
@@ -425,32 +758,15 @@ const path = reconstructPath(prev, 0, target); // [0, ..., target] or [] if unre
 console.log(path); // [0, 1, 2, 4]
 ```
 
-##### Traverse the MST
-
-`kruskalMST(...)` returns `{ edges, totalWeight }`. To traverse the MST like a graph, convert `edges` into an adjacency list:
-
-```ts
-import { createWeightedAdjacencyList } from 'typescript-dsa-stl/collections';
-
-const mstAdj = createWeightedAdjacencyList(n);
-
-for (const { u, v, weight } of edges) {
-  // MST is undirected (we used { undirected: true })
-  mstAdj[u].push({ to: v, weight });
-  mstAdj[v].push({ to: u, weight });
-}
+---
 
-// Example: iterate neighbors of vertex 0 in the MST
-for (const { to, weight } of mstAdj[0]) {
-  // visit edge 0 -> to (weight)
-}
-```
+## String algorithms
 
-#### Knuth–Morris–Pratt (KMP), Rabin–Karp, and string rolling hash
+### Knuth–Morris–Pratt (KMP), Rabin–Karp, and string rolling hash
 
 All three work on **UTF-16 code units** (same as `String` indexing). They solve **different jobs**: KMP and Rabin–Karp are **pattern matchers** (list all start indices of a pattern in a text). `StringRollingHash` is a **substring-hash tool** on a **fixed** string—you combine it with your own logic (equality checks, binary search, etc.).
 
-##### When to use which
+#### When to use which
 
 | Goal | Prefer | Why |
 |------|--------|-----|
@@ -555,263 +871,6 @@ console.log(a.substringHash(2, 2) === b.fullHash()); // true — both are "na"
 
 ---
 
-## Segment trees
-
-Segment trees support **range queries** and **point updates** in **O(log n)**. Range endpoints are **inclusive**: `query(l, r)` covers indices `l` through `r`.
-
-### Ready-made variants (`SegmentTreeSum`, `SegmentTreeMin`, `SegmentTreeMax`)
-
-```ts
-import {
-  SegmentTreeSum,
-  SegmentTreeMin,
-  SegmentTreeMax,
-} from 'typescript-dsa-stl';
-
-const sum = new SegmentTreeSum([1, 2, 3, 4]);
-console.log(sum.query(0, 3)); // 10
-sum.update(1, 10);
-console.log(sum.query(0, 3)); // 1 + 10 + 3 + 4 = 18
-
-const mn = new SegmentTreeMin([5, 2, 8, 1]);
-console.log(mn.query(0, 3)); // 1
-
-const mx = new SegmentTreeMax([5, 2, 8, 1]);
-console.log(mx.query(0, 3)); // 8
-```
-
-### Generic `SegmentTree<T>` (custom combine + neutral)
-
-Use the same type for array elements and aggregates. Pass an **associative** `combine` and a **neutral** value for query ranges that miss a segment (e.g. `0` for sum, `Infinity` for min).
-
-```ts
-import { SegmentTree } from 'typescript-dsa-stl';
-
-const gcdTree = new SegmentTree<number>(
-  [12, 18, 24],
-  (a, b) => {
-    let x = a;
-    let y = b;
-    while (y !== 0) {
-      const t = y;
-      y = x % y;
-      x = t;
-    }
-    return x;
-  },
-  0
-);
-console.log(gcdTree.query(0, 2)); // gcd(12, 18, 24) === 6
-
-// Non-numeric example: concatenate strings
-const strTree = new SegmentTree<string>(
-  ['a', 'b', 'c'],
-  (a, b) => a + b,
-  ''
-);
-console.log(strTree.query(0, 2)); // 'abc'
-```
-
-### `GeneralSegmentTree<T, V>` (custom merge + buildLeaf)
-
-Use when **raw** values `V` differ from the **aggregate** type `T`:
-
-- **`merge(left, right)`** — combine two child aggregates (internal nodes).
-- **`neutral`** — identity for `merge` when a query does not overlap a segment.
-- **`buildLeaf(value, index)`** — build the leaf from the raw array on initial construction and on every `update`.
-
-```ts
-import { GeneralSegmentTree } from 'typescript-dsa-stl';
-
-// Store sum of squares; raw array is plain numbers
-const st = new GeneralSegmentTree<number, number>([1, 2, 3], {
-  merge: (a, b) => a + b,
-  neutral: 0,
-  buildLeaf: (v, i) => v * v + i,
-});
-console.log(st.query(0, 2)); // (1+0) + (4+1) + (9+2) = 17
-st.update(1, 4);
-console.log(st.rawAt(1)); // 4 — current raw value at index 1
-```
-
-### `LazySegmentTreeSum` (range add + range sum)
-
-**`rangeAdd(l, r, delta)`** adds `delta` to every element in the inclusive range. **`rangeSum(l, r)`** returns the sum. **`set(i, value)`** assigns one position (lazy tags are applied along the path). All are **O(log n)**.
-
-```ts
-import { LazySegmentTreeSum } from 'typescript-dsa-stl';
-
-const lazy = new LazySegmentTreeSum([0, 0, 0, 0]);
-lazy.rangeAdd(1, 2, 5); // indices 1 and 2 get +5
-console.log(lazy.rangeSum(0, 3)); // 10
-lazy.set(0, 100);
-console.log(lazy.rangeSum(0, 3)); // 100 + 5 + 5 + 0
-```
-
-### Real-world use cases
-
-These patterns show up in backends and internal tools when you need **many** range queries and updates on a fixed sequence (length known up front), without scanning the whole array each time.
-
-#### 1. Analytics or reporting: totals over a time window (with corrections)
-
-Each index is a **fixed bucket** (hour of day, day of month, version slot, etc.). You repeatedly ask “what is the **sum** from bucket `a` through `b`?” and sometimes **fix one bucket** after late data or a reconciliation.
-
-```ts
-import { SegmentTreeSum } from 'typescript-dsa-stl';
-
-/** Revenue (or events, page views, API calls) per calendar day; index 0 = first day of period. */
-class PeriodMetrics {
-  private readonly tree: SegmentTreeSum;
-
-  constructor(dailyValues: readonly number[]) {
-    this.tree = new SegmentTreeSum(dailyValues);
-  }
-
-  /** Total for an inclusive day range — e.g. chart drill-down or export row. */
-  totalBetweenDay(firstDayIndex: number, lastDayIndex: number): number {
-    return this.tree.query(firstDayIndex, lastDayIndex);
-  }
-
-  /** Backfill or correct one day without rebuilding the whole series. */
-  setDay(dayIndex: number, amount: number): void {
-    this.tree.update(dayIndex, amount);
-  }
-}
-
-const january = new PeriodMetrics([1200, 980, 1100, 1050, 1300]);
-console.log(january.totalBetweenDay(0, 4)); // full period
-january.setDay(2, 1150); // corrected day 2
-console.log(january.totalBetweenDay(1, 3)); // sum over days 1..3
-```
-
-In production you would usually **persist** the underlying series in a database and **rebuild** the tree when the period reloads; the tree stays useful in memory for dashboards, simulations, or request handlers that see heavy read/update traffic on the same window.
-
-#### 2. Operations or finance: bulk adjustment on a slice, then aggregate
-
-You apply the **same delta** to **every** element in an index range (tiered bonuses, prorated credits, simulation shocks), then need **range sums** for reporting. A lazy sum tree avoids touching each cell one by one.
-
-```ts
-import { LazySegmentTreeSum } from 'typescript-dsa-stl';
-
-/** Example: per-seat or per-row amounts; apply a flat bonus to ranks 10–50 (0-based 9..49), then sum a sub-range for a sub-team. */
-function simulateBulkBonusAndSubtotal(seatCount: number): void {
-  // Initial per-seat values (e.g. base commission), built once
-  const base = Array.from({ length: seatCount }, (_, i) => 100 + i);
-  const amounts = new LazySegmentTreeSum(base);
-
-  // HR: +250 to everyone in seats 10–50 inclusive (indices 9..49)
-  amounts.rangeAdd(9, 49, 250);
-
-  // Finance: subtotal for seats 20–30 only
-  console.log(amounts.rangeSum(19, 29));
-}
-
-simulateBulkBonusAndSubtotal(100);
-```
-
-The same idea applies to **inventory deltas** across bin ranges, **loyalty points** batch credits by user-ID band (when IDs map to contiguous indices), or **game/simulation** state where many cells gain the same buff and you query partial totals.
-
----
-
-## API overview
-
-| Module | Exports |
-|--------|--------|
-| **Collections** | `Vector`, `Stack`, `Queue`, `Deque`, `List`, `ListNode`, `PriorityQueue`, `OrderedMap`, `UnorderedMap`, `OrderedSet`, `UnorderedSet`, `OrderedMultiMap`, `OrderedMultiSet`, `GeneralSegmentTree`, `SegmentTree`, `SegmentTreeSum`, `SegmentTreeMin`, `SegmentTreeMax`, `LazySegmentTreeSum`, `WeightedEdge`, `AdjacencyList`, `WeightedAdjacencyList`, `createAdjacencyList`, `createWeightedAdjacencyList`, `addEdge`, `deleteEdge` |
-| **Algorithms** | `sort`, `find`, `findIndex`, `transform`, `filter`, `reduce`, `reverse`, `unique`, `binarySearch`, `lowerBound`, `upperBound`, `min`, `max`, `partition`, `DisjointSetUnion`, `KnuthMorrisPratt`, `RabinKarp`, `RABIN_KARP_DEFAULT_MODS`, `StringRollingHash`, `breadthFirstSearch`, `depthFirstSearch`, `connectedComponents`, `kruskalMST` |
-| **Utils** | `clamp`, `range`, `noop`, `identity`, `swap` |
-| **Types** | `Comparator`, `Predicate`, `UnaryFn`, `Reducer`, `IterableLike`, `toArray`, `RabinKarpTripleMods`, `GeneralSegmentTreeConfig`, `SegmentCombine`, `SegmentMerge`, `SegmentLeafBuild` |
-
-### Subpath imports (tree-shaking)
-
-```ts
-import { Vector, Stack, Queue, Deque } from 'typescript-dsa-stl/collections';
-import { sort, binarySearch, breadthFirstSearch, depthFirstSearch, KnuthMorrisPratt, RabinKarp, StringRollingHash } from 'typescript-dsa-stl/algorithms';
-import { clamp, range } from 'typescript-dsa-stl/utils';
-import type { Comparator } from 'typescript-dsa-stl/types';
-```
-
----
-
-## Data structures
-
-| Structure | Access | Insert end | Insert middle | Remove end | Remove middle |
-|-----------|--------|------------|---------------|------------|---------------|
-| **Vector** | O(1) | O(1)* | O(n) | O(1) | O(n) |
-| **Stack** | — | O(1) | — | O(1) | — |
-| **Queue** | — | O(1)* | — | O(1)* | — |
-| **Deque** | O(1) | O(1)* (front/back) | — | O(1)* (front/back) | — |
-| **List** | O(n) | O(1) | O(1)** | O(1) | O(1)** |
-| **PriorityQueue** | — | O(log n) | — | O(log n) | — |
-| **OrderedMap** (Map) | O(log n) get | O(log n) set | — | O(log n) delete | — |
-| **UnorderedMap** | O(1)* get/set | O(1)* | — | O(1)* delete | — |
-| **OrderedSet** (Set) | O(log n) has | O(log n) add | — | O(log n) delete | — |
-| **UnorderedSet** | O(1)* has/add | O(1)* | — | O(1)* delete | — |
-| **OrderedMultiMap** | O(log n) get | O(log n) set | — | O(log n) delete | — |
-| **OrderedMultiSet** | O(log n) has/count | O(log n) add | — | O(log n) delete | — |
-
-\* Amortized (hash).  
-\** At a known node.
-
-### Segment trees (range queries)
-
-| Structure | Build | Point update | Range query | Extra |
-|-----------|-------|--------------|-------------|--------|
-| **GeneralSegmentTree**, **SegmentTree**, **SegmentTreeSum** / **Min** / **Max** | O(n) | O(log n) | O(log n) | Inclusive `[l, r]`; **GeneralSegmentTree** keeps raw `V` and uses `merge` + `buildLeaf` |
-| **LazySegmentTreeSum** | O(n) | `set`: O(log n) | `rangeSum`: O(log n) | `rangeAdd` on a range: O(log n) |
-
----
-
-## OrderedMultiMap and OrderedMultiSet — use cases
-
-**OrderedMultiSet** is a sorted collection that allows duplicate elements (like C++ `std::multiset`). Use it when you need ordering and multiple copies of the same value.
-
-| Use case | Example |
-|----------|---------|
-| **Sorted runs / leaderboard with ties** | Store scores; multiple users can have the same score. Iterate in sorted order, use `count(score)` for ties. |
-| **Event timeline with repeated timestamps** | Add events by time; several events can share the same time. `add(timestamp)`, iterate in order. |
-| **K-th smallest in a multiset** | Keep elements sorted; k-th element is at index `k - 1` in iteration. |
-| **Range counts** | Combined with binary search ideas: count elements in `[low, high]` using `count` and iteration. |
-
-**OrderedMultiMap** maps one key to multiple values while keeping keys sorted (like C++ `std::multimap`). Use it when a key can have several associated values and you need key order.
-
-| Use case | Example |
-|----------|---------|
-| **Inverted index** | Key = term, values = document IDs containing that term. `set(term, docId)` for each occurrence; `getAll(term)` returns all doc IDs. |
-| **Grouping by key** | Key = category, values = items. `set(category, item)`; iterate keys in order, use `getAll(key)` per group. |
-| **One-to-many relations** | Key = user ID, values = session IDs. `set(userId, sessionId)`; `getAll(userId)` lists all sessions. |
-| **Time-series by bucket** | Key = time bucket, values = events. Sorted keys give chronological buckets; `getAll(bucket)` gets events in that bucket. |
-
-### OrderedMultiSet example
-
-```ts
-import { OrderedMultiSet } from 'typescript-dsa-stl';
-
-const scores = new OrderedMultiSet<number>();
-scores.add(85); scores.add(92); scores.add(85); scores.add(78);
-console.log(scores.toArray());   // [78, 85, 85, 92]
-console.log(scores.count(85));   // 2
-scores.delete(85);               // remove one 85
-console.log(scores.count(85));   // 1
-scores.deleteAll(85);            // remove all 85s
-```
-
-### OrderedMultiMap example
-
-```ts
-import { OrderedMultiMap } from 'typescript-dsa-stl';
-
-const index = new OrderedMultiMap<string, number>();  // term -> doc IDs
-index.set('typescript', 1); index.set('typescript', 3); index.set('stl', 2);
-console.log(index.getAll('typescript'));  // [1, 3]
-console.log(index.get('stl'));            // 2
-for (const [key, value] of index) {
-  console.log(key, value);               // keys in sorted order
-}
-```
-
----
-
 ## For maintainers
 
 - **Build:** `npm run build` (also runs before `npm publish` via `prepublishOnly`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typescript-dsa-stl",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "STL-style data structures and algorithms for TypeScript: Vector, Stack, Queue, Deque (double-ended queue), List, PriorityQueue, Map, Set, sort, binarySearch, graph utilities. Use like C++ STL.",
   "type": "module",
   "main": "dist/index.js",