cuprum-collections 0.4.0 → 0.5.0

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

@@ -100,22 +100,22 @@ module Cuprum::Collections::Commands
 
     def create_entity(attributes:)
       Cuprum::Collections::Commands::Create
-        .new(collection: collection, contract: contract)
-        .call(attributes: attributes)
+        .new(collection:, contract:)
+        .call(attributes:)
     end
 
     def filter_attributes(attributes:)
       tools
         .hash_tools
         .convert_keys_to_strings(attributes)
-        .select { |key, _| attribute_names.include?(key) }
+        .slice(*attribute_names)
     end
 
     def find_entity(attributes:)
-      filtered = filter_attributes(attributes: attributes)
+      filtered = filter_attributes(attributes:)
       result   =
         Cuprum::Collections::Commands::FindOneMatching
-          .new(collection: collection)
+          .new(collection:)
           .call(attributes: filtered)
 
       return if result.error.is_a?(Cuprum::Collections::Errors::NotFound)
@@ -140,12 +140,12 @@ module Cuprum::Collections::Commands
     end
 
     def process(attributes:)
-      entity = step { find_entity(attributes: attributes) }
+      entity = step { find_entity(attributes:) }
 
       if entity
-        update_entity(attributes: attributes, entity: entity)
+        update_entity(attributes:, entity:)
       else
-        create_entity(attributes: attributes)
+        create_entity(attributes:)
       end
     end
 
@@ -155,8 +155,8 @@ module Cuprum::Collections::Commands
 
     def update_entity(attributes:, entity:)
       Cuprum::Collections::Commands::Update
-        .new(collection: collection, contract: contract)
-        .call(attributes: attributes, entity: entity)
+        .new(collection:, contract:)
+        .call(attributes:, entity:)
     end
   end
 end

data/lib/cuprum/collections/commands.rb

@@ -8,6 +8,7 @@ module Cuprum::Collections
     autoload :Associations,    'cuprum/collections/commands/associations'
     autoload :Create,          'cuprum/collections/commands/create'
     autoload :FindOneMatching, 'cuprum/collections/commands/find_one_matching'
+    autoload :QueryCommand,    'cuprum/collections/commands/query_command'
     autoload :Update,          'cuprum/collections/commands/update'
     autoload :Upsert,          'cuprum/collections/commands/upsert'
   end

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

@@ -47,8 +47,8 @@ module Cuprum::Collections::Constraints
       super(
         *ordering_constraints,
         **resolve_required_option(
-          optional: optional,
-          required: required,
+          optional:,
+          required:,
           **options
         )
       )

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

@@ -35,12 +35,12 @@ module Cuprum::Collections::Errors
       resolve_options(**options)
 
       super(
-        attribute_name:  attribute_name,
-        attribute_value: attribute_value,
-        attributes:      attributes,
-        collection_name: collection_name,
+        attribute_name:,
+        attribute_value:,
+        attributes:,
+        collection_name:,
         message:         generate_message,
-        query:           query&.criteria
+        scope:
       )
     end
 
@@ -56,18 +56,23 @@ module Cuprum::Collections::Errors
     # @return [String] the name of the collection.
     attr_reader :collection_name
 
-    # @return [Cuprum::Collections::Query] the performed query, if any.
-    attr_reader :query
+    # @return [Cuprum::Collections::Scopes::Base] the query scope, if any.
+    attr_reader :scope
 
-    # @return [Array<Array>] the details of the query, in query criteria format.
-    def details
+    # @return [Array<Array>] the details of the query, in scope format.
+    def details # rubocop:disable Metrics/MethodLength
       if attribute_name
-        [[attribute_name, :equal, attribute_value]]
+        criteria = [[attribute_name, :equal, attribute_value]]
+
+        { 'type' => :criteria, 'criteria' => criteria }
       elsif attributes
-        attributes
-          .map { |attr_name, attr_value| [attr_name, :equal, attr_value] }
-      elsif query
-        query.criteria
+        criteria =
+          attributes
+            .map { |attr_name, attr_value| [attr_name, :equal, attr_value] }
+
+        { 'type' => :criteria, 'criteria' => criteria }
+      elsif scope
+        scope
       end
     end
 
@@ -112,10 +117,10 @@ module Cuprum::Collections::Errors
       if attribute_name
         "#{core_message} with #{attribute_name.inspect} " \
           "#{attribute_value.inspect}" \
-          "#{primary_key? ? ' (primary key)' : ''}"
+          "#{' (primary key)' if primary_key?}"
       elsif attributes
         "#{core_message} with attributes #{attributes.inspect}"
-      elsif query
+      elsif scope
         "#{core_message} matching the query"
       end
     end
@@ -142,15 +147,13 @@ module Cuprum::Collections::Errors
 
     def resolve_query_options(**options)
       options = options.dup
-      @query  = options.delete(:query)
+      @scope  = options.delete(:query)&.scope
 
       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)
+      if options[:attribute_name] && options.key?(:attribute_value)
         resolve_attribute_options(**options)
       elsif options[:attributes]
         resolve_attributes_options(**options)
@@ -163,26 +166,6 @@ module Cuprum::Collections::Errors
       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
@@ -198,11 +181,11 @@ module Cuprum::Collections::Errors
 
       if ambiguous_keywords.empty?
         raise ArgumentError,
-          "unknown keyword#{extra_keywords.size == 1 ? '' : 's'} " \
+          "unknown keyword#{'s' unless extra_keywords.size == 1} " \
           "#{extra_keywords.map(&:inspect).join(', ')}"
       else
         raise ArgumentError,
-          "ambiguous keyword#{extra_keywords.size == 1 ? '' : 's'} " \
+          "ambiguous keyword#{'s' unless extra_keywords.size == 1} " \
           "#{ambiguous_keywords.map(&:inspect).join(', ')}"
       end
     end

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

@@ -21,10 +21,10 @@ module Cuprum::Collections::Errors
       @valid_attributes = valid_attributes
 
       super(
-        entity_class:     entity_class,
-        extra_attributes: extra_attributes,
+        entity_class:,
+        extra_attributes:,
         message:          default_message,
-        valid_attributes: valid_attributes
+        valid_attributes:
       )
     end
 

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

@@ -18,8 +18,8 @@ module Cuprum::Collections::Errors
       @errors       = errors
 
       super(
-        entity_class: entity_class,
-        errors:       errors,
+        entity_class:,
+        errors:,
         message:      default_message
       )
     end

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

@@ -18,8 +18,8 @@ module Cuprum::Collections::Errors
       @errors  = errors
 
       super(
-        command: command,
-        errors:  errors,
+        command:,
+        errors:,
         message: "invalid parameters for command #{command.class}"
       )
     end

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

@@ -10,36 +10,30 @@ module Cuprum::Collections::Errors
     # 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
+    # @param query [Object] the given filter parameters, if any.
+    # @param message [String] the message to display.
+    def initialize(query:, message: nil)
+      @query = query
 
       super(
-        errors:   errors,
-        message:  message || default_message,
-        strategy: strategy
+        message: message || default_message,
+        query:
       )
     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 [Object] the given filter parameters, if any.
+    attr_reader :query
 
     private
 
     def as_json_data
       {
-        'errors'   => errors.to_a,
-        'strategy' => strategy
+        'query' => (query.respond_to?(:as_json) ? query.as_json : query.inspect)
       }
     end
 
     def default_message
-      "unable to parse query with strategy #{strategy.inspect}"
+      'unable to parse query'
     end
   end
 end

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

@@ -15,7 +15,7 @@ module Cuprum::Collections::Errors
       @entity_class = entity_class
 
       super(
-        entity_class: entity_class,
+        entity_class:,
         message:      default_message
       )
     end

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

@@ -15,7 +15,7 @@ module Cuprum::Collections::Errors
 
       super(
         message:  generate_message,
-        operator: operator
+        operator:
       )
     end
 

data/lib/cuprum/collections/queries.rb

@@ -19,6 +19,37 @@ module Cuprum::Collections
       ONE_OF:                   :one_of
     ).freeze
 
+    # Exception raised when trying to invert an operator with no inverse.
+    class UninvertibleOperatorException < StandardError; end
+
+    # Exception raised when an invalid operator is referenced.
+    class UnknownOperatorException < StandardError
+      # @param msg [String] the exception message.
+      # @param name [String] the name of the invalid operator.
+      def initialize(msg = nil, name = nil)
+        super(msg)
+
+        @name = name
+      end
+
+      # @return [String] the name of the invalid operator.
+      def name
+        @name || cause&.name
+      end
+    end
+
+    # Defines the negated operator corresponding to each operator.
+    INVERTIBLE_OPERATORS = {
+      Operators::EQUAL                    => Operators::NOT_EQUAL,
+      Operators::GREATER_THAN             => Operators::LESS_THAN_OR_EQUAL_TO,
+      Operators::GREATER_THAN_OR_EQUAL_TO => Operators::LESS_THAN,
+      Operators::LESS_THAN                => Operators::GREATER_THAN_OR_EQUAL_TO, # rubocop:disable Layout/LineLength
+      Operators::LESS_THAN_OR_EQUAL_TO    => Operators::GREATER_THAN,
+      Operators::NOT_EQUAL                => Operators::EQUAL,
+      Operators::NOT_ONE_OF               => Operators::ONE_OF,
+      Operators::ONE_OF                   => Operators::NOT_ONE_OF
+    }.freeze
+
     # Enumerates the valid operators as a Set for performant lookup.
     VALID_OPERATORS = Set.new(Operators.values).freeze
   end

data/lib/cuprum/collections/query.rb

@@ -2,38 +2,36 @@
 
 require 'cuprum/collections'
 require 'cuprum/collections/queries/ordering'
+require 'cuprum/collections/scopes/all_scope'
 
 module Cuprum::Collections
   # Abstract base class for collection Query implementations.
   class Query
+    include Enumerable
+
     UNDEFINED = Object.new.freeze
     private_constant :UNDEFINED
 
-    def initialize
-      @criteria = []
+    # @param scope [Cuprum::Collections::Scopes::Base] the base scope for the
+    #   query. Defaults to nil.
+    def initialize(scope: nil)
+      @limit  = nil
+      @offset = nil
+      @order  = {}
+      @scope  = scope ? default_scope.and(scope) : default_scope
     end
 
-    # Returns a normalized representation of the query criteria.
-    #
-    # The query criteria define which data from the collection matches the
-    # query. Specifically, an item in the collection matches the query if and
-    # only if it matches each criterion. If the query has no criteria, then it
-    # will match all items in the collection.
-    #
-    # Each criterion is represented as an Array with three elements:
-    # - The name of the property or column to select by.
-    # - The operation to filter, such as :eq (an equality operation).
-    # - The expected value.
+    # Returns the current scope for the query.
     #
-    # For example, a query that selects all items whose :series property is
-    # equal to 'The Lord of the Rings' would have the following criterion:
-    # `[:series, :eq, 'The Lord of the Rings']`.
+    # Composition methods should not be called on the scope directly, as they
+    # will not change the scope object bound to the query. Call the
+    # corresponding methods on the query itself, i.e. call query.where() instead
+    # of query.scope.where().
     #
-    # @return [Array<Array>] the query criteria.
-    #
-    # @see #where
-    def criteria
-      @criteria.dup
+    # @return [Cuprum::Collections::Scopes::Base] the current scope for the
+    #   query.
+    def scope
+      @scope ||= default_scope
     end
 
     # Sets or returns the maximum number of items returned by the query.
@@ -151,49 +149,35 @@ module Cuprum::Collections
       dup.reset!
     end
 
-    # Returns a copy of the query with the specified filters.
+    # @overload where(hash)
+    #   Returns a copy of the query with the specified filters.
     #
-    # The given parameters are used to construct query criteria, which define
-    # which data from the collection matches the query. Specifically, an item in
-    # the collection matches the query if and only if it matches each criterion.
-    # If the query has no criteria, then it will match all items in the
-    # collection.
+    #   If the query already has a scope, then the filters will be merged with
+    #   the existing scope. Any items in the collection must match both the
+    #   previous scope and the new criteria to be returned by the query.
     #
-    # When #where is called on a query that already defines criteria, then the
-    # new criteria are appended to the old. Any items in the collection must
-    # match both the old and the new criteria to be returned by the query.
+    #   @param hash [Hash{String=>Object}] the filters to apply to the query.
     #
-    # @example Filtering Data By Equality
-    #   # The query will only return items whose author is 'J.R.R. Tolkien'.
-    #   query = query.where { { author: 'J.R.R. Tolkien' } }
+    #   @example Filtering Data By Equality
+    #     # The query will only return items whose author is 'J.R.R. Tolkien'.
+    #     query = query.where { { author: 'J.R.R. Tolkien' } }
     #
-    # @example Filtering Data By Operator
-    #   # The query will only return items whose author is 'J.R.R. Tolkien',
-    #   # and whose series is not 'The Lord of the Rings'.
-    #   query = query.where do
-    #     {
-    #       author: eq('J.R.R. Tolkien'),
-    #       series: ne('The Lord of the Rings')
-    #     }
-    #   end
+    #   @see #scope
     #
     # @overload where(&block)
-    #   @yield The given block is passed to a QueryBuilder, which converts the
-    #     block to query criteria and generates a new query using those
-    #     criteria.
+    #   Returns a copy of the query with the specified filters.
     #
-    #   @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.
+    #   If the query already has a scope, then the filters will be merged with
+    #   the existing scope. Any items in the collection must match both the
+    #   previous scope and the new criteria to be returned by the query.
     #
-    # @see #criteria
-    def where(filter = nil, strategy: nil, &block)
-      filter ||= block
-
-      return dup if filter.nil? && strategy.nil?
-
-      query_builder.call(strategy: strategy, where: filter)
+    #   @yieldreturn [Hash{String=>Object}] 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.
+    def where(...)
+      dup.with_scope(scope.where(...)).reset!
     end
 
     protected
@@ -204,12 +188,6 @@ module Cuprum::Collections
       # :nocov:
     end
 
-    def with_criteria(criteria)
-      @criteria += criteria
-
-      self
-    end
-
     def with_limit(count)
       @limit = count
 
@@ -228,8 +206,18 @@ module Cuprum::Collections
       self
     end
 
+    def with_scope(scope)
+      @scope = scope
+
+      self
+    end
+
     private
 
+    def default_scope
+      Cuprum::Collections::Scopes::AllScope.new
+    end
+
     def validate_limit(count)
       return if count.is_a?(Integer) && !count.negative?