cuprum-collections 0.5.1 → 0.6.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5a70ba7c1dd93657afb1f94f345b6d422e1fee51d7845b249cd2b14e5da387f
-  data.tar.gz: 17121928330b174b661ca5e03a727a8976ddce5bc977f3cab90a490c615dfd0c
+  metadata.gz: 2ac4327e0779a00b865a7f0ddc2e4f2cb6fddc28da8d459cff029b415ba4bd2a
+  data.tar.gz: e371fd9876bc8e4cf26ad5e2abb43588fe763fd37524c7bf32a12a34c83cf968
 SHA512:
-  metadata.gz: b871c8cfa148ff76fb46dc1bc59b07e1f4db4ec71eec23b7194a694fba5fb4db48b3f4c9e96c45de299140b556ff0af337b40b3f41752fa350fb64b0369e789a
-  data.tar.gz: d9ca82d7b9cead80d22ca4b003da62c1f3add4e3e4a8fc957b4c8d6db5796316e4f8267bed744e2762708f52e34565aafad6778bafc6517e8efa59b2933596de
+  metadata.gz: '008fb96865a3264648f439054c7965ca81a386e00bf27bb67a193e981ba4ac044da8713ee09ac15d31b1d1ea47b20e46d3c1b29aa3fe4067f59589598da909b7'
+  data.tar.gz: 98fe25033606d342f72c6fe04c8eb6b351e1e970faeb4420ad969db2d28f25633dbeffa6a641de81a7caca0d2fe0672c77bd185eb209e7aeb3241398c2436260

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.6.0
+
+Removed all deprecated functionality from version 0.5.0 and earlier.
+
+### Collections
+
+Added support for adaptable collections.
+
+- Adapters map raw attributes from a datastore to a Ruby object.
+  - Added `Cuprum::Collections::Adapter`
+  - Added `Cuprum::Collections::Adapters::DataAdapter`
+  - Added `Cuprum::Collections::Adapters::EntityAdapter`
+  - Added `Cuprum::Collections::Adapters::HashAdapter`
+- Adaptable collections use an adapter to transform the data into the desired object.
+  - Added `Cuprum::Collections::Adaptable::Collection`
+  - Added `Cuprum::Collections::Adaptable::Command`
+  - Added `Cuprum::Collections::Adaptable::Commands`
+  - Added `Cuprum::Collections::Adaptable::Query`
+
+### Errors
+
+Removed `#collection_name` from all Find errors. Either pass the `collection:` directly or pass collection parameters (`name:`, `entity_class:`, and/or `qualified_name:`).
+
+### Queries
+
+Added support for `NULL`, `NOT_NULL` operators in queries.
+
+Added support for passing `Proc` values when parsing query criteria.
+
+### Repositories
+
+- Implemented `#find`, which finds the matching collection by name, qualified name, or entity class.
+- Implemented `#remove`, which removes the collection with the specified qualified name.
+- Deprecated `#find_or_create`. Use `#find` to find an existing collection. Use `#create` to add a new collection.
+- Added support for passing a block to `Repository.new { |repository| }`.
+
+### RSpec
+
+Migrated shared contract objects to deferred example groups:
+
+- `Cuprum::Collections::RSpec::Deferred::QueryExamples`
+- `Cuprum::Collections::RSpec::Deferred::RepositoryExamples`
+- `Cuprum::Collections::RSpec::Deferred::ScopeExamples`
+- `Cuprum::Collections::RSpec::Deferred::Scopes::*`
+
+The corresponding contracts are now deprecated.
+
 ## 0.5.1
 
 Added missing `config/locales` directory to the gemspec.

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/adaptable'
+
+module Cuprum::Collections::Adaptable
+  # Mixin for defining adaptable collections.
+  module Collection
+    # @param adapter [Cuprum::Collections::Adapter] the collection adapter.
+    def initialize(adapter:, **parameters)
+      super(default_entity_class: adapter.entity_class, **parameters)
+
+      @adapter = adapter
+    end
+
+    # @return [Cuprum::Collections::Adapter] the collection adapter.
+    attr_reader :adapter
+  end
+end

data/lib/cuprum/collections/adaptable/command.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/adaptable'
+
+module Cuprum::Collections::Adaptable
+  # Mixin for defining commands for adaptable collections.
+  module Command
+    # @return [Cuprum::Collections::Adapter] the adapter defined for the
+    #   collection.
+    def adapter = collection.adapter
+
+    private
+
+    def validate_attributes(attributes, as: 'attributes')
+      adapter.validate_attributes_parameter(attributes, as:)
+    end
+
+    def validate_entity(entity, as: 'entity')
+      adapter.validate_entity_parameter(entity, as:)
+    end
+  end
+end

data/lib/cuprum/collections/adaptable/commands/abstract_assign_one.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'cuprum/parameter_validation'
+
+require 'cuprum/collections/adaptable/commands'
+
+module Cuprum::Collections::Adaptable::Commands
+  # Abstract implementation of the AssignOne command for adaptable collections.
+  module AbstractAssignOne
+    include Cuprum::ParameterValidation
+
+    # @!method call(attributes:, entity:)
+    #   Merges the given attributes into the given entity.
+    #
+    #   @param attributes [Hash] the attributes to merge into the entity.
+    #   @param entity [Object] the entity to update.
+    #
+    #   @return [Object] an instance of the entity class with the updated
+    #     attributes.
+    validate :attributes
+    validate :entity
+
+    private
+
+    def process(attributes:, entity:) = adapter.merge(attributes:, entity:)
+  end
+end

data/lib/cuprum/collections/adaptable/commands/abstract_build_one.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'cuprum/parameter_validation'
+
+require 'cuprum/collections/adaptable/commands'
+
+module Cuprum::Collections::Adaptable::Commands
+  # Abstract implementation of the BuildOne command for adaptable collections.
+  module AbstractBuildOne
+    include Cuprum::ParameterValidation
+
+    # @!method call(attributes:)
+    #   Creates a new entity from the given attributes.
+    #
+    #   @param attributes [Hash] the attributes to build into an entity.
+    #
+    #   @return [Object] an instance of the entity class with the given
+    #     attributes.
+    validate :attributes
+
+    private
+
+    def process(attributes:) = adapter.build(attributes:)
+  end
+end

data/lib/cuprum/collections/adaptable/commands/abstract_validate_one.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'cuprum/parameter_validation'
+
+require 'cuprum/collections/adaptable/commands'
+
+module Cuprum::Collections::Adaptable::Commands
+  # Abstract, adaptable implementation of the ValidateOne command.
+  module AbstractValidateOne
+    include Cuprum::ParameterValidation
+
+    # @!method call(entity:, contract: nil)
+    #   Validates the entity against the given or default contract.
+    #
+    #   If the entity matches the contract, #call will return a passing result
+    #   with the entity as the result value. If the entity does not match the
+    #   contract, #call will return a failing result with a FailedValidation
+    #   error and the validation errors.
+    #
+    #   @param contract [Stannum::Constraints:Base] The contract with which to
+    #     validate the entity. If not given, the entity will be validated using
+    #     the collection's default contract.
+    #   @param entity [Hash] The collection entity to validate.
+    #
+    #   @return [Cuprum::Result<Hash>] the validated entity.
+    validate :contract, Stannum::Constraints::Base, optional: true
+    validate :entity
+
+    private
+
+    def process(entity:, contract: nil)
+      adapter.validate(contract:, entity:)
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/adaptable'
+
+module Cuprum::Collections::Adaptable
+  # Namespace for adaptable command implementations.
+  module Commands
+    autoload :AbstractAssignOne,
+      'cuprum/collections/adaptable/commands/abstract_assign_one'
+    autoload :AbstractBuildOne,
+      'cuprum/collections/adaptable/commands/abstract_build_one'
+    autoload :AbstractValidateOne,
+      'cuprum/collections/adaptable/commands/abstract_validate_one'
+  end
+end

data/lib/cuprum/collections/adaptable/query.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/adaptable'
+require 'cuprum/collections/query'
+
+module Cuprum::Collections::Adaptable
+  # Mixin for adaptable collection Query implementations.
+  module Query
+    # Exception raised when the query cannot convert native data.
+    class AbstractQueryError < StandardError; end
+
+    # Exception raised when converting attributes returns a failing result.
+    class InvalidDataError < StandardError; end
+
+    # @param adapter [Cuprum::Collections::Adapter] the collection adapter.
+    def initialize(*, adapter:, **)
+      super(*, **)
+
+      @adapter = adapter
+    end
+
+    # @return [Cuprum::Collections::Adapter] the collection adapter.
+    attr_reader :adapter
+
+    # Converts a native data representation to the adapter entity format.
+    #
+    # @param native [Object] the native representation of one collection item.
+    #
+    # @return [Object] the collection item in the format specified by the
+    #   adapter.
+    def convert(native)
+      attributes = convert_native_to_attributes(native)
+      result     = adapter.build(attributes:)
+
+      return result.value if result.success?
+
+      # This is an internal data error, not resolvable by the user.
+      raise InvalidDataError,
+        invalid_data_error_message(attributes:, error: result.error, native:)
+    end
+
+    private
+
+    def convert_native_to_attributes(_)
+      raise AbstractQueryError,
+        "#{self.class.name} is an abstract class - define a subclass and " \
+        'implement the #convert_native_to_attributes method'
+    end
+
+    def invalid_data_error_message(attributes:, error:, native:)
+      message = 'Unable to process query data'
+
+      if error
+        message += " - #{error.message}" if error.message
+        message += "\n  error details: #{error.as_json}"
+      end
+
+      message += "\n  raw data: #{native.inspect}"
+      message += "\n  attributes: #{attributes.inspect}"
+
+      message
+    end
+  end
+end

data/lib/cuprum/collections/adaptable.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # Namespace for defining adaptable collections.
+  module Adaptable
+    autoload :Collection, 'cuprum/collections/adaptable/collection'
+    autoload :Command,    'cuprum/collections/adaptable/command'
+    autoload :Commands,   'cuprum/collections/adaptable/commands'
+    autoload :Query,      'cuprum/collections/adaptable/query'
+  end
+end

data/lib/cuprum/collections/adapter.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+require 'cuprum/result_helpers'
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # Utility class for converting between raw attributes and a data format.
+  class Adapter # rubocop:disable Metrics/ClassLength
+    include Cuprum::ResultHelpers
+    include Cuprum::Steps
+
+    # @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.
+    # @option options entity_class [Class] the class of the data objects.
+    def initialize(**options) # rubocop:disable Metrics/MethodLength
+      @attribute_names =
+        options
+          .fetch(:attribute_names, [])
+          .compact
+          .map(&:to_s)
+          .then { |ary| Set.new(ary) }
+      @default_contract       = options[:default_contract]
+      @entity_class           = options[:entity_class]
+      @allow_extra_attributes =
+        options.fetch(:allow_extra_attributes, @attribute_names.empty?)
+
+      validate_entity_class_parameter(@entity_class)
+    end
+
+    # @return [Set<String>] the valid attribute names for a data object.
+    attr_reader :attribute_names
+
+    # @return [Stannum::Constraints:Base] the contract used to validate
+    #   instances of the data object.
+    attr_reader :default_contract
+
+    # @return [Class] the class of the data objects.
+    attr_reader :entity_class
+
+    # @return [true, false] if false, attributes methods return an error for
+    #   attributes not in attributes_names.
+    def allow_extra_attributes?
+      @allow_extra_attributes
+    end
+
+    # Generates a data object from an attributes hash.
+    #
+    # @param attributes [Hash] the attributes used to initialize the object.
+    #
+    # @return [Cuprum::Result<Object>] the result with the generated object or
+    #   the error.
+    def build(attributes:)
+      steps do
+        handle_invalid_parameters(
+          *validate_attributes_parameter(attributes)
+        )
+        handle_extra_attributes(attributes)
+
+        build_entity(attributes:)
+      end
+    end
+
+    # Returns a data object with updated attributes.
+    #
+    # @param attributes [Hash] the attributes used to update the object.
+    # @param entity [Object] the data object to update.
+    #
+    # @return [Cuprum::Result<Object>] the result with the updated object or the
+    #   error.
+    def merge(attributes:, entity:)
+      steps do
+        handle_invalid_parameters(
+          *validate_attributes_parameter(attributes),
+          validate_entity_parameter(entity)
+        )
+        handle_extra_attributes(attributes)
+
+        merge_entity(attributes:, entity:)
+      end
+    end
+
+    # Generates an attributes hash from a data object.
+    #
+    # @param entity [Object] the data object to serialize.
+    #
+    # @return [Cuprum::Result<Object>] the result with the generated attributes
+    #   or the error.
+    def serialize(entity:)
+      steps do
+        handle_invalid_parameters(
+          validate_entity_parameter(entity)
+        )
+
+        serialize_entity(entity:)
+      end
+    end
+
+    # Validates a data object.
+    #
+    # @param entity [Object] the data object to validate.
+    # @param contract [Stannum::Constraint] the contract used to validate the
+    #   data object, if any.
+    #
+    # @return [Cuprum::Result<Object>] a passing result with the data object, or
+    #   the error if the data object is not valid.
+    def validate(entity:, contract: nil)
+      steps do
+        handle_invalid_parameters(
+          validate_entity_parameter(entity)
+        )
+
+        validate_entity(contract:, entity:)
+      end
+    end
+
+    # Asserts that an attributes parameter is a Hash with valid keys.
+    #
+    # @param attributes [Object] the attributes to validate.
+    # @param as [String] the name of the validate object. Defaults to
+    #   "attributes".
+    #
+    # @return [String, nil] the error message if the attributes are not a Hash
+    #   with valid keys; or nil if the attributes are valid.
+    def validate_attributes_parameter(attributes, as: 'attributes')
+      return attributes_not_hash_error(as:) unless attributes.is_a?(Hash)
+
+      attributes
+        .each_key
+        .with_object([]) do |key, messages|
+          messages << validate_attributes_parameter_key(
+            key,
+            as: "#{as}[#{key.inspect}] key"
+          )
+        end
+        .compact
+    end
+
+    # Asserts that an entity parameter is of valid type.
+    #
+    # @param entity [Object] the entity to validate.
+    # @param as [String] the name of the validated object. Defaults to "entity".
+    #
+    # @return [String, nil] the error message if the entity is not of valid
+    #   type; or nil if the entity is valid.
+    def validate_entity_parameter(entity, as: 'entity')
+      return unless entity_class
+
+      return if entity.is_a?(entity_class)
+
+      tools.assertions.error_message_for(
+        'sleeping_king_studios.tools.assertions.instance_of',
+        as:,
+        expected: entity_class
+      )
+    end
+
+    private
+
+    def attributes_not_hash_error(as:)
+      tools.assertions.error_message_for(
+        'sleeping_king_studios.tools.assertions.instance_of',
+        as:,
+        expected: Hash
+      )
+    end
+
+    def build_entity(**)
+      failure(not_implemented_error)
+    end
+
+    def default_contract_for(**)
+      default_contract
+    end
+
+    def empty_attribute_key_error(as:)
+      tools.assertions.error_message_for(
+        'sleeping_king_studios.tools.assertions.presence',
+        as:
+      )
+    end
+
+    def extra_attributes_error(extra_attributes:)
+      Cuprum::Collections::Errors::ExtraAttributes.new(
+        entity_class:,
+        extra_attributes:,
+        valid_attributes: attribute_names.to_a
+      )
+    end
+
+    def failed_validation_error(errors:)
+      Cuprum::Collections::Errors::FailedValidation.new(
+        entity_class:,
+        errors:
+      )
+    end
+
+    def handle_extra_attributes(attributes)
+      step do
+        return if allow_extra_attributes?
+
+        extra_attributes = attributes.each_key.reject do |key|
+          key = key.to_s if key.is_a?(Symbol)
+
+          attribute_names.include?(key)
+        end
+
+        return if extra_attributes.empty?
+
+        failure(extra_attributes_error(extra_attributes:))
+      end
+    end
+
+    def handle_invalid_parameters(*messages)
+      step do
+        failures = messages.compact.reject(&:empty?)
+
+        return if failures.empty?
+
+        failures = failures.map { |failure| failure.split(', ') }.flatten
+
+        failure(invalid_parameters_error(failures:))
+      end
+    end
+
+    def invalid_attribute_key_error(as:)
+      tools.assertions.error_message_for(
+        'sleeping_king_studios.tools.assertions.name',
+        as:
+      )
+    end
+
+    def invalid_parameters_error(failures:)
+      Cuprum::Errors::InvalidParameters
+        .new(command_class: self.class, failures:)
+    end
+
+    def match_contract(contract:, entity:)
+      return contract.match(entity) if contract
+
+      match_native_validation(entity:)
+    end
+
+    def match_native_validation(**)
+      failure(missing_default_contract_error)
+    end
+
+    def merge_entity(**)
+      failure(not_implemented_error)
+    end
+
+    def missing_default_contract_error
+      Cuprum::Collections::Errors::MissingDefaultContract.new(entity_class:)
+    end
+
+    def not_implemented_error
+      Cuprum::Errors::CommandNotImplemented.new(command: self)
+    end
+
+    def serialize_entity(**)
+      failure(not_implemented_error)
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validate_attributes_parameter_key(key, as:)
+      return empty_attribute_key_error(as:) if key.nil?
+
+      unless key.is_a?(String) || key.is_a?(Symbol)
+        return invalid_attribute_key_error(as:)
+      end
+
+      return unless key.empty?
+
+      empty_attribute_key_error(as:)
+    end
+
+    def validate_entity(contract:, entity:)
+      contract ||= default_contract_for(entity:)
+
+      match, errors = step { match_contract(contract:, entity:) }
+
+      return success(entity) if match
+
+      failure(failed_validation_error(errors:))
+    end
+
+    def validate_entity_class_parameter(*, **) = nil
+  end
+end

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

@@ -0,0 +1,82 @@
+# 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 class.
+  class DataAdapter < 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
+    #   members. Must be a subset of the entity class's members.
+    # @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 Data 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
+        data_class?(entity_class) ? entity_class.members : []
+      end
+
+      super(attribute_names:, entity_class:, **options)
+
+      verify_attribute_names_are_members
+    end
+
+    private
+
+    def build_entity(attributes:)
+      attributes = empty_attributes.merge(attributes)
+
+      entity_class.new(**attributes)
+    end
+
+    def data_class?(entity_class)
+      entity_class.is_a?(Class) && entity_class < Data
+    end
+
+    def empty_attributes
+      @empty_attributes ||= member_names.to_h { |key| [key, nil] }
+    end
+
+    def member_names
+      @member_names ||= entity_class.members.map(&:to_s)
+    end
+
+    def merge_entity(attributes:, entity:)
+      attributes = entity.to_h.merge(attributes)
+
+      entity_class.new(**attributes)
+    end
+
+    def serialize_entity(entity:)
+      tools.hash_tools.convert_keys_to_strings(entity.to_h)
+    end
+
+    def validate_entity_class_parameter(entity_class, as: 'entity class')
+      tools.assertions.validate_class(entity_class, as:)
+
+      return if entity_class < Data
+
+      raise ArgumentError, "#{as} is not a subclass of Data"
+    end
+
+    def verify_attribute_names_are_members
+      invalid_names = attribute_names - member_names
+
+      return if invalid_names.empty?
+
+      error_message =
+        "attribute names #{invalid_names.join(', ')} are not members of " \
+        "#{entity_class.name || 'the entity class'}"
+
+      raise ArgumentError, error_message
+    end
+  end
+end