cuprum-collections 0.1.0

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

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/queries'
+require 'cuprum/collections/rspec'
+
+module Cuprum::Collections::RSpec
+  OPERATORS = Cuprum::Collections::Queries::Operators
+  private_constant :OPERATORS
+
+  # Shared contexts for specs that define querying behavior.
+  QUERYING_CONTEXTS = lambda do
+    let(:filter)    { nil }
+    let(:strategy)  { nil }
+    let(:limit)     { nil }
+    let(:offset)    { nil }
+    let(:order)     { nil }
+
+    shared_context 'when the query has limit: value' do
+      let(:limit)         { 3 }
+      let(:matching_data) { super()[0...limit] }
+    end
+
+    shared_context 'when the query has offset: value' do
+      let(:offset)        { 2 }
+      let(:matching_data) { super()[offset..] || [] }
+    end
+
+    shared_context 'when the query has order: a simple ordering' do
+      let(:order)         { :title }
+      let(:matching_data) { super().sort_by { |item| item['title'] } }
+    end
+
+    shared_context 'when the query has order: a complex ordering' do
+      let(:order) do
+        {
+          author: :asc,
+          title:  :desc
+        }
+      end
+      let(:matching_data) do
+        super().sort do |u, v|
+          cmp = u['author'] <=> v['author']
+
+          cmp.zero? ? (v['title'] <=> u['title']) : cmp
+        end
+      end
+    end
+
+    shared_context 'when the query has where: a simple block filter' do
+      let(:filter) { -> { { author: 'Ursula K. LeGuin' } } }
+      let(:matching_data) do
+        super().select { |item| item['author'] == 'Ursula K. LeGuin' }
+      end
+    end
+
+    shared_context 'when the query has where: a complex block filter' do
+      let(:filter) do
+        lambda do
+          {
+            author: equals('Ursula K. LeGuin'),
+            series: not_equal('Earthsea')
+          }
+        end
+      end
+      let(:matching_data) do
+        super()
+          .select { |item| item['author'] == 'Ursula K. LeGuin' }
+          .reject { |item| item['series'] == 'Earthsea' }
+      end
+    end
+
+    shared_context 'when the query has where: a greater_than filter' do
+      let(:filter) { -> { { published_at: greater_than('1970-12-01') } } }
+      let(:matching_data) do
+        super().select { |item| item['published_at'] > '1970-12-01' }
+      end
+    end
+
+    shared_context 'when the query has where: a greater_than_or_equal_to' \
+                   ' filter' \
+    do
+      let(:filter) do
+        -> { { published_at: greater_than_or_equal_to('1970-12-01') } }
+      end
+      let(:matching_data) do
+        super().select { |item| item['published_at'] >= '1970-12-01' }
+      end
+    end
+
+    shared_context 'when the query has where: a less_than filter' do
+      let(:filter) { -> { { published_at: less_than('1970-12-01') } } }
+      let(:matching_data) do
+        super().select { |item| item['published_at'] < '1970-12-01' }
+      end
+    end
+
+    shared_context 'when the query has where: a less_than_or_equal_to filter' do
+      let(:filter) do
+        -> { { published_at: less_than_or_equal_to('1970-12-01') } }
+      end
+      let(:matching_data) do
+        super().select { |item| item['published_at'] <= '1970-12-01' }
+      end
+    end
+
+    shared_context 'when the query has where: an equal block filter' do
+      let(:filter) { -> { { author: equals('Ursula K. LeGuin') } } }
+      let(:matching_data) do
+        super().select { |item| item['author'] == 'Ursula K. LeGuin' }
+      end
+    end
+
+    shared_context 'when the query has where: a not_equal block filter' do
+      let(:filter) { -> { { author: not_equal('Ursula K. LeGuin') } } }
+      let(:matching_data) do
+        super().reject { |item| item['author'] == 'Ursula K. LeGuin' }
+      end
+    end
+
+    shared_context 'when the query has where: a not_one_of block filter' do
+      let(:filter) do
+        -> { { series: not_one_of(['Earthsea', 'The Lord of the Rings']) } }
+      end
+      let(:matching_data) do
+        super().reject do |item|
+          ['Earthsea', 'The Lord of the Rings'].include?(item['series'])
+        end
+      end
+    end
+
+    shared_context 'when the query has where: a one_of block filter' do
+      let(:filter) do
+        -> { { series: one_of(['Earthsea', 'The Lord of the Rings']) } }
+      end
+      let(:matching_data) do
+        super().select do |item|
+          ['Earthsea', 'The Lord of the Rings'].include?(item['series'])
+        end
+      end
+    end
+
+    shared_context 'when the query has multiple query options' do
+      let(:filter)    { -> { { author: 'Ursula K. LeGuin' } } }
+      let(:strategy)  { nil }
+      let(:order)     { { title: :desc } }
+      let(:limit)     { 2 }
+      let(:offset)    { 1 }
+      let(:matching_data) do
+        super()
+          .select { |item| item['author'] == 'Ursula K. LeGuin' }
+          .sort { |u, v| v['title'] <=> u['title'] }
+          .slice(1, 2) || []
+      end
+    end
+  end
+
+  # Contract validating the behavior objects that perform queries.
+  QUERYING_CONTRACT = lambda do |block:, operators: OPERATORS.values|
+    wrap_context 'when the query has limit: value' do
+      instance_exec(&block)
+    end
+
+    wrap_context 'when the query has offset: value' do
+      instance_exec(&block)
+    end
+
+    wrap_context 'when the query has order: a simple ordering' do
+      instance_exec(&block)
+    end
+
+    wrap_context 'when the query has order: a complex ordering' do
+      instance_exec(&block)
+    end
+
+    context 'when the query has where: a block filter' do
+      context 'with a simple filter' do
+        include_context 'when the query has where: a simple block filter'
+
+        instance_exec(&block)
+      end
+
+      context 'with a complex filter' do
+        include_context 'when the query has where: a complex block filter'
+
+        if operators.include?(OPERATORS::EQUAL) &&
+           operators.include?(OPERATORS::NOT_EQUAL)
+          instance_exec(&block)
+        else
+          # :nocov:
+          pending
+          # :nocov:
+        end
+      end
+
+      context 'with an equals filter' do
+        include_context 'when the query has where: an equal block filter'
+
+        if operators.include?(OPERATORS::EQUAL)
+          instance_exec(&block)
+        else
+          # :nocov:
+          pending
+          # :nocov:
+        end
+      end
+
+      context 'with a greater_than filter' do
+        include_context 'when the query has where: a greater_than filter'
+
+        if operators.include?(OPERATORS::GREATER_THAN)
+          instance_exec(&block)
+        else
+          # :nocov:
+          pending
+          # :nocov:
+        end
+      end
+
+      context 'with a greater_than_or_equal_to filter' do
+        include_context \
+          'when the query has where: a greater_than_or_equal_to filter'
+
+        if operators.include?(OPERATORS::GREATER_THAN_OR_EQUAL_TO)
+          instance_exec(&block)
+        else
+          # :nocov:
+          pending
+          # :nocov:
+        end
+      end
+
+      context 'with a less_than filter' do
+        include_context 'when the query has where: a less_than filter'
+
+        if operators.include?(OPERATORS::LESS_THAN)
+          instance_exec(&block)
+        else
+          # :nocov:
+          pending
+          # :nocov:
+        end
+      end
+
+      context 'with a less_than_or_equal_to filter' do
+        include_context \
+          'when the query has where: a less_than_or_equal_to filter'
+
+        if operators.include?(OPERATORS::LESS_THAN_OR_EQUAL_TO)
+          instance_exec(&block)
+        else
+          # :nocov:
+          pending
+          # :nocov:
+        end
+      end
+
+      context 'with a not_equal filter' do
+        include_context 'when the query has where: a not_equal block filter'
+
+        if operators.include?(OPERATORS::NOT_EQUAL)
+          instance_exec(&block)
+        else
+          # :nocov:
+          pending
+          # :nocov:
+        end
+      end
+
+      context 'with a not_one_of filter' do
+        include_context 'when the query has where: a not_one_of block filter'
+
+        if operators.include?(OPERATORS::NOT_ONE_OF)
+          instance_exec(&block)
+        else
+          # :nocov:
+          pending
+          # :nocov:
+        end
+      end
+
+      context 'with a one_of filter' do
+        include_context 'when the query has where: a one_of block filter'
+
+        if operators.include?(OPERATORS::ONE_OF)
+          instance_exec(&block)
+        else
+          # :nocov:
+          pending
+          # :nocov:
+        end
+      end
+    end
+
+    wrap_context 'when the query has multiple query options' do
+      instance_exec(&block)
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec'
+
+module Cuprum::Collections::RSpec
+  # Contract validating the behavior of an UpdateOne command implementation.
+  UPDATE_ONE_COMMAND_CONTRACT = lambda do
+    describe '#call' do
+      let(:mapped_data) do
+        defined?(super()) ? super() : data
+      end
+      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(: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
+        let(:expected_error) do
+          Cuprum::Collections::Errors::NotFound.new(
+            collection_name:    collection_name,
+            primary_key_name:   primary_key_name,
+            primary_key_values: attributes[primary_key_name]
+          )
+        end
+        let(:matching_data) { mapped_data.first }
+
+        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
+
+      context 'when the item exists in the collection' do
+        let(:data) { fixtures_data }
+        let(:matching_data) do
+          mapped_data.first.merge(super())
+        end
+
+        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 not append an item to the collection' do
+          expect { command.call(entity: entity) }
+            .not_to(change { query.reset.count })
+        end
+
+        it 'should set the attributes' do
+          command.call(entity: entity)
+
+          expect(scoped.to_a.first).to be == expected_data
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/rspec'
+
+module Cuprum::Collections::RSpec
+  # Contract validating the behavior of a ValidateOne command implementation.
+  VALIDATE_ONE_COMMAND_CONTRACT = lambda do |default_contract:|
+    describe '#call' do
+      it 'should validate the :contract keyword' do
+        expect(command)
+          .to validate_parameter(:call, :contract)
+          .with_value(Object.new.freeze)
+          .using_constraint(Stannum::Constraints::Base, optional: true)
+      end
+
+      it 'should validate the :entity keyword' do
+        expect(command)
+          .to validate_parameter(:call, :entity)
+          .with_value(Object.new.freeze)
+          .using_constraint(entity_type)
+      end
+
+      describe 'with contract: nil' do
+        if default_contract
+          context 'when the entity does not match the default contract' do
+            let(:attributes) { invalid_default_attributes }
+            let(:expected_error) do
+              Cuprum::Collections::Errors::FailedValidation.new(
+                entity_class: entity.class,
+                errors:       expected_errors
+              )
+            end
+
+            it 'should return a failing result' do
+              expect(command.call(entity: entity))
+                .to be_a_failing_result
+                .with_error(expected_error)
+            end
+          end
+
+          context 'when the entity matches the default contract' do
+            let(:attributes) { valid_default_attributes }
+
+            it 'should return a passing result' do
+              expect(command.call(entity: entity))
+                .to be_a_passing_result
+                .with_value(entity)
+            end
+          end
+        else
+          let(:attributes) { valid_attributes }
+          let(:expected_error) do
+            Cuprum::Collections::Errors::MissingDefaultContract.new(
+              entity_class: entity.class
+            )
+          end
+
+          it 'should return a failing result' do
+            expect(command.call(entity: entity))
+              .to be_a_failing_result
+              .with_error(expected_error)
+          end
+        end
+      end
+
+      describe 'with contract: value' do
+        context 'when the entity does not match the contract' do
+          let(:attributes) { invalid_attributes }
+          let(:errors)     { contract.errors_for(entity) }
+          let(:expected_error) do
+            Cuprum::Collections::Errors::FailedValidation.new(
+              entity_class: entity.class,
+              errors:       errors
+            )
+          end
+
+          it 'should return a failing result' do
+            expect(command.call(contract: contract, entity: entity))
+              .to be_a_failing_result
+              .with_error(expected_error)
+          end
+        end
+
+        context 'when the entity matches the contract' do
+          let(:attributes) { valid_attributes }
+
+          it 'should return a passing result' do
+            expect(command.call(contract: contract, entity: entity))
+              .to be_a_passing_result
+              .with_value(entity)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cuprum/collections/rspec.rb

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

data/lib/cuprum/collections/version.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Cuprum
+  module Collections
+    # @api private
+    #
+    # The current version of the gem.
+    #
+    # @see http://semver.org/
+    module Version
+      # Major version.
+      MAJOR = 0
+      # Minor version.
+      MINOR = 1
+      # Patch version.
+      PATCH = 0
+      # Prerelease version.
+      PRERELEASE = nil
+      # Build metadata.
+      BUILD = nil
+
+      class << self
+        # Generates the gem version string from the Version constants.
+        #
+        # Inlined here because dependencies may not be loaded when processing a
+        # gemspec, which results in the user being unable to install the gem for
+        # the first time.
+        #
+        # @see SleepingKingStudios::Tools::SemanticVersion#to_gem_version
+        def to_gem_version
+          str = +"#{MAJOR}.#{MINOR}.#{PATCH}"
+
+          prerelease = value_of(:PRERELEASE)
+          str << ".#{prerelease}" if prerelease
+
+          build = value_of(:BUILD)
+          str << ".#{build}" if build
+
+          str
+        end
+
+        private
+
+        def value_of(constant)
+          return nil unless const_defined?(constant)
+
+          value = const_get(constant)
+
+          return nil if value.respond_to?(:empty?) && value.empty?
+
+          value
+        end
+      end
+    end
+
+    # @return [String] the current version of the gem.
+    VERSION = Version.to_gem_version
+  end
+end

data/lib/cuprum/collections.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+# A Ruby implementation of the command pattern.
+module Cuprum
+  # A data abstraction layer based on the Cuprum library.
+  module Collections
+    autoload :Base,    'cuprum/collections/base'
+    autoload :Basic,   'cuprum/collections/basic'
+    autoload :Command, 'cuprum/collections/command'
+
+    # @return [String] the absolute path to the gem directory.
+    def self.gem_path
+      sep     = File::SEPARATOR
+      pattern = /#{sep}lib#{sep}cuprum#{sep}?\z/
+
+      __dir__.sub(pattern, '')
+    end
+
+    # @return [String] The current version of the gem.
+    def self.version
+      VERSION
+    end
+  end
+end