[Sequence] Creation: Collection::asSequence() and the constrainOnce flag

[nikophil]

Two creation APIs from the #23 checklist: Collection::asSequence() (§5) and the constrainOnce flag on sequenceOf() (§4). They travel together because they answer the same question — how a sequence comes into being — and the remaining factories (generateSequence, emptySequence) follow in the next one.

Collection::asSequence()

Eight lines, because the machinery was already there:

public function asSequence(): Sequence
{
    return sequenceOf($this);
}

A Collection is an IteratorAggregate, which GeneratorSequence already treats as a producer asked for an iterable once per pass. Every element store returns a fresh ArrayIterator from getIterator(), so the identity guard of resolveProducedIterable() is satisfied without a special case. No copy, no wrapper class, no new branch in the replayability contract.

What that buys is a live view: each pass re-reads the collection rather than a snapshot taken at call time. asSequence_reads_the_collection_on_each_pass pins it on the mutable side, and its immutable branch pins the counterpart — add() returns a new collection the existing sequence does not see.

The laziness test is phrased as "no read of its own" rather than "no read at all", on purpose: view collections such as MapKeySet or MapEntrySet read their source when they are built, well before asSequence() is called. What is under test is that asSequence() and the operation chained onto it add nothing to that count.

Both live in the shared CollectionConvert / CollectionMutateWrite traits, so they run against every Collection implementation — 14 of them.

constrainOnce

$rows = sequenceOf(fn () => $qb->getQuery()->toIterable(), constrainOnce: true);
$rows->toArray();   // ok
$rows->toArray();   // NonReplayableSourceException

A constructor flag rather than a constrainOnce() method, as agreed on #23: one class, one boolean, no wrapper sequence to explain.

The guard sits before the per-source-kind branches of resolveSourceForThisPass():

if ($this->constrainOnce) {
    if ($this->consumed) {
        throw NonReplayableSourceException::constrainedOnceSequenceAlreadyIterated();
    }

    $this->consumed = true;

    // this sequence has exactly one pass, so the per-kind guards below have nothing
    // left to protect: the source is handed over as it is
    return $source instanceof Closure ? $this->produceFromClosure($source) : $source;
}

That position is the point: the identity check and the WeakReference exist to keep a replay honest, and a constrained sequence has no second pass to keep honest. The closure resolution was duplicated between the two paths, so it comes out as produceFromClosure().

The exception gets its own named constructor. The existing message speaks of a source that is non-replayable, which would be untrue of an array the caller chose to constrain, and a reader chasing that message would look in the wrong place.

A chained operation needs no propagation: the derived sequence does not carry the flag, but its factory re-reads the root on every pass, so the root is what throws — constrained_once_throws_through_a_chained_operation pins that. And like the existing one-shot rule, it throws at getIterator() rather than at the first advance, so a violation surfaces at the start of the offending pass instead of yielding a silent empty result.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[delacry]

Thank you!