Enhancement suggestions from repo review

[virgesmith]

Follow-ups from the review that produced #17. These are suggestions, not bugs — each is independent and up for discussion.

1. value_counts: use Counter instead of sort + groupby

The current implementation sorts the input, so it:

• fails with TypeError on hashable-but-unorderable items, e.g. Itr([1j, 1j, 2j]).value_counts() — even though collect(dict) only requires hashability;
• costs O(n log n) where counting is O(n).

Itr(Counter(self._it).items()) fixes both. Caveat: output order changes from sorted-key to first-seen, and the sorted-key ordering is explicitly documented in the 0.3.0 release notes — so this is a (minor) breaking change and needs a deliberate decision.

2. peek(): one-item lookahead buffer instead of tee

Each peek() wraps _it in another itertools.tee layer, so repeated peeks build an ever-deeper chain of tees. A single-item lookahead buffer (like Rust's Peekable) would make peek O(1) regardless of call count, and opens the door to a next_if(predicate) API.

3. Missing Rust-trait staples

Natural additions given the library's stated inspiration:

• sum() / prod() — terminal aggregations (thin wrappers over sum / math.prod);
• dedup() — lazy removal of adjacent duplicates (pairs nicely with chunk_by, works on infinite iterators);
• zip_longest(other, fillvalue=...) — the existing zip truncates to the shorter input;
• sorted_by(key) — eager terminal, complementing groupby's sort-then-group.

4. repeat(1) aliasing inconsistency

repeat(1) returns self, while every other path returns a new Itr (and repeat(n>1) leaves the original exhausted via tee). Harmless, but consuming the returned iterator mutates the original in the n == 1 case only. Dropping the special case would make behaviour uniform.

🤖 Generated with Claude Code

[virgesmith]

Item 1 (value_counts via Counter) has been implemented in #17, with pandas semantics: Counter.most_common() ordering (descending count, ties by first appearance). Items 2–4 remain open.

[virgesmith]

Item 2 (peek lookahead buffer) was implemented, benchmarked, and ultimately rejected in #19 — recording the rationale here.

The premise ("each peek() wraps _it in another itertools.tee layer, so repeated peeks build an ever-deeper chain of tees") is false in CPython: tee() on an already-teed iterator uses _tee.__copy__, which creates a cheap sibling sharing the same data buffer instead of nesting. Measurements on the current implementation:

• 10k / 40k / 160k repeated peeks on one Itr: linear, flat ~0.22 µs/peek
• after 1000 peeks, _it is still a single _tee — no layering

The buffer implementations measured as follows vs main:

workload	always-on buffer	lazy buffer
map+filter+collect, 200k items	2.5–3x slower	parity
peek-then-next loop	~2x faster	~2x faster

A ~2x win on rare peek-heavy loops didn't justify either the pipeline penalty (always-on) or the extra machinery and unpeek() API surface (lazy), so peek remains tee-based. next_if (also suggested here) survives regardless — it's built on peek + next and needs no buffer.

Items 1, 3 and 4 are implemented (item 1 in #17, the rest in #19).

🤖 Generated with Claude Code