decoding 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0af816a4ee858fb01b7affa44921ddb05b38199a2fbdee33f9439342d8c5dee7
-  data.tar.gz: 18511340412ca51970844209ed9d878a2f46b32ffec15f1c9862c97a540c8921
+  metadata.gz: 27eee73e0aa7f430b7fb6aac6aea19c872dd5d825633d1f0e54362668ae355e5
+  data.tar.gz: b6ceb7aa0bd5cda5812949c165a4f8614dd0da97f5e05a8cbbf77cefa3e10e4d
 SHA512:
-  metadata.gz: 044227d25ff8af0830443a267b86455de69ba14c72fa37bed1b5c84080d5f1156aeb533cceb46d5e8cce7b57a6d2a55a85729fb652b36bb747dc6b9f704ef6ef
-  data.tar.gz: f957565332b96ca5fa607fb12ecebfc0bc3379beb6aa154760b70f14f92f59b4c8fbb39e235621e020473f49d68e20fe7909c8a0f6bcef1e091cd7d6f02b6a99
+  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,10 @@
 ## [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"`

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/lib/decoding/decoders/time.rb

@@ -22,35 +22,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)
         )
       ) { |_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 +78,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)
 
-      per_second = UNIX_TIME_UNITS.fetch(unit)
+      require_parser(zone, :at, "a unix timestamp")
       Decoders.map_err(
         Decoders.any(
           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(zone, UNIX_TIME_UNITS.fetch(unit))
         )
       ) { |_message, value| "expected a unix timestamp, got #{value.inspect}" }
     end
 
-    private_class_method :time_format
+    # Decode a number, or a string describing one, 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)) }
+    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.and_then(Decoders.map(Decoders.string) { parse.call(_1) }) do |value|
+        value.nil? ? Decoders.fail("parsed to nothing") : Decoders.succeed(value)
+      end
+    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/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/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.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decoding
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.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