cuprum-collections 0.1.0 → 0.3.0.rc.0

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

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors'
+
+module Cuprum::Collections::Errors
+  # Abstract base class for failed query errors.
+  class AbstractFindError < Cuprum::Error # rubocop:disable Metrics/ClassLength
+    PERMITTED_KEYWORDS = %i[
+      attribute_name
+      attribute_value
+      attributes
+      primary_key
+      query
+    ].freeze
+    private_constant :PERMITTED_KEYWORDS
+
+    # @overload initialize(attribute_name:, attribute_value:, collection_name:, primary_key: false) # rubocop:disable Layout/LineLength
+    #   @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
+    #     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(query:, collection_name:)
+    #   @param collection_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
+      @primary_key     = false
+
+      resolve_options(**options)
+
+      super(
+        attribute_name:  attribute_name,
+        attribute_value: attribute_value,
+        attributes:      attributes,
+        collection_name: collection_name,
+        message:         generate_message,
+        query:           query&.criteria
+      )
+    end
+
+    # @return [String] the name of the queried attribute, if any.
+    attr_reader :attribute_name
+
+    # @return [Object] the value of the queried attribute, if any.
+    attr_reader :attribute_value
+
+    # @return [Hash<String=>Object>] The queried attributes.
+    attr_reader :attributes
+
+    # @return [String] the name of the collection.
+    attr_reader :collection_name
+
+    # @return [Cuprum::Collections::Query] the performed query, if any.
+    attr_reader :query
+
+    # @return [Array<Array>] the details of the query, in query criteria format.
+    def details
+      if attribute_name
+        [[attribute_name, :equal, attribute_value]]
+      elsif attributes
+        attributes
+          .map { |attr_name, attr_value| [attr_name, :equal, attr_value] }
+      elsif query
+        query.criteria
+      end
+    end
+
+    # @return [true, false] indicates that the queried attribute is the primary
+    #   key for the collection.
+    def primary_key?
+      @primary_key
+    end
+
+    private
+
+    def as_json_data
+      {
+        'collection_name' => collection_name,
+        'details'         => details
+      }.merge(find_data)
+    end
+
+    def entity_name
+      titleize(tools.str.singularize(collection_name))
+    end
+
+    def find_data # rubocop:disable Metrics/MethodLength
+      if attribute_name
+        {
+          'attribute_name'  => attribute_name,
+          'attribute_value' => attribute_value,
+          'primary_key'     => primary_key?
+        }
+      elsif attributes
+        hsh = tools.hash_tools.convert_keys_to_strings(attributes)
+
+        { 'attributes' => hsh }
+      else
+        {}
+      end
+    end
+
+    def generate_message
+      core_message = "#{entity_name} #{message_fragment}"
+
+      if attribute_name
+        "#{core_message} with #{attribute_name.inspect} " \
+          "#{attribute_value.inspect}" \
+          "#{primary_key? ? ' (primary key)' : ''}"
+      elsif attributes
+        "#{core_message} with attributes #{attributes.inspect}"
+      elsif query
+        "#{core_message} matching the query"
+      end
+    end
+
+    def message_fragment
+      'query failed'
+    end
+
+    def resolve_attribute_options(**options)
+      options          = options.dup
+      @attribute_name  = options.delete(:attribute_name)
+      @attribute_value = options.delete(:attribute_value)
+      @primary_key     = options.delete(:primary_key) || false
+
+      validate_keywords(extra_keywords: options.keys)
+    end
+
+    def resolve_attributes_options(**options)
+      options     = options.dup
+      @attributes = options.delete(:attributes)
+
+      validate_keywords(extra_keywords: options.keys)
+    end
+
+    def resolve_query_options(**options)
+      options = options.dup
+      @query  = options.delete(:query)
+
+      validate_keywords(extra_keywords: options.keys)
+    end
+
+    def resolve_options(**options) # rubocop:disable Metrics/MethodLength
+      if options[:primary_key_name] && options[:primary_key_values]
+        resolve_primary_key_options(**options)
+      elsif options[:attribute_name] && options.key?(:attribute_value)
+        resolve_attribute_options(**options)
+      elsif options[:attributes]
+        resolve_attributes_options(**options)
+      elsif options[:query]
+        resolve_query_options(**options)
+      else
+        raise ArgumentError,
+          'missing keywords :attribute_name, :attribute_value or :attributes ' \
+          'or :query'
+      end
+    end
+
+    def resolve_primary_key_options(**options) # rubocop:disable Metrics/MethodLength
+      values = Array(options[:primary_key_values])
+
+      unless values.size == 1
+        raise ArgumentError,
+          'deprecated mode does not support empty or multiple attribute values'
+      end
+
+      SleepingKingStudios::Tools::CoreTools
+        .instance
+        .deprecate(
+          'NotFound.new(primary_key_name:, primary_key_values:)',
+          message: 'use NotFound.new(attribute_name:, attribute_value:)'
+        )
+
+      @attribute_name  = options[:primary_key_name]
+      @attribute_value = values.first
+      @primary_key     = true
+    end
+
+    def titleize(string)
+      tools.str.underscore(string).split('_').map(&:capitalize).join(' ')
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validate_keywords(extra_keywords:) # rubocop:disable Metrics/MethodLength
+      return if extra_keywords.empty?
+
+      ambiguous_keywords = extra_keywords & PERMITTED_KEYWORDS
+
+      if ambiguous_keywords.empty?
+        raise ArgumentError,
+          "unknown keyword#{extra_keywords.size == 1 ? '' : 's'} " \
+          "#{extra_keywords.map(&:inspect).join(', ')}"
+      else
+        raise ArgumentError,
+          "ambiguous keyword#{extra_keywords.size == 1 ? '' : 's'} " \
+          "#{ambiguous_keywords.map(&:inspect).join(', ')}"
+      end
+    end
+  end
+end

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

@@ -1,86 +1,18 @@
 # frozen_string_literal: true
 
-require 'cuprum/error'
-
 require 'cuprum/collections/errors'
+require 'cuprum/collections/errors/abstract_find_error'
 
 module Cuprum::Collections::Errors
   # Returned when an insert command is called with an existing record.
-  class AlreadyExists < Cuprum::Error
+  class AlreadyExists < Cuprum::Collections::Errors::AbstractFindError
     # Short string used to identify the type of error.
     TYPE = 'cuprum.collections.errors.already_exists'
 
-    # @param collection_name [String, Symbol] The name of the collection.
-    # @param primary_key_name [String, Symbol] The name of the primary key
-    #   attribute.
-    # @param primary_key_values [Object, Array] The expected values of the
-    #   primary key attribute.
-    def initialize(collection_name:, primary_key_name:, primary_key_values:)
-      @collection_name    = collection_name
-      @primary_key_name   = primary_key_name
-      @primary_key_values = Array(primary_key_values)
-
-      super(
-        collection_name:    collection_name,
-        message:            default_message,
-        primary_key_name:   primary_key_name,
-        primary_key_values: primary_key_values
-      )
-    end
-
-    # @return [String, Symbol] the name of the collection.
-    attr_reader :collection_name
-
-    # @return [String, Symbol] the name of the primary key attribute.
-    attr_reader :primary_key_name
-
-    # @return [Array] The expected values of the primary key attribute.
-    attr_reader :primary_key_values
-
-    # @return [Hash] a serializable hash representation of the error.
-    def as_json
-      {
-        'data'    => {
-          'collection_name'    => collection_name,
-          'primary_key_name'   => primary_key_name,
-          'primary_key_values' => primary_key_values
-        },
-        'message' => message,
-        'type'    => type
-      }
-    end
-
-    # @return [String] short string used to identify the type of error.
-    def type
-      TYPE
-    end
-
     private
 
-    def default_message
-      primary_keys = primary_key_values.map(&:inspect).join(', ')
-
-      "#{entity_name} already exist#{singular? ? 's' : ''} with" \
-        " #{primary_key_name} #{primary_keys}"
-    end
-
-    def entity_name
-      entity_name = collection_name
-      entity_name = tools.str.singularize(entity_name) if singular?
-
-      titleize(entity_name)
-    end
-
-    def singular?
-      primary_key_values.size == 1
-    end
-
-    def titleize(string)
-      tools.str.underscore(string).split('_').map(&:capitalize).join(' ')
-    end
-
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
+    def message_fragment
+      'already exists'
     end
   end
 end

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

@@ -38,29 +38,19 @@ module Cuprum::Collections::Errors
     # @return [Array<String>] The names of valid attributes for the entity.
     attr_reader :valid_attributes
 
-    # @return [Hash] a serializable hash representation of the error.
-    def as_json
+    private
+
+    def as_json_data
       {
-        'data'    => {
-          'entity_class'     => entity_class.name,
-          'extra_attributes' => extra_attributes,
-          'valid_attributes' => valid_attributes
-        },
-        'message' => message,
-        'type'    => type
+        'entity_class'     => entity_class.name,
+        'extra_attributes' => extra_attributes,
+        'valid_attributes' => valid_attributes
       }
     end
 
-    # @return [String] short string used to identify the type of error.
-    def type
-      TYPE
-    end
-
-    private
-
     def default_message
-      "invalid attributes for #{entity_class.name}:" \
-        " #{extra_attributes.join(', ')}"
+      "invalid attributes for #{entity_class.name}: " \
+        "#{extra_attributes.join(', ')}"
     end
   end
 end

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

@@ -7,9 +7,6 @@ require 'cuprum/collections/errors'
 module Cuprum::Collections::Errors
   # Error returned when a collection item fails validation.
   class FailedValidation < Cuprum::Error
-    COMPARABLE_PROPERTIES = %i[entity_class errors message].freeze
-    private_constant :COMPARABLE_PROPERTIES
-
     # Short string used to identify the type of error.
     TYPE = 'cuprum.collections.errors.failed_validation'
 
@@ -33,25 +30,15 @@ module Cuprum::Collections::Errors
     # @return [Stannum::Errors] The errors generated when validating the entity.
     attr_reader :errors
 
-    # @return [Hash] a serializable hash representation of the error.
-    def as_json
+    private
+
+    def as_json_data
       {
-        'data'    => {
-          'entity_class' => entity_class.name,
-          'errors'       => format_errors
-        },
-        'message' => message,
-        'type'    => type
+        'entity_class' => entity_class.name,
+        'errors'       => format_errors
       }
     end
 
-    # @return [String] short string used to identify the type of error.
-    def type
-      TYPE
-    end
-
-    private
-
     def default_message
       "#{entity_class.name} failed validation"
     end

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

@@ -24,27 +24,19 @@ module Cuprum::Collections::Errors
       )
     end
 
-    # @return [Hash] a serializable hash representation of the error.
-    def as_json
-      {
-        'data'    => {
-          'command_class' => command.class.name,
-          'errors'        => errors.to_a
-        },
-        'message' => message,
-        'type'    => type
-      }
-    end
-
     # @return [Cuprum::Command] the called command.
     attr_reader :command
 
     # @return [Stannum::Errors] the errors returned by the parameters contract.
     attr_reader :errors
 
-    # @return [String] short string used to identify the type of error.
-    def type
-      TYPE
+    private
+
+    def as_json_data
+      {
+        'command_class' => command.class.name,
+        'errors'        => errors.to_a
+      }
     end
   end
 end

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

@@ -29,25 +29,15 @@ module Cuprum::Collections::Errors
     # @return [Symbol] the strategy used to construct the query.
     attr_reader :strategy
 
-    # @return [Hash] a serializable hash representation of the error.
-    def as_json
+    private
+
+    def as_json_data
       {
-        'data'    => {
-          'errors'   => errors.to_a,
-          'strategy' => strategy
-        },
-        'message' => message,
-        'type'    => type
+        'errors'   => errors.to_a,
+        'strategy' => strategy
       }
     end
 
-    # @return [String] short string used to identify the type of error.
-    def type
-      TYPE
-    end
-
-    private
-
     def default_message
       "unable to parse query with strategy #{strategy.inspect}"
     end

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

@@ -23,27 +23,15 @@ module Cuprum::Collections::Errors
     # @return [Class] the class of the assigned entity.
     attr_reader :entity_class
 
-    # @return [Hash] a serializable hash representation of the error.
-    def as_json
-      {
-        'data'    => {
-          'entity_class' => entity_class.name
-        },
-        'message' => message,
-        'type'    => type
-      }
-    end
+    private
 
-    # @return [String] short string used to identify the type of error.
-    def type
-      TYPE
+    def as_json_data
+      { 'entity_class' => entity_class.name }
     end
 
-    private
-
     def default_message
-      "attempted to validate a #{entity_class.name}, but #{entity_class.name}" \
-        ' does not define a default contract'
+      "attempted to validate a #{entity_class.name}, but " \
+        "#{entity_class.name} does not define a default contract"
     end
   end
 end

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

@@ -1,81 +1,18 @@
 # frozen_string_literal: true
 
-require 'cuprum/error'
-require 'sleeping_king_studios/tools/toolbelt'
-
 require 'cuprum/collections/errors'
+require 'cuprum/collections/errors/abstract_find_error'
 
 module Cuprum::Collections::Errors
   # Returned when a find command does not find the requested items.
-  class NotFound < Cuprum::Error
+  class NotFound < Cuprum::Collections::Errors::AbstractFindError
     # Short string used to identify the type of error.
     TYPE = 'cuprum.collections.errors.not_found'
 
-    # @param collection_name [String, Symbol] The name of the collection.
-    # @param primary_key_name [String, Symbol] The name of the primary key
-    #   attribute.
-    # @param primary_key_values [Object, Array] The expected values of the
-    #   primary key attribute.
-    def initialize(collection_name:, primary_key_name:, primary_key_values:)
-      @collection_name    = collection_name
-      @primary_key_name   = primary_key_name
-      @primary_key_values = Array(primary_key_values)
-
-      super(message: default_message)
-    end
-
-    # @return [String, Symbol] the name of the collection.
-    attr_reader :collection_name
-
-    # @return [String, Symbol] the name of the primary key attribute.
-    attr_reader :primary_key_name
-
-    # @return [Array] The expected values of the primary key attribute.
-    attr_reader :primary_key_values
-
-    # @return [Hash] a serializable hash representation of the error.
-    def as_json
-      {
-        'data'    => {
-          'collection_name'    => collection_name,
-          'primary_key_name'   => primary_key_name,
-          'primary_key_values' => primary_key_values
-        },
-        'message' => message,
-        'type'    => type
-      }
-    end
-
-    # @return [String] short string used to identify the type of error.
-    def type
-      TYPE
-    end
-
     private
 
-    def default_message
-      primary_keys = primary_key_values.map(&:inspect).join(', ')
-
-      "#{entity_name} not found with #{primary_key_name} #{primary_keys}"
-    end
-
-    def entity_name
-      entity_name = collection_name
-      entity_name = tools.str.singularize(entity_name) if singular?
-
-      titleize(entity_name)
-    end
-
-    def singular?
-      primary_key_values.size == 1
-    end
-
-    def titleize(string)
-      tools.str.underscore(string).split('_').map(&:capitalize).join(' ')
-    end
-
-    def tools
-      SleepingKingStudios::Tools::Toolbelt.instance
+    def message_fragment
+      'not found'
     end
   end
 end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors'
+require 'cuprum/collections/errors/abstract_find_error'
+
+module Cuprum::Collections::Errors
+  # Returned when a unique find command does finds multiple items.
+  class NotUnique < Cuprum::Collections::Errors::AbstractFindError
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.collections.errors.not_unique'
+
+    private
+
+    def message_fragment
+      'not unique'
+    end
+  end
+end

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

@@ -22,18 +22,6 @@ module Cuprum::Collections::Errors
     # @return [String, Symbol] the unknown operator.
     attr_reader :operator
 
-    # @return [Hash] a serializable hash representation of the error.
-    def as_json
-      {
-        'data'    => {
-          'corrections' => corrections,
-          'operator'    => operator
-        },
-        'message' => message,
-        'type'    => type
-      }
-    end
-
     # @return [Array<String>] Suggested possible values for the operator.
     def corrections
       @corrections ||=
@@ -42,13 +30,15 @@ module Cuprum::Collections::Errors
           .correct(operator)
     end
 
-    # @return [String] short string used to identify the type of error.
-    def type
-      TYPE
-    end
-
     private
 
+    def as_json_data
+      {
+        'corrections' => corrections,
+        'operator'    => operator
+      }
+    end
+
     def generate_message
       message = "unknown operator #{operator.inspect}"
 

data/lib/cuprum/collections/errors.rb

@@ -4,5 +4,17 @@ require 'cuprum/collections'
 
 module Cuprum::Collections
   # Namespace for errors, which represent failure states of commands.
-  module Errors; end
+  module Errors
+    autoload :AbstractFindError, 'cuprum/collections/errors/abstract_find_error'
+    autoload :AlreadyExists,     'cuprum/collections/errors/already_exists'
+    autoload :ExtraAttributes,   'cuprum/collections/errors/extra_attributes'
+    autoload :FailedValidation,  'cuprum/collections/errors/failed_validation'
+    autoload :InvalidParameters, 'cuprum/collections/errors/invalid_parameters'
+    autoload :InvalidQuery,      'cuprum/collections/errors/invalid_query'
+    autoload :MissingDefaultContract,
+      'cuprum/collections/errors/missing_default_contract'
+    autoload :NotFound,          'cuprum/collections/errors/not_found'
+    autoload :NotUnique,         'cuprum/collections/errors/not_unique'
+    autoload :UnknownOperator,   'cuprum/collections/errors/unknown_operator'
+  end
 end

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

@@ -33,6 +33,8 @@ module Cuprum::Collections::Queries
       #   @raise InvalidOrderError if any of the hash keys are invalid attribute
       #     names, or any of the hash values are invalid sort directions.
       def normalize(*attributes)
+        attributes = attributes.flatten if attributes.first.is_a?(Array)
+
         validate_ordering!(attributes)
 
         qualified = attributes.last.is_a?(Hash) ? attributes.pop : {}
@@ -66,8 +68,8 @@ module Cuprum::Collections::Queries
         return if ordering_constraint.matches?(attributes)
 
         raise InvalidOrderError,
-          'order must be a list of attribute names and/or a hash of attribute' \
-          ' names with values :asc or :desc'
+          'order must be a list of attribute names and/or a hash of ' \
+          'attribute names with values :asc or :desc'
       end
     end
   end