binary-tree-typed 2.4.5 → 2.5.1

package/src/data-structures/priority-queue/max-priority-queue.ts

@@ -16,6 +16,63 @@ import { ERR } from '../../common';
  * @template E Element type stored in the queue.
  * @template R Extra record/metadata associated with each element.
  * @example
+ * // Job scheduling by priority
+ *  const jobs = new MaxPriorityQueue<number>();
+ *
+ *     jobs.add(3); // low priority
+ *     jobs.add(7); // high priority
+ *     jobs.add(5); // medium priority
+ *     jobs.add(10); // critical
+ *
+ *     // Highest priority job first
+ *     console.log(jobs.poll()); // 10;
+ *     console.log(jobs.poll()); // 7;
+ *     console.log(jobs.poll()); // 5;
+ *     console.log(jobs.poll()); // 3;
+ * @example
+ * // Auction system with highest bid tracking
+ *  interface Bid {
+ *       bidder: string;
+ *       amount: number;
+ *     }
+ *
+ *     const auction = new MaxPriorityQueue<Bid>([], {
+ *       comparator: (a, b) => b.amount - a.amount
+ *     });
+ *
+ *     auction.add({ bidder: 'Alice', amount: 100 });
+ *     auction.add({ bidder: 'Bob', amount: 250 });
+ *     auction.add({ bidder: 'Charlie', amount: 175 });
+ *
+ *     // Current highest bid
+ *     console.log(auction.peek()?.bidder); // 'Bob';
+ *     console.log(auction.peek()?.amount); // 250;
+ *
+ *     // Process winning bid
+ *     const winner = auction.poll()!;
+ *     console.log(winner.bidder); // 'Bob';
+ *     console.log(auction.peek()?.bidder); // 'Charlie';
+ * @example
+ * // CPU process scheduling
+ *  const cpuQueue = new MaxPriorityQueue<[number, string]>([], {
+ *       comparator: (a, b) => b[0] - a[0]
+ *     });
+ *
+ *     cpuQueue.add([5, 'System process']);
+ *     cpuQueue.add([1, 'Background task']);
+ *     cpuQueue.add([8, 'User interaction']);
+ *     cpuQueue.add([3, 'Network sync']);
+ *
+ *     const order = [];
+ *     while (cpuQueue.size > 0) {
+ *       order.push(cpuQueue.poll()![1]);
+ *     }
+ *     console.log(order); // [
+ *  //      'User interaction',
+ *  //      'System process',
+ *  //      'Network sync',
+ *  //      'Background task'
+ *  //    ];
  */
 export class MaxPriorityQueue<E = any, R = any> extends PriorityQueue<E, R> {
   /**

package/src/data-structures/priority-queue/min-priority-queue.ts

@@ -15,6 +15,66 @@ import { PriorityQueue } from './priority-queue';
  * @template E Element type stored in the queue.
  * @template R Extra record/metadata associated with each element.
  * @example
+ * // Shortest job first scheduling
+ *  const jobs = new MinPriorityQueue<number>();
+ *
+ *     jobs.add(8);  // 8 seconds
+ *     jobs.add(2);  // 2 seconds
+ *     jobs.add(5);  // 5 seconds
+ *     jobs.add(1);  // 1 second
+ *
+ *     // Shortest job first
+ *     console.log(jobs.poll()); // 1;
+ *     console.log(jobs.poll()); // 2;
+ *     console.log(jobs.poll()); // 5;
+ *     console.log(jobs.poll()); // 8;
+ * @example
+ * // Event-driven simulation with timestamps
+ *  interface Event {
+ *       time: number;
+ *       action: string;
+ *     }
+ *
+ *     const timeline = new MinPriorityQueue<Event>([], {
+ *       comparator: (a, b) => a.time - b.time
+ *     });
+ *
+ *     timeline.add({ time: 300, action: 'Timeout' });
+ *     timeline.add({ time: 100, action: 'Request received' });
+ *     timeline.add({ time: 200, action: 'Processing done' });
+ *     timeline.add({ time: 150, action: 'Cache hit' });
+ *
+ *     const order = [];
+ *     while (timeline.size > 0) {
+ *       order.push(timeline.poll()!.action);
+ *     }
+ *     console.log(order); // [
+ *  //      'Request received',
+ *  //      'Cache hit',
+ *  //      'Processing done',
+ *  //      'Timeout'
+ *  //    ];
+ * @example
+ * // Huffman coding frequency selection
+ *  // Character frequencies for Huffman tree building
+ *     const freq = new MinPriorityQueue<[number, string]>([], {
+ *       comparator: (a, b) => a[0] - b[0]
+ *     });
+ *
+ *     freq.add([5, 'a']);
+ *     freq.add([9, 'b']);
+ *     freq.add([12, 'c']);
+ *     freq.add([2, 'd']);
+ *
+ *     // Always pick two lowest frequencies
+ *     const first = freq.poll()!;
+ *     const second = freq.poll()!;
+ *     console.log(first[1]); // 'd';  // freq 2
+ *     console.log(second[1]); // 'a'; // freq 5
+ *
+ *     // Combined node goes back
+ *     freq.add([first[0] + second[0], first[1] + second[1]]);
+ *     console.log(freq.peek()![0]); // 7;
  */
 export class MinPriorityQueue<E = any, R = any> extends PriorityQueue<E, R> {
   /**

package/src/data-structures/priority-queue/priority-queue.ts

@@ -11,6 +11,66 @@ import { Heap } from '../heap';
 
 /**
  * @example
+ * // Hospital emergency room triage
+ *  interface Patient {
+ *       name: string;
+ *       severity: number; // 1 = critical, 5 = minor
+ *     }
+ *
+ *     const er = new PriorityQueue<Patient>([], {
+ *       comparator: (a, b) => a.severity - b.severity
+ *     });
+ *
+ *     er.add({ name: 'Flu symptoms', severity: 4 });
+ *     er.add({ name: 'Heart attack', severity: 1 });
+ *     er.add({ name: 'Broken arm', severity: 3 });
+ *     er.add({ name: 'Stroke', severity: 1 });
+ *
+ *     // Most critical patients first
+ *     console.log(er.poll()?.severity); // 1;
+ *     console.log(er.poll()?.severity); // 1;
+ *     console.log(er.poll()?.severity); // 3;
+ *     console.log(er.poll()?.severity); // 4;
+ * @example
+ * // Task scheduler with deadlines
+ *  interface Task {
+ *       name: string;
+ *       deadline: number; // hours until due
+ *     }
+ *
+ *     const scheduler = new PriorityQueue<Task>([], {
+ *       comparator: (a, b) => a.deadline - b.deadline
+ *     });
+ *
+ *     scheduler.add({ name: 'Report', deadline: 24 });
+ *     scheduler.add({ name: 'Email', deadline: 2 });
+ *     scheduler.add({ name: 'Meeting prep', deadline: 4 });
+ *     scheduler.add({ name: 'Code review', deadline: 8 });
+ *
+ *     // Process most urgent first
+ *     console.log(scheduler.peek()?.name); // 'Email';
+ *     console.log(scheduler.size); // 4;
+ *
+ *     const order = [];
+ *     while (scheduler.size > 0) {
+ *       order.push(scheduler.poll()!.name);
+ *     }
+ *     console.log(order); // ['Email', 'Meeting prep', 'Code review', 'Report'];
+ * @example
+ * // Bandwidth allocation with priorities
+ *  const bandwidth = new PriorityQueue<[number, string]>([], {
+ *       comparator: (a, b) => a[0] - b[0]
+ *     });
+ *
+ *     bandwidth.add([1, 'Video call']);     // highest priority
+ *     bandwidth.add([3, 'File download']);
+ *     bandwidth.add([2, 'Web browsing']);
+ *     bandwidth.add([1, 'Voice call']);
+ *
+ *     // Allocate bandwidth to highest priority first
+ *     console.log(bandwidth.poll()?.[1]); // 'Video call';
+ *     console.log(bandwidth.poll()?.[1]); // 'Voice call';
+ *     console.log(bandwidth.size); // 2;
  */
 export class PriorityQueue<E = any, R = any> extends Heap<E, R> {
   constructor(elements: Iterable<E> | Iterable<R> = [], options?: PriorityQueueOptions<E, R>) {