Rewrite with doubly-linked list for O(1) operations

Architecture changes:
- Replace slice-based implementation with map + doubly-linked list
- All operations now O(1) (except At and Range which are O(n))
- Delete: O(n) → O(1)
- PopFront: O(n) → O(1)
- MoveToEnd: O(n) → O(1)

Testing improvements:
- Add comprehensive race tests for GetOrSet with long mk()
- Add fuzz tests for random operation sequences
- Add property tests for order preservation and list integrity
- Add reentrancy tests for Range vs RangeLocked
- Add big-N tests (10k entries) with allocation tracking
- Add benchmarks for all operations with concurrency patterns
- Maintain 100% test coverage

Documentation:
- Rewrite README from scratch for v1.0
- Document O(1) complexity for all operations
- Add clear warnings for RangeLocked deadlock potential
- Add clear warnings for GetOrSet holding write lock
- Add LRU cache example showcasing O(1) MoveToEnd

CI fixes:
- Update Go versions to 1.22, 1.23, 1.24
- Update golangci-lint to v2 (from v1)
- Update golangci-lint-action to v8 (from v4)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: ndbroadbent

.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go-version: ['1.21', '1.22', '1.23']
+        go-version: ['1.22', '1.23', '1.24']
 
     steps:
     - name: Checkout code
@@ -56,9 +56,9 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v5
       with:
-        go-version: '1.23'
+        go-version: '1.24'
 
     - name: Run golangci-lint
-      uses: golangci/golangci-lint-action@v4
+      uses: golangci/golangci-lint-action@v8
       with:
-        version: latest
+        version: v2

README.md

@@ -1,6 +1,6 @@
 # orderedmap
 
-A thread-safe, generic ordered map for Go that maintains insertion order while providing O(1) lookups.
+A thread-safe, generic ordered map for Go that maintains insertion order while providing O(1) operations for lookups, deletes, and moves.
 
 [![Go Reference](https://pkg.go.dev/badge/github.com/DocSpring/orderedmap.svg)](https://pkg.go.dev/github.com/DocSpring/orderedmap)
 [![Go Report Card](https://goreportcard.com/badge/github.com/DocSpring/orderedmap)](https://goreportcard.com/report/github.com/DocSpring/orderedmap)
@@ -10,7 +10,7 @@ A thread-safe, generic ordered map for Go that maintains insertion order while p
 ## Features
 
 - **Insertion order preservation** - Iterates in the order items were added (unlike Go's built-in maps)
-- **O(1) lookups** - Fast key-based access using internal index
+- **O(1) operations** - Fast lookups, deletes, and moves using map + doubly-linked list
 - **Thread-safe** - All operations use internal locking (RWMutex)
 - **Zero-value usable** - No constructor required: `var om OrderedMap[K,V]` just works
 - **Generic** - Works with any comparable key type and any value type
@@ -68,6 +68,16 @@ Go's built-in `map[K]V` has **random iteration order** by design. This causes pr
 - **FIFO/insertion-order semantics** - Process items in the order they were added
 - **Deterministic testing** - Avoid flaky tests from random map iteration
 
+## Implementation
+
+OrderedMap uses a **map + doubly-linked list** hybrid approach:
+
+- **map[K]*node** - O(1) lookups by key
+- **Doubly-linked list** - O(1) deletes and moves, preserves insertion order
+- **Cached length** - O(1) len() operation
+
+This combination provides optimal performance for all operations except indexed access (At), which is O(n).
+
 ## API
 
 ### Creating
@@ -92,7 +102,7 @@ val, ok := om.Get("key")
 // Has - Check existence (O(1))
 if om.Has("key") { ... }
 
-// Delete - Remove entry (O(n) - see notes)
+// Delete - Remove entry (O(1))
 deleted := om.Delete("key")
 
 // Len - Get size (O(1))
@@ -116,16 +126,54 @@ om.RangeBreak(func(key string, value int) bool {
 
 **Important:** Range and RangeBreak take a **snapshot** before iterating, so the callback can safely modify the map without causing deadlocks.
 
+### Zero-Allocation Iteration
+
+```go
+// RangeLocked - Iterate without allocating a snapshot
+om.RangeLocked(func(key string, value int) {
+    // Process items
+})
+```
+
+**⚠️ WARNING:** The callback in `RangeLocked` **MUST NOT** call any OrderedMap methods or deadlock will occur. Use `Range()` if you need to modify the map during iteration.
+
 ### Access First/Last
 
 ```go
-// Front - Get first entry
+// Front - Get first entry (O(1))
 key, val, ok := om.Front()
 
-// Back - Get last entry
+// Back - Get last entry (O(1))
 key, val, ok := om.Back()
+
+// At - Get entry at index (O(n))
+key, val, ok := om.At(5)
 ```
 
+### Queue Operations
+
+```go
+// PopFront - Remove and return first entry (O(1))
+key, val, ok := om.PopFront()
+
+// PopBack - Remove and return last entry (O(1))
+key, val, ok := om.PopBack()
+
+// MoveToEnd - Move key to end of order (O(1))
+moved := om.MoveToEnd("key")
+```
+
+### Cache Patterns
+
+```go
+// GetOrSet - Atomic get-or-create (O(1))
+val, existed := om.GetOrSet("key", func() int {
+    return expensiveComputation()
+})
+```
+
+**⚠️ WARNING:** The `mk` function in `GetOrSet` is called **while holding the write lock**. Keep it fast and simple to avoid blocking other operations.
+
 ### Bulk Operations
 
 ```go
@@ -146,23 +194,26 @@ om.Reset()
 
 | Operation | Complexity | Notes |
 |-----------|-----------|-------|
-| Set | O(1) | Amortized due to slice growth |
-| Get | O(1) | Hash map lookup |
-| Has | O(1) | Hash map lookup |
-| Delete | **O(n)** | Must shift elements and reindex |
-| Len | O(1) | Cached length |
-| Range | O(n) | Snapshot + iteration |
-| Keys/Values | O(n) | Returns defensive copy |
-| Front/Back | O(1) | Direct slice access |
-
-**Delete is O(n)** because it preserves insertion order by shifting elements. If you need frequent deletes with high performance, consider using tombstones + periodic compaction instead.
+| Set | **O(1)** | Amortized due to map growth |
+| Get | **O(1)** | Hash map lookup |
+| Has | **O(1)** | Hash map lookup |
+| Delete | **O(1)** | Doubly-linked list removal |
+| PopFront | **O(1)** | Remove head of list |
+| PopBack | **O(1)** | Remove tail of list |
+| MoveToEnd | **O(1)** | Relink nodes |
+| Len | **O(1)** | Cached length |
+| Range | **O(n)** | Snapshot + iteration |
+| RangeLocked | **O(n)** | No allocation, holds lock |
+| Keys/Values | **O(n)** | Returns defensive copy |
+| Front/Back | **O(1)** | Direct pointer access |
+| At | **O(n)** | Must traverse list |
 
 ## Thread Safety
 
 All operations are thread-safe via internal `sync.RWMutex`:
 
 - **Reads** (Get, Has, Len, Range, Keys, Values, Front, Back) use RLock
-- **Writes** (Set, Delete, Clear, Reset) use Lock
+- **Writes** (Set, Delete, Clear, Reset, Pop*, MoveToEnd) use Lock
 
 ```go
 var om orderedmap.OrderedMap[int, string]
@@ -182,11 +233,20 @@ Range and RangeBreak take snapshots **before** calling your callback, releasing
 ```go
 om.Range(func(k string, v int) {
     om.Set("new_"+k, v*2) // No deadlock!
+    om.Delete("old")      // No deadlock!
 })
 ```
 
 ⚠️ **Snapshot semantics** - The callback sees the state at the time Range was called, not live updates
 
+❌ **RangeLocked is NOT safe** for re-entrant calls:
+
+```go
+om.RangeLocked(func(k string, v int) {
+    om.Set("new", 1) // DEADLOCK!
+})
+```
+
 ## Use Cases
 
 ### Terminal UI - Stable Rendering
@@ -206,16 +266,31 @@ checks.Range(func(name string, status Status) {
 })
 ```
 
-### Configuration - Preserve Order
+### LRU Cache
 
 ```go
-// Maintain order from config file
-type Config struct {
-    Settings orderedmap.OrderedMap[string, string]
+type LRUCache struct {
+    items   orderedmap.OrderedMap[string, []byte]
+    maxSize int
+}
+
+func (c *LRUCache) Get(key string) ([]byte, bool) {
+    if val, ok := c.items.Get(key); ok {
+        c.items.MoveToEnd(key) // O(1) - move to back for LRU
+        return val, true
+    }
+    return nil, false
 }
 
-// YAML/JSON preserves order during unmarshal
-// Display or process in original order
+func (c *LRUCache) Set(key string, value []byte) {
+    c.items.Set(key, value)
+    c.items.MoveToEnd(key) // O(1) - newest at back
+
+    // Evict oldest if over capacity
+    for c.items.Len() > c.maxSize {
+        c.items.PopFront() // O(1) - remove oldest
+    }
+}
 ```
 
 ### FIFO Queue with Deduplication
@@ -226,27 +301,13 @@ var queue orderedmap.OrderedMap[string, Task]
 
 queue.Set(task.ID, task) // Dedupe by ID
 for {
-    id, task, ok := queue.Front()
+    id, task, ok := queue.PopFront() // O(1)
     if !ok { break }
     process(task)
-    queue.Delete(id)
 }
 ```
 
-## Comparison with Alternatives
-
-| Feature | OrderedMap | `map[K]V` | `container/list` |
-|---------|-----------|-----------|------------------|
-| Insertion order | ✅ | ❌ (random) | ✅ |
-| O(1) lookup | ✅ | ✅ | ❌ (O(n)) |
-| Thread-safe | ✅ | ❌ | ❌ |
-| Generic | ✅ | ✅ | ✅ (Go 1.18+) |
-| Zero value usable | ✅ | ✅ | ❌ |
-| O(1) delete | ❌ (O(n)) | ✅ | ✅ |
-
-## Examples
-
-### Example 1: Configuration Manager
+### Configuration Manager
 
 ```go
 type ConfigManager struct {
@@ -267,50 +328,17 @@ func (cm *ConfigManager) Display() {
 }
 ```
 
-### Example 2: LRU-like Cache
-
-```go
-type Cache struct {
-    items orderedmap.OrderedMap[string, []byte]
-    maxSize int
-}
-
-func (c *Cache) Set(key string, value []byte) {
-    c.items.Set(key, value)
-
-    // Evict oldest if over capacity
-    for c.items.Len() > c.maxSize {
-        oldest, _, _ := c.items.Front()
-        c.items.Delete(oldest)
-    }
-}
-```
-
-### Example 3: Event Log
-
-```go
-type EventLog struct {
-    events orderedmap.OrderedMap[string, Event]
-}
-
-func (el *EventLog) Record(event Event) {
-    el.events.Set(event.ID, event)
-}
-
-func (el *EventLog) GetRecent(n int) []Event {
-    var recent []Event
-    count := 0
-
-    // Iterate from oldest to newest
-    el.events.RangeBreak(func(_ string, event Event) bool {
-        recent = append(recent, event)
-        count++
-        return count < n
-    })
+## Comparison with Alternatives
 
-    return recent
-}
-```
+| Feature | OrderedMap | `map[K]V` | `container/list` |
+|---------|-----------|-----------|------------------|
+| Insertion order | ✅ | ❌ (random) | ✅ |
+| O(1) lookup | ✅ | ✅ | ❌ (O(n)) |
+| O(1) delete | ✅ | ✅ | ✅ |
+| O(1) move | ✅ | ❌ | ✅ |
+| Thread-safe | ✅ | ❌ | ❌ |
+| Generic | ✅ | ✅ | ✅ (Go 1.18+) |
+| Zero value usable | ✅ | ✅ | ❌ |
 
 ## Requirements
 
@@ -326,8 +354,11 @@ go test -v
 go test -v -race
 
 # Check coverage
-go test -v -coverprofile=coverage.out
-go tool cover -html=coverage.out
+go test -v -coverprofile=coverage.txt
+go tool cover -html=coverage.txt
+
+# Run benchmarks
+go test -bench=. -benchmem
 ```
 
 Current test coverage: **100%**
@@ -353,4 +384,4 @@ DocSpring, Inc. ([@DocSpring](https://github.com/DocSpring))
 
 ## Acknowledgments
 
-Inspired by the need for stable UI rendering in terminal applications and the lack of a simple, thread-safe ordered map in Go's standard library.
+Inspired by the need for stable UI rendering in terminal applications and the lack of a simple, thread-safe ordered map with O(1) operations in Go's standard library.