Cookie.Decode

Decode cookies into Gren values.

type Decoder a

A decoder for a Cookie header.
type Value a

An opaque decoder for the text of a single cookie into an application value. Pass it to Cookie.create, field, or withDefault.

Use string, int, or bool. Its constructor is private to this module.
type Error
= MissingCookie String
| DuplicateCookie String
| InvalidEncoding String
| InvalidValue String

Errors that can happen when decoding cookies.

  • MissingCookie name means the selected cookie is absent.
  • DuplicateCookie name means the selected name appears more than once.
  • InvalidEncoding name means that cookie's value contains invalid percent escapes or percent-encoded UTF-8.
  • InvalidValue message means a value decoder rejected the text, or fail was called. A value decoder's message is prefixed with the cookie name, as in "visits: Expected an integer, got: many". A message passed to fail has no prefix.
string : Value String

Decode a String value.
int : Value Int

Decode an Int value.
bool : Value Bool

Decode "true" or "false" case-insensitively, and "1" or "0" as True or False, respectively.
field : String -> Value a -> (a -> Decoder b) -> Decoder b

Decode a named cookie and pass the value to the next step.

visitsDecoder : Decode.Decoder String
visitsDecoder =
    Decode.field "session" Decode.string Decode.succeed

The name is matched case-sensitively against parsed cookie names.

The value of the cookie, before decoding, is percent-decoded. Invalid encoding fails with InvalidEncoding.
withDefault : String -> Value a -> a -> (a -> Decoder b) -> Decoder b

Decode a named cookie, using a default value if it is absent.

themeDecoder : Decode.Decoder String
themeDecoder =
    Decode.withDefault "theme" Decode.string "light" Decode.succeed

Only an absent cookie uses the default. Duplicate cookies, invalid encoding, and rejected values still fail, just as they do with field.
succeed : a -> Decoder a

Create a decoder that always succeeds with the given value. Use it to finish a chain of field calls.

sessionDecoder : Decode.Decoder { token : String, visits : Int }
sessionDecoder =
    Decode.field "session" Decode.string <| \token ->
    Decode.field "visits" Decode.int <| \visits ->
        Decode.succeed { token = token, visits = visits }

Decode.decodeString sessionDecoder "session=abc; visits=42"
-- Ok { token = "abc", visits = 42 }
fail : String -> Decoder a

Create a decoder that always fails with InvalidValue and the given message. This message is used as-is, without a cookie-name prefix. Use it to reject a value while chaining field calls.

sessionDecoder : Decode.Decoder { token : String, visits : Int }
sessionDecoder =
    Decode.field "session" Decode.string <| \token ->
    Decode.field "visits" Decode.int <| \visits ->
        if visits < 0 then
            Decode.fail "Visit count cannot be negative"

        else
            Decode.succeed { token = token, visits = visits }

Decode.decodeString sessionDecoder "session=abc; visits=-1"
-- Err (Decode.InvalidValue "Visit count cannot be negative")
decodeString : Decoder a -> String -> Result Error a

Run a decoder on a Cookie header value. Pass only the cookie pairs, such as "session=abc; visits=42", without the Cookie: prefix.
fromRequest : Decoder a -> Request -> Result Error a

Decode cookies from a HttpServer.Request from gren-lang/node.

Decode.fromRequest sessionDecoder request
-- Result Decode.Error { token : String, visits : Int }