stream: defer readable async iterator listener

[trivikr]

This defers installing the readable listener for readable async
iteration until read() returns null.

The iterator still installs eos() up front, so existing error and close
handling is preserved. For the common path where chunks are already
buffered, this avoids listener dispatch while the iterator drains data.

Benchmark results are neutral-to-positive, with no statistically
significant regression observed:

                                                       confidence improvement accuracy (*)   (**)  (***)
streams/readable-async-iterator.js sync='no' n=100000                  0.66 %       ±1.25% ±1.67% ±2.17%
streams/readable-async-iterator.js sync='yes' n=100000                 2.08 %       ±2.42% ±3.25% ±4.28%

---

Assisted-by: openai:gpt-5.5

[nodejs-github-bot]

Review requested:

• @nodejs/streams

[aduh95]

Benchmark CI: https://ci.nodejs.org/view/Node.js%20benchmark/job/benchmark-node-micro-benchmarks/1853/

Results

                                                                                         confidence improvement accuracy (*)    (**)   (***)
streams/compose.js n=1000                                                                                0.26 %       ±0.55%  ±0.73%  ±0.95%
streams/creation.js kind='duplex' n=50000000                                                            -0.07 %       ±0.65%  ±0.86%  ±1.13%
streams/creation.js kind='readable' n=50000000                                                           0.20 %       ±1.05%  ±1.40%  ±1.82%
streams/creation.js kind='transform' n=50000000                                                          0.23 %       ±0.55%  ±0.73%  ±0.95%
streams/creation.js kind='writable' n=50000000                                                           0.15 %       ±0.77%  ±1.03%  ±1.34%
streams/destroy.js kind='duplex' n=1000000                                                              -0.17 %       ±0.43%  ±0.58%  ±0.75%
streams/destroy.js kind='readable' n=1000000                                                            -0.12 %       ±0.86%  ±1.15%  ±1.49%
streams/destroy.js kind='transform' n=1000000                                                           -0.22 %       ±0.53%  ±0.71%  ±0.93%
streams/destroy.js kind='writable' n=1000000                                                            -0.53 %       ±0.68%  ±0.90%  ±1.17%
streams/finished.js streamType='readable' n=10000000                                                    -0.21 %       ±0.67%  ±0.89%  ±1.16%
streams/finished.js streamType='writable' n=10000000                                                    -0.01 %       ±0.53%  ±0.71%  ±0.93%
streams/iter-creation.js n=100000 type='pair' api='classic'                                             -0.47 %       ±4.25%  ±5.66%  ±7.36%
streams/iter-creation.js n=100000 type='pair' api='iter'                                                 0.01 %       ±0.76%  ±1.01%  ±1.31%
streams/iter-creation.js n=100000 type='pair' api='webstream'                                           -0.24 %       ±0.78%  ±1.03%  ±1.35%
streams/iter-creation.js n=100000 type='readable' api='classic'                                          1.08 %       ±7.56% ±10.07% ±13.10%
streams/iter-creation.js n=100000 type='readable' api='iter'                                            -1.26 %       ±2.32%  ±3.09%  ±4.02%
streams/iter-creation.js n=100000 type='readable' api='webstream'                                        0.33 %       ±0.80%  ±1.07%  ±1.39%
streams/iter-creation.js n=100000 type='transform' api='classic'                                        -0.86 %       ±1.95%  ±2.59%  ±3.38%
streams/iter-creation.js n=100000 type='transform' api='webstream'                                      -0.03 %       ±0.89%  ±1.19%  ±1.55%
streams/iter-creation.js n=100000 type='writable' api='classic'                                          1.84 %       ±3.37%  ±4.50%  ±5.89%
streams/iter-creation.js n=100000 type='writable' api='iter'                                            -0.55 %       ±2.48%  ±3.29%  ±4.29%
streams/iter-creation.js n=100000 type='writable' api='webstream'                                       -0.49 %       ±1.95%  ±2.59%  ±3.37%
streams/iter-file-read.js n=5 filesize=1048576 api='classic'                                             6.20 %       ±7.36%  ±9.81% ±12.80%
streams/iter-file-read.js n=5 filesize=1048576 api='iter'                                                3.96 %      ±11.88% ±15.81% ±20.57%
streams/iter-file-read.js n=5 filesize=1048576 api='webstream'                                           4.97 %       ±7.17%  ±9.55% ±12.46%
streams/iter-file-read.js n=5 filesize=16777216 api='classic'                                           -1.47 %       ±6.38%  ±8.50% ±11.07%
streams/iter-file-read.js n=5 filesize=16777216 api='iter'                                               6.23 %      ±22.14% ±29.46% ±38.35%
streams/iter-file-read.js n=5 filesize=16777216 api='webstream'                                         -0.04 %       ±0.53%  ±0.71%  ±0.93%
streams/iter-file-read.js n=5 filesize=67108864 api='classic'                                           -1.29 %       ±3.58%  ±4.80%  ±6.31%
streams/iter-file-read.js n=5 filesize=67108864 api='iter'                                              -4.79 %      ±18.73% ±24.93% ±32.48%
streams/iter-file-read.js n=5 filesize=67108864 api='webstream'                                   *      0.67 %       ±0.61%  ±0.81%  ±1.05%
streams/iter-from-batching.js n=100 chunkSize=16 chunks=256 method='from-sync-writev'                    5.69 %      ±11.61% ±15.49% ±20.24%
streams/iter-from-batching.js n=100 chunkSize=16 chunks=4096 method='from-sync-writev'                   0.62 %       ±4.20%  ±5.59%  ±7.27%
streams/iter-from-batching.js n=1000 chunkSize=16 chunks=16384 method='from-first-batch'                -1.07 %       ±6.37%  ±8.48% ±11.06%
streams/iter-from-batching.js n=1000 chunkSize=16 chunks=256 method='from-first-batch'                  -1.36 %       ±4.11%  ±5.47%  ±7.12%
streams/iter-from-batching.js n=1000 chunkSize=16 chunks=4096 method='from-first-batch'                  1.49 %       ±4.46%  ±5.94%  ±7.73%
streams/iter-throughput-broadcast.js n=5 datasize=1048576 consumers=1 api='classic'                      0.13 %       ±0.79%  ±1.05%  ±1.37%
streams/iter-throughput-broadcast.js n=5 datasize=1048576 consumers=1 api='iter'                         0.57 %       ±0.80%  ±1.07%  ±1.39%
streams/iter-throughput-broadcast.js n=5 datasize=1048576 consumers=1 api='webstream'                   -1.44 %      ±14.56% ±19.37% ±25.21%
streams/iter-throughput-broadcast.js n=5 datasize=1048576 consumers=2 api='classic'                      0.03 %       ±0.70%  ±0.93%  ±1.21%
streams/iter-throughput-broadcast.js n=5 datasize=1048576 consumers=2 api='iter'                        -1.07 %       ±1.66%  ±2.21%  ±2.90%
streams/iter-throughput-broadcast.js n=5 datasize=1048576 consumers=2 api='webstream'                   -8.33 %      ±12.26% ±16.31% ±21.23%
streams/iter-throughput-broadcast.js n=5 datasize=1048576 consumers=4 api='classic'                      2.71 %       ±4.12%  ±5.54%  ±7.32%
streams/iter-throughput-broadcast.js n=5 datasize=1048576 consumers=4 api='iter'                        -2.57 %      ±12.49% ±16.62% ±21.63%
streams/iter-throughput-broadcast.js n=5 datasize=1048576 consumers=4 api='webstream'                   -4.10 %       ±9.92% ±13.21% ±17.20%
streams/iter-throughput-broadcast.js n=5 datasize=16777216 consumers=1 api='classic'                    -6.33 %       ±8.43% ±11.24% ±14.68%
streams/iter-throughput-broadcast.js n=5 datasize=16777216 consumers=1 api='iter'                        2.63 %      ±13.70% ±18.23% ±23.73%
streams/iter-throughput-broadcast.js n=5 datasize=16777216 consumers=1 api='webstream'                   3.15 %      ±10.33% ±13.75% ±17.89%
streams/iter-throughput-broadcast.js n=5 datasize=16777216 consumers=2 api='classic'                    -6.40 %       ±6.63%  ±8.82% ±11.48%
streams/iter-throughput-broadcast.js n=5 datasize=16777216 consumers=2 api='iter'                 *    -15.22 %      ±11.52% ±15.40% ±20.20%
streams/iter-throughput-broadcast.js n=5 datasize=16777216 consumers=2 api='webstream'           **    -10.38 %       ±7.72% ±10.29% ±13.44%
streams/iter-throughput-broadcast.js n=5 datasize=16777216 consumers=4 api='classic'                    -1.84 %       ±6.56%  ±8.73% ±11.37%
streams/iter-throughput-broadcast.js n=5 datasize=16777216 consumers=4 api='iter'                       -2.69 %      ±11.97% ±15.94% ±20.78%
streams/iter-throughput-broadcast.js n=5 datasize=16777216 consumers=4 api='webstream'                  -0.75 %       ±5.20%  ±6.93%  ±9.03%
streams/iter-throughput-compression.js n=5 datasize=1048576 api='classic'                               -5.13 %      ±14.20% ±18.90% ±24.59%
streams/iter-throughput-compression.js n=5 datasize=1048576 api='iter'                                  -5.43 %      ±13.68% ±18.21% ±23.73%
streams/iter-throughput-compression.js n=5 datasize=1048576 api='webstream'                             -3.05 %       ±9.63% ±12.81% ±16.67%
streams/iter-throughput-compression.js n=5 datasize=16777216 api='classic'                              14.72 %      ±31.22% ±41.55% ±54.09%
streams/iter-throughput-compression.js n=5 datasize=16777216 api='iter'                                 -3.25 %      ±26.37% ±35.10% ±45.69%
streams/iter-throughput-compression.js n=5 datasize=16777216 api='webstream'                             4.65 %      ±23.81% ±31.67% ±41.23%
streams/iter-throughput-compression.js n=5 datasize=67108864 api='classic'                               1.06 %      ±15.82% ±21.05% ±27.40%
streams/iter-throughput-compression.js n=5 datasize=67108864 api='iter'                                 -3.22 %      ±23.67% ±31.57% ±41.24%
streams/iter-throughput-compression.js n=5 datasize=67108864 api='webstream'                            11.64 %      ±24.01% ±31.95% ±41.58%
streams/iter-throughput-identity.js n=5 datasize=1048576 api='classic'                                  -1.32 %       ±3.21%  ±4.33%  ±5.73%
streams/iter-throughput-identity.js n=5 datasize=1048576 api='iter-sync'                          *      1.86 %       ±1.71%  ±2.29%  ±3.00%
streams/iter-throughput-identity.js n=5 datasize=1048576 api='iter'                                      0.75 %       ±0.84%  ±1.12%  ±1.46%
streams/iter-throughput-identity.js n=5 datasize=1048576 api='webstream'                         **    -17.41 %      ±12.31% ±16.38% ±21.32%
streams/iter-throughput-identity.js n=5 datasize=16777216 api='classic'                                 -4.62 %      ±10.04% ±13.35% ±17.39%
streams/iter-throughput-identity.js n=5 datasize=16777216 api='iter-sync'                              -15.71 %      ±30.97% ±41.21% ±53.64%
streams/iter-throughput-identity.js n=5 datasize=16777216 api='iter'                                    -3.83 %      ±17.38% ±23.12% ±30.10%
streams/iter-throughput-identity.js n=5 datasize=16777216 api='webstream'                               -4.02 %       ±8.70% ±11.58% ±15.07%
streams/iter-throughput-identity.js n=5 datasize=67108864 api='classic'                                  3.35 %       ±7.61% ±10.12% ±13.18%
streams/iter-throughput-identity.js n=5 datasize=67108864 api='iter-sync'                                1.13 %       ±1.98%  ±2.63%  ±3.43%
streams/iter-throughput-identity.js n=5 datasize=67108864 api='iter'                                    -7.11 %       ±9.73% ±12.99% ±16.99%
streams/iter-throughput-identity.js n=5 datasize=67108864 api='webstream'                               -4.23 %       ±6.33%  ±8.42% ±10.96%
streams/iter-throughput-pipeto.js n=5 datasize=1048576 api='classic'                                    -2.35 %       ±3.53%  ±4.75%  ±6.29%
streams/iter-throughput-pipeto.js n=5 datasize=1048576 api='iter-sync-source'                           -0.64 %       ±2.03%  ±2.72%  ±3.58%
streams/iter-throughput-pipeto.js n=5 datasize=1048576 api='iter-sync'                                   0.76 %       ±1.91%  ±2.54%  ±3.32%
streams/iter-throughput-pipeto.js n=5 datasize=1048576 api='iter'                                        1.41 %       ±6.20%  ±8.26% ±10.77%
streams/iter-throughput-pipeto.js n=5 datasize=1048576 api='webstream'                           **    -18.23 %      ±12.41% ±16.51% ±21.50%
streams/iter-throughput-pipeto.js n=5 datasize=16777216 api='classic'                                   -0.72 %      ±13.53% ±18.00% ±23.43%
streams/iter-throughput-pipeto.js n=5 datasize=16777216 api='iter-sync-source'                           9.63 %      ±22.96% ±30.58% ±39.87%
streams/iter-throughput-pipeto.js n=5 datasize=16777216 api='iter-sync'                                -16.64 %      ±30.98% ±41.25% ±53.76%
streams/iter-throughput-pipeto.js n=5 datasize=16777216 api='iter'                                      -8.68 %      ±10.91% ±14.69% ±19.49%
streams/iter-throughput-pipeto.js n=5 datasize=16777216 api='webstream'                                 -1.74 %      ±10.45% ±13.91% ±18.11%
streams/iter-throughput-pipeto.js n=5 datasize=67108864 api='classic'                                   -2.76 %       ±7.47%  ±9.94% ±12.93%
streams/iter-throughput-pipeto.js n=5 datasize=67108864 api='iter-sync-source'                         -10.94 %      ±12.90% ±17.38% ±23.07%
streams/iter-throughput-pipeto.js n=5 datasize=67108864 api='iter-sync'                                  0.12 %       ±1.83%  ±2.44%  ±3.17%
streams/iter-throughput-pipeto.js n=5 datasize=67108864 api='iter'                                       5.23 %      ±11.86% ±15.80% ±20.61%
streams/iter-throughput-pipeto.js n=5 datasize=67108864 api='webstream'                           *     -5.62 %       ±4.73%  ±6.30%  ±8.21%
streams/iter-throughput-share.js n=5 backpressure='block' batches=10000 consumers=2                      0.36 %       ±1.44%  ±1.91%  ±2.49%
streams/iter-throughput-share.js n=5 backpressure='block' batches=10000 consumers=32                    -0.35 %       ±0.73%  ±0.97%  ±1.28%
streams/iter-throughput-share.js n=5 backpressure='block' batches=10000 consumers=8                      0.41 %       ±0.65%  ±0.86%  ±1.13%
streams/iter-throughput-transform.js n=5 datasize=1048576 api='classic'                                  4.39 %      ±11.57% ±15.39% ±20.04%
streams/iter-throughput-transform.js n=5 datasize=1048576 api='iter-sync'                                0.08 %       ±1.29%  ±1.71%  ±2.23%
streams/iter-throughput-transform.js n=5 datasize=1048576 api='iter'                                     4.32 %      ±17.20% ±22.88% ±29.79%
streams/iter-throughput-transform.js n=5 datasize=1048576 api='webstream'                                8.24 %      ±10.40% ±13.84% ±18.02%
streams/iter-throughput-transform.js n=5 datasize=16777216 api='classic'                         **      4.67 %       ±3.41%  ±4.56%  ±5.95%
streams/iter-throughput-transform.js n=5 datasize=16777216 api='iter-sync'                        *     -6.14 %       ±5.15%  ±6.86%  ±8.93%
streams/iter-throughput-transform.js n=5 datasize=16777216 api='iter'                                    0.00 %       ±7.48%  ±9.95% ±12.95%
streams/iter-throughput-transform.js n=5 datasize=16777216 api='webstream'                               2.12 %       ±5.90%  ±7.85% ±10.22%
streams/iter-throughput-transform.js n=5 datasize=67108864 api='classic'                                 3.21 %       ±3.74%  ±4.98%  ±6.49%
streams/iter-throughput-transform.js n=5 datasize=67108864 api='iter-sync'                              -0.86 %       ±2.78%  ±3.69%  ±4.81%
streams/iter-throughput-transform.js n=5 datasize=67108864 api='iter'                                   -1.72 %       ±4.20%  ±5.59%  ±7.28%
streams/iter-throughput-transform.js n=5 datasize=67108864 api='webstream'                               0.10 %       ±6.08%  ±8.09% ±10.54%
streams/pipe-object-mode.js n=5000000                                                                    0.13 %       ±0.53%  ±0.71%  ±0.93%
streams/pipe.js n=5000000                                                                                0.07 %       ±0.37%  ±0.50%  ±0.65%
streams/readable-async-iterator.js sync='no' n=100000                                                   -0.42 %       ±1.65%  ±2.19%  ±2.85%
streams/readable-async-iterator.js sync='yes' n=100000                                                  -1.88 %       ±4.24%  ±5.64%  ±7.35%
streams/readable-bigread.js n=1000                                                                      -0.37 %       ±1.27%  ±1.69%  ±2.20%
streams/readable-bigunevenread.js n=1000                                                                -0.00 %       ±0.86%  ±1.15%  ±1.49%
streams/readable-boundaryread.js type='buffer' n=2000                                                    0.10 %       ±0.56%  ±0.75%  ±0.97%
streams/readable-boundaryread.js type='string' n=2000                                                   -0.28 %       ±1.18%  ±1.57%  ±2.04%
streams/readable-from.js type='array' n=10000000                                                         0.95 %       ±2.10%  ±2.80%  ±3.64%
streams/readable-from.js type='async-generator' n=10000000                                              -0.18 %       ±0.77%  ±1.02%  ±1.34%
streams/readable-from.js type='sync-generator-with-async-values' n=10000000                             -0.06 %       ±1.06%  ±1.41%  ±1.84%
streams/readable-from.js type='sync-generator-with-sync-values' n=10000000                               0.34 %       ±1.13%  ±1.51%  ±1.97%
streams/readable-readall.js n=5000                                                                       1.05 %       ±1.21%  ±1.61%  ±2.10%
streams/readable-uint8array.js kind='encoding' n=1000000                                                 0.78 %       ±1.02%  ±1.36%  ±1.77%
streams/readable-uint8array.js kind='read' n=1000000                                                    -0.52 %       ±1.59%  ±2.12%  ±2.76%
streams/readable-unevenread.js n=1000                                                                    0.67 %       ±1.06%  ±1.41%  ±1.84%
streams/writable-manywrites.js len=1024 callback='no' writev='no' sync='no' n=100000                    -0.67 %       ±3.55%  ±4.72%  ±6.14%
streams/writable-manywrites.js len=1024 callback='no' writev='no' sync='yes' n=100000             *     13.19 %      ±10.97% ±14.63% ±19.10%
streams/writable-manywrites.js len=1024 callback='no' writev='yes' sync='no' n=100000                   -1.72 %       ±4.69%  ±6.24%  ±8.13%
streams/writable-manywrites.js len=1024 callback='no' writev='yes' sync='yes' n=100000                  -1.70 %       ±2.76%  ±3.69%  ±4.82%
streams/writable-manywrites.js len=1024 callback='yes' writev='no' sync='no' n=100000                   -1.05 %       ±4.00%  ±5.33%  ±6.94%
streams/writable-manywrites.js len=1024 callback='yes' writev='no' sync='yes' n=100000                   1.43 %       ±9.43% ±12.55% ±16.34%
streams/writable-manywrites.js len=1024 callback='yes' writev='yes' sync='no' n=100000                  -1.01 %       ±4.39%  ±5.85%  ±7.61%
streams/writable-manywrites.js len=1024 callback='yes' writev='yes' sync='yes' n=100000                  0.37 %       ±2.47%  ±3.29%  ±4.28%
streams/writable-manywrites.js len=32768 callback='no' writev='no' sync='no' n=100000                   -1.97 %       ±5.68%  ±7.56%  ±9.84%
streams/writable-manywrites.js len=32768 callback='no' writev='no' sync='yes' n=100000                   5.79 %      ±13.32% ±17.72% ±23.07%
streams/writable-manywrites.js len=32768 callback='no' writev='yes' sync='no' n=100000                  -2.07 %       ±4.35%  ±5.78%  ±7.53%
streams/writable-manywrites.js len=32768 callback='no' writev='yes' sync='yes' n=100000           *     -2.89 %       ±2.51%  ±3.35%  ±4.37%
streams/writable-manywrites.js len=32768 callback='yes' writev='no' sync='no' n=100000                  -1.62 %       ±3.80%  ±5.05%  ±6.58%
streams/writable-manywrites.js len=32768 callback='yes' writev='no' sync='yes' n=100000                  4.16 %       ±8.07% ±10.75% ±14.01%
streams/writable-manywrites.js len=32768 callback='yes' writev='yes' sync='no' n=100000                  1.13 %       ±3.78%  ±5.03%  ±6.55%
streams/writable-manywrites.js len=32768 callback='yes' writev='yes' sync='yes' n=100000                -1.37 %       ±1.84%  ±2.45%  ±3.19%
streams/writable-uint8array.js kind='object-mode' n=50000000                                             0.01 %       ±0.19%  ±0.26%  ±0.33%
streams/writable-uint8array.js kind='write' n=50000000                                            *      1.08 %       ±0.91%  ±1.22%  ±1.61%
streams/writable-uint8array.js kind='writev' n=50000000                                                  0.25 %       ±0.40%  ±0.53%  ±0.69%

Be aware that when doing many comparisons the risk of a false-positive
result increases. In this case, there are 140 comparisons, you can thus
expect the following amount of false-positive results:
  7.00 false positives, when considering a   5% risk acceptance (*, **, ***),
  1.40 false positives, when considering a   1% risk acceptance (**, ***),
  0.14 false positives, when considering a 0.1% risk acceptance (***)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.32%. Comparing base (13feb34) to head (be9f90e).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63594      +/-   ##
==========================================
- Coverage   90.32%   90.32%   -0.01%     
==========================================
  Files         730      730              
  Lines      234653   234660       +7     
  Branches    43942    43947       +5     
==========================================
+ Hits       211959   211961       +2     
+ Misses      14415    14413       -2     
- Partials     8279     8286       +7     

Files with missing lines	Coverage Δ
lib/internal/streams/readable.js	97.24% <100.00%> (+0.01%)	⬆️

... and 22 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[aduh95]

There are significant perf regressions:

streams/iter-throughput-broadcast.js n=5 datasize=16777216 consumers=2 api='webstream'           **    -10.38 %       ±7.72% ±10.29% ±13.44%
streams/iter-throughput-identity.js n=5 datasize=1048576 api='webstream'                         **    -17.41 %      ±12.31% ±16.38% ±21.32%
streams/iter-throughput-pipeto.js n=5 datasize=1048576 api='webstream'                           **    -18.23 %      ±12.41% ±16.51% ±21.50%

and the CI did not reproduce the claimed perf improvements:

streams/readable-async-iterator.js sync='no' n=100000     -0.42 %       ±1.65%  ±2.19%  ±2.85%
streams/readable-async-iterator.js sync='yes' n=100000    -1.88 %       ±4.24%  ±5.64%  ±7.35%

[trivikr]

Closing as the benchmark run locally was not reproducible in CI, and there were significant perf regressions in "streams/iter" throughput implementation.