@@ -1,463 +1,156 @@
1−-- | `ArrayBuffer` serialization in the “builder monoid” style.
1+-- | This module provides a `Builder` monoid and a `PutM` monad
2+-- | for serializing `Data.ArrayBuffer.Types.ArrayBuffer`s.
3+-- | See the package README for usage examples.
3−-- | This module provides a `Builder` monoid and a `PutM` monad which are roughly
5+-- | Writing to an `ArrayBuffer` is an `Effect`ful activity, so most
4−-- | equivalent to types of the same name in the Haskell
6+-- | functions in this module must be run in a `MonadEffect` context.
5−-- | [`Data.Binary.Put`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html)
8−-- | This library defines no typeclasses.
8+-- | For other operations for working with `ArrayBuffer`, see
10−-- | ## Deserialization
10+-- | [`Data.ArrayBuffer.ArrayBuffer`](https://pursuit.purescript.org/packages/purescript-arraybuffer/docs/Data.ArrayBuffer.ArrayBuffer)
11−-- |
11+-- | in package __arraybuffer__.
13−-- | [__purescript-parsing-dataview__](https://pursuit.purescript.org/packages/purescript-parsing-dataview/)
14−-- | for a way to deserialize from `ArrayBuffer` back to Purescript data.
16−-- | ## Usage Examples
18−-- | All `ArrayBuffer` building must occur in `Effect`.
20−-- | ### Serialize an integer
22−-- | Create a two-byte `arraybuffer :: ArrayBuffer` which contains the number *-2* encoded as big-endian 16-bit two’s-complement.
25−-- | arraybuffer <- execPut $ putInt16be (-2)
28−-- | ### Serialize a `String` as UTF8
30−-- | A function which encodes a `String` as UTF8 with a length prefix in a
31−-- | way that's compatible with the
32−-- | [`Binary.Put.putStringUtf8`](https://hackage.haskell.org/package/binary/docs/Data-Binary-Put.html#v:putStringUtf8)
33−-- | function from the Haskell
34−-- | [__binary__](https://hackage.haskell.org/package/binary)
36−-- | Uses [`Data.TextEncoding.encodeUtf8`](https://pursuit.purescript.org/packages/purescript-text-encoding/docs/Data.TextEncoding#v:encodeUtf8).
38−-- | putStringUtf8 :: forall m. (MonadEffect m) => String -> PutM m Unit
39−-- | putStringUtf8 s = do
40−-- | let stringbuf = Data.ArrayBuffer.Typed.buffer $
41−-- | Data.TextEncoding.encodeUtf8 s
42−-- | -- Put a 64-bit big-endian length prefix for the length of the utf8
43−-- | -- string, in bytes.
45−-- | putUint32be $ Data.Uint.fromInt $ Data.ArrayBuffer.byteLength stringbuf
46−-- | putArrayBuffer stringbuf
49−-- | ### Serialize an `Array Int`
51−-- | A function which encodes an `Array Int` with a length prefix in a
52−-- | way that's compatible with the
53−-- | [`Binary` instance for `[Int32]`](https://hackage.haskell.org/package/binary/docs/Data-Binary.html#t:Binary)
55−-- | [__binary__](https://hackage.haskell.org/package/binary)
58−-- | putArrayInt32 :: forall m. (MonadEffect m) => Array Int -> PutM m Unit
59−-- | putArrayInt32 xs = do
60−-- | -- Put a 64-bit big-endian length prefix for the length of the
61−-- | -- array, in bytes.
63−-- | putUint32be $ Data.Uint.fromInt $ Data.Array.length xs
64−-- | traverse_ putInt32be xs
66module Data.ArrayBuffer.Builder
12module Data.ArrayBuffer.Builder
69−, execPutM
15+ , execPutM
70−, execPut
16+ , execPut
71−, putArrayBuffer
18+ , putArrayBuffer
72−, putUint8
21+ , putUint8
73−, putInt8
22+ , putInt8
74−, putUint16be
23+ , putUint16be
75−, putUint16le
24+ , putUint16le
76−, putInt16be
25+ , putInt16be
77−, putInt16le
26+ , putInt16le
78−, putUint32be
27+ , putUint32be
79−, putUint32le
28+ , putUint32le
80−, putInt32be
29+ , putInt32be
81−, putInt32le
30+ , putInt32le
82−, putFloat32be
31+ , putFloat32be
83−, putFloat32le
32+ , putFloat32le
84−, putFloat64be
33+ , putFloat64be
85−, putFloat64le
34+ , putFloat64le
86−, Builder
35+ , module Data.ArrayBuffer.Builder.Internal
108import Prelude
38import Prelude
40+import Control.Monad.Rec.Class (class MonadRec)
110−import Control.Monad.Writer.Trans (WriterT, execWriterT, tell)
41+import Control.Monad.Writer.Trans (WriterT, execWriterT, tell, lift)
111−import Data.ArrayBuffer.ArrayBuffer as AB
42+import Data.ArrayBuffer.Builder.Internal (Builder, DataBuff(..), length, toView, (<>>))
112−import Data.ArrayBuffer.DataView as DV
113−import Data.ArrayBuffer.Typed as AT
43+import Data.ArrayBuffer.Builder.Internal as Internal
114−import Data.ArrayBuffer.Types (ArrayBuffer, Uint8Array)
44+import Data.ArrayBuffer.Types (ArrayBuffer, DataView)
115import Data.Float32 (Float32)
45import Data.Float32 (Float32)
116−import Data.Maybe (Maybe(..))
117import Data.UInt (UInt)
46import Data.UInt (UInt)
118import Effect (Effect)
47import Effect (Effect)
119−import Effect.Class (class MonadEffect, liftEffect)
48+import Effect.Class (class MonadEffect)
121−-- | The `PutM` monad is a Writer transformer monad which
50+-- | The `PutM` monad is a `WriterT Builder` transformer monad which
122−-- | [gives us access to do-notation](https://wiki.haskell.org/Do_notation_considered_harmful#Library_design)
51+-- | gives us do-notation for the `Builder` monoid. The base monad must be
123−-- | for building `ArrayBuffer`s.
52+-- | a `MonadEffect`.
54+-- | To append `Builder`s in this monad call `tell`, or any of the `put*`
55+-- | functions in this module.
124type PutM = WriterT Builder
56type PutM = WriterT Builder
126−-- | `Put` monad is the non-transformer version of `PutM`.
58+-- | The `PutM` type reified to `Effect`, in other words `WriterT Builder Effect`.
127type Put = PutM Effect
59type Put = PutM Effect
129−-- | Monoidal builder for `ArrayBuffer`s.
61+-- | Build an `ArrayBuffer` with do-notation in any `MonadEffect`. *O(n)* Stack-safe.
130−-- |
62+execPutM :: forall m. MonadEffect m => MonadRec m => PutM m Unit -> m ArrayBuffer
131−-- | ### Left-associative `<>>` append operator
63+execPutM = Internal.execBuilder <=< execWriterT
65+-- | Build an `ArrayBuffer` with do-notation in `Effect`. *O(n)* Stack-safe.
66+execPut :: Put Unit -> Effect ArrayBuffer
69+-- | Build up a sub-`Builder` without `tell`ing it to the `Writer` yet.
133−-- | __TL;DR__ You probably don't want to use the `Builder` monoid directly
71+-- | One case where we might want to call a `subBuilder` is when
134−-- | in your code, it’s better to use the `PutM` monad with do-notation instead.
72+-- | serializing length-prefixed messages in some protocol. In that case,
73+-- | we must serialize the message first, calculate the message length,
74+-- | append the message length, and then append the message.
136−-- | The `Builder` monoid in this library is efficient when we `snoc` single
76+-- | In a `PutM` monad do-block, we can
137−-- | items onto the end of it, or when we only `cons` single items to the
138−-- | beginning, but it can be less efficient when we are mixing `cons` and
140−-- | This matters when we're appending three or more `Builder`s
141−-- | in one associative expression, because the
142−-- | `Semigroup` append operator `<>` is right-associative.
144−-- | To solve this, we provide an operator `<>>` for appending `Builders`.
145−-- | `<>>` is exactly the same as `<>`, but left-associative.
146−-- | This only matters when we're chaining together three
147−-- | or more `Builder`s in a single associative expression.
150−-- | builder₁ <> builder₂ <> builder₃
152−-- | we should always prefer to
155−-- | builder₁ <>> builder₂ <>> builder₃
157−-- | so that we get the efficient
79+-- | do
158−-- | `snoc`ing of `Builder`s.
80+-- | messageBuilder <- subBuilder $ do
159−-- |
81+-- | putField1
160−-- | If we build our `ArrayBuffer`s with the `PutM` monad instead of appending by
82+-- | putField2
161−-- | using the `Semigroup` instance of `Builder`, then we always get the efficient
164−data Builder
84+-- | putInt32be $ length messageBuilder
165− = Node Builder ArrayBuffer Builder
85+-- | tell messageBuilder
167−
87+subBuilder :: forall m. Monad m => PutM m Unit -> PutM m Builder
168−instance semigroupBuilder :: Semigroup Builder where
169− append Null Null = Null
172− append l (Node Null rx rr) = Node l rx rr -- this is the snoc case
173− append (Node ll lx Null) r = Node ll lx r -- found the rightmost Null
175− append (Node ll lx lr) r = Node ll lx $ append lr r -- search down the right
176− -- side of the left tree
177− -- to find the rightmost
180−infixl 5 append as <>>
182−instance monoidBuilder :: Monoid Builder where
185−-- | `Builder` is not an instance of `Foldable` because `Builder` is monomorphic.
186−foldl :: forall b. (b -> ArrayBuffer -> b) -> b -> Builder -> b
188−foldl f a (Node l x r) = foldl f (f (foldl f a l) x) r
190−-- | Monomorphic foldM copied from
191−-- | [`Data.Foldable.foldM`](https://pursuit.purescript.org/packages/purescript-foldable-traversable/4.1.1/docs/Data.Foldable#v:foldM)
192−foldM :: forall b m. (Monad m) => (b -> ArrayBuffer -> m b) -> b -> Builder -> m b
193−foldM f a0 = foldl (\ma b -> ma >>= flip f b) (pure a0)
195−-- | Construct a `Builder` with a single `ArrayBuffer`. *O(1)*
196−singleton :: ArrayBuffer -> Builder
197−singleton buf = Node Null buf Null
199−-- | Add an `ArrayBuffer` to the end of the `Builder`. *O(1)*
200−snoc :: Builder -> ArrayBuffer -> Builder
201−snoc bs x = Node bs x Null
203−-- | Build a single `ArrayBuffer` from a `Builder`. *O(n)*
204−execBuilder :: forall m. (MonadEffect m) => Builder -> m ArrayBuffer
205−execBuilder bldr = do
206− let buflen = foldl (\b a -> b + AB.byteLength a) 0 bldr
207− -- Allocate the final ArrayBuffer
208− buf <- liftEffect $ AB.empty buflen
209− -- Then copy each ArrayBuffer into the final ArrayBuffer.
210− -- To memcpy from one ArrayBuffer to another, apparently we have to first view
211− -- both ArrayBuffers as ArrayView (Typed Array).
212− newview <- liftEffect (AT.whole buf :: Effect Uint8Array)
215− let offset' = offset + AB.byteLength a
216− aview <- liftEffect (AT.whole a :: Effect Uint8Array)
217− _ <- liftEffect $ AT.setTyped newview (Just offset') aview
222−-- | Build an `ArrayBuffer` with do-notation in any `MonadEffect`. *O(n)*
223−execPutM :: forall m. (MonadEffect m) => PutM m Unit -> m ArrayBuffer
224−execPutM = execBuilder <=< execWriterT
88+subBuilder = lift <<< execWriterT
226−-- | Build an `ArrayBuffer` with do-notation. *O(n)*
227−execPut :: Put Unit -> Effect ArrayBuffer
230-- | Append an `ArrayBuffer` to the builder.
90-- | Append an `ArrayBuffer` to the builder.
231−putArrayBuffer :: forall m. (MonadEffect m) => ArrayBuffer -> PutM m Unit
91+putArrayBuffer :: forall m. Monad m => ArrayBuffer -> PutM m Unit
232−putArrayBuffer = tell <<< singleton
92+putArrayBuffer = tell <<< Internal.singleton <<< Internal.Buff
234−-- | Serialize an 8-bit unsigned integer (byte) into a new `ArrayBuffer`.
94+-- | Append a `DataView` to the builder.
235−encodeUint8 :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
95+putDataView :: forall m. Monad m => DataView -> PutM m Unit
236−encodeUint8 x = do
96+putDataView = tell <<< Internal.singleton <<< Internal.View
237− buf <- liftEffect $ AB.empty 1
238− _ <- liftEffect $ DV.setUint8 (DV.whole buf) 0 x
241−-- | Append an 8-bit unsigned integer (byte) to the builder.
98+-- | Append either an `ArrayBuffer` or a `DataView` to the builder.
242−putUint8 :: forall m. (MonadEffect m) => UInt -> PutM m Unit
99+putDataBuff :: forall m. Monad m => DataBuff -> PutM m Unit
243−putUint8 = putArrayBuffer <=< encodeUint8
100+putDataBuff = tell <<< Internal.singleton
245−-- | Serialize an 8-bit two’s-complement signed integer (char) into a new `ArrayBuffer`.
102+-- | Append an 8-bit unsigned integer (byte) to the builder.
246−encodeInt8 :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
103+putUint8 :: forall m. MonadEffect m => UInt -> PutM m Unit
247−encodeInt8 x = do
104+putUint8 = putArrayBuffer <=< Internal.encodeUint8
248− buf <- liftEffect $ AB.empty 1
249− _ <- liftEffect $ DV.setInt8 (DV.whole buf) 0 x
252-- | Append an 8-bit two’s-complement signed integer (char) to the builder.
106-- | Append an 8-bit two’s-complement signed integer (char) to the builder.
253−putInt8 :: forall m. (MonadEffect m) => Int -> PutM m Unit
107+putInt8 :: forall m. MonadEffect m => Int -> PutM m Unit
254−putInt8 = putArrayBuffer <=< encodeInt8
108+putInt8 = putArrayBuffer <=< Internal.encodeInt8
256−-- | Serialize a 16-bit big-endian unsigned integer into a new `ArrayBuffer`.
257−encodeUint16be :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
258−encodeUint16be x = do
259− buf <- liftEffect $ AB.empty 2
260− _ <- liftEffect $ DV.setUint16be (DV.whole buf) 0 x
263-- | Append a 16-bit big-endian unsigned integer to the builder.
110-- | Append a 16-bit big-endian unsigned integer to the builder.
264−putUint16be :: forall m. (MonadEffect m) => UInt -> PutM m Unit
111+putUint16be :: forall m. MonadEffect m => UInt -> PutM m Unit
265−putUint16be = putArrayBuffer <=< encodeUint16be
112+putUint16be = putArrayBuffer <=< Internal.encodeUint16be
267−-- | Serialize a 16-bit little-endian unsigned integer into a new `ArrayBuffer`.
268−encodeUint16le :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
269−encodeUint16le x = do
270− buf <- liftEffect $ AB.empty 2
271− _ <- liftEffect $ DV.setUint16le (DV.whole buf) 0 x
274-- | Append a 16-bit little-endian unsigned integer to the builder.
114-- | Append a 16-bit little-endian unsigned integer to the builder.
275−putUint16le :: forall m. (MonadEffect m) => UInt -> PutM m Unit
115+putUint16le :: forall m. MonadEffect m => UInt -> PutM m Unit
276−putUint16le = putArrayBuffer <=< encodeUint16le
116+putUint16le = putArrayBuffer <=< Internal.encodeUint16le
278−-- | Serialize a 16-bit big-endian two’s-complement signed integer into a new `ArrayBuffer`.
279−encodeInt16be :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
281− buf <- liftEffect $ AB.empty 2
282− _ <- liftEffect $ DV.setInt16be (DV.whole buf) 0 x
285-- | Append a 16-bit big-endian two’s-complement signed integer to the builder.
118-- | Append a 16-bit big-endian two’s-complement signed integer to the builder.
286−putInt16be :: forall m. (MonadEffect m) => Int -> PutM m Unit
119+putInt16be :: forall m. MonadEffect m => Int -> PutM m Unit
287−putInt16be = putArrayBuffer <=< encodeInt16be
120+putInt16be = putArrayBuffer <=< Internal.encodeInt16be
289−-- | Serialize a 16-bit little-endian two’s-complement signed integer into a new `ArrayBuffer`.
290−encodeInt16le :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
292− buf <- liftEffect $ AB.empty 2
293− _ <- liftEffect $ DV.setInt16le (DV.whole buf) 0 x
296-- | Append a 16-bit little-endian two’s-complement signed integer to the builder.
122-- | Append a 16-bit little-endian two’s-complement signed integer to the builder.
297−putInt16le :: forall m. (MonadEffect m) => Int -> PutM m Unit
123+putInt16le :: forall m. MonadEffect m => Int -> PutM m Unit
298−putInt16le = putArrayBuffer <=< encodeInt16le
124+putInt16le = putArrayBuffer <=< Internal.encodeInt16le
300−-- | Serialize a 32-bit big-endian unsigned integer into a new `ArrayBuffer`.
301−encodeUint32be :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
302−encodeUint32be x = do
303− buf <- liftEffect $ AB.empty 4
304− _ <- liftEffect $ DV.setUint32be (DV.whole buf) 0 x
307-- | Append a 32-bit big-endian unsigned integer to the builder.
126-- | Append a 32-bit big-endian unsigned integer to the builder.
308−putUint32be :: forall m. (MonadEffect m) => UInt -> PutM m Unit
127+putUint32be :: forall m. MonadEffect m => UInt -> PutM m Unit
309−putUint32be = putArrayBuffer <=< encodeUint32be
128+putUint32be = putArrayBuffer <=< Internal.encodeUint32be
311−-- | Serialize a 32-bit little-endian unsigned integer into a new `ArrayBuffer`.
312−encodeUint32le :: forall m. (MonadEffect m) => UInt -> m ArrayBuffer
313−encodeUint32le x = do
314− buf <- liftEffect $ AB.empty 4
315− _ <- liftEffect $ DV.setUint32le (DV.whole buf) 0 x
318-- | Append a 32-bit little-endian unsigned integer to the builder.
130-- | Append a 32-bit little-endian unsigned integer to the builder.
319−putUint32le :: forall m. (MonadEffect m) => UInt -> PutM m Unit
131+putUint32le :: forall m. MonadEffect m => UInt -> PutM m Unit
320−putUint32le = putArrayBuffer <=< encodeUint32le
132+putUint32le = putArrayBuffer <=< Internal.encodeUint32le
322−-- | Serialize a 32-bit big-endian two’s-complement signed integer into a new `ArrayBuffer`.
323−encodeInt32be :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
325− buf <- liftEffect $ AB.empty 4
326− _ <- liftEffect $ DV.setInt32be (DV.whole buf) 0 x
329-- | Append a 32-bit big-endian two’s-complement signed integer to the builder.
134-- | Append a 32-bit big-endian two’s-complement signed integer to the builder.
330−putInt32be :: forall m. (MonadEffect m) => Int -> PutM m Unit
135+putInt32be :: forall m. MonadEffect m => Int -> PutM m Unit
331−putInt32be = putArrayBuffer <=< encodeInt32be
136+putInt32be = putArrayBuffer <=< Internal.encodeInt32be
333−-- | Serialize a 32-bit little-endian two’s-complement signed integer into a new `ArrayBuffer`.
334−encodeInt32le :: forall m. (MonadEffect m) => Int -> m ArrayBuffer
336− buf <- liftEffect $ AB.empty 4
337− _ <- liftEffect $ DV.setInt32le (DV.whole buf) 0 x
340-- | Append a 32-bit little-endian two’s-complement signed integer to the builder.
138-- | Append a 32-bit little-endian two’s-complement signed integer to the builder.
341−putInt32le :: forall m. (MonadEffect m) => Int -> PutM m Unit
139+putInt32le :: forall m. MonadEffect m => Int -> PutM m Unit
342−putInt32le = putArrayBuffer <=< encodeInt32le
140+putInt32le = putArrayBuffer <=< Internal.encodeInt32le
344−-- | Serialize a 32-bit big-endian IEEE single-precision float into a new `ArrayBuffer`.
345−encodeFloat32be :: forall m. (MonadEffect m) => Float32 -> m ArrayBuffer
346−encodeFloat32be x = do
347− buf <- liftEffect $ AB.empty 4
348− _ <- liftEffect $ DV.setFloat32be (DV.whole buf) 0 x
351-- | Append a 32-bit big-endian IEEE single-precision float to the builder.
142-- | Append a 32-bit big-endian IEEE single-precision float to the builder.
352−putFloat32be :: forall m. (MonadEffect m) => Float32 -> PutM m Unit
143+putFloat32be :: forall m. MonadEffect m => Float32 -> PutM m Unit
353−putFloat32be = putArrayBuffer <=< encodeFloat32be
144+putFloat32be = putArrayBuffer <=< Internal.encodeFloat32be
355−-- | Serialize a 32-bit little-endian IEEE single-precision float into a new `ArrayBuffer`.
356−encodeFloat32le :: forall m. (MonadEffect m) => Float32 -> m ArrayBuffer
357−encodeFloat32le x = do
358− buf <- liftEffect $ AB.empty 4
359− _ <- liftEffect $ DV.setFloat32le (DV.whole buf) 0 x
362-- | Append a 32-bit little-endian IEEE single-precision float to the builder.
146-- | Append a 32-bit little-endian IEEE single-precision float to the builder.
363−putFloat32le :: forall m. (MonadEffect m) => Float32 -> PutM m Unit
147+putFloat32le :: forall m. MonadEffect m => Float32 -> PutM m Unit
364−putFloat32le = putArrayBuffer <=< encodeFloat32le
148+putFloat32le = putArrayBuffer <=< Internal.encodeFloat32le
366−-- | Serialize a 64-bit big-endian IEEE double-precision float into a new `ArrayBuffer`.
367−encodeFloat64be :: forall m. (MonadEffect m) => Number -> m ArrayBuffer
368−encodeFloat64be x = do
369− buf <- liftEffect $ AB.empty 8
370− _ <- liftEffect $ DV.setFloat64be (DV.whole buf) 0 x
373-- | Append a 64-bit big-endian IEEE double-precision float to the builder.
150-- | Append a 64-bit big-endian IEEE double-precision float to the builder.
374−putFloat64be :: forall m. (MonadEffect m) => Number -> PutM m Unit
151+putFloat64be :: forall m. MonadEffect m => Number -> PutM m Unit
375−putFloat64be = putArrayBuffer <=< encodeFloat64be
152+putFloat64be = putArrayBuffer <=< Internal.encodeFloat64be
377−-- | Serialize a 64-bit little-endian IEEE double-precision float into a new `ArrayBuffer`.
378−encodeFloat64le :: forall m. (MonadEffect m) => Number -> m ArrayBuffer
379−encodeFloat64le x = do
380− buf <- liftEffect $ AB.empty 8
381− _ <- liftEffect $ DV.setFloat64le (DV.whole buf) 0 x
384-- | Append a 64-bit little-endian IEEE double-precision float to the builder.
154-- | Append a 64-bit little-endian IEEE double-precision float to the builder.
385−putFloat64le :: forall m. (MonadEffect m) => Number -> PutM m Unit
155+putFloat64le :: forall m. MonadEffect m => Number -> PutM m Unit
386−putFloat64le = putArrayBuffer <=< encodeFloat64le
156+putFloat64le = putArrayBuffer <=< Internal.encodeFloat64le
389−-- | ## Implementation Details
391−-- | We want our `Builder` to be a data structure with
392−-- | * *O(1)* monoid append
395−-- | Our `Builder` implementation is an unbalanced binary tree.
397−-- | For monoid `append`, what we actually get is *O(1)* when either the
398−-- | left or right tree is a singleton. If that's not true, then in the
399−-- | unlikely worst case `append` might be *O(n)*.
401−-- | `Builder` is optimized what we consider to be normal usage, that is,
402−-- | `snoc`ing singleton elements to the end of the `Builder`.
404−-- | If a Builder is built entirely by `snoc`ing, it will look like a
405−-- | left-only binary tree, a.k.a. a linked list.
417−-- | If two of these `snoc`-built trees are `append`ed, then the new tree
432−-- | This is all similar to
433−-- | [__bytestring-tree-builder__](https://hackage.haskell.org/package/bytestring-tree-builder)
434−-- | , except that the
435−-- | [`Tree`](https://hackage.haskell.org/package/bytestring-tree-builder-0.2.7.3/docs/src/ByteString.TreeBuilder.Tree.html#Tree)
436−-- | structure in __bytestring-tree-builder__ only carries values in its
437−-- | leaves, which is how it achieves *O(1)* appending, at the cost of
438−-- | a higher coefficient time factor on the fold.
440−-- | We hope that this implementation is fairly fast, but we
441−-- | haven't chosen this implementation because it's fast, we've chosen
442−-- | this implementation because it's simple.
443−-- | The only currently existing Purescript libary which does ArrayBuffer
444−-- | serialization is
445−-- | https://pursuit.purescript.org/packages/purescript-arraybuffer-class
446−-- | , and that library is heavily typeclass-based and designed
447−-- | for compatibility with the Haskell cereal library.
448−-- | If someone wants to create a fast Purescript ArrayBuffer serialization
449−-- | library, then they can benchmark against this one to prove that the new
452−-- | One relatively cheap and simple performance improvement for this library would be to
453−-- | remove the Null constructor of `Builder` and instead use Javascript nulls.
455−-- | In the longer term, it might make sense to try to change the Builder so
456−-- | that it works like the
457−-- | https://hackage.haskell.org/package/bytestring/docs/Data-ByteString-Builder.html
459−-- | Here are some benchmarks of different Haskell ByteString builders
460−-- | https://github.com/haskell-perf/strict-bytestring-builders
462−-- | We've tried to design the API for this library with minimal assumptions,
463−-- | so that if we want to change the Builder implementation later then we can.