@graphty/algorithms 1.3.1 → 1.5.0

package/src/optimized/bit-packed.ts

@@ -1,4 +1,4 @@
-import {TypedFastBitSet} from "typedfastbitset";
+import { TypedFastBitSet } from "typedfastbitset";
 
 /**
  * Wrapper around TypedFastBitSet with graph-specific optimizations
@@ -10,6 +10,10 @@ export class GraphBitSet {
     private bitset: TypedFastBitSet;
     private _cardinality = 0;
 
+    /**
+     * Creates a new GraphBitSet with optional pre-allocated capacity.
+     * @param capacity - The initial capacity to pre-allocate for the bitset
+     */
     constructor(capacity?: number) {
         this.bitset = new TypedFastBitSet();
         if (capacity) {
@@ -19,8 +23,9 @@ export class GraphBitSet {
     }
 
     /**
-   * Add a single element
-   */
+     * Add a single element to the set.
+     * @param index - The element index to add
+     */
     add(index: number): void {
         if (!this.bitset.has(index)) {
             this.bitset.add(index);
@@ -29,8 +34,9 @@ export class GraphBitSet {
     }
 
     /**
-   * Remove a single element
-   */
+     * Remove a single element from the set.
+     * @param index - The element index to remove
+     */
     remove(index: number): void {
         if (this.bitset.has(index)) {
             this.bitset.remove(index);
@@ -39,30 +45,35 @@ export class GraphBitSet {
     }
 
     /**
-   * Check if element exists
-   */
+     * Check if an element exists in the set.
+     * @param index - The element index to check
+     * @returns True if the element exists, false otherwise
+     */
     has(index: number): boolean {
         return this.bitset.has(index);
     }
 
     /**
-   * Clear all elements
-   */
+     * Clear all elements
+     */
     clear(): void {
         this.bitset.clear();
         this._cardinality = 0;
     }
 
     /**
-   * Check if empty
-   */
+     * Check if the set is empty.
+     * @returns True if the set contains no elements, false otherwise
+     */
     isEmpty(): boolean {
         return this._cardinality === 0;
     }
 
     /**
-   * Optimized for graph algorithms - add range of indices
-   */
+     * Optimized for graph algorithms - add a range of indices.
+     * @param start - The starting index (inclusive)
+     * @param end - The ending index (exclusive)
+     */
     addRange(start: number, end: number): void {
         for (let i = start; i < end; i++) {
             if (!this.bitset.has(i)) {
@@ -73,31 +84,35 @@ export class GraphBitSet {
     }
 
     /**
-   * Fast cardinality tracking
-   */
+     * Fast cardinality tracking - get the number of elements in the set.
+     * @returns The number of elements in the set
+     */
     size(): number {
         return this._cardinality;
     }
 
     /**
-   * Batch operations for frontier management - swap contents
-   */
+     * Batch operations for frontier management - swap contents with another GraphBitSet.
+     * @param other - The GraphBitSet to swap contents with
+     */
     swap(other: GraphBitSet): void {
         [this.bitset, other.bitset] = [other.bitset, this.bitset];
         [this._cardinality, other._cardinality] = [other._cardinality, this._cardinality];
     }
 
     /**
-   * Efficient iteration
-   */
+     * Efficient iteration over all elements in the set.
+     * @yields The indices of elements in the set
+     */
     *[Symbol.iterator](): Generator<number> {
-    // Use TypedFastBitSet's optimized iteration
+        // Use TypedFastBitSet's optimized iteration
         yield* this.bitset;
     }
 
     /**
-   * Set operations with cardinality tracking
-   */
+     * Perform union operation with another GraphBitSet, updating this set in place.
+     * @param other - The GraphBitSet to union with
+     */
     union(other: GraphBitSet): void {
         const result = this.bitset.union(other.bitset);
         this.bitset = result;
@@ -106,6 +121,10 @@ export class GraphBitSet {
         this._cardinality = size;
     }
 
+    /**
+     * Perform intersection operation with another GraphBitSet, updating this set in place.
+     * @param other - The GraphBitSet to intersect with
+     */
     intersection(other: GraphBitSet): void {
         const result = this.bitset.intersection(other.bitset);
         this.bitset = result;
@@ -114,6 +133,10 @@ export class GraphBitSet {
         this._cardinality = size;
     }
 
+    /**
+     * Perform difference operation with another GraphBitSet, updating this set in place.
+     * @param other - The GraphBitSet to subtract from this set
+     */
     difference(other: GraphBitSet): void {
         const result = this.bitset.difference(other.bitset);
         this.bitset = result;
@@ -123,8 +146,9 @@ export class GraphBitSet {
     }
 
     /**
-   * Clone the bitset
-   */
+     * Clone the bitset.
+     * @returns A new GraphBitSet with the same elements
+     */
     clone(): GraphBitSet {
         const cloned = new GraphBitSet();
         cloned.bitset = this.bitset.clone();
@@ -145,6 +169,10 @@ export class VisitedBitArray {
     private wordCount: number;
     private _size: number;
 
+    /**
+     * Creates a new VisitedBitArray with the specified size.
+     * @param size - The number of bits to allocate
+     */
     constructor(size: number) {
         this._size = size;
         this.wordCount = Math.ceil(size / 32);
@@ -152,8 +180,9 @@ export class VisitedBitArray {
     }
 
     /**
-   * Set bit at index
-   */
+     * Set bit at the specified index.
+     * @param index - The bit index to set
+     */
     set(index: number): void {
         if (index < 0 || index >= this._size) {
             throw new Error(`Index ${String(index)} out of bounds [0, ${String(this._size)})`);
@@ -168,8 +197,10 @@ export class VisitedBitArray {
     }
 
     /**
-   * Get bit at index
-   */
+     * Get bit value at the specified index.
+     * @param index - The bit index to get
+     * @returns True if the bit is set, false otherwise
+     */
     get(index: number): boolean {
         if (index < 0 || index >= this._size) {
             return false;
@@ -182,15 +213,16 @@ export class VisitedBitArray {
     }
 
     /**
-   * Clear all bits
-   */
+     * Clear all bits
+     */
     clear(): void {
         this.words.fill(0);
     }
 
     /**
-   * Toggle bit at index
-   */
+     * Toggle bit at the specified index.
+     * @param index - The bit index to toggle
+     */
     toggle(index: number): void {
         if (index < 0 || index >= this._size) {
             throw new Error(`Index ${String(index)} out of bounds [0, ${String(this._size)})`);
@@ -205,8 +237,9 @@ export class VisitedBitArray {
     }
 
     /**
-   * Population count for statistics
-   */
+     * Population count for statistics - count the number of set bits.
+     * @returns The number of bits set to 1
+     */
     popcount(): number {
         let count = 0;
         for (let i = 0; i < this.wordCount; i++) {
@@ -219,26 +252,30 @@ export class VisitedBitArray {
     }
 
     /**
-   * Efficient population count for a single word
-   * Uses bit manipulation tricks for fast counting
-   */
+     * Efficient population count for a single word.
+     * Uses bit manipulation tricks for fast counting.
+     * @param n - The 32-bit word to count
+     * @returns The number of bits set to 1 in the word
+     */
     private popcountWord(n: number): number {
         let x = n;
         x = x - ((x >>> 1) & 0x55555555);
         x = (x & 0x33333333) + ((x >>> 2) & 0x33333333);
-        return (((x + (x >>> 4)) & 0xF0F0F0F) * 0x1010101) >>> 24;
+        return (((x + (x >>> 4)) & 0xf0f0f0f) * 0x1010101) >>> 24;
     }
 
     /**
-   * Get size of the bit array
-   */
+     * Get size of the bit array.
+     * @returns The total number of bits in the array
+     */
     size(): number {
         return this._size;
     }
 
     /**
-   * Check if all bits are zero
-   */
+     * Check if all bits are zero.
+     * @returns True if no bits are set, false otherwise
+     */
     isEmpty(): boolean {
         for (let i = 0; i < this.wordCount; i++) {
             if (this.words[i] !== 0) {
@@ -249,8 +286,9 @@ export class VisitedBitArray {
     }
 
     /**
-   * Set multiple bits from array
-   */
+     * Set multiple bits from an array of indices.
+     * @param indices - Array of bit indices to set
+     */
     setMultiple(indices: number[]): void {
         for (const index of indices) {
             this.set(index);
@@ -258,8 +296,9 @@ export class VisitedBitArray {
     }
 
     /**
-   * Get indices of all set bits
-   */
+     * Get indices of all set bits.
+     * @returns Array containing the indices of all bits that are set to 1
+     */
     getSetIndices(): number[] {
         const indices: number[] = [];
         for (let wordIndex = 0; wordIndex < this.wordCount; wordIndex++) {
@@ -292,6 +331,10 @@ export class CompactDistanceArray {
     private _size: number;
     private static readonly INFINITY = 65535;
 
+    /**
+     * Creates a new CompactDistanceArray with the specified size.
+     * @param size - The number of distance values to store
+     */
     constructor(size: number) {
         this._size = size;
         this.data = new Uint16Array(size);
@@ -299,8 +342,10 @@ export class CompactDistanceArray {
     }
 
     /**
-   * Set distance at index
-   */
+     * Set distance at the specified index.
+     * @param index - The node index to set the distance for
+     * @param distance - The distance value to set
+     */
     set(index: number, distance: number): void {
         if (distance >= CompactDistanceArray.INFINITY) {
             throw new Error(`Distance exceeds maximum value (${String(CompactDistanceArray.INFINITY - 1)})`);
@@ -310,30 +355,35 @@ export class CompactDistanceArray {
     }
 
     /**
-   * Get distance at index
-   */
+     * Get distance at the specified index.
+     * @param index - The node index to get the distance for
+     * @returns The distance value, or INFINITY if not set
+     */
     get(index: number): number {
         const value = this.data[index];
         return value ?? CompactDistanceArray.INFINITY; // Default to unvisited
     }
 
     /**
-   * Check if node has been visited
-   */
+     * Check if a node has been visited (has a valid distance).
+     * @param index - The node index to check
+     * @returns True if the node has been visited, false otherwise
+     */
     isVisited(index: number): boolean {
         return this.data[index] !== CompactDistanceArray.INFINITY;
     }
 
     /**
-   * Reset all distances
-   */
+     * Reset all distances to unvisited state.
+     */
     clear(): void {
         this.data.fill(CompactDistanceArray.INFINITY);
     }
 
     /**
-   * Get size
-   */
+     * Get the size of the distance array.
+     * @returns The number of elements in the array
+     */
     size(): number {
         return this._size;
     }

package/src/optimized/csr-graph.ts

@@ -1,4 +1,4 @@
-import type {NodeId} from "../types/index.js";
+import type { NodeId } from "../types/index.js";
 
 /**
  * Interface for read-only graph operations
@@ -44,19 +44,29 @@ interface CSRGraphData<TNodeId> {
 export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     private data: CSRGraphData<TNodeId>;
 
+    /**
+     * Creates a new CSRGraph from an adjacency list representation.
+     * @param adjacencyList - Map of node IDs to arrays of neighbor node IDs
+     * @param weights - Optional map of edge weights keyed by "source-target" strings
+     * @param buildReverse - Whether to build reverse edges for bottom-up BFS (default true)
+     */
     constructor(adjacencyList: Map<TNodeId, TNodeId[]>, weights?: Map<string, number>, buildReverse = true) {
         this.data = this.buildCSR(adjacencyList, weights, buildReverse);
     }
 
     /**
-   * Build CSR structure from adjacency list
-   */
+     * Build CSR structure from adjacency list.
+     * @param adjacencyList - Map of node IDs to arrays of neighbor node IDs
+     * @param weights - Optional map of edge weights keyed by "source-target" strings
+     * @param buildReverse - Whether to build reverse edges for bottom-up BFS
+     * @returns The constructed CSR graph data structure
+     */
     private buildCSR(
         adjacencyList: Map<TNodeId, TNodeId[]>,
         weights?: Map<string, number>,
         buildReverse = true,
     ): CSRGraphData<TNodeId> {
-    // Collect all unique nodes (both sources and targets)
+        // Collect all unique nodes (both sources and targets)
         const allNodes = new Set<TNodeId>();
         for (const [source, neighbors] of adjacencyList) {
             allNodes.add(source);
@@ -115,7 +125,7 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
                         throw new Error(`Node ${String(n)} not found in nodeIdToIndex map`);
                     }
 
-                    return {id: n, index};
+                    return { id: n, index };
                 })
                 .sort((a, b) => a.index - b.index);
 
@@ -193,18 +203,37 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     // Core API methods
+    /**
+     * Get the total number of nodes in the graph.
+     * @returns The number of nodes
+     */
     nodeCount(): number {
         return this.data.indexToNodeId.length;
     }
 
+    /**
+     * Get the total number of edges in the graph.
+     * @returns The number of edges
+     */
     edgeCount(): number {
         return this.data.columnIndices.length;
     }
 
+    /**
+     * Check if a node exists in the graph.
+     * @param nodeId - The node ID to check
+     * @returns True if the node exists, false otherwise
+     */
     hasNode(nodeId: TNodeId): boolean {
         return this.data.nodeIdToIndex.has(nodeId);
     }
 
+    /**
+     * Check if an edge exists between two nodes.
+     * @param source - The source node ID
+     * @param target - The target node ID
+     * @returns True if the edge exists, false otherwise
+     */
     hasEdge(source: TNodeId, target: TNodeId): boolean {
         const sourceIndex = this.data.nodeIdToIndex.get(source);
         const targetIndex = this.data.nodeIdToIndex.get(target);
@@ -225,8 +254,10 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     /**
-   * Get neighbors as node IDs
-   */
+     * Get neighbors of a node as node IDs.
+     * @param nodeId - The node ID to get neighbors for
+     * @returns An iterator over neighbor node IDs
+     */
     neighbors(nodeId: TNodeId): IterableIterator<TNodeId> {
         const nodeIndex = this.data.nodeIdToIndex.get(nodeId);
         if (nodeIndex === undefined) {
@@ -236,7 +267,7 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
         const start = this.data.rowPointers[nodeIndex];
         const end = this.data.rowPointers[nodeIndex + 1];
 
-        const {columnIndices, indexToNodeId} = this.data;
+        const { columnIndices, indexToNodeId } = this.data;
         function* generateNeighbors(): Generator<TNodeId> {
             if (start !== undefined && end !== undefined) {
                 for (let i = start; i < end; i++) {
@@ -255,15 +286,18 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     /**
-   * Get all nodes
-   */
+     * Get all nodes in the graph.
+     * @returns An iterator over all node IDs
+     */
     nodes(): IterableIterator<TNodeId> {
         return this.data.indexToNodeId.values();
     }
 
     /**
-   * Get neighbors as indices (internal use)
-   */
+     * Get neighbors as indices (internal use).
+     * @param nodeIndex - The internal index of the node
+     * @returns Array of neighbor indices
+     */
     getNeighborIndices(nodeIndex: number): number[] {
         if (nodeIndex < 0 || nodeIndex >= this.data.indexToNodeId.length) {
             return [];
@@ -278,6 +312,11 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
         return Array.from(this.data.columnIndices.subarray(start, end));
     }
 
+    /**
+     * Get the out-degree (number of outgoing edges) of a node.
+     * @param nodeId - The node ID to get the out-degree for
+     * @returns The number of outgoing edges from the node
+     */
     outDegree(nodeId: TNodeId): number {
         const nodeIndex = this.data.nodeIdToIndex.get(nodeId);
         if (nodeIndex === undefined) {
@@ -288,8 +327,10 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     /**
-   * Get out-degree by index (internal use)
-   */
+     * Get out-degree by index (internal use).
+     * @param nodeIndex - The internal index of the node
+     * @returns The number of outgoing edges from the node
+     */
     outDegreeByIndex(nodeIndex: number): number {
         const start = this.data.rowPointers[nodeIndex];
         const end = this.data.rowPointers[nodeIndex + 1];
@@ -301,8 +342,10 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     /**
-   * Iterator support for neighbor indices
-   */
+     * Iterator support for neighbor indices.
+     * @param nodeIndex - The internal index of the node
+     * @yields The indices of neighboring nodes
+     */
     *iterateNeighborIndices(nodeIndex: number): Generator<number> {
         const start = this.data.rowPointers[nodeIndex];
         const end = this.data.rowPointers[nodeIndex + 1];
@@ -318,8 +361,10 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     /**
-   * Iterator support for incoming neighbor indices (for bottom-up BFS)
-   */
+     * Iterator support for incoming neighbor indices (for bottom-up BFS).
+     * @param nodeIndex - The internal index of the node
+     * @yields The indices of nodes with edges pointing to this node
+     */
     *iterateIncomingNeighborIndices(nodeIndex: number): Generator<number> {
         if (!this.data.reverseRowPointers || !this.data.reverseColumnIndices) {
             return;
@@ -339,8 +384,10 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     /**
-   * Convert node ID to index
-   */
+     * Convert node ID to internal index.
+     * @param nodeId - The node ID to convert
+     * @returns The internal index for the node
+     */
     nodeToIndex(nodeId: TNodeId): number {
         const index = this.data.nodeIdToIndex.get(nodeId);
         if (index === undefined) {
@@ -351,8 +398,10 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     /**
-   * Convert index to node ID
-   */
+     * Convert internal index to node ID.
+     * @param index - The internal index to convert
+     * @returns The node ID for the given index
+     */
     indexToNodeId(index: number): TNodeId {
         const nodeId = this.data.indexToNodeId[index];
         if (nodeId === undefined) {
@@ -363,8 +412,11 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     /**
-   * Get edge weight
-   */
+     * Get edge weight between two nodes.
+     * @param source - The source node ID
+     * @param target - The target node ID
+     * @returns The edge weight, or undefined if the edge doesn't exist or has no weight
+     */
     getEdgeWeight(source: TNodeId, target: TNodeId): number | undefined {
         if (!this.data.edgeWeights) {
             return undefined;
@@ -393,8 +445,13 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     /**
-   * Binary search for target in sorted array
-   */
+     * Binary search for target in sorted array.
+     * @param arr - The typed array to search in
+     * @param target - The value to search for
+     * @param start - The starting index (inclusive)
+     * @param end - The ending index (exclusive)
+     * @returns The index of the target, or -1 if not found
+     */
     private binarySearch(arr: Uint32Array, target: number, start: number, end: number): number {
         let left = start;
         let right = end - 1;
@@ -422,13 +479,19 @@ export class CSRGraph<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     /**
-   * Create CSR graph from standard Graph
-   */
+     * Create CSR graph from standard Graph interface.
+     * @param graph - The graph object to convert, must implement nodes, neighbors, hasNode, and optionally getEdge
+     * @param graph.nodes - Function that returns an iterator over node objects with id property
+     * @param graph.neighbors - Function that returns an iterator over neighbor node IDs
+     * @param graph.hasNode - Function that checks if a node exists in the graph
+     * @param graph.getEdge - Optional function that returns edge data including weight
+     * @returns A new CSRGraph instance
+     */
     static fromGraph<TNodeId = NodeId>(graph: {
-        nodes(): IterableIterator<{id: TNodeId}>;
+        nodes(): IterableIterator<{ id: TNodeId }>;
         neighbors(nodeId: TNodeId): IterableIterator<TNodeId>;
         hasNode(nodeId: TNodeId): boolean;
-        getEdge?(source: TNodeId, target: TNodeId): {weight?: number} | undefined;
+        getEdge?(source: TNodeId, target: TNodeId): { weight?: number } | undefined;
     }): CSRGraph<TNodeId> {
         const adjacencyList = new Map<TNodeId, TNodeId[]>();
         const weights = new Map<string, number>();