rails_use_case 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e353dd38951526d2e38dd2007380d710c8c6bdec5634a0daeefc9fe4ce4ab469
+  data.tar.gz: c4624ac8f94c97634f84e03f89361947b0eea1da221e5654a718c5f015807285
+SHA512:
+  metadata.gz: 2637b2676bc1cce54bbda93b1ee5a3a62bed6bc3adde5ed5fca63730fcaa5ae6bc0161786bc236383a24b649caebb0f1c61211a745ec81030fbaee41375bb3e3
+  data.tar.gz: 55b19f9294a4a3993beb36e305e8a158f91b5a35ad16a4468a42c6822f60537802a05238ee2b82cd18acff27e59b5b3a1fdff6cd38a223132a330d4ecab4fbc7

data/README.md

@@ -0,0 +1,20 @@
+# Rails Use Case gem
+
+Opinionated gem for UseCases and Services in rails.
+
+
+## Setup
+
+```ruby
+gem 'rails_use_case'
+```
+
+
+## Usage
+
+TODO
+
+
+## License
+
+MIT

data/lib/rails/callable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Rails
+  # Simple module to add a static call method to a class.
+  module Callable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def call(*args)
+        new.call(*args)
+      end
+
+      alias_method :perform, :call
+    end
+
+
+    # @abstract
+    def call(*_args)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/rails/service.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'logger'
+
+module Rails
+  # Abstract base class for all 3rd party services
+  #
+  # Provides:
+  #   - Configuration (automatically loaded from `config/services/[service_name].yml`, available as `config`)
+  #   - Logging (to separate log file `log/services/[service_name].log`, call via `logger.info(msg)`)
+  #   - Call style invocation (like `PDFGenerationService.(some, params)`)
+  #
+  # @example
+  #   class Services::PDFGenerationService < Service
+  #     def initialize
+  #       super('pdf_generation')
+  #     end
+  #
+  #     def call(action, *args)
+  #        ... here happens the magic! ...
+  #     end
+  #   end
+  #
+  #   PDFGenerationService.(some, params)
+  #
+  # @abstract
+  class Service
+    include Rails::Callable
+
+    attr_reader :logger, :service_name, :config
+
+    # Constructor. Call this from the subclass with the service name, like `super 'pdf_generator'`.
+    # After that you can access the config and logger.
+    #
+    # @param [String] service_name Name of the service, like 'pdf_generator'.
+    # @raise [NotImplementedError] When this class is tried to be instantiated without subclass.
+    #
+    # @raise [RuntimeError] When no service_name is given
+    def initialize(service_name = nil)
+      raise NotImplementedError if self.class == Service
+      raise 'Please provide a service name!' if service_name.nil?
+
+      @service_name = service_name
+
+      setup_logger
+      setup_configuration
+    end
+
+
+    # Create the log file and sets @logger
+    private def setup_logger
+      log_path = Rails.root.join('log', 'services')
+      FileUtils.mkdir_p(log_path) unless Dir.exist?(log_path)
+      @logger = Logger.new(Rails.root.join('log', 'services', "#{@service_name}.log").to_s)
+    end
+
+
+    # Loads the configuration for that service and saves it to @config
+    # @raise [RuntimeError] When the config file doesn't exist
+    private def setup_configuration
+      shared_config_path = Rails.root.join('config', 'services', 'shared.yml')
+      config_path = Rails.root.join('config', 'services', "#{@service_name}.yml")
+      raise "Couldn't find the shared config file '#{shared_config_path}'." unless File.exist?(shared_config_path)
+
+      shared_config = load_config_file(shared_config_path)
+
+      if File.exist?(config_path)
+        service_config = load_config_file(config_path) || {}
+        @config = shared_config.merge(service_config)
+      else
+        @config = shared_config
+      end
+    end
+
+
+    private def load_config_file(path)
+      erb = File.read(path)
+      yaml = ERB.new(erb).result.strip
+
+      return {} if yaml.blank?
+
+      YAML.safe_load(yaml) || {}
+    end
+
+
+    # Convenience method to get a secret. It looks for the key `services.<service_name>.<key>`
+    private def secret(key)
+      key = key.to_sym
+      base = Rails.application.secrets.services[@service_name.to_sym]
+
+      raise "No secrets entry found for 'services.#{@service_name}'" unless base
+      raise "No secrets entry found for 'services.#{@service_name}.#{key}'" unless base[key]
+
+      base[key]
+    end
+
+
+    # Abstract method for instance call. Implement this in the subclass!
+    # @raise [NotImplementedError] When this is not overwritten in the subclass
+    def call(options); end
+
+
+    # Allows call syntax on class level: SomeService.(some, args)
+    def self.call(*args)
+      new.(*args)
+    end
+
+    # Allows to use rails view helpers
+    def helpers
+      ApplicationController.new.helpers
+    end
+  end
+end

data/lib/rails/use_case.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'active_model/validations'
+require 'rails/use_case/outcome'
+
+module Rails
+  # A UseCase is a class that contains high level business logic.
+  # It's used to keep controllers and models slim.
+  #
+  # The difference to a Service is that a Service contains low level
+  # non-domain code like communication with a API, generating an
+  # export, etc., while a UseCase contains high level domain logic
+  # like placing a item in the cart, submitting an order, etc.
+  #
+  # The logic of a UseCase is defined via steps. The next step is only
+  # executed when the previous ones returned a truthy value.
+  #
+  # The UseCase should assign the main record to @record. Calling save!
+  # without argument will try to save that record or raises an exception.
+  #
+  # A UseCase should raise the UseCase::Error exception for any
+  # problems.
+  #
+  # UseCase also includes ActiveModel::Validations for simple yet
+  # powerful validations. The validations are run automatically as first step.
+  #
+  # A UseCase can be called via .call(params) or .perform(params) and
+  # always returns a instance of UseCase::Outcome. params should be a hash.
+  class Rails::UseCase
+    include Callable
+    include ActiveModel::Validations
+
+    class Error < StandardError; end
+
+    class << self
+      attr_reader :steps
+    end
+
+
+    # Will be called by Callable.call.
+    # @param params [Hash] The arguments for the UseCase as Hash
+    #                      so we can auto assign instance variables.
+    def call(params)
+      prepare params
+      process
+
+      successful_outcome
+    rescue UseCase::Error => e
+      failure_outcome e
+    end
+
+
+    # DSL to define a process step of the UseCase.
+    # You can use if/unless with a lambda in the options
+    # to conditionally skip the step.
+    # @param name [Symbol]
+    # @param options [Hash]
+    def self.step(name, options = {})
+      @steps ||= []
+      @steps << { name: name.to_sym, options: options }
+    end
+
+
+    # Will run the steps of the use case.
+    def process
+      self.class.steps.each do |step|
+        next if skip_step?(step)
+        next if send(step[:name])
+
+        raise UseCase::Error, "Step #{step[:name]} returned false"
+      end
+    end
+
+
+    # Checks whether to skip a step.
+    # @param step [Hash]
+    def skip_step?(step)
+      if step[:options][:if]
+        proc = step[:options][:if]
+        result = instance_exec(&proc)
+        return true unless result
+      end
+
+      return false unless step[:options][:unless]
+
+      proc = step[:options][:unless]
+      result = instance_exec(&proc)
+      return true if result
+    end
+
+
+    # Prepare step. Runs automatically before the UseCase process starts.
+    # Sets all params as instance variables and then runs the validations.
+    # @param params [Hash]
+    def prepare(params)
+      params.each do |key, value|
+        instance_variable_set "@#{key}", value
+      end
+
+      break_when_invalid!
+    end
+
+
+    # @raises [UseCase::Error] When validations failed.
+    def break_when_invalid!
+      return true if valid?
+
+      raise UseCase::Error, errors.full_messages.join(', ')
+    end
+
+
+    # Saves the a ActiveRecord object. When the object can't be saved, the
+    # validation errors are pushed into the UseCase errors array and then
+    # a UseCase::Error is raised.
+    # @param record [ApplicationModel] Record to save.
+    # @raises [UseCase::Error] When record can't be saved.
+    private def save!(record = nil)
+      record ||= @record
+
+      return false unless record
+      return true if record.save
+
+      errors.add(
+        record.model_name.singular,
+        :invalid,
+        message: record.errors.full_messages.join(', ')
+      )
+
+      raise UseCase::Error, "#{record.class.name} is not valid"
+    end
+
+
+    # @return [UseCase::Outcome] Successful outcome.
+    private def successful_outcome
+      Outcome.new(
+        success: true,
+        record: @record,
+        errors: errors
+      )
+    end
+
+
+    # @param error [StandardError]
+    # @return [UseCase::Outcome] Failure outcome with exception set.
+    private def failure_outcome(error)
+      Outcome.new(
+        success: false,
+        record: @record,
+        errors: errors,
+        exception: error
+      )
+    end
+  end
+end

data/lib/rails/use_case/outcome.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Rails
+  class UseCase
+    # Outcome of a UseCase
+    class Outcome
+      attr_reader :success, :errors, :record, :exception
+
+      # Constructor.
+      # @param success [Boolean] Wether the UseCase was successful.
+      # @param errors [Array|nil] ActiveModel::Validations error.
+      # @param record [ApplicationRecord|nil] The main record of the use case.
+      # @param exception [Rails::UseCase::Error|nil] The error which was raised.
+      def initialize(success:, errors: nil, record: nil, exception: nil)
+        @success = success
+        @errors = errors
+        @record = record
+        @exception = exception
+      end
+
+
+      # @return [Boolean] Whether the UseCase was successful.
+      def success?
+        @success
+      end
+
+
+      # @return [Boolean] Whether the UseCase failed.
+      def failed?
+        !@success
+      end
+    end
+  end
+end

data/lib/rails_use_case.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rails; end
+
+require 'rails/callable'
+require 'rails/use_case'
+require 'rails/service'

metadata

@@ -0,0 +1,189 @@
+--- !ruby/object:Gem::Specification
+name: rails_use_case
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Benjamin Klein
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-02-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: rspec-mocks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.78'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.78'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.37'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.37'
+- !ruby/object:Gem::Dependency
+  name: rubygems-tasks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+description: Rails UseCase and Service classes
+email:
+- bk@itws.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/rails/callable.rb
+- lib/rails/service.rb
+- lib/rails/use_case.rb
+- lib/rails/use_case/outcome.rb
+- lib/rails_use_case.rb
+homepage: https://github.com/phortx/rails-use-case
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Rails UseCase and Service classes
+test_files: []