cuprum-rails 0.1.0

data/lib/cuprum/rails/commands/assign_one.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types/hash_with_indifferent_keys'
+
+require 'cuprum/collections/errors/extra_attributes'
+
+require 'cuprum/rails/command'
+require 'cuprum/rails/commands'
+
+module Cuprum::Rails::Commands
+  # Command for assigning attributes to an ActiveRecord model.
+  class AssignOne < Cuprum::Rails::Command
+    # @!method call(attributes:, entity:)
+    #   Assigns the given attributes to the record.
+    #
+    #   Any attributes on the record that are not part of the given attributes
+    #   hash are unchanged.
+    #
+    #   @param attributes [Hash] The attributes and values to update.
+    #   @param entity [ActiveRecord::Base] The record to update.
+    #
+    #   @return [ActiveRecord::Base] a copy of the record, merged with the given
+    #       attributes.
+    #
+    #   @example Assigning attributes
+    #     entity = Book.new(
+    #       'title'    => 'The Hobbit',
+    #       'author'   => 'J.R.R. Tolkien',
+    #       'series'   => nil,
+    #       'category' => 'Science Fiction and Fantasy'
+    #     )
+    #     attributes = { title: 'The Silmarillion' }
+    #     command    = Assign.new(record_class: Book)
+    #     result     = command.call(attributes: attributes, entity: entity)
+    #     result.value.attributes
+    #     #=> {
+    #       'id'       => nil,
+    #       'title'    => 'The Silmarillion',
+    #       'author'   => 'J.R.R. Tolkien',
+    #       'series'   => nil,
+    #       'category' => 'Science Fiction and Fantasy'
+    #     }
+    validate_parameters :call do
+      keyword :attributes,
+        Stannum::Constraints::Types::HashWithIndifferentKeys.new
+      keyword :entity, Object
+    end
+
+    private
+
+    def process(attributes:, entity:)
+      step { validate_entity(entity) }
+
+      entity.assign_attributes(attributes)
+
+      entity
+    rescue ActiveModel::UnknownAttributeError => exception
+      error = Cuprum::Collections::Errors::ExtraAttributes.new(
+        entity_class:     record_class,
+        extra_attributes: [exception.attribute],
+        valid_attributes: record_class.attribute_names
+      )
+      failure(error)
+    end
+  end
+end

data/lib/cuprum/rails/commands/build_one.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types/hash_with_indifferent_keys'
+
+require 'cuprum/collections/errors/extra_attributes'
+
+require 'cuprum/rails/command'
+require 'cuprum/rails/commands'
+
+module Cuprum::Rails::Commands
+  # Command for generating an ActiveRecord model from an attributes hash.
+  class BuildOne < Cuprum::Rails::Command
+    # @!method call(attributes:)
+    #   Builds a new record with the given attributes.
+    #
+    #   @param attributes [Hash] The attributes and values to assign.
+    #
+    #   @return [ActiveRecord::Base] the newly built record.
+    #
+    #   @example Building a record
+    #     attributes = {
+    #       'title'    => 'The Hobbit',
+    #       'author'   => 'J.R.R. Tolkien',
+    #       'series'   => nil,
+    #       'category' => 'Science Fiction and Fantasy'
+    #     }
+    #     command    = Build.new(record_class: Book)
+    #     result     = command.call(attributes: attributes)
+    #     result.value.attributes
+    #     #=> {
+    #       'id'       => nil,
+    #       'title'    => 'The Silmarillion',
+    #       'author'   => 'J.R.R. Tolkien',
+    #       'series'   => nil,
+    #       'category' => 'Science Fiction and Fantasy'
+    #     }
+    validate_parameters :call do
+      keyword :attributes,
+        Stannum::Constraints::Types::HashWithIndifferentKeys.new
+    end
+
+    private
+
+    def process(attributes:)
+      record_class.new(attributes)
+    rescue ActiveModel::UnknownAttributeError => exception
+      error = Cuprum::Collections::Errors::ExtraAttributes.new(
+        entity_class:     record_class,
+        extra_attributes: [exception.attribute],
+        valid_attributes: record_class.attribute_names
+      )
+      failure(error)
+    end
+  end
+end

data/lib/cuprum/rails/commands/destroy_one.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors/not_found'
+
+require 'cuprum/rails/command'
+require 'cuprum/rails/commands'
+
+module Cuprum::Rails::Commands
+  # Command for destroying an ActiveRecord record by primary key.
+  class DestroyOne < Cuprum::Rails::Command
+    # @!method call(primary_key:)
+    #   Finds and destroys the record with the given primary key.
+    #
+    #   The command will find the record with the given primary key and remove
+    #   it from the collection. If the record is not found, the command will
+    #   fail and return a NotFound error.
+    #
+    #   @param primary_key [Object] The primary key of the requested record.
+    #
+    #   @return [Cuprum::Result<Hash{String, Object}>] a result with the
+    #     destroyed record.
+    validate_parameters :call do
+      keyword :primary_key, Object
+    end
+
+    private
+
+    def process(primary_key:)
+      step { validate_primary_key(primary_key) }
+
+      entity = record_class.find(primary_key)
+
+      entity.destroy
+    rescue ActiveRecord::RecordNotFound
+      error = Cuprum::Collections::Errors::NotFound.new(
+        collection_name:    collection_name,
+        primary_key_name:   primary_key_name,
+        primary_key_values: [primary_key]
+      )
+      Cuprum::Result.new(error: error)
+    end
+  end
+end

data/lib/cuprum/rails/commands/find_many.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/boolean'
+
+require 'cuprum/collections/commands/abstract_find_many'
+
+require 'cuprum/rails/command'
+require 'cuprum/rails/commands'
+
+module Cuprum::Rails::Commands
+  # Command for finding multiple ActiveRecord records by primary key.
+  class FindMany < Cuprum::Rails::Command
+    include Cuprum::Collections::Commands::AbstractFindMany
+
+    # @!method call(primary_keys:, allow_partial: false, envelope: false, scope: nil) # rubocop:disable Layout/LineLength
+    #   Queries the collection for the records with the given primary keys.
+    #
+    #   The command will find and return the entities with the given primary
+    #   keys. If any of the records 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
+    #   records are found.
+    #
+    #   When the :envelope option is true, the command wraps the records in a
+    #   Hash, using the name of the collection as the key.
+    #
+    #   @param allow_partial [Boolean] If true, passes if any of the records are
+    #     found.
+    #   @param envelope [Boolean] If true, wraps the result value in a Hash.
+    #   @param primary_keys [Array] The primary keys of the requested records.
+    #   @param scope [Cuprum::Collections::Basic::Query, nil] Optional scope for
+    #     the query. Records must match the scope as well as the primary keys.
+    #
+    #   @return [Cuprum::Result<Array<ActiveRecord>>] a result with the
+    #     requested records.
+    validate_parameters :call do
+      keyword :allow_partial, Stannum::Constraints::Boolean.new, default: true
+      keyword :envelope,      Stannum::Constraints::Boolean.new, default: true
+      keyword :primary_keys,  Array
+      keyword :scope,         Cuprum::Rails::Query, optional: true
+    end
+
+    private
+
+    def build_query
+      Cuprum::Rails::Query.new(record_class)
+    end
+
+    def process(
+      primary_keys:,
+      allow_partial: false,
+      envelope:      false,
+      scope:         nil
+    )
+      step { validate_primary_keys(primary_keys) }
+
+      super
+    end
+  end
+end

data/lib/cuprum/rails/commands/find_matching.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/commands/abstract_find_matching'
+require 'cuprum/collections/constraints/ordering'
+
+require 'cuprum/rails/command'
+require 'cuprum/rails/commands'
+require 'cuprum/rails/query'
+
+module Cuprum::Rails::Commands
+  # Command for querying filtered, ordered data from a Rails collection.
+  class FindMatching < Cuprum::Rails::Command
+    include Cuprum::Collections::Commands::AbstractFindMatching
+
+    # @!method call(envelope: false, limit: nil, offset: nil, order: nil, scope: nil, where: nil, &block) # rubocop:disable Layout/LineLength
+    #   Queries the collection for records 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. Records 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 records in the collection.
+    #     command = FindMatching.new(collection_name: 'books', data: books)
+    #     command.call
+    #     #=> an enumerable iterating all records in the collection
+    #
+    #   @example Querying all records matching some critera:
+    #     command.call { { author: 'Nnedi Okorafor' } }
+    #     #=> an enumerable iterating all records in the collection whose author
+    #         is 'Nnedi Okorafor'
+    #
+    #   @example Ordering query results
+    #     command.call(order: :title) { { author: 'Nnedi Okorafor' } }
+    #     #=> an enumerable iterating all records 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 records 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 records 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 records in the
+    #     #   collection whose category is 'Science Fiction and Fantasy', sorted
+    #     #   by :author in ascending order.
+    #
+    #   @example Wrapping the result in an envelope
+    #     command =
+    #       Filter.new(collection_name: 'books', data: books)
+    #     command.call(envelope: true)
+    #     #=> {
+    #       'books' => [] # an array containing the matching records
+    #     }
+    #
+    #   @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 records.
+    #
+    #     @return [Cuprum::Result<Enumerator>] the matching records 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<ActiveRecord::Base>}>] a
+    #       hash with the collection name as key and the matching records as
+    #       value.
+    validate_parameters :call do
+      keyword :envelope,
+        Stannum::Constraints::Boolean.new,
+        default: true
+      keyword :limit, Integer, optional: true
+      keyword :offset, Integer, optional: true
+      keyword :order,
+        Cuprum::Collections::Constraints::Ordering.new,
+        optional: true
+      keyword :scope,
+        Cuprum::Rails::Query,
+        optional: true
+      keyword :where, Object, optional: true
+    end
+
+    private
+
+    def build_query
+      Cuprum::Rails::Query.new(record_class)
+    end
+  end
+end

data/lib/cuprum/rails/commands/find_one.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/boolean'
+
+require 'cuprum/collections/commands/abstract_find_one'
+
+require 'cuprum/rails/command'
+require 'cuprum/rails/commands'
+
+module Cuprum::Rails::Commands
+  # Command for finding one ActiveRecord record by primary key.
+  class FindOne < Cuprum::Rails::Command
+    include Cuprum::Collections::Commands::AbstractFindOne
+
+    # @!method call(primary_key:, envelope: false, scope: nil)
+    #   Queries the collection for the record 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 record 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 record.
+    #   @param scope [Cuprum::Collections::Basic::Query, nil] Optional scope for
+    #     the query. The record must match the scope as well as the primary key.
+    #
+    #   @return [Cuprum::Result<Hash{String, Object}>] a result with the
+    #     requested record.
+    validate_parameters :call do
+      keyword :envelope,    Stannum::Constraints::Boolean.new, default: true
+      keyword :primary_key, Object
+      keyword :scope,       Cuprum::Rails::Query, optional: true
+    end
+
+    private
+
+    def build_query
+      Cuprum::Rails::Query.new(record_class)
+    end
+
+    def process(primary_key:, envelope: false, scope: nil)
+      step { validate_primary_key(primary_key) }
+
+      super
+    end
+  end
+end

data/lib/cuprum/rails/commands/insert_one.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors/already_exists'
+
+require 'cuprum/rails/command'
+require 'cuprum/rails/commands'
+
+module Cuprum::Rails::Commands
+  # Command for inserting an ActiveRecord record into the collection.
+  class InsertOne < Cuprum::Rails::Command
+    # @!method call(entity:)
+    #   Inserts the record into the collection.
+    #
+    #   If the collection already includes a record with the same primary key,
+    #   #call will fail and the collection will not be updated.
+    #
+    #   @param entity [ActiveRecord::Base] The record to persist.
+    #
+    #   @return [Cuprum::Result<ActiveRecord::Base>] the persisted record.
+    validate_parameters :call do
+      keyword :entity, Object
+    end
+
+    private
+
+    def process(entity:)
+      step { validate_entity(entity) }
+
+      entity.save
+
+      entity
+    rescue ActiveRecord::RecordNotUnique
+      error = Cuprum::Collections::Errors::AlreadyExists.new(
+        collection_name:    collection_name,
+        primary_key_name:   primary_key_name,
+        primary_key_values: entity[primary_key_name]
+      )
+      failure(error)
+    end
+  end
+end

data/lib/cuprum/rails/commands/update_one.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors/not_found'
+
+require 'cuprum/rails/command'
+require 'cuprum/rails/commands'
+
+module Cuprum::Rails::Commands
+  # Command for updating an ActiveRecord record in the collection.
+  class UpdateOne < Cuprum::Rails::Command
+    # @!method call(entity:)
+    #   Updates the record in the collection.
+    #
+    #   If the collection does not already have a record with the same primary
+    #   key, #call will fail and the collection will not be updated.
+    #
+    #   @param entity [ActiveRecord::Base] The collection record to persist.
+    #
+    #   @return [Cuprum::Result<ActiveRecord::Base>] the persisted record.
+    validate_parameters :call do
+      keyword :entity, Object
+    end
+
+    private
+
+    def handle_missing_record(primary_key:)
+      query = record_class.where(primary_key_name => primary_key)
+
+      return if query.exists?
+
+      error = Cuprum::Collections::Errors::NotFound.new(
+        collection_name:    collection_name,
+        primary_key_name:   primary_key_name,
+        primary_key_values: primary_key
+      )
+      failure(error)
+    end
+
+    def process(entity:)
+      step { validate_entity(entity) }
+
+      step { handle_missing_record(primary_key: entity[primary_key_name]) }
+
+      entity.save
+
+      entity
+    end
+  end
+end

data/lib/cuprum/rails/commands/validate_one.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors/failed_validation'
+
+require 'cuprum/rails/command'
+require 'cuprum/rails/commands'
+require 'cuprum/rails/map_errors'
+
+module Cuprum::Rails::Commands
+  # Command for validating an ActiveRecord record.
+  class ValidateOne < Cuprum::Rails::Command
+    # @!method call(entity:, contract: nil)
+    #   Validates the record against the given or default contract.
+    #
+    #   If the record matches the contract, #call will return a passing result
+    #   with the record as the result value. If the record 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 record. If not given, the record will be validated using
+    #     the collection's default contract.
+    #   @param entity [ActiveRecord::Base] The collection record to validate.
+    #
+    #   @return [Cuprum::Result<ActiveRecord::Base>] the validated record.
+    validate_parameters :call do
+      keyword :contract,
+        Stannum::Constraints::Base,
+        optional: true
+      keyword :entity, Object
+    end
+
+    private
+
+    def map_errors(native_errors:)
+      Cuprum::Rails::MapErrors.instance.call(native_errors: native_errors)
+    end
+
+    def match_default(entity:)
+      return true if entity.valid?
+
+      errors = map_errors(native_errors: entity.errors)
+
+      [false, errors]
+    end
+
+    def process(entity:, contract: nil)
+      step { validate_entity(entity) }
+
+      step { validate_record(contract: contract, entity: entity) }
+
+      entity
+    end
+
+    def validate_record(contract:, entity:)
+      valid, errors =
+        contract ? contract.match(entity) : match_default(entity: entity)
+
+      return if valid
+
+      error = Cuprum::Collections::Errors::FailedValidation.new(
+        entity_class: entity.class,
+        errors:       errors
+      )
+      failure(error)
+    end
+  end
+end

data/lib/cuprum/rails/commands.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Namespace for commands implementing Rails collection functionality.
+  module Commands
+    autoload :AssignOne,    'cuprum/rails/commands/assign_one'
+    autoload :BuildOne,     'cuprum/rails/commands/build_one'
+    autoload :DestroyOne,   'cuprum/rails/commands/destroy_one'
+    autoload :FindMany,     'cuprum/rails/commands/find_many'
+    autoload :FindMatching, 'cuprum/rails/commands/find_matching'
+    autoload :FindOne,      'cuprum/rails/commands/find_one'
+    autoload :InsertOne,    'cuprum/rails/commands/insert_one'
+    autoload :UpdateOne,    'cuprum/rails/commands/update_one'
+    autoload :ValidateOne,  'cuprum/rails/commands/validate_one'
+  end
+end

data/lib/cuprum/rails/controller.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+require 'cuprum/rails/controller_action'
+require 'cuprum/rails/controllers/class_methods/configuration'
+require 'cuprum/rails/controllers/class_methods/validations'
+
+module Cuprum::Rails
+  # Provides a DSL for defining actions and responses.
+  #
+  # @example Defining A Controller
+  #   class ExampleController < ApplicationController
+  #     include Cuprum::Rails::Controller
+  #
+  #     responder :html, CustomHtmlResponder
+  #
+  #     action :process, ExampleProcessAction
+  #   end
+  #
+  # @example Defining A RESTful Controller
+  #   class BooksController
+  #     include Cuprum::Rails::Controller
+  #
+  #     responder :html, Cuprum::Rails::Responders::Html::PluralResource
+  #
+  #     action :index,     Cuprum::Rails::Actions::Index
+  #     action :show,      Cuprum::Rails::Actions::Show, member: true
+  #     action :published, Books::Published
+  #     action :publish,   Books::Publish,               member: true
+  #   end
+  module Controller
+    # Exception when the controller does not define a resource.
+    class UndefinedResourceError < StandardError; end
+
+    # Exception when the controller does not have a responder for a format.
+    class UnknownFormatError < StandardError; end
+
+    class << self
+      private
+
+      def included(other)
+        super
+
+        other.extend(Cuprum::Rails::Controllers::ClassMethods::Actions)
+        other.extend(Cuprum::Rails::Controllers::ClassMethods::Configuration)
+        other.extend(Cuprum::Rails::Controllers::ClassMethods::Validations)
+      end
+    end
+  end
+end