cuprum-collections 0.3.0 → 0.4.0

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

@@ -15,49 +15,25 @@ module Cuprum::Collections::Basic
       @data = data
     end
 
-    # Adds a new collection with the given name to the repository.
-    #
-    # @param collection_name [String] The name of the new collection.
-    # @param data [Hash<String, Object>] The inital data for the collection. If
-    #   not specified, defaults to the data used to initialize the repository.
-    # @param options [Hash] Additional options to pass to Collection.new
-    #
-    # @return [Cuprum::Collections::Basic::Collection] the created collection.
-    #
-    # @see Cuprum::Collections::Basic::Collection#initialize.
-    def build(collection_name:, data: nil, **options)
-      validate_collection_name!(collection_name)
+    private
+
+    def build_collection(data: nil, **parameters)
       validate_data!(data)
 
-      collection = Cuprum::Collections::Basic.new(
-        collection_name: collection_name,
-        data:            data || @data.fetch(collection_name.to_s, []),
-        **options
-      )
+      qualified_name =
+        Cuprum::Collections::Relation::Disambiguation
+          .resolve_parameters(parameters, name: :collection_name)
+          .fetch(:qualified_name)
 
-      add(collection)
+      data ||= @data.fetch(qualified_name, [])
 
-      collection
+      Cuprum::Collections::Basic.new(data: data, **parameters)
     end
 
-    private
-
     def valid_collection?(collection)
       collection.is_a?(Cuprum::Collections::Basic::Collection)
     end
 
-    def validate_collection_name!(name)
-      raise ArgumentError, "collection name can't be blank" if name.nil?
-
-      unless name.is_a?(String) || name.is_a?(Symbol)
-        raise ArgumentError, 'collection name must be a String or Symbol'
-      end
-
-      return unless name.empty?
-
-      raise ArgumentError, "collection name can't be blank"
-    end
-
     def validate_data!(data)
       return if data.nil? || data.is_a?(Array)
 

data/lib/cuprum/collections/basic.rb

@@ -18,5 +18,6 @@ module Cuprum::Collections
     autoload :Command,    'cuprum/collections/basic/command'
     autoload :Commands,   'cuprum/collections/basic/commands'
     autoload :Query,      'cuprum/collections/basic/query'
+    autoload :Repository, 'cuprum/collections/basic/repository'
   end
 end

data/lib/cuprum/collections/collection.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'cuprum/command_factory'
+
+require 'cuprum/collections'
+require 'cuprum/collections/relation'
+
+module Cuprum::Collections
+  # Provides a base implementation for collections.
+  class Collection < Cuprum::CommandFactory
+    include Cuprum::Collections::Relation::Parameters
+    include Cuprum::Collections::Relation::PrimaryKeys
+    include Cuprum::Collections::Relation::Disambiguation
+
+    # Error raised when trying to call an abstract collection method.
+    class AbstractCollectionError < StandardError; end
+
+    IGNORED_PARAMETERS = %i[
+      collection_name
+      entity_class
+      member_name
+      name
+      qualified_name
+      singular_name
+    ].freeze
+    private_constant :IGNORED_PARAMETERS
+
+    # @overload initialize(entity_class: nil, name: nil, qualified_name: nil, singular_name: nil, **options)
+    #   @param entity_class [Class, String] the class of entity represented by
+    #     the relation.
+    #   @param name [String] the name of the relation.
+    #   @param qualified_name [String] a scoped name for the relation.
+    #   @param singular_name [String] the name of an entity in the relation.
+    #   @param options [Hash] additional options for the relation.
+    #
+    #   @option options primary_key_name [String] the name of the primary key
+    #     attribute. Defaults to 'id'.
+    #   @option primary_key_type [Class, Stannum::Constraint] the type of
+    #     the primary key attribute. Defaults to Integer.
+    def initialize(**parameters) # rubocop:disable Metrics/MethodLength
+      super()
+
+      relation_params = resolve_parameters(
+        parameters,
+        name:          :collection_name,
+        singular_name: :member_name
+      )
+      @entity_class   = relation_params[:entity_class]
+      @name           = relation_params[:name]
+      @plural_name    = relation_params[:plural_name]
+      @qualified_name = relation_params[:qualified_name]
+      @singular_name  = relation_params[:singular_name]
+
+      @options = ignore_parameters(**parameters)
+    end
+
+    # @return [Hash<Symbol>] additional options for the collection.
+    attr_reader :options
+
+    # @param other [Object] The object to compare.
+    #
+    # @return [true, false] true if the other object is a collection with the
+    #   same options, otherwise false.
+    def ==(other)
+      return false unless self.class == other.class
+
+      comparable_options == other.comparable_options
+    end
+
+    # @return [String] the name of the collection.
+    def collection_name
+      tools.core_tools.deprecate '#collection_name method',
+        message: 'Use #name instead'
+
+      name
+    end
+
+    # @return [Integer] the count of items in the collection.
+    def count
+      query.count
+    end
+    alias size count
+
+    # Checks if the collection matches the expected options.
+    #
+    # @param expected [Hash] the options to compare.
+    #
+    # @return [Boolean] true if all of the expected options match, otherwise
+    #   false.
+    def matches?(**expected)
+      if expected[:entity_class].is_a?(String)
+        expected = expected.merge(
+          entity_class: Object.const_get(expected[:entity_class])
+        )
+      end
+
+      comparable_options >= expected
+    end
+
+    # @return [String] the name of an entity in the relation.
+    def member_name
+      tools.core_tools.deprecate '#member_name method',
+        message: 'Use #singular_name instead'
+
+      singular_name
+    end
+
+    # A new Query instance, used for querying against the collection data.
+    #
+    # @return [Object] the query.
+    def query
+      raise AbstractCollectionError,
+        "#{self.class.name} is an abstract class. Define a repository " \
+        'subclass and implement the #query method.'
+    end
+
+    protected
+
+    def comparable_options
+      command_options.merge(
+        name:           name,
+        qualified_name: qualified_name,
+        singular_name:  singular_name
+      )
+    end
+
+    private
+
+    def command_options
+      @command_options ||= {
+        collection_name:  name,
+        entity_class:     entity_class,
+        member_name:      singular_name,
+        primary_key_name: primary_key_name,
+        primary_key_type: primary_key_type,
+        **options
+      }
+    end
+
+    def ignore_parameters(**parameters)
+      parameters
+        .reject { |key, _| ignored_parameters.include?(key) }
+        .to_h
+    end
+
+    def ignored_parameters
+      @ignored_parameters ||= Set.new(IGNORED_PARAMETERS)
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/collections/commands/associations/find_many.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands/associations'
+
+module Cuprum::Collections::Commands::Associations
+  # Command for querying entities by association.
+  class FindMany < Cuprum::Command
+    PERMITTED_KEYWORDS = Set.new(%i[entities entity key keys]).freeze
+    private_constant :PERMITTED_KEYWORDS
+
+    # @!method call(**params)
+    #   @overload call(key:)
+    #     Finds the association values for the given key.
+    #
+    #     @param key [Object] the primary or foreign key for querying the
+    #       association.
+    #
+    #     @return [Object, nil] the association value or nil, if the association
+    #       is singular.
+    #     @return [Array<Object>] the association values, if the association is
+    #       plural.
+    #
+    #   @overload call(keys:)
+    #     Finds the association values for the given Array of keys.
+    #     @return [Array<Object>] the association values.
+    #
+    #     @param keys [Array<Object>] the primary or foreign keys for querying
+    #       the association.
+    #
+    #     @return [Array<Object>] the association values.
+    #
+    #   @overload call(entity:)
+    #     Finds the association values for the given entity.
+    #
+    #     @param entity [Object] the base entity for querying the association.
+    #
+    #     @return [Object, nil] the association value or nil, if the association
+    #       is singular.
+    #     @return [Array<Object>] the association values, if the association is
+    #       plural.
+    #
+    #   @overload call(entities:)
+    #     Finds the association values for the given Array of entities.
+    #
+    #     @param entity [Array<Object>] the base entities for querying the
+    #       association.
+    #
+    #     @return [Array<Object>] the association values.
+
+    # @param association [Cuprum::Collections::Association] the association to
+    #   query.
+    # @param repository [Cuprum::Collections::Repository] the repository to
+    #   query from.
+    # @param resource [Cuprum::Collections::Resource] the base resource for the
+    #   association.
+    def initialize(association:, repository:, resource:)
+      super()
+
+      @association = association
+      @repository  = repository
+      @resource    = resource
+    end
+
+    # @return [Cuprum::Collections::Association] the association to query.
+    attr_reader :association
+
+    # @return [Cuprum::Collections::Repository] the repository to query from.
+    attr_reader :repository
+
+    # @return [Cuprum::Collections::Resource] the base resource for the
+    #   association.
+    attr_reader :resource
+
+    private
+
+    def collection
+      repository.find_or_create(
+        name:           tools.string_tools.pluralize(association.name),
+        qualified_name: association.qualified_name
+      )
+    end
+
+    def extract_keys(association, hsh)
+      return hsh[:key]  if hsh.key?(:key)
+      return hsh[:keys] if hsh.key?(:keys)
+
+      values = hsh.fetch(:entity) { hsh[:entities] }
+
+      if values.is_a?(Array)
+        association.map_entities_to_keys(*values)
+      else
+        association.map_entities_to_keys(values).first
+      end
+    end
+
+    def handle_ambiguous_keys(hsh)
+      return if hsh.keys.size == 1
+
+      raise ArgumentError,
+        "ambiguous keywords #{hsh.each_key.map(&:inspect).join(', ')} " \
+        '- must provide exactly one parameter'
+    end
+
+    def handle_extra_keys(hsh)
+      return if hsh.keys.all? { |key| PERMITTED_KEYWORDS.include?(key) }
+
+      extra_keys = hsh.keys - PERMITTED_KEYWORDS.to_a
+
+      raise ArgumentError,
+        "invalid keywords #{extra_keys.map(&:inspect).join(', ')}"
+    end
+
+    def handle_missing_keys(hsh)
+      return unless hsh.empty?
+
+      raise ArgumentError, 'missing keyword :entity, :entities, :key, or :keys'
+    end
+
+    def perform_query(association:, expected_keys:, **)
+      query        = association.build_keys_query(*expected_keys)
+      find_command = collection.find_matching
+
+      find_command.call(&query)
+    end
+
+    def process(**params) # rubocop:disable Metrics/MethodLength
+      association           = @association.with_inverse(resource)
+      expected_keys, plural = resolve_keys(association, **params)
+      plural              ||= association.plural?
+
+      return plural ? [] : nil if expected_keys.empty?
+
+      values = step do
+        perform_query(
+          association:   association,
+          expected_keys: expected_keys,
+          plural:        plural
+        )
+      end
+
+      plural ? values.to_a : values.first
+    end
+
+    def resolve_keys(association, **params)
+      handle_missing_keys(params)
+      handle_extra_keys(params)
+      handle_ambiguous_keys(params)
+
+      keys   = extract_keys(association, params)
+      plural = keys.is_a?(Array)
+      keys   = [keys] unless plural
+      keys   = keys.compact.uniq
+
+      [keys, plural]
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/cuprum/collections/commands/associations/require_many.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands/associations'
+require 'cuprum/collections/commands/associations/require_many'
+require 'cuprum/collections/errors/not_found'
+
+module Cuprum::Collections::Commands::Associations
+  # Command for querying required entities by association.
+  class RequireMany < Cuprum::Collections::Commands::Associations::FindMany
+    private
+
+    def find_missing_keys(entities:, expected_keys:)
+      expected_keys - map_entity_keys(entities: entities)
+    end
+
+    def map_entity_keys(entities:)
+      entities.map { |entity| entity[association.query_key_name] }
+    end
+
+    def missing_keys_error(missing_keys:, plural:)
+      attribute_value =
+        !plural && missing_keys.is_a?(Array) ? missing_keys.first : missing_keys
+
+      Cuprum::Collections::Errors::NotFound.new(
+        attribute_name:  association.query_key_name,
+        attribute_value: attribute_value,
+        collection_name: association.name,
+        primary_key:     association.primary_key_query?
+      )
+    end
+
+    def perform_query(association:, expected_keys:, plural:, **)
+      entities     = step { super }
+      missing_keys = find_missing_keys(
+        entities:      entities,
+        expected_keys: expected_keys
+      )
+
+      return success(entities) if missing_keys.empty?
+
+      missing_keys = missing_keys.first unless plural
+      error        =
+        missing_keys_error(missing_keys: missing_keys, plural: plural)
+
+      failure(error)
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands'
+
+module Cuprum::Collections::Commands
+  # Namespace for commands that operate on entity associations.
+  module Associations
+    autoload :FindMany,
+      'cuprum/collections/commands/associations/find_many'
+    autoload :RequireMany,
+      'cuprum/collections/commands/associations/require_many'
+  end
+end

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

@@ -92,7 +92,7 @@ module Cuprum::Collections::Commands
     private
 
     def error_params_for(attributes: nil, &block)
-      { collection_name: collection.collection_name }.merge(
+      { collection_name: collection.name }.merge(
         if block_given?
           { query: collection.query.where(&block) }
         else

data/lib/cuprum/collections/commands.rb

@@ -5,6 +5,7 @@ require 'cuprum/collections'
 module Cuprum::Collections
   # Namespace for abstract commands and collection-independent commands.
   module Commands
+    autoload :Associations,    'cuprum/collections/commands/associations'
     autoload :Create,          'cuprum/collections/commands/create'
     autoload :FindOneMatching, 'cuprum/collections/commands/find_one_matching'
     autoload :Update,          'cuprum/collections/commands/update'

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

@@ -14,7 +14,7 @@ module Cuprum::Collections::Errors
     ].freeze
     private_constant :PERMITTED_KEYWORDS
 
-    # @overload initialize(attribute_name:, attribute_value:, collection_name:, primary_key: false) # rubocop:disable Layout/LineLength
+    # @overload initialize(attribute_name:, attribute_value:, collection_name:, primary_key: false)
     #   @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.