Choosing Between page.evaluate and page.evaluateHandle for Large DOM Extraction

Recommendation for a 10,000-row table

For a single run where you ultimately need all rows in Node, use chunked page.evaluate with in-page serialization and process/release each chunk. Do not use a single page.evaluateHandle for the whole table unless you only need a small subset of fields and can keep the handle alive in the page.

Confirmed facts

• page.evaluate copies only serializable return values into Node. Map table cells to plain objects or arrays inside the page and never return DOM elements.
• page.evaluateHandle returns a JSHandle that lives in the browser page context. It avoids copying the whole object until properties are accessed, but the handle must be disposed, preferably in a finally block, to release the browser-side reference.
• JSHandles become invalid after navigation or execution-context destruction. Do not reuse them.

Likely trade-offs for this case

• Chunked page.evaluate bounds Node transfer and avoids handle lifecycle. It only reduces peak RSS if each chunk is processed and released, not accumulated into one final in-memory array.
• page.evaluateHandle is preferable only when you need a small subset of fields from a large live object. Repeated property access crosses the context boundary and can be slower than one serialization.
• For 10k rows, handle create/dispose cost is usually small compared with cell transfer. If all fields are copied into Node anyway, the handle adds complexity and leak risk without reducing final memory.

Steps needed for this case

1. Serialize in the page. Extract rows with start/end indices and return plain data only:

   const rows = await page.evaluate(({start, end}) => {
     const trs = Array.from(document.querySelectorAll('table tbody tr'));
     return trs.slice(start, end).map(tr => ({
       cells: Array.from(tr.querySelectorAll('td')).map(td => td.innerText)
     }));
   }, {start, end});
   

2. Chunk the extraction. Start with 500–1,000 rows per call and tune by measured peak RSS and wall time. Wide rows need smaller chunks, narrow rows can use larger chunks.
3. Process and release each chunk. Write to disk/DB or stream it instead of accumulating all 10k rows in one Node array if peak memory is the goal.
4. If you test page.evaluateHandle, always dispose:

   let handle;
   try {
     handle = await page.evaluateHandle(() => document.querySelector('table'));
     // access only needed fields
   } finally {
     await handle?.dispose();
   }
   

One missing diagnostic that changes the recommendation: can you stream/write each chunk and release it, or must you hold all 10,000 rows in Node memory at once? If you must accumulate the full set, peak memory will be similar regardless of chunking, and the decision shifts to transfer overhead vs handle safety. Knowing average serialized bytes per row also lets you set a data-size-based chunk target instead of a row-count guess.

Verification

• Measure Node peak RSS and wall time for one full page.evaluate, chunked page.evaluate at 500 and 1,000 rows with release per chunk, and evaluateHandle with selective access plus dispose.
• Repeat on your target Puppeteer/Chromium version and confirm handles are not reused after navigation or context changes.