A decoder that reads binary data and produces either a value or an error.

Internally, it carries an optional raw Bytes.Decode.Decoder (fast path) and a state-passing function (slow path for error reporting).

Run the given decoder on the provided bytes.

First tries the fast path (a single Decode.decode call). If the fast path is unavailable or fails, re-decodes with the slow path to produce a detailed error.

Describes errors that arise while decoding.

Custom errors happen through fail, context tracking happens through inContext.

Always succeed with the given value, consuming no input.

Always fail with the given error.

This decoder has no fast path — using it (even in a branch of andThen) will cause decode to fall back to the slow path for error reporting.

Add context to errors that may occur during decoding.

The fast path is preserved (context only matters on the error path).

Decode one byte as an unsigned integer from 0 to 255.

Decode two bytes as an unsigned integer from 0 to 65535.

Decode four bytes as an unsigned integer from 0 to 4294967295.

Decode one byte as a signed integer from -128 to 127.

Decode two bytes as a signed integer from -32768 to 32767.

Decode four bytes as a signed integer from -2147483648 to 2147483647.

Decode two bytes as a 16-bit float.

Decode four bytes as a 32-bit float.

Decode eight bytes as a 64-bit float.

Decode exactly n bytes as a UTF-8 string.

Decode exactly n bytes.

Transform the value a decoder produces.

Combine what 2 decoders produce.

Combine what 3 decoders produce.

Combine what 4 decoders produce.

Combine what 5 decoders produce.

Decode a value and apply it to the function held by the previous decoder.

import Bytes.Decoder as BD


BD.succeed Record
    |> BD.keep BD.unsignedInt8
    |> BD.keep BD.unsignedInt8
    |> BD.keep BD.unsignedInt8

Run a decoder but discard its result, keeping the previous value.

The ignored decoder must still succeed for the pipeline to succeed.

Skip n bytes, then continue with the given decoder.

Decode one thing, then decode another thing based on the result.

The fast path uses Decode.andThen. If the callback returns a decoder without a fast path (e.g. via fail), the fast decoder signals failure via Decode.fail, causing decode to fall back to the slow path.

Try each decoder in order, returning the first success.

This decoder has no fast path — it always uses the slow path with backtracking. For tag-based dispatch, prefer andThen which preserves the fast path.

Collects all errors on failure for diagnostic purposes.

Caution: oneOf backtracks by byte offset, not by meaning. If two branches consume the same number of bytes but interpret them differently (e.g. unsignedInt32 vs float32), the first branch that successfully reads those bytes wins — even if the value makes no sense for your domain. In general, raw byte sequences are untagged, so oneOf cannot distinguish between alternatives that happen to have the same byte layout. Prefer andThen with an explicit tag byte whenever possible.

Decode exactly count copies of the same decoder into a list.

If the inner decoder has a fast path, repeat preserves it by composing a single Decode.loop decoder.

Represent the next step of a loop: either continue with updated state, or finish with a final value.

Decode in a loop. Each iteration produces either Loop (continue with new state) or Done (finish with a value).

The fast path uses Decode.loop (a tight while loop in the JS kernel). If any iteration's callback returns a decoder without a fast path, the fast decoder signals failure via Decode.fail and decode falls back to the slow path.

An opaque position in the input, obtained via position.

Produce the current byte offset in the input.

This decoder has no fast path — using it will cause decode to fall back to the slow path.

import Bytes.Decoder as BD


BD.decode BD.position (fromList [ 1, 2, 3 ])
--> Ok BD.startOfInput


BD.decode
    (BD.unsignedInt8
        |> BD.andThen (\_ -> BD.position)
    )
    (fromList [ 1, 2, 3 ])
    |> Result.map (\\p -> p == BD.startOfInput)
--> Ok False

The position at the very start of the input (offset 0).

Useful as the relativeTo argument in randomAccess.

Read data at an arbitrary offset, then resume where you left off.

This decoder has no fast path.

As an example, consider data laid out as:

• A byte giving the length of a string
• A byte giving the absolute offset to the string
• Another byte we also need

import Bytes exposing (Bytes)
import Bytes.Decoder as BD exposing (Decoder)
import Bytes.Encode as E


input : Bytes
input =
    [ E.unsignedInt8 5
    , E.unsignedInt8 15
    , E.unsignedInt8 6
    , E.string (String.repeat 12 "\u{0000}")
    , E.string "hello"
    ]
        |> E.sequence
        |> E.encode


stringAtOffset : Decoder c e String
stringAtOffset =
    BD.map2 Tuple.pair BD.unsignedInt8 BD.unsignedInt8
        |> BD.andThen
            (\( len, offset ) ->
                BD.randomAccess
                    { offset = offset, relativeTo = BD.startOfInput }
                    (BD.string len)
            )


BD.decode stringAtOffset input
--> Ok "hello"

Parsing continues at the sequential position after randomAccess returns:

final : Decoder c e { string : String, number : Int }
final =
    BD.succeed (\s n -> { string = s, number = n })
        |> BD.keep stringAtOffset
        |> BD.keep BD.unsignedInt8


BD.decode final input
--> Ok { string = "hello", number = 6 }

Wrap a raw Bytes.Decode.Decoder into a Decoder with error reporting.

This is an escape hatch for advanced users who already have a working Bytes.Decode.Decoder and want to use it within this library's decoder pipeline. You must supply:

• error — the error to report if the inner decoder fails
• byteLength — the exact number of bytes the inner decoder consumes on success
• the raw Bytes.Decode.Decoder to wrap

The recommended approach is to rewrite your decoder using the functions provided by this module — they cover all the functionality of the original Bytes.Decode module while providing error reporting and oneOf branching.

This function is unsafe because the caller is responsible for providing the correct byte width. If the byte length is wrong, the offset tracking in the slow path will be incorrect, leading to corrupt subsequent decoding. This also means it must not be used for variable-length decoders (e.g. decoders that read a length prefix and then consume that many bytes) — only for fixed-width decoders where the byte count is known statically.