runger_actions 0.19.0

data/README.md

@@ -0,0 +1,662 @@
+[![codecov](https://codecov.io/gh/davidrunger/runger_actions/branch/master/graph/badge.svg)](https://codecov.io/gh/davidrunger/runger_actions)
+![GitHub tag (latest SemVer pre-release)](https://img.shields.io/github/v/tag/davidrunger/runger_actions?include_prereleases)
+
+# RungerActions
+
+Organize and validate the business logic of your Rails application with this combined form object /
+command object.
+
+# Table of Contents
+
+<!--ts-->
+* [RungerActions](#rungeractions)
+* [Table of Contents](#table-of-contents)
+* [Installation](#installation)
+* [Usage in general](#usage-in-general)
+   * [Setup](#setup)
+   * [Generate your actions](#generate-your-actions)
+   * [Define your actions](#define-your-actions)
+   * [Invoke your actions](#invoke-your-actions)
+      * [Available methods](#available-methods)
+* [Usage in specific](#usage-in-specific)
+   * [An #execute instance method is required!](#an-execute-instance-method-is-required)
+   * [Action class methods](#action-class-methods)
+      * [::requires](#requires)
+         * [Specifying the expected shape of a Hash input](#specifying-the-expected-shape-of-a-hash-input)
+         * [Specifying ActiveModel-style validations](#specifying-activemodel-style-validations)
+         * [Specifying arbitrary input "shapes" by providing a callable object](#specifying-arbitrary-input-shapes-by-providing-a-callable-object)
+         * [Specifying validations for ActiveRecord inputs](#specifying-validations-for-activerecord-inputs)
+      * [::returns](#returns)
+         * [The result object](#the-result-object)
+         * [All promised values must be returned](#all-promised-values-must-be-returned)
+         * [Validating the "shape" of returned values](#validating-the-shape-of-returned-values)
+      * [::fails_with](#fails_with)
+         * [Setting an error_message](#setting-an-error_message)
+* [Alternatives](#alternatives)
+* [Status / Context](#status--context)
+* [Development](#development)
+* [License](#license)
+
+<!-- Created by https://github.com/ekalinin/github-markdown-toc -->
+<!-- Added by: david, at: Sat May 20 12:56:10 CDT 2023 -->
+
+<!--te-->
+
+# Installation
+
+Add the gem to your application's `Gemfile`.
+
+```rb
+gem 'runger_actions'
+```
+
+And then execute:
+
+```
+$ bundle install
+```
+
+# Usage in general
+
+## Setup
+
+Create a new subdirectory within the `app/` directory in your Rails app: `app/actions/`.
+
+Create an `app/actions/application_action.rb` file with this content:
+```rb
+# app/actions/application_action.rb
+
+class ApplicationAction < RungerActions::Base
+end
+```
+
+## Generate your actions
+
+This gem provides a Rails generator. For example, running:
+
+```
+bin/rails g runger_actions:action Users::Create
+```
+
+will create an empty action in `app/actions/users/create.rb`.
+
+## Define your actions
+
+Then, you can start defining actions. Here's an example:
+```rb
+# app/actions/send_text_message.rb
+
+class SendTextMessage < ApplicationAction
+  requires :message_body, String, length: { minimum: 3 } # don't send any super short messages
+  requires :user, User do
+    validates :phone, presence: true, format: { with: /[[:digit:]]{11}/ }
+  end
+
+  returns :cost, Float, numericality: { greater_than_or_equal_to: 0 }
+  returns :nexmo_id, String, presence: true
+
+  fails_with :nexmo_request_failed
+
+  def execute
+    nexmo_response = NexmoClient.send_text!(number: user.phone, message: message_body)
+    if nexmo_response.success?
+      nexmo_response_data = nexmo_response.parsed_response
+      result.cost = nexmo_response_data['cost']
+      result.nexmo_id = nexmo_response_data['message-id']
+    else
+      result.nexmo_request_failed!
+    end
+  end
+end
+```
+
+## Invoke your actions
+
+Once you have defined one or more actions, you can invoke the action(s) anywhere in your code, such
+as in a controller, as illustrated below.
+
+```rb
+# app/controllers/api/text_messages_controller.rb
+
+class Api::TextMessagesController < ApplicationController
+  def create
+    send_message_action =
+      SendTextMessage.new(
+        user: current_user,
+        message_body: "Hello! This message was generated at #{Time.current}.",
+      )
+
+    if !send_message_action.valid?
+      # We'll enter this block if one of the ActiveRecord inputs (`user`, in this case) for the
+      # action doesn't meet the required validations, e.g. if the user's `phone` is blank.
+      render json: { error: send_message_action.errors.full_messages.join(', ') }, status: 400
+      return
+    end
+
+    result = send_message_action.run
+    if result.success?
+      Rails.logger.info("Sent message with Nexmo id #{result.nexmo_id} at a cost of #{result.cost}")
+      head :created
+    elsif result.nexmo_request_failed?
+      render json: { error: 'An error occurred when sending the text message' }, status: 500
+    end
+  end
+end
+```
+
+You aren't limited to invoking actions from a controller action, though; you can invoke an action
+from anywhere in your code.
+
+One good place to invoke an action is from within *another* action. For a complex or multi-step
+process, you might want to break that process down into several "sub actions" that can be invoked
+from the `#execute` method of a coordinating "parent action".
+
+### Available methods
+
+There are a few different methods that can be used to instantiate and/or run an action:
+1. `::run!` class method
+2. `::new!` class method
+3. `::new` class method
+4. `#run!` instance method
+5. `#run` instance method
+
+#### `::run!` class method
+
+This will attempt to instantiate an action (via `::new!`) and then attempt to run the action (via
+`#run!`). If there are any validation errors and/or if any `fails_with` conditions are invoked
+during execution, then an error will be raised.
+
+Example:
+```rb
+SendTextMessage.run!(user: current_user, message_body: 'Hello!')
+```
+
+#### `::new!` class method
+
+This will attempt to instantiate an action. If there are any validation errors, then an error will
+be raised.
+
+Example:
+```rb
+action = SendTextMessage.new!(user: current_user, message_body: 'Hi!')
+```
+
+#### `::new` class method
+
+This will instantiate an action. Even if there are ActiveModel validation errors, an error will
+**not** be raised.
+
+Example:
+```rb
+action = SendTextMessage.new(user: current_user, message_body: 'Hi!')
+```
+
+#### `#run!` instance method
+
+This will attempt to run an action. If any `fails_with` conditions are invoked during execution,
+then an error will be raised.
+
+Example:
+```rb
+action = SendTextMessage.new!(user: current_user, message_body: 'Hi!')
+action.run!
+```
+
+#### `#run` instance method
+
+This will run an action. If any `fails_with` conditions are invoked during execution, then an error
+will **not** be raised. The errors will be registered on the `result` object.
+
+Example:
+```rb
+action = SendTextMessage.new!(user: current_user, message_body: 'Hi!')
+result = action.run
+result.nexmo_request_failed? # check if a `fails_with` condition was invoked
+```
+
+# Usage in specific
+
+## An `#execute` instance method is required!
+
+The only real requirement for an action is that it implements an `#execute` instance method.
+
+```rb
+class DoSomething < ApplicationAction
+  def execute
+    # you MUST write an #execute instance method for your action
+  end
+end
+```
+
+Although all actions must implement an `#execute` instance method, you should generally not invoke
+that method directly in your application code. Instead, call `#run` on an instance of the class:
+
+```rb
+# this will run the DoSomething#execute instance method
+DoSomething.new.run
+```
+
+## Action class methods
+
+When defining an action class, these three class methods are available:
+1. `requires`
+2. `returns`
+3. `fails_with`
+
+Those class methods are all optional, though. We'll detail/illustrate their usage below.
+
+### `::requires`
+
+The `::requires` class method declares the necessary, expected inputs that are needed in order to
+execute an action.
+
+An action can have zero, one, or more `requires` statements.
+
+An action that requires no input values will have no `requires` statements:
+
+```rb
+class PrintCurrentTime < ApplicationAction
+  def execute
+    puts("The current time is #{Time.now}.")
+  end
+end
+
+PrintCurrentTime.new.run
+# => prints "The current time is 2020-06-20 03:25:14 -0700."
+```
+
+Most actions probably will take one or more inputs, though. Here's an example of an action with one
+`requires` statement:
+
+```rb
+class PrintDoubledNumber < ApplicationAction
+  requires :number, Numeric
+
+  def execute
+    puts("#{number} doubled is #{number * 2}")
+  end
+end
+
+PrintDoubledNumber.new(number: 8).run
+# => prints "8 doubled is 16"
+```
+
+In the example above, because the `PrintDoubledNumber` action class declares `requires :number`, a
+`#number` instance method is available for all instances of that action class. This `#number`
+instance method is used within the `PrintDoubledNumber#execute` action.
+
+All subsequent arguments given to `requires` are used to define a "shape" via the [`shaped`
+gem](https://github.com/davidrunger/shaped/).
+
+The simplest way to define the expected "shape" of a required action parameter is probably to
+declare its expected class, as illustrated above (where we specified that the `number` input
+parameter must be an instance of `Numeric`). However, the `shaped` gem supports a wide variety of
+ways to specify the expected "shape" of an input. A few additional examples are shown below; see the
+[`shaped` documentation](https://github.com/davidrunger/shaped/) for more possibilities.
+
+#### Specifying the expected shape of a Hash input
+
+```rb
+class PrintNameAndEmail < ApplicationAction
+  # The `{ email: String, phone: String }` argument specifies the expected shape of `user_data`.
+  requires :user_data, { name: String, email: String }
+
+  def execute
+    puts("The email of #{user_data[:name]} is #{user_data[:email]}.")
+  end
+end
+
+PrintNameAndEmail.new(user_data: { name: 'Tom', email: 'tommy@example.com' }).run
+# => prints "The email of Tom is tommy@example.com."
+
+# The name and email keys are strings; they are supposed to be symbols.
+PrintNameAndEmail.new(user_data: { 'name' => 'Thomas', 'email' => 'tommy@example.com' })
+# => raises RungerActions::TypeMismatch
+
+# The `:name` key is missing in the `user_data` hash.
+PrintNameAndEmail.new(user_data: { email: 'tommy@example.com' })
+# => raises RungerActions::TypeMismatch
+```
+
+#### Specifying ActiveModel-style validations
+
+```rb
+class PrintEmail < ApplicationAction
+  requires :email, String, format: { with: /.+@.+\..+/ }, length: { minimum: 6 }
+
+  def execute
+    puts("The email is '#{email}'.")
+  end
+end
+
+PrintEmail.new(email: 'jefferson@example.com').run
+# => prints "The email is 'jefferson@example.com'."
+
+# This email doesn't match the specified regex
+PrintEmail.new(email: 'Thomas Jefferson')
+# => raises RungerActions::TypeMismatch
+
+# This email is too short
+PrintEmail.new(email: 'a@b.c')
+# => raises RungerActions::TypeMismatch
+```
+
+#### Specifying arbitrary input "shapes" by providing a callable object
+
+You can leverage `shaped`'s [`Callable` shape
+type](https://github.com/davidrunger/shaped/#shapedshapescallable) by providing any object that
+responds to `#call` (such as a lambda). This allows you unlimited flexibility to define requirements
+for the action's input(s).
+
+```rb
+class PrintSmallEvenNumber < ApplicationAction
+  requires :small_even_number, ->(number) { (0..6).cover?(number) && number.even? }
+
+  def execute
+    puts("#{small_even_number} is a small, even number.")
+  end
+end
+
+PrintSmallEvenNumber.new(small_even_number: 2).run
+# => prints "2 is a small, even number."
+
+# This number is not even
+PrintSmallEvenNumber.new(small_even_number: 3).run
+# => raises RungerActions::TypeMismatch
+
+# This number is not small
+PrintSmallEvenNumber.new(small_even_number: 200).run
+# => raises RungerActions::TypeMismatch
+```
+
+#### Specifying validations for ActiveRecord inputs
+
+When declaring a `requires` where the input is specified (via the second argument to `requires`) to
+be a class that inherits from `ActiveRecord::Base`, there are a few special things that happen:
+1. You can provide a **validation block** for the ActiveRecord object. Within this block, you can
+   specify validations on attributes of that ActiveRecord model.
+2. You can check, by calling `valid?` on an instance of the action, whether the ActiveRecord
+   object(s) that are inputs for the action meet the **validation block** validations.
+3. You can access any validation errors (from the **validation block**) via the `#errors` method of
+   the action instance.
+4. You can execute the action instance via `run!` rather than `run`; this will raise an exception
+   (and not run the `#execute` method) if any of the validations from a **validation block** are not
+   met.
+
+```rb
+class PrintFirstAndLastName < ApplicationAction
+  requires :user, User do
+    validates :name, format: { with: /.+ .+/ }
+  end
+
+  def execute
+    name_parts = user.name.split(' ')
+    puts("First name: #{name_parts.first}. Last name: #{name_parts.last}")
+  end
+end
+
+user = User.find(1)
+user.is_a?(ActiveRecord::Base)
+# => true
+user.name
+# => "David Runger"
+action = PrintFirstAndLastName.new(user: user)
+action.valid?
+# => true
+action.errors.to_hash
+# => {}
+action.run!
+# => prints "First name: David. Last name: Runger"
+
+user = User.find(2)
+user.name
+# => "Cher"
+action = PrintFirstAndLastName.new(user: user)
+action.valid?
+# => false
+action.errors.to_hash
+# => {:name=>["is invalid"]}
+action.run!
+# => raises RungerActions::InvalidParam
+```
+
+### `::returns`
+
+The `::returns` class method describes the value(s) that an action promises to return (if any).
+
+As with `requires`, an action can have zero, one, or more `returns` statements.
+
+An action that is used for its "side effects," such as most of the examples above that use `puts` to
+print output, will probably not have any `returns` statements.
+
+However, if you want the action to return object(s)/data to other parts of your code, then you'll
+need to declare those return values using the `returns` class method.
+
+Here's an example:
+
+```rb
+class MultiplyNumber < ApplicationAction
+  requires :input_number, Numeric
+
+  returns :doubled_number, Numeric
+  returns :tripled_number, Numeric
+
+  def execute
+    result.doubled_number = input_number * 2
+    result.tripled_number = input_number * 3
+  end
+end
+
+multiply_result = MultiplyNumber.new(input_number: 1.5).run
+multiply_result.class
+# => MultiplyNumber::Result
+puts("The number doubled is #{multiply_result.doubled_number}")
+# => prints "The number doubled is 3.0"
+puts("The number tripled is #{multiply_result.tripled_number}")
+# => prints "The number tripled is 4.5"
+```
+
+#### The `result` object
+
+We can see in the example above that `MultiplyNumber#execute` references `result`, which is an
+object provided automatically to action instances. Because the `MultiplyNumber` action declares
+`returns :doubled_number` and `returns :tripled_number`, the `result` object automatically has
+`#doubled_number=` and `#tripled_number=` writer methods, which can (and should) be invoked by the
+action instance in order to set those values on the `result` object.
+
+When we call `MultiplyNumber.new(input_number: 1.5).run`, the return value of `#run` is the action's
+`result` object. Outside of the action, we can then access the return values that were set within
+the action's `#execute` method; we do this via the `#doubled_number` and `#tripled_number` reader
+methods that are defined on the result object (which we captured in a local variable called
+`multiply_result`).
+
+#### All promised values must be returned
+
+If an action fails to set any promised return values on the `result` object, then an error will be
+raised when `#run` is called:
+
+```rb
+class MultiplyNumber < ApplicationAction
+  requires :input_number, Numeric
+
+  returns :doubled_number, Numeric
+  returns :tripled_number, Numeric
+
+  def execute
+    # PROBLEM BELOW! An error will be raised when this action is executed,
+    # because we fail to set a `doubled_number` return value.
+
+    # result.doubled_number = input_number * 2
+    result.tripled_number = input_number * 3
+  end
+end
+
+multiply_result = MultiplyNumber.new(input_number: 10).run
+# => raises RungerActions::MissingResultValue
+```
+
+#### Validating the "shape" of returned values
+
+As with the `requires` action class method, the "shape" of the promised return values declared via
+`returns` can be described via the arguments to `returns`, which are passed to the [`shaped`
+gem](https://github.com/davidrunger/shaped/). Leveraging this functionality allows you to ensure
+that your action is providing the expected type of return values.
+
+```rb
+class UppercaseEmail < ApplicationAction
+  requires :email, String, format: { with: /.+@.+/ }
+
+  returns :uppercased_email, String, format: { with: /[A-Z]+@[A-Z.]+/ }
+
+  def execute
+    result.uppercased_email = email.upcase
+  end
+end
+
+UppercaseEmail.new(email: 'david@protonmail.com').run.uppercased_email
+# => "DAVID@PROTONMAIL.COM"
+```
+
+If an action attempts to set a return value that doesn't match the specified "shape" for that return
+value, then an `RungerActions::TypeMismatch` error will be raised:
+
+```rb
+class UppercaseEmail < ApplicationAction
+  requires :email, String, format: { with: /.+@.+/ }
+
+  returns :uppercased_email, String, format: { with: /[A-Z]+@[A-Z.]+/ }
+
+  def execute
+    # PROBLEM BELOW! This action is supposed to _upcase_ the email, not downcase it!
+    result.uppercased_email = email.downcase
+  end
+end
+
+UppercaseEmail.new(email: 'david@protonmail.com').run
+# => raises RungerActions::TypeMismatch
+```
+
+### `::fails_with`
+
+The `::fails_with` class method can be used to enumerate possible "failure modes" for the action.
+
+As with `requires` and `returns`, an action can have zero, one, or more `fails_with` statements.
+
+Generally, it's best to try to write actions in a way such that we don't expect any failures, but
+sometimes there are things outside of our control; in such cases, using `fails_with` to list these
+possible points of failure is a good idea. For example, a call to an external API might time out or
+receive a 500 error response.
+
+Here's a (contrived) example with one `fails_with` declaration:
+
+```rb
+class PrintRandomNumberAboveFive < ApplicationAction
+  fails_with :number_was_too_small
+
+  def execute
+    random_number = rand(10)
+    if random_number > 5
+      puts(random_number)
+    else
+      result.number_was_too_small!
+    end
+  end
+end
+
+result = PrintRandomNumberAboveFive.new.run
+# => prints "9" (sometimes)
+result.success?
+# => true
+result.number_was_too_small?
+# => false
+```
+
+In the case above, we didn't encounter the error condition, which we can verify via the `#success?`
+and `#number_was_too_small?` methods on the result. `#success?` is available on all action results,
+and `#number_was_too_small?` is available for this particular action result because the action class
+declares `fails_with :number_was_too_small`.
+
+And here's what a failure case would look like:
+
+```rb
+result = PrintRandomNumberAboveFive.new.run
+# => [doesn't print anything, if the random number is <= 5]
+result.success?
+# => false
+result.number_was_too_small?
+# => true
+```
+
+In this case, we entered the `else` branch of the action's `#execute` method and called the
+`result.number_was_too_small!` method (made available automatically because of the class's
+`fails_with :number_was_too_small` declaration). Since we called the `result.number_was_too_small!`
+method, indicating that that failure mode occurred when executing the action, `#success?` returns
+`false` and `#number_was_too_small?` returns `true`.
+
+#### Setting an `error_message`
+
+When invoking a `fails_with` error case, the bang method can optionally take an error message as an
+argument, which will then be made available via a special `error_message` reader on the result
+object:
+
+```rb
+class SellAlcohol < ApplicationAction
+  requires :age, Numeric
+
+  fails_with :too_young
+
+  def execute
+    if age < 21
+      result.too_young!("Age #{age} is too young to buy alcohol.")
+    else
+      puts('Enjoy your alcohol responsibly!')
+    end
+  end
+end
+
+result = SellAlcohol.new!(age: 17).run
+result.success?
+# => false
+result.too_young?
+# => true
+result.error_message
+# => "Age 17 is too young to buy alcohol."
+```
+
+# Alternatives
+
+This project is not the first of its kind!
+
+Here are a few similar projects:
+* [`interactor`](https://github.com/collectiveidea/interactor)
+* [`active_interaction`](https://github.com/AaronLasseigne/active_interaction)
+* [`mutations`](https://github.com/cypriss/mutations)
+* [`service_actor`](https://github.com/sunny/actor)
+
+# Status / Context
+
+I wouldn't recommend using this gem in production. It's very new (i.e. probably rough around the
+edges, subject to significant changes at a relatively rapid rate, and arguably somewhat feature
+incomplete) and I am not committed to maintaing the gem.
+
+I mostly built this gem because I wasn't _quite_ satisfied with any of the above alternatives that I
+knew about at the time that I decided to start building it. I built this gem mostly to scratch my
+own itch and for the sake of exploring this problem space a little bit.
+
+I am actively using this gem in the small Rails application that hosts my personal website and apps;
+you can check out its [`app/actions/`
+directory](https://github.com/davidrunger/david_runger/tree/master/app/actions) if you are
+interested in seeing some real-world use cases.
+
+# Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rspec` to run
+the tests. You can also run `bin/console` for an interactive prompt that will allow you to
+experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+# License
+
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).

data/RELEASING.md

@@ -0,0 +1,7 @@
+To release a new version, run `bin/release` with an appropriate `--type` option, e.g.:
+
+```
+bin/release --type minor
+```
+
+(This uses the `release_assistant` gem.)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task(default: :spec)

data/bin/_guard-core

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application '_guard-core' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?('This file was generated by Bundler')
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('guard', '_guard-core')