Efficient byte-string builder for all wireform format packages.

This module re-exports the vendored fast-builder engine from Wireform.Builder.FastBuilder and Wireform.Builder.Internal.Prim. All wireform packages should depend on this module rather than importing the internal modules directly.

Builder type

Builder is a zero-copy, chunk-based byte-string builder. It is a Monoid, so fragments are combined with (<>). No bytes are copied until you run the builder with one of the output functions below.

Running a builder

toStrictByteString

Materialise the builder into a single strict ByteString. Allocates one buffer and fills it.

toLazyByteString

Materialise into a lazy ByteString (a list of strict chunks). Good when the output is large or will be streamed further.

hPutBuilder

Write the builder directly to a Handle (e.g. a file or socket) without materialising an intermediate ByteString. Uses chunked I/O internally.

hPutBuilderLen

Like hPutBuilder but also returns the number of bytes written.

hPutBuilderWith

Like hPutBuilderLen with explicit control over the initial and subsequent buffer capacities.

Stream transforms

StreamSink and withStreamTransform allow you to interpose a streaming transformation (e.g. compression) between the builder and its output. The StreamSink receives raw pointer/length pairs as the builder fills buffers; you can feed them into zstd, gzip, or any other streaming codec.

Usage example

import Wireform.Builder

myEncoder :: MyMsg -> Builder
myEncoder msg = word8 0x0A <> byteString (encodePayload msg)

-- strict output
let bs = toStrictByteString (myEncoder msg)

-- or write straight to a handle
hPutBuilder stdout (myEncoder msg)

StreamSink and withStreamTransform allow interposing a streaming transformation (e.g. compression) between the builder and its output destination. See Wireform.Builder.FastBuilder for the full internal API.