cuprum-collections 0.1.0

data/lib/cuprum/collections/query.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+require 'cuprum/collections/queries/ordering'
+
+module Cuprum::Collections
+  # Abstract base class for collection Query implementations.
+  class Query
+    UNDEFINED = Object.new.freeze
+    private_constant :UNDEFINED
+
+    def initialize
+      @criteria = []
+    end
+
+    # Returns a normalized representation of the query criteria.
+    #
+    # The query criteria define which data from the collection matches the
+    # query. Specifically, an item in the collection matches the query if and
+    # only if it matches each criterion. If the query has no criteria, then it
+    # will match all items in the collection.
+    #
+    # Each criterion is represented as an Array with three elements:
+    # - The name of the property or column to select by.
+    # - The operation to filter, such as :eq (an equality operation).
+    # - The expected value.
+    #
+    # For example, a query that selects all items whose :series property is
+    # equal to 'The Lord of the Rings' would have the following criterion:
+    # `[:series, :eq, 'The Lord of the Rings']`.
+    #
+    # @return [Array<Array>] the query criteria.
+    #
+    # @see #where
+    def criteria
+      @criteria.dup
+    end
+
+    # Sets or returns the maximum number of items returned by the query.
+    #
+    # @overload limit
+    #   @return [Integer, nil] the current limit for the query.
+    #
+    # @overload limit(count)
+    #   Returns a copy of the query with the specified limit.
+    #
+    #   The query will return at most the specified number of items.
+    #
+    #   When #limit is called on a query that already defines a limit, the old
+    #   limit is replaced with the new.
+    #
+    #   @param count [Integer] the maximum number of items to return.
+    #
+    #   @return [Query] the copy of the query.
+    def limit(count = UNDEFINED)
+      return @limit if count == UNDEFINED
+
+      validate_limit(count)
+
+      dup.tap { |copy| copy.with_limit(count) }
+    end
+
+    # Sets or returns the number of ordered items skipped by the query.
+    #
+    # @overload offset
+    #   @return [Integer, nil] the current offset for the query.
+    #
+    # @overload offset(count)
+    #   Returns a copy of the query with the specified offset.
+    #
+    #   The query will skip the specified number of matching items, and return
+    #   only matching items after the given offset. If the total number of
+    #   matching items is less than or equal to the offset, the query will not
+    #   return any items.
+    #
+    #   When #offset is called on a query that already defines an offset, the
+    #   old offset is replaced with the new.
+    #
+    #   @param count [Integer] the number of items to skip.
+    #
+    #   @return [Query] the copy of the query.
+    def offset(count = UNDEFINED)
+      return @offset if count == UNDEFINED
+
+      validate_offset(count)
+
+      dup.tap { |copy| copy.with_offset(count) }
+    end
+
+    # Returns a copy of the query with the specified order.
+    #
+    # The query will find the matching items, sort them in the specified order,
+    # and then apply limit and/or offset (if applicable) to determine the final
+    # returned items.
+    #
+    # When #order is called on a query that already defines an ordering, the old
+    # ordering is replaced with the new.
+    #
+    # @return [Query] the copy of the query.
+    #
+    # @example Sorting By Attribute Names
+    #   # This query will sort books by author (ascending), then by title
+    #   # (ascending) within authors.
+    #   query = query.order(:author, :title)
+    #
+    # @example Sorting With Directions
+    #   # This query will sort books by series (ascending), then by the date of
+    #   # publication (descending) within series.
+    #   query = query.order({ series: :asc, published_at: :desc })
+    #
+    # @overload order
+    #   @return [Hash{String,Symbol=>Symbol}] the current ordering for the
+    #     query.
+    #
+    # @overload order(*attributes)
+    #   Orders the results by the given attributes, ascending, and in the
+    #   specified order, i.e. items with the same value of the first attribute
+    #   will be sorted by the second (if any), and so on.
+    #
+    #   @param attributes [Array<String, Symbol>] The attributes to order by.
+    #
+    # @overload order(attributes)
+    #   Orders the results by the given attributes and sort directions, and in
+    #   the specified order.
+    #
+    #   @param attributes [Hash{String,Symbol=>Symbol}] The attributes to order
+    #     by. The hash keys should be the names of attributes or columns, and
+    #     the corresponding values should be the sort direction for that
+    #     attribute, either :asc or :desc.
+    def order(*attributes)
+      return @order if attributes.empty?
+
+      normalized = Cuprum::Collections::Queries::Ordering.normalize(*attributes)
+
+      dup.tap { |copy| copy.with_order(normalized) }
+    end
+    alias order_by order
+
+    # Returns a copy of the query with no cached query results.
+    #
+    # Once the query has been called (e.g. by calling #each or #to_a), the
+    # matching data is cached. If the underlying collection changes, those
+    # changes will not be reflected in the query.
+    #
+    # Calling #reset clears the cached results. The next time the query is
+    # called, the results will be drawn from the current collection state.
+    #
+    # @return [Cuprum::Collections::Query] a copy of the query with a cleared
+    #   results cache.
+    def reset
+      dup.reset!
+    end
+
+    # Returns a copy of the query with the specified filters.
+    #
+    # The given parameters are used to construct query criteria, which define
+    # which data from the collection matches the query. Specifically, an item in
+    # the collection matches the query if and only if it matches each criterion.
+    # If the query has no criteria, then it will match all items in the
+    # collection.
+    #
+    # When #where is called on a query that already defines criteria, then the
+    # new criteria are appended to the old. Any items in the collection must
+    # match both the old and the new criteria to be returned by the query.
+    #
+    # @example Filtering Data By Equality
+    #   # The query will only return items whose author is 'J.R.R. Tolkien'.
+    #   query = query.where { { author: 'J.R.R. Tolkien' } }
+    #
+    # @example Filtering Data By Operator
+    #   # The query will only return items whose author is 'J.R.R. Tolkien',
+    #   # and whose series is not 'The Lord of the Rings'.
+    #   query = query.where do
+    #     {
+    #       author: eq('J.R.R. Tolkien'),
+    #       series: ne('The Lord of the Rings')
+    #     }
+    #   end
+    #
+    # @overload where(&block)
+    #   @yield The given block is passed to a QueryBuilder, which converts the
+    #     block to query criteria and generates a new query using those
+    #     criteria.
+    #
+    #   @yieldreturn [Hash] The filters to apply to the query. The hash keys
+    #     should be the names of attributes or columns, and the corresponding
+    #     values should be either the literal value for that attribute or a
+    #     method call for a valid operation defined for the query.
+    #
+    # @see #criteria
+    def where(filter = nil, strategy: nil, &block)
+      filter ||= block
+
+      return dup if filter.nil? && strategy.nil?
+
+      query_builder.call(strategy: strategy, where: filter)
+    end
+
+    protected
+
+    def reset!
+      # :nocov:
+      self
+      # :nocov:
+    end
+
+    def with_criteria(criteria)
+      @criteria += criteria
+
+      self
+    end
+
+    def with_limit(count)
+      @limit = count
+
+      self
+    end
+
+    def with_offset(count)
+      @offset = count
+
+      self
+    end
+
+    def with_order(order)
+      @order = order
+
+      self
+    end
+
+    private
+
+    def validate_limit(count)
+      return if count.is_a?(Integer) && !count.negative?
+
+      raise ArgumentError, 'limit must be a non-negative integer', caller(1..-1)
+    end
+
+    def validate_offset(count)
+      return if count.is_a?(Integer) && !count.negative?
+
+      raise ArgumentError,
+        'offset must be a non-negative integer',
+        caller(1..-1)
+    end
+  end
+end

data/lib/cuprum/collections/query_builder.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+require 'cuprum/collections/queries/parse'
+
+module Cuprum::Collections
+  # Internal class that handles parsing and applying criteria to a query.
+  class QueryBuilder
+    # Exception class to be raised when the query cannot be parsed.
+    class ParseError < RuntimeError; end
+
+    # @param base_query [Cuprum::Collections::Query] The original query.
+    def initialize(base_query)
+      @base_query = base_query
+    end
+
+    # @return [Cuprum::Collections::Query] the original query.
+    attr_reader :base_query
+
+    # Returns a copy of the query updated with the generated criteria.
+    #
+    # Classifies the parameters to determine parsing strategy, then uses that
+    # strategy to parse the parameters into an array of criteria. Then, copies
+    # the original query and updates the copy with the parsed criteria.
+    #
+    # @param strategy [Symbol, nil] The specified strategy for parsing the given
+    #   filter into criteria. If nil, the builder will attempt to guess the
+    #   strategy based on the given filter.
+    # @param where [Object] The filter used to match items in the collection.
+    #
+    # @return [Cuprum::Collections::Query] the copied and updated query.
+    def call(where:, strategy: nil)
+      criteria =
+        if strategy == :unsafe
+          where
+        else
+          parse_criteria(strategy: strategy, where: where)
+        end
+
+      build_query(criteria)
+    end
+
+    private
+
+    def build_query(criteria)
+      base_query
+        .dup
+        .send(:with_criteria, criteria)
+    end
+
+    def parse_criteria(strategy:, where:)
+      result = Cuprum::Collections::Queries::Parse
+        .new
+        .call(strategy: strategy, where: where)
+
+      return result.value if result.success?
+
+      raise ParseError, result.error.message
+    end
+  end
+end

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

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/presence'
+require 'stannum/constraints/types/hash_with_indifferent_keys'
+require 'stannum/rspec/validate_parameter'
+
+require 'cuprum/collections/rspec'
+
+module Cuprum::Collections::RSpec
+  # Contract validating the behavior of an Assign command implementation.
+  ASSIGN_ONE_COMMAND_CONTRACT = lambda do |allow_extra_attributes:|
+    describe '#call' do
+      shared_examples 'should assign the attributes' do
+        it { expect(result).to be_a_passing_result }
+
+        it { expect(result.value).to be_a entity.class }
+
+        it { expect(result.value).to be == expected_value }
+      end
+
+      let(:attributes) { {} }
+      let(:result)     { command.call(attributes: attributes, entity: entity) }
+      let(:expected_attributes) do
+        initial_attributes.merge(attributes)
+      end
+      let(:expected_value) do
+        defined?(super()) ? super() : expected_attributes
+      end
+
+      it 'should validate the :attributes keyword' do
+        expect(command)
+          .to validate_parameter(:call, :attributes)
+          .using_constraint(
+            Stannum::Constraints::Types::HashWithIndifferentKeys.new
+          )
+      end
+
+      it 'should validate the :entity keyword' do
+        expect(command)
+          .to validate_parameter(:call, :entity)
+          .using_constraint(entity_type)
+          .with_parameters(attributes: {}, entity: nil)
+      end
+
+      describe 'with an empty attributes hash' do
+        let(:attributes) { {} }
+
+        include_examples 'should assign the attributes'
+      end
+
+      describe 'with an attributes hash with partial attributes' do
+        let(:attributes) { { title: 'Gideon the Ninth' } }
+
+        include_examples 'should assign the attributes'
+      end
+
+      describe 'with an attributes hash with full attributes' do
+        let(:attributes) do
+          {
+            title:    'Gideon the Ninth',
+            author:   'Tammsyn Muir',
+            series:   'The Locked Tomb',
+            category: 'Horror'
+          }
+        end
+
+        include_examples 'should assign the attributes'
+      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 assign the attributes'
+        else
+          # :nocov:
+          let(:valid_attributes) do
+            defined?(super()) ? super() : expected_attributes.keys
+          end
+          let(:expected_error) do
+            Cuprum::Collections::Errors::ExtraAttributes.new(
+              entity_class:     entity.class,
+              extra_attributes: %w[audiobook],
+              valid_attributes: 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
+
+      context 'when the entity has existing attributes' do
+        let(:initial_attributes) do
+          # :nocov:
+          if defined?(super())
+            super().merge(fixtures_data.first)
+          else
+            fixtures_data.first
+          end
+          # :nocov:
+        end
+
+        describe 'with an empty attributes hash' do
+          let(:attributes) { {} }
+
+          include_examples 'should assign the attributes'
+        end
+
+        describe 'with an attributes hash with partial attributes' do
+          let(:attributes) { { title: 'Gideon the Ninth' } }
+
+          include_examples 'should assign the attributes'
+        end
+
+        describe 'with an attributes hash with full attributes' do
+          let(:attributes) do
+            {
+              title:    'Gideon the Ninth',
+              author:   'Tammsyn Muir',
+              series:   'The Locked Tomb',
+              category: 'Horror'
+            }
+          end
+
+          include_examples 'should assign the attributes'
+        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 assign the attributes'
+          else
+            # :nocov:
+            let(:valid_attributes) do
+              defined?(super()) ? super() : expected_attributes.keys
+            end
+            let(:expected_error) do
+              Cuprum::Collections::Errors::ExtraAttributes.new(
+                entity_class:     entity.class,
+                extra_attributes: %w[audiobook],
+                valid_attributes: 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/build_one_command_contract.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types/hash_with_indifferent_keys'
+require 'stannum/rspec/validate_parameter'
+
+require 'cuprum/collections/rspec'
+
+module Cuprum::Collections::RSpec
+  # Contract validating the behavior of a Build command implementation.
+  BUILD_ONE_COMMAND_CONTRACT = lambda do |allow_extra_attributes:|
+    include Stannum::RSpec::Matchers
+
+    describe '#call' do
+      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: attributes) }
+      let(:expected_attributes) do
+        attributes
+      end
+      let(:expected_value) do
+        defined?(super()) ? super() : attributes
+      end
+
+      it 'should validate the :attributes keyword' do
+        expect(command)
+          .to validate_parameter(:call, :attributes)
+          .using_constraint(
+            Stannum::Constraints::Types::HashWithIndifferentKeys.new
+          )
+      end
+
+      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:   'Tammsyn 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:     entity_type,
+              extra_attributes: %w[audiobook],
+              valid_attributes: 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