Add fast-hashring library with consistent hashing implementation and documentation

Author: jkyberneees

README.md

@@ -1 +1,65 @@
-# consistent-hash
+# fast-hashring
+
+fast-hashring is a lightweight JavaScript library offering an efficient implementation of consistent hashing using virtual nodes. Designed for high performance, it provides fast and scalable key distribution, ideal for load balancing, caching, and data sharding in distributed systems.
+
+## Installation
+
+Install via npm:
+
+```bash
+npm install fast-hashring
+```
+
+Or using yarn:
+
+```bash
+yarn add fast-hashring
+```
+
+## Usage
+
+Here’s a basic example of how to integrate fast-hashring into your project:
+
+```js
+import ConsistentHash from 'fast-hashring'
+
+const ch = new ConsistentHash({ virtualNodes: 100 })
+ch.addNode('server1')
+ch.addNode('server2')
+
+const node = ch.getNode('my-key')
+console.log(`Key is assigned to node: ${node}`)
+```
+
+## Features
+
+- **Consistent Hashing with Virtual Nodes:**  
+  Utilizes virtual nodes to distribute keys evenly across real nodes, minimizing load imbalance during node changes.
+
+- **Binary Search for Rapid Lookups:**  
+  Maintains a sorted hash ring of virtual nodes, enabling quick key lookups using an optimized binary search algorithm.
+
+- **High Performance & Scalability:**  
+  The design focuses on speed and efficiency, ensuring low latency and high throughput even with large-scale deployments.
+
+- **Simple & Intuitive API:**  
+  Easy-to-use methods for adding, removing, and retrieving nodes enable quick integration into projects.
+
+- **TypeScript Support:**  
+  Complete TypeScript definitions are provided, offering strong typing and an improved developer experience.
+
+## Why Choose fast-hashring?
+
+fast-hashring delivers superior performance by leveraging virtual nodes and binary search, providing a more balanced and efficient key distribution compared to traditional hashing methods. Whether you're scaling a distributed cache, load balancer, or sharded database, fast-hashring minimizes remapping and disruption, ensuring high availability and smooth performance.
+
+## Testing
+
+The library is tested using Bun's testing framework. To run the tests, execute:
+
+```bash
+bun test
+```
+
+## License
+
+MIT

consistent-hash.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ConsistentHash provides an implementation of consistent hashing using virtual nodes
+ * for improved key distribution. It maintains a ring structure of hashed virtual node values,
+ * mapping them to their corresponding real nodes.
+ *
+ * @module consistent-hash
+ */
+declare class ConsistentHash {
+  /**
+   * Create a new ConsistentHash instance.
+   *
+   * @param options - Configuration options.
+   * @param options.virtualNodes - Number of virtual nodes per real node (default is 100).
+   */
+  constructor(options?: { virtualNodes?: number });
+
+  /**
+   * Add a new node to the hash ring.
+   *
+   * @param node - The node identifier.
+   * @throws Will throw an error if the node is not a non-empty string or already exists.
+   */
+  addNode(node: string): void;
+
+  /**
+   * Remove a node and its associated virtual nodes from the hash ring.
+   *
+   * @param node - The node identifier.
+   * @throws Will throw an error if the node does not exist.
+   */
+  removeNode(node: string): void;
+
+  /**
+   * Get the node responsible for a given key.
+   * Returns null if no nodes are present.
+   *
+   * @param key - The key to look up.
+   * @returns The node responsible for the key, or null if none exists.
+   * @throws Will throw an error if the key is not a non-empty string.
+   */
+  getNode(key: string): string | null;
+
+  /**
+   * Get the number of real nodes in the hash ring.
+   *
+   * @returns The count of real nodes.
+   */
+  size(): number;
+}
+
+export default ConsistentHash;

consistent-hash.js

@@ -0,0 +1,132 @@
+import crypto from 'crypto'
+
+/**
+ * ConsistentHash provides an implementation of consistent hashing using virtual nodes
+ * for improved key distribution. It maintains a ring structure of hashed virtual node values,
+ * mapping them to their corresponding real nodes.
+ *
+ * This module is designed to be published on NPM and used as a standalone library.
+ *
+ * Example usage:
+ *   import ConsistentHash from 'consistent-hash'
+ *   const ch = new ConsistentHash({ virtualNodes: 100 })
+ *   ch.addNode('server1')
+ *   const node = ch.getNode('my-key')
+ *
+ * @module consistent-hash
+ */
+class ConsistentHash {
+  /**
+   * Create a new ConsistentHash instance.
+   *
+   * @param {Object} [options={}] - Configuration options.
+   * @param {number} [options.virtualNodes=100] - Number of virtual nodes per real node.
+   */
+  constructor(options = {}) {
+    this.virtualNodes = options.virtualNodes || 100;
+    this.ring = []; // Sorted array of virtual node hashes.
+    this.nodes = new Set(); // Set of real node identifiers.
+    this.virtualToReal = new Map(); // Maps virtual node hash to real node.
+  }
+
+  /**
+   * Generate an MD5 hash for a given key.
+   *
+   * @private
+   * @param {string} key - The key to hash.
+   * @returns {string} The hexadecimal hash.
+   */
+  _hash(key) {
+    return crypto.createHash('md5').update(key).digest('hex');
+  }
+
+  /**
+   * Add a new node to the hash ring.
+   *
+   * @param {string} node - The node identifier.
+   * @throws {Error} If node is not a non-empty string or already exists.
+   */
+  addNode(node) {
+    if (!node || typeof node !== 'string') {
+      throw new Error('Node must be a non-empty string');
+    }
+    if (this.nodes.has(node)) {
+      throw new Error('Node already exists');
+    }
+    this.nodes.add(node);
+
+    // Create virtual nodes for the real node.
+    for (let i = 0; i < this.virtualNodes; i++) {
+      const virtualNode = `${node}-vn-${i}`;
+      const hash = this._hash(virtualNode);
+      this.ring.push(hash);
+      this.virtualToReal.set(hash, node);
+    }
+    // Keep the ring sorted for efficient binary search.
+    this.ring.sort();
+  }
+
+  /**
+   * Remove a node and its associated virtual nodes from the hash ring.
+   *
+   * @param {string} node - The node identifier.
+   * @throws {Error} If the node does not exist.
+   */
+  removeNode(node) {
+    if (!this.nodes.has(node)) {
+      throw new Error('Node does not exist');
+    }
+    this.nodes.delete(node);
+
+    // Remove all virtual nodes associated with the given node.
+    for (let i = 0; i < this.virtualNodes; i++) {
+      const virtualNode = `${node}-vn-${i}`;
+      const hash = this._hash(virtualNode);
+      this.virtualToReal.delete(hash);
+    }
+    // Rebuild the ring with remaining virtual nodes.
+    this.ring = this.ring.filter((hash) => this.virtualToReal.has(hash));
+  }
+
+  /**
+   * Get the node responsible for a given key.
+   * Returns null if no nodes are present.
+   *
+   * @param {string} key - The key to look up.
+   * @returns {string|null} The node responsible for the key, or null if none exists.
+   * @throws {Error} If the key is not a non-empty string.
+   */
+  getNode(key) {
+    if (!key || typeof key !== 'string') {
+      throw new Error('Key must be a non-empty string');
+    }
+    if (this.ring.length === 0) {
+      return null;
+    }
+    const hash = this._hash(key);
+
+    // Binary search to find the first virtual node hash greater than or equal to the key hash.
+    let low = 0, high = this.ring.length;
+    while (low < high) {
+      const mid = Math.floor((low + high) / 2);
+      if (this.ring[mid] < hash) {
+        low = mid + 1;
+      } else {
+        high = mid;
+      }
+    }
+    const index = low % this.ring.length; // Wrap around if needed.
+    return this.virtualToReal.get(this.ring[index]);
+  }
+
+  /**
+   * Get the number of real nodes in the hash ring.
+   *
+   * @returns {number} The count of real nodes.
+   */
+  size() {
+    return this.nodes.size;
+  }
+}
+
+export default ConsistentHash

consistent-hash.test.js

@@ -0,0 +1,127 @@
+import { test, describe, beforeEach, expect } from 'bun:test'
+import ConsistentHash from './consistent-hash.js'
+
+describe('ConsistentHash', () => {
+  let ch
+
+  beforeEach(() => {
+    ch = new ConsistentHash()
+  })
+
+  describe('Constructor', () => {
+    test('should create instance with default virtual nodes', () => {
+      expect(ch).toBeInstanceOf(ConsistentHash)
+      expect(ch.virtualNodes).toBe(100)
+    })
+
+    test('should accept a custom number of virtual nodes', () => {
+      const customHr = new ConsistentHash({ virtualNodes: 200 })
+      expect(customHr.virtualNodes).toBe(200)
+    })
+  })
+
+  describe('addNode()', () => {
+    test('should add nodes successfully', () => {
+      ch.addNode('server1')
+      ch.addNode('server2')
+      expect(ch.size()).toBe(2)
+    })
+
+    test('should throw error when adding empty node', () => {
+      expect(() => ch.addNode('')).toThrow('Node must be a non-empty string')
+    })
+
+    test('should throw error when adding duplicate node', () => {
+      ch.addNode('server1')
+      expect(() => ch.addNode('server1')).toThrow('Node already exists')
+    })
+
+    test('should allow re-adding a node after it has been removed', () => {
+      ch.addNode('server1')
+      ch.removeNode('server1')
+      expect(ch.size()).toBe(0)
+      // Re-add removed node should succeed.
+      ch.addNode('server1')
+      expect(ch.size()).toBe(1)
+      expect(ch.getNode('someKey')).toBe('server1')
+    })
+  })
+
+  describe('removeNode()', () => {
+    beforeEach(() => {
+      ch.addNode('server1')
+      ch.addNode('server2')
+    })
+
+    test('should remove nodes successfully', () => {
+      ch.removeNode('server1')
+      expect(ch.size()).toBe(1)
+    })
+
+    test('should throw error when removing non-existent node', () => {
+      expect(() => ch.removeNode('server3')).toThrow('Node does not exist')
+    })
+
+    test('should remap keys after node removal', () => {
+      const key = '2348'
+      const originalServer = ch.getNode(key)
+      ch.removeNode(originalServer)
+      const newServer = ch.getNode(key)
+      expect(newServer).not.toBe(originalServer)
+    })
+  })
+
+  describe('getNode()', () => {
+    beforeEach(() => {
+      ch.addNode('server1')
+      ch.addNode('server2')
+    })
+
+    test('should return consistent results for the same key', () => {
+      const key = '12345'
+      const server1 = ch.getNode(key)
+      const server2 = ch.getNode(key)
+      expect(server1).toBe(server2)
+    })
+
+    test('should throw error for empty key', () => {
+      expect(() => ch.getNode('')).toThrow('Key must be a non-empty string')
+    })
+
+    test('should return null when no nodes exist', () => {
+      ch.removeNode('server1')
+      ch.removeNode('server2')
+      expect(ch.getNode('12345')).toBe(null)
+    })
+
+    test('should distribute keys relatively evenly', () => {
+      const testKeys = Array.from({ length: 1000 }, (_, i) => `key${i}`)
+      const distribution = {}
+      testKeys.forEach((key) => {
+        const server = ch.getNode(key)
+        distribution[server] = (distribution[server] || 0) + 1
+      })
+
+      const values = Object.values(distribution)
+      const total = values.reduce((a, b) => a + b, 0)
+      const avg = total / values.length
+      const threshold = avg * 0.2 // 20% tolerance
+
+      for (let count of values) {
+        expect(Math.abs(count - avg)).toBeLessThan(threshold)
+      }
+    })
+  })
+
+  describe('size()', () => {
+    test('should return the correct number of nodes', () => {
+      expect(ch.size()).toBe(0)
+      ch.addNode('server1')
+      expect(ch.size()).toBe(1)
+      ch.addNode('server2')
+      expect(ch.size()).toBe(2)
+      ch.removeNode('server1')
+      expect(ch.size()).toBe(1)
+    })
+  })
+})