cuprum-collections 0.1.0

data/lib/cuprum/collections/rspec/find_matching_command_contract.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'stannum/rspec/validate_parameter'
+
+require 'cuprum/collections/constraints/ordering'
+require 'cuprum/collections/rspec'
+require 'cuprum/collections/rspec/querying_contract'
+
+module Cuprum::Collections::RSpec
+  # Contract validating the behavior of a FindMatching command implementation.
+  FIND_MATCHING_COMMAND_CONTRACT = lambda do
+    include Stannum::RSpec::Matchers
+
+    describe '#call' do
+      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
+
+      include_contract Cuprum::Collections::RSpec::QUERYING_CONTEXTS
+
+      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(:matching_data) { data }
+      let(:expected_data) do
+        defined?(super()) ? super() : matching_data
+      end
+
+      it 'should validate the :envelope keyword' do
+        expect(command)
+          .to validate_parameter(:call, :envelope)
+          .using_constraint(Stannum::Constraints::Boolean.new)
+      end
+
+      it 'should validate the :limit keyword' do
+        expect(command)
+          .to validate_parameter(:call, :limit)
+          .with_value(Object.new)
+          .using_constraint(Integer, required: false)
+      end
+
+      it 'should validate the :offset keyword' do
+        expect(command)
+          .to validate_parameter(:call, :offset)
+          .with_value(Object.new)
+          .using_constraint(Integer, required: false)
+      end
+
+      it 'should validate the :order keyword' do
+        constraint = Cuprum::Collections::Constraints::Ordering.new
+
+        expect(command)
+          .to validate_parameter(:call, :order)
+          .with_value(Object.new)
+          .using_constraint(constraint, required: false)
+      end
+
+      it 'should validate the :scope keyword' do
+        expect(command)
+          .to validate_parameter(:call, :scope)
+          .using_constraint(
+            Stannum::Constraints::Type.new(query.class, optional: true)
+          )
+          .with_value(Object.new.freeze)
+      end
+
+      it 'should validate the :where keyword' do
+        expect(command).to validate_parameter(:call, :where)
+      end
+
+      include_examples 'should return the matching items'
+
+      include_contract Cuprum::Collections::RSpec::QUERYING_CONTRACT,
+        block: lambda {
+          include_examples 'should return the matching items'
+        }
+
+      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
+
+      describe 'with envelope: true' do
+        let(:options) { super().merge(envelope: true) }
+
+        include_examples 'should return the wrapped items'
+
+        include_contract Cuprum::Collections::RSpec::QUERYING_CONTRACT,
+          block: lambda {
+            include_examples 'should return the wrapped items'
+          }
+      end
+
+      context 'when the collection has many items' do
+        let(:data) { fixtures_data }
+
+        include_examples 'should return the matching items'
+
+        include_contract Cuprum::Collections::RSpec::QUERYING_CONTRACT,
+          block: lambda {
+            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'
+
+          include_contract Cuprum::Collections::RSpec::QUERYING_CONTRACT,
+            block: lambda {
+              include_examples 'should return the wrapped items'
+            }
+        end
+
+        describe 'with scope: query' do
+          let(:scope_filter) { -> { {} } }
+          let(:options)      { super().merge(scope: scope) }
+
+          describe 'with a scope that does not match any values' do
+            let(:scope_filter)  { -> { { series: 'Mistborn' } } }
+            let(:matching_data) { [] }
+
+            include_examples 'should return the matching items'
+          end
+
+          describe 'with a scope that matches some values' do
+            let(:scope_filter) { -> { { series: nil } } }
+            let(:matching_data) do
+              super().select { |item| item['series'].nil? }
+            end
+
+            include_examples 'should return the matching items'
+
+            describe 'with a where filter' do
+              let(:filter)  { -> { { author: 'Ursula K. LeGuin' } } }
+              let(:options) { super().merge(where: filter) }
+              let(:matching_data) do
+                super().select { |item| item['author'] == 'Ursula K. LeGuin' }
+              end
+
+              include_examples 'should return the matching items'
+            end
+          end
+
+          describe 'with a scope that matches all values' do
+            let(:scope_filter) { -> { { id: not_equal(nil) } } }
+
+            include_examples 'should return the matching items'
+
+            describe 'with a where filter' do
+              let(:filter)  { -> { { author: 'Ursula K. LeGuin' } } }
+              let(:options) { super().merge(where: filter) }
+              let(:matching_data) do
+                super().select { |item| item['author'] == 'Ursula K. LeGuin' }
+              end
+
+              include_examples 'should return the matching items'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/collections/rspec/find_one_command_contract.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec'
+
+module Cuprum::Collections::RSpec
+  # Contract validating the behavior of a FindOne command implementation.
+  FIND_ONE_COMMAND_CONTRACT = lambda do
+    describe '#call' do
+      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_value) do
+        defined?(super()) ? super() : 100
+      end
+      let(:valid_primary_key_value) do
+        defined?(super()) ? super() : 0
+      end
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+
+      it 'should validate the :envelope keyword' do
+        expect(command)
+          .to validate_parameter(:call, :envelope)
+          .using_constraint(Stannum::Constraints::Boolean.new)
+      end
+
+      it 'should validate the :primary_key keyword' do
+        expect(command)
+          .to validate_parameter(:call, :primary_key)
+          .using_constraint(primary_key_type)
+      end
+
+      it 'should validate the :scope keyword' do
+        expect(command)
+          .to validate_parameter(:call, :scope)
+          .using_constraint(
+            Stannum::Constraints::Type.new(query.class, optional: true)
+          )
+          .with_value(Object.new.freeze)
+      end
+
+      describe 'with an invalid primary key' do
+        let(:primary_key) { invalid_primary_key_value }
+        let(:expected_error) do
+          Cuprum::Collections::Errors::NotFound.new(
+            collection_name:    command.collection_name,
+            primary_key_name:   primary_key_name,
+            primary_key_values: primary_key
+          )
+        end
+
+        it 'should return a failing result' do
+          expect(command.call(primary_key: primary_key))
+            .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
+          mapped_data.find { |item| item[primary_key_name.to_s] == primary_key }
+        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(
+              collection_name:    command.collection_name,
+              primary_key_name:   primary_key_name,
+              primary_key_values: primary_key
+            )
+          end
+
+          it 'should return a failing result' do
+            expect(command.call(primary_key: primary_key))
+              .to be_a_failing_result
+              .with_error(expected_error)
+          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: primary_key))
+              .to be_a_passing_result
+              .with_value(expected_data)
+          end
+        end
+
+        describe 'with envelope: true' do
+          let(:member_name) { tools.str.singularize(collection_name) }
+
+          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: primary_key, envelope: true))
+                .to be_a_passing_result
+                .with_value({ member_name => expected_data })
+            end
+          end
+        end
+
+        describe 'with scope: query' do
+          let(:scope_filter) { -> { {} } }
+
+          describe 'with a scope that does not match the key' do
+            let(:scope_filter) { -> { { author: 'Ursula K. LeGuin' } } }
+
+            describe 'with an valid primary key' do
+              let(:primary_key) { valid_primary_key_value }
+              let(:expected_error) do
+                Cuprum::Collections::Errors::NotFound.new(
+                  collection_name:    command.collection_name,
+                  primary_key_name:   primary_key_name,
+                  primary_key_values: primary_key
+                )
+              end
+
+              it 'should return a failing result' do
+                expect(command.call(primary_key: primary_key, scope: scope))
+                  .to be_a_failing_result
+                  .with_error(expected_error)
+              end
+            end
+          end
+
+          describe 'with a scope that matches the key' do
+            let(:scope_filter) { -> { { author: 'J.R.R. Tolkien' } } }
+
+            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: primary_key))
+                  .to be_a_passing_result
+                  .with_value(expected_data)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/collections/rspec/fixtures.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec'
+
+module Cuprum::Collections::RSpec
+  # Sample data for validating collection implementations.
+  BOOKS_FIXTURES = [
+    {
+      'id'           => 0,
+      'title'        => 'The Hobbit',
+      'author'       => 'J.R.R. Tolkien',
+      'series'       => nil,
+      'category'     => 'Science Fiction and Fantasy',
+      'published_at' => '1937-09-21'
+    },
+    {
+      'id'           => 1,
+      'title'        => 'The Silmarillion',
+      'author'       => 'J.R.R. Tolkien',
+      'series'       => nil,
+      'category'     => 'Science Fiction and Fantasy',
+      'published_at' => '1977-09-15'
+    },
+    {
+      'id'           => 2,
+      'title'        => 'The Fellowship of the Ring',
+      'author'       => 'J.R.R. Tolkien',
+      'series'       => 'The Lord of the Rings',
+      'category'     => 'Science Fiction and Fantasy',
+      'published_at' => '1954-07-29'
+    },
+    {
+      'id'           => 3,
+      'title'        => 'The Two Towers',
+      'author'       => 'J.R.R. Tolkien',
+      'series'       => 'The Lord of the Rings',
+      'category'     => 'Science Fiction and Fantasy',
+      'published_at' => '1954-11-11'
+    },
+    {
+      'id'           => 4,
+      'title'        => 'The Return of the King',
+      'author'       => 'J.R.R. Tolkien',
+      'series'       => 'The Lord of the Rings',
+      'category'     => 'Science Fiction and Fantasy',
+      'published_at' => '1955-10-20'
+    },
+    {
+      'id'           => 5,
+      'title'        => 'The Word for World is Forest',
+      'author'       => 'Ursula K. LeGuin',
+      'series'       => nil,
+      'category'     => 'Science Fiction and Fantasy',
+      'published_at' => '1972-03-13'
+    },
+    {
+      'id'           => 6,
+      'title'        => 'The Ones Who Walk Away From Omelas',
+      'author'       => 'Ursula K. LeGuin',
+      'series'       => nil,
+      'category'     => 'Science Fiction and Fantasy',
+      'published_at' => '1973-10-01'
+    },
+    {
+      'id'           => 7,
+      'title'        => 'A Wizard of Earthsea',
+      'author'       => 'Ursula K. LeGuin',
+      'series'       => 'Earthsea',
+      'category'     => 'Science Fiction and Fantasy',
+      'published_at' => '1968-11-01'
+    },
+    {
+      'id'           => 8,
+      'title'        => 'The Tombs of Atuan',
+      'author'       => 'Ursula K. LeGuin',
+      'series'       => 'Earthsea',
+      'category'     => 'Science Fiction and Fantasy',
+      'published_at' => '1970-12-01'
+    },
+    {
+      'id'           => 9,
+      'title'        => 'The Farthest Shore',
+      'author'       => 'Ursula K. LeGuin',
+      'series'       => 'Earthsea',
+      'category'     => 'Science Fiction and Fantasy',
+      'published_at' => '1972-09-01'
+    }
+  ].map(&:freeze).freeze
+end

data/lib/cuprum/collections/rspec/insert_one_command_contract.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec'
+
+module Cuprum::Collections::RSpec
+  # Contract validating the behavior of an InsertOne command implementation.
+  INSERT_ONE_COMMAND_CONTRACT = lambda do
+    describe '#call' do
+      let(:matching_data) { attributes }
+      let(:expected_data) do
+        defined?(super()) ? super() : matching_data
+      end
+      let(:primary_key_name) do
+        defined?(super()) ? super() : :id
+      end
+      let(:primary_key_type) do
+        defined?(super()) ? super() : Integer
+      end
+      let(:scoped) do
+        key    = primary_key_name
+        value  = entity[primary_key_name.to_s]
+
+        query.where { { key => value } }
+      end
+
+      it 'should validate the :entity keyword' do
+        expect(command)
+          .to validate_parameter(:call, :entity)
+          .using_constraint(entity_type)
+      end
+
+      context 'when the item does not exist in the collection' do
+        it 'should return a passing result' do
+          expect(command.call(entity: entity))
+            .to be_a_passing_result
+            .with_value(be == expected_data)
+        end
+
+        it 'should append an item to the collection' do
+          expect { command.call(entity: entity) }
+            .to(
+              change { query.reset.count }
+              .by(1)
+            )
+        end
+
+        it 'should add the entity to the collection' do
+          expect { command.call(entity: entity) }
+            .to change(scoped, :exists?)
+            .to be true
+        end
+
+        it 'should set the attributes' do
+          command.call(entity: entity)
+
+          expect(scoped.to_a.first).to be == expected_data
+        end
+      end
+
+      context 'when the item exists in the collection' do
+        let(:data) { fixtures_data }
+        let(:expected_error) do
+          Cuprum::Collections::Errors::AlreadyExists.new(
+            collection_name:    collection_name,
+            primary_key_name:   primary_key_name,
+            primary_key_values: attributes[primary_key_name]
+          )
+        end
+
+        it 'should return a failing result' do
+          expect(command.call(entity: entity))
+            .to be_a_failing_result
+            .with_error(expected_error)
+        end
+
+        it 'should not append an item to the collection' do
+          expect { command.call(entity: entity) }
+            .not_to(change { query.reset.count })
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/collections/rspec/query_builder_contract.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec'
+
+module Cuprum::Collections::RSpec
+  # Contract validating the behavior of a QueryBuilder implementation.
+  QUERY_BUILDER_CONTRACT = lambda do
+    describe '#base_query' do
+      include_examples 'should define reader', :base_query, -> { base_query }
+    end
+
+    describe '#call' do
+      let(:criteria)  { [['title', :equal, 'The Naked Sun']] }
+      let(:expected)  { criteria }
+      let(:filter)    { { title: 'The Naked Sun' } }
+      let(:strategy)  { :custom }
+      let(:parser) do
+        instance_double(
+          Cuprum::Collections::Queries::Parse,
+          call: Cuprum::Result.new(value: criteria)
+        )
+      end
+      let(:query) do
+        builder.call(strategy: strategy, where: filter)
+      end
+
+      before(:example) do
+        allow(Cuprum::Collections::Queries::Parse)
+          .to receive(:new)
+          .and_return(parser)
+      end
+
+      it 'should define the method' do
+        expect(builder).to respond_to(:call)
+          .with(0).arguments
+          .and_keywords(:strategy, :where)
+      end
+
+      it 'should parse the criteria' do
+        builder.call(strategy: strategy, where: filter)
+
+        expect(parser)
+          .to have_received(:call)
+          .with(strategy: strategy, where: filter)
+      end
+
+      it { expect(query).to be_a base_query.class }
+
+      it { expect(query).not_to be base_query }
+
+      it { expect(query.criteria).to be == expected }
+
+      describe 'with strategy: :unsafe' do
+        let(:strategy) { :unsafe }
+        let(:filter)   { criteria }
+
+        it 'should not parse the criteria' do
+          builder.call(strategy: strategy, where: filter)
+
+          expect(parser).not_to have_received(:call)
+        end
+
+        it { expect(query.criteria).to be == expected }
+      end
+
+      context 'when the query has existing criteria' do
+        let(:old_criteria) { [['genre', :eq, 'Science Fiction']] }
+        let(:expected)     { old_criteria + criteria }
+        let(:base_query)   { super().send(:with_criteria, old_criteria) }
+
+        it { expect(query.criteria).to be == expected }
+      end
+
+      context 'when the parser is unable to parse the query' do
+        let(:error)  { Cuprum::Error.new(message: 'Something went wrong.') }
+        let(:result) { Cuprum::Result.new(error: error) }
+
+        before(:example) do
+          allow(parser).to receive(:call).and_return(result)
+        end
+
+        it 'should raise an exception' do
+          expect do
+            builder.call(strategy: strategy, where: filter)
+          end
+            .to raise_error Cuprum::Collections::QueryBuilder::ParseError,
+              error.message
+        end
+      end
+    end
+  end
+end