Make Iterable.flatten stack safe across empty iterables

[fubhy]

Summary

A finite iterable containing many consecutive empty inner iterables can throw RangeError before yielding a later value or completing.

Important

This PR starts with focused failing reproduction tests. Add the implementation fix to this same branch; CI is expected to fail until that fix is included.

flatten overflows on a long run of empty iterables

Module: Iterable
Audit ID: core-g-r-iterable-flatten-empty-run-stack-overflow
Severity / confidence: medium / high

What happens

A finite iterable containing many consecutive empty inner iterables can throw RangeError before yielding a later value or completing.

Why it happens

When an inner iterator is exhausted, next clears it and recursively calls itself. Every consecutive empty iterable consumes another JavaScript stack frame, so 20,000 empty iterables overflow before the recursion reaches a later value.

Expected behavior

flatten lazily flattens arbitrary iterable inputs, including empty inner iterables, without iteration depth growing with the number of consecutive empty inputs.

Relevant implementation

These links and excerpts are pinned to audit base c9b56ab507f224426ee8388dc450da447ec4715f.

• packages/effect/src/Iterable.ts:1498-1506
• packages/effect/src/Iterable.ts:1541-1562

View problematic code at packages/effect/src/Iterable.ts:1498-1506

export const flatMap: {
  <A, B>(
    f: (a: NoInfer<A>, i: number) => Iterable<B>
  ): (self: Iterable<A>) => Iterable<B>
  <A, B>(self: Iterable<A>, f: (a: NoInfer<A>, i: number) => Iterable<B>): Iterable<B>
} = dual(
  2,
  <A, B>(self: Iterable<A>, f: (a: A, i: number) => Iterable<B>): Iterable<B> => flatten(map(self, f))
)

View exact lines on GitHub

View problematic code at packages/effect/src/Iterable.ts:1541-1562

export const flatten = <A>(self: Iterable<Iterable<A>>): Iterable<A> => ({
  [Symbol.iterator]() {
    const outerIterator = self[Symbol.iterator]()
    let innerIterator: Iterator<A> | undefined
    function next() {
      if (innerIterator === undefined) {
        const next = outerIterator.next()
        if (next.done) {
          return next
        }
        innerIterator = next.value[Symbol.iterator]()
      }
      const result = innerIterator.next()
      if (result.done) {
        innerIterator = undefined
        return next()
      }
      return result
    }
    return { next }
  }
})

View exact lines on GitHub

Reproduction

pnpm vitest run packages/effect/test/Iterable.test.ts -t "flatten is stack safe across empty iterables"

Observed failure: The intended failure was reproduced with RangeError: Maximum call stack size exceeded.

Implementation handoff

The initial reproduction tests on this branch are the regression specification for the implementation fix that should follow in this PR.

1. Start with the pinned implementation excerpts and the Why it happens analysis above.
2. Change the implementation so it satisfies the stated Expected behavior; do not weaken or remove the reproduction assertions.
3. Run the focused reproduction command(s) and confirm the observed failures become passing tests:

pnpm vitest run packages/effect/test/Iterable.test.ts -t "flatten is stack safe across empty iterables"

4. Run the affected package's existing tests, then the repository lint and type checks before requesting review.

Audit provenance

• Audit base: c9b56ab507f224426ee8388dc450da447ec4715f
• Reproduction base: c9b56ab507f224426ee8388dc450da447ec4715f
• Findings: core-g-r-iterable-flatten-empty-run-stack-overflow
• Initial patch: focused reproduction tests; implementation fix pending

[changeset-bot]

⚠️ No Changeset found

Latest commit: a5e3008

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pullfrog]

Reviewed changes

• Added a regression test in packages/effect/test/Iterable.test.ts that reproduces the stack overflow in Iterable.flatten when iterating through 20,000 consecutive empty inner iterables before yielding the final [1].

ℹ️ This branch currently contains only the reproduction test. The non-recursive implementation fix in packages/effect/src/Iterable.ts still needs to land before merge, matching the handoff in the PR description. The test itself is a clean, focused regression spec and should not be weakened.

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}