cuprum-collections 0.5.1 → 0.6.0.rc.0

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'cuprum/parameter_validation'
+
 require 'cuprum/collections/commands'
 require 'cuprum/collections/constraints/ordering'
 require 'cuprum/collections/errors/invalid_query'
@@ -7,6 +9,102 @@ require 'cuprum/collections/errors/invalid_query'
 module Cuprum::Collections::Commands
   # Abstract implementation of the FindMatching command.
   module AbstractFindMatching
+    include Cuprum::ParameterValidation
+
+    # @!method call(envelope: false, limit: nil, offset: nil, order: nil, scope: nil, where: nil, &block)
+    #   Queries the collection for items matching the given conditions.
+    #
+    #   @param envelope [Boolean] If true, wraps the result value in a Hash.
+    #   @param limit [Integer] The maximum number of results to return.
+    #   @param offset [Integer] The initial ordered items to skip.
+    #   @param order [Array<String, Symbol>, Hash<{String, Symbol => Symbol}>]
+    #     The sort order of the returned items. Should be either an array of
+    #     attribute names or a hash of attribute names and directions.
+    #   @param scope [Cuprum::Collections::Basic::Query, nil] Optional scope for
+    #     the query. Items must match the scope as well as the :where filters.
+    #   @param where [Object] Additional filters for selecting data. The command
+    #     will only return data matching these filters.
+    #   @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.
+    #
+    #   @example Querying all items in the collection.
+    #     command = FindMatching.new(collection_name: 'books', data: books)
+    #     command.call
+    #     #=> an enumerable iterating all items in the collection
+    #
+    #   @example Querying all items matching some critera:
+    #     command.call { { author: 'Nnedi Okorafor' } }
+    #     #=> an enumerable iterating all items in the collection whose author
+    #         is 'Nnedi Okorafor'
+    #
+    #   @example Ordering query results
+    #     command.call(order: :title) { { author: 'Nnedi Okorafor' } }
+    #     #=> an enumerable iterating all items in the collection whose author
+    #     #   is 'Nnedi Okorafor', sorted by :title in ascending order
+    #
+    #   @example Advanced filtering
+    #     command.call do
+    #       {
+    #         category: eq('Science Fiction and Fantasy'),
+    #         author:   ne('J.R.R. Tolkien')
+    #       }
+    #     end
+    #     #=> an enumerable iterating all items in the collection whose category
+    #     #   is 'Science Fiction and Fantasy', and whose author is not
+    #     #   'J.R.R. Tolkien'.
+    #
+    #   @example Advanced ordering
+    #     order = { author: :asc, genre: :desc }
+    #     command.call(order: order) { { author: 'Nnedi Okorafor' } }
+    #     #=> an enumerable iterating all items in the collection whose author
+    #     #   is 'Nnedi Okorafor', sorted first by :author in ascending order
+    #     #   and within the same author by genre in descending order
+    #
+    #   @example Filtering, ordering, and subsets
+    #     command.call(offset: 50, limit: 10, order: :author) do
+    #       { category: 'Science Fiction and Fantasy' }
+    #     end
+    #     #=> an enumerable iterating the 51st through 60th items in the
+    #     #   collection whose category is 'Science Fiction and Fantasy', sorted
+    #     #   by :author in ascending order.
+    #
+    #   @example Wrapping the result in an envelope
+    #     command =
+    #       FindMatching.new(
+    #         collection_name: 'books',
+    #         data:            books
+    #       )
+    #     command.call(envelope: true)
+    #     #=> {
+    #       'books' => [] # an array containing the matching items
+    #     }
+    #
+    #   @overload call(limit: nil, offset: nil, order: nil, &block)
+    #     When the :envelope option is false (default), the command returns an
+    #     Enumerator which can be iterated to return the matching items.
+    #
+    #     @return [Cuprum::Result<Enumerator>] the matching items in the
+    #       specified order as an Enumerator.
+    #
+    #   @overload call(limit: nil, offset: nil, order: nil, &block)
+    #     When the :envelope option is true, the command immediately evaluates
+    #     the query and wraps the resulting array in a Hash, using the name of
+    #     the collection as the key.
+    #
+    #     @return [Cuprum::Result<Hash{String, Array<Hash{String, Object}>}>] a
+    #       hash with the collection name as key and the matching items as
+    #       value.
+    validate :envelope, :boolean, optional: true
+    validate :limit,    Integer,  optional: true
+    validate :offset,   Integer,  optional: true
+    validate :order
+    validate :where
+
     private
 
     def apply_query(limit:, offset:, order:, scope:)
@@ -22,6 +120,8 @@ module Cuprum::Collections::Commands
     def build_scope(value, &)
       return Cuprum::Collections::Scope.build(&) if block_given?
 
+      return Cuprum::Collections::Scope.build(&value) if value.is_a?(Proc)
+
       return value if value.is_a?(Cuprum::Collections::Scopes::Base)
 
       Cuprum::Collections::Scope.build(value) if value
@@ -69,6 +169,8 @@ module Cuprum::Collections::Commands
     def validate_where(value, as: 'where')
       return if value.nil?
 
+      return if value.is_a?(Proc) && (-1..1).cover?(value.arity)
+
       return if value.is_a?(Cuprum::Collections::Scopes::Base)
 
       return if validate_attributes(value, as:).empty?

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

@@ -1,11 +1,33 @@
 # frozen_string_literal: true
 
+require 'cuprum/parameter_validation'
+
 require 'cuprum/collections/commands'
 require 'cuprum/collections/errors/not_found'
 
 module Cuprum::Collections::Commands
   # Abstract implementation of the FindOne command.
   module AbstractFindOne
+    include Cuprum::ParameterValidation
+
+    # @!method call(primary_key:, envelope: false)
+    #   Queries the collection for the item with the given primary key.
+    #
+    #   The command will find and return the entity with the given primary key.
+    #   If the entity is not found, the command will fail and return a NotFound
+    #   error.
+    #
+    #   When the :envelope option is true, the command wraps the item in a Hash,
+    #   using the singular name of the collection as the key.
+    #
+    #   @param envelope [Boolean] If true, wraps the result value in a Hash.
+    #   @param primary_key [Object] The primary key of the requested item.
+    #
+    #   @return [Cuprum::Result<Hash{String, Object}>] a result with the
+    #     requested item.
+    validate :envelope, :boolean, optional: true
+    validate :primary_key
+
     private
 
     def apply_query(primary_key:)
@@ -20,7 +42,7 @@ module Cuprum::Collections::Commands
       error = Cuprum::Collections::Errors::NotFound.new(
         attribute_name:  primary_key_name,
         attribute_value: primary_key,
-        collection_name:,
+        name:,
         primary_key:     true
       )
       Cuprum::Result.new(error:)

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

@@ -74,9 +74,7 @@ module Cuprum::Collections::Commands::Associations
     private
 
     def collection
-      repository.find_or_create(
-        qualified_name: association.qualified_name
-      )
+      repository.find(qualified_name: association.qualified_name)
     end
 
     def extract_keys(association, hsh)

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

@@ -24,7 +24,7 @@ module Cuprum::Collections::Commands::Associations
       Cuprum::Collections::Errors::NotFound.new(
         attribute_name:  association.query_key_name,
         attribute_value:,
-        collection_name: association.name,
+        name:            association.name,
         primary_key:     association.primary_key_query?
       )
     end

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

@@ -91,25 +91,25 @@ module Cuprum::Collections::Commands
 
     private
 
-    def error_params_for(attributes: nil, &block)
-      { collection_name: collection.name }.merge(
+    def error_params_for(attributes: nil, &)
+      { name: collection.name }.merge(
         if block_given?
-          { query: collection.query.where(&block) }
+          { query: collection.query.where(&) }
         else
           { attributes: }
         end
       )
     end
 
-    def not_found_error(attributes: nil, &block)
+    def not_found_error(attributes: nil, &)
       Cuprum::Collections::Errors::NotFound.new(
-        **error_params_for(attributes:, &block)
+        **error_params_for(attributes:, &)
       )
     end
 
-    def not_unique_error(attributes: nil, &block)
+    def not_unique_error(attributes: nil, &)
       Cuprum::Collections::Errors::NotUnique.new(
-        **error_params_for(attributes:, &block)
+        **error_params_for(attributes:, &)
       )
     end
 
@@ -120,14 +120,14 @@ module Cuprum::Collections::Commands
       require_one_entity(attributes:, entities:, &block)
     end
 
-    def require_one_entity(attributes:, entities:, &block)
+    def require_one_entity(attributes:, entities:, &)
       case entities.count
       when 0
-        failure(not_found_error(attributes:, &block))
+        failure(not_found_error(attributes:, &))
       when 1
         entities.first
       when 2
-        failure(not_unique_error(attributes:, &block))
+        failure(not_unique_error(attributes:, &))
       end
     end
   end

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

@@ -5,10 +5,12 @@ 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)
+    # @overload initialize(query:, **options)
+    #   @param query [#call] the query object used to access the collection
+    #     data.
+    #   @param options [Hash] additional options for the collection.
+    def initialize(query:, **)
+      super(**)
 
       @query = query
     end

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'set'
-
 require 'cuprum/collections/commands'
 require 'cuprum/collections/commands/create'
 require 'cuprum/collections/commands/find_one_matching'

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

@@ -14,12 +14,13 @@ module Cuprum::Collections::Constraints::Order
       @instance ||= new
     end
 
-    # @param options [Hash<Symbol, Object>] Configuration options for the
-    #   constraint. Defaults to an empty Hash.
-    def initialize(**options)
+    # @overload initialize(**options)
+    #   @param options [Hash<Symbol, Object>] Configuration options for the
+    #     constraint. Defaults to an empty Hash.
+    def initialize(**)
       super(
         item_type: Cuprum::Collections::Constraints::AttributeName.instance,
-        **options
+        **
       )
     end
   end

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

@@ -13,14 +13,15 @@ module Cuprum::Collections::Constraints::Order
       @instance ||= new
     end
 
-    # @param options [Hash<Symbol, Object>] Configuration options for the
-    #   constraint. Defaults to an empty Hash.
-    def initialize(**options)
+    # @overload initialize(**options)
+    #   @param options [Hash<Symbol, Object>] Configuration options for the
+    #     constraint. Defaults to an empty Hash.
+    def initialize(**)
       super(
         key_type:   Cuprum::Collections::Constraints::AttributeName.instance,
         value_type: Cuprum::Collections::Constraints::Order::SortDirection
           .instance,
-        **options
+        **
       )
     end
   end

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

@@ -19,8 +19,8 @@ module Cuprum::Collections::Constraints::Order
       @instance ||= new
     end
 
-    def initialize(**options)
-      super(*sort_directions, **options)
+    def initialize(**)
+      super(*sort_directions, **)
     end
 
     private

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

@@ -41,15 +41,16 @@ module Cuprum::Collections::Constraints
       @instance ||= new
     end
 
-    # @param options [Hash<Symbol, Object>] Configuration options for the
-    #   constraint. Defaults to an empty Hash.
-    def initialize(optional: nil, required: nil, **options)
+    # @overload initialize(optional: nil, required: nil, **options)
+    #   @param options [Hash<Symbol, Object>] Configuration options for the
+    #     constraint. Defaults to an empty Hash.
+    def initialize(optional: nil, required: nil, **)
       super(
         *ordering_constraints,
         **resolve_required_option(
           optional:,
           required:,
-          **options
+          **
         )
       )
     end
@@ -91,13 +92,14 @@ module Cuprum::Collections::Constraints
       (errors || Stannum::Errors.new).add(negated_type)
     end
 
-    # Creates a copy of the constraint and updates the copy's options.
+    # @overload with_options(**options)
+    #   Creates a copy of the constraint and updates the copy's options.
     #
-    # @param options [Hash] The options to update.
+    #   @param options [Hash] The options to update.
     #
-    # @return [Stannum::Constraints::Base] the copied constraint.
-    def with_options(**options)
-      super(**resolve_required_option(**options))
+    #   @return [Stannum::Constraints::Base] the copied constraint.
+    def with_options(**)
+      super(**resolve_required_option(**))
     end
 
     private

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

@@ -8,11 +8,11 @@ require 'cuprum/collections/constraints/attribute_name'
 module Cuprum::Collections::Constraints
   # Asserts that the object is a Hash with valid attribute name keys.
   class QueryHash < Stannum::Constraints::Types::HashType
-    def initialize(**options)
+    def initialize(**)
       super(
         allow_empty: true,
         key_type:    attribute_name_constraint,
-        **options
+        **
       )
     end
 

data/lib/cuprum/collections/errors/abstract_find_error.rb

@@ -1,44 +1,110 @@
 # frozen_string_literal: true
 
 require 'cuprum/collections/errors'
+require 'cuprum/collections/relations/parameters'
 
 module Cuprum::Collections::Errors
   # Abstract base class for failed query errors.
   class AbstractFindError < Cuprum::Error # rubocop:disable Metrics/ClassLength
-    PERMITTED_KEYWORDS = %i[
+    COLLECTION_KEYWORDS = %i[
+      collection
+      collection_name
+      entity_class
+      name
+      qualified_name
+    ].freeze
+    private_constant :COLLECTION_KEYWORDS
+
+    QUERYING_KEYWORDS = %i[
       attribute_name
       attribute_value
       attributes
       primary_key
       query
     ].freeze
-    private_constant :PERMITTED_KEYWORDS
+    private_constant :QUERYING_KEYWORDS
+
+    VALID_PARAMETERS = %i[entity_class name qualified_name].freeze
+    private_constant :VALID_PARAMETERS
+
+    class << self
+      # Resolves the details about the queried collection.
+      #
+      # @param params [Hash] the parameters to resolve.
+      #
+      # @return [Hash] the collection details.
+      def resolve_collection(**params) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        if params[:collection].is_a?(Cuprum::Collections::Collection)
+          return collection_details(params[:collection])
+        elsif collection_name?(params[:collection])
+          return { 'name' => params[:collection].to_s }
+        elsif collection_name?(params[:collection_name])
+          # @deprecated 0.6.0
+          tools.core_tools.deprecate(
+            ':collection_name parameter is deprecated',
+            message: 'Use the :name parameter instead.'
+          )
+
+          return { 'name' => params[:collection_name].to_s }
+        elsif VALID_PARAMETERS.any? { |key| params.key?(key) }
+          return Cuprum::Collections::Relations::Parameters
+              .resolve_parameters(params)
+              .slice(*VALID_PARAMETERS)
+              .to_h { |key, value| [key.to_s, value.to_s] }
+        end
+
+        raise ArgumentError, "collection, name or entity class can't be blank"
+      end
+
+      private
+
+      def collection_details(collection)
+        entity_class = collection.entity_class
+        entity_class = entity_class.name if entity_class.is_a?(Class)
+
+        {
+          'entity_class'   => entity_class,
+          'name'           => collection.name,
+          'qualified_name' => collection.qualified_name
+        }
+      end
+
+      def collection_name?(value)
+        return false unless value.is_a?(String) || value.is_a?(Symbol)
+
+        !value.to_s.empty?
+      end
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+    end
 
-    # @overload initialize(attribute_name:, attribute_value:, collection_name:, primary_key: false)
-    #   @param attribute_name [String] The name of the queried attribute.
-    #   @param attribute_value [Object] The value of the queried attribute.
-    #   @param collection_name [String] The name of the collection.
-    #   @param primary_key [true, false] Indicates that the queried attribute is
+    # @overload initialize(attribute_name:, attribute_value:, name:, primary_key: false)
+    #   @param attribute_name [String] the name of the queried attribute.
+    #   @param attribute_value [Object] the value of the queried attribute.
+    #   @param name [String] the name of the collection.
+    #   @param primary_key [true, false] indicates that the queried attribute is
     #     the primary key for the collection.
     #
-    # @overload initialize(attributes:, collection_name:)
-    #   @param attributes [Hash<String=>Object>] The queried attributes.
-    #   @param collection_name [String] The name of the collection.
+    # @overload initialize(attributes:, name:)
+    #   @param attributes [Hash<String=>Object>] the queried attributes.
+    #   @param name [String] the name of the collection.
     #
-    # @overload initialize(query:, collection_name:)
-    #   @param collection_name [String] The name of the collection.
+    # @overload initialize(query:, name:)
+    #   @param name [String] the name of the collection.
     #   @param query [Cuprum::Collections::Query] The performed query.
-    def initialize(collection_name:, **options) # rubocop:disable Metrics/MethodLength
-      @collection_name = collection_name
+    def initialize(**params) # rubocop:disable Metrics/MethodLength
+      @collection      = self.class.resolve_collection(**params)
+      @collection_name = @collection['name']
       @primary_key     = false
 
-      resolve_options(**options)
+      resolve_options(**params.except(*COLLECTION_KEYWORDS))
 
       super(
         attribute_name:,
         attribute_value:,
         attributes:,
-        collection_name:,
         message:         generate_message,
         scope:
       )
@@ -53,12 +119,24 @@ module Cuprum::Collections::Errors
     # @return [Hash<String=>Object>] The queried attributes.
     attr_reader :attributes
 
-    # @return [String] the name of the collection.
-    attr_reader :collection_name
+    # @return [Hash] the resolved collection details.
+    attr_reader :collection
 
     # @return [Cuprum::Collections::Scopes::Base] the query scope, if any.
     attr_reader :scope
 
+    # @return [String] the name of the collection.
+    #
+    # @deprecated 0.6.0
+    def collection_name
+      tools.core_tools.deprecate(
+        '#collection_name is deprecated',
+        message: 'Use the #collection method instead.'
+      )
+
+      collection['name']
+    end
+
     # @return [Array<Array>] the details of the query, in scope format.
     def details # rubocop:disable Metrics/MethodLength
       if attribute_name
@@ -86,13 +164,13 @@ module Cuprum::Collections::Errors
 
     def as_json_data
       {
-        'collection_name' => collection_name,
-        'details'         => details
+        'collection' => collection,
+        'details'    => details
       }.merge(find_data)
     end
 
     def entity_name
-      titleize(tools.str.singularize(collection_name))
+      titleize(tools.str.singularize(collection['name']))
     end
 
     def find_data # rubocop:disable Metrics/MethodLength
@@ -161,7 +239,7 @@ module Cuprum::Collections::Errors
         resolve_query_options(**options)
       else
         raise ArgumentError,
-          'missing keywords :attribute_name, :attribute_value or :attributes ' \
+          'missing keywords :attribute_name, :attribute_value, :attributes, ' \
           'or :query'
       end
     end
@@ -177,7 +255,7 @@ module Cuprum::Collections::Errors
     def validate_keywords(extra_keywords:) # rubocop:disable Metrics/MethodLength
       return if extra_keywords.empty?
 
-      ambiguous_keywords = extra_keywords & PERMITTED_KEYWORDS
+      ambiguous_keywords = extra_keywords & QUERYING_KEYWORDS
 
       if ambiguous_keywords.empty?
         raise ArgumentError,

data/lib/cuprum/collections/errors/extra_attributes.rb

@@ -15,7 +15,7 @@ module Cuprum::Collections::Errors
     #   that were assigned to the entity.
     # @param valid_attributes [Array<String>] The names of valid attributes for
     #   the entity.
-    def initialize(entity_class:, extra_attributes:, valid_attributes:)
+    def initialize(extra_attributes:, valid_attributes:, entity_class: nil)
       @entity_class     = entity_class
       @extra_attributes = extra_attributes
       @valid_attributes = valid_attributes
@@ -42,14 +42,14 @@ module Cuprum::Collections::Errors
 
     def as_json_data
       {
-        'entity_class'     => entity_class.name,
+        'entity_class'     => entity_class&.name,
         'extra_attributes' => extra_attributes,
         'valid_attributes' => valid_attributes
       }
     end
 
     def default_message
-      "invalid attributes for #{entity_class.name}: " \
+      "invalid attributes for #{entity_class&.name || 'an entity'}: " \
         "#{extra_attributes.join(', ')}"
     end
   end

data/lib/cuprum/collections/errors/failed_validation.rb

@@ -13,7 +13,7 @@ module Cuprum::Collections::Errors
     # @param entity_class [Class] The class of the assigned entity.
     # @param errors [Stannum::Errors] The errors generated when validating the
     #   entity.
-    def initialize(entity_class:, errors:)
+    def initialize(errors:, entity_class: nil)
       @entity_class = entity_class
       @errors       = errors
 
@@ -34,13 +34,13 @@ module Cuprum::Collections::Errors
 
     def as_json_data
       {
-        'entity_class' => entity_class.name,
+        'entity_class' => entity_class&.name,
         'errors'       => format_errors
       }
     end
 
     def default_message
-      "#{entity_class.name} failed validation"
+      "#{entity_class&.name || 'an entity'} failed validation"
     end
 
     def format_errors

data/lib/cuprum/collections/errors/missing_default_contract.rb

@@ -11,7 +11,7 @@ module Cuprum::Collections::Errors
     TYPE = 'cuprum.collections.errors.missing_default_contract'
 
     # @param entity_class [Class] The class of the assigned entity.
-    def initialize(entity_class:)
+    def initialize(entity_class: nil)
       @entity_class = entity_class
 
       super(
@@ -26,12 +26,20 @@ module Cuprum::Collections::Errors
     private
 
     def as_json_data
-      { 'entity_class' => entity_class.name }
+      { 'entity_class' => entity_class&.name }
     end
 
     def default_message
-      "attempted to validate a #{entity_class.name}, but " \
-        "#{entity_class.name} does not define a default contract"
+      "attempted to validate #{entity_name}, but " \
+        "#{entity_class_name} does not define a default contract"
+    end
+
+    def entity_class_name
+      entity_class&.name || 'the entity class'
+    end
+
+    def entity_name
+      entity_class ? "a #{entity_class.name}" : 'an entity'
     end
   end
 end