cuprum-rails 0.1.0

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

@@ -0,0 +1,460 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/rspec'
+
+require 'support/book'
+require 'support/tome'
+
+module Cuprum::Rails::RSpec
+  # Contract validating the behavior of a Rails command implementation.
+  COMMAND_CONTRACT = lambda do
+    describe '.subclass' do
+      let(:subclass) { described_class.subclass }
+      let(:constructor_options) do
+        {
+          record_class: Book,
+          optional_key: 'optional value'
+        }
+      end
+
+      it 'should define the class method' do
+        expect(described_class)
+          .to respond_to(:subclass)
+          .with(0).arguments
+          .and_any_keywords
+      end
+
+      it { expect(subclass).to be_a Class }
+
+      it { expect(subclass).to be < described_class }
+
+      it 'should define the constructor' do
+        expect(subclass)
+          .to respond_to(:new)
+          .with(0).arguments
+          .and_any_keywords
+      end
+
+      it 'should return the record class' do
+        expect(subclass.new(**constructor_options).record_class)
+          .to be record_class
+      end
+
+      it 'should return the options' do
+        expect(subclass.new(**constructor_options).options)
+          .to be == { optional_key: 'optional value' }
+      end
+
+      describe 'with options' do
+        let(:default_options) do
+          {
+            record_class: Book,
+            custom_key:   'custom value'
+          }
+        end
+        let(:constructor_options) do
+          {
+            optional_key: 'optional value'
+          }
+        end
+        let(:subclass) { described_class.subclass(**default_options) }
+
+        it { expect(subclass).to be_a Class }
+
+        it { expect(subclass).to be < described_class }
+
+        it 'should define the constructor' do
+          expect(subclass)
+            .to respond_to(:new)
+            .with(0).arguments
+            .and_any_keywords
+        end
+
+        it 'should return the record class' do
+          expect(subclass.new(**constructor_options).record_class)
+            .to be record_class
+        end
+
+        it 'should return the options' do
+          expect(subclass.new(**constructor_options).options)
+            .to be == {
+              custom_key:   'custom value',
+              optional_key: 'optional value'
+            }
+        end
+      end
+    end
+
+    describe '#collection_name' do
+      let(:expected) { record_class.name.underscore.pluralize }
+
+      include_examples 'should define reader',
+        :collection_name,
+        -> { be == expected }
+
+      context 'when initialized with collection_name: string' do
+        let(:collection_name) { 'books' }
+        let(:constructor_options) do
+          super().merge(collection_name: collection_name)
+        end
+
+        it { expect(command.collection_name).to be == collection_name }
+      end
+
+      context 'when initialized with collection_name: symbol' do
+        let(:collection_name) { :books }
+        let(:constructor_options) do
+          super().merge(collection_name: collection_name)
+        end
+
+        it { expect(command.collection_name).to be == collection_name.to_s }
+      end
+    end
+
+    describe '#member_name' do
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+
+      include_examples 'should have reader',
+        :member_name,
+        -> { record_class.name.underscore }
+
+      context 'when initialized with collection_name: value' do
+        let(:collection_name) { :books }
+
+        it 'should return the singular collection name' do
+          expect(command.member_name)
+            .to be == tools.str.singularize(collection_name.to_s)
+        end
+      end
+
+      context 'when initialized with member_name: string' do
+        let(:member_name)         { 'tome' }
+        let(:constructor_options) { super().merge(member_name: member_name) }
+
+        it 'should return the singular collection name' do
+          expect(command.member_name).to be member_name
+        end
+      end
+
+      context 'when initialized with member_name: symbol' do
+        let(:member_name)         { :tome }
+        let(:constructor_options) { super().merge(member_name: member_name) }
+
+        it 'should return the singular collection name' do
+          expect(command.member_name).to be == member_name.to_s
+        end
+      end
+    end
+
+    describe '#options' do
+      let(:expected_options) do
+        defined?(super()) ? super() : constructor_options
+      end
+
+      include_examples 'should define reader',
+        :options,
+        -> { be == expected_options }
+
+      context 'when initialized with options' do
+        let(:constructor_options) { super().merge({ key: 'value' }) }
+        let(:expected_options)    { super().merge({ key: 'value' }) }
+
+        it { expect(command.options).to be == expected_options }
+      end
+    end
+
+    describe '#primary_key_name' do
+      include_examples 'should define reader', :primary_key_name, :id
+
+      context 'with a record class with custom primary key' do
+        let(:record_class) { Tome }
+
+        include_examples 'should define reader', :primary_key_name, :uuid
+      end
+    end
+
+    describe '#primary_key_type' do
+      include_examples 'should define reader', :primary_key_type, Integer
+
+      context 'with a record class with custom primary key' do
+        let(:record_class) { Tome }
+
+        include_examples 'should define reader', :primary_key_type, String
+      end
+    end
+
+    describe '#record_class' do
+      include_examples 'should define reader',
+        :record_class,
+        -> { record_class }
+    end
+
+    describe '#validate_entity' do
+      let(:expected_error) do
+        type     = record_class
+        contract = Stannum::Contracts::ParametersContract.new do
+          keyword :entity, type
+        end
+        errors = contract.errors_for(
+          {
+            arguments: [],
+            block:     nil,
+            keywords:  { entity: nil }
+          }
+        )
+
+        Cuprum::Collections::Errors::InvalidParameters.new(
+          command: command,
+          errors:  errors
+        )
+      end
+
+      it 'should define the private method' do
+        expect(command)
+          .to respond_to(:validate_entity, true)
+          .with(1).argument
+      end
+
+      describe 'with nil' do
+        it 'should return a failing result' do
+          expect(command.send(:validate_entity, nil))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with an Object' do
+        it 'should return a failing result' do
+          expect(command.send(:validate_entity, Object.new.freeze))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with an invalid record instance' do
+        it 'should return a failing result' do
+          expect(command.send(:validate_entity, Tome.new))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with a valid record instance' do
+        it 'should not return a result' do
+          expect(command.send(:validate_entity, Book.new))
+            .not_to be_a_result
+        end
+      end
+    end
+
+    describe '#validate_primary_key' do
+      let(:primary_key_type) { Integer }
+      let(:expected_error) do
+        type     = primary_key_type
+        contract = Stannum::Contracts::ParametersContract.new do
+          keyword :primary_key, type
+        end
+        errors = contract.errors_for(
+          {
+            arguments: [],
+            block:     nil,
+            keywords:  { primary_key: nil }
+          }
+        )
+
+        Cuprum::Collections::Errors::InvalidParameters.new(
+          command: command,
+          errors:  errors
+        )
+      end
+
+      it 'should define the private method' do
+        expect(command)
+          .to respond_to(:validate_primary_key, true)
+          .with(1).argument
+      end
+
+      describe 'with nil' do
+        it 'should return a failing result' do
+          expect(command.send(:validate_primary_key, nil))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with an Object' do
+        it 'should return a failing result' do
+          expect(command.send(:validate_primary_key, Object.new.freeze))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with a String' do
+        it 'should return a failing result' do
+          expect(command.send(:validate_primary_key, '12345'))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with an Integer' do
+        it 'should not return a result' do
+          expect(command.send(:validate_primary_key, 12_345)).not_to be_a_result
+        end
+      end
+
+      context 'with a record class with custom primary key' do
+        let(:record_class)     { Tome }
+        let(:primary_key_type) { String }
+
+        describe 'with an Integer' do
+          it 'should return a failing result' do
+            expect(command.send(:validate_primary_key, 12_345))
+              .to be_a_failing_result
+              .with_error(expected_error)
+          end
+        end
+
+        describe 'with a String' do
+          it 'should not return a result' do
+            expect(command.send(:validate_primary_key, '12345'))
+              .not_to be_a_result
+          end
+        end
+      end
+    end
+
+    describe '#validate_primary_keys' do
+      let(:primary_keys)     { nil }
+      let(:primary_key_type) { Integer }
+      let(:expected_error) do
+        type     = primary_key_type
+        contract = Stannum::Contracts::ParametersContract.new do
+          keyword :primary_keys,
+            Stannum::Constraints::Types::ArrayType.new(item_type: type)
+        end
+        errors = contract.errors_for(
+          {
+            arguments: [],
+            block:     nil,
+            keywords:  { primary_keys: primary_keys }
+          }
+        )
+
+        Cuprum::Collections::Errors::InvalidParameters.new(
+          command: command,
+          errors:  errors
+        )
+      end
+
+      it 'should define the private method' do
+        expect(command)
+          .to respond_to(:validate_primary_keys, true)
+          .with(1).argument
+      end
+
+      describe 'with nil' do
+        it 'should return a failing result' do
+          expect(command.send(:validate_primary_keys, nil))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with an Object' do
+        it 'should return a failing result' do
+          expect(command.send(:validate_primary_keys, Object.new.freeze))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with a String' do
+        it 'should return a failing result' do
+          expect(command.send(:validate_primary_keys, '12345'))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with an Integer' do
+        it 'should return a failing result' do
+          expect(command.send(:validate_primary_keys, 12_345))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with an empty Array' do
+        it 'should not return a result' do
+          expect(command.send(:validate_primary_keys, []))
+            .not_to be_a_result
+        end
+      end
+
+      describe 'with an Array with nil values' do
+        let(:primary_keys) { Array.new(3, nil) }
+
+        it 'should return a failing result' do
+          expect(command.send(:validate_primary_keys, primary_keys))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with an Array with Object values' do
+        let(:primary_keys) { Array.new(3) { Object.new.freeze } }
+
+        it 'should return a failing result' do
+          expect(command.send(:validate_primary_keys, primary_keys))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with an Array with String values' do
+        let(:primary_keys) { %w[ichi ni san] }
+
+        it 'should return a failing result' do
+          expect(command.send(:validate_primary_keys, primary_keys))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+      end
+
+      describe 'with an Array with Integer values' do
+        it 'should not return a result' do
+          expect(command.send(:validate_primary_keys, [0, 1, 2]))
+            .not_to be_a_result
+        end
+      end
+
+      context 'with a record class with custom primary key' do
+        let(:record_class)     { Tome }
+        let(:primary_key_type) { String }
+
+        describe 'with an Array with String values' do
+          let(:primary_keys) { %w[ichi ni san] }
+
+          it 'should not return a result' do
+            expect(command.send(:validate_primary_keys, primary_keys))
+              .not_to be_a_result
+          end
+        end
+
+        describe 'with an Array with Integer values' do
+          let(:primary_keys) { [0, 1, 2] }
+
+          it 'should return a failing result' do
+            expect(command.send(:validate_primary_keys, primary_keys))
+              .to be_a_failing_result
+              .with_error(expected_error)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/rspec'
+
+module Cuprum::Rails::RSpec
+  # Contract asserting that a Routes object defines the given route.
+  DEFINE_ROUTE_CONTRACT = lambda \
+  do |action_name:, path:, member_action: false, wildcards: {}|
+    describe "##{action_name}_path" do
+      let(:method_name) { "#{action_name}_path" }
+      let(:expected) do
+        next path unless member_action
+
+        primary_key_name  = entity.class.primary_key
+        primary_key_value = entity[primary_key_name]
+
+        path.sub(':id', primary_key_value.to_s)
+      end
+
+      define_method(:route_helper) do
+        scoped = wildcards.empty? ? routes : routes.with_wildcards(wildcards)
+
+        if member_action
+          scoped.send(method_name, entity)
+        else
+          scoped.send(method_name)
+        end
+      end
+
+      it 'should define the helper method' do
+        if member_action
+          expect(routes).to respond_to(method_name).with(1).argument
+        else
+          expect(routes).to respond_to(method_name).with(0).arguments
+        end
+      end
+
+      it 'should return the route path' do
+        expect(route_helper).to be == expected
+      end
+
+      if member_action
+        describe 'when the entity is nil' do
+          let(:entity)        { nil }
+          let(:error_message) { 'missing wildcard :id' }
+
+          it 'should raise an exception' do
+            expect { route_helper }
+              .to raise_error(
+                described_class::MissingWildcardError,
+                error_message
+              )
+          end
+        end
+      end
+
+      wildcards.each do |key, _|
+        wildcard = key.to_s.end_with?('_id') ? key.intern : :"#{key}_id"
+
+        describe "when the #{wildcard.inspect} wildcard is undefined" do
+          let(:error_message) { "missing wildcard #{wildcard.inspect}" }
+
+          define_method(:route_helper) do
+            scoped = routes.with_wildcards(wildcards.except(key))
+
+            if member_action
+              scoped.send(method_name, entity)
+            else
+              scoped.send(method_name)
+            end
+          end
+
+          it 'should raise an exception' do
+            expect { route_helper }
+              .to raise_error(
+                described_class::MissingWildcardError,
+                error_message
+              )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/rails/rspec.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Namespace for RSpec contracts, which validate collection implementations.
+  module RSpec; end
+end

data/lib/cuprum/rails/serializers/json/active_record_serializer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/serializers/json'
+require 'cuprum/rails/serializers/json/serializer'
+
+module Cuprum::Rails::Serializers::Json
+  # Converts ActiveRecord record to JSON using the #as_json method.
+  class ActiveRecordSerializer < Cuprum::Rails::Serializers::Json::Serializer
+    # Converts the ActiveRecord record to JSON.
+    #
+    # Calls and returns the #as_json method of the record.
+    #
+    # @param record [ActiveRecord::Base] The record to convert to JSON.
+    #
+    # @return [Hash] a JSON-compatible representation of the record.
+    def call(record, **_)
+      unless record.is_a?(ActiveRecord::Base)
+        raise ArgumentError, 'object must be an ActiveRecord record'
+      end
+
+      record.as_json
+    end
+  end
+end

data/lib/cuprum/rails/serializers/json/array_serializer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/serializers/json'
+require 'cuprum/rails/serializers/json/serializer'
+
+module Cuprum::Rails::Serializers::Json
+  # Converts Array data structures to JSON based on configured serializers.
+  class ArraySerializer < Cuprum::Rails::Serializers::Json::Serializer
+    # Converts the array to JSON using the given serializers.
+    #
+    # First, #call finds the best serializer from the :serializers Hash for each
+    # item in the Array. 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, and the results are
+    # combined into a new Array and returned.
+    #
+    # @param array [Array] The array to convert to JSON.
+    # @param serializers [Hash<Class, #call>] The serializers for different
+    #   object types.
+    #
+    # @return [Array] a JSON-compatible representation of the array.
+    #
+    # @raise UndefinedSerializerError if there is no matching serializer for
+    #   any of the items in the array.
+    def call(array, serializers:)
+      raise ArgumentError, 'object must be an Array' unless array.is_a?(Array)
+
+      array.map { |item| super(item, serializers: serializers) }
+    end
+
+    private
+
+    def handle_recursion!(_object)
+      # Call serializes the items, not the array. Because the context changes,
+      # we don't need to check for recursion (unless the Array contains itself,
+      # in which case here there be dragons).
+      yield
+    end
+  end
+end