v2.5.0 - API Completeness + Complete Dijkstra Examples

What's New

v2.5.0 delivers API completeness across all five languages with Dijkstra examples in each.

Complete Dijkstra Examples (5 Languages)

Same algorithm, same graph, five languages—validates API parity:

• TypeScript: examples/dijkstra/TypeScript/
• Go: examples/dijkstra/Go/
• Rust: examples/dijkstra/Rust/
• Zig: examples/dijkstra/Zig/
• C++: examples/dijkstra/Cpp/ (graph embedded; no standard JSON support)

API Completeness

All five implementations now have identical core APIs:

Feature	C++	Go	Rust	Zig	TypeScript
updatePriority()	✅	✅	✅	✅	✅
getPosition()	✅	✅	✅	✅	✅
*ByIndex methods	✅	✅	✅	✅	✅
Bulk operations	✅	✅	✅	✅	✅
toArray()	✅	✅	✅	✅	✅

Language-Specific Enhancements

• C++: C++23 std::expected<T, Error>, safe variants (try_*), factory functions
• Rust: Result<T, Error>, Display trait, comprehensive doctests
• Go: Idiomatic error handling, Position type alias, fmt.Stringer
• Zig: Error unions, snake_case aliases, fixed decreasePriority() semantics
• TypeScript: Fixed decreasePriority() to match instrumentation

Test Coverage

• C++: 61 tests
• Rust: 97 tests
• Go: 57 tests
• Zig: 54 tests
• TypeScript: 57 tests

Fixed

• Zig/TypeScript decreasePriority() Semantics: Now correctly only moves down

---

Full Changelog: https://github.com/PCfVW/d-Heap-priority-queue/blob/master/CHANGELOG.md

v2.4.0 — Interactive React Flow Demo

Highlights

🎨 Interactive Visualization — Live React Flow demo showing d-ary heap behavior during Dijkstra's algorithm. Toggle arity (d=2, d=4, d=8), use Race Mode to compare all three simultaneously, and step through with timeline controls.

👉 Try it live: https://PCfVW.github.io/Priority-Queues/

📊 TypeScript Instrumentation — Opt-in comparison counting with instrumentComparator() for performance analysis. Zero overhead when disabled.

⚡ Zig Bulk Operations — New insertMany() with Floyd's O(n) heapify, popMany(), and toArray() methods.

What's New

Added

• Interactive React Flow demo with dual-panel layout (heap tree + graph)
• Real-time vertex state coloring (unvisited/in-queue/processed)
• Race Mode for comparing arities simultaneously
• TypeScript instrumentComparator() for tracking comparisons per operation
• Theoretical complexity functions (theoreticalInsertComparisons, etc.)
• GitHub Actions workflow for automatic demo deployment
• Zig: insertMany(), popMany(), toArray() with snake_case aliases
• Go: Increase_priority_by_index() alias

Changed

• Zig: pop() signature changed from ?T to !?T for proper error propagation
• Zig: swapItems() now propagates errors instead of silently ignoring failures
• Go: Internal methods now use Position type alias consistently

Installation

See INSTALL.md for language-specific instructions.

Language	Install
TypeScript	npm install d-ary-heap@2.4.0
Go	go get github.com/PCfVW/d-Heap-priority-queue/Go/src@go/v2.4.0
Rust	d-ary-heap = "2.4.0"
Zig	See build.zig.zon in release
C++	Header-only, copy PriorityQueue.h

Full Changelog: https://github.com/PCfVW/d-Heap-priority-queue/blob/master/CHANGELOG.md#240---2026-01-07

v2.3.0 — Go Implementation

What's New

Go joins C++, Rust, Zig, and TypeScript as the 5th language implementation of the d-ary heap priority queue.

Go Implementation

• Full API parity with existing implementations
• Go generics: PriorityQueue[T any, K comparable] with Comparator and KeyExtractor
• O(1) item lookup via internal map for efficient priority updates
• Dijkstra example in examples/dijkstra/Go/ demonstrating real-world usage
• Cross-language aliases: Is_empty(), To_string() for consistency with other implementations

Installation

go get github.com/PCfVW/d-Heap-priority-queue/Go/src@v2.3.0

Quick Start

import dheap "github.com/PCfVW/d-Heap-priority-queue/Go/src"

pq := dheap.New(dheap.Options[Task, string]{
    D:            4,
    Comparator:   dheap.MinBy(func(t Task) int { return t.Priority }),
    KeyExtractor: func(t Task) string { return t.ID },
})

pq.Insert(Task{ID: "task1", Priority: 10})
top, _ := pq.Front()  // Highest priority item

Documentation Updates

• Updated all READMEs to v2.3.0
• Added Go to INSTALL.md with examples
• Updated cross-language method compatibility tables
• Updated version compatibility matrix
• Full Changelog: v2.2.0...v2.3.0

v2.2.0 - Examples Infrastructure + TypeScript Dijkstra

🚀 v2.2.0 - Examples Infrastructure + TypeScript Dijkstra

This release introduces examples infrastructure with a complete TypeScript implementation of Dijkstra's shortest path algorithm, demonstrating the performance advantages of d-ary heaps in real-world algorithms.

🎯 What's New

✅ Examples Infrastructure

• Complete examples/dijkstra/ directory structure with Network Flows textbook example
• Shared test graph in JSON format from Ahuja, Magnanti, Orlin Network Flows Figure 4.7
• Benchmarks scaffold for future cross-language performance testing (v2.4.0)

✅ TypeScript Dijkstra Implementation

• Complete working example with path reconstruction and performance timing
• Performance comparisons demonstrating d-ary heap advantages (d=2 vs d=4 vs d=8)
• Real algorithm validation showing 4-ary heaps ~4x faster than binary heaps
• Path visualization showing optimal route: A → C → E → F (cost = 9)

✅ Enhanced Documentation

• Algorithm explanation with complexity analysis and theoretical background
• Visual graph representation using Mermaid diagrams with red edge weights
• Cross-language foundation establishing patterns for future implementations

📊 Performance Results

The TypeScript Dijkstra example demonstrates measurable performance improvements:

• Binary heap (d=2): 0.355ms baseline
• 4-ary heap (d=4): 0.086ms (~4x faster)
• 8-ary heap (d=8): 0.045ms (~8x faster)

🔄 Version Updates

All implementations synchronized to v2.2.0:

• C++: Updated header comments and version
• Rust: Updated Cargo.toml and documentation
• Zig: Updated README and version references
• TypeScript: Updated package.json and source files

🛣️ Roadmap Progress

This release completes v2.2.0 milestone from the ROADMAP.md:

• ✅ Examples infrastructure established
• ✅ TypeScript Dijkstra implementation complete
• 🔄 Next: v2.3.0 Go implementation
• 🔄 Future: v2.4.0 Complete Dijkstra examples (all 5 languages)

📚 Getting Started

New users: Check out the Dijkstra Algorithm Example to see d-ary heaps in action!

Existing users: All core APIs remain unchanged - this is a pure addition release.

🔗 Links

• Examples: examples/dijkstra/
• TypeScript Implementation: examples/dijkstra/TypeScript/
• Project Roadmap: ROADMAP.md
• Full Changelog: CHANGELOG.md

---

Full Changelog: v2.1.2...v2.2.0

v2.1.2: Documentation & Cross-Language Compatibility

🚀 What's New in v2.1.2

📚 Documentation Overhaul

• Fixed misleading unified API claims - Now accurately documents per-language method names
• Added comprehensive error handling guide - Best practices for C++, Rust, Zig, and TypeScript
• Return type clarity - Safety recommendations and type differences across languages

🌐 Cross-Language Compatibility

• Zig to_string() alias - Added snake_case compatibility with C++/Rust
• Enhanced TypeScript aliases - Complete snake_case compatibility methods
• Updated installation guide - TypeScript npm instructions and cross-language notes

✅ Quality Improvements

• API audit resolution - All critical documentation issues resolved
• TypeScript npm publication - Available as d-ary-heap@2.1.2
• Backward compatibility - No breaking changes across all implementations

📦 Installation

Zig (Updated)

// In build.zig.zon
.d_heap = .{
    .url = "https://github.com/PCfVW/d-Heap-priority-queue/archive/refs/tags/v2.1.2.tar.gz",
    .hash = "...", // Zig will provide the correct hash
},

d-Heap Priority Queue v2.0.0 - Zig 0.15.2 Support

d-Heap Priority Queue v2.0.0 - Zig 0.15.2 Support

🚀 Major Release: Complete Zig 0.15.2 compatibility with generic implementation and comprehensive testing.

🎯 What's New

✨ Zig 0.15.2 Support

• Full compatibility with latest Zig version
• Updated ArrayList, HashMap, and build system APIs
• New format function signature support

🔧 Generic Implementation

• Truly generic: Use your own item types in Zig
• Type-safe with HashContext(T) and Comparator(T)
• Backward compatible with built-in Item type via DHeapItem

🧪 Comprehensive Testing

• 20+ tests covering all functionality
• Edge cases, error conditions, and heap property maintenance
• Passes in Debug, ReleaseSafe, and ReleaseFast modes

📦 Module Export

• Can be used as a dependency in other Zig projects
• Proper build.zig.zon integration
• Clean module interface with d-heap import

➕ New Features

• peek() alias for front() method
• initCapacity() for pre-allocation
• Better error handling (no unreachable in user paths)

🔄 API Consistency

All three implementations (C++, Rust, Zig) now have identical APIs:

Operation	C++	Rust	Zig
Create	PriorityQueue(d)	PriorityQueue::new(d, cmp)	DHeapItem.init(d, cmp, alloc)
Insert	insert(item)	insert(item)	insert(item)
Front	front()	front()	front() / peek()
Pop	pop()	pop()	pop()
Contains	contains(item)	contains(&item)	contains(item)
Size	len()	len()	len()
Empty	is_empty()	is_empty()	isEmpty()

📚 Quick Start

Built-in Item Type

const d_heap = @import("d-heap");
const DHeapItem = d_heap.DHeapItem;
const MinByCost = d_heap.MinByCost;
const Item = d_heap.Item;

var heap = try DHeapItem.init(3, MinByCost, allocator);
defer heap.deinit();

try heap.insert(Item.init(1, 10));
try heap.insert(Item.init(2, 5));

while (heap.pop()) |item| {
    std.debug.print("Popped: {f}\n", .{item});
}

Custom Item Types

const Task = struct {
    id: u64,
    priority: i32,
    
    pub fn hash(self: Task) u64 { /* ... */ }
    pub fn eql(a: Task, b: Task) bool { /* ... */ }
};

const TaskHeap = d_heap.DHeap(Task, d_heap.HashContext(Task), d_heap.Comparator(Task));

🛠 Installation

Add to your build.zig.zon:

.dependencies = .{
    .d_heap = .{
        .url = "https://github.com/your-username/priority-queues/archive/refs/tags/v2.0.0.tar.gz",
        .hash = "...", // Zig will calculate this
    },
},

See INSTALL.md for complete installation instructions.

🔄 Migration from v1.x

• Zig users: Update to Zig 0.15.2, use DHeapItem for built-in types
• Custom types: Use new generic API with DHeap(T, Context, Comparator)
• API: All method names remain the same (camelCase in Zig)

🏆 Competitive Advantage

This is the first professional-grade, generic, well-tested d-ary heap implementation in Zig with:

• ✅ O(1) item lookup via HashMap
• ✅ Configurable arity (d-ary heap)
• ✅ Min/max heap support
• ✅ Cross-language API parity
• ✅ Comprehensive documentation
• ✅ 20+ unit tests

📊 Performance

• O(1): front(), peek(), contains(), len(), isEmpty(), d()
• O(log_d n): insert(), increasePriority()
• O(d·log_d n): pop(), decreasePriority()

🔗 Links

• Documentation: See language-specific README files
• Examples: Check src/main.zig for usage patterns
• Tests: Run zig build test to see all functionality
• Issues: Report bugs or feature requests on GitHub

---

Full Changelog: v1.1.0...v2.0.0