cuprum-collections 0.5.1 → 0.6.0.rc.0

data/lib/cuprum/collections/queries.rb

@@ -15,7 +15,9 @@ module Cuprum::Collections
       LESS_THAN:                :less_than,
       LESS_THAN_OR_EQUAL_TO:    :less_than_or_equal_to,
       NOT_EQUAL:                :not_equal,
+      NOT_NULL:                 :not_null,
       NOT_ONE_OF:               :not_one_of,
+      NULL:                     :null,
       ONE_OF:                   :one_of
     ).freeze
 
@@ -46,7 +48,9 @@ module Cuprum::Collections
       Operators::LESS_THAN                => Operators::GREATER_THAN_OR_EQUAL_TO, # rubocop:disable Layout/LineLength
       Operators::LESS_THAN_OR_EQUAL_TO    => Operators::GREATER_THAN,
       Operators::NOT_EQUAL                => Operators::EQUAL,
+      Operators::NOT_NULL                 => Operators::NULL,
       Operators::NOT_ONE_OF               => Operators::ONE_OF,
+      Operators::NULL                     => Operators::NOT_NULL,
       Operators::ONE_OF                   => Operators::NOT_ONE_OF
     }.freeze
 

data/lib/cuprum/collections/relation.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'set'
-
 require 'cuprum/collections'
 require 'cuprum/collections/relations/options'
 require 'cuprum/collections/relations/parameters'

data/lib/cuprum/collections/relations/parameters.rb

@@ -13,40 +13,48 @@ module Cuprum::Collections::Relations
     ].freeze
     private_constant :IGNORED_PARAMETERS
 
-    PARAMETER_KEYS = %i[entity_class name qualified_name].freeze
+    OPTIONAL_PARAMETER_KEYS =
+      %i[default_entity_class plural_name singular_name].freeze
+    private_constant :OPTIONAL_PARAMETER_KEYS
+
+    REQUIRED_PARAMETER_KEYS = %i[entity_class name qualified_name].freeze
+    private_constant :REQUIRED_PARAMETER_KEYS
+
+    PARAMETER_KEYS = (OPTIONAL_PARAMETER_KEYS + REQUIRED_PARAMETER_KEYS).freeze
     private_constant :PARAMETER_KEYS
 
     class << self # rubocop:disable Metrics/ClassLength
-      # @overload resolve_parameters(entity_class: nil, singular_name: nil, name: nil, qualified_name: nil)
+      # @overload resolve_parameters(**options)
       #   Helper method for resolving a Relation's required parameters.
       #
-      #   The returned Hash will define the :entity_class, :singular_name,
-      #   :name, and :qualified_name keys.
+      #   At least one of the following options must be provided: name,
+      #   qualified_name, or entity_class. The returned Hash will include the
+      #   above keys as well as :singular_name and :plural_name.
       #
-      #   @param entity_class [Class, String] the class of entity represented
-      #     by the relation.
-      #   @param singular_name [String] the name of an entity in the relation.
-      #   @param name [String] the name of the relation.
-      #   @param qualified_name [String] a scoped name for the relation.
+      #   @param options [Hash] the parameters to resolve.
+      #
+      #   @option options default_entity_class [Class, String, nil] if given,
+      #     this value will be assigned to the entity class if the entity_class
+      #     is absent; it will *not* be used to derive other properties.
+      #   @option options entity_class [Class, String] the class of entity
+      #     represented by the relation.
+      #   @option options name [String] the name of the relation.
+      #   @option options plural_name [String] the name of a group of entities
+      #     in the relation.
+      #   @option options qualified_name [String] a scoped name for the
+      #     relation.
+      #   @option options singular_name [String] the name of an entity in the
+      #     relation.
       #
       #   @return [Hash] the resolved parameters.
-      def resolve_parameters(params) # rubocop:disable Metrics/MethodLength
+      def resolve_parameters(params)
         validate_parameters(**params)
 
-        entity_class   = entity_class_from(**params)
-        class_name     = entity_class_name(entity_class)
-        name           = relation_name_from(**params, class_name:)
-        plural_name    = plural_name_from(**params, name:)
-        qualified_name = qualified_name_from(**params, class_name:)
-        singular_name  = singular_name_from(**params, name:)
-
-        {
-          entity_class:,
-          name:,
-          plural_name:,
-          qualified_name:,
-          singular_name:
-        }
+        if has_key?(params, :entity_class)
+          resolve_parameters_from_entity_class(**params)
+        else
+          resolve_parameters_from_name(**params)
+        end
       end
 
       private
@@ -59,65 +67,109 @@ module Cuprum::Collections::Relations
           .join('::')
       end
 
-      def entity_class_from(**params)
-        if has_key?(params, :entity_class)
-          entity_class = params[:entity_class]
-
-          return entity_class.is_a?(Class) ? entity_class : entity_class.to_s
-        end
-
-        if has_key?(params, :qualified_name)
-          return classify(params[:qualified_name])
-        end
-
-        classify(params[:name])
-      end
-
-      def entity_class_name(entity_class, scoped: true)
-        (entity_class.is_a?(Class) ? entity_class.name : entity_class)
-          .split('::')
-          .map { |str| tools.string_tools.underscore(str) }
-          .then { |ary| scoped ? ary.join('/') : ary.last }
-      end
-
       def has_key?(params, key) # rubocop:disable Naming/PredicatePrefix
         return false unless params.key?(key)
 
         !params[key].nil?
       end
 
-      def plural_name_from(name:, **parameters)
-        if parameters.key?(:plural_name) && !parameters[:plural_name].nil?
-          return validate_parameter(
-            parameters[:plural_name],
-            as: 'plural name'
-          )
-        end
+      def resolve_entity_class(params)
+        entity_class =
+          if has_key?(params, :default_entity_class)
+            params[:default_entity_class]
+          else
+            classify(params[:qualified_name])
+          end
+
+        params.update(entity_class:)
+      end
+
+      def resolve_entity_name(params)
+        entity_class = params[:entity_class]
+        entity_name  =
+          (entity_class.is_a?(Class) ? entity_class.name : entity_class)
+            .split('::')
+            .map { |str| tools.string_tools.underscore(str) }
+            .join('/')
 
-        tools.string_tools.pluralize(name)
+        params.update(entity_name:)
       end
 
-      def qualified_name_from(class_name:, **params)
-        return params[:qualified_name].to_s if has_key?(params, :qualified_name)
+      def resolve_name(params)
+        name =
+          if has_key?(params, :name)
+            params[:name].to_s
+          elsif has_key?(params, :entity_name)
+            tools.string_tools.pluralize(params[:entity_name].split('/').last)
+          else
+            params[:qualified_name].split('/').last
+          end
+
+        params.update(name:)
+      end
 
-        tools.string_tools.pluralize(class_name)
+      def resolve_parameters_from_entity_class(**params)
+        params
+          .slice(*PARAMETER_KEYS)
+          .then { |hsh| resolve_entity_name(hsh) }
+          .then { |hsh| resolve_qualified_name(hsh) }
+          .then { |hsh| resolve_name(hsh) }
+          .then { |hsh| resolve_plural_name(hsh) }
+          .then { |hsh| resolve_singular_name(hsh) }
+          .tap  { |hsh| hsh.delete(:default_entity_class) }
+          .tap  { |hsh| hsh.delete(:entity_name) }
       end
 
-      def relation_name_from(class_name:, **params)
-        return params[:name].to_s if has_key?(params, :name)
+      def resolve_parameters_from_name(**params)
+        params
+          .slice(*PARAMETER_KEYS)
+          .then { |hsh| resolve_qualified_name(hsh) }
+          .then { |hsh| resolve_name(hsh) }
+          .then { |hsh| resolve_plural_name(hsh) }
+          .then { |hsh| resolve_singular_name(hsh) }
+          .then { |hsh| resolve_entity_class(hsh) }
+          .tap  { |hsh| hsh.delete(:default_entity_class) }
+      end
 
-        tools.string_tools.pluralize(class_name.split('/').last)
+      def resolve_plural_name(params)
+        plural_name =
+          if has_key?(params, :plural_name)
+            validate_parameter(
+              params[:plural_name],
+              as: 'plural name'
+            )
+          else
+            tools.string_tools.pluralize(params[:name])
+          end
+
+        params.update(plural_name:)
       end
 
-      def singular_name_from(name:, **parameters)
-        if parameters.key?(:singular_name) && !parameters[:singular_name].nil?
-          return validate_parameter(
-            parameters[:singular_name],
-            as: 'singular name'
-          )
-        end
+      def resolve_qualified_name(params)
+        qualified_name =
+          if has_key?(params, :qualified_name)
+            params[:qualified_name].to_s
+          elsif has_key?(params, :entity_name)
+            tools.string_tools.pluralize(params[:entity_name])
+          elsif has_key?(params, :name)
+            tools.string_tools.pluralize(params[:name])
+          end
+
+        params.update(qualified_name:)
+      end
 
-        tools.string_tools.singularize(name)
+      def resolve_singular_name(params)
+        singular_name =
+          if has_key?(params, :singular_name)
+            validate_parameter(
+              params[:singular_name],
+              as: 'singular name'
+            )
+          else
+            tools.string_tools.singularize(params[:name])
+          end
+
+        params.update(singular_name:)
       end
 
       def tools
@@ -144,7 +196,7 @@ module Cuprum::Collections::Relations
       end
 
       def validate_parameter_keys(params)
-        return if PARAMETER_KEYS.any? { |key| has_key?(params, key) }
+        return if REQUIRED_PARAMETER_KEYS.any? { |key| has_key?(params, key) }
 
         raise ArgumentError, "name or entity class can't be blank"
       end

data/lib/cuprum/collections/repository.rb

@@ -14,7 +14,7 @@ module Cuprum::Collections
   # and so on. The application may instead aggregate all of its collections into
   # a single repository, relying on the shared interface of all Collection
   # implementations.
-  class Repository
+  class Repository # rubocop:disable Metrics/ClassLength
     extend Forwardable
 
     # Error raised when trying to call an abstract repository method.
@@ -29,8 +29,11 @@ module Cuprum::Collections
     # Error raised when trying to access a collection that is not defined.
     class UndefinedCollectionError < StandardError; end
 
+    # @yieldparam [Cuprum::Collections::Repository] the created repository.
     def initialize
       @collections = {}
+
+      yield self if block_given?
     end
 
     # @!method keys
@@ -73,6 +76,8 @@ module Cuprum::Collections
     def add(collection, force: false)
       validate_collection!(collection)
 
+      raise FrozenError, frozen_error_message if frozen?
+
       if !force && key?(collection.qualified_name.to_s)
         raise DuplicateCollectionError,
           "collection #{collection.qualified_name} already exists"
@@ -84,10 +89,10 @@ module Cuprum::Collections
     end
     alias << add
 
-    # @overload create(collection_name: nil, entity_class: nil, force: false, **options)
+    # @overload create(name: nil, entity_class: nil, force: false, **options)
     #   Adds a new collection with the given name to the repository.
     #
-    #   @param collection_name [String] the name of the new collection.
+    #   @param name [String] the name of the new collection.
     #   @param entity_class [Class, String] the class of entity represented in
     #     the collection.
     #   @param force [true, false] if true, override an existing collection with
@@ -98,14 +103,31 @@ module Cuprum::Collections
     #
     #   @raise [DuplicateCollectionError] if a collection with the same name
     #     already exists in the repository.
-    def create(force: false, **options)
-      collection = build_collection(**options)
+    def create(force: false, **)
+      collection = build_collection(**)
 
       add(collection, force:)
 
       collection
     end
 
+    # @overload find(name: nil, entity_class: nil, **options)
+    def find(**parameters)
+      qualified_name = qualified_name_for(**parameters)
+      collection     = @collections[qualified_name]
+
+      unless collection
+        raise UndefinedCollectionError,
+          "repository does not define collection #{qualified_name.inspect}"
+      end
+
+      return collection if collection.matches?(**parameters)
+
+      error_message = partial_match_error_message(collection:, parameters:)
+
+      raise DuplicateCollectionError, error_message
+    end
+
     # @overload find_or_create(collection_name: nil, entity_class: nil, **options)
     #   Finds or creates a new collection with the given name.
     #
@@ -118,7 +140,12 @@ module Cuprum::Collections
     #
     #   @raise [DuplicateCollectionError] if a collection with the same name
     #     but different parameters already exists in the repository.
-    def find_or_create(**parameters)
+    def find_or_create(**parameters) # rubocop:disable Metrics/MethodLength
+      tools.core_tools.deprecate(
+        "#{self.class.name}#find_or_create()",
+        message: 'Use #create or #find method.'
+      )
+
       qualified_name = qualified_name_for(**parameters)
 
       unless key?(qualified_name)
@@ -144,6 +171,22 @@ module Cuprum::Collections
       @collections.key?(qualified_name.to_s)
     end
 
+    # Removes the specified collection from the repository.
+    #
+    # @param qualified_name [String, Symbol] the name of the collection to
+    #   remove.
+    #
+    # @return [Cuprum::Collections::Collection] the removed collection.
+    def remove(qualified_name:)
+      raise FrozenError, frozen_error_message if frozen?
+
+      collection = find(qualified_name:)
+
+      @collections.delete(collection.qualified_name)
+
+      collection
+    end
+
     private
 
     def build_collection(**)
@@ -152,12 +195,34 @@ module Cuprum::Collections
         'subclass and implement the #build_collection method.'
     end
 
+    def frozen_error_message
+      "can't modify frozen #{self.class.name}"
+    end
+
+    def partial_match_error_message(collection:, parameters:)
+      non_matching =
+        parameters
+          .each_key
+          .reject { |key| collection.public_send(key) == parameters[key] }
+      expected = parameters.slice(*non_matching)
+      actual   = non_matching.to_h { |key| [key, collection.public_send(key)] }
+      name     = collection.qualified_name.inspect
+
+      "collection #{name} exists but does not match:\n" \
+        "\n  expected: #{expected.inspect}" \
+        "\n    actual: #{actual.inspect}"
+    end
+
     def qualified_name_for(**parameters)
       Cuprum::Collections::Relations::Parameters
         .resolve_parameters(parameters)
         .fetch(:qualified_name)
     end
 
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
     def valid_collection?(collection)
       collection.respond_to?(:qualified_name)
     end

data/lib/cuprum/collections/rspec/contracts/query_contracts.rb

@@ -2,12 +2,17 @@
 
 require 'cuprum/collections/queries'
 require 'cuprum/collections/rspec/contracts'
+require 'cuprum/collections/rspec/deferred/query_examples'
 require 'cuprum/collections/rspec/fixtures'
 
 module Cuprum::Collections::RSpec::Contracts
   # Contracts for asserting on Query objects.
   module QueryContracts
+    include Cuprum::Collections::RSpec::Deferred::QueryExamples
+
     # Contract validating the behavior of a Query implementation.
+    #
+    # @deprecated 0.6.0
     module ShouldBeAQuery
       extend RSpec::SleepingKingStudios::Contract
 
@@ -27,6 +32,11 @@ module Cuprum::Collections::RSpec::Contracts
       contract do |abstract: false|
         include Cuprum::Collections::RSpec::Contracts::QueryContracts
 
+        SleepingKingStudios::Tools::CoreTools.deprecate(
+          'QueryContracts "should be a query"',
+          message: 'Use Deferred::QueryExamples instead.'
+        )
+
         shared_context 'when initialized with a scope' do
           let(:initial_scope) do
             Cuprum::Collections::Scope.new do |scope|
@@ -97,7 +107,8 @@ module Cuprum::Collections::RSpec::Contracts
           context 'when the collection has many items' do
             let(:data) { BOOKS_FIXTURES }
 
-            include_contract 'should query the collection', :ignore_order do
+            include_deferred 'should query the collection', ignore_order: true \
+            do
               it { expect(scoped_query.count).to be == expected_data.count }
 
               wrap_context 'when the query has composed filters' do
@@ -167,7 +178,7 @@ module Cuprum::Collections::RSpec::Contracts
           context 'when the collection has many items' do
             let(:data) { BOOKS_FIXTURES }
 
-            include_contract 'should query the collection' do
+            include_deferred 'should query the collection' do
               include_examples 'should enumerate the matching data'
 
               wrap_context 'when the query has composed filters' do
@@ -215,7 +226,8 @@ module Cuprum::Collections::RSpec::Contracts
           context 'when the collection has many items' do
             let(:data) { BOOKS_FIXTURES }
 
-            include_contract 'should query the collection', :ignore_order do
+            include_deferred 'should query the collection', ignore_order: true \
+            do
               include_examples 'should check the existence of matching data'
 
               wrap_context 'when the query has composed filters' do
@@ -549,7 +561,7 @@ module Cuprum::Collections::RSpec::Contracts
           context 'when the collection has many items' do
             let(:data) { BOOKS_FIXTURES }
 
-            include_contract 'should query the collection' do
+            include_deferred 'should query the collection' do
               it { expect(queried_data).to be == expected_data }
 
               wrap_context 'when the query has composed filters' do
@@ -766,12 +778,19 @@ module Cuprum::Collections::RSpec::Contracts
     end
 
     # Contract validating the behavior when performing queries.
+    #
+    # @deprecate 0.6.0 Use Deferred::QueryExamples instead.
     module ShouldQueryTheCollectionContract
       extend RSpec::SleepingKingStudios::Contract
 
       contract do |*tags, &examples|
         ignore_order = tags.include?(:ignore_order)
 
+        SleepingKingStudios::Tools::CoreTools.deprecate(
+          'QueryContracts "should query the collection"',
+          message: 'Use Deferred::QueryExamples instead.'
+        )
+
         shared_examples 'should query the collection' do
           # :nocov:
           if examples

data/lib/cuprum/collections/rspec/contracts/repository_contracts.rb

@@ -4,8 +4,13 @@ require 'cuprum/collections/rspec/contracts'
 
 module Cuprum::Collections::RSpec::Contracts
   # Contracts for asserting on Repository objects.
+  #
+  # @deprecated 0.6.0 Use RepositoryExamples instead.
+  #   Note - requires defining a #build_collection(**options) helper method.
   module RepositoryContracts
     # Contract validating the behavior of a Repository.
+    #
+    # @deprecated 0.6.0
     module ShouldBeARepositoryContract
       extend RSpec::SleepingKingStudios::Contract
 
@@ -23,6 +28,14 @@ module Cuprum::Collections::RSpec::Contracts
       #   @option options entity_class [Class, String] the expected entity
       #     class.
       contract do |abstract: false, **options|
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .core_tools
+          .deprecate(
+            'Cuprum::Collections::RSpec::Contracts::RepositoryContracts',
+            message: 'Use RepositoryExamples instead.'
+          )
+
         shared_examples 'should create the collection' do
           let(:configured_collection_class) do
             return super() if defined?(super())
@@ -443,6 +456,11 @@ module Cuprum::Collections::RSpec::Contracts
               'repository subclass and implement the #build_collection method.'
           end
 
+          before(:example) do
+            allow(SleepingKingStudios::Tools::Toolbelt.instance.core_tools)
+              .to receive(:deprecate)
+          end
+
           def create_collection(safe: true, **options)
             if safe
               begin

data/lib/cuprum/collections/rspec/contracts/scope_contracts.rb

@@ -8,6 +8,8 @@ module Cuprum::Collections::RSpec::Contracts
   # Contracts for asserting on scope objects.
   module ScopeContracts
     # Contract validating the behavior of a scope implementation.
+    #
+    # @deprecated 0.6.0
     module ShouldBeAScopeContract
       extend RSpec::SleepingKingStudios::Contract
 
@@ -19,6 +21,16 @@ module Cuprum::Collections::RSpec::Contracts
       #   @param invertible [Boolean] if true, the scope defines an
       #     implementation of the #invert method. Defaults to false.
       contract do |invertible: false|
+        message = 'Use deferred examples "should implement the Scope methods"'
+
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .core_tools
+          .deprecate(
+            'ShouldBeAScopeContract',
+            message:
+          )
+
         describe '#==' do
           it { expect(subject == nil).to be false } # rubocop:disable Style/NilComparison
 
@@ -73,6 +85,8 @@ module Cuprum::Collections::RSpec::Contracts
     end
 
     # Contract validating the behavior of a Container scope implementation.
+    #
+    # @deprecated 0.6.0
     module ShouldBeAContainerScopeContract
       extend RSpec::SleepingKingStudios::Contract
 
@@ -84,6 +98,17 @@ module Cuprum::Collections::RSpec::Contracts
       #   @param invertible [Boolean] if true, the scope defines an
       #     implementation of the #invert method. Defaults to false.
       contract do |invertible: false|
+        message =
+          'Use deferred examples "should implement the Scope methods" and ' \
+          '"should define child scopes"'
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .core_tools
+          .deprecate(
+            'ShouldBeADisjunctionScopeContract',
+            message:
+          )
+
         shared_context 'with scopes' do
           let(:scopes) do
             [
@@ -272,6 +297,8 @@ module Cuprum::Collections::RSpec::Contracts
     end
 
     # Contract validating the behavior of an All scope implementation.
+    #
+    # @deprecated 0.6.0
     module ShouldBeAnAllScopeContract
       extend RSpec::SleepingKingStudios::Contract
 
@@ -283,6 +310,17 @@ module Cuprum::Collections::RSpec::Contracts
       #   @param abstract [Boolean] if true, the scope is abstract and does not
       #     define a #call implementation. Defaults to false.
       contract do |abstract: false|
+        message =
+          'Use deferred examples "should implement the AllScope methods"'
+
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .core_tools
+          .deprecate(
+            'ShouldBeAnAllScopeContract',
+            message:
+          )
+
         include_contract 'should be a scope', invertible: true
 
         describe '#==' do
@@ -653,6 +691,8 @@ module Cuprum::Collections::RSpec::Contracts
     end
 
     # Contract validating the behavior of a None scope implementation.
+    #
+    # @deprecated 0.6.0
     module ShouldBeANoneScopeContract
       extend RSpec::SleepingKingStudios::Contract
 
@@ -664,6 +704,17 @@ module Cuprum::Collections::RSpec::Contracts
       #   @param abstract [Boolean] if true, the scope is abstract and does not
       #     define a #call implementation. Defaults to false.
       contract do |abstract: false|
+        message =
+          'Use deferred examples "should implement the NoneScope methods"'
+
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .core_tools
+          .deprecate(
+            'ShouldBeANoneScopeContract',
+            message:
+          )
+
         include_contract 'should be a scope', invertible: true
 
         describe '#==' do

data/lib/cuprum/collections/rspec/contracts/scopes/builder_contracts.rb

@@ -15,6 +15,8 @@ module Cuprum::Collections::RSpec::Contracts::Scopes
     include Cuprum::Collections::RSpec::Contracts::Scopes::CriteriaContracts
 
     # Contract validating the behavior of a scope builder implementation.
+    #
+    # @deprecated 0.6.0
     module ShouldBeAScopeBuilderContract
       extend RSpec::SleepingKingStudios::Contract
 
@@ -44,6 +46,14 @@ module Cuprum::Collections::RSpec::Contracts::Scopes
         disjunction_scope_class = contract_options[:disjunction_class]
         none_scope_class        = contract_options[:none_class]
 
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .core_tools
+          .deprecate(
+            'ShouldBeAScopeBuilderContract',
+            message: 'Use deferred examples "should build collection Scopes"'
+          )
+
         shared_context 'with container scope helpers' do
           let(:scope) { build_container(scopes:) }