re_sorcery 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b2890e5efcd2dbd01d5f849d9ba9887ac5c78077057b6406ae458ef3c048337
-  data.tar.gz: 3971c5c49f0c6d6bc0ac407b6b79091e1e2e9d16fa7d80c7deab0e12d3a94954
+  metadata.gz: 37fc462892cc20c02ed1a1dd5d3aaeaf8712bfd2708cccdfbe026944015adc66
+  data.tar.gz: ac6f04c6ad4992e8d0babcb9de137702eb62ec489fa336c708e9b4a5700e2c99
 SHA512:
-  metadata.gz: 6281d8f26287f854baccd61aa8e800dd27720053262b99380c5f2a26b4336b8bef238f7073722f8789d4da9b84f17a021df2e74030b64be995425c6cf5ae9f70
-  data.tar.gz: 546cc421b749cd28393494f10190bd34e9e7ed1ff5170b91a07724fccc94ece8351e03fc3d672e98e3c1e9908aa21abbdf91fc8eb86d0db2426ea9131eb7f0dd
+  metadata.gz: 833577165a1a176f7b3237d59f8bf55339dfc3709bab21a20ce3d463385ab6a98b1184dbb7bb3eb872d8f7f299072050caf0f2fe1f98bedb4744d522c175b343
+  data.tar.gz: e65b27a43d44d32d0ca27b13e1f058f3972448353874f50aecf259c9378644e2fbd781aa21a192c554d8ebf4b110645b03a6058407dde36db97cea48a8561e12

data/Gemfile.lock

@@ -1,28 +1,32 @@
 PATH
   remote: .
   specs:
-    re_sorcery (0.1.0)
+    re_sorcery (0.2.0)
+      addressable (~> 2.8, >= 2.8.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.8.1)
+      public_suffix (>= 2.0.2, < 6.0)
     coderay (1.1.3)
     method_source (1.0.0)
-    minitest (5.14.4)
-    pry (0.14.1)
+    minitest (5.17.0)
+    pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    rake (10.5.0)
+    public_suffix (5.0.1)
+    rake (13.0.6)
 
 PLATFORMS
-  ruby
+  arm64-darwin-21
 
 DEPENDENCIES
-  bundler (~> 2.0)
-  re_sorcery!
-  minitest (~> 5.0)
+  bundler (~> 2.3)
+  minitest (~> 5.16)
   pry
-  rake (~> 10.0)
+  rake (~> 13.0)
+  re_sorcery!
 
 BUNDLED WITH
-   2.0.2
+   2.3.7

data/README.md

@@ -15,11 +15,14 @@ and link validation before sending resources to the client.
   `Array` of `<link>` objects).
 - Each entry in the `:payload` is type checked using a `Decoder` (inspired by [Elm's Decoders]).
 - A `<link>` is a `Hash` with four fields:
-  - `:href`, which is either a `URI` or a `String` that parses as a valid `URI`;
+  - `:href`, which is either a `URI` or a `String` that parses as a valid `URI` ([Addressable] is
+    used for URI-parsing, as it handles URI templates.)
   - `:rel`, which is a white-listed `String`;
   - `:method`, which is also a white-listed `String`; and
   - `:type`, which is a `String`.
 
+[Addressable]: https://github.com/sporkmonger/addressable
+
 Demo:
 
 ```ruby
@@ -33,12 +36,17 @@ class StaticResource
   end
 end
 
-StaticResource.new.resource
-# #<ReSorcery::Result::Ok @value={
-#   :payload=>{:string=>"a string", :number=>42},
-#   :links=>[{:rel=>"self", :href=>"/here", :method=>"get", :type=>"application/json"},
-#            {:rel=>"create", :href=>"/here", :method=>"post", :type=>"application/json"}]
-# }>
+StaticResource.new.as_json
+# {
+#   :payload=>{
+#     :string=>"a string",
+#     :number=>42
+#   }, 
+#   :links=>[
+#     {:rel=>"self", :href=>"/here", :method=>"get", :type=>"application/json"}, 
+#     {:rel=>"create", :href=>"/here", :method=>"post", :type=>"application/json"}
+#   ]
+# }
 ```
 
 ## Installation
@@ -90,8 +98,8 @@ User.new(name: "Spencer", id: 1, admin: true).as_json #=> {
 
 # An invalid `name` raises an error when calling `as_json`
 User.new(name: :Invalid, id: 1).as_json
-# ReSorcery::Error::InvalidResourceError: Error at field `name` of `User`: Expected a(n) String, but
-# got a(n) Symbol
+# ReSorcery::Error::InvalidResourceError: 
+#   Error at field `name` of `User`: Expected kind String, but got Symbol
 ```
 
 The implementation of `ReSorcery#as_json` raises an exception on invalid data, instead of serving

data/lib/re_sorcery/configuration.rb

@@ -14,26 +14,46 @@ module ReSorcery
   #       link_methods ['get', 'post', 'put']
   #     end
   #
-  # @see `Configuration::CONFIGURABLES` for a list of what can be configured and
-  # what value each configurable takes.
+  # @see `Configuration::CONFIGURABLES`, whose keys define the list of
+  # configuration methods. Each entry contains a `:decoder` key, which is used
+  # to check the value passed to the configuration method, and a `:default`
+  # key, which is the default value for that entry.
   #
   module Configuration
     extend Decoder::BuiltinDecoders
 
+    UNIQUE_STRING_OR_SYMBOL = non_empty_array(is(String, Symbol).map(&:to_s)).map(&:uniq)
+    DEFAULT_LINK_METHOD_DECODER = is(Proc)
+      .and { |p| p.arity == 1 || "default_link_method Proc must accept exactly one argument" }
+
     CONFIGURABLES = {
-      link_rels: array(String),
-      link_methods: array(String),
+      link_rels: {
+        decoder: UNIQUE_STRING_OR_SYMBOL,
+        default: %w[self create update destroy].freeze,
+      }.freeze,
+      link_methods: {
+        decoder: UNIQUE_STRING_OR_SYMBOL,
+        default: %w[get post patch put delete].freeze,
+      }.freeze,
+      default_link_method: {
+        decoder: DEFAULT_LINK_METHOD_DECODER,
+        default: ->(link_methods) { link_methods.first }.freeze,
+      }.freeze,
+      default_link_type: {
+        decoder: is(String),
+        default: "application/json",
+      }.freeze,
     }.freeze
 
     def configuration
-      @configuration ||= {}
+      @configuration ||= CONFIGURABLES.transform_values { |v| v.fetch(:default) }
     end
 
-    def configure(&block)
+    def configure(&)
       raise Error::InvalidConfigurationError, @configured if configured?
 
       @configured = "configured at #{caller_locations.first}"
-      instance_exec(&block)
+      instance_exec(&)
     end
 
     private
@@ -42,7 +62,8 @@ module ReSorcery
       @configured ||= false
     end
 
-    CONFIGURABLES.each do |name, decoder|
+    CONFIGURABLES.each do |name, metadata|
+      decoder = metadata.fetch(:decoder)
       define_method(name) do |value|
         decoder.test(value).cata(
           ok: ->(v) { configuration[name] = v },

data/lib/re_sorcery/decoder/builtin_decoders.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module ReSorcery
   class Decoder
     # Common decoders implemented here for convenience
@@ -9,17 +11,60 @@ module ReSorcery
       private
 
       # A Decoder that always succeeds with a given value
+      #
+      # Useful for starting decoder chains that build up successful values.
       def succeed(value)
         Decoder.new { ok(value) }
       end
 
       # A decoder that always fails with some error message
+      #
+      # Useful for starting decoder chains that search for a successful value.
       def fail(message = '`fail` Decoder always fails')
         ArgCheck['message', message, String]
 
         Decoder.new { message }
       end
 
+      # Test if an object is_a?(first_mod) (or is one of a list of modules)
+      #
+      # Note that classes are also modules.
+      #
+      # In general prefer `#is`.
+      #
+      # @param [Module] first_mod
+      # @param [Array<Module>] others
+      # @return [Decoder]
+      def mod(first_mod, *others)
+        all_mods = ([first_mod] + others).map.with_index { |o, i| ArgCheck["mods[#{i}]", o, Module] }
+        raise ReSorcery::Error::ArgumentError, "Do not use `nil`" if all_mods.include?(NilClass)
+
+        mods = all_mods.select { |m| ((m.ancestors - [m]) & all_mods).empty? }
+
+        msg = lambda {
+          prefix = mods.count == 1 ? "Expected" : "Expected one of"
+          "#{prefix} (#{mods.join(' | ')}) but received"
+        }
+
+        Decoder.new { |u| mods.any? { |m| u.is_a?(m) } || "#{msg.call}: #{u.class}" }
+      end
+
+      # Test if an object is one of a specific set of things
+      #
+      # In general prefer `#is`.
+      def one_of_exactly(thing, *others)
+        things = ([thing] + others).to_set
+        nillish = things.include?(nil)
+        raise ReSorcery::Error::ArgumentError, "Do not use `nil`" if nillish
+
+        msg = lambda {
+          prefix = things.count == 1 ? "Expected exactly" : "Expected one of exactly"
+          "#{prefix} (#{things.map(&:inspect).join(' | ')}) but received"
+        }
+
+        Decoder.new { |u| things.include?(u) || "#{msg.call}: #{u.inspect}" }
+      end
+
       # Test if an object is a thing (or one of a list of things)
       #
       # Convenience method for creating common types of `Decoder`s.
@@ -44,7 +89,11 @@ module ReSorcery
       # @return [Decoder]
       def is(thing, *others)
         things = [thing] + others
-        decoders = things.map { |t| make_decoder_from(t) }
+        groups = things.group_by { |t| [t.is_a?(Decoder), t.is_a?(Module)] }
+        decoders =
+          groups.fetch([true, false], []) +
+          (groups[[false, true]].nil? ? [] : [mod(*groups[[false, true]])]) +
+          (groups[[false, false]].nil? ? [] : [one_of_exactly(*groups[[false, false]])])
 
         Decoder.new do |instance|
           test_multiple(decoders, instance).map_error do |errors|
@@ -73,6 +122,19 @@ module ReSorcery
         end
       end
 
+      # Like #array, but test the array contains at least one item
+      #
+      # @param thing @see `is` for details
+      # @param others @see `is` for details
+      # @return [Decoder]
+      def non_empty_array(thing, *others)
+        array(thing, *others).and_then do |a|
+          Decoder.new do
+            a.empty? ? "Expected a non-empty array, but received an empty array" : ok(a)
+          end
+        end
+      end
+
       # Test that an object is a Maybe whose `value` passes some `Decoder`
       #
       # @param thing @see `is` for details

data/lib/re_sorcery/decoder.rb

@@ -42,6 +42,7 @@ module ReSorcery
 
     def initialize(&block)
       @block = block
+      freeze
     end
 
     # Use the decoder to `test` that an `unknown` object satisfies some property
@@ -51,15 +52,15 @@ module ReSorcery
     # @param [unknown] unknown
     # @return [Result]
     def test(unknown)
-      result = @block.call(unknown)
-      case result
+      block_result = @block.call(unknown)
+      case block_result
       when Result::Ok, Result::Err
-        result
+        block_result
       when TrueClass
         ok(unknown)
       else
-        err(result)
-      end.and_then { |r| r.nil? ? err("`nil` was returned on a successful test!") : ok(r) }
+        err(block_result)
+      end
     end
 
     # Apply some block within the context of a successful decoder
@@ -77,6 +78,14 @@ module ReSorcery
     # The second decoder can be chosen based on the (successful) result of the
     # first decoder.
     #
+    # Note: the second decoder decodes the "original" unknown value, not the
+    # potentially-changed result of the first decoder.
+    #
+    #     Decoder.new { |u| u.is_a?(Symbol) || "Not symbol" }
+    #       .map(&:to_s)
+    #       .and_then { |v| Decoder.new { |u| true } } # v is a String & u is a Symbol
+    #       .test(:a_symbol)
+    #
     # The block must return a `Decoder`.
     def and_then(decoder = nil, &block)
       ArgCheck['decoder', decoder, Decoder] unless decoder.nil?
@@ -89,6 +98,24 @@ module ReSorcery
       end
     end
 
+    # Chain decoders and maintain any transformed value
+    #
+    #     pos = is(String, Symbol)
+    #       .map(&:to_sym)
+    #       .and { |s, u| [:a, :b, :c].include?(s) || "Invalid option: #{u.inspect}" }
+    #
+    #     pos.test(:a) == ok(:a)
+    #     pos.test("a") == ok(:a)
+    #     pos.test("d") == err('Invalid option: "d"')
+    #
+    def and
+      and_then do |value|
+        Decoder.new do |unknown|
+          Decoder.new { yield(value, unknown) }.test(value)
+        end
+      end
+    end
+
     # If the `Decoder` failed, try another `Decoder`
     #
     # The block must return a `Decoder`.
@@ -97,18 +124,11 @@ module ReSorcery
 
       Decoder.new do |unknown|
         test(unknown).or_else do |value|
-          decoder ||= ArgCheck['block.call(value)', block.call(value), Decoder]
-
-          decoder.test(unknown)
+          (decoder || ArgCheck['block.call(value)', block.call(value), Decoder]).test(unknown)
         end
       end
     end
 
-    # Chain decoders like `and_then`, but always with a specific decoder
-    def and(&block)
-      and_then { Decoder.new(&block) }
-    end
-
     # Chain decoders like and_then, but use the chain to build an object
     def assign(key, other)
       ArgCheck['key', key, Symbol]

data/lib/re_sorcery/fielded/expand_internal_fields.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "uri"
+require "addressable/uri"
+
 module ReSorcery
   module Fielded
     module ExpandInternalFields
@@ -23,7 +26,7 @@ module ReSorcery
           ok(obj)
         when Array
           expand_for_array(obj)
-        when URI
+        when URI, Addressable::URI
           ok(obj.to_s)
         when Hash
           err("`Hash` cannot be safely expanded as a `field`. Use a `Fielded` class instead.")

data/lib/re_sorcery/fielded.rb

@@ -40,10 +40,9 @@ module ReSorcery
     # @return [Result<String, Hash>]
     def fields
       self.class.instance_exec { @fields ||= [] }.inject(ok({})) do |result_hash, (name, field_hash)|
-        result_hash.and_then do |ok_hash|
+        result_hash.assign(name) do
           field_hash[:type].test(instance_exec(&field_hash[:pro]))
             .and_then { |tested| ExpandInternalFields.expand(tested) }
-            .map { |fielded| ok_hash.merge(name => fielded) }
             .map_error { |error| "Error at field `#{name}` of `#{self.class}`: #{error}" }
         end
       end

data/lib/re_sorcery/linked/link_class_factory.rb

@@ -1,60 +1,72 @@
 # frozen_string_literal: true
 
+require "uri"
+require "addressable/uri"
+
 module ReSorcery
   module Linked
     class LinkClassFactory
-      extend Decoder::BuiltinDecoders
-
-      def self.valid_rels
-        ReSorcery.configuration.fetch(
-          :link_rels,
-          %w[
-            self
-            create
-            update
-            destroy
-          ],
-        )
-      end
+      class << self
+        include Decoder::BuiltinDecoders
 
-      def self.valid_methods
-        ReSorcery.configuration.fetch(
-          :link_methods,
-          %w[
-            get
-            post
-            patch
-            put
-            delete
-          ],
-        )
-      end
+        def make_link_class
+          fields = build_fields
 
-      URI_ABLE = is(String, URI).and do |s|
-        next true if s.is_a?(URI)
+          Class.new do
+            include Fielded
 
-        begin
-          ok(URI.parse(s))
-        rescue URI::InvalidURIError
-          err("Not a valid URI: #{s}")
+            def initialize(args)
+              @args = args
+            end
+
+            fields.each { |(name, decoder, value)| field name, decoder, value }
+          end
         end
-      end
 
-      def self.make_link_class
-        default_method = valid_methods.first
-        this = self
+        private
+
+        def valid_rels
+          ReSorcery.configuration.fetch(:link_rels)
+        end
 
-        Class.new do
-          include Fielded
+        def valid_methods
+          ReSorcery.configuration.fetch(:link_methods)
+        end
 
-          def initialize(args)
-            @args = args
+        def uri_able
+          is(URI, Addressable::URI).or_else do
+            is(String).and_then do
+              Decoder.new do |u|
+                ok(Addressable::URI.parse(u))
+              rescue Addressable::URI::InvalidURIError
+                err("Not a valid URI: #{u}")
+              end
+            end
           end
+        end
+
+        def str_or_sym
+          is(String, Symbol).map(&:to_s)
+        end
+
+        def rel_decoder
+          str_or_sym.and_then { |v| Decoder.new { is(*valid_rels).test(v) } }
+        end
+
+        def method_decoder
+          str_or_sym.and_then { |v| Decoder.new { is(*valid_methods).test(v) } }
+        end
+
+        def build_fields
+          default_method = ReSorcery.configuration.fetch(:default_link_method).call(valid_methods)
+          default_type = ReSorcery.configuration.fetch(:default_link_type)
 
-          field :rel, is(*this.valid_rels), -> { @args[:rel] }
-          field :href, URI_ABLE, -> { @args[:href] }
-          field :method, is(*this.valid_methods), -> { @args.fetch(:method, default_method) }
-          field :type, String, -> { @args.fetch(:type, 'application/json') }
+          [
+            [:rel, rel_decoder, -> { @args[:rel] }],
+            [:href, uri_able, -> { @args[:href] }],
+            [:method, method_decoder, -> { @args.fetch(:method, default_method) }],
+            [:type, String, -> { @args.fetch(:type, default_type) }],
+          ]
         end
       end
     end

data/lib/re_sorcery/linked.rb

@@ -65,9 +65,10 @@ module ReSorcery
     # Define a `Link` for an object
     #
     # @see `ReSorcery::Linked::Link#initialize` for param types
-    def link(rel, href, method = 'get', type = 'application/json')
+    def link(rel, href, method = nil, type = nil)
       klass = Linked.link_class
-      (@_created_links ||= []) << klass.new(rel: rel, href: href, method: method, type: type).fields
+      args = {rel:, href:, method:, type:}.compact
+      (@_created_links ||= []) << klass.new(**args).fields
     end
   end
 end

data/lib/re_sorcery/result/ok.rb

@@ -3,6 +3,14 @@
 module ReSorcery
   module Result
     class Ok
+      class << self
+        def new(value)
+          return Result::Err.new("`nil` was provided as a successful result value!") if value.nil?
+
+          super
+        end
+      end
+
       def initialize(value)
         @value = value
       end

data/lib/re_sorcery/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ReSorcery
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/re_sorcery.gemspec

@@ -14,21 +14,26 @@ Gem::Specification.new do |spec|
 
   # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
 
+  spec.required_ruby_version = '~> 3.1'
+
   spec.metadata["homepage_uri"] = spec.homepage
-  # spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
+  spec.metadata["source_code_uri"] = "https://github.com/spejamchr/re_sorcery"
   # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+  spec.metadata['rubygems_mfa_required'] = 'true'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_runtime_dependency "addressable", "~> 2.8", ">= 2.8.1"
+
+  spec.add_development_dependency "bundler", "~> 2.3"
+  spec.add_development_dependency "minitest", "~> 5.16"
   spec.add_development_dependency "pry"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 13.0"
 end

metadata

@@ -1,43 +1,63 @@
 --- !ruby/object:Gem::Specification
 name: re_sorcery
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Spencer Christiansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-12-21 00:00:00.000000000 Z
+date: 2023-03-10 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.16'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.16'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -58,14 +78,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 description:
 email:
 - jc.spencer92@gmail.com
@@ -106,22 +126,24 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/spejamchr/re_sorcery
+  source_code_uri: https://github.com/spejamchr/re_sorcery
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Create resources with run-time payload type checking and link validation