feat(core/stdlib): implement LinkedList, PriorityQueue, and Queue data structures
This commit is contained in:
@@ -0,0 +1,229 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
|
||||
import { BinaryHeap } from '.';
|
||||
|
||||
describe('BinaryHeap', () => {
|
||||
describe('constructor', () => {
|
||||
it('should create an empty heap', () => {
|
||||
const heap = new BinaryHeap<number>();
|
||||
|
||||
expect(heap.length).toBe(0);
|
||||
expect(heap.isEmpty).toBe(true);
|
||||
});
|
||||
|
||||
it('should create a heap from single value', () => {
|
||||
const heap = new BinaryHeap(42);
|
||||
|
||||
expect(heap.length).toBe(1);
|
||||
expect(heap.peek()).toBe(42);
|
||||
});
|
||||
|
||||
it('should create a heap from array (heapify)', () => {
|
||||
const heap = new BinaryHeap([5, 3, 8, 1, 4]);
|
||||
|
||||
expect(heap.length).toBe(5);
|
||||
expect(heap.peek()).toBe(1);
|
||||
});
|
||||
|
||||
it('should accept a custom comparator for max-heap', () => {
|
||||
const heap = new BinaryHeap([5, 3, 8, 1, 4], {
|
||||
comparator: (a, b) => b - a,
|
||||
});
|
||||
|
||||
expect(heap.peek()).toBe(8);
|
||||
});
|
||||
});
|
||||
|
||||
describe('push', () => {
|
||||
it('should insert elements maintaining heap property', () => {
|
||||
const heap = new BinaryHeap<number>();
|
||||
|
||||
heap.push(5);
|
||||
heap.push(3);
|
||||
heap.push(8);
|
||||
heap.push(1);
|
||||
|
||||
expect(heap.peek()).toBe(1);
|
||||
expect(heap.length).toBe(4);
|
||||
});
|
||||
|
||||
it('should handle duplicate values', () => {
|
||||
const heap = new BinaryHeap<number>();
|
||||
|
||||
heap.push(3);
|
||||
heap.push(3);
|
||||
heap.push(3);
|
||||
|
||||
expect(heap.length).toBe(3);
|
||||
expect(heap.peek()).toBe(3);
|
||||
});
|
||||
});
|
||||
|
||||
describe('pop', () => {
|
||||
it('should return undefined for empty heap', () => {
|
||||
const heap = new BinaryHeap<number>();
|
||||
|
||||
expect(heap.pop()).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should extract elements in min-heap order', () => {
|
||||
const heap = new BinaryHeap([5, 3, 8, 1, 4, 2, 7, 6]);
|
||||
const sorted: number[] = [];
|
||||
|
||||
while (!heap.isEmpty) {
|
||||
sorted.push(heap.pop()!);
|
||||
}
|
||||
|
||||
expect(sorted).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
|
||||
});
|
||||
|
||||
it('should extract elements in max-heap order with custom comparator', () => {
|
||||
const heap = new BinaryHeap([5, 3, 8, 1, 4], {
|
||||
comparator: (a, b) => b - a,
|
||||
});
|
||||
const sorted: number[] = [];
|
||||
|
||||
while (!heap.isEmpty) {
|
||||
sorted.push(heap.pop()!);
|
||||
}
|
||||
|
||||
expect(sorted).toEqual([8, 5, 4, 3, 1]);
|
||||
});
|
||||
|
||||
it('should handle single element', () => {
|
||||
const heap = new BinaryHeap(42);
|
||||
|
||||
expect(heap.pop()).toBe(42);
|
||||
expect(heap.isEmpty).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('peek', () => {
|
||||
it('should return undefined for empty heap', () => {
|
||||
const heap = new BinaryHeap<number>();
|
||||
|
||||
expect(heap.peek()).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should return root without removing it', () => {
|
||||
const heap = new BinaryHeap([5, 3, 1]);
|
||||
|
||||
expect(heap.peek()).toBe(1);
|
||||
expect(heap.length).toBe(3);
|
||||
});
|
||||
});
|
||||
|
||||
describe('clear', () => {
|
||||
it('should remove all elements', () => {
|
||||
const heap = new BinaryHeap([1, 2, 3]);
|
||||
|
||||
const result = heap.clear();
|
||||
|
||||
expect(heap.length).toBe(0);
|
||||
expect(heap.isEmpty).toBe(true);
|
||||
expect(result).toBe(heap);
|
||||
});
|
||||
});
|
||||
|
||||
describe('toArray', () => {
|
||||
it('should return empty array for empty heap', () => {
|
||||
const heap = new BinaryHeap<number>();
|
||||
|
||||
expect(heap.toArray()).toEqual([]);
|
||||
});
|
||||
|
||||
it('should return a shallow copy', () => {
|
||||
const heap = new BinaryHeap([3, 1, 2]);
|
||||
const arr = heap.toArray();
|
||||
|
||||
arr.push(99);
|
||||
|
||||
expect(heap.length).toBe(3);
|
||||
});
|
||||
});
|
||||
|
||||
describe('toString', () => {
|
||||
it('should return formatted string', () => {
|
||||
const heap = new BinaryHeap([1, 2, 3]);
|
||||
|
||||
expect(heap.toString()).toBe('BinaryHeap(3)');
|
||||
});
|
||||
});
|
||||
|
||||
describe('iterator', () => {
|
||||
it('should iterate over heap elements', () => {
|
||||
const heap = new BinaryHeap([5, 3, 8, 1]);
|
||||
const elements = [...heap];
|
||||
|
||||
expect(elements.length).toBe(4);
|
||||
expect(elements[0]).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('custom comparator', () => {
|
||||
it('should work with string length comparator', () => {
|
||||
const heap = new BinaryHeap(['banana', 'apple', 'kiwi', 'fig'], {
|
||||
comparator: (a, b) => a.length - b.length,
|
||||
});
|
||||
|
||||
expect(heap.pop()).toBe('fig');
|
||||
expect(heap.pop()).toBe('kiwi');
|
||||
});
|
||||
|
||||
it('should work with object comparator', () => {
|
||||
interface Task {
|
||||
priority: number;
|
||||
name: string;
|
||||
}
|
||||
|
||||
const heap = new BinaryHeap<Task>(
|
||||
[
|
||||
{ priority: 3, name: 'low' },
|
||||
{ priority: 1, name: 'high' },
|
||||
{ priority: 2, name: 'medium' },
|
||||
],
|
||||
{ comparator: (a, b) => a.priority - b.priority },
|
||||
);
|
||||
|
||||
expect(heap.pop()?.name).toBe('high');
|
||||
expect(heap.pop()?.name).toBe('medium');
|
||||
expect(heap.pop()?.name).toBe('low');
|
||||
});
|
||||
});
|
||||
|
||||
describe('heapify', () => {
|
||||
it('should correctly heapify large arrays', () => {
|
||||
const values = Array.from({ length: 1000 }, () => Math.random() * 1000 | 0);
|
||||
const heap = new BinaryHeap(values);
|
||||
const sorted: number[] = [];
|
||||
|
||||
while (!heap.isEmpty) {
|
||||
sorted.push(heap.pop()!);
|
||||
}
|
||||
|
||||
const expected = [...values].sort((a, b) => a - b);
|
||||
|
||||
expect(sorted).toEqual(expected);
|
||||
});
|
||||
});
|
||||
|
||||
describe('interleaved operations', () => {
|
||||
it('should maintain heap property with mixed push and pop', () => {
|
||||
const heap = new BinaryHeap<number>();
|
||||
|
||||
heap.push(10);
|
||||
heap.push(5);
|
||||
expect(heap.pop()).toBe(5);
|
||||
|
||||
heap.push(3);
|
||||
heap.push(7);
|
||||
expect(heap.pop()).toBe(3);
|
||||
|
||||
heap.push(1);
|
||||
expect(heap.pop()).toBe(1);
|
||||
expect(heap.pop()).toBe(7);
|
||||
expect(heap.pop()).toBe(10);
|
||||
expect(heap.pop()).toBeUndefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,220 @@
|
||||
import { first } from '../../arrays';
|
||||
import { isArray } from '../../types';
|
||||
import type { BinaryHeapLike, Comparator } from './types';
|
||||
|
||||
export type { BinaryHeapLike, Comparator } from './types';
|
||||
|
||||
export interface BinaryHeapOptions<T> {
|
||||
comparator?: Comparator<T>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Default min-heap comparator for numeric values
|
||||
*
|
||||
* @param {number} a First element
|
||||
* @param {number} b Second element
|
||||
* @returns {number} Negative if a < b, positive if a > b, zero if equal
|
||||
*/
|
||||
const defaultComparator: Comparator<any> = (a: number, b: number) => a - b;
|
||||
|
||||
/**
|
||||
* @name BinaryHeap
|
||||
* @category Data Structures
|
||||
* @description Binary heap backed by a flat array with configurable comparator
|
||||
*
|
||||
* @since 0.0.8
|
||||
*
|
||||
* @template T The type of elements stored in the heap
|
||||
*/
|
||||
export class BinaryHeap<T> implements BinaryHeapLike<T> {
|
||||
/**
|
||||
* The comparator function used to order elements
|
||||
*
|
||||
* @private
|
||||
* @type {Comparator<T>}
|
||||
*/
|
||||
private readonly comparator: Comparator<T>;
|
||||
|
||||
/**
|
||||
* Internal flat array backing the heap
|
||||
*
|
||||
* @private
|
||||
* @type {T[]}
|
||||
*/
|
||||
private readonly heap: T[] = [];
|
||||
|
||||
/**
|
||||
* Creates an instance of BinaryHeap
|
||||
*
|
||||
* @param {(T[] | T)} [initialValues] The initial values to heapify
|
||||
* @param {BinaryHeapOptions<T>} [options] Heap configuration
|
||||
*/
|
||||
constructor(initialValues?: T[] | T, options?: BinaryHeapOptions<T>) {
|
||||
this.comparator = options?.comparator ?? defaultComparator;
|
||||
|
||||
if (initialValues != null) {
|
||||
const items = isArray(initialValues) ? initialValues : [initialValues];
|
||||
this.heap.push(...items);
|
||||
this.heapify();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets the number of elements in the heap
|
||||
* @returns {number} The number of elements in the heap
|
||||
*/
|
||||
public get length(): number {
|
||||
return this.heap.length;
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks if the heap is empty
|
||||
* @returns {boolean} `true` if the heap is empty, `false` otherwise
|
||||
*/
|
||||
public get isEmpty(): boolean {
|
||||
return this.heap.length === 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pushes an element into the heap
|
||||
* @param {T} element The element to insert
|
||||
*/
|
||||
public push(element: T): void {
|
||||
this.heap.push(element);
|
||||
this.siftUp(this.heap.length - 1);
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes and returns the root element (min or max depending on comparator)
|
||||
* @returns {T | undefined} The root element, or `undefined` if the heap is empty
|
||||
*/
|
||||
public pop(): T | undefined {
|
||||
if (this.heap.length === 0) return undefined;
|
||||
|
||||
const root = first(this.heap)!;
|
||||
const last = this.heap.pop()!;
|
||||
|
||||
if (this.heap.length > 0) {
|
||||
this.heap[0] = last;
|
||||
this.siftDown(0);
|
||||
}
|
||||
|
||||
return root;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the root element without removing it
|
||||
* @returns {T | undefined} The root element, or `undefined` if the heap is empty
|
||||
*/
|
||||
public peek(): T | undefined {
|
||||
return first(this.heap);
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes all elements from the heap
|
||||
* @returns {this} The heap instance for chaining
|
||||
*/
|
||||
public clear(): this {
|
||||
this.heap.length = 0;
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a shallow copy of the heap elements as an array (heap order, not sorted)
|
||||
* @returns {T[]} Array of elements in heap order
|
||||
*/
|
||||
public toArray(): T[] {
|
||||
return this.heap.slice();
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a string representation of the heap
|
||||
* @returns {string} String representation
|
||||
*/
|
||||
public toString(): string {
|
||||
return `BinaryHeap(${this.heap.length})`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Iterator over heap elements in heap order
|
||||
*/
|
||||
public *[Symbol.iterator](): Iterator<T> {
|
||||
yield* this.heap;
|
||||
}
|
||||
|
||||
/**
|
||||
* Async iterator over heap elements in heap order
|
||||
*/
|
||||
public async *[Symbol.asyncIterator](): AsyncIterator<T> {
|
||||
for (const element of this.heap)
|
||||
yield element;
|
||||
}
|
||||
|
||||
/**
|
||||
* Restores heap property by sifting an element up
|
||||
*
|
||||
* @private
|
||||
* @param {number} index The index of the element to sift up
|
||||
*/
|
||||
private siftUp(index: number): void {
|
||||
const heap = this.heap;
|
||||
const cmp = this.comparator;
|
||||
|
||||
while (index > 0) {
|
||||
const parent = (index - 1) >> 1;
|
||||
|
||||
if (cmp(heap[index]!, heap[parent]!) >= 0) break;
|
||||
|
||||
const temp = heap[index]!;
|
||||
heap[index] = heap[parent]!;
|
||||
heap[parent] = temp;
|
||||
|
||||
index = parent;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Restores heap property by sifting an element down
|
||||
*
|
||||
* @private
|
||||
* @param {number} index The index of the element to sift down
|
||||
*/
|
||||
private siftDown(index: number): void {
|
||||
const heap = this.heap;
|
||||
const cmp = this.comparator;
|
||||
const length = heap.length;
|
||||
|
||||
while (true) {
|
||||
let smallest = index;
|
||||
const left = 2 * index + 1;
|
||||
const right = 2 * index + 2;
|
||||
|
||||
if (left < length && cmp(heap[left]!, heap[smallest]!) < 0) {
|
||||
smallest = left;
|
||||
}
|
||||
|
||||
if (right < length && cmp(heap[right]!, heap[smallest]!) < 0) {
|
||||
smallest = right;
|
||||
}
|
||||
|
||||
if (smallest === index) break;
|
||||
|
||||
const temp = heap[index]!;
|
||||
heap[index] = heap[smallest]!;
|
||||
heap[smallest] = temp;
|
||||
|
||||
index = smallest;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Builds heap from unordered array in O(n) using Floyd's algorithm
|
||||
*
|
||||
* @private
|
||||
*/
|
||||
private heapify(): void {
|
||||
for (let i = (this.heap.length >> 1) - 1; i >= 0; i--) {
|
||||
this.siftDown(i);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
export type Comparator<T> = (a: T, b: T) => number;
|
||||
|
||||
export interface BinaryHeapLike<T> extends Iterable<T>, AsyncIterable<T> {
|
||||
readonly length: number;
|
||||
readonly isEmpty: boolean;
|
||||
|
||||
push(element: T): void;
|
||||
pop(): T | undefined;
|
||||
peek(): T | undefined;
|
||||
clear(): this;
|
||||
toArray(): T[];
|
||||
toString(): string;
|
||||
}
|
||||
Reference in New Issue
Block a user