cuprum-rails 0.1.0 → 0.2.0

data/lib/cuprum/rails/rspec/contracts/routes_contracts.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/contract'
+
+require 'cuprum/rails/rspec/contracts'
+
+module Cuprum::Rails::RSpec::Contracts
+  # Namespace for RSpec contracts for Routes objects.
+  module RoutesContracts
+    # Contract asserting that the given collection route helper is defined.
+    module ShouldDefineCollectionRouteContract
+      extend RSpec::SleepingKingStudios::Contract
+
+      # @!method apply(example_group, constructor_keywords: [])
+      #   Adds the contract to the example group.
+      #
+      #   @param example_group [RSpec::Core::ExampleGroup] the example group to
+      #     which the contract is applied.
+      #   @param action_name [String, Symbol] the name of the route action.
+      #   @param path [String] the expected path for the route helper.
+      #   @param options [Hash] additional options for the contract.
+      #
+      #   @option options wildcards [Hash{String=>String}] the required
+      #     wildcards for generating the route.
+      contract do |action_name:, path:, **options|
+        options[:wildcards] = options.fetch(:wildcards, {}).stringify_keys
+        expected_wildcards  =
+          path.split('/').select { |str| str.start_with?(':') }
+
+        describe "##{action_name}_path" do
+          let(:method_name) { "#{action_name}_path" }
+          let(:wildcards)   { options[:wildcards] }
+          let(:expected) do
+            expected_wildcards.reduce(path) do |resolved, key|
+              resolved.sub(key, resolve_wildcard(key))
+            end
+          end
+          let(:error_class) do
+            Cuprum::Rails::Routes::MissingWildcardError
+          end
+          let(:error_message) do
+            "missing wildcard #{expected_wildcards.first}"
+          end
+
+          def resolve_wildcard(key)
+            key   = key.sub(/\A:/, '')
+            value =
+              wildcards.fetch(key) { wildcards.fetch(key.sub(/_id\z/, '')) }
+
+            return value.to_s unless value.class.respond_to?(:primary_key)
+
+            primary_key = value.class.primary_key
+
+            value[primary_key].to_s
+          end
+
+          it 'should define the helper method' do
+            expect(subject)
+              .to respond_to(method_name)
+              .with(0).arguments
+              .and_any_keywords
+          end
+
+          if expected_wildcards.empty?
+            it { expect(subject.send(method_name)).to be == expected }
+          else
+            it 'should raise an exception' do
+              expect { subject.send(method_name) }
+                .to raise_error(error_class, error_message)
+            end
+
+            expected_wildcards.each do |key|
+              describe "with wildcards: missing #{key}" do
+                let(:wildcards) do
+                  wildcard = key[1..]
+
+                  super().except(wildcard, wildcard[...-3])
+                end
+                let(:error_message) { "missing wildcard #{key}" }
+
+                it 'should raise an exception' do
+                  expect { subject.send(method_name, **wildcards) }
+                    .to raise_error(error_class, error_message)
+                end
+              end
+
+              context "when the routes defines wildcards: missing #{key}" do
+                let(:wildcards) do
+                  wildcard = key[1..]
+
+                  super().except(wildcard, wildcard[...-3])
+                end
+                let(:error_message) { "missing wildcard #{key}" }
+
+                it 'should raise an exception' do
+                  expect { subject.with_wildcards(wildcards).send(method_name) }
+                    .to raise_error(error_class, error_message)
+                end
+              end
+            end
+
+            describe 'with wildcards: matching wildcards' do
+              it 'should generate the path' do
+                expect(subject.send(method_name, **wildcards)).to be == expected
+              end
+            end
+
+            context 'when the routes defines wildcards: matching wildcards' do
+              it 'should generate the path' do
+                expect(subject.with_wildcards(wildcards).send(method_name))
+                  .to be == expected
+              end
+
+              describe 'with wildcards: value' do
+                let(:other_wildcards) do
+                  expected_wildcards.each.with_index.to_h
+                end
+
+                it 'should generate the path' do
+                  expect(
+                    subject
+                      .with_wildcards(other_wildcards)
+                      .send(method_name, **wildcards)
+                  )
+                    .to be == expected
+                end
+              end
+            end
+          end
+
+          describe 'with wildcards: extra wildcards' do
+            let(:wildcards) { super().merge('other_id' => 'value') }
+
+            it 'should generate the path' do
+              expect(subject.send(method_name, **wildcards)).to be == expected
+            end
+          end
+
+          context 'when the routes defines wildcards: extra wildcards' do
+            let(:wildcards) { super().merge('other_id' => 'value') }
+
+            it 'should generate the path' do
+              expect(subject.with_wildcards(wildcards).send(method_name))
+                .to be == expected
+            end
+          end
+        end
+      end
+    end
+
+    # Contract asserting that the given member route helper is defined.
+    module ShouldDefineMemberRouteContract
+      extend RSpec::SleepingKingStudios::Contract
+
+      # @!method apply(example_group, constructor_keywords: [])
+      #   Adds the contract to the example group.
+      #
+      #   @param example_group [RSpec::Core::ExampleGroup] the example group to
+      #     which the contract is applied.
+      #   @param action_name [String, Symbol] the name of the route action.
+      #   @param path [String] the expected path for the route helper.
+      #   @param options [Hash] additional options for the contract.
+      #
+      #   @option options wildcards [Hash{String=>String}] the required
+      #     wildcards for generating the route.
+      contract do |action_name:, path:, **options|
+        options[:wildcards] = options.fetch(:wildcards, {}).stringify_keys
+        expected_wildcards  =
+          path.split('/').select { |str| str.start_with?(':') && str != ':id' }
+
+        describe "##{action_name}_path" do
+          let(:configured_wildcards) { options[:wildcards] }
+          let(:method_name)          { "#{action_name}_path" }
+          let(:wildcards)            { options[:wildcards] }
+          let(:entity_value)         { options[:wildcards].fetch('id') }
+          let(:expected) do
+            [':id', *expected_wildcards].reduce(path) do |resolved, key|
+              resolved.sub(key, resolve_wildcard(key))
+            end
+          end
+          let(:error_class) do
+            Cuprum::Rails::Routes::MissingWildcardError
+          end
+          let(:error_message) do
+            "missing wildcard #{expected_wildcards.first}"
+          end
+
+          def resolve_wildcard(key)
+            key   = key.sub(/\A:/, '')
+            value =
+              configured_wildcards
+                .stringify_keys
+                .fetch(key) { wildcards.fetch(key.sub(/_id\z/, '')) }
+
+            return value.to_s unless value.class.respond_to?(:primary_key)
+
+            primary_key = value.class.primary_key
+
+            value[primary_key].to_s
+          end
+
+          it 'should define the helper method' do
+            expect(subject)
+              .to respond_to(method_name)
+              .with(0..1).arguments
+              .and_any_keywords
+          end
+
+          if expected_wildcards.empty?
+            it 'should raise an exception' do
+              expect { subject.send(method_name) }
+                .to raise_error(error_class, 'missing wildcard :id')
+            end
+
+            describe 'with entity: value' do
+              it 'should generate the path' do
+                expect(subject.send(method_name, entity_value))
+                  .to be == expected
+              end
+            end
+
+            describe 'with wildcards: matching wildcards' do
+              it 'should generate the path' do
+                expect(subject.send(method_name, **wildcards))
+                  .to be == expected
+              end
+
+              describe 'with entity: value' do
+                let(:other_wildcards) do
+                  [':id', expected_wildcards].each.with_index.to_h
+                end
+
+                it 'should generate the path' do
+                  expect(
+                    subject.send(method_name, entity_value, **other_wildcards)
+                  )
+                    .to be == expected
+                end
+              end
+            end
+
+            context 'when the routes defines wildcards: matching wildcards' do
+              it 'should generate the path' do
+                expect(subject.with_wildcards(**wildcards).send(method_name))
+                  .to be == expected
+              end
+
+              describe 'with entity: value' do
+                let(:other_wildcards) do
+                  [':id', expected_wildcards].each.with_index.to_h
+                end
+
+                it 'should generate the path' do
+                  expect(
+                    subject
+                      .with_wildcards(**other_wildcards)
+                      .send(method_name, entity_value)
+                  )
+                    .to be == expected
+                end
+              end
+            end
+          else
+            it 'should raise an exception' do
+              expect { subject.send(method_name) }
+                .to raise_error(error_class, error_message)
+            end
+
+            expected_wildcards.each do |key|
+              describe "with wildcards: missing #{key}" do
+                let(:wildcards) do
+                  wildcard = key[1..]
+
+                  super().except(wildcard, wildcard[...-3])
+                end
+                let(:error_message) { "missing wildcard #{key}" }
+
+                it 'should raise an exception' do
+                  expect { subject.send(method_name, **wildcards) }
+                    .to raise_error(error_class, error_message)
+                end
+              end
+
+              context "when the routes defines wildcards: missing #{key}" do
+                let(:wildcards) do
+                  wildcard = key[1..]
+
+                  super().except(wildcard, wildcard[...-3])
+                end
+                let(:error_message) { "missing wildcard #{key}" }
+
+                it 'should raise an exception' do
+                  expect { subject.with_wildcards(wildcards).send(method_name) }
+                    .to raise_error(error_class, error_message)
+                end
+              end
+            end
+
+            describe 'with entity: value' do
+              it 'should raise an exception' do
+                expect { subject.send(method_name) }
+                  .to raise_error(error_class, error_message)
+              end
+
+              describe 'with wildcards: matching wildcards' do
+                let(:wildcards) { super().except('id') }
+
+                it 'should generate the path' do
+                  expect(subject.send(method_name, entity_value, **wildcards))
+                    .to be == expected
+                end
+              end
+
+              context 'when the routes defines wildcards: matching wildcards' do
+                let(:wildcards) { super().except('id') }
+
+                it 'should generate the path' do
+                  expect(
+                    subject
+                      .with_wildcards(wildcards)
+                      .send(method_name, entity_value)
+                  )
+                    .to be == expected
+                end
+              end
+            end
+
+            describe 'with wildcards: matching wildcards' do
+              it 'should generate the path' do
+                expect(subject.send(method_name, **wildcards))
+                  .to be == expected
+              end
+            end
+
+            context 'when the routes defines wildcards: matching wildcards' do
+              it 'should generate the path' do
+                expect(subject.with_wildcards(wildcards).send(method_name))
+                  .to be == expected
+              end
+            end
+          end
+
+          describe 'with wildcards: extra wildcards' do
+            let(:wildcards) { super().merge('other_id' => 'value') }
+
+            it 'should generate the path' do
+              expect(subject.send(method_name, **wildcards)).to be == expected
+            end
+          end
+
+          context 'when the routes defines wildcards: extra wildcards' do
+            let(:wildcards) { super().merge('other_id' => 'value') }
+
+            it 'should generate the path' do
+              expect(subject.with_wildcards(wildcards).send(method_name))
+                .to be == expected
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/rails/rspec/contracts/serializers_contracts.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'rspec/sleeping_king_studios/contract'
+
+require 'cuprum/rails/rspec/contracts'
+
+module Cuprum::Rails::RSpec::Contracts
+  # Namespace for contracts that specify serialization behavior.
+  module SerializersContracts
+    # Contract specifying that a serializer serializes the expected properties.
+    module ShouldSerializeAttributesContract
+      extend RSpec::SleepingKingStudios::Contract
+
+      # @method apply(example_group, *attribute_names, **attribute_values)
+      #   Adds the contract to the example group.
+      #
+      #   @param example_group [RSpec::Core::ExampleGroup] The example group to
+      #     which the contract is applied.
+      #   @param attribute_names [Array] The names of the attributes to
+      #     serialize. The value for each attribute should match the value of
+      #     the attribute on the original object.
+      #   @param attribute_values [Hash] The names and values of attributes to
+      #     serialize. The value of the serialized attribute should match the
+      #     given value.
+
+      contract do |*attribute_names, **attribute_values|
+        let(:serializers) do
+          return super() if defined?(super())
+
+          Cuprum::Rails::Serializers::Json.default_serializers
+        end
+        let(:context) do
+          return super() if defined?(super())
+
+          Cuprum::Rails::Serializers::Context.new(serializers: serializers)
+        end
+        let(:expected_attributes) do
+          tools = SleepingKingStudios::Tools::Toolbelt.instance
+
+          attribute_names
+            .to_h do |attr_name|
+              [attr_name, context.serialize(object.send(attr_name))]
+            end # rubocop:disable Style/MultilineBlockChain
+            .merge(attribute_values)
+            .then { |hsh| tools.hash_tools.convert_keys_to_strings(hsh) }
+        end
+        let(:serialized) { serializer.call(object, context: context) }
+
+        it 'should serialize the expected attributes' do
+          expect(serialized.keys).to contain_exactly(*expected_attributes.keys)
+        end
+
+        attribute_names.each do |attr_name|
+          it "should serialize the #{attr_name.inspect} attribute" do
+            expect(serialized[attr_name.to_s])
+              .to be == expected_attributes[attr_name.to_s]
+          end
+        end
+
+        attribute_values.each do |attr_name, attr_value|
+          it "should serialize the #{attr_name.inspect} attribute" do
+            attr_value = instance_exec(&attr_value) if attr_value.is_a?(Proc)
+
+            expect(serialized[attr_name.to_s]).to be == attr_value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/rails/rspec/contracts.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/rspec'
+
+module Cuprum::Rails::RSpec
+  # Namespace for RSpec contract objects.
+  module Contracts; end
+end

data/lib/cuprum/rails/rspec/matchers/be_a_result_matcher.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/rspec/matchers'
+
+module Cuprum::Rails::RSpec::Matchers
+  # Asserts the actual object is a result object with the specified properties.
+  #
+  # @see Cuprum::RSpec::BeAResultMatcher.
+  class BeAResultMatcher < Cuprum::RSpec::BeAResultMatcher
+    # @param expected_class [Class] the expected class of result. Defaults to
+    #   Cuprum::Result.
+    def initialize(expected_class = nil)
+      super
+
+      @expected_metadata = DEFAULT_VALUE
+    end
+
+    # Sets a metadata expectation on the matcher.
+    #
+    # Calls to #matches? will fail unless the result responds to #metadata? and
+    # has the specified metadata.
+    def with_metadata(metadata)
+      @expected_metadata = metadata
+
+      self
+    end
+    alias and_metadata with_metadata
+
+    private
+
+    attr_reader :expected_metadata
+
+    def expected_metadata?
+      expected_metadata != DEFAULT_VALUE
+    end
+
+    def expected_properties
+      return super unless expected_metadata?
+
+      super.merge('metadata' => expected_metadata)
+    end
+
+    def metadata_failure_message
+      return '' if metadata_matches?
+
+      unless actual.respond_to?(:metadata)
+        return "\n  actual does not respond to #metadata"
+      end
+
+      "#{pad_key('expected metadata')}#{inspect_expected(expected_metadata)}" \
+        "#{pad_key('actual metadata')}#{result.metadata.inspect}"
+    end
+
+    def metadata_matches?
+      return @metadata_matches unless @metadata_matches.nil?
+
+      return @metadata_matches unless expected_metadata?
+
+      return @metadata_matches = false unless actual.respond_to?(:metadata)
+
+      @metadata_matches = compare_items(expected_metadata, result.metadata)
+    end
+  end
+end

data/lib/cuprum/rails/rspec/matchers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/rspec'
+
+module Cuprum::Rails::RSpec
+  # Namespace for custom RSpec matchers.
+  module Matchers
+    autoload :BeAResultMatcher,
+      'cuprum/rails/rspec/matchers/be_a_result_matcher'
+
+    # Asserts that the object is a result with status: :failure.
+    #
+    # @param expected_class [Class] the expected class of result. Defaults to
+    #   Cuprum::Result.
+    #
+    # @return [Cuprum::Rails::RSpec::Matchers::BeAResultMatcher] the generated
+    #   matcher.
+    def be_a_failing_result(expected_class = nil)
+      be_a_result(expected_class).with_status(:failure)
+    end
+
+    # Asserts that the object is a Cuprum::Result with status: :success.
+    #
+    # @param expected_class [Class] the expected class of result. Defaults to
+    #   Cuprum::Result.
+    #
+    # @return [Cuprum::Rails::RSpec::Matchers::BeAResultMatcher] the generated
+    #   matcher.
+    def be_a_passing_result(expected_class = nil)
+      be_a_result(expected_class).with_status(:success).and_error(nil)
+    end
+
+    # Asserts that the object is a Cuprum::Result.
+    #
+    # @return [Cuprum::Rails::RSpec::Matchers::BeAResultMatcher] the generated
+    #   matcher.
+    def be_a_result(expected_class = nil)
+      Cuprum::Rails::RSpec::Matchers::BeAResultMatcher.new(expected_class)
+    end
+  end
+end

data/lib/cuprum/rails/serializers/base_serializer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/serializers'
+
+module Cuprum::Rails::Serializers
+  # Converts objects or data structures based on configured serializers.
+  class BaseSerializer
+    # Error class used when a serializer calls itself.
+    class RecursiveSerializerError < StandardError; end
+
+    # Error class used when there is no matching serializer for the object.
+    class UndefinedSerializerError < StandardError; end
+
+    # @return [Cuprum::Rails::Serializers::Serializer] a cached instance
+    #   of the serializer.
+    def self.instance
+      @instance ||= new
+    end
+
+    # Converts the object to a serialized representation.
+    #
+    # First, #call finds the best serializer from the :serializers Hash. This is
+    # done by walking up the object class's ancestors to find the closest
+    # ancestor which is a key in the :serializers Hash. The corresponding value
+    # is then called with the object.
+    #
+    # @param object [Object] The object to serialize.
+    # @param context [Cuprum::Rails::Serializers::Context] The serialization
+    #   context, which includes the configured serializers for attributes or
+    #   collection items.
+    #
+    # @return [Object] a serialized representation of the object.
+    #
+    # @raise RecursiveSerializerError if the serializer would create an infinite
+    #   loop, e.g. by calling itself.
+    # @raise UndefinedSerializerError if there is no matching serializer for
+    #   the object.
+    def call(object, context:)
+      handle_recursion!(object, context: context)
+
+      context.serialize(object)
+    end
+
+    private
+
+    def allow_recursion?
+      false
+    end
+
+    def handle_recursion!(object, context:)
+      return if allow_recursion?
+
+      return unless context.serializer_for(object).instance_of?(self.class)
+
+      raise RecursiveSerializerError,
+        "invalid serializer for #{object.class.name} - recursive calls to " \
+        "#{self.class.name}#call"
+    end
+  end
+end

data/lib/cuprum/rails/serializers/context.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/serializers'
+
+module Cuprum::Rails::Serializers
+  # Encapsulates and applies configuration for performing serialization.
+  class Context
+    # Error class used when there is no matching serializer for the object.
+    class UndefinedSerializerError < StandardError; end
+
+    # @param serializers [Hash<Class, Object>] The configured serializers for
+    #   different object types.
+    def initialize(serializers:)
+      @serializers = serializers
+    end
+
+    # @return [Hash<Class, Object>] The configured serializers for different
+    #   object types.
+    attr_reader :serializers
+
+    # Finds and calls the configured serializer for the given object.
+    #
+    # @param object [Object] The object to serialize.
+    #
+    # @return [Object] the serialized representation of the object.
+    #
+    # @raise [UndefinedSerializerError] if there is no configured serializer for
+    #   the object.
+    #
+    # @see #serializer_for
+    def serialize(object)
+      serializer_for(object).call(object, context: self)
+    end
+
+    # Finds and initializes the configured serializer for the given object.
+    #
+    # If the configured serializer is a Class and responds to the .instance
+    # class method, then #serializer_for will return the value of .instance. If
+    # the configured serializer is a Class but does not respond to .instance, a
+    # new instance of the serializer class will be created using .new and
+    # returned. If the configured serializer is not a Class, #serializer_for
+    # will return the configured serializer.
+    #
+    # The return value is cached across multiple calls to #serializer_for.
+    #
+    # @param object [Object] The object to serialize.
+    #
+    # @return [Object] the serializer instance for that object.
+    #
+    # @raise [UndefinedSerializerError] if there is no configured serializer for
+    #   the object.
+    def serializer_for(object)
+      (@cached_serializers ||= {})[object.class] ||= find_serializer_for(object)
+    end
+
+    private
+
+    def find_serializer_class_for(object)
+      object.class.ancestors.each do |ancestor|
+        configured = serializers[ancestor]
+
+        return configured if configured
+      end
+
+      nil
+    end
+
+    def find_serializer_for(object)
+      configured = find_serializer_class_for(object)
+
+      if configured.nil?
+        raise UndefinedSerializerError,
+          "no serializer defined for #{object.class.name}",
+          caller(1..-1)
+      end
+
+      return configured unless configured.is_a?(Class)
+
+      return configured.instance if configured.respond_to?(:instance)
+
+      configured.new
+    end
+  end
+end