Enhance bufferedWriter with bufio.Writer, scratch space, and configurable thresholds (B1)

[AdamDrewsTR]

Summary

Enhances the internal bufferedWriter used by StreamWriter to reduce syscalls and heap allocations during streaming worksheet generation. Adds two new Options fields to give callers control over when and how streaming data spills to disk.

Changes

bufio.Writer layer after threshold

Once the in-memory buffer reaches the threshold, the old code flushed raw bytes.Buffer to the temp file on every Sync() call. The new code switches to a bufio.Writer wrapping the temp file, so disk writes happen only when the bufio buffer is full (default 128 KiB). This reduces write syscalls by ~100x for large worksheets (e.g. 100 MB XML goes from ~3000 syscalls to ~400).

After the switch, the bytes.Buffer backing array is released entirely (bw.buf = bytes.Buffer{}) to avoid holding two large buffers simultaneously.

Scratch space for numeric formatting

A [24]byte scratch field eliminates heap allocations in the new WriteInt, WriteUint, and WriteFloat methods by using strconv.AppendInt/AppendUint/AppendFloat directly into stack memory.

Offset tracking and WriteAt

The written field tracks total bytes written. WriteAt allows updating data at specific offsets — in-memory mode modifies the buffer directly, temp file mode flushes bufio first then uses pwrite.

CopyTo for efficient streaming to ZIP

CopyTo copies all buffered data to an io.Writer using a large read buffer (256 KiB minimum, or bioSize if larger) to minimize Pread syscalls when writing sheet data into the ZIP archive.

Configurable options

• StreamingChunkSize: Controls when streaming spills to a temp file. Default is StreamChunkSize (16 MiB). Set to -1 to keep all data in memory (eliminates disk I/O when sufficient RAM is available).
• StreamingBufSize: Controls the bufio.Writer size after spill. Default is StreamingBufSizeDefault (128 KiB), which is the measured inflection point on both NVMe and HDD.

Compatibility

All existing tests pass. The enhanced bufferedWriter is a strict superset of the old one — existing callers that only use Write, WriteString, Reader, Sync, Flush, and Close are unaffected. The new methods (WriteInt, WriteUint, WriteFloat, WriteAt, CopyTo, Bytes, Reset) are additive.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.60%. Comparing base (4bebb61) to head (eeb75bb).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2321   +/-   ##
=======================================
  Coverage   99.60%   99.60%           
=======================================
  Files          32       32           
  Lines       26791    26876   +85     
=======================================
+ Hits        26685    26770   +85     
  Misses         55       55           
  Partials       51       51           

Flag	Coverage Δ
unittests	99.60% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.