cuprum-collections 0.4.0 → 0.5.0

data/lib/cuprum/collections/rspec/deferred/commands/build_one_examples.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec/deferred/command_examples'
+require 'cuprum/collections/rspec/deferred/commands'
+
+module Cuprum::Collections::RSpec::Deferred::Commands
+  # Namespace for deferred example groups for validating BuildOne commands.
+  module BuildOneExamples
+    include RSpec::SleepingKingStudios::Deferred::Provider
+
+    deferred_examples 'should implement the BuildOne command' \
+    do |allow_extra_attributes: true|
+      describe '#call' do
+        include Cuprum::Collections::RSpec::Deferred::CommandExamples
+
+        shared_examples 'should build the entity' do
+          it { expect(result).to be_a_passing_result }
+
+          it { expect(result.value).to be == expected_value }
+        end
+
+        let(:attributes) { {} }
+        let(:result)     { command.call(attributes:) }
+        let(:expected_attributes) do
+          attributes
+        end
+        let(:expected_value) do
+          defined?(super()) ? super() : attributes
+        end
+
+        def call_command
+          command.call(attributes:)
+        end
+
+        include_deferred 'should validate the attributes parameter'
+
+        describe 'with an empty attributes hash' do
+          let(:attributes) { {} }
+
+          include_examples 'should build the entity'
+        end
+
+        describe 'with an attributes hash with partial attributes' do
+          let(:attributes) { { title: 'Gideon the Ninth' } }
+
+          include_examples 'should build the entity'
+        end
+
+        describe 'with an attributes hash with full attributes' do
+          let(:attributes) do
+            {
+              title:    'Gideon the Ninth',
+              author:   'Tamsyn Muir',
+              series:   'The Locked Tomb',
+              category: 'Horror'
+            }
+          end
+
+          include_examples 'should build the entity'
+        end
+
+        describe 'with an attributes hash with extra attributes' do
+          let(:attributes) do
+            {
+              title:     'The Book of Lost Tales',
+              audiobook: true
+            }
+          end
+
+          if allow_extra_attributes
+            include_examples 'should build the entity'
+          else
+            # :nocov:
+            let(:valid_attributes) do
+              defined?(super()) ? super() : expected_attributes.keys
+            end
+            let(:expected_error) do
+              Cuprum::Collections::Errors::ExtraAttributes.new(
+                entity_class:,
+                extra_attributes: %w[audiobook],
+                valid_attributes:
+              )
+            end
+
+            it 'should return a failing result' do
+              expect(result).to be_a_failing_result.with_error(expected_error)
+            end
+            # :nocov:
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/collections/rspec/deferred/commands/destroy_one_examples.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec/deferred/command_examples'
+require 'cuprum/collections/rspec/deferred/commands'
+
+module Cuprum::Collections::RSpec::Deferred::Commands
+  # Namespace for deferred example groups for validating DestroyOne commands.
+  module DestroyOneExamples
+    include RSpec::SleepingKingStudios::Deferred::Provider
+
+    deferred_examples 'should implement the DestroyOne command' do
+      describe '#call' do
+        include Cuprum::Collections::RSpec::Deferred::CommandExamples
+
+        let(:query) { collection.query }
+        let(:mapped_data) do
+          defined?(super()) ? super() : data
+        end
+        let(:invalid_primary_key_value) do
+          defined?(super()) ? super() : 100
+        end
+        let(:valid_primary_key_value) do
+          defined?(super()) ? super() : 0
+        end
+
+        def call_command
+          command.call(primary_key:)
+        end
+
+        include_deferred 'should validate the primary key parameter'
+
+        describe 'with an invalid primary key' do
+          let(:primary_key) { invalid_primary_key_value }
+          let(:expected_error) do
+            Cuprum::Collections::Errors::NotFound.new(
+              attribute_name:  collection.primary_key_name,
+              attribute_value: primary_key,
+              collection_name: collection.name,
+              primary_key:     true
+            )
+          end
+
+          it 'should return a failing result' do
+            expect(command.call(primary_key:))
+              .to be_a_failing_result
+              .with_error(expected_error)
+          end
+
+          it 'should not remove an entity from the collection' do
+            expect { command.call(primary_key:) }
+              .not_to(change { query.reset.count })
+          end
+        end
+
+        context 'when the collection has many items' do
+          let(:data) { fixtures_data }
+          let(:matching_data) do
+            mapped_data.find do |item|
+              item[collection.primary_key_name.to_s] == primary_key
+            end
+          end
+          let!(:expected_data) do
+            defined?(super()) ? super() : matching_data
+          end
+
+          describe 'with an invalid primary key' do
+            let(:primary_key) { invalid_primary_key_value }
+            let(:expected_error) do
+              Cuprum::Collections::Errors::NotFound.new(
+                attribute_name:  collection.primary_key_name,
+                attribute_value: primary_key,
+                collection_name: collection.name,
+                primary_key:     true
+              )
+            end
+
+            it 'should return a failing result' do
+              expect(command.call(primary_key:))
+                .to be_a_failing_result
+                .with_error(expected_error)
+            end
+
+            it 'should not remove an entity from the collection' do
+              expect { command.call(primary_key:) }
+                .not_to(change { query.reset.count })
+            end
+          end
+
+          describe 'with a valid primary key' do
+            let(:primary_key) { valid_primary_key_value }
+
+            it 'should return a passing result' do
+              expect(command.call(primary_key:))
+                .to be_a_passing_result
+                .with_value(expected_data)
+            end
+
+            it 'should remove an entity from the collection' do
+              expect { command.call(primary_key:) }
+                .to(
+                  change { query.reset.count }.by(-1)
+                )
+            end
+
+            it 'should remove the entity from the collection' do
+              command.call(primary_key:)
+
+              expect(
+                query.map { |item| item[collection.primary_key_name.to_s] }
+              )
+                .not_to include primary_key
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/collections/rspec/deferred/commands/find_many_examples.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec/deferred/command_examples'
+require 'cuprum/collections/rspec/deferred/commands'
+
+module Cuprum::Collections::RSpec::Deferred::Commands
+  # Namespace for deferred example groups for validating FindMany commands.
+  module FindManyExamples
+    include RSpec::SleepingKingStudios::Deferred::Provider
+
+    deferred_examples 'should implement the FindMany command' do
+      describe '#call' do
+        include Cuprum::Collections::RSpec::Deferred::CommandExamples
+
+        let(:mapped_data) do
+          defined?(super()) ? super() : data
+        end
+        let(:primary_key_name) { defined?(super()) ? super() : 'id' }
+        let(:primary_key_type) { defined?(super()) ? super() : Integer }
+        let(:invalid_primary_key_values) do
+          defined?(super()) ? super() : [100, 101, 102]
+        end
+        let(:valid_primary_key_values) do
+          defined?(super()) ? super() : [0, 1, 2]
+        end
+        let(:primary_keys) { [] }
+        let(:options)      { {} }
+
+        def call_command
+          command.call(primary_keys:, **options)
+        end
+
+        include_deferred 'should validate the primary keys parameter'
+
+        describe 'with an invalid allow_partial value' do
+          let(:options) { super().merge(allow_partial: Object.new.freeze) }
+
+          include_deferred 'should validate the parameter',
+            :allow_partial,
+            'sleeping_king_studios.tools.assertions.boolean'
+        end
+
+        describe 'with an invalid envelope value' do
+          let(:options) { super().merge(envelope: Object.new.freeze) }
+
+          include_deferred 'should validate the parameter',
+            :envelope,
+            'sleeping_king_studios.tools.assertions.boolean'
+        end
+
+        describe 'with an empty array of primary keys' do
+          let(:primary_keys)  { [] }
+          let(:expected_data) { [] }
+
+          it 'should return a passing result' do
+            expect(command.call(primary_keys:))
+              .to be_a_passing_result
+              .with_value(expected_data)
+          end
+        end
+
+        describe 'with an array of invalid primary keys' do
+          let(:primary_keys) { invalid_primary_key_values }
+          let(:expected_error) do
+            Cuprum::Errors::MultipleErrors.new(
+              errors: primary_keys.map do |primary_key|
+                Cuprum::Collections::Errors::NotFound.new(
+                  attribute_name:  collection.primary_key_name,
+                  attribute_value: primary_key,
+                  collection_name: collection.name,
+                  primary_key:     true
+                )
+              end
+            )
+          end
+
+          it 'should return a failing result' do
+            expect(command.call(primary_keys:))
+              .to be_a_failing_result
+              .with_error(expected_error)
+          end
+        end
+
+        context 'when the collection has many items' do
+          let(:data) { fixtures_data }
+          let(:matching_data) do
+            primary_keys
+              .map do |key|
+                mapped_data.find { |item| item[primary_key_name.to_s] == key }
+              end
+          end
+          let(:expected_data) do
+            defined?(super()) ? super() : matching_data
+          end
+
+          describe 'with an empty array of primary keys' do
+            let(:primary_keys)  { [] }
+            let(:expected_data) { [] }
+
+            it 'should return a passing result' do
+              expect(command.call(primary_keys:))
+                .to be_a_passing_result
+                .with_value(expected_data)
+            end
+          end
+
+          describe 'with an array of invalid primary keys' do
+            let(:primary_keys) { invalid_primary_key_values }
+            let(:expected_error) do
+              Cuprum::Errors::MultipleErrors.new(
+                errors: primary_keys.map do |primary_key|
+                  Cuprum::Collections::Errors::NotFound.new(
+                    attribute_name:  collection.primary_key_name,
+                    attribute_value: primary_key,
+                    collection_name: collection.name,
+                    primary_key:     true
+                  )
+                end
+              )
+            end
+
+            it 'should return a failing result' do
+              expect(command.call(primary_keys:))
+                .to be_a_failing_result
+                .with_error(expected_error)
+            end
+          end
+
+          describe 'with a partially valid array of primary keys' do
+            let(:primary_keys) do
+              invalid_primary_key_values + valid_primary_key_values
+            end
+            let(:expected_error) do
+              Cuprum::Errors::MultipleErrors.new(
+                errors: primary_keys.map do |primary_key|
+                  unless invalid_primary_key_values.include?(primary_key)
+                    next nil
+                  end
+
+                  Cuprum::Collections::Errors::NotFound.new(
+                    attribute_name:  collection.primary_key_name,
+                    attribute_value: primary_key,
+                    collection_name: collection.name,
+                    primary_key:     true
+                  )
+                end
+              )
+            end
+
+            it 'should return a failing result' do
+              expect(command.call(primary_keys:))
+                .to be_a_failing_result
+                .with_error(expected_error)
+            end
+          end
+
+          describe 'with a valid array of primary keys' do
+            let(:primary_keys) { valid_primary_key_values }
+
+            it 'should return a passing result' do
+              expect(command.call(primary_keys:))
+                .to be_a_passing_result
+                .with_value(expected_data)
+            end
+
+            describe 'with an ordered array of primary keys' do
+              let(:primary_keys) { valid_primary_key_values.reverse }
+
+              it 'should return a passing result' do
+                expect(command.call(primary_keys:))
+                  .to be_a_passing_result
+                  .with_value(expected_data)
+              end
+            end
+          end
+
+          describe 'with allow_partial: true' do
+            describe 'with an array of invalid primary keys' do
+              let(:primary_keys) { invalid_primary_key_values }
+              let(:expected_error) do
+                Cuprum::Errors::MultipleErrors.new(
+                  errors: invalid_primary_key_values.map do |primary_key|
+                    Cuprum::Collections::Errors::NotFound.new(
+                      attribute_name:  collection.primary_key_name,
+                      attribute_value: primary_key,
+                      collection_name: collection.name,
+                      primary_key:     true
+                    )
+                  end
+                )
+              end
+
+              it 'should return a failing result' do
+                expect(command.call(primary_keys:))
+                  .to be_a_failing_result
+                  .with_error(expected_error)
+              end
+            end
+
+            describe 'with a partially valid array of primary keys' do
+              let(:primary_keys) do
+                invalid_primary_key_values + valid_primary_key_values
+              end
+              let(:expected_error) do
+                Cuprum::Errors::MultipleErrors.new(
+                  errors: primary_keys.map do |primary_key|
+                    unless invalid_primary_key_values.include?(primary_key)
+                      next nil
+                    end
+
+                    Cuprum::Collections::Errors::NotFound.new(
+                      attribute_name:  collection.primary_key_name,
+                      attribute_value: primary_key,
+                      collection_name: collection.name,
+                      primary_key:     true
+                    )
+                  end
+                )
+              end
+
+              it 'should return a passing result' do
+                expect(
+                  command.call(
+                    primary_keys:,
+                    allow_partial: true
+                  )
+                )
+                  .to be_a_passing_result
+                  .with_value(expected_data)
+                  .and_error(expected_error)
+              end
+            end
+
+            describe 'with a valid array of primary keys' do
+              let(:primary_keys) { valid_primary_key_values }
+
+              it 'should return a passing result' do
+                expect(
+                  command.call(
+                    primary_keys:,
+                    allow_partial: true
+                  )
+                )
+                  .to be_a_passing_result
+                  .with_value(expected_data)
+              end
+
+              describe 'with an ordered array of primary keys' do
+                let(:primary_keys) { valid_primary_key_values.reverse }
+
+                it 'should return a passing result' do
+                  expect(
+                    command.call(
+                      primary_keys:,
+                      allow_partial: true
+                    )
+                  )
+                    .to be_a_passing_result
+                    .with_value(expected_data)
+                end
+              end
+            end
+          end
+
+          describe 'with envelope: true' do
+            describe 'with an empty array of primary keys' do
+              let(:primary_keys)  { [] }
+              let(:expected_data) { [] }
+
+              it 'should return a passing result' do
+                expect(
+                  command.call(primary_keys:, envelope: true)
+                )
+                  .to be_a_passing_result
+                  .with_value(match({ collection.name => expected_data }))
+              end
+            end
+
+            describe 'with a valid array of primary keys' do
+              let(:primary_keys) { valid_primary_key_values }
+
+              it 'should return a passing result' do
+                expect(
+                  command.call(primary_keys:, envelope: true)
+                )
+                  .to be_a_passing_result
+                  .with_value(match({ collection.name => expected_data }))
+              end
+
+              describe 'with an ordered array of primary keys' do
+                let(:primary_keys) { valid_primary_key_values.reverse }
+
+                it 'should return a passing result' do
+                  expect(
+                    command.call(primary_keys:, envelope: true)
+                  )
+                    .to be_a_passing_result
+                    .with_value(match({ collection.name => expected_data }))
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/collections/rspec/deferred/commands/find_matching_examples.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec/contracts/query_contracts'
+require 'cuprum/collections/rspec/deferred/command_examples'
+require 'cuprum/collections/rspec/deferred/commands'
+
+module Cuprum::Collections::RSpec::Deferred::Commands
+  # Namespace for deferred example groups for validating FindMatching commands.
+  module FindMatchingExamples
+    include RSpec::SleepingKingStudios::Deferred::Provider
+
+    deferred_examples 'should implement the FindMatching command' do
+      describe '#call' do
+        include Cuprum::Collections::RSpec::Contracts::QueryContracts
+        include Cuprum::Collections::RSpec::Deferred::CommandExamples
+
+        shared_examples 'should return the matching items' do
+          it { expect(result).to be_a_passing_result }
+
+          it { expect(result.value).to be_a Enumerator }
+
+          it { expect(result.value.to_a).to be == expected_data }
+        end
+
+        shared_examples 'should return the wrapped items' do
+          it { expect(result).to be_a_passing_result }
+
+          it { expect(result.value).to be_a Hash }
+
+          it { expect(result.value.keys).to be == [collection.name] }
+
+          it { expect(result.value[collection.name]).to be == expected_data }
+        end
+
+        let(:filter) { nil }
+        let(:limit)  { nil }
+        let(:offset) { nil }
+        let(:order)  { nil }
+        let(:options) do
+          opts = {}
+
+          opts[:limit]  = limit  if limit
+          opts[:offset] = offset if offset
+          opts[:order]  = order  if order
+          opts[:where]  = filter unless filter.nil? || filter.is_a?(Proc)
+
+          opts
+        end
+        let(:block)  { filter.is_a?(Proc) ? filter : nil }
+        let(:result) { command.call(**options, &block) }
+        let(:data)   { [] }
+        let(:filtered_data) do
+          defined?(super()) ? super() : data
+        end
+        let(:matching_data) do
+          defined?(super()) ? super() : filtered_data
+        end
+        let(:expected_data) do
+          defined?(super()) ? super() : matching_data
+        end
+
+        def call_command
+          command.call(**options, &block)
+        end
+
+        describe 'with an invalid envelope value' do
+          let(:options) { super().merge(envelope: Object.new.freeze) }
+
+          include_deferred 'should validate the parameter',
+            :envelope,
+            'sleeping_king_studios.tools.assertions.boolean'
+        end
+
+        describe 'with an invalid limit value' do
+          let(:options) { super().merge(limit: Object.new.freeze) }
+
+          include_deferred 'should validate the parameter',
+            :limit,
+            'sleeping_king_studios.tools.assertions.instance_of',
+            expected: Integer
+        end
+
+        describe 'with an invalid offset value' do
+          let(:options) { super().merge(offset: Object.new.freeze) }
+
+          include_deferred 'should validate the parameter',
+            :offset,
+            'sleeping_king_studios.tools.assertions.instance_of',
+            expected: Integer
+        end
+
+        describe 'with an invalid order value' do
+          let(:options) { super().merge(order: Object.new.freeze) }
+
+          include_deferred 'should validate the parameter',
+            :order,
+            message: 'order is not a valid sort order'
+        end
+
+        describe 'with an invalid where value' do
+          let(:options) { super().merge(where: Object.new.freeze) }
+
+          include_deferred 'should validate the parameter',
+            :where,
+            message: 'where is not a scope or query hash'
+        end
+
+        describe 'with an invalid filter block' do
+          let(:block) { -> {} }
+          let(:expected_error) do
+            an_instance_of(Cuprum::Collections::Errors::InvalidQuery)
+          end
+
+          it 'should return a failing result' do
+            expect(result).to be_a_failing_result.with_error(expected_error)
+          end
+        end
+
+        include_examples 'should return the matching items'
+
+        describe 'with envelope: true' do
+          let(:options) { super().merge(envelope: true) }
+
+          include_examples 'should return the wrapped items'
+        end
+
+        context 'when the collection has many items' do
+          let(:data) { fixtures_data }
+
+          include_contract 'should query the collection' do
+            include_examples 'should return the matching items'
+
+            describe 'with envelope: true' do
+              let(:options) { super().merge(envelope: true) }
+
+              include_examples 'should return the wrapped items'
+            end
+          end
+        end
+      end
+    end
+  end
+end