Support ordered iteration

[voxpelli]

Summary by CodeRabbit

• New Features

  • Added an ordered option to control result ordering—process results in order or unordered for improved performance.

• Documentation

  • Updated README with new ordered option documentation in both the Options and API sections.

• Chores

  • Removed "WORK IN PROGRESS – early prerelease" badge, indicating project maturity.
  • Refined project header description.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[voxpelli]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

The changes introduce an ordered option to bufferedAsyncMap that determines whether results are returned in iteration order or as soon as they resolve. The underlying data structures were refactored from Sets to Arrays, with supporting utility functions updated to work with arrays instead of sets.

Changes

Cohort / File(s)	Change Summary
Documentation README.md	Reworded header, removed WIP badge, added documentation for new ordered option (defaults to false)
Core Implementation index.js	Introduced ordered parameter in options; replaced Set with Array for sub-iterators and buffered promises; implemented separate control flow paths for ordered vs. unordered modes; updated JSDoc signature to include ordered?: boolean option
Type & Utility Updates lib/find-least-targeted.js	Updated JSDoc type annotations to accept Iterable<Item> | Item[] instead of Set<Item> for items parameters in countTargets and findLeastTargeted
Helper Functions lib/misc.js	Added new exported function arrayDeleteInPlace(list, value) for in-place removal of first occurrence from arrays
Type Checks lib/type-checks.js	Renamed isPartOfSet to isPartOfArray; updated signature and logic to work with arrays using includes() instead of Set-based has()
Test Utilities test/utils.js	Added new async generator function nestedYieldValuesOverTime(count, wait, nested) for nested async iteration testing
Test Coverage test/values.spec.js	Added test suite for ordered option with multiple test cases covering out-of-order results, in-order results, nested generators, and performance comparisons

Sequence Diagram

sequenceDiagram
    participant Caller
    participant bufferedAsyncMap
    participant SubIterator
    participant Buffer
    
    Note over bufferedAsyncMap: ordered = false (default)
    Caller->>bufferedAsyncMap: iterate with ordered=false
    loop Race-based buffering
        bufferedAsyncMap->>Buffer: queue all sub-iterator promises
        bufferedAsyncMap->>Buffer: resolve first-to-complete promise
        Buffer-->>Caller: return unordered result
        bufferedAsyncMap->>Buffer: remove resolved promise, refill buffer
    end
    
    Note over bufferedAsyncMap: ordered = true
    Caller->>bufferedAsyncMap: iterate with ordered=true
    loop Sequential buffering
        bufferedAsyncMap->>Buffer: queue promises in order
        bufferedAsyncMap->>Buffer: resolve from first sub-iterator
        Buffer-->>Caller: return ordered result
        bufferedAsyncMap->>Buffer: preserve source order
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Areas requiring extra attention:

• index.js: Multiple interdependent behavioral branches between ordered and unordered modes; array mutation operations (splice, unshift) across asynchronous control flows; potential edge cases with empty arrays or iterator exhaustion
• Interaction between modes: Verify ordered mode correctly preserves iteration order while unordered mode properly implements race-based buffering strategy
• test/values.spec.js: Ensure nested test cases properly validate both ordered and unordered semantics with complex async generator compositions
• lib/find-least-targeted.js and lib/type-checks.js: Confirm array-based logic (includes, iteration) handles all edge cases previously covered by Set operations

Poem

🐰 Hop, hop! Arrays replace sets today,
Ordered or wild—results find their way,
Buffered and async, in parallel stream,
The rabbit's refactored your iteration dream! ✨

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch support-ordered-iteration

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f77358b and 1bc1987.

📒 Files selected for processing (7)

• README.md (2 hunks)
• index.js (7 hunks)
• lib/find-least-targeted.js (2 hunks)
• lib/misc.js (1 hunks)
• lib/type-checks.js (1 hunks)
• test/utils.js (1 hunks)
• test/values.spec.js (4 hunks)

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}