cuprum-collections 0.2.0 → 0.3.0

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

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

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors'
+
+module Cuprum::Collections::Errors
+  # Abstract base class for failed query errors.
+  class AbstractFindError < Cuprum::Error # rubocop:disable Metrics/ClassLength
+    PERMITTED_KEYWORDS = %i[
+      attribute_name
+      attribute_value
+      attributes
+      primary_key
+      query
+    ].freeze
+    private_constant :PERMITTED_KEYWORDS
+
+    # @overload initialize(attribute_name:, attribute_value:, collection_name:, primary_key: false) # rubocop:disable Layout/LineLength
+    #   @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.
+    #   @param primary_key [true, false] Indicates that the queried attribute is
+    #     the primary key for the collection.
+    #
+    # @overload initialize(attributes:, collection_name:)
+    #   @param attributes [Hash<String=>Object>] The queried attributes.
+    #   @param collection_name [String] The name of the collection.
+    #
+    # @overload initialize(query:, collection_name:)
+    #   @param collection_name [String] The name of the collection.
+    #   @param query [Cuprum::Collections::Query] The performed query.
+    def initialize(collection_name:, **options) # rubocop:disable Metrics/MethodLength
+      @collection_name = collection_name
+      @primary_key     = false
+
+      resolve_options(**options)
+
+      super(
+        attribute_name:  attribute_name,
+        attribute_value: attribute_value,
+        attributes:      attributes,
+        collection_name: collection_name,
+        message:         generate_message,
+        query:           query&.criteria
+      )
+    end
+
+    # @return [String] the name of the queried attribute, if any.
+    attr_reader :attribute_name
+
+    # @return [Object] the value of the queried attribute, if any.
+    attr_reader :attribute_value
+
+    # @return [Hash<String=>Object>] The queried attributes.
+    attr_reader :attributes
+
+    # @return [String] the name of the collection.
+    attr_reader :collection_name
+
+    # @return [Cuprum::Collections::Query] the performed query, if any.
+    attr_reader :query
+
+    # @return [Array<Array>] the details of the query, in query criteria format.
+    def details
+      if attribute_name
+        [[attribute_name, :equal, attribute_value]]
+      elsif attributes
+        attributes
+          .map { |attr_name, attr_value| [attr_name, :equal, attr_value] }
+      elsif query
+        query.criteria
+      end
+    end
+
+    # @return [true, false] indicates that the queried attribute is the primary
+    #   key for the collection.
+    def primary_key?
+      @primary_key
+    end
+
+    private
+
+    def as_json_data
+      {
+        'collection_name' => collection_name,
+        'details'         => details
+      }.merge(find_data)
+    end
+
+    def entity_name
+      titleize(tools.str.singularize(collection_name))
+    end
+
+    def find_data # rubocop:disable Metrics/MethodLength
+      if attribute_name
+        {
+          'attribute_name'  => attribute_name,
+          'attribute_value' => attribute_value,
+          'primary_key'     => primary_key?
+        }
+      elsif attributes
+        hsh = tools.hash_tools.convert_keys_to_strings(attributes)
+
+        { 'attributes' => hsh }
+      else
+        {}
+      end
+    end
+
+    def generate_message
+      core_message = "#{entity_name} #{message_fragment}"
+
+      if attribute_name
+        "#{core_message} with #{attribute_name.inspect} " \
+          "#{attribute_value.inspect}" \
+          "#{primary_key? ? ' (primary key)' : ''}"
+      elsif attributes
+        "#{core_message} with attributes #{attributes.inspect}"
+      elsif query
+        "#{core_message} matching the query"
+      end
+    end
+
+    def message_fragment
+      'query failed'
+    end
+
+    def resolve_attribute_options(**options)
+      options          = options.dup
+      @attribute_name  = options.delete(:attribute_name)
+      @attribute_value = options.delete(:attribute_value)
+      @primary_key     = options.delete(:primary_key) || false
+
+      validate_keywords(extra_keywords: options.keys)
+    end
+
+    def resolve_attributes_options(**options)
+      options     = options.dup
+      @attributes = options.delete(:attributes)
+
+      validate_keywords(extra_keywords: options.keys)
+    end
+
+    def resolve_query_options(**options)
+      options = options.dup
+      @query  = options.delete(:query)
+
+      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)
+        resolve_attribute_options(**options)
+      elsif options[:attributes]
+        resolve_attributes_options(**options)
+      elsif options[:query]
+        resolve_query_options(**options)
+      else
+        raise ArgumentError,
+          'missing keywords :attribute_name, :attribute_value or :attributes ' \
+          'or :query'
+      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
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validate_keywords(extra_keywords:) # rubocop:disable Metrics/MethodLength
+      return if extra_keywords.empty?
+
+      ambiguous_keywords = extra_keywords & PERMITTED_KEYWORDS
+
+      if ambiguous_keywords.empty?
+        raise ArgumentError,
+          "unknown keyword#{extra_keywords.size == 1 ? '' : 's'} " \
+          "#{extra_keywords.map(&:inspect).join(', ')}"
+      else
+        raise ArgumentError,
+          "ambiguous keyword#{extra_keywords.size == 1 ? '' : 's'} " \
+          "#{ambiguous_keywords.map(&:inspect).join(', ')}"
+      end
+    end
+  end
+end

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

@@ -1,86 +1,18 @@
 # frozen_string_literal: true
 
-require 'cuprum/error'
-
 require 'cuprum/collections/errors'
+require 'cuprum/collections/errors/abstract_find_error'
 
 module Cuprum::Collections::Errors
   # Returned when an insert command is called with an existing record.
-  class AlreadyExists < Cuprum::Error
+  class AlreadyExists < Cuprum::Collections::Errors::AbstractFindError
     # Short string used to identify the type of error.
     TYPE = 'cuprum.collections.errors.already_exists'
 
-    # @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(
-        collection_name:    collection_name,
-        message:            default_message,
-        primary_key_name:   primary_key_name,
-        primary_key_values: primary_key_values
-      )
-    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} already exist#{singular? ? 's' : ''} 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
+    def message_fragment
+      'already exists'
     end
   end
 end