feat: ordered: 'eager' — concurrent dispatch, in-order delivery

[voxpelli]

What this adds

A new opt-in mode that fills the one gap in ordered delivery: out-of-order callback dispatch with in-order yields.

Under ordered: true, async-generator callbacks run strictly serial — the buffer always feeds from the current sub-iterator, so bufferSize only buffers the undispatched generator objects and never steps them concurrently. ordered: 'eager' delivers in strict source order like ordered: true, but dispatches callbacks — generators included — concurrently up to bufferSize.

Stacked on #50 (which introduces ordered: true). Review/merge that first; this PR's diff resolves once #50 lands.

Implementation — the lane model

Full contract in ADVANCED.md, "Ordered mode". Fully isolated behind one mode === 'eager' check at construction and in next(); the ordered/unordered hot paths only get the equivalent ordered → mode === 'ordered' renames, so their V8 shapes are untouched.

• Lanes — one Lane per in-flight source item, in source order (lanes[0] = delivery head), each with a private buffer of ≤ lookahead values.
• admitLanes admits placeholder lanes; the source's own FIFO .next() binds lane order == source order, and a placeholder always exists as a head to race (no long-lived promise — the memory invariant holds).
• pumpLane steps non-head lanes up to lookahead values ahead concurrently, then parks them. Total buffering ≤ bufferSize × lookahead, independent of an unbounded non-head generator.
• nextValueEager only ever waits on the head lane, reusing the same fresh-per-pull park / ABORT_SENTINEL machinery as nextValue (exactly-once rejection + retention contracts preserved).
• Errors surface in source order, so observable order — fail-fast picking the source-order-earliest error, and a generator's buffered values arriving before its own later error — matches ordered: true.
• doCleanup .return()s live lane iterators (deduped vs pendingCloses); a shared classifyStep factors the result-classification ladder for the two eager helpers without touching the two envelope factories.

lookahead option

The per-lane buffer depth is exposed as lookahead (positive integer, default 1, ordered: 'eager' only — throws with any other mode). It trades memory (and, under shared-resource contention, the head's critical-path priority) for pipeline depth on deep per-item generators. The allocation is deliberately flat (one lookahead for every lane): buffers and step-slots are per-lane and independent, so the head is never internally starved, and a serial/consumer-paced head can't use a bigger share anyway. External contention is a bufferSize concern the library can't schedule. (Rationale in ADVANCED.md.)

Magnitude worth knowing (documented in ADVANCED.md): at the default lookahead: 1, a generator whose cost is spread across its yields (rather than before the first) gets no benefit from bufferSize — each non-head lane runs one value ahead then parks, so the mode performs like ordered: true and the shortfall grows with the bufferSize you asked for. Treat bufferSize × lookahead as a memory budget in values. There is a genuine limit underneath: for a very-long or unbounded spread-cost generator, no lookahead both bounds memory and recovers full concurrency — ordered: false is the better fit there if out-of-order delivery is acceptable.

Tests & verification

npm test green — 166 passing, type-coverage 99.25% strict, coverage 99.92%, lint clean.

• test/eager.spec.js: option handling + lookahead validation; real concurrency (maxInFlight === bufferSize vs 1 for ordered: true); in-order delivery under reordering; faster-than-ordered:true timing; bounded look-ahead (an unbounded non-head generator is stepped exactly lookahead times, then parks — default 1 and a custom 3); cleanup of every live lane; external-abort delivery (exactly-once rejection then done, in source order — identical to ordered: true); early close with lookahead > 1 buffered values (the non-head lane is still .return()ed); both error modes; and malformed-result / hostile-getter handling.
• test/memory.spec.js: an eager retention case alongside the unordered one.
• benchmark/nested.js: ordered: true and ordered: 'eager' fan-out rows.

Notable bugs caught & fixed

• OOM on a fast source: admitOneLane must keep lane.pending set across the callback dispatch's await and clear it only once the lane settles — clearing it early left a parked consumer racing an instantly-resolving undefined → busy-loop. Fixed and pinned by the array-sourced error specs.
• Vacuous look-ahead test: the original bounded-look-ahead spec used an async arrow returning a generator (delivered as a plain value, never fanned out), so it passed at.most(1) with 0 steps. Rewritten to use an async generator function and assert the exact step count.

Breaking changes (v2)

• ordered now throws on a non-boolean, non-'eager' value. { ordered: 1 }, { ordered: 'yes' }, { ordered: null } all worked in v1.0.1 (coerced by truthiness) and now throw a TypeError. Correct — a typo shouldn't silently pick a mode — but a genuine break for anyone writing ordered: flag ? 1 : 0, and the strongest reason this can't ship as a minor.

Release-please note (maintainer decision, not made here): this branch is feat:-driven, which release-please cuts as a minor. For it to cut a major, a commit in the release needs a BREAKING CHANGE: footer. I have deliberately not added one — whether to force the major now or cut v2 by hand is a release-timing call for you.

Decisions (settled)

• API: ordered: 'eager' (widened ordered to boolean | 'eager').
• lookahead: exposed as an option, eager-only, default 1, flat per-lane allocation.
• Fail-fast ordering: surfaces the source-order-earliest error (not the chronologically-first). Not a concession — if delivery is in source order, an error is just another thing delivered in that order; the surprising mode would deliver values in source order but errors in wall-clock order. ADVANCED.md already states this as a flat property, and it matches ordered: true exactly. The only cost is not short-circuiting quite as early — a latency detail, not a semantic one.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FSyTJjbP823pjYfueuSsdu