decoding 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e42aa2335c51607c8da6110d0bec04cfef6b2af82365e003b51d54db365e091a
-  data.tar.gz: 50d36892d40a7a3ca152125a0265cd7c4ac2f87da78c236f7ca98844f83bd81a
+  metadata.gz: 27eee73e0aa7f430b7fb6aac6aea19c872dd5d825633d1f0e54362668ae355e5
+  data.tar.gz: b6ceb7aa0bd5cda5812949c165a4f8614dd0da97f5e05a8cbbf77cefa3e10e4d
 SHA512:
-  metadata.gz: 561b13185e19d9402fc8b416e8cb851f8dea4eb0bf0ad337151e5e43eb6eb97fe76211b2d85aebbbb44ce7111aa852a1bb61015585dab1af68fc4afe250d055d
-  data.tar.gz: 356c32052eba205c3ff07395d20afd87d5b4c6c564ce50e7727a2bffba6cb1a43f537e1a92ca33bd628ab819ad01ac643ad30f700387f78914d056e9b8246ce7
+  metadata.gz: 8119c1c00072ccbe6393ba6265d8eb5bd18e4f3a6b0c821a66eac6f1a9d52481b4cdf6b7e70656545c08cecbbb365f7736a505b3df25a9bd03c1b2e9ec486e9e
+  data.tar.gz: 5a76a8b7c125c47e2afd5f8a37bd0290ca5e2fb6de03a42cc2dabeeba4121f4601a27bd804e62a088aad8e165e2f85aca7ac8a07f6fc537be3019d9a610baae7

data/.rubocop.yml

@@ -29,6 +29,8 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Exclude:
     - spec/**/*_spec.rb
+    # The RSpec matcher DSL puts a matcher's whole definition inside one block.
+    - lib/decoding/rspec/*.rb
 
 Metrics/MethodLength:
   Max: 17
@@ -53,3 +55,13 @@ RSpec/IdenticalEqualityAssertion:
 
 RSpec/ExampleLength:
   Enabled: false
+
+# The matcher specs deliberately pass literal values to `expect` to assert on
+# the messages the matchers themselves produce.
+RSpec/DescribeClass:
+  Exclude:
+    - spec/matchers/*_spec.rb
+
+RSpec/ExpectActual:
+  Exclude:
+    - spec/matchers/*_spec.rb

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 ## [Unreleased]
 
+## [0.5.0]
+
+* Add a `zone:` argument to the `time` and `unix_time` decoders, for resolving times somewhere other than the system's time zone.
+* Add `decoding/rspec` module with matchers to help with testing custom decoders
+
+## [0.4.0]
+
+* Add `uri` decoder for URI objects and strings that can be parsed as one, available after `require "decoding/decoders/uri"`
+* Add `map_err` decoder for replacing the error message of a failed decoder
+* Add `Decoding.decode!` for decoding a value, raising `Decoding::UnwrapError` when decoding fails
+* Add `lazy` decoder, making recursive decoders possible
+* Add `match` decoder for matching a value against any pattern using `===`
+* Add `enum` decoder for a value that must be one of a fixed set of values
+* Add `optional_field` decoder for a key that may be absent from a hash
+* Add `time` and `date` decoders, available after `require "decoding/decoders/time"` and `require "decoding/decoders/date"`
+* Add `big_decimal` decoder, available after `require "decoding/decoders/big_decimal"`
+* Add `unix_time` decoder for timestamps, alongside the `time` decoder
+* Add `parsed_integer`, `parsed_float` and `parsed_boolean` decoders for reading typed values out of strings
+* Add `Decoding.env` for decoding a single environment variable, available after `require "decoding/env"`
+* Raise `Decoding::UnwrapError` as a `Decoding::Error`
+* Remove the unused `Decoding::Decoders::Index::Err` constant
+* Report the location of errors nested inside a `hash` decoder as a path, like `field` and `array` do, rather than flattening it into the error message.
+* Give the `boolean` decoder its own error message, rather than reporting the failures of the decoders it is built from
+* Use consistent phrasing for the error messages of the `match`, `field`, `array` and `index` decoders
+* Report the failure of the given decoder from the `optional` decoder, rather than also reporting that the value was not `nil`
+* Report the location shared by all failures of an `any` decoder once, instead of repeating it in every collected message
+
 ## [0.3.0]
 
 * Add `Decoding::Data` for creating decodable data classes

data/CLAUDE.md

@@ -19,6 +19,12 @@ Ruby gem for decoding dynamic/external data into known structures. Functional-st
 - Test file: `spec/<module>/<class>_spec.rb`
 - Run with `COVERAGE=true bundle exec rspec`
 
+**Custom matchers** (defined in `spec/support/matchers/`, tested in `spec/matchers/`):
+- `expect(decoder).to decode_value(input).to(value)` - assert what a decoder decodes an input to
+- `expect(decoder).to decode_value(input).failing_with(msg).at(*path)` - assert how it fails, path outermost first
+- `expect(result).to succeed_with(value)` / `expect(result).to fail_with(msg).at(*path)` - assert on a `Result`
+- Expected values compare strictly (`eql?`) unless you pass a matcher, so `1` does not match `1.0`
+
 ## Architecture
 
 **Core concepts:**

data/README.md

@@ -31,7 +31,7 @@ Assume the response body, parsed as JSON, results in a value like this:
   "orderID" => "7EBWXB5",
   "orderDate" => "1595674680",
   "estimatedDeliveryDate" => "1596365935",
-  "deliveryDate" => null,
+  "deliveryDate" => nil,
   "delayed" => false,
   "status" => {
     "orderPlaced" => true,
@@ -54,8 +54,8 @@ time_decoder = D.map(D.string) { Time.at(_1.to_i) }
 order_decoder = D.map(
   D.field("orderID", D.string),
   D.field("orderDate", time_decoder),
-  D.hash(D.string, D.boolean)
-) { Order.new(*args) }
+  D.field("status", D.hash(D.string, D.boolean))
+) { |*args| Order.new(*args) }
 
 Decoding.decode(order_decoder, body)
 # => Decoding::Ok(#<data Order
@@ -84,6 +84,8 @@ You can use the base decoders along with `map` to write more complex decoder. Fo
 time_decoder = D.map(D.string) { Time.at(_1.to_i) }
 ```
 
+(For unix timestamps specifically there is a `unix_time` decoder, described under optional decoders below; the point here is that `map` lets you build one yourself.)
+
 When the shape of the incoming data is unknown, you can try out various decoders in a row to find the first that succeeds using `any`:
 
 ```ruby
@@ -92,6 +94,31 @@ Decoding.decode(string_or_integer, 1) # => Decoding::Ok(1)
 Decoding.decode(string_or_integer, '1') # => Decoding::Ok('1')
 ```
 
+A value that might be absent is decoded with `optional`. It hands the value to the given decoder first, so that decoder can give `nil` a meaning of its own, and only falls back to `nil` when the decoder cannot handle it:
+
+```ruby
+optional_name = D.optional(D.string)
+Decoding.decode(optional_name, "John") # => Decoding::Ok("John")
+Decoding.decode(optional_name, nil) # => Decoding::Ok(nil)
+Decoding.decode(optional_name, 123) # => Decoding::Err("expected String, got Integer")
+```
+
+Note how the failure is the one reported by the given decoder: since you asked for an optional string, being told the value was not `nil` either adds nothing.
+
+Decoders that refer to themselves need `lazy`, which defers building the decoder until there is a value to decode. Without it, building the decoder would recurse endlessly:
+
+```ruby
+def tree
+  D.decode_hash(
+    name: D.field("name", D.string),
+    children: D.field("children", D.array(D.lazy { tree }))
+  )
+end
+
+Decoding.decode(tree, { "name" => "a", "children" => [{ "name" => "b", "children" => [] }] })
+# => Decoding::Ok({ name: "a", children: [{ name: "b", children: [] }] })
+```
+
 You can also base one decoder on a previously decoded value. For example, a payload might contain a version number describing its format. Use `and_then` to decode one value and then construct a new decoder to run against the same input using that value:
 
 ```ruby
@@ -115,6 +142,49 @@ Decoding.decode(multiple_version_decoder, "version" => "2", "fullName" => "Paul"
 
 The return values of decoding are `Decoding::Result` values, which come in `Ok` and `Err` subclasses. These describe how the decoding either succeeded or failed. The `Ok` values contain the decoded result, while the `Err` values always contain a string error message. It is up to you, as a developer, to decide how to deal with unsuccessful decoding.
 
+When you would rather not handle failure explicitly, `decode!` returns the decoded value itself and raises `Decoding::UnwrapError` when decoding fails:
+
+```ruby
+Decoding.decode!(D.string, "foo") # => "foo"
+Decoding.decode!(D.field("name", D.string), { "name" => 123 })
+# raises Decoding::UnwrapError: Error at .name: expected String, got Integer
+```
+
+### Error messages
+
+Decoders that reach into a value -- `field`, `at`, `array`, `index` and `hash` -- record where in the input the error occurred, so a failure deep inside a nested structure still tells you how to find it:
+
+```ruby
+Decoding.decode(D.at("a", "b", D.string), { "a" => { "b" => 1 } })
+# => Decoding::Err("Error at .a.b: expected String, got Integer")
+```
+
+A decoder composed of other decoders reports the failures of the decoders it is built from, which is not always what a caller needs to know:
+
+```ruby
+id = D.any(D.integer, D.map(D.string, &:to_i))
+Decoding.decode(id, true)
+# => Decoding::Err("None of the decoders matched:\n  - expected Integer, got TrueClass\n  - expected String, got TrueClass")
+```
+
+Use `map_err` to give such a decoder a single error message of its own. The block receives the original message and the value being decoded, and returns the message to use instead:
+
+```ruby
+id = D.map_err(D.any(D.integer, D.map(D.string, &:to_i))) do |_message, value|
+  "expected an ID, got #{value.inspect}"
+end
+
+Decoding.decode(id, true)
+# => Decoding::Err("expected an ID, got true")
+```
+
+Replacing the message does not discard where the error occurred, so a decoder built this way still composes:
+
+```ruby
+Decoding.decode(D.field("id", id), { "id" => true })
+# => Decoding::Err("Error at .id: expected an ID, got true")
+```
+
 ## Available decoders
 
 The following decoders are included:
@@ -129,23 +199,180 @@ The following decoders are included:
     * `false`
     * `boolean`
     * `symbol`
+    * `parsed_integer`
+    * `parsed_float`
+    * `parsed_boolean`
     * `regexp`
+    * `match`
+    * `enum`
 * Utility decoders
     * `succeed`
     * `fail`
     * `original`
     * `map`
+    * `map_err`
     * `decode_hash`
     * `and_then`
+    * `lazy`
 * Compound decoders
     * `any`
     * `optional`
     * `field`
+    * `optional_field`
     * `array`
     * `index`
     * `hash`
     * `at`
 
+### A note on `include`
+
+Refer to the decoders through a short alias, as the examples above do:
+
+```ruby
+D = Decoding::Decoders
+```
+
+Do not `include Decoding::Decoders`. Several decoders are named after methods every object already has: `hash` would override `Object#hash`, leaving instances unusable as hash keys, and `fail` would shadow `Kernel#fail`, so raising an exception would silently build a decoder instead. In specs, `match` would shadow RSpec's `match` matcher. The decoders `nil`, `true` and `false` are unreachable as bare words in any case, since those are keywords.
+
+### Optional decoders
+
+Some decoders depend on parts of the standard library that not every application needs, so they are not loaded by default. Require them explicitly to make them available:
+
+* `uri` -- decodes a `URI` object, or a string that can be parsed as one:
+
+```ruby
+require "decoding/decoders/uri"
+
+Decoding.decode(D.uri, "https://example.com") # => Decoding::Ok(URI("https://example.com"))
+Decoding.decode(D.uri, 123) # => Decoding::Err("expected a URI, got 123")
+```
+
+* `time` and `date` -- decode a `Time` or `Date` object, or a string in a given format. The format is either the name of a standard format or a `strptime` pattern:
+
+```ruby
+require "decoding/decoders/time"
+require "decoding/decoders/date"
+
+Decoding.decode(D.time(:iso8601), "2020-01-01T10:00:00Z") # => Decoding::Ok(2020-01-01 10:00:00 UTC)
+Decoding.decode(D.date("%Y|%m"), "2020|01") # => Decoding::Ok(#<Date: 2020-01-01>)
+Decoding.decode(D.date(:iso8601), "3rd Feb") # => Decoding::Err("expected a date in iso8601 format, got \"3rd Feb\"")
+```
+
+`time` accepts `:iso8601`, `:xmlschema`, `:rfc2822`, `:rfc822`, `:httpdate` and `:parse`; `date` also accepts `:rfc3339` and `:jisx0301`. The same file provides `unix_time`, which reads a number, or a string describing one, as a number of seconds since the epoch:
+
+```ruby
+Decoding.decode(D.unix_time, 1_595_674_680) # => Decoding::Ok(2020-07-25 10:58:00 UTC)
+Decoding.decode(D.unix_time, "1595674680") # => Decoding::Ok(2020-07-25 10:58:00 UTC)
+Decoding.decode(D.unix_time(:milliseconds), 1_595_674_680_123) # => Decoding::Ok(2020-07-25 10:58:00.123 UTC)
+```
+
+A timestamp read in the wrong unit is not an error but a wildly different point in time, so a source reporting milliseconds has to say so. There is deliberately no default: `:parse` is lenient and fills in whatever the input leaves out from the current time, so it has to be asked for by name.
+
+Both `time` and `unix_time` resolve times through `Time` itself, and so in the system's time zone. That is rarely the zone a Rails application means: its containers usually run UTC while the application runs somewhere else, and taking `to_date` of the two answers differs by a day for a late-evening timestamp. Pass anything that answers the format you name as `zone:` to decide it yourself:
+
+```ruby
+Decoding.decode(D.time(:parse, zone: Time.zone), "2020-01-01 10:00:00")
+# => Decoding::Ok(2020-01-01 10:00:00 +0100)
+Decoding.decode(D.map(D.unix_time(zone: Time.zone), &:to_date), 1_710_113_400)
+# => Decoding::Ok(#<Date: 2024-03-11>)
+```
+
+An `ActiveSupport::TimeZone` answers only `iso8601`, `rfc3339` and `parse` of the format names above, plus `strptime` patterns, so a zone that cannot parse the format you asked for is refused when the decoder is built:
+
+```ruby
+D.time(:httpdate, zone: Time.zone)
+# raises ArgumentError: cannot decode a time in httpdate format: the given zone does not respond to httpdate
+```
+
+Note `ActiveSupport::TimeZone#parse` answers a value it cannot parse with `nil` rather than by raising, unlike every method of `Time`. Both are read as a failure to decode.
+
+* `big_decimal` -- decode a `BigDecimal` object, or a number or string describing one. Only finite numbers are accepted:
+
+```ruby
+require "decoding/decoders/big_decimal"
+
+Decoding.decode(D.big_decimal, "1.23") # => Decoding::Ok(BigDecimal("1.23"))
+Decoding.decode(D.big_decimal, 42) # => Decoding::Ok(BigDecimal("42"))
+Decoding.decode(D.big_decimal, "abc") # => Decoding::Err("expected a decimal number, got \"abc\"")
+```
+
+This decoder needs the `bigdecimal` gem, which is no longer one of Ruby's default gems. Add `gem "bigdecimal"` to your Gemfile to use it.
+
+## Reading configuration from the environment
+
+Environment variables are always strings, and an application that is misconfigured should refuse to boot rather than fail later. `Decoding.env` reads a single variable, decodes it, and raises when it is missing or its value does not make sense:
+
+```ruby
+require "decoding/env"
+
+Decoding.env("DATABASE_URL")                  # => "postgres://localhost/app"
+Decoding.env("PORT", :integer)                # => 8080
+Decoding.env("DEBUG", :boolean)               # => true
+Decoding.env("PORT", :integer, default: 3000) # => 3000 when PORT is not set
+```
+
+The named types are `:string` (the default), `:symbol`, `:integer`, `:float` and `:boolean`. Any decoder is accepted too, which is how you read the types that live behind their own require:
+
+```ruby
+require "decoding/decoders/uri"
+
+Decoding.env("DATABASE_URL", D.uri) # => #<URI::Generic postgres://localhost/app>
+```
+
+Failures name the variable, so the reason an application would not start is clear:
+
+```
+Decoding::UnwrapError: ENV["PORT"] is not set
+Decoding::UnwrapError: ENV["PORT"]: expected an integer, got "abc"
+```
+
+A variable set to an empty string counts as set, so it still has to decode rather than quietly falling back to the default. To allow a variable to be absent without a default, give it a decoder that accepts `nil`:
+
+```ruby
+Decoding.env("SENTRY_DSN", D.optional(D.string)) # => nil when not set
+```
+
+Pass `from:` to read from somewhere other than `ENV`, which is useful in tests.
+
+## Testing your own decoders
+
+The matchers this gem tests itself with are available to applications that write decoders of their own. They need `rspec-expectations`, which is not a dependency of this gem, so require them from your spec helper:
+
+```ruby
+# spec/spec_helper.rb
+require "decoding/rspec"
+```
+
+`decode_value` describes a decoder, running it for you, so an example says what a decoder does rather than how to call it:
+
+```ruby
+expect(my_decoder).to decode_value({ "name" => "John" }).to({ name: "John" })
+expect(my_decoder).to decode_value({}).failing_with(%(expected Hash with key "name"))
+expect(my_decoder).to decode_value(nil)      # decodes; the value is not asserted
+expect(my_decoder).not_to decode_value(nil)  # fails to decode
+```
+
+An error nested in a structure is asserted with its location, outermost segment first, rather than by matching the rendered `Error at .` prefix:
+
+```ruby
+expect(D.field("a", D.field("b", D.string)))
+  .to decode_value({ "a" => { "b" => 1 } })
+  .failing_with("expected String, got Integer").at("a", "b")
+```
+
+`succeed_with` and `fail_with` describe a result you already have, for when making the call is part of what the example tests:
+
+```ruby
+expect(Decoding.decode(my_decoder, input)).to succeed_with({ name: "John" })
+expect(Decoding.decode(my_decoder, input)).to fail_with("expected String, got Integer").at("name")
+```
+
+Expected values are compared strictly, so `1` does not match `1.0` and a decoder answering with the wrong type cannot pass. Pass a matcher where that is too strict:
+
+```ruby
+expect(D.unix_time).to decode_value("1595674680.5").to(an_object_having_attributes(usec: 500_000))
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/decoding/decoders/any.rb

@@ -31,7 +31,11 @@ module Decoding
 
           failures << result.unwrap_err(nil)
         end
-        err(failure("None of the decoders matched:\n#{failures.map { "  - #{_1}" }.join("\n")}"))
+        err(
+          failures.first.combine(failures.drop(1)) do |messages|
+            "None of the decoders matched:\n#{messages.map { "  - #{_1}" }.join("\n")}"
+          end
+        )
       end
     end
   end

data/lib/decoding/decoders/array.rb

@@ -24,7 +24,7 @@ module Decoding
             .map { |v, i| @decoder.call(v).map_err { _1.push(i) } }
             .then { all _1 }
         else
-          err(failure("expected an Array, got: #{value.class}"))
+          err(failure("expected Array, got #{value.class}"))
         end
       end
     end

data/lib/decoding/decoders/big_decimal.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Decoding
+  # Decoders are composable functions for deconstructing unknown input values
+  # into known output values.
+  module Decoders
+    module_function
+
+    # Decode a `BigDecimal` object, or a number or string describing one.
+    #
+    # Only finite numbers are accepted: `NaN` and `Infinity` are errors, as a
+    # decimal is usually reached for when a value has to be exact.
+    #
+    # Note this decoder needs the `bigdecimal` gem, which is no longer part of
+    # Ruby's default gems. Add it to your Gemfile to use this decoder.
+    #
+    # @example
+    #   decode(big_decimal, "1.23") # => Decoding::Ok(BigDecimal("1.23"))
+    #   decode(big_decimal, 42) # => Decoding::Ok(BigDecimal("42"))
+    #   decode(big_decimal, "abc")
+    #   # => Decoding::Err(%(expected a decimal number, got "abc"))
+    # @return [Decoding::Decoder<BigDecimal>]
+    # @see Decoding::Decoders::MapErr
+    def big_decimal
+      Decoders.map_err(
+        Decoders.and_then(
+          Decoders.any(
+            Decoders.match(::BigDecimal),
+            Decoders.map(Decoders.any(Decoders.integer, Decoders.float, Decoders.string)) { BigDecimal(_1) }
+          )
+        ) { |number| number.finite? ? Decoders.succeed(number) : Decoders.fail("not a finite number") }
+      ) { |_message, value| "expected a decimal number, got #{value.inspect}" }
+    end
+  end
+end

data/lib/decoding/decoders/date.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Decoding
+  # Decoders are composable functions for deconstructing unknown input values
+  # into known output values.
+  module Decoders
+    # The standard formats {Decoding::Decoders.date} can parse, each named after
+    # the `Date` method that parses it.
+    DATE_FORMATS = %i[iso8601 xmlschema rfc2822 rfc822 rfc3339 httpdate jisx0301 parse].freeze
+
+    module_function
+
+    # Decode a `Date` object, or a string describing a date in a given format.
+    #
+    # The format is either the name of one of {DATE_FORMATS}, or a string with a
+    # `strptime` pattern. Note that the `:parse` format is lenient: it fills in
+    # any components the input value leaves out from the current date.
+    #
+    # @example
+    #   decode(date(:iso8601), "2020-01-01")
+    #   # => Decoding::Ok(#<Date: 2020-01-01>)
+    #   decode(date("%Y|%m"), "nope")
+    #   # => Decoding::Err("expected a date matching \"%Y|%m\", got \"nope\"")
+    # @param format [Symbol, String]
+    # @raise [ArgumentError] when the format is not a known name or a pattern.
+    #   This is raised when the decoder is built, not when it is used.
+    # @return [Decoding::Decoder<Date>]
+    # @see Decoding::Decoders::MapErr
+    def date(format)
+      parse, description = date_format(format)
+      Decoders.map_err(
+        Decoders.any(
+          Decoders.match(::Date),
+          Decoders.map(Decoders.string) { parse.call(_1) }
+        )
+      ) { |_message, value| "expected #{description}, got #{value.inspect}" }
+    end
+
+    # @private
+    def date_format(format)
+      case format
+      when ::String
+        [->(str) { ::Date.strptime(str, format) }, "a date matching #{format.inspect}"]
+      when ::Symbol
+        raise ArgumentError, "unknown date format: #{format.inspect}" unless DATE_FORMATS.include?(format)
+
+        [->(str) { ::Date.public_send(format, str) }, format == :parse ? "a date" : "a date in #{format} format"]
+      else
+        raise ArgumentError, "expected a date format name or a strptime pattern, got #{format.inspect}"
+      end
+    end
+
+    private_class_method :date_format
+  end
+end

data/lib/decoding/decoders/enum.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "../decoder"
+
+module Decoding
+  module Decoders
+    # A decoder for a value that must be one of a fixed set of values.
+    #
+    # Values are compared for equality, not with the `===` operator the {Match}
+    # decoder uses, so the values are read as themselves rather than as
+    # patterns.
+    #
+    # @see Decoding::Decoders.enum
+    class Enum < Decoder
+      # @overload initialize(value, *values)
+      #   @param value [Object]
+      #   @param values [Object]
+      # @overload initialize(values)
+      #   @param values [Array<Object>] the values as a single array
+      # @raise [ArgumentError] when no values are given, or one is repeated.
+      def initialize(value, *values)
+        @values = collect(value, values)
+        super()
+      end
+
+      # @param value [Object]
+      # @return [Decoding::Result<Object>]
+      def call(value)
+        return ok(value) if @values.include?(value)
+
+        err(failure("expected one of #{@values.map(&:inspect).join(", ")}, got #{value.inspect}"))
+      end
+
+      private
+
+      def collect(value, values)
+        values = (values.empty? && value.is_a?(::Array) ? value.dup : [value, *values]).freeze
+        raise ArgumentError, "expected at least one value to decode" if values.empty?
+
+        duplicates = values.tally.select { |_, count| count > 1 }.keys
+        raise ArgumentError, "duplicate values: #{duplicates.map(&:inspect).join(", ")}" if duplicates.any?
+
+        values
+      end
+    end
+  end
+end

data/lib/decoding/decoders/field.rb

@@ -23,10 +23,10 @@ module Decoding
           if value.key?(@key)
             @decoder.call(value.fetch(@key)).map_err { _1.push(@key) }
           else
-            err(failure("expected a Hash with key #{@key}"))
+            err(failure("expected Hash with key #{@key.inspect}"))
           end
         else
-          err(failure("expected a Hash, got: #{value.inspect}"))
+          err(failure("expected Hash, got #{value.class}"))
         end
       end
     end

data/lib/decoding/decoders/hash.rb

@@ -26,11 +26,11 @@ module Decoding
             [
               @key_decoder
                 .call(k)
-                .map_err { |e| failure("error decoding key #{k.inspect}: #{e}") },
+                .map_err { _1.map { |msg| "invalid key: #{msg}" }.push(k) },
 
               @value_decoder
                 .call(v)
-                .map_err { |e| failure("error decoding value for key #{k.inspect}: #{e}") }
+                .map_err { _1.push(k) }
             ]
           )
         end

data/lib/decoding/decoders/index.rb

@@ -9,9 +9,6 @@ module Decoding
     #
     # @see Decoding::Decoders.index
     class Index < Decoder
-      # @private
-      Err = Result.err("error decoding array: index is out of bounds")
-
       # @param index [Integer]
       # @param decoder [Decoding::Decoder<Object>]
       def initialize(index, decoder)
@@ -23,7 +20,7 @@ module Decoding
       # @param value [Object]
       # @return [Decoding::Decoder<Object>]
       def call(value)
-        return err(failure("expected an Array, got: #{value.class}")) unless value.is_a?(::Array)
+        return err(failure("expected Array, got #{value.class}")) unless value.is_a?(::Array)
 
         @decoder
           .call(value.fetch(@index))

data/lib/decoding/decoders/lazy.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../decoder"
+
+module Decoding
+  module Decoders
+    # A decoder that builds the decoder it delegates to on first use, rather
+    # than when it is created.
+    #
+    # This is what makes recursive decoders possible: a decoder for a tree can
+    # refer to itself, since the reference is only resolved once there is a
+    # value to decode.
+    #
+    # @see Decoding::Decoders.lazy
+    class Lazy < Decoder
+      # @yieldreturn [Decoding::Decoder<a>]
+      def initialize(&block)
+        @block = block
+        super()
+      end
+
+      # @param value [Object]
+      # @return [Decoding::Result<a>]
+      def call(value) = decoder.call(value)
+
+      private
+
+      def decoder = @decoder ||= @block.call.to_decoder
+    end
+  end
+end

data/lib/decoding/decoders/map_err.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../decoder"
+
+module Decoding
+  module Decoders
+    # A decoder that replaces the error message of a decoder that failed,
+    # leaving successful results untouched.
+    #
+    # @see Decoding::Decoders.map_err
+    class MapErr < Decoder
+      # @param decoder [Decoding::Decoder<a>]
+      # @yieldparam msg [String]
+      # @yieldparam value [Object]
+      # @yieldreturn [String]
+      def initialize(decoder, &block)
+        @decoder = decoder.to_decoder
+        @block = block
+        super()
+      end
+
+      # @param value [Object]
+      # @return [Decoding::Result<a>]
+      def call(value)
+        @decoder.call(value).map_err { |f| f.map { @block.call(_1, value) } }
+      rescue StandardError => e
+        err(failure("error in map_err block: #{e.message}"))
+      end
+    end
+  end
+end

data/lib/decoding/decoders/match.rb

@@ -21,7 +21,7 @@ module Decoding
         elsif @pattern.is_a?(Class)
           err(failure("expected #{@pattern}, got #{value.class}"))
         else
-          err(failure("expected value matching #{@pattern.inspect}, got: #{value.inspect}"))
+          err(failure("expected value matching #{@pattern.inspect}, got #{value.inspect}"))
         end
       end
     end