cuprum-collections 0.1.0

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+require 'sleeping_king_studios/tools/toolbelt'
+
+require 'cuprum/collections/errors'
+
+module Cuprum::Collections::Errors
+  # Returned when a find command does not find the requested items.
+  class NotFound < Cuprum::Error
+    # 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
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors'
+require 'cuprum/collections/queries'
+
+module Cuprum::Collections::Errors
+  # An error returned when a query attempts to filter by an unknown operator.
+  class UnknownOperator < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.collections.errors.unknown_operator'
+
+    # @param operator [String, Symbol] The unknown operator.
+    def initialize(operator:)
+      @operator = operator
+
+      super(
+        message:  generate_message,
+        operator: operator
+      )
+    end
+
+    # @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 ||=
+        DidYouMean::SpellChecker
+          .new(dictionary: Cuprum::Collections::Queries::VALID_OPERATORS.to_a)
+          .correct(operator)
+    end
+
+    # @return [String] short string used to identify the type of error.
+    def type
+      TYPE
+    end
+
+    private
+
+    def generate_message
+      message = "unknown operator #{operator.inspect}"
+
+      return message if corrections.empty?
+
+      "#{message} - did you mean #{suggestion}?"
+    end
+
+    def suggestion
+      tools.ary.humanize_list(
+        corrections.map(&:inspect),
+        last_separator: ', or '
+      )
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/collections/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # Namespace for errors, which represent failure states of commands.
+  module Errors; end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/constraints/ordering'
+require 'cuprum/collections/queries'
+
+module Cuprum::Collections::Queries
+  # Functionality around validating and normalizing query sort orderings.
+  module Ordering
+    # Exception class for handling invalid order keywords.
+    class InvalidOrderError < ArgumentError; end
+
+    ORDER_HASH_VALUES = {
+      asc:        :asc,
+      ascending:  :asc,
+      desc:       :desc,
+      descending: :desc
+    }.freeze
+    private_constant :ORDER_HASH_VALUES
+
+    class << self
+      # @overload normalize(*attributes, ordering_hash = nil)
+      #   Converts the given sort order into a hash with standard values.
+      #
+      #   @param attributes [Array<String, Symbol>] The attribute names to sort
+      #     by, in ascending direction, and in order of importance.
+      #   @param ordering_hash [Hash] An optional ordering hash, with keys that
+      #     are valid attribute names and values that are valid sort directions.
+      #
+      #   @return [Hash] the normalized sort ordering.
+      #
+      #   @raise InvalidOrderError if any of the attributes are invalid
+      #     attribute names.
+      #   @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)
+        validate_ordering!(attributes)
+
+        qualified = attributes.last.is_a?(Hash) ? attributes.pop : {}
+        qualified = normalize_order_hash(qualified)
+
+        attributes
+          .each
+          .with_object({}) { |attribute, hsh| hsh[attribute.intern] = :asc }
+          .merge(qualified)
+      end
+
+      private
+
+      def normalize_order_hash(hsh)
+        hsh.each.with_object({}) do |(key, value), normalized|
+          normalized[key.intern] = normalize_order_hash_value(value)
+        end
+      end
+
+      def normalize_order_hash_value(value)
+        value = value.downcase if value.is_a?(String)
+
+        ORDER_HASH_VALUES.fetch(value.is_a?(String) ? value.intern : value)
+      end
+
+      def ordering_constraint
+        Cuprum::Collections::Constraints::Ordering.instance
+      end
+
+      def validate_ordering!(attributes)
+        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'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/queries'
+require 'cuprum/collections/queries/parse_strategy'
+
+module Cuprum::Collections::Queries
+  # Command to parse parameters passed to Query#where into criteria.
+  class Parse < Cuprum::Command
+    private
+
+    def process(where:, strategy: nil)
+      command = step do
+        Cuprum::Collections::Queries::ParseStrategy.new.call(
+          strategy: strategy,
+          where:    where
+        )
+      end
+
+      command.call(where: where)
+    end
+  end
+end

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

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'cuprum/errors/uncaught_exception'
+require 'stannum/contracts/parameters_contract'
+
+require 'cuprum/collections/command'
+require 'cuprum/collections/constraints/query_hash'
+require 'cuprum/collections/errors/invalid_query'
+require 'cuprum/collections/errors/unknown_operator'
+require 'cuprum/collections/queries'
+
+module Cuprum::Collections::Queries
+  # Command for parsing a Query#where block into criteria.
+  #
+  # @example An Empty Query
+  #   command = Cuprum::Collections::Queries::ParseBlock.new
+  #   result  = command.call { {} }
+  #   result.value #=> []
+  #
+  # @example A Value Query
+  #   command = Cuprum::Collections::Queries::ParseBlock.new
+  #   result  = command.call do
+  #     {
+  #       author: 'Nnedi Okorafor',
+  #       series: 'Binti',
+  #       genre:  'Africanfuturism'
+  #     }
+  #   end
+  #   result.value #=>
+  #   # [
+  #   #   ['author', :eq, 'Nnedi Okorafor'],
+  #   #   ['series', :eq, 'Binti'],
+  #   #   ['genre',  :eq, 'Africanfuturism']
+  #   # ]
+  #
+  # @example A Query With Operators
+  #   command = Cuprum::Collections::Queries::ParseBlock.new
+  #   result  = command.call do
+  #     {
+  #       author: equal('Nnedi Okorafor'),
+  #       series: not_equal('Binti')
+  #     }
+  #   end
+  #   result.value #=>
+  #   # [
+  #   #   ['author', :eq, 'Nnedi Okorafor'],
+  #   #   ['series', :ne, 'Binti']
+  #   # ]
+  class ParseBlock < Cuprum::Collections::Command
+    # Evaluation context for query blocks.
+    class Builder < BasicObject
+      # Generates an equality criterion.
+      #
+      # @return [Array] the equality criterion.
+      def equals(value)
+        [nil, Operators::EQUAL, value]
+      end
+      alias equal equals
+      alias eq equals
+
+      # Generates a greater than comparison criterion.
+      #
+      # @return [Array] the greater than criterion.
+      def greater_than(value)
+        [nil, Operators::GREATER_THAN, value]
+      end
+      alias gt greater_than
+
+      # Generates a greater than or equal to comparison criterion.
+      #
+      # @return [Array] the greater than or equal to criterion.
+      def greater_than_or_equal_to(value)
+        [nil, Operators::GREATER_THAN_OR_EQUAL_TO, value]
+      end
+      alias gte greater_than_or_equal_to
+
+      # Generates a less than comparison criterion.
+      #
+      # @return [Array] the less than criterion.
+      def less_than(value)
+        [nil, Operators::LESS_THAN, value]
+      end
+      alias lt less_than
+
+      # Generates a less than or equal to comparison criterion.
+      #
+      # @return [Array] the less than or equal to criterion.
+      def less_than_or_equal_to(value)
+        [nil, Operators::LESS_THAN_OR_EQUAL_TO, value]
+      end
+      alias lte less_than_or_equal_to
+
+      # Generates a negated equality criterion.
+      #
+      # @return [Array] the negated equality criterion.
+      def not_equal(value)
+        [nil, Operators::NOT_EQUAL, value]
+      end
+      alias ne not_equal
+
+      # Generates a negated inclusion criterion.
+      #
+      # @return [Array] the negated inclusion criterion.
+      def not_one_of(value)
+        [nil, Operators::NOT_ONE_OF, value]
+      end
+
+      # Generates an inclusion criterion.
+      #
+      # @return [Array] the inclusion criterion.
+      def one_of(value)
+        [nil, Operators::ONE_OF, value]
+      end
+    end
+
+    class << self
+      extend Forwardable
+
+      def_delegators :validation_contract,
+        :errors_for,
+        :match,
+        :matches?
+
+      private
+
+      def validation_contract
+        self::MethodValidations.contracts.fetch(:call)
+      end
+    end
+
+    validate_parameters :call do
+      keyword :where, Proc
+    end
+
+    private
+
+    def call_block(&block)
+      handle_unknown_operator { Builder.new.instance_exec(&block) }
+    rescue StandardError => exception
+      error = Cuprum::Errors::UncaughtException.new(
+        exception: exception,
+        message:   'uncaught exception when parsing query block'
+      )
+
+      failure(error)
+    end
+
+    def generate_criteria(hsh)
+      hsh.map do |key, value|
+        unless partial_criterion?(value)
+          next [key.to_s, Cuprum::Collections::Queries::Operators::EQUAL, value]
+        end
+
+        value.tap { |ary| ary[0] = key.to_s }
+      end
+    end
+
+    def handle_unknown_operator
+      yield
+    rescue NoMethodError => exception
+      error = Cuprum::Collections::Errors::UnknownOperator.new(
+        operator: exception.name
+      )
+
+      failure(error)
+    end
+
+    def invalid_query_error(errors:, message: nil)
+      Cuprum::Collections::Errors::InvalidQuery.new(
+        errors:   errors,
+        message:  message,
+        strategy: :block
+      )
+    end
+
+    def partial_criterion?(obj)
+      return false unless obj.is_a?(Array) && obj.size == 3
+
+      attribute, operator, _value = obj
+
+      return false unless attribute.nil?
+
+      Cuprum::Collections::Queries::VALID_OPERATORS.include?(operator)
+    end
+
+    def process(where:)
+      hsh = step { call_block(&where) }
+
+      step { validate_hash(hsh) }
+
+      generate_criteria(hsh)
+    end
+
+    def validate_hash(obj)
+      constraint    = Cuprum::Collections::Constraints::QueryHash.new
+      match, errors = constraint.match(obj)
+
+      return if match
+
+      message = 'query block returned invalid value'
+      failure(invalid_query_error(errors: errors, message: message))
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/queries'
+require 'cuprum/collections/queries/parse_block'
+require 'cuprum/collections/errors/invalid_query'
+
+module Cuprum::Collections::Queries
+  # Command to select the parsing strategy for parsing Query#where parameters.
+  class ParseStrategy < Cuprum::Command
+    STRATEGIES = {
+      block: Cuprum::Collections::Queries::ParseBlock
+    }.freeze
+    private_constant :STRATEGIES
+
+    # The :type of the error generated for an unknown parsing strategy.
+    UNKNOWN_STRATEGY_ERROR =
+      'cuprum.collections.errors.queries.unknown_strategy'
+
+    private
+
+    def find_and_validate_strategy(strategy:, where:)
+      command_class = step { find_strategy_by_key(strategy: strategy) }
+      parameters    = {
+        arguments: [],
+        block:     nil,
+        keywords:  { where: where }
+      }
+
+      return command_class if command_class.matches?(parameters)
+
+      errors = command_class.errors_for(parameters)
+
+      failure(invalid_parameters_error(errors: errors, strategy: strategy))
+    end
+
+    def find_strategy(strategy:, where:)
+      if strategy
+        return find_and_validate_strategy(strategy: strategy, where: where)
+      end
+
+      command_class = find_strategy_by_parameters(where: where)
+
+      return command_class if command_class
+
+      failure(unknown_strategy_error(strategy: strategy))
+    end
+
+    def find_strategy_by_key(strategy:)
+      STRATEGIES.fetch(strategy) do
+        failure(unknown_strategy_error(strategy: strategy))
+      end
+    end
+
+    def find_strategy_by_parameters(where:)
+      STRATEGIES
+        .values
+        .find do |command_class|
+          command_class.matches?(
+            arguments: [],
+            block:     nil,
+            keywords:  { where: where }
+          )
+        end
+    end
+
+    def invalid_parameters_error(errors:, strategy:)
+      Cuprum::Collections::Errors::InvalidQuery.new(
+        errors:   errors,
+        strategy: strategy
+      )
+    end
+
+    def process(strategy: nil, where: nil)
+      command_class = step do
+        find_strategy(strategy: strategy, where: where)
+      end
+
+      command_class.new
+    end
+
+    def unknown_strategy_error(strategy:)
+      errors = Stannum::Errors.new
+      errors[:strategy].add(UNKNOWN_STRATEGY_ERROR, strategy: strategy)
+
+      Cuprum::Collections::Errors::InvalidQuery.new(
+        errors:   errors,
+        strategy: strategy
+      )
+    end
+  end
+end

data/lib/cuprum/collections/queries.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbox/constant_map'
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # Namespace for internal functionality for implementing collection queries.
+  module Queries
+    # Defines the supported operators for a Query.
+    Operators = SleepingKingStudios::Tools::Toolbox::ConstantMap.new(
+      EQUAL:                    :equal,
+      GREATER_THAN:             :greater_than,
+      GREATER_THAN_OR_EQUAL_TO: :greater_than_or_equal_to,
+      LESS_THAN:                :less_than,
+      LESS_THAN_OR_EQUAL_TO:    :less_than_or_equal_to,
+      NOT_EQUAL:                :not_equal,
+      NOT_ONE_OF:               :not_one_of,
+      ONE_OF:                   :one_of
+    ).freeze
+
+    # Enumerates the valid operators as a Set for performant lookup.
+    VALID_OPERATORS = Set.new(Operators.values).freeze
+  end
+end