cuprum-collections 0.1.0

data/lib/cuprum/collections/basic/rspec/command_contract.rb

@@ -0,0 +1,392 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/basic/rspec'
+
+module Cuprum::Collections::Basic::RSpec
+  # Contract validating the behavior of a basic command implementation.
+  COMMAND_CONTRACT = lambda do
+    describe '.subclass' do
+      let(:subclass) { described_class.subclass }
+      let(:constructor_options) do
+        {
+          collection_name: 'books',
+          data:            data,
+          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 collection name' do
+        expect(subclass.new(**constructor_options).collection_name)
+          .to be collection_name
+      end
+
+      it 'should return the data' do
+        expect(subclass.new(**constructor_options).data)
+          .to be data
+      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
+          {
+            collection_name: 'books',
+            custom_key:      'custom value'
+          }
+        end
+        let(:constructor_options) do
+          {
+            data:         data,
+            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 collection name' do
+          expect(subclass.new(**constructor_options).collection_name)
+            .to be collection_name
+        end
+
+        it 'should return the data' do
+          expect(subclass.new(**constructor_options).data)
+            .to be data
+        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
+      include_examples 'should have reader',
+        :collection_name,
+        -> { collection_name }
+
+      context 'when initialized with collection_name: symbol' do
+        let(:collection_name) { :books }
+
+        it { expect(command.collection_name).to be == collection_name.to_s }
+      end
+    end
+
+    describe '#data' do
+      include_examples 'should define reader', :data, -> { data }
+    end
+
+    describe '#default_contract' do
+      include_examples 'should define reader', :default_contract, nil
+
+      context 'when initialized with a default contract' do
+        let(:default_contract) { Stannum::Contract.new }
+        let(:constructor_options) do
+          super().merge(default_contract: default_contract)
+        end
+
+        it { expect(command.default_contract).to be default_contract }
+      end
+    end
+
+    describe '#member_name' do
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+
+      include_examples 'should have reader',
+        :member_name,
+        -> { tools.str.singularize(collection_name) }
+
+      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 'when initialized with a primary key name' do
+        let(:primary_key_name) { :uuid }
+        let(:constructor_options) do
+          super().merge({ primary_key_name: primary_key_name })
+        end
+
+        it { expect(command.primary_key_name).to be == primary_key_name }
+      end
+    end
+
+    describe '#primary_key_type' do
+      include_examples 'should define reader', :primary_key_type, Integer
+
+      context 'when initialized with a primary key type' do
+        let(:primary_key_type) { String }
+        let(:constructor_options) do
+          super().merge({ primary_key_type: primary_key_type })
+        end
+
+        it { expect(command.primary_key_type).to be == primary_key_type }
+      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 'when initialized with a primary key type' do
+        let(:primary_key_type) { String }
+        let(:constructor_options) do
+          super().merge({ primary_key_type: primary_key_type })
+        end
+
+        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
+    end
+  end
+end

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

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

data/lib/cuprum/collections/basic.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # The Basic collection is an example, in-memory collection implementation.
+  module Basic
+    # Returns a new instance of Basic::Collection.
+    #
+    # @param options [Hash] Constructor options for the collection.
+    #
+    # @see Cuprum::Collections::Basic::Collection#initialize.
+    def self.new(**options)
+      Cuprum::Collections::Basic::Collection.new(**options)
+    end
+
+    autoload :Collection, 'cuprum/collections/basic/collection'
+    autoload :Command,    'cuprum/collections/basic/command'
+    autoload :Commands,   'cuprum/collections/basic/commands'
+    autoload :Query,      'cuprum/collections/basic/query'
+  end
+end

data/lib/cuprum/collections/command.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'stannum/parameter_validation'
+
+require 'cuprum/collections'
+require 'cuprum/collections/errors/invalid_parameters'
+
+module Cuprum::Collections
+  # Abstract base class for Cuprum::Collection commands.
+  class Command < Cuprum::Command
+    extend  Stannum::ParameterValidation
+    include Stannum::ParameterValidation
+
+    private
+
+    def handle_invalid_parameters(errors:, method_name:)
+      return super unless method_name == :call
+
+      error = Cuprum::Collections::Errors::InvalidParameters.new(
+        command: self,
+        errors:  errors
+      )
+      failure(error)
+    end
+  end
+end

data/lib/cuprum/collections/commands/abstract_find_many.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands'
+require 'cuprum/collections/errors/not_found'
+
+module Cuprum::Collections::Commands
+  # Abstract implementation of the FindMany command.
+  #
+  # Subclasses must define the #build_query method, which returns an empty
+  # Query instance for that collection.
+  module AbstractFindMany
+    private
+
+    def apply_query(primary_keys:, scope:)
+      key = primary_key_name
+
+      (scope || build_query).where { { key => one_of(primary_keys) } }
+    end
+
+    def handle_missing_items(allow_partial:, items:, primary_keys:)
+      found, missing = match_items(items: items, primary_keys: primary_keys)
+
+      return found if missing.empty?
+
+      return found if allow_partial && !found.empty?
+
+      error = Cuprum::Collections::Errors::NotFound.new(
+        collection_name:    collection_name,
+        primary_key_name:   primary_key_name,
+        primary_key_values: missing
+      )
+      Cuprum::Result.new(error: error)
+    end
+
+    def items_with_primary_keys(items:)
+      # :nocov:
+      items.map { |item| [item.send(primary_key_name), item] }.to_h
+      # :nocov:
+    end
+
+    def match_items(items:, primary_keys:)
+      items   = items_with_primary_keys(items: items)
+      found   = []
+      missing = []
+
+      primary_keys.each do |key|
+        item = items[key]
+
+        item.nil? ? (missing << key) : (found << item)
+      end
+
+      [found, missing]
+    end
+
+    def process(
+      primary_keys:,
+      allow_partial: false,
+      envelope:      false,
+      scope:         nil
+    )
+      query = apply_query(primary_keys: primary_keys, scope: scope)
+      items = step do
+        handle_missing_items(
+          allow_partial: allow_partial,
+          items:         query.to_a,
+          primary_keys:  primary_keys
+        )
+      end
+
+      envelope ? wrap_items(items) : items
+    end
+
+    def wrap_items(items)
+      { collection_name => items }
+    end
+  end
+end

data/lib/cuprum/collections/commands/abstract_find_matching.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands'
+require 'cuprum/collections/queries/parse'
+
+module Cuprum::Collections::Commands
+  # Abstract implementation of the FindMatching command.
+  #
+  # Subclasses must define the #build_query method, which returns an empty
+  # Query instance for that collection.
+  module AbstractFindMatching
+    private
+
+    def apply_query(criteria:, limit:, offset:, order:, scope:)
+      query = scope || build_query
+      query = query.limit(limit)   if limit
+      query = query.offset(offset) if offset
+      query = query.order(order)   if order
+      query = query.where(criteria, strategy: :unsafe) unless criteria.empty?
+
+      success(query)
+    end
+
+    def parse_criteria(strategy:, where:, &block)
+      return [] if strategy.nil? && where.nil? && !block_given?
+
+      Cuprum::Collections::Queries::Parse.new.call(
+        strategy: strategy,
+        where:    where || block
+      )
+    end
+
+    def process( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+      envelope: false,
+      limit:    nil,
+      offset:   nil,
+      order:    nil,
+      scope:    nil,
+      strategy: nil,
+      where:    nil,
+      &block
+    )
+      criteria = step do
+        parse_criteria(strategy: strategy, where: where, &block)
+      end
+
+      query = step do
+        apply_query(
+          criteria: criteria,
+          limit:    limit,
+          offset:   offset,
+          order:    order,
+          scope:    scope
+        )
+      end
+
+      envelope ? wrap_query(query) : query.each
+    end
+
+    def wrap_query(query)
+      { collection_name => query.to_a }
+    end
+  end
+end

data/lib/cuprum/collections/commands/abstract_find_one.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands'
+require 'cuprum/collections/errors/not_found'
+
+module Cuprum::Collections::Commands
+  # Abstract implementation of the FindOne command.
+  #
+  # Subclasses must define the #build_query method, which returns an empty
+  # Query instance for that collection.
+  module AbstractFindOne
+    private
+
+    def apply_query(primary_key:, scope:)
+      key = primary_key_name
+
+      (scope || build_query).where { { key => equals(primary_key) } }.limit(1)
+    end
+
+    def handle_missing_item(item:, primary_key:)
+      return if item
+
+      error = Cuprum::Collections::Errors::NotFound.new(
+        collection_name:    collection_name,
+        primary_key_name:   primary_key_name,
+        primary_key_values: [primary_key]
+      )
+      Cuprum::Result.new(error: error)
+    end
+
+    def process(envelope:, primary_key:, scope:)
+      query = apply_query(primary_key: primary_key, scope: scope)
+      item  = query.to_a.first
+
+      step { handle_missing_item(item: item, primary_key: primary_key) }
+
+      envelope ? wrap_item(item) : item
+    end
+
+    def wrap_item(item)
+      { member_name => item }
+    end
+  end
+end

data/lib/cuprum/collections/commands.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # Namespace for abstract commands implementing collection functionality.
+  module Commands; end
+end

data/lib/cuprum/collections/constraints/attribute_name.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/hashes/indifferent_key'
+
+require 'cuprum/collections/constraints'
+
+module Cuprum::Collections::Constraints
+  # Asserts that the object is a non-empty String or Symbol.
+  class AttributeName < Stannum::Constraints::Hashes::IndifferentKey
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'cuprum.collections.constraints.is_valid_attribute_name'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'cuprum.collections.constraints.is_not_valid_attribute_name'
+
+    # @return [Cuprum::Collections::Constraints::AttributeName] a cached
+    #   instance of the constraint with default options.
+    def self.instance
+      @instance ||= new
+    end
+  end
+end

data/lib/cuprum/collections/constraints/order/attributes_array.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/constraints/attribute_name'
+require 'cuprum/collections/constraints/order'
+
+require 'stannum/constraints/types/array_type'
+
+module Cuprum::Collections::Constraints::Order
+  # Asserts that the object is an Array of attribute names.
+  class AttributesArray < Stannum::Constraints::Types::ArrayType
+    # @return [Cuprum::Collections::Constraints::Order::AttributesArray] a
+    #   cached instance of the constraint with default options.
+    def self.instance
+      @instance ||= new
+    end
+
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(
+        item_type: Cuprum::Collections::Constraints::AttributeName.instance,
+        **options
+      )
+    end
+  end
+end