decoding 0.2.6 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d613b53b493863ecae1fcbc778f5684acbbc628ad51f88fca0953889cd138d0
-  data.tar.gz: cfc4039a5bfcf182c174b0d1f037d2cbd3b610fa746904906a2209b680fb4cad
+  metadata.gz: 0af816a4ee858fb01b7affa44921ddb05b38199a2fbdee33f9439342d8c5dee7
+  data.tar.gz: 18511340412ca51970844209ed9d878a2f46b32ffec15f1c9862c97a540c8921
 SHA512:
-  metadata.gz: cbe2df98d6a2b6b9588cc5ecfe5543cae21575488a09d99768f10791fdb66332f8cda35483b6e61045a8bbdb5949f900cdd69ab94cfb602e456fb05f5dbfa14e
-  data.tar.gz: e0eaddb3e027ba796f126aa500564507481847c196d139b16a51c390cb28990706be3d959bde8700857abbf2c18fc69765f79c03cd7cd16cbfd5e7a7be03be92
+  metadata.gz: 044227d25ff8af0830443a267b86455de69ba14c72fa37bed1b5c84080d5f1156aeb533cceb46d5e8cce7b57a6d2a55a85729fb652b36bb747dc6b9f704ef6ef
+  data.tar.gz: f957565332b96ca5fa607fb12ecebfc0bc3379beb6aa154760b70f14f92f59b4c8fbb39e235621e020473f49d68e20fe7909c8a0f6bcef1e091cd7d6f02b6a99

data/.rubocop.yml

@@ -1,5 +1,5 @@
 ---
-require:
+plugins:
   - rubocop-rspec
   - rubocop-performance
   - rubocop-rake

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [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
+
 ## [0.2.6]
 
 * Add `Decoding::Result#unwrap!`

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,123 @@ 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.
+
+* `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.
+
 ## 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/data.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "decoders"
+
+module Decoding
+  # Wrapper around Ruby's `Data` class, providing a way to both define a new
+  # data class as usual but including a decoder to decode a value into such a
+  # data value.
+  #
+  # @example
+  #   User = Decoding::Data.define(
+  #     name: field("postName", string),
+  #     age: field("yearsOld", integer)
+  #   ) do
+  #    def greet
+  #      "Hello, my name is #{name} and I am #{age} years old."
+  #    end
+  #  end
+  #  payload = { "postName" => "John", "yearsOld" => 30 }
+  #  Decoding.decode(User.decoder, payload) => Decoding::Ok(user)
+  #  user.greet # => "Hello, my name is John and I am 30 years old."
+  # @return [Class]
+  module Data
+    # @param attributes [Hash<Symbol, Decoding::Decoder>] A hash of attribute
+    #   names and decoders
+    # @see ::Data.define
+    # @return [Class] A new data class with a `decoder` method.
+    def self.define(attributes, &)
+      # First ensure we have a hash of attribute names and decoders
+      attributes = attributes.to_h do |key, value|
+        [key.to_sym, value.to_decoder]
+      end
+
+      # Define the data class as usual
+      data_class = ::Data.define(*attributes.keys, &)
+
+      # Add a special `decode` method to use the provided decoders to decode a
+      # value as hash and build a new instance with it
+      data_class.define_singleton_method(:decoder) do
+        Decoding::Decoders.map(
+          Decoding::Decoders.decode_hash(attributes)
+        ) { |attrs| new(**attrs) }
+      end
+
+      # Adapt to `to_decoder` protocol
+      data_class.define_singleton_method(:to_decoder) { decoder }
+
+      # Return the data class so regular assignment like
+      # `User = ::Data.define(...)` works.
+      data_class
+    end
+  end
+end

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

data/lib/decoding/decoders/optional.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "../decoder"
+
+module Decoding
+  module Decoders
+    # A decoder for a value that may or may not be `nil`, decoding any other
+    # value with a given decoder.
+    #
+    # The given decoder gets to decode a `nil` value first, so it can give it a
+    # meaning of its own. Only when it fails to do so does this decoder treat
+    # `nil` as an absent value.
+    #
+    # @see Decoding::Decoders.optional
+    class Optional < Decoder
+      # @param decoder [Decoding::Decoder<a>]
+      def initialize(decoder)
+        @decoder = decoder.to_decoder
+        super()
+      end
+
+      # @param value [Object]
+      # @return [Decoding::Result<a, nil>]
+      def call(value)
+        result = @decoder.call(value)
+        return result if result.ok?
+        return ok(nil) if value.nil?
+
+        result
+      end
+    end
+  end
+end

data/lib/decoding/decoders/optional_field.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../decoder"
+require_relative "field"
+
+module Decoding
+  module Decoders
+    # Decode a value from a key that may be absent from a hash.
+    #
+    # This differs from wrapping a {Field} decoder in an {Optional} decoder,
+    # which describes a key that is present but may hold `nil`. Here the key
+    # itself may be missing; when it is present, its value must still decode.
+    #
+    # @see Decoding::Decoders.optional_field
+    class OptionalField < Decoder
+      # @param key [Object]
+      # @param decoder [Decoding::Decoder<a>]
+      # @param default [Object] used when the key is absent.
+      def initialize(key, decoder, default: nil)
+        @key = String(key)
+        @field = Field.new(@key, decoder)
+        @default = default
+        super()
+      end
+
+      # @param value [Object]
+      # @return [Decoding::Result<a>]
+      def call(value)
+        return ok(@default) if value.is_a?(::Hash) && !value.key?(@key)
+
+        @field.call(value)
+      end
+    end
+  end
+end

data/lib/decoding/decoders/succeed.rb

@@ -11,9 +11,14 @@ module Decoding
     # @example Always return a fixed value
     #   decode(Succeed.new(5), "anything") # => Decoding::Ok(5)
     #
-    # @example Use with field to provide defaults
-    #   decode(any(field("x", integer), Succeed.new(0)), {})
-    #   # => Decoding::Ok(0)
+    # @example Use in conditional decoding
+    #   and_then(field("kind", string)) do |kind|
+    #     kind == "none" ? Succeed.new(nil) : field("value", integer)
+    #   end
+    #
+    # Note this is not the way to give a key a default value: combining it with
+    # {Any} would also swallow the failure of a key that is present but holds a
+    # value of the wrong type. Use {OptionalField} for that instead.
     class Succeed < Decoder
       # @param value [Object] the value to always return
       def initialize(value)

data/lib/decoding/decoders/time.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Decoding
+  # Decoders are composable functions for deconstructing unknown input values
+  # into known output values.
+  module Decoders
+    # The standard formats {Decoding::Decoders.time} can parse, each named after
+    # the `Time` method that parses it.
+    TIME_FORMATS = %i[iso8601 xmlschema rfc2822 rfc822 httpdate parse].freeze
+
+    # 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
+
+    module_function
+
+    # Decode a `Time` object, or a string describing a time in a given format.
+    #
+    # The format is either the name of one of {TIME_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 time.
+    #
+    # @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\"")
+    # @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<Time>]
+    # @see Decoding::Decoders::MapErr
+    def time(format)
+      parse, description = time_format(format)
+      Decoders.map_err(
+        Decoders.any(
+          Decoders.match(::Time),
+          Decoders.map(Decoders.string) { parse.call(_1) }
+        )
+      ) { |_message, value| "expected #{description}, got #{value.inspect}" }
+    end
+
+    # @private
+    def time_format(format)
+      case format
+      when ::String
+        [->(str) { ::Time.strptime(str, format) }, "a time matching #{format.inspect}"]
+      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"]
+      else
+        raise ArgumentError, "expected a time format name or a strptime pattern, got #{format.inspect}"
+      end
+    end
+
+    # Decode a unix timestamp, given as a number or as a string describing one.
+    #
+    # Timestamps are read as a number of seconds since the epoch unless another
+    # unit is given. Note that reading a timestamp in the wrong unit is not an
+    # error but a wildly different point in time, so a source that reports
+    # milliseconds has to say so.
+    #
+    # @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.
+    # @return [Decoding::Decoder<Time>]
+    # @see Decoding::Decoders::MapErr
+    def unix_time(unit = :seconds)
+      raise ArgumentError, "unknown unit: #{unit.inspect}" unless UNIX_TIME_UNITS.key?(unit)
+
+      per_second = UNIX_TIME_UNITS.fetch(unit)
+      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)) }
+        )
+      ) { |_message, value| "expected a unix timestamp, got #{value.inspect}" }
+    end
+
+    private_class_method :time_format
+  end
+end

data/lib/decoding/decoders/uri.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Decoding
+  # Decoders are composable functions for deconstructing unknown input values
+  # into known output values.
+  module Decoders
+    module_function
+
+    # Decode a URI object, or a string that can be parsed as one.
+    #
+    # @example
+    #   decode(uri, "https://example.com") # => Decoding::Ok(URI("https://example.com"))
+    #   decode(uri, 123) # => Decoding::Err("expected a URI, got 123")
+    # @return [Decoding::Decoder<URI::Generic>]
+    # @see Decoding::Decoders::MapErr
+    def uri
+      Decoders.map_err(
+        Decoders.any(
+          Decoders::Match.new(::URI::Generic),
+          Decoders.map(Decoders.string) { ::URI.parse(_1) }
+        )
+      ) { |_msg, value| "expected a URI, got #{value.inspect}" }
+    end
+  end
+end

data/lib/decoding/decoders.rb

@@ -2,8 +2,13 @@
 
 require_relative "decoders/match"
 require_relative "decoders/map"
+require_relative "decoders/map_err"
+require_relative "decoders/optional"
+require_relative "decoders/lazy"
+require_relative "decoders/enum"
 require_relative "decoders/any"
 require_relative "decoders/field"
+require_relative "decoders/optional_field"
 require_relative "decoders/array"
 require_relative "decoders/index"
 require_relative "decoders/hash"
@@ -30,6 +35,37 @@ module Decoding
     # @see Decoding::Decoders::Match
     def string = Decoders::Match.new(String)
 
+    # Decode any value matching the given pattern, using the `===` operator.
+    # This works with anything that can be used in a `case` statement, such as
+    # classes, ranges and regular expressions.
+    #
+    # @example
+    #   decode(match(Symbol), :foo) # => Decoding::Ok(:foo)
+    #   decode(match(1..5), 3) # => Decoding::Ok(3)
+    # @param pattern [#===]
+    # @return [Decoding::Decoder<Object>]
+    # @see Decoding::Decoders::Match
+    def match(pattern) = Decoders::Match.new(pattern)
+
+    # Decode a value that must be one of a fixed set of values.
+    #
+    # The values are compared for equality, and can be given either as separate
+    # arguments or as a single array.
+    #
+    # @example
+    #   decode(enum("active", "archived"), "active") # => Decoding::Ok("active")
+    #   decode(enum("active", "archived"), "nope")
+    #   # => Decoding::Err(%(expected one of "active", "archived", got "nope"))
+    # @overload enum(value, *values)
+    #   @param value [Object]
+    #   @param values [Object]
+    # @overload enum(values)
+    #   @param values [Array<Object>]
+    # @raise [ArgumentError] when no values are given, or one is repeated.
+    # @return [Decoding::Decoder<Object>]
+    # @see Decoding::Decoders::Enum
+    def enum(...) = Decoders::Enum.new(...)
+
     # Decode any string value that matches a regular expression.
     #
     # @param regex [Regexp, String]
@@ -92,7 +128,7 @@ module Decoding
     #   decode(boolean, true) # => Decoding::Ok(true)
     #   decode(boolean, false) # => Decoding::Ok(false)
     # @return [Decoding::Decoder<Boolean>]
-    def boolean = any(self.true, self.false)
+    def boolean = map_err(any(self.true, self.false)) { |_msg, value| "expected true or false, got #{value.class}" }
 
     # Decode a String value into a symbol.
     #
@@ -101,6 +137,46 @@ module Decoding
     # @return [Decoding::Decoder<Symbol>]
     def symbol = map(string, &:to_sym)
 
+    # @!group Parsing decoders
+
+    # Decode a string describing an integer into that integer.
+    #
+    # The string is always read as a decimal number, so `"08"` decodes to `8`
+    # and `"0x1f"` is not a valid integer.
+    #
+    # @example
+    #   decode(parsed_integer, "8080") # => Decoding::Ok(8080)
+    #   decode(parsed_integer, "abc") # => Decoding::Err(%(expected an integer, got "abc"))
+    # @return [Decoding::Decoder<Integer>]
+    def parsed_integer
+      map_err(map(string) { Integer(_1, 10) }) { |_message, value| "expected an integer, got #{value.inspect}" }
+    end
+
+    # Decode a string describing a number into a float.
+    #
+    # @example
+    #   decode(parsed_float, "1.5") # => Decoding::Ok(1.5)
+    #   decode(parsed_float, "abc") # => Decoding::Err(%(expected a number, got "abc"))
+    # @return [Decoding::Decoder<Float>]
+    def parsed_float
+      map_err(map(string) { Float(_1) }) { |_message, value| "expected a number, got #{value.inspect}" }
+    end
+
+    # Decode the string `"true"` or `"false"` into the matching boolean.
+    #
+    # Only those two values are accepted: anything else, such as `"1"` or
+    # `"yes"`, is an error rather than a guess at what was meant.
+    #
+    # @example
+    #   decode(parsed_boolean, "true") # => Decoding::Ok(true)
+    #   decode(parsed_boolean, "1") # => Decoding::Err(%(expected "true" or "false", got "1"))
+    # @return [Decoding::Decoder<Boolean>]
+    def parsed_boolean
+      map_err(map(enum("true", "false")) { _1 == "true" }) do |_message, value|
+        %(expected "true" or "false", got #{value.inspect})
+      end
+    end
+
     # @!group Utility decoders
 
     # A decoder that always succeeds with the given value.
@@ -151,6 +227,28 @@ module Decoding
     # @see Decoding::Decoders::Map
     def map(...) = Decoders::Map.new(...)
 
+    # Decode a value with the given decoder and, if it failed, replace its
+    # error message with the result of the given block.
+    #
+    # This is useful for giving a compound decoder a single, fitting error
+    # message rather than exposing the messages of the decoders it is built
+    # from. The location of the original error, if any, is retained.
+    #
+    # @example
+    #   decoder = map_err(any(string, integer)) { |_msg, value|
+    #     "expected a string or integer, got #{value.inspect}"
+    #   }
+    #   decode(decoder, nil)
+    #   # => Decoding::Err("expected a string or integer, got nil")
+    # @overload map_err(decoder)
+    #   @param decoder [Decoding::Decoder<a>]
+    #   @yieldparam msg [String] the original error message
+    #   @yieldparam value [Object] the value being decoded
+    #   @yieldreturn [String]
+    #   @return [Decoding::Decoder<a>]
+    # @see Decoding::Decoders::MapErr
+    def map_err(...) = Decoders::MapErr.new(...)
+
     # Decode a value by trying many different decoders in order, using the first
     # matching result -- or a failure when none of the given decoders succeed.
     #
@@ -168,9 +266,15 @@ module Decoding
     # @example
     #   decode(string, "foo") # => Decoding::Ok("foo")
     #   decode(string, nil) # => Decoding::Ok(nil)
-    # @param decoder [Decoding::Decoder<a>]
-    # @return [Decoding::Decoder<a, nil>]
-    def optional(decoder) = any(decoder, self.nil)
+    # The given decoder gets to decode a `nil` value first, so it can give it a
+    # meaning of its own. Only when it fails to do so is `nil` treated as an
+    # absent value.
+    #
+    # @overload optional(decoder)
+    #   @param decoder [Decoding::Decoder<a>]
+    #   @return [Decoding::Decoder<a, nil>]
+    # @see Decoding::Decoders::Optional
+    def optional(...) = Decoders::Optional.new(...)
 
     # Decode a value from a given key in a hash.
     #
@@ -183,6 +287,26 @@ module Decoding
     # @see Decoding::Decoders::Field
     def field(...) = Decoders::Field.new(...)
 
+    # Decode a value from a key that may be absent from a hash.
+    #
+    # When the key is absent, the given default is used. When it is present, its
+    # value must still decode: a key holding a value of the wrong type is an
+    # error rather than a reason to fall back to the default.
+    #
+    # @example
+    #   decoder = optional_field("count", integer, default: 0)
+    #   decode(decoder, {}) # => Decoding::Ok(0)
+    #   decode(decoder, { "count" => 5 }) # => Decoding::Ok(5)
+    #   decode(decoder, { "count" => "x" })
+    #   # => Decoding::Err("Error at .count: expected Integer, got String")
+    # @overload optional_field(key, decoder, default: nil)
+    #   @param key [Object]
+    #   @param decoder [Decoding::Decoder<a>]
+    #   @param default [Object]
+    #   @return [Decoding::Decoder<a>]
+    # @see Decoding::Decoders::OptionalField
+    def optional_field(...) = Decoders::OptionalField.new(...)
+
     # Decode an array of values using a given decoder.
     #
     # @example
@@ -233,6 +357,8 @@ module Decoding
     #   # => Decode::Ok({ id: 1 })
     # @return Decoding::Decoder
     def decode_hash(decoders)
+      return succeed({}) if decoders.empty?
+
       map(*decoders.values) do |*values|
         decoders.keys.zip(values).to_h
       end
@@ -260,6 +386,26 @@ module Decoding
     # @see Decoding::Decoders::AndThen
     def and_then(...) = Decoders::AndThen.new(...)
 
+    # Create a decoder that is only built when it is used.
+    #
+    # This makes recursive decoders possible: without it, a decoder that refers
+    # to itself would recurse endlessly while being built.
+    #
+    # @example
+    #   def tree
+    #     decode_hash(
+    #       name: field("name", string),
+    #       children: field("children", array(lazy { tree }))
+    #     )
+    #   end
+    #   decode(tree, { "name" => "a", "children" => [] })
+    #   # => Decoding::Ok({ name: "a", children: [] })
+    # @overload lazy
+    #   @yieldreturn [Decoding::Decoder<a>]
+    #   @return [Decoding::Decoder<a>]
+    # @see Decoding::Decoders::Lazy
+    def lazy(...) = Decoders::Lazy.new(...)
+
     # Decode deeply-nested fields.
     #
     # @example
@@ -267,7 +413,7 @@ module Decoding
     #   decode(decoder, { "a" => { "b" => { "c" => "d" } } })
     #   # => Decoding::Ok("d")
     #   decode(decoder, { "a" => { "b" => "d" } })
-    #   # => Decoding::Err("Error at .a.b: expected a Hash, got String")
+    #   # => Decoding::Err("Error at .a.b: expected Hash, got String")
     # @overload at(*fields, decoder)
     #   @param fields [String]
     #   @param decoder [Decoding::Decoder<a>]

data/lib/decoding/env.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "../decoding"
+
+# Decoding is a library to help transform unknown external data into neat values
+# with known shapes.
+module Decoding
+  # The types {Decoding.env} accepts by name, mapped to the decoder that reads
+  # them.
+  #
+  # Environment variables are always strings, so these are all decoders that
+  # parse a string. Pass a decoder directly for anything else.
+  ENV_TYPES = {
+    string: :string,
+    symbol: :symbol,
+    integer: :parsed_integer,
+    float: :parsed_float,
+    boolean: :parsed_boolean
+  }.freeze
+
+  # Marks the absence of a default value, so that `nil` can be used as one.
+  NO_DEFAULT = Object.new.freeze
+  private_constant :NO_DEFAULT
+
+  module_function
+
+  # Read a single environment variable, decoding its value.
+  #
+  # This is meant for configuration read at boot time, such as a Rails
+  # initializer: it returns the decoded value itself and raises when the
+  # variable is missing or its value cannot be decoded, rather than letting a
+  # misconfigured application start.
+  #
+  # @example
+  #   Decoding.env("DATABASE_URL") # => "postgres://localhost/app"
+  #   Decoding.env("PORT", :integer) # => 8080
+  #   Decoding.env("PORT", :integer, default: 3000) # => 3000 when unset
+  #   Decoding.env("DATABASE_URL", Decoders.uri) # => #<URI::Generic ...>
+  # @param name [String] the name of the environment variable.
+  # @param type [Symbol, Decoding::Decoder] one of the keys of {ENV_TYPES}, or
+  #   any decoder to run against the value.
+  # @param default [Object] returned, undecoded, when the variable is not set.
+  # @param from [#key?, #fetch] where to read the variable from.
+  # @raise [ArgumentError] when the type is not a known name or a decoder.
+  # @raise [Decoding::UnwrapError] when the variable is missing or its value
+  #   cannot be decoded.
+  # @return [Object]
+  def env(name, type = :string, default: NO_DEFAULT, from: ENV)
+    decoder = env_decoder(type)
+    return default if !from.key?(name) && !default.equal?(NO_DEFAULT)
+
+    decode!(
+      Decoders.map_err(decoder) do |message, value|
+        value.nil? ? "ENV[#{name.inspect}] is not set" : "ENV[#{name.inspect}]: #{message}"
+      end,
+      from.fetch(name, nil)
+    )
+  end
+
+  # @private
+  def env_decoder(type)
+    return type.to_decoder if type.respond_to?(:to_decoder)
+    raise ArgumentError, "expected a type name or a decoder, got #{type.inspect}" unless type.is_a?(Symbol)
+    raise ArgumentError, "unknown type: #{type.inspect}" unless ENV_TYPES.key?(type)
+
+    Decoders.public_send(ENV_TYPES.fetch(type))
+  end
+
+  private_class_method :env_decoder
+end

data/lib/decoding/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Decoding
+  # Base class for all errors raised by this library.
+  class Error < StandardError; end
+end

data/lib/decoding/failure.rb

@@ -9,6 +9,17 @@ module Decoding
   # error, the `array` decoder can push `3` to the stack to indicate that
   # happened at index 3 in its input value.
   class Failure
+    # The error message, without the location it occurred at.
+    #
+    # @return [String]
+    attr_reader :msg
+
+    # The stack of segments describing where the error occurred, innermost
+    # first.
+    #
+    # @return [Array]
+    attr_reader :path
+
     # @param msg [String]
     # @param path [Array] Internal parameter for creating copies with updated paths
     def initialize(msg, path = [])
@@ -33,6 +44,37 @@ module Decoding
       self.class.new(@msg, @path + [segment])
     end
 
+    # Create a copy of this failure with a transformed error message, retaining
+    # the current stack of errors.
+    #
+    # This is useful for decoders that want to replace the error message of a
+    # nested decoder with something more fitting, without losing the location
+    # of the error.
+    #
+    # @yieldparam msg [String]
+    # @yieldreturn [String]
+    # @return [Decoding::Failure]
+    def map = self.class.new(yield(@msg), @path)
+
+    # Combine this failure with others into a single failure, using the given
+    # block to build a single message from all of their messages.
+    #
+    # When all failures occurred at the same location, that location is kept for
+    # the combined failure and left out of the individual messages, since the
+    # combined failure already describes it. Otherwise each message describes
+    # its own location.
+    #
+    # @param others [Array<Decoding::Failure>]
+    # @yieldparam messages [Array<String>]
+    # @yieldreturn [String]
+    # @return [Decoding::Failure]
+    def combine(others)
+      failures = [self, *others]
+      return self.class.new(yield(failures.map(&:to_s))) unless failures.map(&:path).uniq.size == 1
+
+      self.class.new(yield(failures.map(&:msg)), @path)
+    end
+
     def to_s
       if @path.any?
         "Error at .#{@path.reverse.join(".")}: #{@msg}"
@@ -40,9 +82,5 @@ module Decoding
         @msg
       end
     end
-
-    protected
-
-    attr_reader :msg, :path
   end
 end

data/lib/decoding/result.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "error"
+
 module Decoding
   # Raised when calling {Result#unwrap!} on an `Err` value.
-  class UnwrapError < StandardError; end
+  class UnwrapError < Error; end
 
   # A result represent the outcome of some computation that can succeed or fail.
   # The results are represented with two subclasses of `Result`: `Ok` and `Err`.

data/lib/decoding/version.rb

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

data/lib/decoding.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require_relative "decoding/version"
+require_relative "decoding/error"
 require_relative "decoding/decoders"
+require_relative "decoding/data"
 
 # Decoding is a library to help transform unknown external data into neat values
 # with known shapes. Consider calling an HTTP API: you might pull in whatever
@@ -109,8 +111,6 @@ require_relative "decoding/decoders"
 # 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`.
@@ -119,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.2.6
+  version: 0.4.0
 platform: ruby
 authors:
 - Arjan van der Gaag
@@ -28,20 +28,32 @@ files:
 - README.md
 - Rakefile
 - lib/decoding.rb
+- lib/decoding/data.rb
 - lib/decoding/decoder.rb
 - lib/decoding/decoders.rb
 - lib/decoding/decoders/and_then.rb
 - 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/result.rb
 - lib/decoding/version.rb