decoding 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27eee73e0aa7f430b7fb6aac6aea19c872dd5d825633d1f0e54362668ae355e5
-  data.tar.gz: b6ceb7aa0bd5cda5812949c165a4f8614dd0da97f5e05a8cbbf77cefa3e10e4d
+  metadata.gz: 3dcd003beb1f65e74c31189b632c9c290d636a20467f5fed1a8c382d1aff634b
+  data.tar.gz: 338652cc9d8ea559a31fc9b14adc14a83cdc10c5730a175a1fa3670b87435b3d
 SHA512:
-  metadata.gz: 8119c1c00072ccbe6393ba6265d8eb5bd18e4f3a6b0c821a66eac6f1a9d52481b4cdf6b7e70656545c08cecbbb365f7736a505b3df25a9bd03c1b2e9ec486e9e
-  data.tar.gz: 5a76a8b7c125c47e2afd5f8a37bd0290ca5e2fb6de03a42cc2dabeeba4121f4601a27bd804e62a088aad8e165e2f85aca7ac8a07f6fc537be3019d9a610baae7
+  metadata.gz: 1a20f3f88d3970063dd6b3f8890ee8f0646df418e0c157fffe3081f6de6c2c3b7718cd685335c1b7f108e21f110d5823be6bdab3e37a222c2d6b4a728bcb820f
+  data.tar.gz: 31edcf5c7f5721d93308269883d271b1cd1336738a1013c18c5d21e071dddfd3de855fb3091b5d2426ddc1e57f19baca471051cbffdddf2cc47e7b157120bd1e

data/.rubocop.yml

@@ -25,6 +25,9 @@ Metrics/ModuleLength:
 
 Metrics/AbcSize:
   Max: 18
+  Exclude:
+    # The benchmarks build test data in long methods.
+    - benchmark/support/*.rb
 
 Metrics/BlockLength:
   Exclude:
@@ -34,6 +37,9 @@ Metrics/BlockLength:
 
 Metrics/MethodLength:
   Max: 17
+  Exclude:
+    # The benchmarks build test data in long methods.
+    - benchmark/support/*.rb
 
 Style/SignalException:
   Enabled: false
@@ -65,3 +71,13 @@ RSpec/DescribeClass:
 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,13 @@
 ## [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.

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
@@ -47,8 +51,8 @@ module Decoding
       parse, description = time_format(format, zone)
       Decoders.map_err(
         Decoders.any(
-          Decoders.match(::Time),
-          parsed_by(parse)
+          parsed_by(parse),
+          Decoders.match(::Time)
         )
       ) { |_message, value| "expected #{description}, got #{value.inspect}" }
     end
@@ -98,21 +102,23 @@ module Decoding
       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),
-          timestamp_in(zone, UNIX_TIME_UNITS.fetch(unit))
+          timestamp_in(Decoders.any(Decoders.parsed_integer, Decoders.parsed_float), zone, per_second)
         )
       ) { |_message, value| "expected a unix timestamp, got #{value.inspect}" }
     end
 
-    # Decode a number, or a string describing one, as a point in time.
+    # Decode the number given by `decoder` as a point in time.
     #
     # @private
-    def timestamp_in(zone, per_second)
-      Decoders.map(
-        Decoders.any(Decoders.integer, Decoders.float, Decoders.parsed_integer, Decoders.parsed_float)
-      ) { zone.at(per_second == 1 ? _1 : _1 / Rational(per_second)) }
+    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.
@@ -123,9 +129,7 @@ module Decoding
     #
     # @private
     def parsed_by(parse)
-      Decoders.and_then(Decoders.map(Decoders.string) { parse.call(_1) }) do |value|
-        value.nil? ? Decoders.fail("parsed to nothing") : Decoders.succeed(value)
-      end
+      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,

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/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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decoding
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Arjan van der Gaag