cuprum-collections 0.5.1 → 0.6.0.rc.0

data/lib/cuprum/collections/adapters/entity_adapter.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/adapter'
+require 'cuprum/collections/adapters'
+
+module Cuprum::Collections::Adapters
+  # Utility class for converting between attributes and a Stannum::Entity class.
+  class EntityAdapter < Cuprum::Collections::Adapter
+    # @param options [Hash] options for initializing the adapter.
+    #
+    # @option options attributes_names [Array<String, Symbol>] the valid
+    #   attribute names for a data object. Defaults to the entity class's
+    #   attributes. Must be a subset of the entity class's attributes.
+    # @option options default_contract [Stannum::Constraints:Base] the contract
+    #   used to validate instances of the data object.
+    # @option options entity_class [Class] the class of the data objects. Must
+    #   be a Stannum::Enttiy subclass.
+    def initialize(entity_class:, **options)
+      if options[:allow_extra_attributes]
+        raise ArgumentError, 'adapter does not support extra attributes'
+      end
+
+      attribute_names = options.fetch(:attribute_names) do
+        entity_class?(entity_class) ? entity_class&.attributes&.keys || [] : []
+      end
+
+      super(attribute_names:, entity_class:, **options)
+
+      verify_attribute_names_are_attributes
+    end
+
+    private
+
+    def build_entity(attributes:)
+      entity_class.new(**attributes)
+    end
+
+    def default_contract_for(**)
+      return default_contract if default_contract
+
+      entity_class.contract
+    end
+
+    def entity_class?(entity_class)
+      entity_class.is_a?(Class) && entity_class < Stannum::Entity
+    end
+
+    def merge_entity(attributes:, entity:)
+      entity.dup.tap { |copy| copy.assign_attributes(attributes) }
+    end
+
+    def serialize_entity(entity:)
+      entity.attributes
+    end
+
+    def validate_entity_class_parameter(entity_class, as: 'entity class')
+      tools.assertions.validate_class(entity_class, as:)
+
+      return if entity_class < Stannum::Entity
+
+      raise ArgumentError, "#{as} is not a Stannum::Entity"
+    end
+
+    def verify_attribute_names_are_attributes
+      invalid_names = attribute_names - (entity_class&.attributes&.keys || [])
+
+      return if invalid_names.empty?
+
+      error_message =
+        "attribute names #{invalid_names.join(', ')} are not attributes of " \
+        "#{entity_class.name || 'the entity class'}"
+
+      raise ArgumentError, error_message
+    end
+  end
+end

data/lib/cuprum/collections/adapters/hash_adapter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/adapter'
+require 'cuprum/collections/adapters'
+
+module Cuprum::Collections::Adapters
+  # Utility class for converting between raw attributes and a data Hash.
+  class HashAdapter < Cuprum::Collections::Adapter
+    # @param options [Hash] options for initializing the adapter.
+    #
+    # @option options allow_extra_attributes [true, false] if false, attributes
+    #   methods return an error for attributes not in attributes_names. Defaults
+    #   to true if attribute_names is empty, otherwise false.
+    # @option options attributes_names [Array<String, Symbol>] the valid
+    #   attribute names for a data object. Defaults to [].
+    # @option options default_contract [Stannum::Constraints:Base] the contract
+    #   used to validate instances of the data object.
+    def initialize(**options)
+      if options[:entity_class]
+        raise ArgumentError, 'adapter does not support entity class'
+      end
+
+      super(entity_class: Hash, **options)
+    end
+
+    private
+
+    def build_entity(attributes:)
+      attributes = tools.hash_tools.convert_keys_to_strings(attributes)
+
+      empty_attributes.merge(attributes)
+    end
+
+    def empty_attributes
+      @empty_attributes ||= attribute_names.to_h { |key| [key, nil] }
+    end
+
+    def merge_entity(attributes:, entity:)
+      attributes = tools.hash_tools.convert_keys_to_strings(attributes)
+
+      entity.merge(attributes)
+    end
+
+    def serialize_entity(entity:)
+      entity.dup
+    end
+  end
+end

data/lib/cuprum/collections/adapters.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # Namespace for adapter implementations.
+  #
+  # @see Cuprum::Collections::Adapter.
+  module Adapters
+    autoload :DataAdapter,   'cuprum/collections/adapters/data_adapter'
+    autoload :EntityAdapter, 'cuprum/collections/adapters/entity_adapter'
+    autoload :HashAdapter,   'cuprum/collections/adapters/hash_adapter'
+  end
+end

data/lib/cuprum/collections/basic/collection.rb

@@ -27,7 +27,7 @@ module Cuprum::Collections::Basic
     #     [Cuprum::Collections::Scopes::Base, Hash, Proc, nil] the configured
     #     scope for the relation.
     def initialize(data: [], **parameters)
-      super(**normalize_parameters(**parameters))
+      super(default_entity_class: Hash, **parameters)
 
       @data = data
     end
@@ -71,7 +71,7 @@ module Cuprum::Collections::Basic
       Cuprum::Collections::Basic::Commands::ValidateOne.new(collection: self)
     end
 
-    # @return [Stannum::Constraints::Base, nil] the #   default contract for
+    # @return [Stannum::Constraints::Base, nil] the default contract for
     #   validating items in the collection.
     def default_contract
       @options[:default_contract]
@@ -98,23 +98,5 @@ module Cuprum::Collections::Basic
     def default_scope
       Cuprum::Collections::Basic::Scopes::AllScope.new
     end
-
-    def normalize_parameters(**parameters) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-      return parameters if parameters.key?(:entity_class)
-
-      return parameters unless parameters[:name] || parameters[:qualified_name]
-
-      parameters = parameters.merge(entity_class: Hash)
-
-      if parameters.key?(:name) && parameters.key?(:qualified_name)
-        parameters
-      elsif parameters.key?(:name)
-        parameters.merge(qualified_name: parameters[:name])
-      elsif parameters.key?(:qualified_name)
-        name = parameters[:qualified_name].split('/').last
-
-        parameters.merge(name:)
-      end
-    end
   end
 end

data/lib/cuprum/collections/basic/commands/destroy_one.rb

@@ -28,7 +28,7 @@ module Cuprum::Collections::Basic::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/basic/commands/find_many.rb

@@ -10,36 +10,5 @@ module Cuprum::Collections::Basic::Commands
   # Command for finding multiple collection items by primary key.
   class FindMany < Cuprum::Collections::Basic::Command
     include Cuprum::Collections::Commands::AbstractFindMany
-
-    # @!method call(primary_keys:, allow_partial: false, envelope: false)
-    #   Queries the collection for the items with the given primary keys.
-    #
-    #   The command will find and return the entities with the given primary
-    #   keys. If any of the items are not found, the command will fail and
-    #   return a NotFound error. If the :allow_partial option is set, the
-    #   command will return a partial result unless none of the requested items
-    #   are found.
-    #
-    #   When the :envelope option is true, the command wraps the items in a
-    #   Hash, using the name of the collection as the key.
-    #
-    #   @param allow_partial [Boolean] If true, passes if any of the items are
-    #     found.
-    #   @param envelope [Boolean] If true, wraps the result value in a Hash.
-    #   @param primary_keys [Array] The primary keys of the requested items.
-    #
-    #   @return [Cuprum::Result<Array<Hash{String, Object}>>] a result with the
-    #     requested items.
-    validate :allow_partial, :boolean, optional: true
-    validate :envelope,      :boolean, optional: true
-    validate :primary_keys
-
-    private
-
-    def items_with_primary_keys(items:)
-      # :nocov:
-      items.to_h { |item| [item[primary_key_name.to_s], item] }
-      # :nocov:
-    end
   end
 end

data/lib/cuprum/collections/basic/commands/find_matching.rb

@@ -12,99 +12,5 @@ module Cuprum::Collections::Basic::Commands
   # Command for querying filtered, ordered data from a basic collection.
   class FindMatching < Cuprum::Collections::Basic::Command
     include Cuprum::Collections::Commands::AbstractFindMatching
-
-    # @!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
   end
 end

data/lib/cuprum/collections/basic/commands/find_one.rb

@@ -10,23 +10,5 @@ module Cuprum::Collections::Basic::Commands
   # Command for finding one collection item by primary key.
   class FindOne < Cuprum::Collections::Basic::Command
     include Cuprum::Collections::Commands::AbstractFindOne
-
-    # @!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
   end
 end

data/lib/cuprum/collections/basic/commands/insert_one.rb

@@ -31,7 +31,7 @@ module Cuprum::Collections::Basic::Commands
       error = Cuprum::Collections::Errors::AlreadyExists.new(
         attribute_name:  primary_key_name,
         attribute_value: value,
-        collection_name:,
+        name:,
         primary_key:     true
       )
       failure(error)

data/lib/cuprum/collections/basic/commands/update_one.rb

@@ -31,7 +31,7 @@ module Cuprum::Collections::Basic::Commands
       error = Cuprum::Collections::Errors::NotFound.new(
         attribute_name:  primary_key_name,
         attribute_value: entity[primary_key_name.to_s],
-        collection_name:,
+        name:,
         primary_key:     true
       )
       failure(error)

data/lib/cuprum/collections/basic/scopes/criteria_scope.rb

@@ -13,6 +13,40 @@ module Cuprum::Collections::Basic::Scopes
     Operators = Cuprum::Collections::Queries::Operators
     private_constant :Operators
 
+    FILTERS = {
+      Operators::EQUAL                    => lambda { |item, attribute, value|
+        item[attribute] == value
+      },
+      Operators::GREATER_THAN             => lambda { |item, attribute, value|
+        item[attribute] > value
+      },
+      Operators::GREATER_THAN_OR_EQUAL_TO => lambda { |item, attribute, value|
+        item[attribute] >= value
+      },
+      Operators::LESS_THAN                => lambda { |item, attribute, value|
+        item[attribute] < value
+      },
+      Operators::LESS_THAN_OR_EQUAL_TO    => lambda { |item, attribute, value|
+        item[attribute] <= value
+      },
+      Operators::NOT_EQUAL                => lambda { |item, attribute, value|
+        item[attribute] != value
+      },
+      Operators::NOT_NULL                 => lambda { |item, attribute, _value|
+        !item[attribute].nil?
+      },
+      Operators::NOT_ONE_OF               => lambda { |item, attribute, value|
+        !value.include?(item[attribute])
+      },
+      Operators::NULL                     => lambda { |item, attribute, _value|
+        item[attribute].nil?
+      },
+      Operators::ONE_OF                   => lambda { |item, attribute, value|
+        value.include?(item[attribute])
+      }
+    }.freeze
+    private_constant :FILTERS
+
     # Returns true if the provided item matches the configured criteria.
     def match?(item:)
       super
@@ -31,27 +65,8 @@ module Cuprum::Collections::Basic::Scopes
 
     private
 
-    def filter_for(operator) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-      case operator
-      when Operators::EQUAL
-        @eq_filter ||= ->(item, attribute, value) { item[attribute] == value }
-      when Operators::GREATER_THAN
-        @gt_filter ||= ->(item, attribute, value) { item[attribute] > value }
-      when Operators::GREATER_THAN_OR_EQUAL_TO
-        @gte_filter ||= ->(item, attribute, value) { item[attribute] >= value }
-      when Operators::LESS_THAN
-        @lt_filter ||= ->(item, attribute, value) { item[attribute] < value }
-      when Operators::LESS_THAN_OR_EQUAL_TO
-        @lte_filter ||= ->(item, attribute, value) { item[attribute] <= value }
-      when Operators::NOT_EQUAL
-        @ne_filter ||= ->(item, attribute, value) { item[attribute] != value }
-      when Operators::NOT_ONE_OF
-        @nin_filter ||=
-          ->(item, attribute, value) { !value.include?(item[attribute]) }
-      when Operators::ONE_OF
-        @in_filter ||=
-          ->(item, attribute, value) { value.include?(item[attribute]) }
-      else
+    def filter_for(operator)
+      FILTERS.fetch(operator) do
         error_class = Cuprum::Collections::Queries::UnknownOperatorException
         message     = %(unknown operator "#{operator}")
 

data/lib/cuprum/collections/basic.rb

@@ -5,13 +5,14 @@ require 'cuprum/collections'
 module Cuprum::Collections
   # The Basic collection is an example, in-memory collection implementation.
   module Basic
-    # Returns a new instance of Basic::Collection.
+    # @overload new(**options)
+    #   Returns a new instance of Basic::Collection.
     #
-    # @param options [Hash] Constructor options for the collection.
+    #   @param options [Hash] Constructor options for the collection.
     #
-    # @see Cuprum::Collections::Basic::Collection#initialize.
-    def self.new(**options)
-      Cuprum::Collections::Basic::Collection.new(**options)
+    #   @see Cuprum::Collections::Basic::Collection#initialize.
+    def self.new(**)
+      Cuprum::Collections::Basic::Collection.new(**)
     end
 
     autoload :Collection, 'cuprum/collections/basic/collection'

data/lib/cuprum/collections/collection.rb

@@ -66,6 +66,12 @@ module Cuprum::Collections
         )
       end
 
+      expected[:name] = expected[:name].to_s if expected[:name]
+
+      if expected[:qualified_name]
+        expected[:qualified_name] = expected[:qualified_name].to_s
+      end
+
       comparable_options >= expected
     end
 

data/lib/cuprum/collections/collection_command.rb

@@ -46,7 +46,7 @@ module Cuprum::Collections
       collection.query
     end
 
-    # @returnb [String] the name of an entity in the collection.
+    # @return [String] the name of an entity in the collection.
     def singular_name
       @singular_name ||= collection.singular_name
     end

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

@@ -1,11 +1,39 @@
 # frozen_string_literal: true
 
+require 'cuprum/parameter_validation'
+require 'stannum/constraints/boolean'
+
 require 'cuprum/collections/commands'
 require 'cuprum/collections/errors/not_found'
 
 module Cuprum::Collections::Commands
   # Abstract implementation of the FindMany command.
   module AbstractFindMany
+    include Cuprum::ParameterValidation
+
+    # @!method call(primary_keys:, allow_partial: false, envelope: false)
+    #   Queries the collection for the items with the given primary keys.
+    #
+    #   The command will find and return the entities with the given primary
+    #   keys. If any of the items are not found, the command will fail and
+    #   return a NotFound error. If the :allow_partial option is set, the
+    #   command will return a partial result unless none of the requested items
+    #   are found.
+    #
+    #   When the :envelope option is true, the command wraps the items in a
+    #   Hash, using the name of the collection as the key.
+    #
+    #   @param allow_partial [Boolean] If true, passes if any of the items are
+    #     found.
+    #   @param envelope [Boolean] If true, wraps the result value in a Hash.
+    #   @param primary_keys [Array] The primary keys of the requested items.
+    #
+    #   @return [Cuprum::Result<Array<Hash{String, Object}>>] a result with the
+    #     requested items.
+    validate :allow_partial, :boolean, optional: true
+    validate :envelope,      :boolean, optional: true
+    validate :primary_keys
+
     private
 
     def apply_query(primary_keys:)
@@ -36,7 +64,16 @@ module Cuprum::Collections::Commands
 
     def items_with_primary_keys(items:)
       # :nocov:
-      items.to_h { |item| [item.send(primary_key_name), item] }
+      items.to_h do |item|
+        primary_key_value =
+          if item.respond_to?(:[])
+            item[primary_key_name.to_s] || item[primary_key_name.to_sym]
+          else
+            item.send(primary_key_name)
+          end
+
+        [primary_key_value, item]
+      end
       # :nocov:
     end
 
@@ -44,7 +81,7 @@ module Cuprum::Collections::Commands
       Cuprum::Collections::Errors::NotFound.new(
         attribute_name:  primary_key_name,
         attribute_value: primary_key_value,
-        collection_name:,
+        name:,
         primary_key:     true
       )
     end
@@ -62,7 +99,7 @@ module Cuprum::Collections::Commands
     end
 
     def wrap_items(items)
-      { collection_name => items }
+      { name => items }
     end
   end
 end