cuprum-collections 0.4.0 → 0.5.0

data/lib/cuprum/collections/collection.rb

@@ -4,28 +4,24 @@ require 'cuprum/command_factory'
 
 require 'cuprum/collections'
 require 'cuprum/collections/relation'
+require 'cuprum/collections/relations/options'
+require 'cuprum/collections/relations/parameters'
+require 'cuprum/collections/relations/primary_keys'
+require 'cuprum/collections/relations/scope'
+require 'cuprum/collections/scopes/all_scope'
 
 module Cuprum::Collections
   # Provides a base implementation for collections.
   class Collection < Cuprum::CommandFactory
-    include Cuprum::Collections::Relation::Parameters
-    include Cuprum::Collections::Relation::PrimaryKeys
-    include Cuprum::Collections::Relation::Disambiguation
+    include Cuprum::Collections::Relations::Options
+    include Cuprum::Collections::Relations::Parameters
+    include Cuprum::Collections::Relations::PrimaryKeys
+    include Cuprum::Collections::Relations::Scope
 
     # Error raised when trying to call an abstract collection method.
     class AbstractCollectionError < StandardError; end
 
-    IGNORED_PARAMETERS = %i[
-      collection_name
-      entity_class
-      member_name
-      name
-      qualified_name
-      singular_name
-    ].freeze
-    private_constant :IGNORED_PARAMETERS
-
-    # @overload initialize(entity_class: nil, name: nil, qualified_name: nil, singular_name: nil, **options)
+    # @!method initialize(entity_class: nil, name: nil, qualified_name: nil, singular_name: nil, **options)
     #   @param entity_class [Class, String] the class of entity represented by
     #     the relation.
     #   @param name [String] the name of the relation.
@@ -35,27 +31,11 @@ module Cuprum::Collections
     #
     #   @option options primary_key_name [String] the name of the primary key
     #     attribute. Defaults to 'id'.
-    #   @option primary_key_type [Class, Stannum::Constraint] the type of
-    #     the primary key attribute. Defaults to Integer.
-    def initialize(**parameters) # rubocop:disable Metrics/MethodLength
-      super()
-
-      relation_params = resolve_parameters(
-        parameters,
-        name:          :collection_name,
-        singular_name: :member_name
-      )
-      @entity_class   = relation_params[:entity_class]
-      @name           = relation_params[:name]
-      @plural_name    = relation_params[:plural_name]
-      @qualified_name = relation_params[:qualified_name]
-      @singular_name  = relation_params[:singular_name]
-
-      @options = ignore_parameters(**parameters)
-    end
-
-    # @return [Hash<Symbol>] additional options for the collection.
-    attr_reader :options
+    #   @option options primary_key_type [Class, Stannum::Constraint] the type
+    #     of the primary key attribute. Defaults to Integer.
+    #   @option options scope
+    #     [Cuprum::Collections::Scopes::Base, Hash, Proc, nil] the configured
+    #     scope for the relation.
 
     # @param other [Object] The object to compare.
     #
@@ -67,14 +47,6 @@ module Cuprum::Collections
       comparable_options == other.comparable_options
     end
 
-    # @return [String] the name of the collection.
-    def collection_name
-      tools.core_tools.deprecate '#collection_name method',
-        message: 'Use #name instead'
-
-      name
-    end
-
     # @return [Integer] the count of items in the collection.
     def count
       query.count
@@ -97,58 +69,28 @@ module Cuprum::Collections
       comparable_options >= expected
     end
 
-    # @return [String] the name of an entity in the relation.
-    def member_name
-      tools.core_tools.deprecate '#member_name method',
-        message: 'Use #singular_name instead'
-
-      singular_name
-    end
-
     # A new Query instance, used for querying against the collection data.
     #
     # @return [Object] the query.
     def query
       raise AbstractCollectionError,
-        "#{self.class.name} is an abstract class. Define a repository " \
+        "#{self.class.name} is an abstract class. Define a collection " \
         'subclass and implement the #query method.'
     end
 
     protected
 
     def comparable_options
-      command_options.merge(
-        name:           name,
-        qualified_name: qualified_name,
-        singular_name:  singular_name
-      )
-    end
-
-    private
-
-    def command_options
-      @command_options ||= {
-        collection_name:  name,
-        entity_class:     entity_class,
-        member_name:      singular_name,
-        primary_key_name: primary_key_name,
-        primary_key_type: primary_key_type,
+      @comparable_options ||= {
+        entity_class:,
+        name:,
+        primary_key_name:,
+        primary_key_type:,
+        qualified_name:,
+        scope:,
+        singular_name:,
         **options
       }
     end
-
-    def ignore_parameters(**parameters)
-      parameters
-        .reject { |key, _| ignored_parameters.include?(key) }
-        .to_h
-    end
-
-    def ignored_parameters
-      @ignored_parameters ||= Set.new(IGNORED_PARAMETERS)
-    end
-
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
-    end
   end
 end

data/lib/cuprum/collections/collection_command.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'cuprum/parameter_validation'
+
+require 'cuprum/collections'
+require 'cuprum/collections/errors/invalid_parameters'
+
+module Cuprum::Collections
+  # Abstract base class for commands implementing collection actions.
+  class CollectionCommand < Cuprum::Command
+    include Cuprum::ParameterValidation
+
+    # @param collection [Cuprum::Collections::Collection] the collection to
+    #   which the command belongs.
+    def initialize(collection:)
+      super()
+
+      @collection = collection
+    end
+
+    # @return [Cuprum::Collections::Collection] the collection to which the
+    #   command belongs.
+    attr_reader :collection
+
+    # @return [String] the name of the relation.
+    def name
+      @name ||= collection.name
+    end
+    alias collection_name name
+
+    # @return [String] the name of the primary key attribute. Defaults to 'id'.
+    def primary_key_name
+      @primary_key_name ||= collection.primary_key_name
+    end
+
+    # @return [Class, Stannum::Constraint] the type of the primary key
+    #   attribute. Defaults to Integer.
+    def primary_key_type
+      @primary_key_type ||= collection.primary_key_type
+    end
+
+    # A new Query instance, used for querying against the collection data.
+    #
+    # @return [Object] the query.
+    def query
+      collection.query
+    end
+
+    # @returnb [String] the name of an entity in the collection.
+    def singular_name
+      @singular_name ||= collection.singular_name
+    end
+    alias member_name singular_name
+
+    private
+
+    def error_message_for(message = nil, as:, expected:)
+      tools.assertions.error_message_for(
+        message || 'sleeping_king_studios.tools.assertions.instance_of',
+        as:,
+        expected:
+      )
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validate_attributes(value, as: 'attributes')
+      return error_message_for(as:, expected: Hash) unless value.is_a?(Hash)
+
+      return [] if value.empty?
+
+      validator = tools.assertions.aggregator_class.new
+
+      value.each_key do |key|
+        validator.validate_name(
+          key,
+          as: "#{as}[#{key.inspect}] key"
+        )
+      end
+
+      validator.each.to_a
+    end
+
+    def validate_primary_key(value, as: nil)
+      return nil if primary_key_type.nil?
+
+      if primary_key_type.is_a?(Stannum::Constraints::Base)
+        match, errors = primary_key_type.match(value)
+
+        return match ? nil : "#{as || primary_key_name} #{errors.summary}"
+      end
+
+      return nil if value.is_a?(primary_key_type)
+
+      error_message_for(as: as || primary_key_name, expected: primary_key_type)
+    end
+
+    def validate_primary_keys(primary_keys, as: 'value')
+      unless primary_keys.is_a?(Array)
+        return error_message_for(as:, expected: Array)
+      end
+
+      messages = []
+
+      primary_keys.each.with_index do |item, index|
+        message = validate_primary_key(item, as: "#{as}[#{index}]")
+
+        messages << message if message
+      end
+
+      messages
+    end
+  end
+end

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

@@ -5,16 +5,13 @@ 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:)
+    def apply_query(primary_keys:)
       key = primary_key_name
 
-      (scope || build_query).where { { key => one_of(primary_keys) } }
+      query.where { |scope| { key => scope.one_of(primary_keys) } }
     end
 
     def build_results(items:, primary_keys:)
@@ -26,16 +23,14 @@ module Cuprum::Collections::Commands
     end
 
     def build_result_list(results, allow_partial:, envelope:)
-      unless envelope
-        return Cuprum::ResultList.new(*results, allow_partial: allow_partial)
-      end
+      return Cuprum::ResultList.new(*results, allow_partial:) unless envelope
 
       value = envelope ? wrap_items(results.map(&:value)) : nil
 
       Cuprum::ResultList.new(
         *results,
-        allow_partial: allow_partial,
-        value:         value
+        allow_partial:,
+        value:
       )
     end
 
@@ -49,25 +44,20 @@ module Cuprum::Collections::Commands
       Cuprum::Collections::Errors::NotFound.new(
         attribute_name:  primary_key_name,
         attribute_value: primary_key_value,
-        collection_name: collection_name,
+        collection_name:,
         primary_key:     true
       )
     end
 
-    def process(
-      primary_keys:,
-      allow_partial: false,
-      envelope:      false,
-      scope:         nil
-    )
-      query   = apply_query(primary_keys: primary_keys, scope: scope)
+    def process(primary_keys:, allow_partial: false, envelope: false)
+      query   = apply_query(primary_keys:)
       items   = items_with_primary_keys(items: query.to_a)
-      results = build_results(items: items, primary_keys: primary_keys)
+      results = build_results(items:, primary_keys:)
 
       build_result_list(
         results,
-        allow_partial: allow_partial,
-        envelope:      envelope
+        allow_partial:,
+        envelope:
       )
     end
 

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

@@ -1,62 +1,81 @@
 # frozen_string_literal: true
 
 require 'cuprum/collections/commands'
-require 'cuprum/collections/queries/parse'
+require 'cuprum/collections/constraints/ordering'
+require 'cuprum/collections/errors/invalid_query'
 
 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
+    def apply_query(limit:, offset:, order:, scope:)
+      query = self.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?
+      query = query.where(scope)   if scope
 
       success(query)
     end
 
-    def parse_criteria(strategy:, where:, &block)
-      return [] if strategy.nil? && where.nil? && !block_given?
+    def build_scope(value, &)
+      return Cuprum::Collections::Scope.build(&) if block_given?
 
-      Cuprum::Collections::Queries::Parse.new.call(
-        strategy: strategy,
-        where:    where || block
+      return value if value.is_a?(Cuprum::Collections::Scopes::Base)
+
+      Cuprum::Collections::Scope.build(value) if value
+    rescue ArgumentError => exception
+      error = Cuprum::Collections::Errors::InvalidQuery.new(
+        message: exception.message,
+        query:   value
       )
+
+      failure(error)
     end
 
-    def process( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+    def process(
       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
-
+      scope = step { build_scope(where, &block) }
       query = step do
         apply_query(
-          criteria: criteria,
-          limit:    limit,
-          offset:   offset,
-          order:    order,
-          scope:    scope
+          limit:,
+          offset:,
+          order:,
+          scope:
         )
       end
 
       envelope ? wrap_query(query) : query.each
     end
 
+    def validate_order(value, as: 'order')
+      return if value.nil?
+
+      match, errors =
+        Cuprum::Collections::Constraints::Ordering.new.match(value)
+
+      return if match
+
+      "#{as} #{errors.summary}"
+    end
+
+    def validate_where(value, as: 'where')
+      return if value.nil?
+
+      return if value.is_a?(Cuprum::Collections::Scopes::Base)
+
+      return if validate_attributes(value, as:).empty?
+
+      "#{as} is not a scope or query hash"
+    end
+
     def wrap_query(query)
       { collection_name => query.to_a }
     end

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

@@ -5,16 +5,13 @@ 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:)
+    def apply_query(primary_key:)
       key = primary_key_name
 
-      (scope || build_query).where { { key => equals(primary_key) } }.limit(1)
+      query.where { |scope| { key => scope.equals(primary_key) } }.limit(1)
     end
 
     def handle_missing_item(item:, primary_key:)
@@ -23,17 +20,17 @@ module Cuprum::Collections::Commands
       error = Cuprum::Collections::Errors::NotFound.new(
         attribute_name:  primary_key_name,
         attribute_value: primary_key,
-        collection_name: collection_name,
+        collection_name:,
         primary_key:     true
       )
-      Cuprum::Result.new(error: error)
+      Cuprum::Result.new(error:)
     end
 
-    def process(envelope:, primary_key:, scope:)
-      query = apply_query(primary_key: primary_key, scope: scope)
+    def process(primary_key:, envelope: false)
+      query = apply_query(primary_key:)
       item  = query.to_a.first
 
-      step { handle_missing_item(item: item, primary_key: primary_key) }
+      step { handle_missing_item(item:, primary_key:) }
 
       envelope ? wrap_item(item) : item
     end

data/lib/cuprum/collections/commands/associations/find_many.rb

@@ -75,7 +75,6 @@ module Cuprum::Collections::Commands::Associations
 
     def collection
       repository.find_or_create(
-        name:           tools.string_tools.pluralize(association.name),
         qualified_name: association.qualified_name
       )
     end
@@ -132,9 +131,9 @@ module Cuprum::Collections::Commands::Associations
 
       values = step do
         perform_query(
-          association:   association,
-          expected_keys: expected_keys,
-          plural:        plural
+          association:,
+          expected_keys:,
+          plural:
         )
       end
 
@@ -153,9 +152,5 @@ module Cuprum::Collections::Commands::Associations
 
       [keys, plural]
     end
-
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
-    end
   end
 end

data/lib/cuprum/collections/commands/associations/require_many.rb

@@ -10,7 +10,7 @@ module Cuprum::Collections::Commands::Associations
     private
 
     def find_missing_keys(entities:, expected_keys:)
-      expected_keys - map_entity_keys(entities: entities)
+      expected_keys - map_entity_keys(entities:)
     end
 
     def map_entity_keys(entities:)
@@ -23,7 +23,7 @@ module Cuprum::Collections::Commands::Associations
 
       Cuprum::Collections::Errors::NotFound.new(
         attribute_name:  association.query_key_name,
-        attribute_value: attribute_value,
+        attribute_value:,
         collection_name: association.name,
         primary_key:     association.primary_key_query?
       )
@@ -32,15 +32,15 @@ module Cuprum::Collections::Commands::Associations
     def perform_query(association:, expected_keys:, plural:, **)
       entities     = step { super }
       missing_keys = find_missing_keys(
-        entities:      entities,
-        expected_keys: expected_keys
+        entities:,
+        expected_keys:
       )
 
       return success(entities) if missing_keys.empty?
 
       missing_keys = missing_keys.first unless plural
       error        =
-        missing_keys_error(missing_keys: missing_keys, plural: plural)
+        missing_keys_error(missing_keys:, plural:)
 
       failure(error)
     end

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

@@ -50,11 +50,11 @@ module Cuprum::Collections::Commands
     private
 
     def process(attributes:)
-      entity = step { collection.build_one.call(attributes: attributes) }
+      entity = step { collection.build_one.call(attributes:) }
 
-      step { collection.validate_one.call(contract: contract, entity: entity) }
+      step { collection.validate_one.call(contract:, entity:) }
 
-      collection.insert_one.call(entity: entity)
+      collection.insert_one.call(entity:)
     end
   end
 end

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

@@ -96,20 +96,20 @@ module Cuprum::Collections::Commands
         if block_given?
           { query: collection.query.where(&block) }
         else
-          { attributes: attributes }
+          { attributes: }
         end
       )
     end
 
     def not_found_error(attributes: nil, &block)
       Cuprum::Collections::Errors::NotFound.new(
-        **error_params_for(attributes: attributes, &block)
+        **error_params_for(attributes:, &block)
       )
     end
 
     def not_unique_error(attributes: nil, &block)
       Cuprum::Collections::Errors::NotUnique.new(
-        **error_params_for(attributes: attributes, &block)
+        **error_params_for(attributes:, &block)
       )
     end
 
@@ -117,17 +117,17 @@ module Cuprum::Collections::Commands
       query    = block || -> { attributes }
       entities = step { collection.find_matching.call(limit: 2, &query) }
 
-      require_one_entity(attributes: attributes, entities: entities, &block)
+      require_one_entity(attributes:, entities:, &block)
     end
 
     def require_one_entity(attributes:, entities:, &block)
       case entities.count
       when 0
-        failure(not_found_error(attributes: attributes, &block))
+        failure(not_found_error(attributes:, &block))
       when 1
         entities.first
       when 2
-        failure(not_unique_error(attributes: attributes, &block))
+        failure(not_unique_error(attributes:, &block))
       end
     end
   end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands'
+
+module Cuprum::Collections::Commands
+  # Shared functionality for defining commands that query the collection.
+  module QueryCommand
+    # @param query [#call] the query object used to access the collection data.
+    # @param options [Hash] additional options for the collection.
+    def initialize(query:, **options)
+      super(**options)
+
+      @query = query
+    end
+
+    # @return [#call] the query object used to access the collection data.
+    attr_reader :query
+  end
+end

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

@@ -63,12 +63,12 @@ module Cuprum::Collections::Commands
 
     def process(attributes:, entity:)
       entity = step do
-        collection.assign_one.call(attributes: attributes, entity: entity)
+        collection.assign_one.call(attributes:, entity:)
       end
 
-      step { collection.validate_one.call(entity: entity, contract: contract) }
+      step { collection.validate_one.call(entity:, contract:) }
 
-      step { collection.update_one.call(entity: entity) }
+      step { collection.update_one.call(entity:) }
     end
   end
 end