feat(helpers): add onFlush callback to bulk helper (#2553)

[new-world-coder]

Closes #2553

What

Adds an optional onFlush callback to the bulk helper that is invoked after each batch
is flushed to Elasticsearch. The callback receives the current cumulative stats object,
allowing users to track progress during long-running bulk operations.

Why

For large bulk operations using streams or async generators, there was no way to get
progress feedback mid-operation. Users had to wait for the final result to see any stats.
The onFlush callback provides per-batch feedback, making it easy to log progress,
update a progress bar, or surface metrics in terms of document count rather than bytes.

How

• Added onFlush?: (stats: BulkStats) => void | Promise<void> to BulkHelperOptions
• Extracted BulkStats as a named, exported interface
• Called await opts.onFlush({...stats}) at the end of each send() invocation,
  after all per-document callbacks (onSuccess, onDrop) have run for that batch
• Added unit tests covering: basic invocation, cumulative stats, async support, and optional usage
• Updated documentation

Example

await client.helpers.bulk({
  datasource: largeDataset,
  onDocument(doc) {
    return { index: { _index: 'my-index' } }
  },
  onFlush({ total, successful, failed }) {
    console.log(`Progress — processed: ${total}, ok: ${successful}, failed: ${failed}`)
  }
})

[prodsecmachine]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[github-actions]

✅ Vale Linting Results

No issues found on modified lines!

---

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

[github-actions]

🔍 Preview links for changed docs

• docs/reference/client-helpers.md

[JoshMock]

Some nits but the implementation is sound. Thanks for the contribution!

[new-world-coder]

@JoshMock - Thank you for the PR review.
I've addressed all the review comments :

• Test improvements: Replaced the loose type assertions with exact value checks in the onFlush tests. Now they verify specific cumulative stats (1→2→3 documents) instead of just checking types.

• Removed redundant test: Dropped the "bulk helper works fine without onFlush" test since the other tests already cover the optional callback behavior.

• Documentation fix: Updated the docs to use {{es}} placeholder instead of "Elasticsearch".

All tests are passing locally and the changes are ready for your review.
Let me know if you'd like any adjustments

Thanks again

[JoshMock]

looks great!

[elastic-vault-github-plugin-prod]

The backport to 9.4 failed:

The process '/usr/bin/git' failed with exit code 128

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-9.4 9.4
# Navigate to the new working tree
cd .worktrees/backport-9.4
# Create a new branch
git switch --create backport-3226-to-9.4
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 347597584a2fa3840f8b10dad7c688ad4496e142
# Push it to GitHub
git push --set-upstream origin backport-3226-to-9.4
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-9.4

Then, create a pull request where the base branch is 9.4 and the compare/head branch is backport-3226-to-9.4.

[github-actions]

AI Backport Resolver created a backport PR (no conflicts): #3248