elseware-nodejs 1.0.9 → 1.1.0

package/dist/index.d.cts

@@ -94,6 +94,1698 @@ declare function createAllowedOrigins(options?: AllowedOriginsOptions): string[]
 
 declare function createCorsOptions(allowedOrigins: string[]): CorsOptions;
 
+/**
+ * CircularArray (Ring Buffer)
+ * ---------------------------
+ * A fixed-capacity circular array implementation.
+ *
+ * Characteristics:
+ * - Fixed capacity
+ * - O(1) enqueue / dequeue
+ * - Wrap-around indexing
+ * - Bounds-safe
+ * - Generic
+ * - Iterable (logical order)
+ *
+ * Use cases:
+ * - Queues
+ * - Circular buffers
+ * - Sliding windows
+ * - Game event buffers
+ */
+declare class CircularArray<T> implements Iterable<T> {
+    private readonly capacity;
+    private data;
+    private head;
+    private tail;
+    private length;
+    constructor(capacity: number);
+    size(): number;
+    getCapacity(): number;
+    isEmpty(): boolean;
+    isFull(): boolean;
+    enqueue(value: T): void;
+    dequeue(): T | undefined;
+    peek(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+    [Symbol.iterator](): Iterator<T>;
+    toString(): string;
+}
+
+/**
+ * DynamicArray
+ * ------------
+ * A resizable array implementation similar to ArrayList / Vector.
+ *
+ * Characteristics:
+ * - Automatically resizes when capacity is exceeded
+ * - O(1) amortized append
+ * - O(1) access by index
+ * - Bounds-safe
+ * - Generic
+ * - Iterable
+ *
+ * Use cases:
+ * - General-purpose collections
+ * - Algorithm implementations
+ * - Game entity lists
+ * - Backend buffers
+ */
+declare class DynamicArray<T> implements Iterable<T> {
+    private data;
+    private capacity;
+    private length;
+    constructor(initialCapacity?: number);
+    size(): number;
+    getCapacity(): number;
+    private checkBounds;
+    private resize;
+    get(index: number): T | undefined;
+    set(index: number, value: T): void;
+    push(value: T): void;
+    pop(): T | undefined;
+    insert(index: number, value: T): void;
+    removeAt(index: number): T | undefined;
+    contains(value: T): boolean;
+    toArray(): T[];
+    clear(): void;
+    [Symbol.iterator](): Iterator<T>;
+    toString(): string;
+}
+
+/**
+ * StaticArray
+ * -----------
+ * A fixed-size array implementation.
+ *
+ * Characteristics:
+ * - Size is defined at creation time and cannot be changed
+ * - O(1) access by index
+ * - Bounds-safe
+ * - Generic
+ * - Iterable
+ *
+ * Use cases:
+ * - Fixed buffers
+ * - Memory-sensitive systems
+ * - Game grids / tiles
+ * - Algorithm demonstrations
+ */
+declare class StaticArray<T> implements Iterable<T> {
+    private readonly capacity;
+    private readonly data;
+    /**
+     * Creates a static array with a fixed size.
+     * @param size Total capacity of the array
+     * @param initialValue Optional default value for all indices
+     */
+    constructor(size: number, initialValue?: T);
+    size(): number;
+    private checkBounds;
+    get(index: number): T | undefined;
+    set(index: number, value: T): void;
+    fill(value: T): void;
+    clear(): void;
+    contains(value: T): boolean;
+    indexOf(value: T): number;
+    toArray(): (T | undefined)[];
+    [Symbol.iterator](): Iterator<T>;
+    forEach(callback: (value: T | undefined, index: number) => void): void;
+    clone(): StaticArray<T>;
+    toString(): string;
+}
+
+/**
+ * AdjacencyList
+ * -------------
+ * A generic adjacency list data structure.
+ *
+ * Characteristics:
+ * - Stores neighbors for each vertex
+ * - Supports weighted or unweighted edges
+ * - No traversal or algorithms included
+ *
+ * Intended to be used as a building block
+ * for Graph / DirectedGraph implementations.
+ */
+interface AdjacentEdge<T = string> {
+    to: T;
+    weight?: number;
+}
+declare class AdjacencyList<T = string> {
+    private list;
+    addVertex(vertex: T): void;
+    removeVertex(vertex: T): void;
+    hasVertex(vertex: T): boolean;
+    getVertices(): T[];
+    addEdge(from: T, to: T, weight?: number): void;
+    removeEdge(from: T, to: T): void;
+    hasEdge(from: T, to: T): boolean;
+    getEdges(vertex: T): AdjacentEdge<T>[];
+    clear(): void;
+    size(): number;
+}
+
+/**
+ * AdjacencyMatrix
+ * ---------------
+ * Matrix-based graph representation.
+ *
+ * Characteristics:
+ * - Directed or Undirected
+ * - Weighted or Unweighted
+ * - Dense graph friendly
+ * - No traversal or algorithms included
+ *
+ * Internally maps vertices to indices.
+ */
+declare class AdjacencyMatrix<T = string> {
+    private readonly directed;
+    private matrix;
+    private vertices;
+    private indexMap;
+    constructor(directed?: boolean);
+    addVertex(vertex: T): void;
+    removeVertex(vertex: T): void;
+    hasVertex(vertex: T): boolean;
+    getVertices(): T[];
+    addEdge(from: T, to: T, weight?: number): void;
+    removeEdge(from: T, to: T): void;
+    hasEdge(from: T, to: T): boolean;
+    getWeight(from: T, to: T): number | undefined;
+    size(): number;
+    clear(): void;
+    isDirected(): boolean;
+    /**
+     * Returns a copy of the adjacency matrix
+     */
+    toMatrix(): number[][];
+}
+
+/**
+ * DirectedGraph
+ * -------------
+ * Adjacency-list based directed graph data structure.
+ *
+ * Characteristics:
+ * - Directed edges only
+ * - Weighted or unweighted edges (stored, not processed)
+ * - Includes general traversals: BFS & DFS
+ *
+ * Advanced algorithms should live separately.
+ */
+interface DirectedEdge<T = string> {
+    to: T;
+    weight?: number;
+}
+declare class DirectedGraph<T = string> {
+    private adjList;
+    addVertex(vertex: T): void;
+    removeVertex(vertex: T): void;
+    hasVertex(vertex: T): boolean;
+    getVertices(): T[];
+    addEdge(from: T, to: T, weight?: number): void;
+    removeEdge(from: T, to: T): void;
+    hasEdge(from: T, to: T): boolean;
+    getEdges(vertex: T): DirectedEdge<T>[];
+    /**
+     * Breadth-First Search (BFS)
+     */
+    bfs(start: T): T[];
+    /**
+     * Depth-First Search (DFS)
+     */
+    dfs(start: T): T[];
+    clear(): void;
+    size(): number;
+    isDirected(): true;
+}
+
+/**
+ * Graph
+ * -----
+ * General-purpose adjacency list graph data structure.
+ *
+ * Includes:
+ * - Directed / Undirected graph support
+ * - Weighted or unweighted edges (stored, not processed)
+ * - General traversal algorithms: BFS & DFS
+ *
+ * Advanced algorithms (Dijkstra, MST, etc.) should live separately.
+ */
+interface Edge<T = string> {
+    to: T;
+    weight?: number;
+}
+declare class Graph<T = string> {
+    private readonly directed;
+    private adjList;
+    constructor(directed?: boolean);
+    addVertex(vertex: T): void;
+    removeVertex(vertex: T): void;
+    hasVertex(vertex: T): boolean;
+    getVertices(): T[];
+    addEdge(from: T, to: T, weight?: number): void;
+    removeEdge(from: T, to: T): void;
+    hasEdge(from: T, to: T): boolean;
+    getEdges(vertex: T): Edge<T>[];
+    /**
+     * Breadth-First Search (BFS)
+     */
+    bfs(start: T): T[];
+    /**
+     * Depth-First Search (DFS)
+     */
+    dfs(start: T): T[];
+    clear(): void;
+    size(): number;
+    isDirected(): boolean;
+}
+
+/**
+ * ConsistentHash
+ * --------------
+ * Consistent hashing implementation with virtual nodes.
+ *
+ * Use cases:
+ * - Load balancers
+ * - Distributed caches
+ * - Database sharding
+ *
+ * Characteristics:
+ * - Minimal key remapping on node add/remove
+ * - Supports virtual nodes (replicas)
+ * - Deterministic hashing
+ */
+declare class ConsistentHash<T extends string | number> {
+    private ring;
+    private sortedKeys;
+    private replicas;
+    constructor(replicas?: number);
+    addNode(node: T): void;
+    removeNode(node: T): void;
+    getNode(key: string | number): T | undefined;
+    getNodes(): T[];
+    size(): number;
+    clear(): void;
+    private hash;
+    private sortRing;
+    private findClosestIndex;
+}
+
+/**
+ * HashMap
+ * -------
+ * A generic hash map implementation using separate chaining.
+ *
+ * Characteristics:
+ * - Generic key-value support
+ * - Handles collisions via linked lists (arrays)
+ * - Automatically resizes when load factor exceeds threshold
+ *
+ * Time Complexity:
+ * - Average: O(1)
+ * - Worst: O(n)
+ */
+declare class HashMap<K extends string | number, V> {
+    private buckets;
+    private capacity;
+    private size;
+    private readonly LOAD_FACTOR;
+    constructor(initialCapacity?: number);
+    set(key: K, value: V): void;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    keys(): K[];
+    values(): V[];
+    entries(): Array<[K, V]>;
+    getSize(): number;
+    getCapacity(): number;
+    private hash;
+    private resize;
+}
+
+/**
+ * HashSet
+ * -------
+ * A generic hash set implementation built on top of HashMap.
+ *
+ * Characteristics:
+ * - Stores unique values only
+ * - Backed by HashMap for O(1) average operations
+ *
+ * Time Complexity:
+ * - Average: O(1)
+ * - Worst: O(n)
+ */
+declare class HashSet<T extends string | number> {
+    private map;
+    constructor(initialCapacity?: number);
+    add(value: T): void;
+    has(value: T): boolean;
+    delete(value: T): boolean;
+    clear(): void;
+    size(): number;
+    values(): T[];
+    isEmpty(): boolean;
+}
+
+/**
+ * LFUCache
+ * --------
+ * Least Frequently Used cache implementation.
+ *
+ * Eviction rules:
+ * 1. Evict the lowest frequency
+ * 2. If tie, evict least recently used (LRU)
+ *
+ * Uses:
+ * - HashMap for O(1) lookup
+ * - Frequency Map → DoublyLinkedList for LRU ordering
+ */
+declare class LFUCache<K extends string | number, V> {
+    private capacity;
+    private size;
+    private minFreq;
+    private cache;
+    private freqMap;
+    constructor(capacity: number);
+    get(key: K): V | undefined;
+    put(key: K, value: V): void;
+    has(key: K): boolean;
+    sizeOf(): number;
+    clear(): void;
+    private updateFrequency;
+    private evictLFU;
+    private getFreqList;
+}
+
+/**
+ * LRUCache
+ * --------
+ * Least Recently Used (LRU) Cache implementation.
+ *
+ * Characteristics:
+ * - O(1) get and put operations
+ * - Evicts least recently used item when capacity is exceeded
+ *
+ * Data Structures Used:
+ * - HashMap for fast lookup
+ * - Doubly Linked List for usage order
+ */
+declare class LRUCache<K extends string | number, V> {
+    private capacity;
+    private cache;
+    private head;
+    private tail;
+    constructor(capacity: number);
+    get(key: K): V | undefined;
+    put(key: K, value: V): void;
+    has(key: K): boolean;
+    size(): number;
+    clear(): void;
+    private addToFront;
+    private removeNode;
+    private moveToFront;
+    private evictLeastRecentlyUsed;
+}
+
+/**
+ * BinaryHeap
+ * ----------
+ * A generic binary heap implementation.
+ *
+ * By default this is a min-heap.
+ * You can create a max-heap by providing a custom comparator.
+ *
+ * Time Complexity:
+ * - Insert: O(log n)
+ * - Extract: O(log n)
+ * - Peek: O(1)
+ */
+declare class BinaryHeap<T> {
+    private heap;
+    private readonly compare;
+    constructor(comparator?: (a: T, b: T) => number, initial?: T[]);
+    insert(value: T): void;
+    extract(): T | undefined;
+    peek(): T | undefined;
+    size(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    toArray(): T[];
+    private heapify;
+    private siftUp;
+    private siftDown;
+    private swap;
+}
+
+/**
+ * FibonacciHeap
+ * -------------
+ * Amortized-optimal heap supporting:
+ * - insert: O(1)
+ * - findMin: O(1)
+ * - merge: O(1)
+ * - decreaseKey: O(1) amortized
+ * - extractMin: O(log n) amortized
+ */
+declare class FibNode<T> {
+    key: T;
+    parent: FibNode<T> | null;
+    children: FibNode<T>[];
+    mark: boolean;
+    constructor(key: T);
+}
+declare class FibonacciHeap<T> {
+    private roots;
+    private minNode;
+    private _size;
+    private readonly compare;
+    constructor(compareFn?: (a: T, b: T) => number);
+    insert(key: T): FibNode<T>;
+    findMin(): T | undefined;
+    size(): number;
+    isEmpty(): boolean;
+    merge(other: FibonacciHeap<T>): void;
+    extractMin(): T | undefined;
+    decreaseKey(node: FibNode<T>, newKey: T): void;
+    clear(): void;
+    private consolidate;
+    private link;
+    private cut;
+    private cascadingCut;
+}
+
+/**
+ * MaxHeap
+ * -------
+ * A specialized MaxHeap implementation built on top of BinaryHeap.
+ *
+ * Characteristics:
+ * - Always extracts the maximum element
+ * - O(log n) insert & extract
+ * - O(1) peek
+ */
+
+declare class MaxHeap<T> extends BinaryHeap<T> {
+    constructor(initial?: T[]);
+}
+
+/**
+ * MinHeap
+ * -------
+ * A specialized MinHeap implementation built on top of BinaryHeap.
+ *
+ * Characteristics:
+ * - Always extracts the minimum element
+ * - O(log n) insert & extract
+ * - O(1) peek
+ */
+
+declare class MinHeap<T> extends BinaryHeap<T> {
+    constructor(initial?: T[]);
+}
+
+/**
+ * PairingHeap
+ * -----------
+ * A self-adjusting heap with excellent practical performance.
+ *
+ * Time Complexity (amortized):
+ * - insert: O(1)
+ * - merge: O(1)
+ * - findMin: O(1)
+ * - extractMin: O(log n)
+ * - decreaseKey: O(log n)
+ *
+ * Simpler and safer than Fibonacci Heap.
+ */
+declare class PairingNode<T> {
+    key: T;
+    child: PairingNode<T> | null;
+    sibling: PairingNode<T> | null;
+    parent: PairingNode<T> | null;
+    constructor(key: T);
+}
+declare class PairingHeap<T> {
+    private root;
+    private _size;
+    private readonly compare;
+    constructor(compareFn?: (a: T, b: T) => number);
+    insert(key: T): PairingNode<T>;
+    findMin(): T | undefined;
+    size(): number;
+    isEmpty(): boolean;
+    merge(other: PairingHeap<T>): void;
+    extractMin(): T | undefined;
+    decreaseKey(node: PairingNode<T>, newKey: T): void;
+    clear(): void;
+    private mergeNodes;
+    /**
+     * Two-pass pairing: first pair siblings, then merge back
+     */
+    private combineSiblings;
+    private cut;
+}
+
+declare class CircularLinkedList<T> implements Iterable<T> {
+    private tail;
+    private length;
+    size(): number;
+    add(value: T): void;
+    remove(value: T): boolean;
+    toArray(): T[];
+    [Symbol.iterator](): Iterator<T>;
+}
+
+declare class DoublyLinkedList<T> implements Iterable<T> {
+    private head;
+    private tail;
+    private length;
+    size(): number;
+    add(value: T): void;
+    remove(value: T): boolean;
+    toArray(): T[];
+    [Symbol.iterator](): Iterator<T>;
+}
+
+declare class Node<T> {
+    value: T;
+    next: Node<T> | null;
+    prev: Node<T> | null;
+    constructor(value: T);
+}
+
+declare class SinglyLinkedList<T> implements Iterable<T> {
+    private head;
+    private tail;
+    private length;
+    size(): number;
+    isEmpty(): boolean;
+    add(value: T): void;
+    remove(value: T): boolean;
+    contains(value: T): boolean;
+    toArray(): T[];
+    [Symbol.iterator](): Iterator<T>;
+}
+
+/**
+ * BloomFilter
+ * -----------
+ * A probabilistic data structure for fast membership testing.
+ *
+ * Characteristics:
+ * - No false negatives
+ * - Possible false positives
+ * - Space efficient
+ * - Insert & lookup only
+ *
+ * Time Complexity:
+ * - add: O(k)
+ * - contains: O(k)
+ */
+declare class BloomFilter {
+    private readonly size;
+    private readonly hashCount;
+    private readonly bits;
+    constructor(size: number, hashCount: number);
+    add(value: string): void;
+    contains(value: string): boolean;
+    clear(): void;
+    private getHashes;
+    private hash;
+}
+
+/**
+ * CountMinSketch
+ * --------------
+ * A probabilistic data structure for frequency estimation.
+ *
+ * Guarantees:
+ * - Estimated count >= true count
+ * - No false negatives
+ *
+ * Time Complexity:
+ * - update: O(d)
+ * - estimate: O(d)
+ */
+declare class CountMinSketch {
+    private readonly width;
+    private readonly depth;
+    private readonly table;
+    private readonly seeds;
+    constructor(width: number, depth: number);
+    /**
+     * Increments the count of an item
+     */
+    update(value: string, count?: number): void;
+    /**
+     * Returns the estimated frequency of an item
+     */
+    estimate(value: string): number;
+    clear(): void;
+    private hash;
+}
+
+/**
+ * HyperLogLog
+ * -----------
+ * Probabilistic data structure for cardinality estimation.
+ *
+ * Guarantees:
+ * - Approximates number of distinct elements
+ * - Small memory footprint
+ *
+ * Error rate ≈ 1.04 / sqrt(m)
+ * where m = number of registers
+ */
+declare class HyperLogLog {
+    private readonly p;
+    private readonly m;
+    private readonly registers;
+    private readonly alpha;
+    constructor(p?: number);
+    add(value: string): void;
+    count(): number;
+    clear(): void;
+    private hash;
+    private countLeadingZeros;
+    private getAlpha;
+}
+
+/**
+ * CircularQueue
+ * -------------
+ * Fixed-size circular FIFO queue.
+ *
+ * Characteristics:
+ * - O(1) enqueue / dequeue
+ * - Fixed capacity
+ *
+ * Use cases:
+ * - Ring buffers
+ * - Real-time systems
+ */
+declare class CircularQueue<T> {
+    private readonly capacity;
+    private data;
+    private head;
+    private tail;
+    private length;
+    constructor(capacity: number);
+    size(): number;
+    isEmpty(): boolean;
+    isFull(): boolean;
+    enqueue(value: T): void;
+    dequeue(): T | undefined;
+    peek(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+    toString(): string;
+}
+
+/**
+ * Deque
+ * -----
+ * Double-ended queue.
+ *
+ * Characteristics:
+ * - O(1) add/remove from both ends
+ *
+ * Use cases:
+ * - Sliding window problems
+ * - Palindrome checking
+ */
+declare class Deque<T> {
+    private items;
+    size(): number;
+    isEmpty(): boolean;
+    pushFront(value: T): void;
+    pushBack(value: T): void;
+    popFront(): T | undefined;
+    popBack(): T | undefined;
+    peekFront(): T | undefined;
+    peekBack(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+    toString(): string;
+}
+
+/**
+ * PriorityQueue (Min-Heap)
+ * ------------------------
+ * Elements with lower priority value are dequeued first.
+ *
+ * Characteristics:
+ * - O(log n) enqueue / dequeue
+ *
+ * Use cases:
+ * - Dijkstra / A*
+ * - Task scheduling
+ */
+declare class PriorityQueue<T> {
+    private heap;
+    size(): number;
+    isEmpty(): boolean;
+    enqueue(value: T, priority: number): void;
+    dequeue(): T | undefined;
+    peek(): T | undefined;
+    private bubbleUp;
+    private bubbleDown;
+    toString(): string;
+}
+
+/**
+ * Queue
+ * -----
+ * FIFO (First In First Out) queue.
+ *
+ * Characteristics:
+ * - O(1) enqueue / dequeue (amortized)
+ * - Generic
+ *
+ * Use cases:
+ * - Task scheduling
+ * - Event processing
+ * - BFS traversal
+ */
+declare class Queue<T> {
+    private items;
+    private head;
+    size(): number;
+    isEmpty(): boolean;
+    enqueue(value: T): void;
+    dequeue(): T | undefined;
+    peek(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+    toString(): string;
+}
+
+/**
+ * Disjoint Set Union (Union-Find)
+ * ------------------------------
+ * Data structure that keeps track of a partition of a set into
+ * disjoint (non-overlapping) subsets.
+ *
+ * Optimizations:
+ * - Path compression
+ * - Union by rank
+ *
+ * Time Complexity (amortized):
+ * - find: O(α(n))
+ * - union: O(α(n))
+ * - connected: O(α(n))
+ */
+declare class DisjointSetUnion<T = number> {
+    private parent;
+    private rank;
+    /**
+     * Creates a new set containing `x` if it doesn't exist.
+     */
+    makeSet(x: T): void;
+    /**
+     * Finds the representative (root) of the set containing `x`.
+     * Applies path compression.
+     */
+    find(x: T): T;
+    /**
+     * Unions the sets containing `x` and `y`.
+     */
+    union(x: T, y: T): void;
+    /**
+     * Checks whether `x` and `y` belong to the same set.
+     */
+    connected(x: T, y: T): boolean;
+    /**
+     * Returns the number of disjoint sets.
+     */
+    countSets(): number;
+    /**
+     * Returns all elements.
+     */
+    elements(): T[];
+    /**
+     * Clears all sets.
+     */
+    clear(): void;
+    /**
+     * Returns total number of elements.
+     */
+    size(): number;
+}
+
+/**
+ * MultiSet (Bag)
+ * --------------
+ * A set-like data structure that allows duplicate elements
+ * and tracks the count of each element.
+ *
+ * Characteristics:
+ * - Elements can appear multiple times
+ * - Count-based operations
+ * - No ordering guarantees
+ */
+declare class MultiSet<T> implements Iterable<[T, number]> {
+    private store;
+    constructor(iterable?: Iterable<T>);
+    add(value: T, count?: number): void;
+    remove(value: T, count?: number): boolean;
+    clear(): void;
+    has(value: T): boolean;
+    count(value: T): number;
+    size(): number;
+    distinctSize(): number;
+    isEmpty(): boolean;
+    values(): T[];
+    entries(): Array<[T, number]>;
+    /**
+     * Union: max(countA, countB)
+     */
+    union(other: MultiSet<T>): MultiSet<T>;
+    /**
+     * Intersection: min(countA, countB)
+     */
+    intersection(other: MultiSet<T>): MultiSet<T>;
+    /**
+     * Difference: countA - countB (floor at 0)
+     */
+    difference(other: MultiSet<T>): MultiSet<T>;
+    [Symbol.iterator](): Iterator<[T, number]>;
+}
+
+/**
+ * OrderedSet
+ * ----------
+ * A set data structure that preserves insertion order.
+ *
+ * Characteristics:
+ * - Unique elements
+ * - Deterministic iteration order
+ * - Supports standard set operations
+ *
+ * Backed by Map to guarantee order.
+ */
+declare class OrderedSet<T> implements Iterable<T> {
+    private store;
+    constructor(iterable?: Iterable<T>);
+    add(value: T): void;
+    delete(value: T): boolean;
+    has(value: T): boolean;
+    clear(): void;
+    size(): number;
+    isEmpty(): boolean;
+    values(): T[];
+    first(): T | undefined;
+    last(): T | undefined;
+    union(other: OrderedSet<T>): OrderedSet<T>;
+    intersection(other: OrderedSet<T>): OrderedSet<T>;
+    difference(other: OrderedSet<T>): OrderedSet<T>;
+    isSubsetOf(other: OrderedSet<T>): boolean;
+    isSupersetOf(other: OrderedSet<T>): boolean;
+    [Symbol.iterator](): Iterator<T>;
+}
+
+/**
+ * Set
+ * ---
+ * A generic Set data structure abstraction.
+ *
+ * Characteristics:
+ * - Stores unique elements
+ * - No ordering guarantees
+ * - Supports standard set operations
+ *
+ * Internally backed by JavaScript's Set,
+ * but exposes a clean, controlled API.
+ */
+declare class Set<T> implements Iterable<T> {
+    private store;
+    constructor(iterable?: Iterable<T>);
+    add(value: T): void;
+    delete(value: T): boolean;
+    has(value: T): boolean;
+    clear(): void;
+    size(): number;
+    isEmpty(): boolean;
+    values(): T[];
+    union(other: Set<T>): Set<T>;
+    intersection(other: Set<T>): Set<T>;
+    difference(other: Set<T>): Set<T>;
+    isSubsetOf(other: Set<T>): boolean;
+    isSupersetOf(other: Set<T>): boolean;
+    [Symbol.iterator](): Iterator<T>;
+}
+
+/**
+ * KDTree (k-dimensional tree)
+ * ---------------------------
+ * A space-partitioning data structure for organizing points
+ * in a k-dimensional space.
+ *
+ * Use cases:
+ * - Nearest neighbor search
+ * - Range queries
+ * - Spatial indexing
+ *
+ * Characteristics:
+ * - Binary tree
+ * - Splits space by alternating dimensions
+ *
+ * Time Complexity (average):
+ * - Build: O(n log n)
+ * - Insert: O(log n)
+ * - Search: O(log n)
+ */
+type Point = number[];
+declare class KDTree<T = any> {
+    private root;
+    private readonly k;
+    constructor(points?: Array<{
+        point: Point;
+        value?: T;
+    }>, dimensions?: number);
+    insert(point: Point, value?: T): void;
+    contains(point: Point): boolean;
+    nearest(target: Point): {
+        point: Point;
+        value?: T;
+    } | null;
+    rangeSearch(min: Point, max: Point): Array<{
+        point: Point;
+        value?: T;
+    }>;
+    isEmpty(): boolean;
+    private build;
+    private insertNode;
+    private findNode;
+    private distanceSquared;
+    private inRange;
+    private pointsEqual;
+}
+
+/**
+ * QuadTree
+ * --------
+ * A 2D spatial partitioning data structure that recursively subdivides
+ * space into four quadrants.
+ */
+type Point2D = {
+    x: number;
+    y: number;
+};
+type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+declare class QuadTree<T = any> {
+    private root;
+    constructor(boundary: Rect, capacity?: number);
+    insert(point: Point2D, value?: T): boolean;
+    contains(point: Point2D): boolean;
+    query(range: Rect): Array<{
+        point: Point2D;
+        value?: T;
+    }>;
+    clear(): void;
+}
+
+/**
+ * MaxStack
+ * --------
+ * Stack with constant-time maximum lookup.
+ *
+ * Characteristics:
+ * - O(1) push / pop / getMax
+ * - Uses auxiliary stack
+ *
+ * Use cases:
+ * - Sliding window problems
+ * - Game stat tracking
+ */
+declare class MaxStack<T> {
+    private stack;
+    private maxStack;
+    size(): number;
+    isEmpty(): boolean;
+    push(value: T): void;
+    pop(): T | undefined;
+    peek(): T | undefined;
+    getMax(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+    toString(): string;
+}
+
+/**
+ * MinStack
+ * --------
+ * Stack with constant-time minimum lookup.
+ *
+ * Characteristics:
+ * - O(1) push / pop / getMin
+ * - Uses auxiliary stack
+ *
+ * Use cases:
+ * - Range queries
+ * - Algorithm optimization
+ */
+declare class MinStack<T> {
+    private stack;
+    private minStack;
+    size(): number;
+    isEmpty(): boolean;
+    push(value: T): void;
+    pop(): T | undefined;
+    peek(): T | undefined;
+    getMin(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+    toString(): string;
+}
+
+/**
+ * Stack
+ * -----
+ * LIFO (Last In First Out) stack implementation.
+ *
+ * Characteristics:
+ * - O(1) push / pop / peek
+ * - Generic
+ * - Iterable (top → bottom)
+ *
+ * Use cases:
+ * - Function calls
+ * - Undo/redo systems
+ * - Expression evaluation
+ */
+declare class Stack<T> implements Iterable<T> {
+    protected items: T[];
+    size(): number;
+    isEmpty(): boolean;
+    push(value: T): void;
+    pop(): T | undefined;
+    peek(): T | undefined;
+    clear(): void;
+    toArray(): T[];
+    [Symbol.iterator](): Iterator<T>;
+    toString(): string;
+}
+
+/**
+ * SuffixArray
+ * -----------
+ * Data structure that stores the sorted order of all suffixes of a string.
+ *
+ * Use cases:
+ * - Fast substring search
+ * - Pattern matching
+ * - Longest repeated substring
+ * - Longest common prefix (with LCP)
+ *
+ * Construction:
+ * - O(n log n) using prefix-doubling
+ */
+declare class SuffixArray {
+    private readonly text;
+    private readonly suffixArray;
+    constructor(text: string);
+    /**
+     * Returns the suffix array (indices of sorted suffixes)
+     */
+    getArray(): number[];
+    /**
+     * Returns the original string
+     */
+    getText(): string;
+    /**
+     * Returns the suffix at a given position in the suffix array
+     */
+    getSuffix(i: number): string;
+    /**
+     * Number of suffixes
+     */
+    size(): number;
+    private buildSuffixArray;
+}
+
+/**
+ * SuffixTree
+ * ----------
+ * A compressed trie of all suffixes of a string.
+ *
+ * Implementation:
+ * - Ukkonen's algorithm (online, O(n))
+ * - Uses implicit end index for leaf edges
+ *
+ * Use cases:
+ * - Fast substring queries
+ * - Longest repeated substring
+ * - Pattern matching
+ */
+declare class SuffixTree {
+    private readonly text;
+    private readonly root;
+    private activeNode;
+    private activeEdge;
+    private activeLength;
+    private remainingSuffixCount;
+    private readonly leafEnd;
+    constructor(text: string);
+    /**
+     * Checks if a pattern exists in the text.
+     * (Traversal only; no extra algorithms.)
+     */
+    contains(pattern: string): boolean;
+    /**
+     * Returns the original text
+     */
+    getText(): string;
+    private build;
+    private extend;
+    private walkDown;
+}
+
+/**
+ * SparseTable
+ * -----------
+ * Data structure for answering range queries on static arrays.
+ *
+ * Supports:
+ * - Range Min Query (RMQ)
+ * - Range Max Query
+ * - Any idempotent operation
+ *
+ * Constraints:
+ * - Array is immutable
+ * - Operation must be associative
+ * - Operation should be idempotent for O(1) queries
+ *
+ * Time Complexity:
+ * - Build: O(n log n)
+ * - Query: O(1)
+ */
+declare class SparseTable<T> {
+    private readonly n;
+    private readonly log;
+    private readonly table;
+    private readonly combine;
+    constructor(arr: T[], combine: (a: T, b: T) => T);
+    /**
+     * Queries range [l, r] inclusive
+     */
+    query(l: number, r: number): T;
+    size(): number;
+}
+
+/**
+ * AVLTree
+ * -------
+ * Self-balancing Binary Search Tree (AVL).
+ *
+ * Properties:
+ * - Balance factor = height(left) - height(right)
+ * - Balance factor ∈ {-1, 0, 1}
+ *
+ * Guarantees:
+ * - O(log n) insert, delete, search
+ */
+declare class AVLTree<T> {
+    private root;
+    private compare;
+    constructor(compareFn?: (a: T, b: T) => number);
+    insert(value: T): void;
+    remove(value: T): void;
+    contains(value: T): boolean;
+    inorder(): T[];
+    preorder(): T[];
+    postorder(): T[];
+    height(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    private insertNode;
+    private removeNode;
+    private search;
+    private rotateRight;
+    private rotateLeft;
+    private rebalance;
+    private nodeHeight;
+    private updateHeight;
+    private getBalance;
+    private findMin;
+    private inorderTraverse;
+    private preorderTraverse;
+    private postorderTraverse;
+}
+
+/**
+ * RedBlackTree
+ * ------------
+ * Self-balancing Binary Search Tree using red-black properties.
+ *
+ * Properties:
+ * 1. Every node is either red or black
+ * 2. Root is always black
+ * 3. Red nodes cannot have red children
+ * 4. Every path from a node to its null leaves
+ *    has the same number of black nodes
+ *
+ * Guarantees:
+ * - O(log n) insert, delete, search
+ */
+declare class RedBlackTree<T> {
+    private root;
+    private compare;
+    constructor(compareFn?: (a: T, b: T) => number);
+    insert(value: T): void;
+    remove(value: T): void;
+    contains(value: T): boolean;
+    inorder(): T[];
+    height(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    private bstInsert;
+    private fixInsert;
+    private deleteNode;
+    private fixDelete;
+    private rotateLeft;
+    private rotateRight;
+    private transplant;
+    private minimum;
+    private findNode;
+    private inorderTraverse;
+    private calculateHeight;
+}
+
+/**
+ * SplayTree
+ * ---------
+ * Self-adjusting Binary Search Tree.
+ *
+ * Properties:
+ * - Recently accessed elements are moved to the root
+ * - Amortized O(log n) for insert, search, delete
+ *
+ * Splaying operations:
+ * - Zig
+ * - Zig-Zig
+ * - Zig-Zag
+ */
+declare class SplayTree<T> {
+    private root;
+    private compare;
+    constructor(compareFn?: (a: T, b: T) => number);
+    insert(value: T): void;
+    contains(value: T): boolean;
+    remove(value: T): void;
+    inorder(): T[];
+    height(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    private splay;
+    private rotateLeft;
+    private rotateRight;
+    private findNode;
+    private replaceRoot;
+    private subtreeMax;
+    private inorderTraverse;
+    private calculateHeight;
+}
+
+/**
+ * BinarySearchTree
+ * ----------------
+ * A classic Binary Search Tree (BST) implementation.
+ *
+ * Properties:
+ * - Left subtree values < node value
+ * - Right subtree values > node value
+ * - No duplicate values (by default)
+ *
+ * Time Complexity:
+ * - Average: O(log n)
+ * - Worst: O(n) (skewed tree)
+ */
+declare class BinarySearchTree<T> {
+    private root;
+    private compare;
+    constructor(compareFn?: (a: T, b: T) => number);
+    insert(value: T): void;
+    contains(value: T): boolean;
+    remove(value: T): void;
+    inorder(): T[];
+    preorder(): T[];
+    postorder(): T[];
+    min(): T | undefined;
+    max(): T | undefined;
+    height(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    private insertNode;
+    private search;
+    private removeNode;
+    private inorderTraverse;
+    private preorderTraverse;
+    private postorderTraverse;
+    private findMin;
+    private findMax;
+    private calculateHeight;
+}
+
+/**
+ * BinaryTree
+ * ----------
+ * A generic binary tree implementation.
+ *
+ * Characteristics:
+ * - Each node has at most two children
+ * - No ordering constraints (not a BST)
+ * - Supports DFS & BFS traversals
+ */
+declare class TreeNode<T> {
+    value: T;
+    left: TreeNode<T> | null;
+    right: TreeNode<T> | null;
+    constructor(value: T);
+}
+declare class BinaryTree<T> {
+    root: TreeNode<T> | null;
+    constructor(rootValue?: T);
+    /**
+     * Inserts a value using level-order traversal
+     * (keeps tree as balanced as possible)
+     */
+    insert(value: T): void;
+    inorder(): T[];
+    preorder(): T[];
+    postorder(): T[];
+    levelOrder(): T[];
+    height(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    private inorderTraverse;
+    private preorderTraverse;
+    private postorderTraverse;
+    private calculateHeight;
+}
+
+/**
+ * BPlusTree
+ * ---------
+ * B+ Tree implementation where:
+ * - All values are stored in leaf nodes
+ * - Internal nodes contain only keys for routing
+ * - Leaf nodes are linked for fast range queries
+ *
+ * Order (t):
+ * - Max keys per node = 2t - 1
+ * - Min keys per non-root node = t - 1
+ *
+ * Time Complexity:
+ * - Search: O(log n)
+ * - Insert: O(log n)
+ * - Delete: O(log n)
+ * - Range Scan: O(log n + k)
+ */
+declare class BPlusTree<T> {
+    private root;
+    private readonly t;
+    private compare;
+    constructor(minDegree: number, compareFn?: (a: T, b: T) => number);
+    search(key: T): boolean;
+    insert(key: T): void;
+    delete(key: T): void;
+    traverse(): T[];
+    range(from: T, to: T): T[];
+    clear(): void;
+    isEmpty(): boolean;
+    private findLeaf;
+    private insertNonFull;
+    private splitChild;
+    private deleteFromNode;
+    private rebalance;
+}
+
+/**
+ * BTree
+ * -----
+ * A classic B-Tree implementation.
+ *
+ * Properties (minimum degree = t):
+ * - Every node has at most 2t - 1 keys
+ * - Every non-root node has at least t - 1 keys
+ * - All leaves appear at the same level
+ *
+ * Time Complexity:
+ * - Search: O(log n)
+ * - Insert: O(log n)
+ * - Delete: O(log n)
+ */
+declare class BTree<T> {
+    private root;
+    private readonly t;
+    private compare;
+    constructor(minDegree: number, compareFn?: (a: T, b: T) => number);
+    search(key: T): boolean;
+    insert(key: T): void;
+    delete(key: T): void;
+    traverse(): T[];
+    clear(): void;
+    isEmpty(): boolean;
+    private searchNode;
+    private insertNonFull;
+    private splitChild;
+    private deleteFromNode;
+    private deleteInternalNode;
+    private fill;
+    private borrowFromPrev;
+    private borrowFromNext;
+    private merge;
+    private findKey;
+    private getPredecessor;
+    private getSuccessor;
+    private traverseNode;
+}
+
+/**
+ * RadixTree (Compressed Trie / Patricia Trie)
+ * -------------------------------------------
+ * Optimized trie where chains of single-child nodes
+ * are compressed into single edges.
+ *
+ * Use cases:
+ * - Autocomplete
+ * - Routing tables
+ * - Prefix matching
+ *
+ * Time Complexity:
+ * - Insert: O(n)
+ * - Search: O(n)
+ * - Delete: O(n)
+ * - Prefix lookup: O(n)
+ */
+declare class RadixTree {
+    private root;
+    insert(word: string): void;
+    search(word: string): boolean;
+    startsWith(prefix: string): boolean;
+    delete(word: string): void;
+    clear(): void;
+    isEmpty(): boolean;
+    private findNode;
+    private deleteHelper;
+    private commonPrefix;
+}
+
+/**
+ * TernarySearchTree (TST)
+ * ----------------------
+ * A space-efficient string tree where each node stores
+ * a single character and has three children:
+ *
+ * - left   → characters less than current
+ * - equal  → next character in word
+ * - right  → characters greater than current
+ *
+ * Time Complexity:
+ * - Insert: O(n)
+ * - Search: O(n)
+ * - Delete: O(n)
+ * - Prefix lookup: O(n)
+ */
+declare class TernarySearchTree {
+    private root;
+    insert(word: string): void;
+    search(word: string): boolean;
+    startsWith(prefix: string): boolean;
+    delete(word: string): void;
+    clear(): void;
+    isEmpty(): boolean;
+    private insertNode;
+    private searchNode;
+    private deleteNode;
+}
+
+/**
+ * Trie (Prefix Tree)
+ * ------------------
+ * Efficient tree-based data structure for storing strings.
+ *
+ * Use cases:
+ * - Autocomplete
+ * - Spell checking
+ * - Prefix search
+ *
+ * Time Complexity:
+ * - Insert: O(n)
+ * - Search: O(n)
+ * - Delete: O(n)
+ * - Prefix lookup: O(n)
+ */
+declare class Trie {
+    private root;
+    insert(word: string): void;
+    search(word: string): boolean;
+    startsWith(prefix: string): boolean;
+    delete(word: string): void;
+    clear(): void;
+    isEmpty(): boolean;
+    private findNode;
+    private deleteHelper;
+}
+
+/**
+ * FenwickTree (Binary Indexed Tree)
+ * --------------------------------
+ * Efficient data structure for prefix sums.
+ *
+ * Supports:
+ * - Point update: O(log n)
+ * - Prefix sum query: O(log n)
+ * - Range sum query: O(log n)
+ *
+ * Internally uses 1-based indexing.
+ */
+declare class FenwickTree {
+    private readonly n;
+    private tree;
+    constructor(sizeOrArray: number | number[]);
+    /**
+     * Add value to index (0-based)
+     */
+    add(index: number, value: number): void;
+    /**
+     * Prefix sum from 0 to index (inclusive)
+     */
+    sum(index: number): number;
+    /**
+     * Range sum [left, right]
+     */
+    rangeSum(left: number, right: number): number;
+    /**
+     * Get size of tree
+     */
+    size(): number;
+    /**
+     * Reset all values
+     */
+    clear(): void;
+}
+
+/**
+ * IntervalTree
+ * ------------
+ * Augmented Binary Search Tree for interval overlap queries.
+ *
+ * Each node stores:
+ * - interval [low, high]
+ * - max: maximum high endpoint in its subtree
+ *
+ * Time Complexity (average):
+ * - Insert: O(log n)
+ * - Delete: O(log n)
+ * - Search overlap: O(log n)
+ * - Search all overlaps: O(k + log n)
+ */
+interface Interval {
+    low: number;
+    high: number;
+}
+declare class IntervalTree {
+    private root;
+    insert(interval: Interval): void;
+    delete(interval: Interval): void;
+    /**
+     * Returns true if any interval overlaps with the query interval
+     */
+    search(query: Interval): boolean;
+    /**
+     * Returns all intervals that overlap with the query interval
+     */
+    searchAll(query: Interval): Interval[];
+    /**
+     * In-order traversal (sorted by low)
+     */
+    traverse(): Interval[];
+    clear(): void;
+    isEmpty(): boolean;
+    private insertNode;
+    private deleteNode;
+    private searchAny;
+    private searchAllFrom;
+    private overlaps;
+    private minNode;
+    private inOrder;
+}
+
+/**
+ * SegmentTree
+ * -----------
+ * A generic segment tree implementation for range queries.
+ *
+ * Supports:
+ * - Range query: O(log n)
+ * - Point update: O(log n)
+ *
+ * Requirements:
+ * - Merge function must be associative
+ *
+ * Examples:
+ * - Sum: (a, b) => a + b
+ * - Min: Math.min
+ * - Max: Math.max
+ */
+declare class SegmentTree<T> {
+    private tree;
+    private data;
+    private readonly n;
+    private readonly merge;
+    private readonly identity;
+    constructor(arr: T[], mergeFn: (a: T, b: T) => T, identity: T);
+    /**
+     * Query range [l, r]
+     */
+    query(l: number, r: number): T;
+    /**
+     * Update value at index
+     */
+    update(index: number, value: T): void;
+    /**
+     * Get original array
+     */
+    toArray(): T[];
+    size(): number;
+    private build;
+    private queryRange;
+    private updatePoint;
+}
+
 declare class AppError extends Error {
     statusCode: number;
     status: string;
@@ -135,4 +1827,16 @@ interface CrudService<T> {
     deleteById(id: string): Promise<T>;
 }
 
-export { APIFactory, APIFeatures, APIResponse, type AllowedOriginsOptions, AppError, BaseService, type CrudService, type DatabaseConfig, GlobalErrorHandler, type LoggerOptions, asyncHandler, authMiddleware, connectMongoDB, createAllowedOrigins, createCorsOptions, loadEnv, logger, validate };
+declare function errorToString(error: unknown): string;
+
+declare function milliseconds(value: number): number;
+declare function seconds(value: number): number;
+declare function minutes(value: number): number;
+declare function hours(value: number): number;
+declare function days(value: number): number;
+declare function toSeconds(ms: number): number;
+declare function toMinutes(ms: number): number;
+declare function toHours(ms: number): number;
+declare function sleep(ms: number): Promise<void>;
+
+export { APIFactory, APIFeatures, APIResponse, AVLTree, AdjacencyList, AdjacencyMatrix, type AdjacentEdge, type AllowedOriginsOptions, AppError, BPlusTree, BTree, BaseService, BinaryHeap, BinarySearchTree, BinaryTree, BloomFilter, CircularArray, CircularLinkedList, CircularQueue, ConsistentHash, CountMinSketch, type CrudService, type DatabaseConfig, Deque, type DirectedEdge, DirectedGraph, DisjointSetUnion, DoublyLinkedList, DynamicArray, type Edge, FenwickTree, FibNode, FibonacciHeap, GlobalErrorHandler, Graph, HashMap, HashSet, HyperLogLog, type Interval, IntervalTree, KDTree, LFUCache, LRUCache, type LoggerOptions, MaxHeap, MaxStack, MinHeap, MinStack, MultiSet, Node, OrderedSet, PairingHeap, PairingNode, type Point, type Point2D, PriorityQueue, QuadTree, Queue, RadixTree, type Rect, RedBlackTree, SegmentTree, Set, SinglyLinkedList, SparseTable, SplayTree, Stack, StaticArray, SuffixArray, SuffixTree, TernarySearchTree, TreeNode, Trie, asyncHandler, authMiddleware, connectMongoDB, createAllowedOrigins, createCorsOptions, days, errorToString, hours, loadEnv, logger, milliseconds, minutes, seconds, sleep, toHours, toMinutes, toSeconds, validate };