rails_use_case 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e353dd38951526d2e38dd2007380d710c8c6bdec5634a0daeefc9fe4ce4ab469
-  data.tar.gz: c4624ac8f94c97634f84e03f89361947b0eea1da221e5654a718c5f015807285
+  metadata.gz: eccdc9b039ad948018925576475a8857da769828aef5f58f2426901b6cca77c3
+  data.tar.gz: 5ed1d23accbd83dda0428d7fc3f959366e49e5a2cb29e95ec1e641f1063d8942
 SHA512:
-  metadata.gz: 2637b2676bc1cce54bbda93b1ee5a3a62bed6bc3adde5ed5fca63730fcaa5ae6bc0161786bc236383a24b649caebb0f1c61211a745ec81030fbaee41375bb3e3
-  data.tar.gz: 55b19f9294a4a3993beb36e305e8a158f91b5a35ad16a4468a42c6822f60537802a05238ee2b82cd18acff27e59b5b3a1fdff6cd38a223132a330d4ecab4fbc7
+  metadata.gz: 931eb6a75e1d92604c5f1e33140a3ddd3c20f6cbad225814f4d6e75e801e95f09d3a738d778643221f29b82f2c188c2c007e4449313297bacfee4eacd41bacd2
+  data.tar.gz: aa4cc82f951293c672211129cdf27968bca51a218305982c55929b13ba5cafd9b60edcce5b89824b6ba4108ad0c8ec8dc3dbed6d06cc841ea04d0a4ed4b2aa1d

data/README.md

@@ -1,6 +1,12 @@
 # Rails Use Case gem
 
-Opinionated gem for UseCases and Services in rails.
+Opinionated gem for UseCases and Services in rails to keep models and controllers slim.
+
+The purpose of a UseCase is to contain reusable high level business logic which would normally be
+located in the controller. Examples are: Place an item in the cart, create a new user or delete a comment.
+
+The purpose of a Service is to contain low level non-domain code like communication with a API,
+generating an export, upload via FTP or generating a PDF.
 
 
 ## Setup
@@ -10,9 +16,124 @@ gem 'rails_use_case'
 ```
 
 
-## Usage
+## Use Case
+
+The purpose of a UseCase is to contain reusable high level business logic which would normally be
+located in the controller. It defines a process via `step` definitions. A UseCase takes params
+and has a outcome, which is successfully or failed. It doesn't have a configuration file and doesn't
+log anything. Examples are: Place an item in the cart, create a new user or delete a comment.
+
+Steps are executed in the defined order. Only when a step succeeds (returns true) the next step will
+be executed. Steps can be skipped via `if` and `unless`.
+
+The UseCase should assign the main record to `@record`. Calling save! without argument will try to
+save that record or raises an exception. Also the `@record` will automatically passed into the outcome.
+
+The params should always passed as hash and are automatically assigned to instance variables.
+
+### Example UseCase
+
+```ruby
+class CreateBlogPost < Rails::UseCase
+  attr_accessor :title, :content, :author, :skip_notifications
+
+  validates :title, presence: true
+  validates :content, presence: true
+  validates :author, presence: true
+
+  step :build_post
+  step :save!
+  step :notify_subscribers, unless: -> { skip_notifications }
+
+
+  private def build_post
+    @record = BlogPost.new(
+      title: title,
+      content: content,
+      created_by: author,
+      type: :default
+    )
+  end
+
+  private def notify_subscribers
+    # ... send some mails ...
+  end
+end
+```
+
+Example usage of that UseCase:
+
+```ruby
+result = CreateBlogPost.perform(
+  title: 'Super Awesome Stuff!',
+  content: 'Lorem Ipsum Dolor Sit Amet',
+  created_by: current_user,
+  skip_notifications: false
+)
+
+puts result.inspect
+# => {
+#   success: true,
+#   record: BlogPost(...)
+#   errors: [],
+#   error: nil
+# }
+```
+
+
+## Service
+
+The purpose of a Service is to contain low level non-domain code like communication with a API,
+generating an export, upload via FTP or generating a PDF. It takes params, has it's own configuration
+and writes a log file.
+
+It comes with call style invocation: `PDFGenerationService.(some, params)`
+
+### Example Service
+
+```ruby
+class PDFGenerationService < Rails::Service
+  attr_reader :pdf_template, :values
+
+  # Constructor.
+  def initialize
+    super 'pdf_generation'
+    prepare
+    validate_libreoffice
+  end
+
+
+  # Entry point.
+  #
+  # @param [PdfTemplate] pdf_template PdfTemplate record.
+  # @param [Hash<String, String>] values Mapping of variables to their values.
+  #
+  # @returns [String] Path to PDF file.
+  def call(pdf_template, values = {})
+    @pdf_template = pdf_template
+    @values = prepare_variable_values(values)
+
+    write_odt_file
+    replace_variables
+    generate_pdf
+
+    @pdf_file_path
+  ensure
+    delete_tempfile
+  end
+end
+```
+
+### Configuration
+
+The service tries to automatically load a configuration from `config/services/[service_name].yml`
+which is available via the `config` method.
+
+
+### Logging
 
-TODO
+The service los to a separate log file `log/services/[service_name].log`. You can write additional
+logs via `logger.info(msg)`.
 
 
 ## License

data/lib/rails/use_case.rb

@@ -1,35 +1,16 @@
 # frozen_string_literal: true
 
-require 'active_model/validations'
+require 'active_model'
 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
+  # UseCase. See README.
+  class UseCase
     include Callable
     include ActiveModel::Validations
 
+    attr_reader :record
+
     class Error < StandardError; end
 
     class << self
@@ -115,13 +96,18 @@ module Rails
     # @param record [ApplicationModel] Record to save.
     # @raises [UseCase::Error] When record can't be saved.
     private def save!(record = nil)
-      record ||= @record
+      if record.nil?
+        record = @record
+        name = :record
+      else
+        name = record.model_name.singular
+      end
 
       return false unless record
       return true if record.save
 
       errors.add(
-        record.model_name.singular,
+        name,
         :invalid,
         message: record.errors.full_messages.join(', ')
       )

data/lib/rails_use_case.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Namespace
 module Rails; end
 
 require 'rails/callable'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_use_case
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Benjamin Klein