directed-graph-typed 2.1.1 → 2.1.2

package/dist/cjs/index.cjs

@@ -0,0 +1,2798 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/utils/utils.ts
+var uuidV4 = /* @__PURE__ */ __name(function() {
+  return "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".replace(/[x]/g, function(c) {
+    const r = Math.random() * 16 | 0, v = c == "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}, "uuidV4");
+var arrayRemove = /* @__PURE__ */ __name(function(array, predicate) {
+  let i = -1, len = array ? array.length : 0;
+  const result = [];
+  while (++i < len) {
+    const value = array[i];
+    if (predicate(value, i, array)) {
+      result.push(value);
+      Array.prototype.splice.call(array, i--, 1);
+      len--;
+    }
+  }
+  return result;
+}, "arrayRemove");
+function isPrimitiveComparable(value) {
+  const valueType = typeof value;
+  if (valueType === "number") return true;
+  return valueType === "bigint" || valueType === "string" || valueType === "boolean";
+}
+__name(isPrimitiveComparable, "isPrimitiveComparable");
+function tryObjectToPrimitive(obj) {
+  if (typeof obj.valueOf === "function") {
+    const valueOfResult = obj.valueOf();
+    if (valueOfResult !== obj) {
+      if (isPrimitiveComparable(valueOfResult)) return valueOfResult;
+      if (typeof valueOfResult === "object" && valueOfResult !== null) return tryObjectToPrimitive(valueOfResult);
+    }
+  }
+  if (typeof obj.toString === "function") {
+    const stringResult = obj.toString();
+    if (stringResult !== "[object Object]") return stringResult;
+  }
+  return null;
+}
+__name(tryObjectToPrimitive, "tryObjectToPrimitive");
+function isComparable(value, isForceObjectComparable = false) {
+  if (value === null || value === void 0) return false;
+  if (isPrimitiveComparable(value)) return true;
+  if (typeof value !== "object") return false;
+  if (value instanceof Date) return true;
+  if (isForceObjectComparable) return true;
+  const comparableValue = tryObjectToPrimitive(value);
+  if (comparableValue === null || comparableValue === void 0) return false;
+  return isPrimitiveComparable(comparableValue);
+}
+__name(isComparable, "isComparable");
+
+// src/data-structures/base/iterable-entry-base.ts
+var _IterableEntryBase = class _IterableEntryBase {
+  /**
+   * Default iterator yielding `[key, value]` entries.
+   * @returns Iterator of `[K, V]`.
+   * @remarks Time O(n) to iterate, Space O(1)
+   */
+  *[Symbol.iterator](...args) {
+    yield* this._getIterator(...args);
+  }
+  /**
+   * Iterate over `[key, value]` pairs (may yield `undefined` values).
+   * @returns Iterator of `[K, V | undefined]`.
+   * @remarks Time O(n), Space O(1)
+   */
+  *entries() {
+    for (const item of this) {
+      yield item;
+    }
+  }
+  /**
+   * Iterate over keys only.
+   * @returns Iterator of keys.
+   * @remarks Time O(n), Space O(1)
+   */
+  *keys() {
+    for (const item of this) {
+      yield item[0];
+    }
+  }
+  /**
+   * Iterate over values only.
+   * @returns Iterator of values.
+   * @remarks Time O(n), Space O(1)
+   */
+  *values() {
+    for (const item of this) {
+      yield item[1];
+    }
+  }
+  /**
+   * Test whether all entries satisfy the predicate.
+   * @param predicate - `(key, value, index, self) => boolean`.
+   * @param thisArg - Optional `this` for callback.
+   * @returns `true` if all pass; otherwise `false`.
+   * @remarks Time O(n), Space O(1)
+   */
+  every(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (!predicate.call(thisArg, item[0], item[1], index++, this)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Test whether any entry satisfies the predicate.
+   * @param predicate - `(key, value, index, self) => boolean`.
+   * @param thisArg - Optional `this` for callback.
+   * @returns `true` if any passes; otherwise `false`.
+   * @remarks Time O(n), Space O(1)
+   */
+  some(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (predicate.call(thisArg, item[0], item[1], index++, this)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Visit each entry, left-to-right.
+   * @param callbackfn - `(key, value, index, self) => void`.
+   * @param thisArg - Optional `this` for callback.
+   * @remarks Time O(n), Space O(1)
+   */
+  forEach(callbackfn, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      const [key, value] = item;
+      callbackfn.call(thisArg, key, value, index++, this);
+    }
+  }
+  /**
+   * Find the first entry that matches a predicate.
+   * @param callbackfn - `(key, value, index, self) => boolean`.
+   * @param thisArg - Optional `this` for callback.
+   * @returns Matching `[key, value]` or `undefined`.
+   * @remarks Time O(n), Space O(1)
+   */
+  find(callbackfn, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      const [key, value] = item;
+      if (callbackfn.call(thisArg, key, value, index++, this)) return item;
+    }
+    return;
+  }
+  /**
+   * Whether the given key exists.
+   * @param key - Key to test.
+   * @returns `true` if found; otherwise `false`.
+   * @remarks Time O(n) generic, Space O(1)
+   */
+  has(key) {
+    for (const item of this) {
+      const [itemKey] = item;
+      if (itemKey === key) return true;
+    }
+    return false;
+  }
+  /**
+   * Whether there exists an entry with the given value.
+   * @param value - Value to test.
+   * @returns `true` if found; otherwise `false`.
+   * @remarks Time O(n), Space O(1)
+   */
+  hasValue(value) {
+    for (const [, elementValue] of this) {
+      if (elementValue === value) return true;
+    }
+    return false;
+  }
+  /**
+   * Get the value under a key.
+   * @param key - Key to look up.
+   * @returns Value or `undefined`.
+   * @remarks Time O(n) generic, Space O(1)
+   */
+  get(key) {
+    for (const item of this) {
+      const [itemKey, value] = item;
+      if (itemKey === key) return value;
+    }
+    return;
+  }
+  /**
+   * Reduce entries into a single accumulator.
+   * @param callbackfn - `(acc, value, key, index, self) => acc`.
+   * @param initialValue - Initial accumulator.
+   * @returns Final accumulator.
+   * @remarks Time O(n), Space O(1)
+   */
+  reduce(callbackfn, initialValue) {
+    let accumulator = initialValue;
+    let index = 0;
+    for (const item of this) {
+      const [key, value] = item;
+      accumulator = callbackfn(accumulator, value, key, index++, this);
+    }
+    return accumulator;
+  }
+  /**
+   * Visualize the iterable as an array of `[key, value]` pairs (or a custom string).
+   * @returns Array of entries (default) or a string.
+   * @remarks Time O(n), Space O(n)
+   */
+  toVisual() {
+    return [...this];
+  }
+  /**
+   * Print a human-friendly representation to the console.
+   * @remarks Time O(n), Space O(n)
+   */
+  print() {
+    console.log(this.toVisual());
+  }
+};
+__name(_IterableEntryBase, "IterableEntryBase");
+var IterableEntryBase = _IterableEntryBase;
+
+// src/data-structures/base/iterable-element-base.ts
+var _IterableElementBase = class _IterableElementBase {
+  /**
+   * Create a new iterable base.
+   *
+   * @param options Optional behavior overrides. When provided, a `toElementFn`
+   * is used to convert a raw element (`R`) into a public element (`E`).
+   *
+   * @remarks
+   * Time O(1), Space O(1).
+   */
+  constructor(options) {
+    /**
+     * The converter used to transform a raw element (`R`) into a public element (`E`).
+     *
+     * @remarks
+     * Time O(1), Space O(1).
+     */
+    __publicField(this, "_toElementFn");
+    if (options) {
+      const { toElementFn } = options;
+      if (typeof toElementFn === "function") this._toElementFn = toElementFn;
+      else if (toElementFn) throw new TypeError("toElementFn must be a function type");
+    }
+  }
+  /**
+   * Exposes the current `toElementFn`, if configured.
+   *
+   * @returns The converter function or `undefined` when not set.
+   * @remarks
+   * Time O(1), Space O(1).
+   */
+  get toElementFn() {
+    return this._toElementFn;
+  }
+  /**
+   * Returns an iterator over the structure's elements.
+   *
+   * @param args Optional iterator arguments forwarded to the internal iterator.
+   * @returns An `IterableIterator<E>` that yields the elements in traversal order.
+   *
+   * @remarks
+   * Producing the iterator is O(1); consuming the entire iterator is Time O(n) with O(1) extra space.
+   */
+  *[Symbol.iterator](...args) {
+    yield* this._getIterator(...args);
+  }
+  /**
+   * Returns an iterator over the values (alias of the default iterator).
+   *
+   * @returns An `IterableIterator<E>` over all elements.
+   * @remarks
+   * Creating the iterator is O(1); full iteration is Time O(n), Space O(1).
+   */
+  *values() {
+    for (const item of this) yield item;
+  }
+  /**
+   * Tests whether all elements satisfy the predicate.
+   *
+   * @template TReturn
+   * @param predicate Function invoked for each element with signature `(value, index, self)`.
+   * @param thisArg Optional `this` binding for the predicate.
+   * @returns `true` if every element passes; otherwise `false`.
+   *
+   * @remarks
+   * Time O(n) in the worst case; may exit early when the first failure is found. Space O(1).
+   */
+  every(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        if (!predicate(item, index++, this)) return false;
+      } else {
+        const fn = predicate;
+        if (!fn.call(thisArg, item, index++, this)) return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Tests whether at least one element satisfies the predicate.
+   *
+   * @param predicate Function invoked for each element with signature `(value, index, self)`.
+   * @param thisArg Optional `this` binding for the predicate.
+   * @returns `true` if any element passes; otherwise `false`.
+   *
+   * @remarks
+   * Time O(n) in the worst case; may exit early on first success. Space O(1).
+   */
+  some(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        if (predicate(item, index++, this)) return true;
+      } else {
+        const fn = predicate;
+        if (fn.call(thisArg, item, index++, this)) return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Invokes a callback for each element in iteration order.
+   *
+   * @param callbackfn Function invoked per element with signature `(value, index, self)`.
+   * @param thisArg Optional `this` binding for the callback.
+   * @returns `void`.
+   *
+   * @remarks
+   * Time O(n), Space O(1).
+   */
+  forEach(callbackfn, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        callbackfn(item, index++, this);
+      } else {
+        const fn = callbackfn;
+        fn.call(thisArg, item, index++, this);
+      }
+    }
+  }
+  // Implementation signature
+  find(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        if (predicate(item, index++, this)) return item;
+      } else {
+        const fn = predicate;
+        if (fn.call(thisArg, item, index++, this)) return item;
+      }
+    }
+    return;
+  }
+  /**
+   * Checks whether a strictly-equal element exists in the structure.
+   *
+   * @param element The element to test with `===` equality.
+   * @returns `true` if an equal element is found; otherwise `false`.
+   *
+   * @remarks
+   * Time O(n) in the worst case. Space O(1).
+   */
+  has(element) {
+    for (const ele of this) if (ele === element) return true;
+    return false;
+  }
+  /**
+   * Reduces all elements to a single accumulated value.
+   *
+   * @overload
+   * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`. The first element is used as the initial accumulator.
+   * @returns The final accumulated value typed as `E`.
+   *
+   * @overload
+   * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`.
+   * @param initialValue The initial accumulator value of type `E`.
+   * @returns The final accumulated value typed as `E`.
+   *
+   * @overload
+   * @template U The accumulator type when it differs from `E`.
+   * @param callbackfn Reducer of signature `(acc: U, value, index, self) => U`.
+   * @param initialValue The initial accumulator value of type `U`.
+   * @returns The final accumulated value typed as `U`.
+   *
+   * @remarks
+   * Time O(n), Space O(1). Throws if called on an empty structure without `initialValue`.
+   */
+  reduce(callbackfn, initialValue) {
+    let index = 0;
+    const iter = this[Symbol.iterator]();
+    let acc;
+    if (arguments.length >= 2) {
+      acc = initialValue;
+    } else {
+      const first = iter.next();
+      if (first.done) throw new TypeError("Reduce of empty structure with no initial value");
+      acc = first.value;
+      index = 1;
+    }
+    for (const value of iter) {
+      acc = callbackfn(acc, value, index++, this);
+    }
+    return acc;
+  }
+  /**
+   * Materializes the elements into a new array.
+   *
+   * @returns A shallow array copy of the iteration order.
+   * @remarks
+   * Time O(n), Space O(n).
+   */
+  toArray() {
+    return [...this];
+  }
+  /**
+   * Returns a representation of the structure suitable for quick visualization.
+   * Defaults to an array of elements; subclasses may override to provide richer visuals.
+   *
+   * @returns A visual representation (array by default).
+   * @remarks
+   * Time O(n), Space O(n).
+   */
+  toVisual() {
+    return [...this];
+  }
+  /**
+   * Prints `toVisual()` to the console. Intended for quick debugging.
+   *
+   * @returns `void`.
+   * @remarks
+   * Time O(n) due to materialization, Space O(n) for the intermediate representation.
+   */
+  print() {
+    console.log(this.toVisual());
+  }
+};
+__name(_IterableElementBase, "IterableElementBase");
+var IterableElementBase = _IterableElementBase;
+
+// src/data-structures/heap/heap.ts
+var _Heap = class _Heap extends IterableElementBase {
+  /**
+   * Create a Heap and optionally bulk-insert elements.
+   * @remarks Time O(N), Space O(N)
+   * @param [elements] - Iterable of elements (or raw values if toElementFn is set).
+   * @param [options] - Options such as comparator and toElementFn.
+   * @returns New Heap instance.
+   */
+  constructor(elements = [], options) {
+    super(options);
+    __publicField(this, "_equals", Object.is);
+    __publicField(this, "_elements", []);
+    __publicField(this, "_DEFAULT_COMPARATOR", /* @__PURE__ */ __name((a, b) => {
+      if (typeof a === "object" || typeof b === "object") {
+        throw TypeError("When comparing object types, define a custom comparator in options.");
+      }
+      if (a > b) return 1;
+      if (a < b) return -1;
+      return 0;
+    }, "_DEFAULT_COMPARATOR"));
+    __publicField(this, "_comparator", this._DEFAULT_COMPARATOR);
+    if (options) {
+      const { comparator } = options;
+      if (comparator) this._comparator = comparator;
+    }
+    this.addMany(elements);
+  }
+  /**
+   * Get the backing array of the heap.
+   * @remarks Time O(1), Space O(1)
+   * @returns Internal elements array.
+   */
+  get elements() {
+    return this._elements;
+  }
+  /**
+   * Get the number of elements.
+   * @remarks Time O(1), Space O(1)
+   * @returns Heap size.
+   */
+  get size() {
+    return this.elements.length;
+  }
+  /**
+   * Get the last leaf element.
+   * @remarks Time O(1), Space O(1)
+   * @returns Last element or undefined.
+   */
+  get leaf() {
+    var _a;
+    return (_a = this.elements[this.size - 1]) != null ? _a : void 0;
+  }
+  /**
+   * Create a heap of the same class from an iterable.
+   * @remarks Time O(N), Space O(N)
+   * @template T
+   * @template R
+   * @template S
+   * @param [elements] - Iterable of elements or raw records.
+   * @param [options] - Heap options including comparator.
+   * @returns A new heap instance of this class.
+   */
+  static from(elements, options) {
+    return new this(elements, options);
+  }
+  /**
+   * Build a Heap from an iterable in linear time given a comparator.
+   * @remarks Time O(N), Space O(N)
+   * @template EE
+   * @template RR
+   * @param elements - Iterable of elements.
+   * @param options - Heap options including comparator.
+   * @returns A new Heap built from elements.
+   */
+  static heapify(elements, options) {
+    return new _Heap(elements, options);
+  }
+  /**
+   * Insert an element.
+   * @remarks Time O(1) amortized, Space O(1)
+   * @param element - Element to insert.
+   * @returns True.
+   */
+  add(element) {
+    this._elements.push(element);
+    return this._bubbleUp(this.elements.length - 1);
+  }
+  /**
+   * Insert many elements from an iterable.
+   * @remarks Time O(N log N), Space O(1)
+   * @param elements - Iterable of elements or raw values.
+   * @returns Array of per-element success flags.
+   */
+  addMany(elements) {
+    const flags = [];
+    for (const el of elements) {
+      if (this.toElementFn) {
+        const ok = this.add(this.toElementFn(el));
+        flags.push(ok);
+      } else {
+        const ok = this.add(el);
+        flags.push(ok);
+      }
+    }
+    return flags;
+  }
+  /**
+   * Remove and return the top element.
+   * @remarks Time O(log N), Space O(1)
+   * @returns Top element or undefined.
+   */
+  poll() {
+    if (this.elements.length === 0) return;
+    const value = this.elements[0];
+    const last = this.elements.pop();
+    if (this.elements.length) {
+      this.elements[0] = last;
+      this._sinkDown(0, this.elements.length >> 1);
+    }
+    return value;
+  }
+  /**
+   * Get the current top element without removing it.
+   * @remarks Time O(1), Space O(1)
+   * @returns Top element or undefined.
+   */
+  peek() {
+    return this.elements[0];
+  }
+  /**
+   * Check whether the heap is empty.
+   * @remarks Time O(1), Space O(1)
+   * @returns True if size is 0.
+   */
+  isEmpty() {
+    return this.size === 0;
+  }
+  /**
+   * Remove all elements.
+   * @remarks Time O(1), Space O(1)
+   * @returns void
+   */
+  clear() {
+    this._elements = [];
+  }
+  /**
+   * Replace the backing array and rebuild the heap.
+   * @remarks Time O(N), Space O(N)
+   * @param elements - Iterable used to refill the heap.
+   * @returns Array of per-node results from fixing steps.
+   */
+  refill(elements) {
+    this._elements = Array.from(elements);
+    return this.fix();
+  }
+  /**
+   * Check if an equal element exists in the heap.
+   * @remarks Time O(N), Space O(1)
+   * @param element - Element to search for.
+   * @returns True if found.
+   */
+  has(element) {
+    for (const el of this.elements) if (this._equals(el, element)) return true;
+    return false;
+  }
+  /**
+   * Delete one occurrence of an element.
+   * @remarks Time O(N), Space O(1)
+   * @param element - Element to delete.
+   * @returns True if an element was removed.
+   */
+  delete(element) {
+    let index = -1;
+    for (let i = 0; i < this.elements.length; i++) {
+      if (this._equals(this.elements[i], element)) {
+        index = i;
+        break;
+      }
+    }
+    if (index < 0) return false;
+    if (index === 0) {
+      this.poll();
+    } else if (index === this.elements.length - 1) {
+      this.elements.pop();
+    } else {
+      this.elements.splice(index, 1, this.elements.pop());
+      this._bubbleUp(index);
+      this._sinkDown(index, this.elements.length >> 1);
+    }
+    return true;
+  }
+  /**
+   * Delete the first element that matches a predicate.
+   * @remarks Time O(N), Space O(1)
+   * @param predicate - Function (element, index, heap) → boolean.
+   * @returns True if an element was removed.
+   */
+  deleteBy(predicate) {
+    let idx = -1;
+    for (let i = 0; i < this.elements.length; i++) {
+      if (predicate(this.elements[i], i, this)) {
+        idx = i;
+        break;
+      }
+    }
+    if (idx < 0) return false;
+    if (idx === 0) {
+      this.poll();
+    } else if (idx === this.elements.length - 1) {
+      this.elements.pop();
+    } else {
+      this.elements.splice(idx, 1, this.elements.pop());
+      this._bubbleUp(idx);
+      this._sinkDown(idx, this.elements.length >> 1);
+    }
+    return true;
+  }
+  /**
+   * Set the equality comparator used by has/delete operations.
+   * @remarks Time O(1), Space O(1)
+   * @param equals - Equality predicate (a, b) → boolean.
+   * @returns This heap.
+   */
+  setEquality(equals) {
+    this._equals = equals;
+    return this;
+  }
+  /**
+   * Traverse the binary heap as a complete binary tree and collect elements.
+   * @remarks Time O(N), Space O(H)
+   * @param [order] - Traversal order: 'PRE' | 'IN' | 'POST'.
+   * @returns Array of visited elements.
+   */
+  dfs(order = "PRE") {
+    const result = [];
+    const _dfs = /* @__PURE__ */ __name((index) => {
+      const left = 2 * index + 1, right = left + 1;
+      if (index < this.size) {
+        if (order === "IN") {
+          _dfs(left);
+          result.push(this.elements[index]);
+          _dfs(right);
+        } else if (order === "PRE") {
+          result.push(this.elements[index]);
+          _dfs(left);
+          _dfs(right);
+        } else if (order === "POST") {
+          _dfs(left);
+          _dfs(right);
+          result.push(this.elements[index]);
+        }
+      }
+    }, "_dfs");
+    _dfs(0);
+    return result;
+  }
+  /**
+   * Restore heap order bottom-up (heapify in-place).
+   * @remarks Time O(N), Space O(1)
+   * @returns Array of per-node results from fixing steps.
+   */
+  fix() {
+    const results = [];
+    for (let i = Math.floor(this.size / 2) - 1; i >= 0; i--) {
+      results.push(this._sinkDown(i, this.elements.length >> 1));
+    }
+    return results;
+  }
+  /**
+   * Return all elements in ascending order by repeatedly polling.
+   * @remarks Time O(N log N), Space O(N)
+   * @returns Sorted array of elements.
+   */
+  sort() {
+    const visited = [];
+    const cloned = this._createInstance();
+    for (const x of this.elements) cloned.add(x);
+    while (!cloned.isEmpty()) {
+      const top = cloned.poll();
+      if (top !== void 0) visited.push(top);
+    }
+    return visited;
+  }
+  /**
+   * Deep clone this heap.
+   * @remarks Time O(N), Space O(N)
+   * @returns A new heap with the same elements.
+   */
+  clone() {
+    const next = this._createInstance();
+    for (const x of this.elements) next.add(x);
+    return next;
+  }
+  /**
+   * Filter elements into a new heap of the same class.
+   * @remarks Time O(N log N), Space O(N)
+   * @param callback - Predicate (element, index, heap) → boolean to keep element.
+   * @param [thisArg] - Value for `this` inside the callback.
+   * @returns A new heap with the kept elements.
+   */
+  filter(callback, thisArg) {
+    const out = this._createInstance();
+    let i = 0;
+    for (const x of this) {
+      if (thisArg === void 0 ? callback(x, i++, this) : callback.call(thisArg, x, i++, this)) {
+        out.add(x);
+      } else {
+        i++;
+      }
+    }
+    return out;
+  }
+  /**
+   * Map elements into a new heap of possibly different element type.
+   * @remarks Time O(N log N), Space O(N)
+   * @template EM
+   * @template RM
+   * @param callback - Mapping function (element, index, heap) → newElement.
+   * @param options - Options for the output heap, including comparator for EM.
+   * @param [thisArg] - Value for `this` inside the callback.
+   * @returns A new heap with mapped elements.
+   */
+  map(callback, options, thisArg) {
+    const { comparator, toElementFn, ...rest } = options != null ? options : {};
+    if (!comparator) throw new TypeError("Heap.map requires options.comparator for EM");
+    const out = this._createLike([], { ...rest, comparator, toElementFn });
+    let i = 0;
+    for (const x of this) {
+      const v = thisArg === void 0 ? callback(x, i++, this) : callback.call(thisArg, x, i++, this);
+      out.add(v);
+    }
+    return out;
+  }
+  /**
+   * Map elements into a new heap of the same element type.
+   * @remarks Time O(N log N), Space O(N)
+   * @param callback - Mapping function (element, index, heap) → element.
+   * @param [thisArg] - Value for `this` inside the callback.
+   * @returns A new heap with mapped elements.
+   */
+  mapSame(callback, thisArg) {
+    const out = this._createInstance();
+    let i = 0;
+    for (const x of this) {
+      const v = thisArg === void 0 ? callback(x, i++, this) : callback.call(thisArg, x, i++, this);
+      out.add(v);
+    }
+    return out;
+  }
+  /**
+  * Get the comparator used to order elements.
+  * @remarks Time O(1), Space O(1)
+  * @returns Comparator function.
+  */
+  /**
+   * Get the comparator used to order elements.
+   * @remarks Time O(1), Space O(1)
+   * @returns Comparator function.
+   */
+  get comparator() {
+    return this._comparator;
+  }
+  *_getIterator() {
+    for (const element of this.elements) yield element;
+  }
+  _bubbleUp(index) {
+    const element = this.elements[index];
+    while (index > 0) {
+      const parent = index - 1 >> 1;
+      const parentItem = this.elements[parent];
+      if (this.comparator(parentItem, element) <= 0) break;
+      this.elements[index] = parentItem;
+      index = parent;
+    }
+    this.elements[index] = element;
+    return true;
+  }
+  _sinkDown(index, halfLength) {
+    const element = this.elements[index];
+    while (index < halfLength) {
+      let left = index << 1 | 1;
+      const right = left + 1;
+      let minItem = this.elements[left];
+      if (right < this.elements.length && this.comparator(minItem, this.elements[right]) > 0) {
+        left = right;
+        minItem = this.elements[right];
+      }
+      if (this.comparator(minItem, element) >= 0) break;
+      this.elements[index] = minItem;
+      index = left;
+    }
+    this.elements[index] = element;
+    return true;
+  }
+  /**
+   * (Protected) Create an empty instance of the same concrete class.
+   * @remarks Time O(1), Space O(1)
+   * @param [options] - Options to override comparator or toElementFn.
+   * @returns A like-kind empty heap instance.
+   */
+  _createInstance(options) {
+    const Ctor = this.constructor;
+    const next = new Ctor([], { comparator: this.comparator, toElementFn: this.toElementFn, ...options != null ? options : {} });
+    return next;
+  }
+  /**
+   * (Protected) Create a like-kind instance seeded by elements.
+   * @remarks Time O(N log N), Space O(N)
+   * @template EM
+   * @template RM
+   * @param [elements] - Iterable of elements or raw values to seed.
+   * @param [options] - Options forwarded to the constructor.
+   * @returns A like-kind heap instance.
+   */
+  _createLike(elements = [], options) {
+    const Ctor = this.constructor;
+    return new Ctor(elements, options);
+  }
+  /**
+   * (Protected) Spawn an empty like-kind heap instance.
+   * @remarks Time O(1), Space O(1)
+   * @template EM
+   * @template RM
+   * @param [options] - Options forwarded to the constructor.
+   * @returns An empty like-kind heap instance.
+   */
+  _spawnLike(options) {
+    return this._createLike([], options);
+  }
+};
+__name(_Heap, "Heap");
+var Heap = _Heap;
+
+// src/data-structures/base/linear-base.ts
+var _LinearBase = class _LinearBase extends IterableElementBase {
+  /**
+   * Construct a linear container with runtime options.
+   * @param options - `{ maxLen?, ... }` bounds/behavior options.
+   * @remarks Time O(1), Space O(1)
+   */
+  constructor(options) {
+    super(options);
+    __publicField(this, "_maxLen", -1);
+    if (options) {
+      const { maxLen } = options;
+      if (typeof maxLen === "number" && maxLen > 0 && maxLen % 1 === 0) this._maxLen = maxLen;
+    }
+  }
+  /**
+   * Upper bound for length (if positive), or `-1` when unbounded.
+   * @returns Maximum allowed length.
+   * @remarks Time O(1), Space O(1)
+   */
+  get maxLen() {
+    return this._maxLen;
+  }
+  /**
+   * First index of a value from the left.
+   * @param searchElement - Value to match.
+   * @param fromIndex - Start position (supports negative index).
+   * @returns Index or `-1` if not found.
+   * @remarks Time O(n), Space O(1)
+   */
+  indexOf(searchElement, fromIndex = 0) {
+    if (this.length === 0) return -1;
+    if (fromIndex < 0) fromIndex = this.length + fromIndex;
+    if (fromIndex < 0) fromIndex = 0;
+    for (let i = fromIndex; i < this.length; i++) {
+      const element = this.at(i);
+      if (element === searchElement) return i;
+    }
+    return -1;
+  }
+  /**
+   * Last index of a value from the right.
+   * @param searchElement - Value to match.
+   * @param fromIndex - Start position (supports negative index).
+   * @returns Index or `-1` if not found.
+   * @remarks Time O(n), Space O(1)
+   */
+  lastIndexOf(searchElement, fromIndex = this.length - 1) {
+    if (this.length === 0) return -1;
+    if (fromIndex >= this.length) fromIndex = this.length - 1;
+    if (fromIndex < 0) fromIndex = this.length + fromIndex;
+    for (let i = fromIndex; i >= 0; i--) {
+      const element = this.at(i);
+      if (element === searchElement) return i;
+    }
+    return -1;
+  }
+  /**
+   * Find the first index matching a predicate.
+   * @param predicate - `(element, index, self) => boolean`.
+   * @param thisArg - Optional `this` for callback.
+   * @returns Index or `-1`.
+   * @remarks Time O(n), Space O(1)
+   */
+  findIndex(predicate, thisArg) {
+    for (let i = 0; i < this.length; i++) {
+      const item = this.at(i);
+      if (item !== void 0 && predicate.call(thisArg, item, i, this)) return i;
+    }
+    return -1;
+  }
+  /**
+   * Concatenate elements and/or containers.
+   * @param items - Elements or other containers.
+   * @returns New container with combined elements (`this` type).
+   * @remarks Time O(sum(length)), Space O(sum(length))
+   */
+  concat(...items) {
+    const newList = this.clone();
+    for (const item of items) {
+      if (item instanceof _LinearBase) {
+        newList.pushMany(item);
+      } else {
+        newList.push(item);
+      }
+    }
+    return newList;
+  }
+  /**
+   * In-place stable order via array sort semantics.
+   * @param compareFn - Comparator `(a, b) => number`.
+   * @returns This container.
+   * @remarks Time O(n log n), Space O(n) (materializes to array temporarily)
+   */
+  sort(compareFn) {
+    const arr = this.toArray();
+    arr.sort(compareFn);
+    this.clear();
+    for (const item of arr) this.push(item);
+    return this;
+  }
+  /**
+   * Remove and/or insert elements at a position (array-compatible).
+   * @param start - Start index (supports negative index).
+   * @param deleteCount - How many to remove.
+   * @param items - Elements to insert.
+   * @returns Removed elements as a new list (`this` type).
+   * @remarks Time O(n + m), Space O(min(n, m)) where `m = items.length`
+   */
+  splice(start, deleteCount = 0, ...items) {
+    const removedList = this._createInstance();
+    start = start < 0 ? this.length + start : start;
+    start = Math.max(0, Math.min(start, this.length));
+    deleteCount = Math.max(0, Math.min(deleteCount, this.length - start));
+    for (let i = 0; i < deleteCount; i++) {
+      const removed = this.deleteAt(start);
+      if (removed !== void 0) {
+        removedList.push(removed);
+      }
+    }
+    for (let i = 0; i < items.length; i++) {
+      this.addAt(start + i, items[i]);
+    }
+    return removedList;
+  }
+  /**
+   * Join all elements into a string.
+   * @param separator - Separator string.
+   * @returns Concatenated string.
+   * @remarks Time O(n), Space O(n)
+   */
+  join(separator = ",") {
+    return this.toArray().join(separator);
+  }
+  /**
+   * Snapshot elements into a reversed array.
+   * @returns New reversed array.
+   * @remarks Time O(n), Space O(n)
+   */
+  toReversedArray() {
+    const array = [];
+    for (let i = this.length - 1; i >= 0; i--) {
+      array.push(this.at(i));
+    }
+    return array;
+  }
+  reduceRight(callbackfn, initialValue) {
+    let accumulator = initialValue != null ? initialValue : 0;
+    for (let i = this.length - 1; i >= 0; i--) {
+      accumulator = callbackfn(accumulator, this.at(i), i, this);
+    }
+    return accumulator;
+  }
+  /**
+   * Create a shallow copy of a subrange.
+   * @param start - Inclusive start (supports negative index).
+   * @param end - Exclusive end (supports negative index).
+   * @returns New list with the range (`this` type).
+   * @remarks Time O(n), Space O(n)
+   */
+  slice(start = 0, end = this.length) {
+    start = start < 0 ? this.length + start : start;
+    end = end < 0 ? this.length + end : end;
+    const newList = this._createInstance();
+    for (let i = start; i < end; i++) {
+      newList.push(this.at(i));
+    }
+    return newList;
+  }
+  /**
+   * Fill a range with a value.
+   * @param value - Value to set.
+   * @param start - Inclusive start.
+   * @param end - Exclusive end.
+   * @returns This list.
+   * @remarks Time O(n), Space O(1)
+   */
+  fill(value, start = 0, end = this.length) {
+    start = start < 0 ? this.length + start : start;
+    end = end < 0 ? this.length + end : end;
+    if (start < 0) start = 0;
+    if (end > this.length) end = this.length;
+    if (start >= end) return this;
+    for (let i = start; i < end; i++) {
+      this.setAt(i, value);
+    }
+    return this;
+  }
+};
+__name(_LinearBase, "LinearBase");
+var LinearBase = _LinearBase;
+
+// src/data-structures/queue/queue.ts
+var _Queue = class _Queue extends LinearBase {
+  /**
+   * Create a Queue and optionally bulk-insert elements.
+   * @remarks Time O(N), Space O(N)
+   * @param [elements] - Iterable of elements (or raw records if toElementFn is set).
+   * @param [options] - Options such as toElementFn, maxLen, and autoCompactRatio.
+   * @returns New Queue instance.
+   */
+  constructor(elements = [], options) {
+    super(options);
+    __publicField(this, "_elements", []);
+    __publicField(this, "_offset", 0);
+    __publicField(this, "_autoCompactRatio", 0.5);
+    if (options) {
+      const { autoCompactRatio = 0.5 } = options;
+      this._autoCompactRatio = autoCompactRatio;
+    }
+    this.pushMany(elements);
+  }
+  /**
+   * Get the underlying array buffer.
+   * @remarks Time O(1), Space O(1)
+   * @returns Backing array of elements.
+   */
+  get elements() {
+    return this._elements;
+  }
+  /**
+   * Get the current start offset into the array.
+   * @remarks Time O(1), Space O(1)
+   * @returns Zero-based offset.
+   */
+  get offset() {
+    return this._offset;
+  }
+  /**
+   * Get the compaction threshold (offset/size).
+   * @remarks Time O(1), Space O(1)
+   * @returns Auto-compaction ratio in (0,1].
+   */
+  get autoCompactRatio() {
+    return this._autoCompactRatio;
+  }
+  /**
+   * Set the compaction threshold.
+   * @remarks Time O(1), Space O(1)
+   * @param value - New ratio; compacts when offset/size exceeds this value.
+   * @returns void
+   */
+  set autoCompactRatio(value) {
+    this._autoCompactRatio = value;
+  }
+  /**
+   * Get the number of elements currently in the queue.
+   * @remarks Time O(1), Space O(1)
+   * @returns Current length.
+   */
+  get length() {
+    return this.elements.length - this._offset;
+  }
+  /**
+   * Get the first element (front) without removing it.
+   * @remarks Time O(1), Space O(1)
+   * @returns Front element or undefined.
+   */
+  get first() {
+    return this.length > 0 ? this.elements[this._offset] : void 0;
+  }
+  /**
+   * Get the last element (back) without removing it.
+   * @remarks Time O(1), Space O(1)
+   * @returns Back element or undefined.
+   */
+  get last() {
+    return this.length > 0 ? this.elements[this.elements.length - 1] : void 0;
+  }
+  /**
+   * Create a queue from an array of elements.
+   * @remarks Time O(N), Space O(N)
+   * @template E
+   * @param elements - Array of elements to enqueue in order.
+   * @returns A new queue populated from the array.
+   */
+  static fromArray(elements) {
+    return new _Queue(elements);
+  }
+  /**
+   * Check whether the queue is empty.
+   * @remarks Time O(1), Space O(1)
+   * @returns True if length is 0.
+   */
+  isEmpty() {
+    return this.length === 0;
+  }
+  /**
+   * Enqueue one element at the back.
+   * @remarks Time O(1), Space O(1)
+   * @param element - Element to enqueue.
+   * @returns True on success.
+   */
+  push(element) {
+    this.elements.push(element);
+    if (this._maxLen > 0 && this.length > this._maxLen) this.shift();
+    return true;
+  }
+  /**
+   * Enqueue many elements from an iterable.
+   * @remarks Time O(N), Space O(1)
+   * @param elements - Iterable of elements (or raw records if toElementFn is set).
+   * @returns Array of per-element success flags.
+   */
+  pushMany(elements) {
+    const ans = [];
+    for (const el of elements) {
+      if (this.toElementFn) ans.push(this.push(this.toElementFn(el)));
+      else ans.push(this.push(el));
+    }
+    return ans;
+  }
+  /**
+   * Dequeue one element from the front (amortized via offset).
+   * @remarks Time O(1) amortized, Space O(1)
+   * @returns Removed element or undefined.
+   */
+  shift() {
+    if (this.length === 0) return void 0;
+    const first = this.first;
+    this._offset += 1;
+    if (this.elements.length > 0 && this.offset / this.elements.length > this.autoCompactRatio) this.compact();
+    return first;
+  }
+  /**
+   * Delete the first occurrence of a specific element.
+   * @remarks Time O(N), Space O(1)
+   * @param element - Element to remove (strict equality via Object.is).
+   * @returns True if an element was removed.
+   */
+  delete(element) {
+    for (let i = this._offset; i < this.elements.length; i++) {
+      if (Object.is(this.elements[i], element)) {
+        this.elements.splice(i, 1);
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Get the element at a given logical index.
+   * @remarks Time O(1), Space O(1)
+   * @param index - Zero-based index from the front.
+   * @returns Element or undefined.
+   */
+  at(index) {
+    if (index < 0 || index >= this.length) return void 0;
+    return this._elements[this._offset + index];
+  }
+  /**
+   * Delete the element at a given index.
+   * @remarks Time O(N), Space O(1)
+   * @param index - Zero-based index from the front.
+   * @returns Removed element or undefined.
+   */
+  deleteAt(index) {
+    if (index < 0 || index >= this.length) return void 0;
+    const gi = this._offset + index;
+    const [deleted] = this.elements.splice(gi, 1);
+    return deleted;
+  }
+  /**
+   * Insert a new element at a given index.
+   * @remarks Time O(N), Space O(1)
+   * @param index - Zero-based index from the front.
+   * @param newElement - Element to insert.
+   * @returns True if inserted.
+   */
+  addAt(index, newElement) {
+    if (index < 0 || index > this.length) return false;
+    this._elements.splice(this._offset + index, 0, newElement);
+    return true;
+  }
+  /**
+   * Replace the element at a given index.
+   * @remarks Time O(1), Space O(1)
+   * @param index - Zero-based index from the front.
+   * @param newElement - New element to set.
+   * @returns True if updated.
+   */
+  setAt(index, newElement) {
+    if (index < 0 || index >= this.length) return false;
+    this._elements[this._offset + index] = newElement;
+    return true;
+  }
+  /**
+   * Reverse the queue in-place by compacting then reversing.
+   * @remarks Time O(N), Space O(N)
+   * @returns This queue.
+   */
+  reverse() {
+    this._elements = this.elements.slice(this._offset).reverse();
+    this._offset = 0;
+    return this;
+  }
+  /**
+   * Remove all elements and reset offset.
+   * @remarks Time O(1), Space O(1)
+   * @returns void
+   */
+  clear() {
+    this._elements = [];
+    this._offset = 0;
+  }
+  /**
+   * Compact storage by discarding consumed head elements.
+   * @remarks Time O(N), Space O(N)
+   * @returns True when compaction performed.
+   */
+  compact() {
+    this._elements = this.elements.slice(this._offset);
+    this._offset = 0;
+    return true;
+  }
+  /**
+   * Remove and/or insert elements at a position (array-like).
+   * @remarks Time O(N + M), Space O(M)
+   * @param start - Start index (clamped to [0, length]).
+   * @param [deleteCount] - Number of elements to remove (default 0).
+   * @param [items] - Elements to insert after `start`.
+   * @returns A new queue containing the removed elements (typed as `this`).
+   */
+  splice(start, deleteCount = 0, ...items) {
+    start = Math.max(0, Math.min(start, this.length));
+    deleteCount = Math.max(0, Math.min(deleteCount, this.length - start));
+    const gi = this._offset + start;
+    const removedArray = this._elements.splice(gi, deleteCount, ...items);
+    if (this.elements.length > 0 && this.offset / this.elements.length > this.autoCompactRatio) this.compact();
+    const removed = this._createInstance({ toElementFn: this.toElementFn, maxLen: this._maxLen });
+    removed._setAutoCompactRatio(this._autoCompactRatio);
+    removed.pushMany(removedArray);
+    return removed;
+  }
+  /**
+   * Deep clone this queue and its parameters.
+   * @remarks Time O(N), Space O(N)
+   * @returns A new queue with the same content and options.
+   */
+  clone() {
+    const out = this._createInstance({ toElementFn: this.toElementFn, maxLen: this._maxLen });
+    out._setAutoCompactRatio(this._autoCompactRatio);
+    for (let i = this._offset; i < this.elements.length; i++) out.push(this.elements[i]);
+    return out;
+  }
+  /**
+   * Filter elements into a new queue of the same class.
+   * @remarks Time O(N), Space O(N)
+   * @param predicate - Predicate (element, index, queue) → boolean to keep element.
+   * @param [thisArg] - Value for `this` inside the predicate.
+   * @returns A new queue with kept elements.
+   */
+  filter(predicate, thisArg) {
+    const out = this._createInstance({ toElementFn: this.toElementFn, maxLen: this._maxLen });
+    out._setAutoCompactRatio(this._autoCompactRatio);
+    let index = 0;
+    for (const v of this) {
+      if (predicate.call(thisArg, v, index, this)) out.push(v);
+      index++;
+    }
+    return out;
+  }
+  /**
+   * Map each element to a new element in a possibly different-typed queue.
+   * @remarks Time O(N), Space O(N)
+   * @template EM
+   * @template RM
+   * @param callback - Mapping function (element, index, queue) → newElement.
+   * @param [options] - Options for the output queue (e.g., toElementFn, maxLen, autoCompactRatio).
+   * @param [thisArg] - Value for `this` inside the callback.
+   * @returns A new Queue with mapped elements.
+   */
+  map(callback, options, thisArg) {
+    var _a, _b;
+    const out = new this.constructor([], {
+      toElementFn: options == null ? void 0 : options.toElementFn,
+      maxLen: (_a = options == null ? void 0 : options.maxLen) != null ? _a : this._maxLen,
+      autoCompactRatio: (_b = options == null ? void 0 : options.autoCompactRatio) != null ? _b : this._autoCompactRatio
+    });
+    let index = 0;
+    for (const v of this)
+      out.push(thisArg === void 0 ? callback(v, index++, this) : callback.call(thisArg, v, index++, this));
+    return out;
+  }
+  /**
+   * Map each element to a new value of the same type.
+   * @remarks Time O(N), Space O(N)
+   * @param callback - Mapping function (element, index, queue) → element.
+   * @param [thisArg] - Value for `this` inside the callback.
+   * @returns A new queue with mapped elements (same element type).
+   */
+  mapSame(callback, thisArg) {
+    var _a;
+    const Ctor = this.constructor;
+    const out = new Ctor([], {
+      toElementFn: this.toElementFn,
+      maxLen: this._maxLen,
+      autoCompactRatio: this._autoCompactRatio
+    });
+    (_a = out._setAutoCompactRatio) == null ? void 0 : _a.call(out, this._autoCompactRatio);
+    let index = 0;
+    for (const v of this) {
+      const mv = thisArg === void 0 ? callback(v, index++, this) : callback.call(thisArg, v, index++, this);
+      out.push(mv);
+    }
+    return out;
+  }
+  /**
+   * (Protected) Set the internal auto-compaction ratio.
+   * @remarks Time O(1), Space O(1)
+   * @param value - New ratio to assign.
+   * @returns void
+   */
+  _setAutoCompactRatio(value) {
+    this._autoCompactRatio = value;
+  }
+  /**
+   * (Protected) Iterate elements from front to back.
+   * @remarks Time O(N), Space O(1)
+   * @returns Iterator of E.
+   */
+  *_getIterator() {
+    for (let i = this._offset; i < this.elements.length; i++) yield this.elements[i];
+  }
+  /**
+   * (Protected) Iterate elements from back to front.
+   * @remarks Time O(N), Space O(1)
+   * @returns Iterator of E.
+   */
+  *_getReverseIterator() {
+    for (let i = this.length - 1; i >= 0; i--) {
+      const cur = this.at(i);
+      if (cur !== void 0) yield cur;
+    }
+  }
+  /**
+   * (Protected) Create an empty instance of the same concrete class.
+   * @remarks Time O(1), Space O(1)
+   * @param [options] - Options forwarded to the constructor.
+   * @returns An empty like-kind queue instance.
+   */
+  _createInstance(options) {
+    const Ctor = this.constructor;
+    return new Ctor([], options);
+  }
+  /**
+   * (Protected) Create a like-kind queue and seed it from an iterable.
+   * @remarks Time O(N), Space O(N)
+   * @template EM
+   * @template RM
+   * @param [elements] - Iterable used to seed the new queue.
+   * @param [options] - Options forwarded to the constructor.
+   * @returns A like-kind Queue instance.
+   */
+  _createLike(elements = [], options) {
+    const Ctor = this.constructor;
+    return new Ctor(elements, options);
+  }
+};
+__name(_Queue, "Queue");
+var Queue = _Queue;
+
+// src/data-structures/graph/abstract-graph.ts
+var _AbstractVertex = class _AbstractVertex {
+  constructor(key, value) {
+    __publicField(this, "key");
+    __publicField(this, "value");
+    this.key = key;
+    this.value = value;
+  }
+};
+__name(_AbstractVertex, "AbstractVertex");
+var AbstractVertex = _AbstractVertex;
+var _AbstractEdge = class _AbstractEdge {
+  constructor(weight, value) {
+    __publicField(this, "value");
+    __publicField(this, "weight");
+    __publicField(this, "_hashCode");
+    this.weight = weight !== void 0 ? weight : 1;
+    this.value = value;
+    this._hashCode = uuidV4();
+  }
+  get hashCode() {
+    return this._hashCode;
+  }
+};
+__name(_AbstractEdge, "AbstractEdge");
+var AbstractEdge = _AbstractEdge;
+var _AbstractGraph = class _AbstractGraph extends IterableEntryBase {
+  /**
+   * Construct a graph with runtime defaults.
+   * @param options - `GraphOptions<V>` in `options.graph` (e.g. `vertexValueInitializer`, `defaultEdgeWeight`).
+   * @remarks Time O(1), Space O(1)
+   */
+  constructor(options) {
+    super();
+    __publicField(this, "_options", { defaultEdgeWeight: 1 });
+    __publicField(this, "_vertexMap", /* @__PURE__ */ new Map());
+    const graph = options == null ? void 0 : options.graph;
+    this._options = { defaultEdgeWeight: 1, ...graph != null ? graph : {} };
+  }
+  get options() {
+    return this._options;
+  }
+  get vertexMap() {
+    return this._vertexMap;
+  }
+  set vertexMap(v) {
+    this._vertexMap = v;
+  }
+  get size() {
+    return this._vertexMap.size;
+  }
+  /**
+   * Get vertex instance by key.
+   * @param vertexKey - Vertex key.
+   * @returns Vertex instance or `undefined`.
+   * @remarks Time O(1), Space O(1)
+   */
+  getVertex(vertexKey) {
+    return this._vertexMap.get(vertexKey) || void 0;
+  }
+  /**
+   * Whether a vertex exists.
+   * @param vertexOrKey - Vertex or key.
+   * @returns `true` if present, otherwise `false`.
+   * @remarks Time O(1) avg, Space O(1)
+   */
+  hasVertex(vertexOrKey) {
+    return this._vertexMap.has(this._getVertexKey(vertexOrKey));
+  }
+  /**
+   * Add a vertex by key/value or by pre-built vertex.
+   * @param keyOrVertex - Vertex key or existing vertex instance.
+   * @param value - Optional payload.
+   * @returns `true` if inserted; `false` when key already exists.
+   * @remarks Time O(1) avg, Space O(1)
+   */
+  addVertex(keyOrVertex, value) {
+    if (keyOrVertex instanceof AbstractVertex) {
+      return this._addVertex(keyOrVertex);
+    } else {
+      const newVertex = this.createVertex(keyOrVertex, value);
+      return this._addVertex(newVertex);
+    }
+  }
+  /**
+   * Type guard: check if a value is a valid vertex key.
+   * @param potentialKey - Value to test.
+   * @returns `true` if string/number; else `false`.
+   * @remarks Time O(1), Space O(1)
+   */
+  isVertexKey(potentialKey) {
+    const potentialKeyType = typeof potentialKey;
+    return potentialKeyType === "string" || potentialKeyType === "number";
+  }
+  /**
+   * Delete multiple vertices.
+   * @param vertexMap - Array of vertices or keys.
+   * @returns `true` if any vertex was removed.
+   * @remarks Time O(sum(deg)), Space O(1)
+   */
+  removeManyVertices(vertexMap) {
+    const removed = [];
+    for (const v of vertexMap) {
+      removed.push(this.deleteVertex(v));
+    }
+    return removed.length > 0;
+  }
+  /**
+   * Whether an edge exists between two vertices.
+   * @param v1 - Endpoint A vertex or key.
+   * @param v2 - Endpoint B vertex or key.
+   * @returns `true` if present; otherwise `false`.
+   * @remarks Time O(1) avg, Space O(1)
+   */
+  hasEdge(v1, v2) {
+    const edge = this.getEdge(v1, v2);
+    return !!edge;
+  }
+  /**
+   * Add an edge by instance or by `(src, dest, weight?, value?)`.
+   * @param srcOrEdge - Edge instance or source vertex/key.
+   * @param dest - Destination vertex/key (when adding by pair).
+   * @param weight - Edge weight.
+   * @param value - Edge payload.
+   * @returns `true` if inserted; otherwise `false`.
+   * @remarks Time O(1) avg, Space O(1)
+   */
+  addEdge(srcOrEdge, dest, weight, value) {
+    if (srcOrEdge instanceof AbstractEdge) {
+      return this._addEdge(srcOrEdge);
+    } else {
+      if (dest instanceof AbstractVertex || typeof dest === "string" || typeof dest === "number") {
+        if (!(this.hasVertex(srcOrEdge) && this.hasVertex(dest))) return false;
+        if (srcOrEdge instanceof AbstractVertex) srcOrEdge = srcOrEdge.key;
+        if (dest instanceof AbstractVertex) dest = dest.key;
+        const newEdge = this.createEdge(srcOrEdge, dest, weight, value);
+        return this._addEdge(newEdge);
+      } else {
+        throw new Error("dest must be a Vertex or vertex key while srcOrEdge is an Edge");
+      }
+    }
+  }
+  /**
+   * Set the weight of an existing edge.
+   * @param srcOrKey - Source vertex or key.
+   * @param destOrKey - Destination vertex or key.
+   * @param weight - New weight.
+   * @returns `true` if updated; otherwise `false`.
+   * @remarks Time O(1) avg, Space O(1)
+   */
+  setEdgeWeight(srcOrKey, destOrKey, weight) {
+    const edge = this.getEdge(srcOrKey, destOrKey);
+    if (edge) {
+      edge.weight = weight;
+      return true;
+    } else {
+      return false;
+    }
+  }
+  /**
+   * Enumerate simple paths up to a limit.
+   * @param v1 - Source vertex or key.
+   * @param v2 - Destination vertex or key.
+   * @param limit - Maximum number of paths to collect.
+   * @returns Array of paths (each path is an array of vertices).
+   * @remarks Time O(paths) worst-case exponential, Space O(V + paths)
+   */
+  getAllPathsBetween(v1, v2, limit = 1e3) {
+    const paths = [];
+    const vertex1 = this._getVertex(v1);
+    const vertex2 = this._getVertex(v2);
+    if (!(vertex1 && vertex2)) {
+      return [];
+    }
+    const stack = [];
+    stack.push({ vertex: vertex1, path: [vertex1] });
+    while (stack.length > 0) {
+      const { vertex, path } = stack.pop();
+      if (vertex === vertex2) {
+        paths.push(path);
+        if (paths.length >= limit) return paths;
+      }
+      const neighbors = this.getNeighbors(vertex);
+      for (const neighbor of neighbors) {
+        if (!path.includes(neighbor)) {
+          const newPath = [...path, neighbor];
+          stack.push({ vertex: neighbor, path: newPath });
+        }
+      }
+    }
+    return paths;
+  }
+  /**
+   * Sum the weights along a vertex path.
+   * @param path - Sequence of vertices.
+   * @returns Path weight sum (0 if empty or edge missing).
+   * @remarks Time O(L), Space O(1) where L is path length
+   */
+  getPathSumWeight(path) {
+    var _a;
+    let sum = 0;
+    for (let i = 0; i < path.length; i++) {
+      sum += ((_a = this.getEdge(path[i], path[i + 1])) == null ? void 0 : _a.weight) || 0;
+    }
+    return sum;
+  }
+  /**
+   * Minimum hops/weight between two vertices.
+   * @param v1 - Source vertex or key.
+   * @param v2 - Destination vertex or key.
+   * @param isWeight - If `true`, compare by path weight; otherwise by hop count.
+   * @returns Minimum cost or `undefined` if missing/unreachable.
+   * @remarks Time O((V + E) log V) weighted / O(V + E) unweighted, Space O(V + E)
+   */
+  getMinCostBetween(v1, v2, isWeight) {
+    if (isWeight === void 0) isWeight = false;
+    if (isWeight) {
+      const allPaths = this.getAllPathsBetween(v1, v2);
+      let min = Number.MAX_SAFE_INTEGER;
+      for (const path of allPaths) {
+        min = Math.min(this.getPathSumWeight(path), min);
+      }
+      return min;
+    } else {
+      const vertex2 = this._getVertex(v2);
+      const vertex1 = this._getVertex(v1);
+      if (!(vertex1 && vertex2)) {
+        return void 0;
+      }
+      const visited = /* @__PURE__ */ new Map();
+      const queue = new Queue([vertex1]);
+      visited.set(vertex1, true);
+      let cost = 0;
+      while (queue.length > 0) {
+        for (let i = 0, layerSize = queue.length; i < layerSize; i++) {
+          const cur = queue.shift();
+          if (cur === vertex2) {
+            return cost;
+          }
+          if (cur !== void 0) {
+            const neighbors = this.getNeighbors(cur);
+            for (const neighbor of neighbors) {
+              if (!visited.has(neighbor)) {
+                visited.set(neighbor, true);
+                queue.push(neighbor);
+              }
+            }
+          }
+        }
+        cost++;
+      }
+      return void 0;
+    }
+  }
+  /**
+   * Minimum path (as vertex sequence) between two vertices.
+   * @param v1 - Source vertex or key.
+   * @param v2 - Destination vertex or key.
+   * @param isWeight - If `true`, compare by path weight; otherwise by hop count.
+   * @param isDFS - For weighted mode only: if `true`, brute-force all paths; if `false`, use Dijkstra.
+   * @returns Vertex sequence, or `undefined`/empty when unreachable depending on branch.
+   * @remarks Time O((V + E) log V) weighted / O(V + E) unweighted, Space O(V + E)
+   */
+  getMinPathBetween(v1, v2, isWeight, isDFS = false) {
+    var _a, _b;
+    if (isWeight === void 0) isWeight = false;
+    if (isWeight) {
+      if (isDFS) {
+        const allPaths = this.getAllPathsBetween(v1, v2, 1e4);
+        let min = Number.MAX_SAFE_INTEGER;
+        let minIndex = -1;
+        let index = 0;
+        for (const path of allPaths) {
+          const pathSumWeight = this.getPathSumWeight(path);
+          if (pathSumWeight < min) {
+            min = pathSumWeight;
+            minIndex = index;
+          }
+          index++;
+        }
+        return allPaths[minIndex] || void 0;
+      } else {
+        return (_b = (_a = this.dijkstra(v1, v2, true, true)) == null ? void 0 : _a.minPath) != null ? _b : [];
+      }
+    } else {
+      let minPath = [];
+      const vertex1 = this._getVertex(v1);
+      const vertex2 = this._getVertex(v2);
+      if (!(vertex1 && vertex2)) return [];
+      const dfs = /* @__PURE__ */ __name((cur, dest, visiting, path) => {
+        visiting.add(cur);
+        if (cur === dest) {
+          minPath = [vertex1, ...path];
+          return;
+        }
+        const neighbors = this.getNeighbors(cur);
+        for (const neighbor of neighbors) {
+          if (!visiting.has(neighbor)) {
+            path.push(neighbor);
+            dfs(neighbor, dest, visiting, path);
+            path.pop();
+          }
+        }
+        visiting.delete(cur);
+      }, "dfs");
+      dfs(vertex1, vertex2, /* @__PURE__ */ new Set(), []);
+      return minPath;
+    }
+  }
+  /**
+   * Dijkstra without heap (array-based selection).
+   * @param src - Source vertex or key.
+   * @param dest - Optional destination for early stop.
+   * @param getMinDist - If `true`, compute global minimum distance.
+   * @param genPaths - If `true`, also generate path arrays.
+   * @returns Result bag or `undefined` if source missing.
+   * @remarks Time O(V^2 + E), Space O(V + E)
+   */
+  dijkstraWithoutHeap(src, dest = void 0, getMinDist = false, genPaths = false) {
+    let minDist = Number.MAX_SAFE_INTEGER;
+    let minDest = void 0;
+    let minPath = [];
+    const paths = [];
+    const vertexMap = this._vertexMap;
+    const distMap = /* @__PURE__ */ new Map();
+    const seen = /* @__PURE__ */ new Set();
+    const preMap = /* @__PURE__ */ new Map();
+    const srcVertex = this._getVertex(src);
+    const destVertex = dest ? this._getVertex(dest) : void 0;
+    if (!srcVertex) {
+      return void 0;
+    }
+    for (const vertex of vertexMap) {
+      const vertexOrKey = vertex[1];
+      if (vertexOrKey instanceof AbstractVertex) distMap.set(vertexOrKey, Number.MAX_SAFE_INTEGER);
+    }
+    distMap.set(srcVertex, 0);
+    preMap.set(srcVertex, void 0);
+    const getMinOfNoSeen = /* @__PURE__ */ __name(() => {
+      let min = Number.MAX_SAFE_INTEGER;
+      let minV = void 0;
+      for (const [key, value] of distMap) {
+        if (!seen.has(key)) {
+          if (value < min) {
+            min = value;
+            minV = key;
+          }
+        }
+      }
+      return minV;
+    }, "getMinOfNoSeen");
+    const getPaths = /* @__PURE__ */ __name((minV) => {
+      for (const vertex of vertexMap) {
+        const vertexOrKey = vertex[1];
+        if (vertexOrKey instanceof AbstractVertex) {
+          const path = [vertexOrKey];
+          let parent = preMap.get(vertexOrKey);
+          while (parent) {
+            path.push(parent);
+            parent = preMap.get(parent);
+          }
+          const reversed = path.reverse();
+          if (vertex[1] === minV) minPath = reversed;
+          paths.push(reversed);
+        }
+      }
+    }, "getPaths");
+    for (let i = 1; i < vertexMap.size; i++) {
+      const cur = getMinOfNoSeen();
+      if (cur) {
+        seen.add(cur);
+        if (destVertex && destVertex === cur) {
+          if (getMinDist) {
+            minDist = distMap.get(destVertex) || Number.MAX_SAFE_INTEGER;
+          }
+          if (genPaths) {
+            getPaths(destVertex);
+          }
+          return { distMap, preMap, seen, paths, minDist, minPath };
+        }
+        const neighbors = this.getNeighbors(cur);
+        for (const neighbor of neighbors) {
+          if (!seen.has(neighbor)) {
+            const edge = this.getEdge(cur, neighbor);
+            if (edge) {
+              const curFromMap = distMap.get(cur);
+              const neighborFromMap = distMap.get(neighbor);
+              if (curFromMap !== void 0 && neighborFromMap !== void 0) {
+                if (edge.weight + curFromMap < neighborFromMap) {
+                  distMap.set(neighbor, edge.weight + curFromMap);
+                  preMap.set(neighbor, cur);
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    if (getMinDist)
+      distMap.forEach((d, v) => {
+        if (v !== srcVertex) {
+          if (d < minDist) {
+            minDist = d;
+            if (genPaths) minDest = v;
+          }
+        }
+      });
+    if (genPaths) getPaths(minDest);
+    return { distMap, preMap, seen, paths, minDist, minPath };
+  }
+  dijkstra(src, dest = void 0, getMinDist = false, genPaths = false) {
+    var _a;
+    let minDist = Number.MAX_SAFE_INTEGER;
+    let minDest = void 0;
+    let minPath = [];
+    const paths = [];
+    const vertexMap = this._vertexMap;
+    const distMap = /* @__PURE__ */ new Map();
+    const seen = /* @__PURE__ */ new Set();
+    const preMap = /* @__PURE__ */ new Map();
+    const srcVertex = this._getVertex(src);
+    const destVertex = dest ? this._getVertex(dest) : void 0;
+    if (!srcVertex) return void 0;
+    for (const vertex of vertexMap) {
+      const vertexOrKey = vertex[1];
+      if (vertexOrKey instanceof AbstractVertex) distMap.set(vertexOrKey, Number.MAX_SAFE_INTEGER);
+    }
+    const heap = new Heap([], { comparator: /* @__PURE__ */ __name((a, b) => a.key - b.key, "comparator") });
+    heap.add({ key: 0, value: srcVertex });
+    distMap.set(srcVertex, 0);
+    preMap.set(srcVertex, void 0);
+    const getPaths = /* @__PURE__ */ __name((minV) => {
+      for (const vertex of vertexMap) {
+        const vertexOrKey = vertex[1];
+        if (vertexOrKey instanceof AbstractVertex) {
+          const path = [vertexOrKey];
+          let parent = preMap.get(vertexOrKey);
+          while (parent) {
+            path.push(parent);
+            parent = preMap.get(parent);
+          }
+          const reversed = path.reverse();
+          if (vertex[1] === minV) minPath = reversed;
+          paths.push(reversed);
+        }
+      }
+    }, "getPaths");
+    while (heap.size > 0) {
+      const curHeapNode = heap.poll();
+      const dist = curHeapNode == null ? void 0 : curHeapNode.key;
+      const cur = curHeapNode == null ? void 0 : curHeapNode.value;
+      if (dist !== void 0) {
+        if (cur) {
+          seen.add(cur);
+          if (destVertex && destVertex === cur) {
+            if (getMinDist) {
+              minDist = distMap.get(destVertex) || Number.MAX_SAFE_INTEGER;
+            }
+            if (genPaths) {
+              getPaths(destVertex);
+            }
+            return { distMap, preMap, seen, paths, minDist, minPath };
+          }
+          const neighbors = this.getNeighbors(cur);
+          for (const neighbor of neighbors) {
+            if (!seen.has(neighbor)) {
+              const weight = (_a = this.getEdge(cur, neighbor)) == null ? void 0 : _a.weight;
+              if (typeof weight === "number") {
+                const distSrcToNeighbor = distMap.get(neighbor);
+                if (distSrcToNeighbor !== void 0) {
+                  if (dist + weight < distSrcToNeighbor) {
+                    heap.add({ key: dist + weight, value: neighbor });
+                    preMap.set(neighbor, cur);
+                    distMap.set(neighbor, dist + weight);
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    if (getMinDist) {
+      distMap.forEach((d, v) => {
+        if (v !== srcVertex) {
+          if (d < minDist) {
+            minDist = d;
+            if (genPaths) minDest = v;
+          }
+        }
+      });
+    }
+    if (genPaths) {
+      getPaths(minDest);
+    }
+    return { distMap, preMap, seen, paths, minDist, minPath };
+  }
+  /**
+   * Bellman-Ford single-source shortest paths with option to scan negative cycles.
+   * @param src - Source vertex or key.
+   * @param scanNegativeCycle - If `true`, also detect negative cycles.
+   * @param getMin - If `true`, compute global minimum distance.
+   * @param genPath - If `true`, generate path arrays via predecessor map.
+   * @returns Result bag including distances, predecessors, and optional cycle flag.
+   * @remarks Time O(V * E), Space O(V + E)
+   */
+  bellmanFord(src, scanNegativeCycle, getMin, genPath) {
+    if (getMin === void 0) getMin = false;
+    if (genPath === void 0) genPath = false;
+    const srcVertex = this._getVertex(src);
+    const paths = [];
+    const distMap = /* @__PURE__ */ new Map();
+    const preMap = /* @__PURE__ */ new Map();
+    let min = Number.MAX_SAFE_INTEGER;
+    let minPath = [];
+    let hasNegativeCycle;
+    if (scanNegativeCycle) hasNegativeCycle = false;
+    if (!srcVertex) return { hasNegativeCycle, distMap, preMap, paths, min, minPath };
+    const vertexMap = this._vertexMap;
+    const numOfVertices = vertexMap.size;
+    const edgeMap = this.edgeSet();
+    const numOfEdges = edgeMap.length;
+    this._vertexMap.forEach((vertex) => {
+      distMap.set(vertex, Number.MAX_SAFE_INTEGER);
+    });
+    distMap.set(srcVertex, 0);
+    for (let i = 1; i < numOfVertices; ++i) {
+      for (let j = 0; j < numOfEdges; ++j) {
+        const ends = this.getEndsOfEdge(edgeMap[j]);
+        if (ends) {
+          const [s, d] = ends;
+          const weight = edgeMap[j].weight;
+          const sWeight = distMap.get(s);
+          const dWeight = distMap.get(d);
+          if (sWeight !== void 0 && dWeight !== void 0) {
+            if (distMap.get(s) !== Number.MAX_SAFE_INTEGER && sWeight + weight < dWeight) {
+              distMap.set(d, sWeight + weight);
+              if (genPath) preMap.set(d, s);
+            }
+          }
+        }
+      }
+    }
+    let minDest = void 0;
+    if (getMin) {
+      distMap.forEach((d, v) => {
+        if (v !== srcVertex) {
+          if (d < min) {
+            min = d;
+            if (genPath) minDest = v;
+          }
+        }
+      });
+    }
+    if (genPath) {
+      for (const vertex of vertexMap) {
+        const vertexOrKey = vertex[1];
+        if (vertexOrKey instanceof AbstractVertex) {
+          const path = [vertexOrKey];
+          let parent = preMap.get(vertexOrKey);
+          while (parent !== void 0) {
+            path.push(parent);
+            parent = preMap.get(parent);
+          }
+          const reversed = path.reverse();
+          if (vertex[1] === minDest) minPath = reversed;
+          paths.push(reversed);
+        }
+      }
+    }
+    for (let j = 0; j < numOfEdges; ++j) {
+      const ends = this.getEndsOfEdge(edgeMap[j]);
+      if (ends) {
+        const [s] = ends;
+        const weight = edgeMap[j].weight;
+        const sWeight = distMap.get(s);
+        if (sWeight) {
+          if (sWeight !== Number.MAX_SAFE_INTEGER && sWeight + weight < sWeight) hasNegativeCycle = true;
+        }
+      }
+    }
+    return { hasNegativeCycle, distMap, preMap, paths, min, minPath };
+  }
+  /**
+   * Floyd–Warshall all-pairs shortest paths.
+   * @returns `{ costs, predecessor }` matrices.
+   * @remarks Time O(V^3), Space O(V^2)
+   */
+  floydWarshall() {
+    var _a;
+    const idAndVertices = [...this._vertexMap];
+    const n = idAndVertices.length;
+    const costs = [];
+    const predecessor = [];
+    for (let i = 0; i < n; i++) {
+      costs[i] = [];
+      predecessor[i] = [];
+      for (let j = 0; j < n; j++) {
+        predecessor[i][j] = void 0;
+      }
+    }
+    for (let i = 0; i < n; i++) {
+      for (let j = 0; j < n; j++) {
+        costs[i][j] = ((_a = this.getEdge(idAndVertices[i][1], idAndVertices[j][1])) == null ? void 0 : _a.weight) || Number.MAX_SAFE_INTEGER;
+      }
+    }
+    for (let k = 0; k < n; k++) {
+      for (let i = 0; i < n; i++) {
+        for (let j = 0; j < n; j++) {
+          if (costs[i][j] > costs[i][k] + costs[k][j]) {
+            costs[i][j] = costs[i][k] + costs[k][j];
+            predecessor[i][j] = idAndVertices[k][1];
+          }
+        }
+      }
+    }
+    return { costs, predecessor };
+  }
+  /**
+   * Enumerate simple cycles (may be expensive).
+   * @param isInclude2Cycle - If `true`, include 2-cycles when graph semantics allow.
+   * @returns Array of cycles (each as array of vertex keys).
+   * @remarks Time exponential in worst-case, Space O(V + E)
+   */
+  getCycles(isInclude2Cycle = false) {
+    const cycles = [];
+    const visited = /* @__PURE__ */ new Set();
+    const dfs = /* @__PURE__ */ __name((vertex, currentPath, visited2) => {
+      if (visited2.has(vertex)) {
+        if ((!isInclude2Cycle && currentPath.length > 2 || isInclude2Cycle && currentPath.length >= 2) && currentPath[0] === vertex.key) {
+          cycles.push([...currentPath]);
+        }
+        return;
+      }
+      visited2.add(vertex);
+      currentPath.push(vertex.key);
+      for (const neighbor of this.getNeighbors(vertex)) {
+        if (neighbor) dfs(neighbor, currentPath, visited2);
+      }
+      visited2.delete(vertex);
+      currentPath.pop();
+    }, "dfs");
+    for (const vertex of this.vertexMap.values()) {
+      dfs(vertex, [], visited);
+    }
+    const uniqueCycles = /* @__PURE__ */ new Map();
+    for (const cycle of cycles) {
+      const sorted = [...cycle].sort().toString();
+      if (uniqueCycles.has(sorted)) continue;
+      else {
+        uniqueCycles.set(sorted, cycle);
+      }
+    }
+    return [...uniqueCycles].map((cycleString) => cycleString[1]);
+  }
+  /**
+   * Induced-subgraph filter: keep vertices where `predicate(key, value)` is true,
+   * and only keep edges whose endpoints both survive.
+   * @param predicate - `(key, value, index, self) => boolean`.
+   * @param thisArg - Optional `this` for callback.
+   * @returns A new graph of the same concrete class (`this` type).
+   * @remarks Time O(V + E), Space O(V + E)
+   */
+  filter(predicate, thisArg) {
+    const filtered = [];
+    let index = 0;
+    for (const [key, value] of this) {
+      if (predicate.call(thisArg, key, value, index, this)) {
+        filtered.push([key, value]);
+      }
+      index++;
+    }
+    return this._createLike(filtered, this._snapshotOptions());
+  }
+  /**
+   * Preserve the old behavior: return filtered entries as an array.
+   * @remarks Time O(V), Space O(V)
+   */
+  filterEntries(predicate, thisArg) {
+    const filtered = [];
+    let index = 0;
+    for (const [key, value] of this) {
+      if (predicate.call(thisArg, key, value, index, this)) {
+        filtered.push([key, value]);
+      }
+      index++;
+    }
+    return filtered;
+  }
+  map(callback, thisArg) {
+    const mapped = [];
+    let index = 0;
+    for (const [key, value] of this) {
+      mapped.push(callback.call(thisArg, key, value, index, this));
+      index++;
+    }
+    return mapped;
+  }
+  /**
+   * Create a deep clone of the graph with the same species.
+   * @remarks Time O(V + E), Space O(V + E)
+   */
+  /**
+   * Create a deep clone of the graph with the same species.
+   * @returns A new graph of the same concrete class (`this` type).
+   * @remarks Time O(V + E), Space O(V + E)
+   */
+  clone() {
+    return this._createLike(void 0, this._snapshotOptions());
+  }
+  // ===== Same-species factory & cloning helpers =====
+  /**
+   * Internal iterator over `[key, value]` entries in insertion order.
+   * @returns Iterator of `[VertexKey, V | undefined]`.
+   * @remarks Time O(V), Space O(1)
+   */
+  *_getIterator() {
+    for (const vertex of this._vertexMap.values()) {
+      yield [vertex.key, vertex.value];
+    }
+  }
+  /**
+   * Capture configuration needed to reproduce the current graph.
+   * Currently the graph has no runtime options, so we return an empty object.
+   */
+  /**
+   * Capture configuration needed to reproduce the current graph.
+   * @returns Options bag (opaque to callers).
+   * @remarks Time O(1), Space O(1)
+   */
+  _snapshotOptions() {
+    return { graph: { ...this._options } };
+  }
+  /**
+   * Create an empty graph instance of the same concrete species (Directed/Undirected/etc).
+   * @remarks Time O(1), Space O(1)
+   */
+  /**
+   * Create an empty graph instance of the same concrete species.
+   * @param _options - Snapshot options from `_snapshotOptions()`.
+   * @returns A new empty graph instance of `this` type.
+   * @remarks Time O(1), Space O(1)
+   */
+  _createInstance(_options) {
+    const Ctor = this.constructor;
+    const instance = new Ctor();
+    const graph = _options == null ? void 0 : _options.graph;
+    if (graph) instance._options = { ...instance._options, ...graph };
+    else instance._options = { ...instance._options, ...this._options };
+    return instance;
+  }
+  /**
+   * Create a same-species graph populated with the given entries.
+   * Also preserves edges between kept vertices from the source graph.
+   * @remarks Time O(V + E), Space O(V + E)
+   */
+  /**
+   * Create a same-species graph populated with entries; preserves edges among kept vertices.
+   * @param iter - Optional entries to seed the new graph.
+   * @param options - Snapshot options.
+   * @returns A new graph of `this` type.
+   * @remarks Time O(V + E), Space O(V + E)
+   */
+  _createLike(iter, options) {
+    const g = this._createInstance(options);
+    if (iter) {
+      for (const [k, v] of iter) {
+        g.addVertex(k, v);
+      }
+    } else {
+      for (const [k, v] of this) {
+        g.addVertex(k, v);
+      }
+    }
+    const edges = this.edgeSet();
+    for (const e of edges) {
+      const ends = this.getEndsOfEdge(e);
+      if (!ends) continue;
+      const [va, vb] = ends;
+      const ka = va.key;
+      const kb = vb.key;
+      const hasA = g.hasVertex ? g.hasVertex(ka) : false;
+      const hasB = g.hasVertex ? g.hasVertex(kb) : false;
+      if (hasA && hasB) {
+        const w = e.weight;
+        const val = e.value;
+        const newEdge = g.createEdge(ka, kb, w, val);
+        g._addEdge(newEdge);
+      }
+    }
+    return g;
+  }
+  /**
+   * Insert a pre-built vertex into the graph.
+   * @param newVertex - Concrete vertex instance.
+   * @returns `true` if inserted; `false` if key already exists.
+   * @remarks Time O(1) avg, Space O(1)
+   */
+  _addVertex(newVertex) {
+    if (this.hasVertex(newVertex)) {
+      return false;
+    }
+    this._vertexMap.set(newVertex.key, newVertex);
+    return true;
+  }
+  /**
+   * Resolve a vertex key or instance to the concrete vertex instance.
+   * @param vertexOrKey - Vertex key or existing vertex.
+   * @returns Vertex instance or `undefined`.
+   * @remarks Time O(1), Space O(1)
+   */
+  _getVertex(vertexOrKey) {
+    const vertexKey = this._getVertexKey(vertexOrKey);
+    return this._vertexMap.get(vertexKey) || void 0;
+  }
+  /**
+   * Resolve a vertex key from a key or vertex instance.
+   * @param vertexOrKey - Vertex key or existing vertex.
+   * @returns The vertex key.
+   * @remarks Time O(1), Space O(1)
+   */
+  _getVertexKey(vertexOrKey) {
+    return vertexOrKey instanceof AbstractVertex ? vertexOrKey.key : vertexOrKey;
+  }
+};
+__name(_AbstractGraph, "AbstractGraph");
+var AbstractGraph = _AbstractGraph;
+
+// src/data-structures/graph/directed-graph.ts
+var _DirectedVertex = class _DirectedVertex extends AbstractVertex {
+  constructor(key, value) {
+    super(key, value);
+  }
+};
+__name(_DirectedVertex, "DirectedVertex");
+var DirectedVertex = _DirectedVertex;
+var _DirectedEdge = class _DirectedEdge extends AbstractEdge {
+  constructor(src, dest, weight, value) {
+    super(weight, value);
+    __publicField(this, "src");
+    __publicField(this, "dest");
+    this.src = src;
+    this.dest = dest;
+  }
+};
+__name(_DirectedEdge, "DirectedEdge");
+var DirectedEdge = _DirectedEdge;
+var _DirectedGraph = class _DirectedGraph extends AbstractGraph {
+  /**
+   * Construct a directed graph with runtime defaults.
+   * @param options - `GraphOptions<V>` (e.g. `vertexValueInitializer`, `defaultEdgeWeight`).
+   * @remarks Time O(1), Space O(1)
+   */
+  constructor(options) {
+    super(options);
+    __publicField(this, "_outEdgeMap", /* @__PURE__ */ new Map());
+    __publicField(this, "_inEdgeMap", /* @__PURE__ */ new Map());
+  }
+  get outEdgeMap() {
+    return this._outEdgeMap;
+  }
+  set outEdgeMap(v) {
+    this._outEdgeMap = v;
+  }
+  get inEdgeMap() {
+    return this._inEdgeMap;
+  }
+  set inEdgeMap(v) {
+    this._inEdgeMap = v;
+  }
+  /**
+   * Construct a directed graph from keys with value initializer `v => v`.
+   * @template K - Vertex key type.
+   * @param keys - Iterable of vertex keys.
+   * @returns DirectedGraph with all keys added.
+   * @remarks Time O(V), Space O(V)
+   */
+  static fromKeys(keys) {
+    const g = new _DirectedGraph({
+      vertexValueInitializer: /* @__PURE__ */ __name((k) => k, "vertexValueInitializer")
+    });
+    for (const k of keys) g.addVertex(k);
+    return g;
+  }
+  /**
+   * Construct a directed graph from `[key, value]` entries.
+   * @template V - Vertex value type.
+   * @param entries - Iterable of `[key, value]` pairs.
+   * @returns DirectedGraph with all vertices added.
+   * @remarks Time O(V), Space O(V)
+   */
+  static fromEntries(entries) {
+    const g = new _DirectedGraph();
+    for (const [k, v] of entries) g.addVertex(k, v);
+    return g;
+  }
+  /**
+   * Create a directed vertex instance. Does not insert into the graph.
+   * @param key - Vertex identifier.
+   * @param value - Optional payload.
+   * @returns Concrete vertex instance.
+   * @remarks Time O(1), Space O(1)
+   */
+  createVertex(key, value) {
+    return new DirectedVertex(key, value);
+  }
+  /**
+   * Create a directed edge instance. Does not insert into the graph.
+   * @param src - Source vertex key.
+   * @param dest - Destination vertex key.
+   * @param weight - Edge weight; defaults to `defaultEdgeWeight`.
+   * @param value - Edge payload.
+   * @returns Concrete edge instance.
+   * @remarks Time O(1), Space O(1)
+   */
+  createEdge(src, dest, weight, value) {
+    var _a;
+    return new DirectedEdge(src, dest, (_a = weight != null ? weight : this.options.defaultEdgeWeight) != null ? _a : 1, value);
+  }
+  /**
+   * Get the unique edge from `src` to `dest`, if present.
+   * @param srcOrKey - Source vertex or key.
+   * @param destOrKey - Destination vertex or key.
+   * @returns Edge instance or `undefined`.
+   * @remarks Time O(1) avg, Space O(1)
+   */
+  getEdge(srcOrKey, destOrKey) {
+    let edgeMap = [];
+    if (srcOrKey !== void 0 && destOrKey !== void 0) {
+      const src = this._getVertex(srcOrKey);
+      const dest = this._getVertex(destOrKey);
+      if (src && dest) {
+        const srcOutEdges = this._outEdgeMap.get(src);
+        if (srcOutEdges) {
+          edgeMap = srcOutEdges.filter((edge) => edge.dest === dest.key);
+        }
+      }
+    }
+    return edgeMap[0] || void 0;
+  }
+  /**
+   * Delete edge `src -> dest` if present.
+   * @param srcOrKey - Source vertex or key.
+   * @param destOrKey - Destination vertex or key.
+   * @returns Removed edge or `undefined`.
+   * @remarks Time O(1) avg, Space O(1)
+   */
+  deleteEdgeSrcToDest(srcOrKey, destOrKey) {
+    const src = this._getVertex(srcOrKey);
+    const dest = this._getVertex(destOrKey);
+    let removed = void 0;
+    if (!src || !dest) {
+      return void 0;
+    }
+    const srcOutEdges = this._outEdgeMap.get(src);
+    if (srcOutEdges) {
+      arrayRemove(srcOutEdges, (edge) => edge.dest === dest.key);
+    }
+    const destInEdges = this._inEdgeMap.get(dest);
+    if (destInEdges) {
+      removed = arrayRemove(destInEdges, (edge) => edge.src === src.key)[0] || void 0;
+    }
+    return removed;
+  }
+  /**
+   * Delete an edge by instance or by `(srcKey, destKey)`.
+   * @param edgeOrSrcVertexKey - Edge instance or source vertex/key.
+   * @param destVertexKey - Optional destination vertex/key when deleting by pair.
+   * @returns Removed edge or `undefined`.
+   * @remarks Time O(1) avg, Space O(1)
+   */
+  deleteEdge(edgeOrSrcVertexKey, destVertexKey) {
+    let removed = void 0;
+    let src, dest;
+    if (this.isVertexKey(edgeOrSrcVertexKey)) {
+      if (this.isVertexKey(destVertexKey)) {
+        src = this._getVertex(edgeOrSrcVertexKey);
+        dest = this._getVertex(destVertexKey);
+      } else {
+        return;
+      }
+    } else {
+      src = this._getVertex(edgeOrSrcVertexKey.src);
+      dest = this._getVertex(edgeOrSrcVertexKey.dest);
+    }
+    if (src && dest) {
+      const srcOutEdges = this._outEdgeMap.get(src);
+      if (srcOutEdges && srcOutEdges.length > 0) {
+        arrayRemove(srcOutEdges, (edge) => edge.src === src.key && edge.dest === (dest == null ? void 0 : dest.key));
+      }
+      const destInEdges = this._inEdgeMap.get(dest);
+      if (destInEdges && destInEdges.length > 0) {
+        removed = arrayRemove(destInEdges, (edge) => edge.src === src.key && edge.dest === dest.key)[0];
+      }
+    }
+    return removed;
+  }
+  deleteVertex(vertexOrKey) {
+    let vertexKey;
+    let vertex;
+    if (this.isVertexKey(vertexOrKey)) {
+      vertex = this.getVertex(vertexOrKey);
+      vertexKey = vertexOrKey;
+    } else {
+      vertex = vertexOrKey;
+      vertexKey = this._getVertexKey(vertexOrKey);
+    }
+    if (vertex) {
+      const neighbors = this.getNeighbors(vertex);
+      for (const neighbor of neighbors) {
+        this.deleteEdgeSrcToDest(vertex, neighbor);
+      }
+      this._outEdgeMap.delete(vertex);
+      this._inEdgeMap.delete(vertex);
+    }
+    return this._vertexMap.delete(vertexKey);
+  }
+  deleteEdgesBetween(v1, v2) {
+    const removed = [];
+    if (v1 && v2) {
+      const v1ToV2 = this.deleteEdgeSrcToDest(v1, v2);
+      const v2ToV1 = this.deleteEdgeSrcToDest(v2, v1);
+      if (v1ToV2) removed.push(v1ToV2);
+      if (v2ToV1) removed.push(v2ToV1);
+    }
+    return removed;
+  }
+  /**
+   * Incoming edges of a vertex.
+   * @param vertexOrKey - Vertex or key.
+   * @returns Array of incoming edges.
+   * @remarks Time O(deg_in), Space O(deg_in)
+   */
+  incomingEdgesOf(vertexOrKey) {
+    const target = this._getVertex(vertexOrKey);
+    if (target) {
+      return this.inEdgeMap.get(target) || [];
+    }
+    return [];
+  }
+  /**
+   * Outgoing edges of a vertex.
+   * @param vertexOrKey - Vertex or key.
+   * @returns Array of outgoing edges.
+   * @remarks Time O(deg_out), Space O(deg_out)
+   */
+  outgoingEdgesOf(vertexOrKey) {
+    const target = this._getVertex(vertexOrKey);
+    if (target) {
+      return this._outEdgeMap.get(target) || [];
+    }
+    return [];
+  }
+  /**
+   * Degree (in + out) of a vertex.
+   * @param vertexOrKey - Vertex or key.
+   * @returns Non-negative integer.
+   * @remarks Time O(1) avg, Space O(1)
+   */
+  degreeOf(vertexOrKey) {
+    return this.outDegreeOf(vertexOrKey) + this.inDegreeOf(vertexOrKey);
+  }
+  inDegreeOf(vertexOrKey) {
+    return this.incomingEdgesOf(vertexOrKey).length;
+  }
+  outDegreeOf(vertexOrKey) {
+    return this.outgoingEdgesOf(vertexOrKey).length;
+  }
+  /**
+   * All incident edges of a vertex.
+   * @param vertexOrKey - Vertex or key.
+   * @returns Array of incident edges.
+   * @remarks Time O(deg_in + deg_out), Space O(deg_in + deg_out)
+   */
+  edgesOf(vertexOrKey) {
+    return [...this.outgoingEdgesOf(vertexOrKey), ...this.incomingEdgesOf(vertexOrKey)];
+  }
+  getEdgeSrc(e) {
+    return this._getVertex(e.src);
+  }
+  getEdgeDest(e) {
+    return this._getVertex(e.dest);
+  }
+  /**
+   * Direct children reachable by one outgoing edge.
+   * @param vertex - Vertex or key.
+   * @returns Array of neighbor vertices.
+   * @remarks Time O(deg_out), Space O(deg_out)
+   */
+  getDestinations(vertex) {
+    if (vertex === void 0) {
+      return [];
+    }
+    const destinations = [];
+    const outgoingEdges = this.outgoingEdgesOf(vertex);
+    for (const outEdge of outgoingEdges) {
+      const child = this.getEdgeDest(outEdge);
+      if (child) {
+        destinations.push(child);
+      }
+    }
+    return destinations;
+  }
+  /**
+   * Topological sort if DAG; returns `undefined` if a cycle exists.
+   * @param propertyName - `'key'` to map to keys; `'vertex'` to keep instances.
+   * @returns Array of keys/vertices, or `undefined` when cycle is found.
+   * @remarks Time O(V + E), Space O(V)
+   */
+  topologicalSort(propertyName) {
+    propertyName = propertyName != null ? propertyName : "key";
+    const statusMap = /* @__PURE__ */ new Map();
+    for (const entry of this.vertexMap) {
+      statusMap.set(entry[1], 0);
+    }
+    let sorted = [];
+    let hasCycle = false;
+    const dfs = /* @__PURE__ */ __name((cur) => {
+      statusMap.set(cur, 1);
+      const children = this.getDestinations(cur);
+      for (const child of children) {
+        const childStatus = statusMap.get(child);
+        if (childStatus === 0) {
+          dfs(child);
+        } else if (childStatus === 1) {
+          hasCycle = true;
+        }
+      }
+      statusMap.set(cur, 2);
+      sorted.push(cur);
+    }, "dfs");
+    for (const entry of this.vertexMap) {
+      if (statusMap.get(entry[1]) === 0) {
+        dfs(entry[1]);
+      }
+    }
+    if (hasCycle) return void 0;
+    if (propertyName === "key") sorted = sorted.map((vertex) => vertex instanceof DirectedVertex ? vertex.key : vertex);
+    return sorted.reverse();
+  }
+  edgeSet() {
+    let edgeMap = [];
+    this._outEdgeMap.forEach((outEdges) => {
+      edgeMap = [...edgeMap, ...outEdges];
+    });
+    return edgeMap;
+  }
+  getNeighbors(vertexOrKey) {
+    const neighbors = [];
+    const vertex = this._getVertex(vertexOrKey);
+    if (vertex) {
+      const outEdges = this.outgoingEdgesOf(vertex);
+      for (const outEdge of outEdges) {
+        const neighbor = this._getVertex(outEdge.dest);
+        if (neighbor) {
+          neighbors.push(neighbor);
+        }
+      }
+    }
+    return neighbors;
+  }
+  /**
+   * Resolve an edge's `[src, dest]` endpoints to vertex instances.
+   * @param edge - Edge instance.
+   * @returns `[src, dest]` or `undefined` if either endpoint is missing.
+   * @remarks Time O(1), Space O(1)
+   */
+  getEndsOfEdge(edge) {
+    if (!this.hasEdge(edge.src, edge.dest)) {
+      return void 0;
+    }
+    const v1 = this._getVertex(edge.src);
+    const v2 = this._getVertex(edge.dest);
+    if (v1 && v2) {
+      return [v1, v2];
+    } else {
+      return void 0;
+    }
+  }
+  /**
+   * Whether the graph has no vertices and no edges.
+   * @remarks Time O(1), Space O(1)
+   */
+  isEmpty() {
+    return this.vertexMap.size === 0 && this.inEdgeMap.size === 0 && this.outEdgeMap.size === 0;
+  }
+  /**
+   * Remove all vertices and edges.
+   * @remarks Time O(V + E), Space O(1)
+   */
+  clear() {
+    this._vertexMap = /* @__PURE__ */ new Map();
+    this._inEdgeMap = /* @__PURE__ */ new Map();
+    this._outEdgeMap = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Deep clone as the same concrete class.
+   * @returns A new graph of the same concrete class (`this` type).
+   * @remarks Time O(V + E), Space O(V + E)
+   */
+  clone() {
+    return super.clone();
+  }
+  /**
+   * Tarjan's algorithm for strongly connected components.
+   * @returns `{ dfnMap, lowMap, SCCs }`.
+   * @remarks Time O(V + E), Space O(V + E)
+   */
+  tarjan() {
+    const dfnMap = /* @__PURE__ */ new Map();
+    const lowMap = /* @__PURE__ */ new Map();
+    const SCCs = /* @__PURE__ */ new Map();
+    let time = 0;
+    const stack = [];
+    const inStack = /* @__PURE__ */ new Set();
+    const dfs = /* @__PURE__ */ __name((vertex) => {
+      dfnMap.set(vertex, time);
+      lowMap.set(vertex, time);
+      time++;
+      stack.push(vertex);
+      inStack.add(vertex);
+      const neighbors = this.getNeighbors(vertex);
+      for (const neighbor of neighbors) {
+        if (!dfnMap.has(neighbor)) {
+          dfs(neighbor);
+          lowMap.set(vertex, Math.min(lowMap.get(vertex), lowMap.get(neighbor)));
+        } else if (inStack.has(neighbor)) {
+          lowMap.set(vertex, Math.min(lowMap.get(vertex), dfnMap.get(neighbor)));
+        }
+      }
+      if (dfnMap.get(vertex) === lowMap.get(vertex)) {
+        const SCC = [];
+        let poppedVertex;
+        do {
+          poppedVertex = stack.pop();
+          inStack.delete(poppedVertex);
+          SCC.push(poppedVertex);
+        } while (poppedVertex !== vertex);
+        SCCs.set(SCCs.size, SCC);
+      }
+    }, "dfs");
+    for (const vertex of this.vertexMap.values()) {
+      if (!dfnMap.has(vertex)) {
+        dfs(vertex);
+      }
+    }
+    return { dfnMap, lowMap, SCCs };
+  }
+  /**
+   * DFN index map computed by `tarjan()`.
+   * @returns Map from vertex to DFN index.
+   * @remarks Time O(V), Space O(V)
+   */
+  getDFNMap() {
+    return this.tarjan().dfnMap;
+  }
+  /**
+   * LOW link map computed by `tarjan()`.
+   * @returns Map from vertex to LOW value.
+   * @remarks Time O(V), Space O(V)
+   */
+  getLowMap() {
+    return this.tarjan().lowMap;
+  }
+  /**
+   * Strongly connected components computed by `tarjan()`.
+   * @returns Map from SCC id to vertices.
+   * @remarks Time O(#SCC + V), Space O(V)
+   */
+  getSCCs() {
+    return this.tarjan().SCCs;
+  }
+  /**
+   * Internal hook to attach a directed edge into adjacency maps.
+   * @param edge - Edge instance.
+   * @returns `true` if inserted; otherwise `false`.
+   * @remarks Time O(1) avg, Space O(1)
+   */
+  _addEdge(edge) {
+    if (!(this.hasVertex(edge.src) && this.hasVertex(edge.dest))) {
+      return false;
+    }
+    const srcVertex = this._getVertex(edge.src);
+    const destVertex = this._getVertex(edge.dest);
+    if (srcVertex && destVertex) {
+      const srcOutEdges = this._outEdgeMap.get(srcVertex);
+      if (srcOutEdges) {
+        srcOutEdges.push(edge);
+      } else {
+        this._outEdgeMap.set(srcVertex, [edge]);
+      }
+      const destInEdges = this._inEdgeMap.get(destVertex);
+      if (destInEdges) {
+        destInEdges.push(edge);
+      } else {
+        this._inEdgeMap.set(destVertex, [edge]);
+      }
+      return true;
+    } else {
+      return false;
+    }
+  }
+};
+__name(_DirectedGraph, "DirectedGraph");
+var DirectedGraph = _DirectedGraph;
+
+// src/common/index.ts
+var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
+  DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
+  DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
+  return DFSOperation2;
+})(DFSOperation || {});
+var _Range = class _Range {
+  constructor(low, high, includeLow = true, includeHigh = true) {
+    this.low = low;
+    this.high = high;
+    this.includeLow = includeLow;
+    this.includeHigh = includeHigh;
+    if (!(isComparable(low) && isComparable(high))) throw new RangeError("low or high is not comparable");
+    if (low > high) throw new RangeError("low must be less than or equal to high");
+  }
+  // Determine whether a key is within the range
+  isInRange(key, comparator) {
+    const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;
+    const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;
+    return lowCheck && highCheck;
+  }
+};
+__name(_Range, "Range");
+var Range = _Range;
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+
+exports.AbstractEdge = AbstractEdge;
+exports.AbstractGraph = AbstractGraph;
+exports.AbstractVertex = AbstractVertex;
+exports.DFSOperation = DFSOperation;
+exports.DirectedEdge = DirectedEdge;
+exports.DirectedGraph = DirectedGraph;
+exports.DirectedVertex = DirectedVertex;
+exports.Range = Range;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map