cuprum-collections 0.1.0

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/constraints/attribute_name'
+require 'cuprum/collections/constraints/order'
+require 'cuprum/collections/constraints/order/sort_direction'
+
+module Cuprum::Collections::Constraints::Order
+  # Asserts that the object is a Hash of attribute names and sort directions.
+  class AttributesHash < Stannum::Constraints::Types::HashType
+    # @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(
+        key_type:   Cuprum::Collections::Constraints::AttributeName.instance,
+        value_type: Cuprum::Collections::Constraints::Order::SortDirection
+          .instance,
+        **options
+      )
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/constraints/order'
+require 'cuprum/collections/constraints/order/attributes_array'
+require 'cuprum/collections/constraints/order/attributes_hash'
+
+module Cuprum::Collections::Constraints::Order
+  # Asserts that the object is an attributes Array with an sort order Hash.
+  class ComplexOrdering < Stannum::Constraints::Base
+    # @return [Cuprum::Collections::Constraints::Order::AttributesArray] a
+    #   cached instance of the constraint with default options.
+    def self.instance
+      @instance ||= new
+    end
+
+    # Checks that the given object is a complex ordering.
+    #
+    # A complex ordering is a data structure consisting of an Array of zero or
+    # more attribute names, with the last item in the array a Hash of attribute
+    # names and sort directions, e.g. [:title, :author, { publisher: 'asc' }].
+    #
+    # @param actual [Object] The object to match.
+    #
+    # @return [true, false] true if the object matches the expected properties
+    #   or behavior, otherwise false.
+    def matches?(actual)
+      return false unless actual.is_a?(Array)
+
+      array = actual.dup
+      hash  = array.pop
+
+      array_constraint.matches?(array) && hash_constraint.matches?(hash)
+    end
+    alias match? matches?
+
+    private
+
+    def array_constraint
+      Cuprum::Collections::Constraints::Order::AttributesArray.instance
+    end
+
+    def hash_constraint
+      Cuprum::Collections::Constraints::Order::AttributesHash.instance
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/enum'
+
+require 'cuprum/collections/constraints/order'
+
+module Cuprum::Collections::Constraints::Order
+  # Asserts that the object is a valid direction for a sort.
+  class SortDirection < Stannum::Constraints::Enum
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'cuprum.collections.constraints.is_valid_sort_direction'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'cuprum.collections.constraints.is_not_valid_sort_direction'
+
+    # @return [Cuprum::Collections::Constraints::AttributeName] a cached
+    #   instance of the constraint with default options.
+    def self.instance
+      @instance ||= new
+    end
+
+    def initialize(**options)
+      super(*sort_directions, **options)
+    end
+
+    private
+
+    def sort_directions
+      %w[asc ascending desc descending] + %i[asc ascending desc descending]
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/constraints'
+
+module Cuprum::Collections::Constraints
+  # Namespace for constraints that validate query ordering.
+  module Order; end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types/array_type'
+require 'stannum/constraints/types/hash_type'
+require 'stannum/constraints/union'
+require 'stannum/support/optional'
+
+require 'cuprum/collections/constraints'
+require 'cuprum/collections/constraints/attribute_name'
+require 'cuprum/collections/constraints/order/attributes_array'
+require 'cuprum/collections/constraints/order/attributes_hash'
+require 'cuprum/collections/constraints/order/complex_ordering'
+
+module Cuprum::Collections::Constraints
+  # Asserts that the object is a valid query ordering.
+  #
+  # A valid ordering can be any of the following:
+  # - An attribute name (a non-empty string or symbol).
+  #   e.g. 'name' or :title
+  # - An array of attribute names
+  #   e.g. ['author', 'title']
+  # - A hash with attribute key names, whose values are valid sort directions.
+  #   e.g. { author: :ascending, title: :descending }
+  # - An array of attribute names, followed by a valid hash.
+  #   e.g. ['author', { title: :descending }]
+  #
+  # Valid sort directions are :ascending and :descending (or :asc and :desc),
+  # and can be either strings or symbols.
+  class Ordering < Stannum::Constraints::Union
+    include Stannum::Support::Optional
+
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'cuprum.collections.constraints.is_valid_ordering'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'cuprum.collections.constraints.is_not_valid_ordering'
+
+    # @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(optional: nil, required: nil, **options)
+      super(
+        *ordering_constraints,
+        **resolve_required_option(
+          optional: optional,
+          required: required,
+          **options
+        )
+      )
+    end
+
+    # @overload errors_for(actual, errors: nil)
+    #   Generates an errors object for the given object.
+    #
+    #   @param actual [Object] The object to generate errors for.
+    #   @param errors [Stannum::Errors] The errors object to append errors to.
+    #     If an errors object is not given, a new errors object will be created.
+    #
+    #   @return [Stannum::Errors] the given or generated errors object.
+    def errors_for(_actual, errors: nil)
+      (errors || Stannum::Errors.new).add(type)
+    end
+
+    # Checks that the given object matches the constraint.
+    #
+    # @param actual [Object] The object to match.
+    #
+    # @return [true, false] true if the object is a valid ordering; otherwise
+    #   false.
+    def matches?(actual)
+      return true if optional? && actual.nil?
+
+      super
+    end
+    alias match? matches?
+
+    # @overload negated_errors_for(actual, errors: nil)
+    #   Generates an errors object for the given object when negated.
+    #
+    #   @param actual [Object] The object to generate errors for.
+    #   @param errors [Stannum::Errors] The errors object to append errors to.
+    #     If an errors object is not given, a new errors object will be created.
+    #
+    #   @return [Stannum::Errors] the given or generated errors object.
+    def negated_errors_for(_actual, errors: nil)
+      (errors || Stannum::Errors.new).add(negated_type)
+    end
+
+    # Creates a copy of the constraint and updates the copy's options.
+    #
+    # @param options [Hash] The options to update.
+    #
+    # @return [Stannum::Constraints::Base] the copied constraint.
+    def with_options(**options)
+      super(**resolve_required_option(**options))
+    end
+
+    private
+
+    def ordering_constraints
+      [
+        Cuprum::Collections::Constraints::AttributeName.instance,
+        Cuprum::Collections::Constraints::Order::AttributesArray.instance,
+        Cuprum::Collections::Constraints::Order::AttributesHash.instance,
+        Cuprum::Collections::Constraints::Order::ComplexOrdering.instance
+      ]
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types/hash_type'
+
+require 'cuprum/collections/constraints'
+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)
+      super(
+        allow_empty: true,
+        key_type:    attribute_name_constraint,
+        **options
+      )
+    end
+
+    private
+
+    def attribute_name_constraint
+      Cuprum::Collections::Constraints::AttributeName.instance
+    end
+  end
+end

data/lib/cuprum/collections/constraints.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # Namespace for Stannum constraints, which are used for parameter validation.
+  module Constraints; end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/collections/errors'
+
+module Cuprum::Collections::Errors
+  # Returned when an insert command is called with an existing record.
+  class AlreadyExists < Cuprum::Error
+    # 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
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/collections/errors'
+
+module Cuprum::Collections::Errors
+  # Error returned when assigning invalid attributes to an entity.
+  class ExtraAttributes < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.collections.errors.extra_attributes'
+
+    # @param entity_class [Class] The class of the assigned entity.
+    # @param extra_attributes [Array<String>] The names of the extra attributes
+    #   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:)
+      @entity_class     = entity_class
+      @extra_attributes = extra_attributes
+      @valid_attributes = valid_attributes
+
+      super(
+        entity_class:     entity_class,
+        extra_attributes: extra_attributes,
+        message:          default_message,
+        valid_attributes: valid_attributes
+      )
+    end
+
+    # @return [Class] the class of the assigned entity.
+    attr_reader :entity_class
+
+    # @return [Array<String>] The names of the extra attributes that were
+    #   assigned to the entity.
+    attr_reader :extra_attributes
+
+    # @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
+      {
+        'data'    => {
+          'entity_class'     => entity_class.name,
+          'extra_attributes' => extra_attributes,
+          'valid_attributes' => valid_attributes
+        },
+        'message' => message,
+        'type'    => type
+      }
+    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(', ')}"
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+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'
+
+    # @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:)
+      @entity_class = entity_class
+      @errors       = errors
+
+      super(
+        entity_class: entity_class,
+        errors:       errors,
+        message:      default_message
+      )
+    end
+
+    # @return [Class] the class of the assigned entity.
+    attr_reader :entity_class
+
+    # @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
+      {
+        'data'    => {
+          'entity_class' => entity_class.name,
+          'errors'       => format_errors
+        },
+        'message' => message,
+        'type'    => type
+      }
+    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
+
+    def format_errors
+      errors
+        .with_messages
+        .group_by_path { |err| err[:message] }
+        .transform_keys { |path| path.map(&:to_s).join('.') }
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/collections/errors'
+
+module Cuprum::Collections::Errors
+  # An error returned when a command is called with invalid parameters.
+  class InvalidParameters < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.collections.errors.invalid_parameters'
+
+    # @param command [Cuprum::Command] the called command.
+    # @param errors [Stannum::Errors] the errors returned by the parameters
+    #   contract.
+    def initialize(command:, errors:)
+      @command = command
+      @errors  = errors
+
+      super(
+        command: command,
+        errors:  errors,
+        message: "invalid parameters for command #{command.class}"
+      )
+    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
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/collections/errors'
+
+module Cuprum::Collections::Errors
+  # An error returned when a query is created with invalid filter parameters.
+  class InvalidQuery < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.collections.errors.invalid_query'
+
+    # @param errors [Stannum::Errors] The errors returned by the query builder.
+    # @param strategy [Symbol] The strategy used to construct the query.
+    def initialize(errors:, strategy:, message: nil)
+      @errors   = errors
+      @strategy = strategy
+
+      super(
+        errors:   errors,
+        message:  message || default_message,
+        strategy: strategy
+      )
+    end
+
+    # @return [Stannum::Errors] the errors returned by the query builder.
+    attr_reader :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
+      {
+        'data'    => {
+          'errors'   => errors.to_a,
+          'strategy' => strategy
+        },
+        'message' => message,
+        'type'    => type
+      }
+    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
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+
+require 'cuprum/collections/errors'
+
+module Cuprum::Collections::Errors
+  # Error returned when validating an entity without a contract.
+  class MissingDefaultContract < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.collections.errors.missing_default_contract'
+
+    # @param entity_class [Class] The class of the assigned entity.
+    def initialize(entity_class:)
+      @entity_class = entity_class
+
+      super(
+        entity_class: entity_class,
+        message:      default_message
+      )
+    end
+
+    # @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
+
+    # @return [String] short string used to identify the type of error.
+    def type
+      TYPE
+    end
+
+    private
+
+    def default_message
+      "attempted to validate a #{entity_class.name}, but #{entity_class.name}" \
+        ' does not define a default contract'
+    end
+  end
+end