cuprum-rails 0.1.0

data/lib/cuprum/rails/action.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'cuprum/command'
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Abstract command that implement a controller action.
+  class Action < Cuprum::Command
+    # @param resource [Cuprum::Rails::Resource] The controller resource.
+    def initialize(resource:)
+      super()
+
+      @resource = resource
+    end
+
+    # @!method call(request:)
+    #   Performs the controller action.
+    #
+    #   Subclasses should implement a #process method with the :request keyword,
+    #   which accepts an ActionDispatch::Request instance.
+    #
+    #   @param request [ActionDispatch::Request] The Rails request.
+    #
+    #   @return [Cuprum::Result] the result of the action.
+
+    # @return [Cuprum::Rails::Resource] the controller resource.
+    attr_reader :resource
+
+    private
+
+    attr_reader :request
+
+    def params
+      @params ||= ActionController::Parameters.new(request.params)
+    end
+
+    def process(request:)
+      @params  = nil
+      @request = request
+
+      nil
+    end
+  end
+end

data/lib/cuprum/rails/actions/create.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors/failed_validation'
+
+require 'cuprum/rails/actions'
+require 'cuprum/rails/actions/resource_action'
+
+module Cuprum::Rails::Actions
+  # Action to build and insert a resource instance.
+  class Create < Cuprum::Rails::Actions::ResourceAction
+    private
+
+    def create_resource
+      entity = nil
+
+      result = steps do
+        attributes = step { resource_params }
+        entity     = step { collection.build_one.call(attributes: attributes) }
+
+        step { collection.validate_one.call(entity: entity) }
+
+        step { collection.insert_one.call(entity: entity) }
+
+        { singular_resource_name => entity }
+      end
+
+      [entity, result]
+    end
+
+    def failed_validation?(result)
+      result.failure? &&
+        result.error.is_a?(Cuprum::Collections::Errors::FailedValidation)
+    end
+
+    def process(request:)
+      super
+
+      entity, result = create_resource
+
+      return result unless failed_validation?(result)
+
+      Cuprum::Result.new(
+        error:  result.error,
+        status: :failure,
+        value:  { singular_resource_name => entity }
+      )
+    end
+  end
+end

data/lib/cuprum/rails/actions/destroy.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/actions'
+require 'cuprum/rails/actions/resource_action'
+
+module Cuprum::Rails::Actions
+  # Action to delete a resource instance by primary key.
+  class Destroy < Cuprum::Rails::Actions::ResourceAction
+    private
+
+    def process(request:)
+      super
+
+      primary_key = step { resource_id }
+      entity      = step do
+        collection.destroy_one.call(primary_key: primary_key)
+      end
+
+      { singular_resource_name => entity }
+    end
+  end
+end

data/lib/cuprum/rails/actions/edit.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/actions'
+require 'cuprum/rails/actions/resource_action'
+
+module Cuprum::Rails::Actions
+  # Action to find a resource instance by primary key.
+  class Edit < Cuprum::Rails::Actions::ResourceAction
+    private
+
+    def process(request:)
+      super
+
+      primary_key = step { resource_id }
+      entity      = step do
+        collection.find_one.call(primary_key: primary_key)
+      end
+
+      { singular_resource_name => entity }
+    end
+  end
+end

data/lib/cuprum/rails/actions/index.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/actions'
+require 'cuprum/rails/actions/resource_action'
+
+module Cuprum::Rails::Actions
+  # Action to find and filter resources.
+  class Index < Cuprum::Rails::Actions::ResourceAction
+    def_delegators :@resource,
+      :default_order
+
+    private
+
+    # @note Overload this method to change how the filtering params are defined,
+    #   or override the #limit, #offset, #order, #where methods directly.
+    def filter_params
+      tools.hash_tools.convert_keys_to_strings(request.params)
+    end
+
+    def limit
+      filter_params['limit']
+    end
+
+    def offset
+      filter_params['offset']
+    end
+
+    def order
+      filter_params.fetch('order', default_order.presence)
+    end
+
+    def process(request:)
+      super
+
+      filters = where
+      block   = where.present? ? -> { filters } : nil
+
+      collection.find_matching.call(
+        envelope: true,
+        limit:    limit,
+        offset:   offset,
+        order:    order,
+        &block
+      )
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def where
+      filter_params['where']
+    end
+  end
+end

data/lib/cuprum/rails/actions/new.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/actions'
+require 'cuprum/rails/actions/resource_action'
+
+module Cuprum::Rails::Actions
+  # Action to build an empty resource instance.
+  class New < Cuprum::Rails::Actions::ResourceAction
+    private
+
+    def process(request:)
+      super
+
+      instance = step { collection.build_one.call(attributes: {}) }
+
+      { singular_resource_name => instance }
+    end
+  end
+end

data/lib/cuprum/rails/actions/resource_action.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'cuprum/rails/actions'
+require 'cuprum/rails/errors/missing_parameters'
+require 'cuprum/rails/errors/missing_primary_key'
+require 'cuprum/rails/errors/undefined_permitted_attributes'
+
+module Cuprum::Rails::Actions
+  # Abstract base class for resourceful actions.
+  class ResourceAction < Cuprum::Rails::Action
+    extend Forwardable
+
+    # @param resource [Cuprum::Rails::Resource] The controller resource.
+    def initialize(resource:)
+      if resource.collection.nil?
+        raise ArgumentError, 'resource must have a collection'
+      end
+
+      super
+    end
+
+    def_delegators :@resource,
+      :collection,
+      :resource_name,
+      :singular_resource_name
+
+    # @return [Object] the primary key for the resource.
+    def resource_id
+      return success(params[:id]) if params[:id].present?
+
+      failure(missing_primary_key_error)
+    end
+
+    # @return [Hash] the permitted params for the resource.
+    def resource_params
+      return failure(permitted_attributes_error) unless permitted_attributes?
+
+      success(raw_resource_params)
+    rescue ActionController::ParameterMissing
+      failure(missing_parameters_error)
+    end
+
+    private
+
+    def missing_parameters_error
+      Cuprum::Rails::Errors::MissingParameters
+        .new(resource_name: singular_resource_name)
+    end
+
+    def missing_primary_key_error
+      Cuprum::Rails::Errors::MissingPrimaryKey.new(
+        primary_key:   resource.primary_key,
+        resource_name: singular_resource_name
+      )
+    end
+
+    def permitted_attributes?
+      !resource.permitted_attributes.nil?
+    end
+
+    def permitted_attributes_error
+      Cuprum::Rails::Errors::UndefinedPermittedAttributes
+        .new(resource_name: singular_resource_name)
+    end
+
+    def raw_resource_params
+      params
+        .require(singular_resource_name)
+        .permit(*resource.permitted_attributes)
+        .to_hash
+    end
+  end
+end

data/lib/cuprum/rails/actions/show.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/actions'
+require 'cuprum/rails/actions/resource_action'
+
+module Cuprum::Rails::Actions
+  # Action to find a resource instance by primary key.
+  class Show < Cuprum::Rails::Actions::ResourceAction
+    private
+
+    def process(request:)
+      super
+
+      primary_key = step { resource_id }
+      entity      = step do
+        collection.find_one.call(primary_key: primary_key)
+      end
+
+      { singular_resource_name => entity }
+    end
+  end
+end

data/lib/cuprum/rails/actions/update.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/errors/failed_validation'
+
+require 'cuprum/rails/actions'
+require 'cuprum/rails/actions/resource_action'
+
+module Cuprum::Rails::Actions
+  # Action to assign and update a resource instance by primary key.
+  class Update < Cuprum::Rails::Actions::ResourceAction
+    private
+
+    def assign_resource
+      primary_key = step { resource_id }
+      attributes  = step { resource_params }
+      entity      = step do
+        collection.find_one.call(primary_key: primary_key)
+      end
+      step do
+        collection.assign_one.call(attributes: attributes, entity: entity)
+      end
+    end
+
+    def failed_validation?(result)
+      result.failure? &&
+        result.error.is_a?(Cuprum::Collections::Errors::FailedValidation)
+    end
+
+    def process(request:)
+      super
+
+      entity, result = update_resource
+
+      return result unless failed_validation?(result)
+
+      Cuprum::Result.new(
+        error:  result.error,
+        status: :failure,
+        value:  { singular_resource_name => entity }
+      )
+    end
+
+    def update_resource
+      entity = nil
+
+      result = steps do
+        entity = assign_resource
+
+        step { collection.validate_one.call(entity: entity) }
+
+        step { collection.update_one.call(entity: entity) }
+
+        { singular_resource_name => entity }
+      end
+
+      [entity, result]
+    end
+  end
+end

data/lib/cuprum/rails/actions.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Namespace for defined resourceful actions.
+  module Actions
+    autoload :Create,  'cuprum/rails/actions/create'
+    autoload :Destroy, 'cuprum/rails/actions/destroy'
+    autoload :Edit,    'cuprum/rails/actions/edit'
+    autoload :Index,   'cuprum/rails/actions/index'
+    autoload :New,     'cuprum/rails/actions/new'
+    autoload :Show,    'cuprum/rails/actions/show'
+    autoload :Update,  'cuprum/rails/actions/update'
+  end
+end

data/lib/cuprum/rails/collection.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'cuprum/command_factory'
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Wraps an ActiveRecord model as a Cuprum collection.
+  class Collection < Cuprum::CommandFactory
+    # @param collection_name [String, Symbol] The name of the collection.
+    # @param member_name [String] The name of a collection entity.
+    # @param options [Hash<Symbol>] Additional options for the command.
+    # @param record_class [Class] The ActiveRecord class for the collection.
+    def initialize(
+      record_class:,
+      collection_name: nil,
+      member_name:     nil,
+      **options
+    )
+      super()
+
+      @collection_name = resolve_collection_name(collection_name, record_class)
+      @member_name     = resolve_member_name(@collection_name, member_name)
+      @record_class    = record_class
+      @options         = options
+    end
+
+    # @return [String] The name of the collection.
+    attr_reader :collection_name
+
+    # @return [String] the name of a collection entity.
+    attr_reader :member_name
+
+    # @return [Hash<Symbol>] additional options for the command.
+    attr_reader :options
+
+    # @return [Class] the ActiveRecord class for the collection.
+    attr_reader :record_class
+
+    command_class :assign_one do
+      Cuprum::Rails::Commands::AssignOne
+        .subclass(**command_options)
+    end
+
+    command_class :build_one do
+      Cuprum::Rails::Commands::BuildOne
+        .subclass(**command_options)
+    end
+
+    command_class :destroy_one do
+      Cuprum::Rails::Commands::DestroyOne
+        .subclass(**command_options)
+    end
+
+    command_class :find_many do
+      Cuprum::Rails::Commands::FindMany
+        .subclass(**command_options)
+    end
+
+    command_class :find_matching do
+      Cuprum::Rails::Commands::FindMatching
+        .subclass(**command_options)
+    end
+
+    command_class :find_one do
+      Cuprum::Rails::Commands::FindOne
+        .subclass(**command_options)
+    end
+
+    command_class :insert_one do
+      Cuprum::Rails::Commands::InsertOne
+        .subclass(**command_options)
+    end
+
+    command_class :update_one do
+      Cuprum::Rails::Commands::UpdateOne
+        .subclass(**command_options)
+    end
+
+    command_class :validate_one do
+      Cuprum::Rails::Commands::ValidateOne
+        .subclass(**command_options)
+    end
+
+    # A new Query instance, used for querying against the collection data.
+    #
+    # @return [Cuprum::Rails::Query] the query.
+    def query
+      Cuprum::Rails::Query.new(record_class)
+    end
+
+    private
+
+    def command_options
+      @command_options ||= {
+        collection_name: collection_name,
+        member_name:     member_name,
+        record_class:    record_class,
+        **options
+      }
+    end
+
+    def resolve_collection_name(collection_name, record_class)
+      return collection_name.to_s unless collection_name.nil?
+
+      record_class.name.underscore.pluralize
+    end
+
+    def resolve_member_name(collection_name, member_name)
+      return member_name.to_s unless member_name.nil?
+
+      collection_name.singularize
+    end
+  end
+end

data/lib/cuprum/rails/command.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Abstract base class for Rails collection commands.
+  class Command < Cuprum::Collections::Command
+    # Creates a subclass with the given parameters applied to the constructor.
+    def self.subclass(**default_options)
+      Class.new(self) do
+        define_method(:initialize) do |**options|
+          super(**default_options.merge(options))
+        end
+      end
+    end
+
+    # @param collection_name [String, Symbol] The name of the collection.
+    # @param member_name [String] The name of a collection entity.
+    # @param options [Hash<Symbol>] Additional options for the command.
+    # @param record_class [Class] The ActiveRecord class for the collection.
+    def initialize(
+      record_class:,
+      collection_name: nil,
+      member_name:     nil,
+      **options
+    )
+      super()
+
+      @collection_name = resolve_collection_name(collection_name, record_class)
+      @member_name     = resolve_member_name(@collection_name, member_name)
+      @record_class    = record_class
+      @options         = options
+    end
+
+    # @return [String] The name of the collection.
+    attr_reader :collection_name
+
+    # @return [String] the name of a collection entity.
+    attr_reader :member_name
+
+    # @return [Hash<Symbol>] additional options for the command.
+    attr_reader :options
+
+    # @return [Class] the ActiveRecord class for the collection.
+    attr_reader :record_class
+
+    # @return [Symbol] the name of the primary key attribute.
+    def primary_key_name
+      @primary_key_name ||= record_class.primary_key.intern
+    end
+
+    # @return [Class] the type of the primary key attribute.
+    def primary_key_type
+      @primary_key_type ||=
+        case primary_key_column_type
+        when :integer
+          Integer
+        when :uuid
+          String
+        else
+          # :nocov:
+          raise "unknown primary key column type :#{primary_key_column_type}"
+          # :nocov:
+        end
+    end
+
+    private
+
+    def entity_contract
+      type = record_class
+
+      @entity_contract ||= Stannum::Contracts::ParametersContract.new do
+        keyword :entity, type
+      end
+    end
+
+    def primary_key_contract
+      type = primary_key_type
+
+      @primary_key_contract ||= Stannum::Contracts::ParametersContract.new do
+        keyword :primary_key, type
+      end
+    end
+
+    def primary_key_column_type
+      record_class
+        .columns
+        .find { |column| column.name == record_class.primary_key }
+        .type
+    end
+
+    def primary_keys_contract
+      type = primary_key_type
+
+      @primary_keys_contract ||= Stannum::Contracts::ParametersContract.new do
+        keyword :primary_keys,
+          Stannum::Constraints::Types::ArrayType.new(item_type: type)
+      end
+    end
+
+    def resolve_collection_name(collection_name, record_class)
+      return collection_name.to_s unless collection_name.nil?
+
+      record_class.name.underscore.pluralize
+    end
+
+    def resolve_member_name(collection_name, member_name)
+      return member_name.to_s unless member_name.nil?
+
+      collection_name.singularize
+    end
+
+    def validate_entity(entity)
+      match_parameters_to_contract(
+        contract:    entity_contract,
+        keywords:    { entity: entity },
+        method_name: :call
+      )
+    end
+
+    def validate_primary_key(primary_key)
+      match_parameters_to_contract(
+        contract:    primary_key_contract,
+        keywords:    { primary_key: primary_key },
+        method_name: :call
+      )
+    end
+
+    def validate_primary_keys(primary_keys)
+      match_parameters_to_contract(
+        contract:    primary_keys_contract,
+        keywords:    { primary_keys: primary_keys },
+        method_name: :call
+      )
+    end
+  end
+end