Repository navigation
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## perf/drain-results #1240 +/- ##
======================================================
+ Coverage 94.31% 94.33% +0.02%
======================================================
Files 293 293
Lines 29912 30050 +138
Branches 3057 3069 +12
======================================================
+ Hits 28211 28349 +138
Misses 1679 1679
Partials 22 22 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
🚀 Deploying Preview to Cloudflare 🚀Preview Deployments by commit
|
ovflowd
marked this pull request as ready for review
November 3, 2026 20:39
ovflowd
force-pushed
the
perf/stream-metadata
branch
from
November 4, 2026 18:24
deb7a89 to
90363d4
Compare
4 tasks done
This comment was marked as low quality.
This comment was marked as low quality.
Sorry, something went wrong.
ovflowd
force-pushed
the
perf/stream-metadata
branch
from
November 6, 2026 13:37
90363d4 to
084e275
Compare
ovflowd
force-pushed
the
perf/stream-metadata
branch
from
November 6, 2026 19:30
084e275 to
b6f721b
Compare
ovflowd
force-pushed
the
perf/stream-metadata
branch
from
November 6, 2026 19:43
b6f721b to
3611a22
Compare
avivkeller
force-pushed
the
perf/stream-metadata
branch
from
November 9, 2026 02:26
3611a22 to
cfe9347
Compare
ovflowd
force-pushed
the
perf/stream-metadata
branch
from
November 9, 2026 10:37
cfe9347 to
be718cd
Compare
ovflowd
force-pushed
the
perf/stream-metadata
branch
from
November 9, 2026 11:03
be718cd to
0b3700d
Compare
This was referenced Nov 9, 2026
ovflowd
force-pushed
the
perf/stream-metadata
branch
from
November 10, 2026 20:53
0b3700d to
cd9e078
Compare
…t chunk With more than one thread, metadata and section-pages now start on the first chunk of their dependency instead of waiting for all of it, so parsing, metadata and section pages overlap. The generated files are unchanged. section-pages passes each module's entries on as they arrive and adds the chunk pages after the last of them, in module order, as if built from the whole input at once. A module's chunk pages need all of its entries, and a chunk need not hold whole modules, so groupWholeModules regroups streamed entries into batches of whole modules, and rejects a module whose entries come back after another's. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com> Assisted-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…Modules worker.stream no longer reads its input with toBatches, so the helper now comes with groupWholeModules, its first caller. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
…ules From the review. A module is one file: parseApiDoc sets every entry's api once per file, and worker.stream never splits an item, so each of metadata's chunks already holds whole modules. section-pages reads its input as it comes with toBatches instead of regrouping it, and the helper and its tests go. Co-authored-by: Aviv Keller <me@aviv.sh> Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
The two tests comparing section-pages' batched output with its whole input become one: both compared against the same output. core's collectAsyncGenerator replaces a local copy of it, and html's test gives section-pages its entries as an array, which it reads as one batch, so it needs no stream of its own. toBatches' test no longer defines a generator body it never runs. The comment on section-pages' chunk pages says batches, as chunk already means a page there. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Every streaming generator reads its input through toBatches, which takes both the stream and the collected array one thread gives, but the docs for writing one only said to accept both. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
ovflowd
force-pushed
the
perf/stream-metadata
branch
from
November 11, 2026 00:06
cd9e078 to
d026fd1
Compare
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR lets
metadataandsection-pagesstart on their dependency's first chunk instead of waiting for all of it, so with more than one thread parsing, metadata and section pages overlap. It's the fourth part of a stack that splits #1205.section-pagespasses each batch of entries on as it arrives and builds that batch's chunk pages, which it adds after the last batch, in module order, as if built from the whole input at once.metadata's chunks holds whole modules, sosection-pagesreads its input as it comes, with no regrouping.creating-generators.mdnow states that guarantee.toBatchesgives an input that is whole or streamed as batches, and the streaming docs point to it.Why it's built this way
Why does this barely move the site build? The overlap here is between
ast,metadataandsection-pages, and stops there.-t section-pagesis delivered throughhtmlandsitemap, so the site build also runsjsx-ast,htmlandsitemap. Butjsx-ast, which readssection-pages, still takes its input whole, and so dojson,orama-dbandllms-txt, which readmetadata.jsx-astandhtmlstream in #1241, which is where the site build gets its -17% (4 threads) and -20% (6 threads) againstmain. So this layer is mostly a precondition. On its own it saves 0.14 to 0.36s. In the site build that's within run-to-run spread. In the legacy build it isn't: at both thread counts, every run on this branch beat every run on #1239. So overlappingastandmetadatadoes save time.The in-flight limit doesn't stop this.
threads * CHUNKS_PER_THREADis counted perworker.streamcall, so at 4 threadsastandmetadatacan each have up to 12 chunks in the pool at once. A benchmark like #1253 can't see this PR. With one thread, core hands every generator its input whole andworker.streamruns each chunk on the main thread, so nothing overlaps. It also builds no section pages.Why no regrouping of
metadata's chunks? The first version hadgroupWholeModules, because I assumed a chunk could end partway through a module. It can't.parseApiDocsetsapionce per file, from the file's path, andworker.streamsplits a batch by item, so each chunk holds whole files, which means whole modules. Aviv pointed this out. Dropping it removed the helper (61 lines) and its 92 lines of tests, and made no measurable difference to #1241 at 6 threads over 7 runs. The guarantee is documented becausejsx-astrelies on it in #1241 too.Why hold the chunk pages until the end? Only to keep the output identical. Each chunk page's first entry is promoted to depth 1, and
sitemaplists depth-1 entries in input order. Yielding each batch's chunk pages right away would mix them in with the module pages and reordersitemap.xml. It costs nothing next tomain, which also built every chunk page after the whole input and returned everything at the end. From #1241 on,htmlputs its pages in site order itself. So if we want the chunk pages to go out earlier, the cheaper fix is a sort insitemap. I'd rather do that in its own PR.Why
toBatches? So a streaming generator can handle both cases with a singlefor await: the collected array it gets with one thread (the contract from #1238), and the iterable it gets with more. It's 6 lines, andjsx-ast,htmlandhtml-alluse it later in the stack.Benchmarks
Full Node.js docs on Node 26. Each number is the median of 5 interleaved runs (4 for #1239 at 6 threads, and for
main's legacy build at 6 threads). Peak is RSS summed over the process tree. Site is-t orama-db -t json -t llms-txt -t section-pages, and legacy is-t legacy-html-all -t legacy-json-all.mainMemory is flat. The site build's -3% at 6 threads is within #1239's spread there (2189 to 2399MB over 4 runs).
Validation
Added tests for
toBatches, and forsection-pagesbuilding the same output from several batches as from its whole input, as it gets it with one thread, and passing each batch on before the next one arrives. Built on 12 of Node.js's API docs at 1 and 4 threads, the output is byte-identical tomain's.Related Issues
Refs: #1205
Check List
node --run testand all tests passed.node --run format:check&node --run lint.