cuprum-collections 0.1.0 → 0.3.0.rc.0

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

@@ -17,39 +17,41 @@ module Cuprum::Collections::Commands
       (scope || build_query).where { { key => one_of(primary_keys) } }
     end
 
-    def handle_missing_items(allow_partial:, items:, primary_keys:)
-      found, missing = match_items(items: items, primary_keys: primary_keys)
+    def build_results(items:, primary_keys:)
+      primary_keys.map do |primary_key_value|
+        next success(items[primary_key_value]) if items.key?(primary_key_value)
 
-      return found if missing.empty?
+        failure(not_found_error(primary_key_value))
+      end
+    end
+
+    def build_result_list(results, allow_partial:, envelope:)
+      unless envelope
+        return Cuprum::ResultList.new(*results, allow_partial: allow_partial)
+      end
 
-      return found if allow_partial && !found.empty?
+      value = envelope ? wrap_items(results.map(&:value)) : nil
 
-      error = Cuprum::Collections::Errors::NotFound.new(
-        collection_name:    collection_name,
-        primary_key_name:   primary_key_name,
-        primary_key_values: missing
+      Cuprum::ResultList.new(
+        *results,
+        allow_partial: allow_partial,
+        value:         value
       )
-      Cuprum::Result.new(error: error)
     end
 
     def items_with_primary_keys(items:)
       # :nocov:
-      items.map { |item| [item.send(primary_key_name), item] }.to_h
+      items.to_h { |item| [item.send(primary_key_name), item] }
       # :nocov:
     end
 
-    def match_items(items:, primary_keys:)
-      items   = items_with_primary_keys(items: items)
-      found   = []
-      missing = []
-
-      primary_keys.each do |key|
-        item = items[key]
-
-        item.nil? ? (missing << key) : (found << item)
-      end
-
-      [found, missing]
+    def not_found_error(primary_key_value)
+      Cuprum::Collections::Errors::NotFound.new(
+        attribute_name:  primary_key_name,
+        attribute_value: primary_key_value,
+        collection_name: collection_name,
+        primary_key:     true
+      )
     end
 
     def process(
@@ -58,16 +60,15 @@ module Cuprum::Collections::Commands
       envelope:      false,
       scope:         nil
     )
-      query = apply_query(primary_keys: primary_keys, scope: scope)
-      items = step do
-        handle_missing_items(
-          allow_partial: allow_partial,
-          items:         query.to_a,
-          primary_keys:  primary_keys
-        )
-      end
-
-      envelope ? wrap_items(items) : items
+      query   = apply_query(primary_keys: primary_keys, scope: scope)
+      items   = items_with_primary_keys(items: query.to_a)
+      results = build_results(items: items, primary_keys: primary_keys)
+
+      build_result_list(
+        results,
+        allow_partial: allow_partial,
+        envelope:      envelope
+      )
     end
 
     def wrap_items(items)

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

@@ -21,9 +21,10 @@ module Cuprum::Collections::Commands
       return if item
 
       error = Cuprum::Collections::Errors::NotFound.new(
-        collection_name:    collection_name,
-        primary_key_name:   primary_key_name,
-        primary_key_values: [primary_key]
+        attribute_name:  primary_key_name,
+        attribute_value: primary_key,
+        collection_name: collection_name,
+        primary_key:     true
       )
       Cuprum::Result.new(error: error)
     end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands'
+
+module Cuprum::Collections::Commands
+  # Command for building, validating and inserting an entity into a collection.
+  #
+  # @example Creating An Entity
+  #   command =
+  #     Cuprum::Collections::Commands::Create.new(collection:)
+  #     .new(collection: books_collection)
+  #
+  #   # With Invalid Attributes
+  #   attributes = { 'title' => '' }
+  #   result     = command.call(attributes: attributes)
+  #   result.success?
+  #   #=> false
+  #   result.error
+  #   #=> an instance of Cuprum::Collections::Errors::FailedValidation
+  #   books_collection.query.count
+  #   #=> 0
+  #
+  #   # With Valid Attributes
+  #   attributes = { 'title' => 'Gideon the Ninth' }
+  #   result     = command.call(attributes: attributes)
+  #   result.success?
+  #   #=> true
+  #   result.value
+  #   #=> a Book with title 'Gideon the Ninth'
+  #   books_collection.query.count
+  #   #=> 1
+  class Create < Cuprum::Command
+    # @param collection [Object] The collection used to store the entity.
+    # @param contract [Stannum::Constraint] The constraint used to validate the
+    #   entity. If not given, defaults to the default contract for the
+    #   collection.
+    def initialize(collection:, contract: nil)
+      super()
+
+      @collection = collection
+      @contract   = contract
+    end
+
+    # @return [Object] the collection used to store the entity.
+    attr_reader :collection
+
+    # @return [Stannum::Constraint] the constraint used to validate the entity.
+    attr_reader :contract
+
+    private
+
+    def process(attributes:)
+      entity = step { collection.build_one.call(attributes: attributes) }
+
+      step { collection.validate_one.call(contract: contract, entity: entity) }
+
+      collection.insert_one.call(entity: entity)
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands'
+require 'cuprum/collections/errors/not_found'
+require 'cuprum/collections/errors/not_unique'
+
+module Cuprum::Collections::Commands
+  # Command for finding a unique entity by a query or set of attributes.
+  #
+  # @example Finding An Entity By Attributes
+  #   command =
+  #     Cuprum::Collections::Commands::FindOneMatching
+  #     .new(collection: books_collection)
+  #
+  #   # With an attributes Hash that matches one entity.
+  #   result = command.call(attributes: { 'title' => 'Gideon the Ninth' })
+  #   result.success?
+  #   #=> true
+  #   result.value
+  #   #=> a Book with title 'Gideon the Ninth'
+  #
+  #   # With an attributes Hash that matches multiple entities.
+  #   result = command.call(attributes: { 'author' => 'Tamsyn Muir' })
+  #   result.success?
+  #   #=> false
+  #   result.error
+  #   #=> an instance of Cuprum::Collections::NotUnique
+  #
+  #   # With an attributes Hash that does not match any entities.
+  #   result = command.call(
+  #     attributes: {
+  #       'author' => 'Becky Chambers',
+  #       'series' => 'The Locked Tomb'
+  #     }
+  #   )
+  #   result.success?
+  #   #=> false
+  #   result.error
+  #   #=> an instance of Cuprum::Collections::NotFound
+  #
+  # @example Finding An Entity By Query
+  #   command =
+  #     Cuprum::Collections::Commands::FindOneMatching
+  #     .new(collection: collection)
+  #
+  #   # With a query that matches one entity.
+  #   result = command.call do
+  #     {
+  #       'series'       => 'The Lord of the Rings',
+  #       'published_at' => greater_than('1955-01-01')
+  #     }
+  #   end
+  #   result.success?
+  #   #=> true
+  #   result.value
+  #   #=> a Book matching the query
+  #
+  #   # With a query that matches multiple entities.
+  #   result = command.call do
+  #     {
+  #       'series'       => 'The Lord of the Rings',
+  #       'published_at' => less_than('1955-01-01')
+  #     }
+  #   end
+  #   result.success?
+  #   #=> false
+  #   result.error
+  #   #=> an instance of Cuprum::Collections::NotUnique
+  #
+  #   # With an attributes Hash that does not match any entities.
+  #   result = command.call do
+  #     {
+  #       'series'       => 'The Lord of the Rings',
+  #       'published_at' => less_than('1954-01-01')
+  #     }
+  #   end
+  #   result.success?
+  #   #=> false
+  #   result.error
+  #   #=> an instance of Cuprum::Collections::NotFound
+  class FindOneMatching < Cuprum::Command
+    # @param collection [#find_matching] The collection to query.
+    def initialize(collection:)
+      super()
+
+      @collection = collection
+    end
+
+    # @return [#find_matching] the collection to query.
+    attr_reader :collection
+
+    private
+
+    def error_params_for(attributes: nil, &block)
+      { collection_name: collection.collection_name }.merge(
+        if block_given?
+          { query: collection.query.where(&block) }
+        else
+          { attributes: attributes }
+        end
+      )
+    end
+
+    def not_found_error(attributes: nil, &block)
+      Cuprum::Collections::Errors::NotFound.new(
+        **error_params_for(attributes: attributes, &block)
+      )
+    end
+
+    def not_unique_error(attributes: nil, &block)
+      Cuprum::Collections::Errors::NotUnique.new(
+        **error_params_for(attributes: attributes, &block)
+      )
+    end
+
+    def process(attributes: nil, &block)
+      query    = block || -> { attributes }
+      entities = step { collection.find_matching.call(limit: 2, &query) }
+
+      require_one_entity(attributes: attributes, entities: entities, &block)
+    end
+
+    def require_one_entity(attributes:, entities:, &block)
+      case entities.count
+      when 0
+        failure(not_found_error(attributes: attributes, &block))
+      when 1
+        entities.first
+      when 2
+        failure(not_unique_error(attributes: attributes, &block))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands'
+
+module Cuprum::Collections::Commands
+  # Command for assigning, validating and updating an entity in a collection.
+  #
+  # @example Updating An Entity
+  #   command =
+  #     Cuprum::Collections::Commands::Create.new(collection:)
+  #     .new(collection: books_collection)
+  #   entity  =
+  #     books_collection
+  #     .find_matching { { 'title' => 'Gideon the Ninth' } }
+  #     .value
+  #     .first
+  #
+  #   # With Invalid Attributes
+  #   attributes = { 'author' => '' }
+  #   result     = command.call(attributes: attributes)
+  #   result.success?
+  #   #=> false
+  #   result.error
+  #   #=> an instance of Cuprum::Collections::Errors::FailedValidation
+  #   books_collection
+  #     .find_matching { { 'title' => 'Gideon the Ninth' } }
+  #     .value
+  #     .first['author']
+  #   #=> 'Tamsyn Muir'
+  #
+  #   # With Valid Attributes
+  #   attributes = { 'series' => 'The Locked Tomb' }
+  #   result     = command.call(attributes: attributes)
+  #   result.success?
+  #   #=> true
+  #   result.value
+  #   #=> an instance of Book with title 'Gideon the Ninth' and series
+  #       'The Locked Tomb'
+  #   books_collection
+  #     .find_matching { { 'title' => 'Gideon the Ninth' } }
+  #     .value
+  #     .first['series']
+  #   #=> 'The Locked Tomb'
+  class Update < Cuprum::Command
+    # @param collection [Object] The collection used to store the entity.
+    # @param contract [Stannum::Constraint] The constraint used to validate the
+    #   entity. If not given, defaults to the default contract for the
+    #   collection.
+    def initialize(collection:, contract: nil)
+      super()
+
+      @collection = collection
+      @contract   = contract
+    end
+
+    # @return [Object] the collection used to store the entity.
+    attr_reader :collection
+
+    # @return [Stannum::Constraint] the constraint used to validate the entity.
+    attr_reader :contract
+
+    private
+
+    def process(attributes:, entity:)
+      entity = step do
+        collection.assign_one.call(attributes: attributes, entity: entity)
+      end
+
+      step { collection.validate_one.call(entity: entity, contract: contract) }
+
+      step { collection.update_one.call(entity: entity) }
+    end
+  end
+end

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

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require 'cuprum/collections/commands'
+require 'cuprum/collections/commands/create'
+require 'cuprum/collections/commands/find_one_matching'
+require 'cuprum/collections/commands/update'
+
+module Cuprum::Collections::Commands
+  # Command for creating or updating an entity from an attributes Hash.
+  #
+  # @example Creating Or Updating An Entity By Primary Key
+  #   command    =
+  #     Cuprum::Collections::Commands::Upsert
+  #     .new(collection: books_collection)
+  #
+  #   # Creating A New Entity
+  #   books_collection.query.count
+  #   #=> 0
+  #   attributes = {
+  #     'id'     => 0
+  #     'title'  => 'Gideon the Ninth',
+  #     'author' => 'Tamsyn Muir'
+  #   }
+  #   result = command.call(attributes: attributes)
+  #   result.value
+  #   #=> a Book with id 0, title 'Gideon the Ninth', and author 'Tamsyn Muir'
+  #   books_collection.query.count
+  #   #=> 1
+  #
+  #   # Updating An Existing Entity
+  #   attributes = {
+  #     'id'     => 0
+  #     'series' => 'The Locked Tomb'
+  #   }
+  #   result = command.call(attributes: attributes)
+  #   result.value
+  #   #=> a Book with id 0, title 'Gideon the Ninth', author 'Tamsyn Muir', and
+  #       series 'The Locked Tomb'
+  #   books_collection.query.count
+  #   #=> 1
+  #
+  # @example Creating Or Updating An Entity By Attributes
+  #   command    =
+  #     Cuprum::Collections::Commands::Upsert
+  #     .new(attribute_names: %w[title], collection: books_collection)
+  #
+  #   # Creating A New Entity
+  #   books_collection.query.count
+  #   #=> 0
+  #   attributes = {
+  #     'id'     => 0
+  #     'title'  => 'Gideon the Ninth',
+  #     'author' => 'Tamsyn Muir'
+  #   }
+  #   result = command.call(attributes: attributes)
+  #   result.value
+  #   #=> a Book with id 0, title 'Gideon the Ninth', and author 'Tamsyn Muir'
+  #   books_collection.query.count
+  #   #=> 1
+  #
+  #   # Updating An Existing Entity
+  #   attributes = {
+  #     'title'  => 'Gideon the Ninth',
+  #     'series' => 'The Locked Tomb'
+  #   }
+  #   result = command.call(attributes: attributes)
+  #   result.value
+  #   #=> a Book with id 0, title 'Gideon the Ninth', author 'Tamsyn Muir', and
+  #       series 'The Locked Tomb'
+  #   books_collection.query.count
+  #   #=> 1
+  class Upsert < Cuprum::Command
+    # @param attribute_names [String, Symbol, Array<String, Symbol>] The names
+    #   of the attributes used to find the unique entity.
+    # @param collection [Object] The collection used to store the entity.
+    # @param contract [Stannum::Constraint] The constraint used to validate the
+    #   entity. If not given, defaults to the default contract for the
+    #   collection.
+    def initialize(collection:, attribute_names: 'id', contract: nil)
+      super()
+
+      @attribute_names = normalize_attribute_names(attribute_names)
+      @collection      = collection
+      @contract        = contract
+    end
+
+    # @return [Array<String>] the names of the attributes used to find the
+    #   unique entity.
+    attr_reader :attribute_names
+
+    # @return [Object] the collection used to store the entity.
+    attr_reader :collection
+
+    # @return [Stannum::Constraint] the constraint used to validate the entity.
+    attr_reader :contract
+
+    private
+
+    def create_entity(attributes:)
+      Cuprum::Collections::Commands::Create
+        .new(collection: collection, contract: contract)
+        .call(attributes: attributes)
+    end
+
+    def filter_attributes(attributes:)
+      tools
+        .hash_tools
+        .convert_keys_to_strings(attributes)
+        .select { |key, _| attribute_names.include?(key) }
+    end
+
+    def find_entity(attributes:)
+      filtered = filter_attributes(attributes: attributes)
+      result   =
+        Cuprum::Collections::Commands::FindOneMatching
+          .new(collection: collection)
+          .call(attributes: filtered)
+
+      return if result.error.is_a?(Cuprum::Collections::Errors::NotFound)
+
+      result
+    end
+
+    def normalize_attribute_names(attribute_names)
+      names = Array(attribute_names)
+
+      raise ArgumentError, "attribute names can't be blank" if names.empty?
+
+      names = names.map do |name|
+        unless name.is_a?(String) || name.is_a?(Symbol)
+          raise ArgumentError, "invalid attribute name #{name.inspect}"
+        end
+
+        name.to_s
+      end
+
+      Set.new(names)
+    end
+
+    def process(attributes:)
+      entity = step { find_entity(attributes: attributes) }
+
+      if entity
+        update_entity(attributes: attributes, entity: entity)
+      else
+        create_entity(attributes: attributes)
+      end
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def update_entity(attributes:, entity:)
+      Cuprum::Collections::Commands::Update
+        .new(collection: collection, contract: contract)
+        .call(attributes: attributes, entity: entity)
+    end
+  end
+end

data/lib/cuprum/collections/commands.rb

@@ -3,6 +3,11 @@
 require 'cuprum/collections'
 
 module Cuprum::Collections
-  # Namespace for abstract commands implementing collection functionality.
-  module Commands; end
+  # Namespace for abstract commands and collection-independent commands.
+  module Commands
+    autoload :Create,          'cuprum/collections/commands/create'
+    autoload :FindOneMatching, 'cuprum/collections/commands/find_one_matching'
+    autoload :Update,          'cuprum/collections/commands/update'
+    autoload :Upsert,          'cuprum/collections/commands/upsert'
+  end
 end