decoding 0.3.0 → 0.5.0

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.3.0"
+  VERSION = "0.5.0"
 end

data/lib/decoding.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "decoding/version"
+require_relative "decoding/error"
 require_relative "decoding/decoders"
 require_relative "decoding/data"
 
@@ -110,8 +111,6 @@ require_relative "decoding/data"
 # always contain a string error message. It is up to you, as a developer, to
 # decide how to deal with unsuccessful decoding.
 module Decoding
-  class Error < StandardError; end
-
   module_function
 
   # Run a given `decoder` on the given input `value`.
@@ -120,4 +119,18 @@ module Decoding
   # @param value [Object]
   # @return [Decoding::Result<a>]
   def decode(decoder, value) = decoder.call(value).map_err(&:to_s)
+
+  # Run a given `decoder` on the given input `value`, returning the decoded
+  # value or raising an error when decoding failed.
+  #
+  # @example
+  #   decode!(string, "foo") # => "foo"
+  #   decode!(string, 123) # raises Decoding::UnwrapError
+  # @overload decode!(decoder, value)
+  #   @param decoder [Decoding::Decoder<a>]
+  #   @param value [Object]
+  #   @raise [Decoding::UnwrapError] when decoding failed.
+  #   @return [Object]
+  # @see Decoding::Result#unwrap!
+  def decode!(...) = decode(...).unwrap!
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decoding
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Arjan van der Gaag
@@ -35,16 +35,32 @@ files:
 - lib/decoding/decoders/any.rb
 - lib/decoding/decoders/array.rb
 - lib/decoding/decoders/at.rb
+- lib/decoding/decoders/big_decimal.rb
+- lib/decoding/decoders/date.rb
+- lib/decoding/decoders/enum.rb
 - lib/decoding/decoders/fail.rb
 - lib/decoding/decoders/field.rb
 - lib/decoding/decoders/hash.rb
 - lib/decoding/decoders/index.rb
+- lib/decoding/decoders/lazy.rb
 - lib/decoding/decoders/map.rb
+- lib/decoding/decoders/map_err.rb
 - lib/decoding/decoders/match.rb
+- lib/decoding/decoders/optional.rb
+- lib/decoding/decoders/optional_field.rb
 - lib/decoding/decoders/pass.rb
 - lib/decoding/decoders/succeed.rb
+- lib/decoding/decoders/time.rb
+- lib/decoding/decoders/uri.rb
+- 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