feat(batch)!: single-use Batch + Go returns (<-chan error, error); inline item IDs

[MasterOfBinary]

Summary

Makes Batch single-use, changes Batch.Go to return (<-chan error, error), replaces the dedicated ID-generator goroutine with an inline per-reader counter, and fixes a timer leak in waitForItems.

Note: the CHANGELOG entry and "Latest Release" version bump are intentionally not part of this PR.

⚠️ Breaking changes

1. Batch.Go now returns (<-chan error, error). Start failures are reported via the returned error instead of a panic or the pipeline error channel:

   • already-used Batch → ErrBatchUsed
   • nil source → ErrNilSource

   Both are errors.Is-able. On a start error the returned channel is non-nil and already closed, so ranging over it is always safe even if the error is ignored.

   Migration: errs, err := b.Go(ctx, s, p...) and check err.

2. Batch is single-use. A second Go() on the same Batch returns ErrBatchUsed; create a new Batch with New for each run.

3. Removed BufferConfig.IDBufferSize and DefaultIDBufferSize. Item IDs come from an inline counter — there is no ID-generator goroutine or channel. Drop IDBufferSize from any BufferConfig literal.

What it does & why

• Single-use instead of reusable. New() is cheap (it allocates no goroutines or channels until Go), so reuse saved essentially nothing while creating a whole class of cross-run concurrency hazards. Single-use removes them by construction:
  • the item-ID counter is now a doReader-local variable — no atomic, no lock, nothing to reason about;
  • shutdown no longer needs a mutex around closing done/errs;
  • the Done()/Go() data race (a Done() call concurrent with a reusing Go()) becomes impossible.
• Errors over panics for Go. Go already returns a channel, so folding start failures into a returned error is friendlier for long-lived services and treats nil-source and reuse consistently — no recover() needed, and the pipeline error channel is no longer overloaded with "you misused the constructor" errors.
• Timer-leak fix. waitForItems uses time.NewTimer + defer Stop() + Reset() instead of time.After.
• Inline item IDs. Removes the ID-generator goroutine and its buffered channel; IDs are assigned in doReader.
• CollectErrors doc clarified — it blocks until the error channel closes, so there is no need to wait on Done() afterward.

Tests & verification

• New single_use_test.go covers ErrBatchUsed, ErrNilSource, and success-returns-nil; the returned channel on a rejected Go is asserted closed/drainable. reuse_test.go removed.
• BenchmarkBatchThroughput uses only the public API, so it runs on master too.
• gofmt -l . clean · go vet ./... clean · go build ./... clean · go test -race ./... green (including the example // Output: checks) · GOOS=linux GOARCH=386 go build clean (no atomic ⇒ no 32-bit alignment concern).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 95.12195% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.73%. Comparing base (ed01cd7) to head (d49ace6).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
batch/helpers.go	80.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #64      +/-   ##
==========================================
- Coverage   96.79%   96.73%   -0.06%     
==========================================
  Files          12       12              
  Lines         374      368       -6     
==========================================
- Hits          362      356       -6     
  Misses          9        9              
  Partials        3        3              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gemini-code-assist]

Code Review

This pull request addresses data races and improves the reliability of reusing Batch instances. Key changes include passing channels to the ID generator by value to prevent field access races, introducing an idDone channel to ensure background goroutines have fully exited before shutdown completes, and replacing time.After with time.NewTimer to prevent timer leaks. Documentation and examples for CollectErrors were also updated to clarify its blocking behavior. Feedback was provided regarding a remaining race condition where the running flag is cleared after the Done() channel is closed, which could lead to panics if the batch is reused immediately after waiting on Done().

[MasterOfBinary]

Removed the nil source handling subtest from error_handling_test.go (and the code comment that pointed to its replacement — that note only made sense as PR context, not in the source long-term).

For the record: with the start-error contract in this PR, a nil source is reported by Go as ErrNilSource (a start error, the second return value) rather than delivered on the pipeline error channel. The old subtest asserted the pre-change behavior (error arriving on the channel), which no longer holds. Coverage now lives in:

• TestGo_NilSourceReturnsErrNilSource — direct Go(ctx, nil) returns ErrNilSource with a closed, drainable channel.
• TestExecuteBatches_NilSourceSurfacesError — the same error surfaces through the ExecuteBatches helper.