@graphty/algorithms 1.0.1

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

@@ -0,0 +1,180 @@
+/**
+ * Priority Queue implementation using a binary heap
+ *
+ * Optimized for graph algorithms requiring efficient priority-based operations.
+ * Uses a min-heap by default but supports custom comparison functions.
+ */
+export class PriorityQueue<T> {
+    private heap: {item: T, priority: number}[];
+    private compareFn: (a: number, b: number) => number;
+
+    constructor(compareFn?: (a: number, b: number) => number) {
+        this.heap = [];
+        // Default to min-heap (smaller priority values have higher priority)
+        this.compareFn = compareFn ?? ((a, b) => a - b);
+    }
+
+    /**
+     * Add an item with the given priority to the queue
+     */
+    enqueue(item: T, priority: number): void {
+        const element = {item, priority};
+        this.heap.push(element);
+        this.heapifyUp(this.heap.length - 1);
+    }
+
+    /**
+     * Remove and return the item with the highest priority
+     */
+    dequeue(): T | undefined {
+        if (this.heap.length === 0) {
+            return undefined;
+        }
+
+        if (this.heap.length === 1) {
+            return this.heap.pop()?.item;
+        }
+
+        const root = this.heap[0];
+        const lastElement = this.heap.pop();
+
+        if (!root) {
+            return undefined;
+        }
+
+        if (lastElement) {
+            this.heap[0] = lastElement;
+            this.heapifyDown(0);
+        }
+
+        return root.item;
+    }
+
+    /**
+     * View the item with the highest priority without removing it
+     */
+    peek(): T | undefined {
+        const first = this.heap[0];
+        return first ? first.item : undefined;
+    }
+
+    /**
+     * Check if the queue is empty
+     */
+    isEmpty(): boolean {
+        return this.heap.length === 0;
+    }
+
+    /**
+     * Get the number of items in the queue
+     */
+    size(): number {
+        return this.heap.length;
+    }
+
+    /**
+     * Update the priority of an item if it exists in the queue
+     * Returns true if the item was found and updated
+     */
+    updatePriority(item: T, newPriority: number): boolean {
+        const index = this.heap.findIndex((element) => element.item === item);
+
+        if (index === -1) {
+            return false;
+        }
+
+        const element = this.heap[index];
+        if (!element) {
+            return false;
+        }
+
+        const oldPriority = element.priority;
+        element.priority = newPriority;
+
+        // Determine whether to heapify up or down based on priority change
+        if (this.compareFn(newPriority, oldPriority) < 0) {
+            this.heapifyUp(index);
+        } else if (this.compareFn(newPriority, oldPriority) > 0) {
+            this.heapifyDown(index);
+        }
+
+        return true;
+    }
+
+    /**
+     * Clear all items from the queue
+     */
+    clear(): void {
+        this.heap = [];
+    }
+
+    /**
+     * Convert queue to array (for testing/debugging)
+     */
+    toArray(): {item: T, priority: number}[] {
+        return [... this.heap];
+    }
+
+    /**
+     * Move element up the heap until heap property is satisfied
+     */
+    private heapifyUp(index: number): void {
+        if (index === 0) {
+            return;
+        }
+
+        const parentIndex = Math.floor((index - 1) / 2);
+
+        const current = this.heap[index];
+        const parent = this.heap[parentIndex];
+
+        if (current && parent && this.compareFn(current.priority, parent.priority) < 0) {
+            this.swap(index, parentIndex);
+            this.heapifyUp(parentIndex);
+        }
+    }
+
+    /**
+     * Move element down the heap until heap property is satisfied
+     */
+    private heapifyDown(index: number): void {
+        const leftChildIndex = (2 * index) + 1;
+        const rightChildIndex = (2 * index) + 2;
+        let targetIndex = index;
+
+        // Find the child with highest priority (lowest value for min-heap)
+        const leftChild = this.heap[leftChildIndex];
+        const target = this.heap[targetIndex];
+
+        if (leftChildIndex < this.heap.length && leftChild && target &&
+            this.compareFn(leftChild.priority, target.priority) < 0) {
+            targetIndex = leftChildIndex;
+        }
+
+        const rightChild = this.heap[rightChildIndex];
+        const newTarget = this.heap[targetIndex];
+
+        if (rightChildIndex < this.heap.length && rightChild && newTarget &&
+            this.compareFn(rightChild.priority, newTarget.priority) < 0) {
+            targetIndex = rightChildIndex;
+        }
+
+        // If we found a child with higher priority, swap and continue
+        if (targetIndex !== index) {
+            this.swap(index, targetIndex);
+            this.heapifyDown(targetIndex);
+        }
+    }
+
+    /**
+     * Swap two elements in the heap
+     */
+    private swap(i: number, j: number): void {
+        const temp = this.heap[i];
+        const other = this.heap[j];
+        if (temp && other) {
+            this.heap[i] = other;
+            this.heap[j] = temp;
+        }
+    }
+}

package/src/data-structures/union-find.ts

@@ -0,0 +1,170 @@
+import type {NodeId} from "../types/index.js";
+
+/**
+ * Union-Find (Disjoint Set) data structure with path compression and union by rank
+ *
+ * Efficiently supports dynamic connectivity queries and is essential for
+ * algorithms like connected components and minimum spanning trees.
+ */
+export class UnionFind {
+    private parent: Map<NodeId, NodeId>;
+    private rank: Map<NodeId, number>;
+    private componentCount: number;
+
+    constructor(elements: NodeId[]) {
+        this.parent = new Map();
+        this.rank = new Map();
+        this.componentCount = elements.length;
+
+        // Initialize each element as its own parent with rank 0
+        for (const element of elements) {
+            this.parent.set(element, element);
+            this.rank.set(element, 0);
+        }
+    }
+
+    /**
+     * Find the root of the set containing the element with path compression
+     */
+    find(element: NodeId): NodeId {
+        const parent = this.parent.get(element);
+
+        if (parent === undefined) {
+            throw new Error(`Element ${String(element)} not found in UnionFind`);
+        }
+
+        // Path compression: make every node on the path point directly to the root
+        if (parent !== element) {
+            this.parent.set(element, this.find(parent));
+        }
+
+        const result = this.parent.get(element);
+        if (result === undefined) {
+            throw new Error(`Element ${String(element)} not found in UnionFind`);
+        }
+
+        return result;
+    }
+
+    /**
+     * Union two sets using union by rank
+     */
+    union(elementA: NodeId, elementB: NodeId): void {
+        const rootA = this.find(elementA);
+        const rootB = this.find(elementB);
+
+        // Already in the same set
+        if (rootA === rootB) {
+            return;
+        }
+
+        const rankA = this.rank.get(rootA);
+        const rankB = this.rank.get(rootB);
+        if (rankA === undefined || rankB === undefined) {
+            throw new Error("Rank not found for root elements");
+        }
+
+        // Union by rank: attach smaller tree under root of larger tree
+        if (rankA < rankB) {
+            this.parent.set(rootA, rootB);
+        } else if (rankA > rankB) {
+            this.parent.set(rootB, rootA);
+        } else {
+            // Same rank: make one root and increment its rank
+            this.parent.set(rootB, rootA);
+            this.rank.set(rootA, rankA + 1);
+        }
+
+        this.componentCount--;
+    }
+
+    /**
+     * Check if two elements are in the same connected component
+     */
+    connected(elementA: NodeId, elementB: NodeId): boolean {
+        try {
+            return this.find(elementA) === this.find(elementB);
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Get the number of connected components
+     */
+    getComponentCount(): number {
+        return this.componentCount;
+    }
+
+    /**
+     * Get all elements that belong to the same component as the given element
+     */
+    getComponent(element: NodeId): NodeId[] {
+        const root = this.find(element);
+        const component: NodeId[] = [];
+
+        for (const [node] of this.parent) {
+            if (this.find(node) === root) {
+                component.push(node);
+            }
+        }
+
+        return component;
+    }
+
+    /**
+     * Get all connected components as separate arrays
+     */
+    getAllComponents(): NodeId[][] {
+        const componentMap = new Map<NodeId, NodeId[]>();
+
+        for (const [node] of this.parent) {
+            const root = this.find(node);
+
+            if (!componentMap.has(root)) {
+                componentMap.set(root, []);
+            }
+
+            const component = componentMap.get(root);
+            if (component) {
+                component.push(node);
+            }
+        }
+
+        return Array.from(componentMap.values());
+    }
+
+    /**
+     * Get the size of the component containing the given element
+     */
+    getComponentSize(element: NodeId): number {
+        return this.getComponent(element).length;
+    }
+
+    /**
+     * Add a new element to the data structure
+     */
+    addElement(element: NodeId): void {
+        if (this.parent.has(element)) {
+            return; // Element already exists
+        }
+
+        this.parent.set(element, element);
+        this.rank.set(element, 0);
+        this.componentCount++;
+    }
+
+    /**
+     * Check if an element exists in the data structure
+     */
+    hasElement(element: NodeId): boolean {
+        return this.parent.has(element);
+    }
+
+    /**
+     * Get the total number of elements
+     */
+    size(): number {
+        return this.parent.size;
+    }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * @graphty/algorithms - Graph algorithms library for browser environments
+ *
+ * A comprehensive TypeScript library implementing fundamental graph algorithms
+ * optimized for browser environments and visualization applications.
+ */
+
+// Core exports
+export {Graph} from "./core/graph.js";
+
+// Type exports
+export type {
+    BellmanFordResult,
+    CentralityOptions,
+    CentralityResult,
+    CommunityResult,
+    ComponentResult,
+    DijkstraOptions,
+    Edge,
+    GirvanNewmanOptions,
+    GraphConfig,
+    LouvainOptions,
+    Node,
+    NodeId,
+    PageRankOptions,
+    ShortestPathResult,
+    TraversalOptions,
+    TraversalResult,
+} from "./types/index.js";
+
+// Algorithm exports
+export * from "./algorithms/index.js";
+
+// Data structure exports
+export * from "./data-structures/index.js";

package/src/types/index.ts

@@ -0,0 +1,95 @@
+/**
+ * Core types for the Graphty Algorithms library
+ */
+
+// Node identifier type
+export type NodeId = string | number;
+
+// Edge representation
+export interface Edge {
+    source: NodeId;
+    target: NodeId;
+    weight?: number;
+    id?: string;
+    data?: Record<string, unknown> | undefined;
+}
+
+// Node representation
+export interface Node {
+    id: NodeId;
+    data?: Record<string, unknown> | undefined;
+}
+
+// Graph configuration
+export interface GraphConfig {
+    directed: boolean;
+    allowSelfLoops: boolean;
+    allowParallelEdges: boolean;
+}
+
+// Algorithm result interfaces
+export interface ShortestPathResult {
+    distance: number;
+    path: NodeId[];
+    predecessor: Map<NodeId, NodeId | null>;
+}
+
+export type CentralityResult = Record<string, number>;
+
+export interface TraversalResult {
+    visited: Set<NodeId>;
+    order: NodeId[];
+    tree?: Map<NodeId, NodeId | null>;
+}
+
+export interface CommunityResult {
+    communities: NodeId[][];
+    modularity: number;
+    iterations?: number;
+}
+
+export interface ComponentResult {
+    components: NodeId[][];
+    componentMap: Map<NodeId, number>;
+}
+
+// Algorithm options interfaces
+export interface TraversalOptions {
+    targetNode?: NodeId;
+    visitCallback?: (node: NodeId, level: number) => void;
+}
+
+export interface DijkstraOptions {
+    target?: NodeId;
+}
+
+export interface BellmanFordResult {
+    distances: Map<NodeId, number>;
+    previous: Map<NodeId, NodeId | null>;
+    hasNegativeCycle: boolean;
+    negativeCycleNodes?: NodeId[];
+}
+
+export interface CentralityOptions {
+    normalized?: boolean;
+    endpoints?: boolean;
+    mode?: "in" | "out" | "total"; // For directed graphs
+}
+
+export interface PageRankOptions {
+    alpha?: number; // Damping factor (default: 0.85)
+    maxIterations?: number; // Maximum iterations (default: 100)
+    tolerance?: number; // Convergence tolerance (default: 1e-6)
+    personalization?: Map<NodeId, number>; // Personalized PageRank
+}
+
+export interface LouvainOptions {
+    resolution?: number; // Resolution parameter (default: 1.0)
+    maxIterations?: number; // Maximum iterations (default: 100)
+    tolerance?: number; // Improvement tolerance (default: 1e-6)
+}
+
+export interface GirvanNewmanOptions {
+    maxCommunities?: number; // Stop when this many communities reached
+    minCommunitySize?: number; // Minimum size for valid community
+}