decoding 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0af816a4ee858fb01b7affa44921ddb05b38199a2fbdee33f9439342d8c5dee7
-  data.tar.gz: 18511340412ca51970844209ed9d878a2f46b32ffec15f1c9862c97a540c8921
+  metadata.gz: 3dcd003beb1f65e74c31189b632c9c290d636a20467f5fed1a8c382d1aff634b
+  data.tar.gz: 338652cc9d8ea559a31fc9b14adc14a83cdc10c5730a175a1fa3670b87435b3d
 SHA512:
-  metadata.gz: 044227d25ff8af0830443a267b86455de69ba14c72fa37bed1b5c84080d5f1156aeb533cceb46d5e8cce7b57a6d2a55a85729fb652b36bb747dc6b9f704ef6ef
-  data.tar.gz: f957565332b96ca5fa607fb12ecebfc0bc3379beb6aa154760b70f14f92f59b4c8fbb39e235621e020473f49d68e20fe7909c8a0f6bcef1e091cd7d6f02b6a99
+  metadata.gz: 1a20f3f88d3970063dd6b3f8890ee8f0646df418e0c157fffe3081f6de6c2c3b7718cd685335c1b7f108e21f110d5823be6bdab3e37a222c2d6b4a728bcb820f
+  data.tar.gz: 31edcf5c7f5721d93308269883d271b1cd1336738a1013c18c5d21e071dddfd3de855fb3091b5d2426ddc1e57f19baca471051cbffdddf2cc47e7b157120bd1e

data/.rubocop.yml

@@ -25,13 +25,21 @@ Metrics/ModuleLength:
 
 Metrics/AbcSize:
   Max: 18
+  Exclude:
+    # The benchmarks build test data in long methods.
+    - benchmark/support/*.rb
 
 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
+  Exclude:
+    # The benchmarks build test data in long methods.
+    - benchmark/support/*.rb
 
 Style/SignalException:
   Enabled: false
@@ -53,3 +61,23 @@ 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
+
+# The benchmarks print aligned tables, where plain format strings next to each
+# other read better than annotated ones.
+Style/FormatStringToken:
+  Exclude:
+    - benchmark/**/*.rb
+
+Style/RedundantFormat:
+  Exclude:
+    - benchmark/**/*.rb

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.6.0]
+
+* Decode arrays, hashes and multi-field decoders (such as `decode_hash` and `Decoding::Data`) in linear rather than quadratic time. Decoding 1,600 records is about 29 times faster.
+* Decode valid input to `boolean`, `big_decimal`, `time`, `date`, `uri` and `unix_time` without first trying, and failing, a decoder for another type of input. Strings and numbers decode up to 3 times faster; values that are already a `Time`, `Date` or `URI` are now checked last and take a little longer.
+* Stop decoding an array, hash or `map` at the first failure, as only that one is reported. A document whose first record is invalid fails about 90 times faster. Items after the failure are no longer decoded, so blocks given to `map` for them no longer run.
+* Accept a block in `Result.all` to map each item to a result, stopping at the first `Err`
+* Make `optional` remember when its decoder has failed to decode `nil`, and decode `nil` without asking it again. A `nil` now takes about 0.3 µs instead of up to 5 µs. A decoder that does decode `nil`, such as `optional(succeed(5))`, is still asked every time.
+
+## [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"`

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

@@ -268,6 +268,24 @@ Decoding.decode(D.unix_time(:milliseconds), 1_595_674_680_123) # => Decoding::Ok
 
 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
@@ -316,6 +334,45 @@ 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/Rakefile

@@ -12,3 +12,15 @@ RuboCop::RakeTask.new
 YARD::Rake::YardocTask.new
 
 task default: %i[spec rubocop yard]
+
+BENCHMARKS = %w[realistic scaling invalid micro memory].freeze
+
+namespace :bench do
+  BENCHMARKS.each do |name|
+    desc "Run benchmark/#{name}.rb"
+    task(name) { ruby "benchmark/#{name}.rb" }
+  end
+end
+
+desc "Run all benchmarks (see benchmark/README.md)"
+task bench: BENCHMARKS.map { "bench:#{_1}" }

data/lib/decoding/decoders/array.rb

@@ -19,10 +19,7 @@ module Decoding
       # @return [Decoding::Result<a>]
       def call(value)
         if value.is_a?(::Array)
-          value
-            .each_with_index
-            .map { |v, i| @decoder.call(v).map_err { _1.push(i) } }
-            .then { all _1 }
+          all(value.each_index) { |i| @decoder.call(value[i]).map_err { _1.push(i) } }
         else
           err(failure("expected Array, got #{value.class}"))
         end

data/lib/decoding/decoders/big_decimal.rb

@@ -6,6 +6,12 @@ module Decoding
   # Decoders are composable functions for deconstructing unknown input values
   # into known output values.
   module Decoders
+    # Matches the values {big_decimal} converts, in one check rather than
+    # trying a decoder for each type and discarding their failures.
+    DECIMAL_SOURCES = [::BigDecimal, ::Integer, ::Float, ::String].freeze
+    DECIMAL_SOURCE = ->(value) { DECIMAL_SOURCES.any? { _1 === value } }
+    private_constant :DECIMAL_SOURCES, :DECIMAL_SOURCE
+
     module_function
 
     # Decode a `BigDecimal` object, or a number or string describing one.
@@ -25,12 +31,9 @@ module Decoding
     # @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") }
+        Decoders.map(Decoders.match(DECIMAL_SOURCE)) do |value|
+          BigDecimal(value).tap { |number| raise ArgumentError, "not a finite number" unless number.finite? }
+        end
       ) { |_message, value| "expected a decimal number, got #{value.inspect}" }
     end
   end

data/lib/decoding/decoders/date.rb

@@ -32,8 +32,8 @@ module Decoding
       parse, description = date_format(format)
       Decoders.map_err(
         Decoders.any(
-          Decoders.match(::Date),
-          Decoders.map(Decoders.string) { parse.call(_1) }
+          Decoders.map(Decoders.string) { parse.call(_1) },
+          Decoders.match(::Date)
         )
       ) { |_message, value| "expected #{description}, got #{value.inspect}" }
     end

data/lib/decoding/decoders/hash.rb

@@ -21,20 +21,20 @@ module Decoding
       def call(value)
         return err(failure("expected Hash, got #{value.class}")) unless value.is_a?(::Hash)
 
-        key_value_pairs = value.map do |k, v|
-          all(
-            [
-              @key_decoder
-                .call(k)
-                .map_err { _1.map { |msg| "invalid key: #{msg}" }.push(k) },
+        all(value) { |k, v| decode_entry(k, v) }.map(&:to_h)
+      end
+
+      private
 
-              @value_decoder
-                .call(v)
-                .map_err { _1.push(k) }
-            ]
-          )
-        end
-        all(key_value_pairs).map(&:to_h)
+      # Decode a single key and value into a pair, leaving the value alone
+      # when the key cannot be decoded.
+      def decode_entry(key, value)
+        @key_decoder
+          .call(key)
+          .map_err { _1.map { |msg| "invalid key: #{msg}" }.push(key) }
+          .and_then do |decoded_key|
+            @value_decoder.call(value).map_err { _1.push(key) }.map { [decoded_key, _1] }
+          end
       end
     end
   end

data/lib/decoding/decoders/map.rb

@@ -22,7 +22,7 @@ module Decoding
       # @return [Decoding::Result<b>]
       def call(value)
         Result
-          .all(@decoders.map { _1.call(value) })
+          .all(@decoders) { _1.call(value) }
           .map { @block.call(*_1) }
       rescue StandardError => e
         err(failure("error in map block: #{e.message}"))

data/lib/decoding/decoders/optional.rb

@@ -11,22 +11,30 @@ module Decoding
     # meaning of its own. Only when it fails to do so does this decoder treat
     # `nil` as an absent value.
     #
+    # Most decoders cannot decode `nil`, and building the failure that says so
+    # costs more than decoding most values. Since a decoder gives the same
+    # result for the same input, this decoder remembers when the given decoder
+    # has failed to decode `nil`, and stops asking it about `nil` from then on.
+    #
     # @see Decoding::Decoders.optional
     class Optional < Decoder
       # @param decoder [Decoding::Decoder<a>]
       def initialize(decoder)
         @decoder = decoder.to_decoder
+        @fails_on_nil = false
         super()
       end
 
       # @param value [Object]
       # @return [Decoding::Result<a, nil>]
       def call(value)
+        return ok(nil) if value.nil? && @fails_on_nil
+
         result = @decoder.call(value)
-        return result if result.ok?
-        return ok(nil) if value.nil?
+        return result if result.ok? || !value.nil?
 
-        result
+        @fails_on_nil = true
+        ok(nil)
       end
     end
   end

data/lib/decoding/decoders/time.rb

@@ -10,6 +10,10 @@ module Decoding
     # the `Time` method that parses it.
     TIME_FORMATS = %i[iso8601 xmlschema rfc2822 rfc822 httpdate parse].freeze
 
+    # Matches the numbers {Decoding::Decoders.unix_time} reads as a timestamp.
+    TIMESTAMP_NUMBER = ->(value) { value.is_a?(::Integer) || value.is_a?(::Float) }
+    private_constant :TIMESTAMP_NUMBER
+
     # The units {Decoding::Decoders.unix_time} can read a timestamp in, mapped
     # to the number of them that make up a second.
     UNIX_TIME_UNITS = { seconds: 1, milliseconds: 1000 }.freeze
@@ -22,35 +26,50 @@ module Decoding
     # `strptime` pattern. Note that the `:parse` format is lenient: it fills in
     # any components the input value leaves out from the current time.
     #
+    # Times are resolved by `Time` itself, and so in the system's time zone,
+    # unless another zone is given. Anything answering the format you name will
+    # do: an `ActiveSupport::TimeZone` resolves in the application's zone, which
+    # is rarely the system's, but note it answers only `iso8601`, `rfc3339` and
+    # `parse` of the names above.
+    #
     # @example
     #   decode(time(:iso8601), "2020-01-01T10:00:00Z")
     #   # => Decoding::Ok(2020-01-01 10:00:00 UTC)
     #   decode(time("%Y|%m"), "nope")
     #   # => Decoding::Err("expected a time matching \"%Y|%m\", got \"nope\"")
+    #   decode(time(:parse, zone: Time.zone), "2020-01-01 10:00:00")
+    #   # => Decoding::Ok(2020-01-01 10:00:00 +0100)
     # @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.
+    # @param zone [Object] anything answering the format you name, such as
+    #   `Time` or an `ActiveSupport::TimeZone`.
+    # @raise [ArgumentError] when the format is not a known name or a pattern,
+    #   or the zone cannot parse it. This is raised when the decoder is built,
+    #   not when it is used.
     # @return [Decoding::Decoder<Time>]
     # @see Decoding::Decoders::MapErr
-    def time(format)
-      parse, description = time_format(format)
+    def time(format, zone: ::Time)
+      parse, description = time_format(format, zone)
       Decoders.map_err(
         Decoders.any(
-          Decoders.match(::Time),
-          Decoders.map(Decoders.string) { parse.call(_1) }
+          parsed_by(parse),
+          Decoders.match(::Time)
         )
       ) { |_message, value| "expected #{description}, got #{value.inspect}" }
     end
 
     # @private
-    def time_format(format)
+    def time_format(format, zone)
       case format
       when ::String
-        [->(str) { ::Time.strptime(str, format) }, "a time matching #{format.inspect}"]
+        description = "a time matching #{format.inspect}"
+        require_parser(zone, :strptime, description)
+        [->(str) { zone.strptime(str, format) }, description]
       when ::Symbol
         raise ArgumentError, "unknown time format: #{format.inspect}" unless TIME_FORMATS.include?(format)
 
-        [->(str) { ::Time.public_send(format, str) }, format == :parse ? "a time" : "a time in #{format} format"]
+        description = format == :parse ? "a time" : "a time in #{format} format"
+        require_parser(zone, format, description)
+        [->(str) { zone.public_send(format, str) }, description]
       else
         raise ArgumentError, "expected a time format name or a strptime pattern, got #{format.inspect}"
       end
@@ -63,29 +82,66 @@ module Decoding
     # error but a wildly different point in time, so a source that reports
     # milliseconds has to say so.
     #
+    # A timestamp names a point in time rather than a local one, so the zone
+    # only decides how the value describes itself afterwards -- which matters as
+    # soon as anything derives a date from it.
+    #
     # @example
     #   decode(unix_time, 1_595_674_680) # => Decoding::Ok(2020-07-25 10:58:00 UTC)
     #   decode(unix_time(:milliseconds), 1_595_674_680_123)
     #   # => Decoding::Ok(2020-07-25 10:58:00.123 UTC)
     # @param unit [Symbol] one of the keys of {UNIX_TIME_UNITS}.
-    # @raise [ArgumentError] when the unit is not a known one. This is raised
-    #   when the decoder is built, not when it is used.
+    # @param zone [Object] anything answering `at`, such as `Time` or an
+    #   `ActiveSupport::TimeZone`.
+    # @raise [ArgumentError] when the unit is not a known one, or the zone
+    #   cannot read a timestamp. This is raised when the decoder is built, not
+    #   when it is used.
     # @return [Decoding::Decoder<Time>]
     # @see Decoding::Decoders::MapErr
-    def unix_time(unit = :seconds)
+    def unix_time(unit = :seconds, zone: ::Time)
       raise ArgumentError, "unknown unit: #{unit.inspect}" unless UNIX_TIME_UNITS.key?(unit)
 
+      require_parser(zone, :at, "a unix timestamp")
       per_second = UNIX_TIME_UNITS.fetch(unit)
+      # Cheapest checks first, so the most common inputs fail the fewest
+      # decoders on their way to the one that matches.
       Decoders.map_err(
         Decoders.any(
+          timestamp_in(Decoders.match(TIMESTAMP_NUMBER), zone, per_second),
           Decoders.match(::Time),
-          Decoders.map(
-            Decoders.any(Decoders.integer, Decoders.float, Decoders.parsed_integer, Decoders.parsed_float)
-          ) { ::Time.at(per_second == 1 ? _1 : _1 / Rational(per_second)) }
+          timestamp_in(Decoders.any(Decoders.parsed_integer, Decoders.parsed_float), zone, per_second)
         )
       ) { |_message, value| "expected a unix timestamp, got #{value.inspect}" }
     end
 
-    private_class_method :time_format
+    # Decode the number given by `decoder` as a point in time.
+    #
+    # @private
+    def timestamp_in(decoder, zone, per_second)
+      Decoders.map(decoder) { zone.at(per_second == 1 ? _1 : _1 / Rational(per_second)) }
+    end
+
+    # Decode a string with the given parser, treating a nil answer as a failure.
+    #
+    # Every method of `Time` raises for a value it cannot parse, but
+    # `ActiveSupport::TimeZone#parse` answers with nil instead, which would
+    # otherwise decode as a successful nil.
+    #
+    # @private
+    def parsed_by(parse)
+      Decoders.map(Decoders.string) { parse.call(_1) || raise(ArgumentError, "parsed to nothing") }
+    end
+
+    # Refuse a zone that cannot answer the parsing this decoder will ask of it,
+    # while the decoder is being built rather than once it is decoding.
+    #
+    # @private
+    def require_parser(zone, method, description)
+      return if zone.respond_to?(method)
+
+      raise ArgumentError, "cannot decode #{description}: the given zone does not respond to #{method}"
+    end
+
+    private_class_method :time_format, :parsed_by, :timestamp_in, :require_parser
   end
 end

data/lib/decoding/decoders/uri.rb

@@ -18,8 +18,8 @@ module Decoding
     def uri
       Decoders.map_err(
         Decoders.any(
-          Decoders::Match.new(::URI::Generic),
-          Decoders.map(Decoders.string) { ::URI.parse(_1) }
+          Decoders.map(Decoders.string) { ::URI.parse(_1) },
+          Decoders::Match.new(::URI::Generic)
         )
       ) { |_msg, value| "expected a URI, got #{value.inspect}" }
     end

data/lib/decoding/decoders.rb

@@ -128,7 +128,7 @@ module Decoding
     #   decode(boolean, true) # => Decoding::Ok(true)
     #   decode(boolean, false) # => Decoding::Ok(false)
     # @return [Decoding::Decoder<Boolean>]
-    def boolean = map_err(any(self.true, self.false)) { |_msg, value| "expected true or false, got #{value.class}" }
+    def boolean = map_err(enum(true, false)) { |_msg, value| "expected true or false, got #{value.class}" }
 
     # Decode a String value into a symbol.
     #

data/lib/decoding/matcher_helpers.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Decoding
+  # Shared logic for the matchers that describe decoding, loaded along with
+  # them by `require "decoding/rspec"`.
+  #
+  # Decoders report failures as {Decoding::Failure} values, but {Decoding.decode}
+  # renders those into strings, so matchers have to understand both.
+  module MatcherHelpers
+    # Split the error value of a result into its message and the path it
+    # occurred at, with the outermost path segment first.
+    #
+    # @param result [Decoding::Result]
+    # @return [Array(String, Array)]
+    def describe_failure(result)
+      error = result.unwrap_err(nil)
+      return [error.msg, error.path.reverse] if error.is_a?(Decoding::Failure)
+
+      match = error.to_s.match(/\AError at \.(?<path>.+?): (?<msg>.*)\z/m)
+      match ? [match[:msg], match[:path].split(".")] : [error.to_s, []]
+    end
+
+    # @param path [Array]
+    # @return [String]
+    def render_path(path) = path.empty? ? "" : " at .#{path.join(".")}"
+
+    # The path set by the `at` chain, if any.
+    #
+    # @return [Array]
+    def expected_path = @expected_path ||= []
+
+    # @param path [Array]
+    # @return [Boolean]
+    def path_matches?(path) = path.map(&:to_s) == expected_path.map(&:to_s)
+
+    # Compare a decoded value to what the example expects. Values are
+    # compared strictly, so that a decoder returning a value of the wrong
+    # type is not mistaken for a success, unless the example expects a
+    # matcher rather than a value.
+    #
+    # @param expected [Object]
+    # @param actual [Object]
+    # @return [Boolean]
+    def matches_value?(expected, actual)
+      return values_match?(expected, actual) if RSpec::Support.is_a_matcher?(expected)
+
+      actual.eql?(expected)
+    end
+  end
+end

data/lib/decoding/result.rb

@@ -30,15 +30,29 @@ module Decoding
     # Collapse array of result values into a single result, or return the
     # first `Err` value.
     #
+    # Given a block, each item is mapped to a result with the block first,
+    # one at a time, and items after the first `Err` are not mapped at all.
+    #
     # @example
     #   all(Ok(1), Ok(2)) # => Ok([1, 2])
     #   all(Ok(1), Err("error")) # => Err("error")
-    # @param results [Array<Result<a>>]
-    # @return [Result<a>]
-    def self.all(results)
-      results.reduce(ok([])) do |acc, el|
-        acc.and(el.to_result) { [*_1, _2] }
+    #   all([1, 2]) { Ok(_1 * 10) } # => Ok([10, 20])
+    # @overload all(results)
+    #   @param results [Enumerable<Result<a>>]
+    # @overload all(items)
+    #   @param items [Enumerable<Object>]
+    #   @yieldparam item [Object]
+    #   @yieldreturn [Result<a>]
+    # @return [Result<Array<a>>]
+    def self.all(items)
+      values = []
+      items.each_entry do |item|
+        result = (block_given? ? yield(item) : item).to_result
+        return result if result.err?
+
+        values << result.unwrap(nil)
       end
+      ok(values)
     end
 
     private_class_method :new
@@ -48,12 +62,15 @@ module Decoding
 
     protected :value
 
+    # Computed when asked for rather than up front: results are rarely used as
+    # hash keys, and hashing a large decoded value for every result created
+    # made decoding a collection quadratic.
+    #
     # @private
-    attr_reader :hash
+    def hash = [self.class, value].hash
 
     def initialize(value)
       @value = value
-      @hash = [self.class, value].hash
       freeze
     end
 

data/lib/decoding/rspec/decode_value.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "../matcher_helpers"
+
+# Passes when the given decoder decodes the given input. Chain `to` to also
+# assert the decoded value, or `failing_with` (optionally with `at`) to assert
+# that decoding fails with a particular message. Both expected values may
+# themselves be matchers.
+#
+#     expect(decoder).to decode_value(["foo"]).to(["foo"])
+#     expect(decoder).to decode_value([1]).failing_with("expected String, got Integer").at(0)
+#     expect(decoder).not_to decode_value(true)
+RSpec::Matchers.define :decode_value do |input|
+  include Decoding::MatcherHelpers
+
+  match do |actual|
+    next false unless actual.respond_to?(:call)
+
+    result = Decoding.decode(actual, input)
+    next matches_failure?(result) if message_expected?
+    next result.ok? && matches_value?(@expected_value, result.unwrap!) if value_expected?
+
+    result.ok?
+  end
+
+  match_when_negated do |actual|
+    raise ArgumentError, "use `not_to decode_value(input)` without `to` or `failing_with`" if message_expected? || value_expected?
+
+    actual.respond_to?(:call) && Decoding.decode(actual, input).err?
+  end
+
+  chain :to do |value|
+    @expected_value = value
+    @value_expected = true
+  end
+
+  chain :failing_with do |message|
+    @expected_message = message
+    @message_expected = true
+  end
+
+  chain :at do |*segments|
+    @expected_path = segments
+  end
+
+  failure_message do |actual|
+    next "expected a decoder, got #{description_of(actual)}" unless actual.respond_to?(:call)
+
+    "expected the decoder to #{description}, but #{describe_outcome(Decoding.decode(actual, input))}"
+  end
+
+  failure_message_when_negated do |actual|
+    next "expected a decoder, got #{description_of(actual)}" unless actual.respond_to?(:call)
+
+    "expected the decoder not to decode #{description_of(input)}"
+  end
+
+  description do
+    if message_expected?
+      next "fail decoding #{description_of(input)} with #{description_of(@expected_message)}#{render_path(expected_path)}"
+    end
+    next "decode #{description_of(input)} to #{description_of(@expected_value)}" if value_expected?
+
+    "decode #{description_of(input)}"
+  end
+
+  def message_expected? = @message_expected
+  def value_expected? = @value_expected
+
+  def matches_failure?(result)
+    return false unless result.err?
+
+    msg, path = describe_failure(result)
+    matches_value?(@expected_message, msg) && path_matches?(path)
+  end
+
+  def describe_outcome(result)
+    unless result.ok?
+      msg, path = describe_failure(result)
+      return "it failed with #{description_of(msg)}#{render_path(path)}"
+    end
+
+    return "it succeeded with #{description_of(result.unwrap!)}" if message_expected?
+
+    "it decoded to #{description_of(result.unwrap!)}"
+  end
+end

data/lib/decoding/rspec/fail_with.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../matcher_helpers"
+
+# Passes when the given {Decoding::Result} is an `Err` that failed with the
+# expected message. Chain `at` to also assert where the failure occurred,
+# naming the path segments outermost first. The expected message may itself be
+# a matcher.
+#
+#     expect(Decoding.decode(decoder, [1])).to fail_with("expected String, got Integer").at(0)
+#
+# Failures are recognised both as {Decoding::Failure} values and as the strings
+# they turn into once {Decoding.decode} has rendered them.
+RSpec::Matchers.define :fail_with do |expected|
+  include Decoding::MatcherHelpers
+
+  match do |actual|
+    next false unless actual.is_a?(Decoding::Result) && actual.err?
+
+    msg, path = describe_failure(actual)
+    matches_value?(expected, msg) && path_matches?(path)
+  end
+
+  chain :at do |*segments|
+    @expected_path = segments
+  end
+
+  failure_message do |actual|
+    next "expected a Decoding::Result, got #{description_of(actual)}" unless actual.is_a?(Decoding::Result)
+
+    outcome =
+      if actual.ok?
+        "it succeeded with #{description_of(actual.unwrap!)}"
+      else
+        msg, path = describe_failure(actual)
+        "it failed with #{description_of(msg)}#{render_path(path)}"
+      end
+    "expected the result to #{description}, but #{outcome}"
+  end
+
+  failure_message_when_negated do
+    "expected the result not to #{description}"
+  end
+
+  description do
+    "fail with #{description_of(expected)}#{render_path(expected_path)}"
+  end
+end

data/lib/decoding/rspec/succeed_with.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../matcher_helpers"
+
+# Passes when the given {Decoding::Result} is an `Ok` holding the expected
+# value. The expected value may itself be a matcher.
+#
+#     expect(Decoding.decode(decoder, "foo")).to succeed_with("foo")
+RSpec::Matchers.define :succeed_with do |expected|
+  include Decoding::MatcherHelpers
+
+  match do |actual|
+    actual.is_a?(Decoding::Result) && actual.ok? && matches_value?(expected, actual.unwrap!)
+  end
+
+  failure_message do |actual|
+    next "expected a Decoding::Result, got #{description_of(actual)}" unless actual.is_a?(Decoding::Result)
+
+    outcome =
+      if actual.ok?
+        "it succeeded with #{description_of(actual.unwrap!)}"
+      else
+        "it failed with #{description_of(actual.unwrap_err(nil).to_s)}"
+      end
+    "expected the result to succeed with #{description_of(expected)}, but #{outcome}"
+  end
+
+  failure_message_when_negated do
+    "expected the result not to succeed with #{description_of(expected)}"
+  end
+end

data/lib/decoding/rspec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Matchers for asserting on decoders and their results, for applications that
+# write decoders of their own.
+#
+# These are the matchers this gem tests itself with. Require them from your
+# spec helper; they need `rspec-expectations`, which is not a dependency of
+# this gem, so nothing is loaded unless you ask for it.
+#
+#     # spec/spec_helper.rb
+#     require "decoding/rspec"
+#
+# `decode_value` describes a decoder, and is what you want most of the time: it
+# runs the decoder for you, so an example says what a decoder does rather than
+# how to call it.
+#
+#     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:
+#
+#     expect(field("a", field("b", 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 is testing:
+#
+#     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:
+#
+#     expect(unix_time).to decode_value("1595674680.5").to(an_object_having_attributes(usec: 500_000))
+require_relative "../decoding"
+require_relative "matcher_helpers"
+require_relative "rspec/decode_value"
+require_relative "rspec/succeed_with"
+require_relative "rspec/fail_with"

data/lib/decoding/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Decoding
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decoding
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Arjan van der Gaag
@@ -55,7 +55,12 @@ files:
 - lib/decoding/env.rb
 - lib/decoding/error.rb
 - lib/decoding/failure.rb
+- lib/decoding/matcher_helpers.rb
 - lib/decoding/result.rb
+- lib/decoding/rspec.rb
+- lib/decoding/rspec/decode_value.rb
+- lib/decoding/rspec/fail_with.rb
+- lib/decoding/rspec/succeed_with.rb
 - lib/decoding/version.rb
 - sig/decoding.rbs
 homepage: https://github.com/avdgaag/decoding