Improve decode.one_of API

[ghivert]

I'm currently rewriting my old decoders with the new gleam/dynamic/decode API, and I think it's time now to talk about areas of improvements, before the stdlib bumps to v1.0.0.

decode.one_of

I find decode.one_of a bit weird, because of the nature of decoders. In previous decoding libraries, we could simply write one_of as decode.one_of([decoders]). Now, we're forced to write it as decode.one_of(first_decoder, or: [decoders]). I feel that it can be difficult to understand why we have to put a decoder in the first place, and not in a list like the others. I think we could add a decode.or function instead of the decode.one_of, because it would make more sense, it can be piped easily, and can be used in an easy in different place. When you have a Decoder(a), and you suddenly need to parse a different shape, you don't have to rewrite your existing decoder, but instead pipe it in decode.or.

An example:

// If you have the previous decoder:
pub fn decoder() {
  decode.int
}

// And if you want to add a new case, nowadays, you'd have to rewrite it like:
pub fn decoder() {
  decode.one_of(decode.int, or: [
    decode.float |> decode.then(float.round)
  ])
}

// Which is a "huge" change in the code, while with `or`, it could be simplified as:
pub fn decoder() {
  decode.int
  |> decode.or(decode.float |> decode.then(float.round))
}

I'm not sure it's really the best API or not, but I would find a bit more intuitive, and it avoid to explain why we need to pass a decoder as first argument.

[lpil]

I don't find the justification of it being "weird" very compelling as that term doesn't have any useful meaning. The or API looks nice to me though! I'd be interested in what others think of this.

[ryanmiville]

Would creating a NonEmptyList type be overkill here? It would help the caller understand, and be reused in other packages so there's just one way to create these sort of functions.

Granted, the ergonomics of one_of wouldn't benefit (I personally don't find it awkward to begin with).

[ghivert]

Adding a NonEmptyList type only for one function seems really overkill to me. I think it's better to keep one_of in this case.

[lpil]

Using a non empty list would result in exactly the same API as the existing one_of function where the first is supplied as the first argument and the rest are supplied as the second.

[ryanmiville]

Right, the usage would be the same, but the type would address

I feel that it can be difficult to understand why we have to put a decoder in the first place, and not in a list like the others.

Though I'd be happy with or, or just leaving one_of as is. I think I'm in the minority in that I slightly prefer one_of so I was trying to think of a way to help it be more understandable.

[andho]

Using a non empty list would result in exactly the same API as the existing one_of function where the first is supplied as the first argument and the rest are supplied as the second.

The non empty list makes it explicit that the first is still part of the "one of" list, but makes it more verbose (I like explicit, but not too verbose)

Once I understood one_of it was okay. Maybe I'll have to understand it again after not using it for a bit, when reading someone else's code. If I'm looking at the docs it's fine.

So either API seems fine to me, while or is easier to grok in the wild.

Is there a reason at lease one is required? If it's because of naming aesthetic (name is one_of so it has to be a choice between at least 2 items), then supplying 1 item doesn't make sense either, it has to be at least 2. Or is it to avoid foot guns where no decoder is provided which would result in a decoder that always return an error.

[rob-b]

We would remove one_of if we added or

How would we do the example from the one_of docs with or?

let decoder = decode.one_of(decode.string, or: [
  decode.int |> decode.map(int.to_string),
  decode.float |> decode.map(float.to_string),
])
decode.run(dynamic.from(1000), decoder)
// -> Ok("1000")

Using elm's parser-combinators as prior art, I would think or would be or and one_of would be choice

edit: to be clear I'm suggesting a rename, just pointing out that or + one_of are not 1 for 1 equivalents

[andho]

We would remove one_of if we added or

How would we do the example from the one_of docs with or?

let decoder = decode.one_of(decode.string, or: [
  decode.int |> decode.map(int.to_string),
  decode.float |> decode.map(float.to_string),
])
decode.run(dynamic.from(1000), decoder)
// -> Ok("1000")

Using elm's parser-combinators as prior art, I would think or would be or and one_of would be choice

edit: to be clear I'm suggesting a rename, just pointing out that or + one_of are not 1 for 1 equivalents

The example with or:

let decoder =
  decode.string
  |> decode.or(decode.int |> decode.map(int.to_string))
  |> decode.or(decode.float |> decode.map(float.to_string))
decode.run(dynamic.from(1000), decoder)
// -> Ok("1000")

[lpil]

@rob-b could you give an example of when they are not equivalent please 🙏