Skip to content

Releases: 1mb-dev/hash-orbit

v1.0.0 - Production Release

20 Nov 18:45
@vnykmshr vnykmshr
v1.0.0
f4ed8b3

Choose a tag to compare

View all tags
v1.0.0 - Production Release Latest
Latest

hash-orbit v1.0.0

Production-ready consistent hashing implementation for distributed systems.

Highlights

  • Fast & Lightweight: O(log n) lookups, <500ms test suite, 100% coverage
  • TypeScript-First: Full type safety with strict mode
  • Pure Algorithm: Zero infrastructure opinions, compose with any library
  • Battle-Tested: 42 comprehensive tests covering all edge cases

Core Features

  • Consistent hashing ring with virtual nodes (configurable replicas)
  • Minimal key redistribution (~1/N) when cluster changes
  • Binary search optimization for fast lookups
  • Replication support via getN() method
  • State serialization with toJSON() / fromJSON()
  • Input validation and edge case handling

Use Cases

  • Cache sharding (Redis, Memcached)
  • Database partitioning
  • Load balancing with sticky sessions
  • Distributed storage replication

What's New in v1.0.0

Added

  • Consistent hashing ring implementation with virtual nodes
  • add(), remove(), get(), getN() methods
  • size and nodes getters for introspection
  • toJSON() and fromJSON() for serialization
  • TypeScript support with full type definitions
  • 100% test coverage (42 tests, <500ms)
  • Comprehensive documentation and working examples
  • Production-ready codebase with minimal dependencies

Changed

  • Optimized test suite (99% faster, removed bloat)
  • Streamlined README (52% shorter, more practical)
  • Deduplicated code and removed redundant comments
  • Improved code maintainability and consistency

Removed

  • Codecov integration (coverage verified locally via vitest)

Installation

```bash
npm install hash-orbit
```

Quick Start

```typescript
import { HashOrbit } from 'hash-orbit';

const ring = new HashOrbit({ replicas: 150 });

ring.add('cache-1');
ring.add('cache-2');
ring.add('cache-3');

const node = ring.get('user:123'); // Deterministic routing
const replicas = ring.getN('user:123', 2); // Replication
```

Documentation

Performance

  • add/remove: O(r × log(r×n)) (~9ms for 3 nodes, 150 replicas)
  • get: O(log(r×n)) (<1μs)
  • getN: O(r×n) worst case, typically much faster
  • Memory: ~64 bytes per virtual node position

Full Changelog: https://github.com/vnykmshr/hash-orbit/blob/main/CHANGELOG.md

Assets 2
Loading