Writeup on Design Decisions

[andrewthad]

Sadly, most libraries for building arrays of bytes (this one included) do not document design decisions. This is unfortunate because these internal details, although they may not be visible in the surface API, are extremely important for using the library in a way that provides predictable performance. For example, stashing a builder (from any byte-array-building library) in a data structure is often a bad idea. Understanding how to efficiently serialize an array of objects is important (and foldMap is often the wrong choice). I'd like to do a write up as part of the documentation that goes into these low-level details of builders and then concludes by explaining the choices made in the library. Because otherwise most users have meaningful way to compare this solution to something like Data.ByteString.Builder. It would also be prudent to include benchmarks.