skywalker 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 189ad007dad735d22002e8e676be20d37202e427
-  data.tar.gz: 49633c02c8e18e1572ed5d570b3ad49e1ca71f85
+  metadata.gz: 3f6ceac6b8264295e36a783bfb010c99b1caa549
+  data.tar.gz: 2705c927542812c9033a49957d37ed00a7a9cddf
 SHA512:
-  metadata.gz: 32d48d08a9c6bd7a25af17485f2f0202fcee026b32133c3851093e2c530959148578c01dc29b012ea8f6ff08692c212b7eb8b912bdd695c1b4bc0c3bf3d77cc3
-  data.tar.gz: 4103d5ba416a5e403d2c00390c92f62d8001e7712a56b9c692e186ddc6d78e8eba589bae6b201ae4521e252cac066a391739d4dc98255a03834beb16eed91208
+  metadata.gz: 93acfda6e3a9adf0516d804f206d234e5cf14efe338eb4abeef2bf810917e1bcdd9638c04545aad6823b4f5b275c48fafe40f93dea498c9161f800bbdc5fa6f7
+  data.tar.gz: 6b1a5df15debb17a660a2fa92eb95ce14b8b555a056768b905245ac1491f46d6ea398ef5ab50f9221deef18ff736b3c9ceb51a47bdc0ef7931994b6479b69c95

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+All commits by Rob Yurkowski unless otherwise noted.
+
+
+## 1.1.0 (2014-11-03)
+
+- Expanded documentation.
+- Allow `on_success` and `on_failure` callbacks to be optional.
+- Allow passing arbitrary values to command instantiation.
+- Adds this changelog.
+
+## 1.0.0 (2014-11-02)
+
+- Initial creation.

data/README.md

@@ -4,8 +4,8 @@ Skywalker is a gem that provides a simple command pattern for applications that
 
 ## Why Skywalker?
 
-It's impossible to come up with a single-word clever name for a gem about commands. If you can't
-achieve clever, achieve topicality.
+It's impossible to come up with a single-word name for a gem about commands that's at least marginally
+witty. If you can't achieve wit or cleverness, at least achieve topicality, right?
 
 ## What is a command?
 
@@ -34,7 +34,19 @@ having to know its internals. Standard caveats apply, but if you have a `CreateG
 command, you should be able to infer that calling the command with the correct arguments
 will produce the expected result.
 
-### A gateway to harder architectures
+### Knowledge of Results Without Knowledge of Response
+
+A command prescriptively takes callbacks or `#call`able objects, which can be called
+depending on the result of the command. By default, `Skywalker::Command` can handle
+an `on_success` and an `on_failure` callback, which are called after their respective
+results. You can define these in your controllers, which lets you run the same command
+but respond in unique ways, and keeps controller concerns inside the controller.
+
+You can also easily override which callbacks are run. Need to run a different callback
+if `request.xhr?`? Simply override `run_success_callbacks` and `run_failure_callbacks`
+and call your own.
+
+### A Gateway to Harder Architectures
 
 It's not hard to create an `Event` class and step up toward full event sourcing, or to
 go a bit further and implement full CQRS. This is the architectural pattern your parents
@@ -58,9 +70,153 @@ Or install it yourself as:
 
 ## Usage
 
+Let's talk about a situation where you're creating a group and sending an email inside a
+Rails app.
+
+Standard operating procedure usually falls into one of two patterns, both of which are
+mediocre. The first makes use of ActiveRecord callbacks:
+
+```ruby
+# app/controllers/groups_controller.rb
+class GroupsController < ApplicationController
+  # ...
+
+  def create
+    @group = Group.new(params.require(:group).permit(:name))
+
+    if @group.save
+      redirect_to @group, notice: "Created the group!"
+    else
+      flash[:alert] = "Oh no, something went wrong!"
+      render :new
+    end
+  end
+end
+
+
+# app/models/group.rb
+class Group < ActiveRecord::Base
+  after_create :send_notification
+
+  private
+
+  def send_notification
+    NotificationMailer.group_created_notification(self).deliver
+  end
+end
+```
+
+This might seem concise because it keeps the controller small. (Fat model,
+thin controller has been a plank of Rails development for a while, but it's
+slowly going away, thank heavens). But there are two problems here:
+first, it introduces a point of coupling between the model and the mailer,
+which not only makes testing slower, it means that these two objects are
+now entwined. Create a group through the Rails console? You're sending an email with
+no way to skip that. Secondly, it reduces the reasonability of the code. When you
+look at the `GroupsController`, you can't suss out the fact that this sends an email.
+
+**Moral #1: Orthogonal concerns should not be put into ActiveRecord callbacks.**
+
+The alternative is to keep this inside the controller:
+
+```ruby
+# app/controllers/groups_controller.rb
+class GroupsController < ApplicationController
+  # ...
+
+  def create
+    @group = Group.new(params.require(:group).permit(:name))
+
+    if @group.save
+      NotificationMailer.group_created_notification(@group).deliver
+      redirect_to @group, notice: "Created the group!"
+    else
+      flash[:alert] = "Oh no, something went wrong!"
+      render :new
+    end
+  end
+end
+```
+
+This is more reasonable, but it's longer in the controller and at some point your eyes
+begin to glaze over. Imagine as these orthogonal concerns grow longer and longer. Maybe
+you're sending a tweet about the group, scheduling a background job to update some thumbnails,
+or hitting a webhook URL. You're losing the reasonability of the code because of the detail.
+
+Moreover, imagine that the group email being sent contains critical instructions on how
+to proceed. What if `NotificationMailer` has a syntax error? The group is created, but the
+mail won't be sent. Now the user hasn't gotten a good error, and your database is potentially
+fouled up by half-performed requests. You can run this in a transaction, but that does not
+reduce the complexity contained within the controller. 
+
+**Moral #2: Rails controllers should dispatch to application logic, and receive instructions on how to respond.**
+
+The purpose of the command is to group orthogonal but interdependent results into logical operations. Here's how that
+looks with a `Skywalker::Command`:
+
+
+```ruby
+# app/controllers/groups_controller.rb
+class GroupsController < ApplicationController
+  # ...
+
+  def create
+    CreateGroupCommand.call(
+      group:      Group.new(params.require(:group).permit(:name)),
+      on_success: method(:on_create_success),
+      on_failure: method(:on_create_failure)
+    )
+  end
+
+
+  def on_create_success(command)
+    redirect_to command.group, notice: "Created the group!"
+  end
+
+
+  def on_create_failure(command)
+    flash[:alert] = "Oh no, something went wrong!"
+    @group = command.group
+    render :new
+  end
+end
+
+
+# app/commands/create_group_command.rb
+class CreateGroupCommand < Skywalker::Command
+  def execute!
+    save_group!
+    send_notification!
+  end
+
+
+  private def save_group!
+    group.save!
+  end
+
+
+  private def send_notifications!
+    notifier.call(group).deliver
+  end
+
+
+  private def notifier
+    @notifier ||= NotificationsMailer.method(:group_created_notification)
+  end
+end
+```
+
+You can of course set up a default for Group as with `#notifier` and pass in
+params only, but I find injecting a pre-constructed ActiveRecord object usually
+works well.
+
+
+### Basic Composition Summary
 Compose your commands:
 
 ```ruby
+require 'skywalker/command'
+
 class AddGroupCommand < Skywalker::Command
   def execute!
     # Your transactional operations go here. No need to open a transaction.
@@ -73,13 +229,36 @@ Then call your commands:
 
 ```ruby
 command = AddGroupCommand.call(
-  on_success: method(:on_success),
-  on_failure: method(:on_failure)
+  any_keyword_argument: "Is taken and has an attr_accessor defined for it."
 )
 
-You can pass any object responding to `#call` to the `on_success` and `on_failure` handlers, including procs, lambdas, controller methods, or other commands themselves.
 ```
 
+You can pass any object responding to `#call` to the `on_success` and `on_failure` handlers, including procs, lambdas, controller methods, or other commands themselves.
+
+### Overriding Methods
+
+The following methods are overridable for easy customization:
+
+- `execute!`
+  - Define your operations here.
+- `transaction(&block)`
+  - Uses an `ActiveRecord::Base.transaction` by default, but can be customized. `execute!` runs inside of this.
+- `confirm_success`
+  - Fires off callbacks on command success (i.e. non-error).
+- `run_success_callbacks`
+  - Dictates which success callbacks are run. Defaults to `on_success` if defined.
+- `confirm_failure`
+  - Fires off callbacks on command failure (i.e. erroneous state), and sets the exception as `command.error`.
+- `run_failure_callbacks`
+  - Dictates which failure callbacks are run. Defaults to `on_failure` if defined.
+
+For further reference, simply see the command file. It's less than 90 LOC and well-commented.
+
+## Testing
+
+To come.
+
 ## Contributing
 
 1. Fork it ( https://github.com/robyurkowski/skywalker/fork )

data/lib/skywalker/command.rb

@@ -13,9 +13,14 @@ module Skywalker
     ################################################################################
     # Instantiates command, setting all arguments.
     ################################################################################
-    def initialize(on_success: nil, on_failure: nil)
-      self.on_success = on_success
-      self.on_failure = on_failure
+    def initialize(**args)
+      args.each_pair do |k, v|
+        singleton_class.class_eval do
+          send(:attr_accessor, k) unless self.respond_to? k
+        end
+
+        self.send("#{k}=", v)
+      end
     end
 
 
@@ -57,7 +62,12 @@ module Skywalker
     # Trigger the given callback on success
     ################################################################################
     private def confirm_success
-      on_success.call(self)
+      run_success_callbacks
+    end
+
+
+    private def run_success_callbacks
+      on_success.call(self) if self.respond_to?(:on_success)
     end
 
 
@@ -66,7 +76,12 @@ module Skywalker
     ################################################################################
     private def confirm_failure(error)
       self.error = error
-      on_failure.call(self)
+      run_failure_callbacks
+    end
+
+
+    private def run_failure_callbacks
+      on_failure.call(self) if self.respond_to?(:on_failure)
     end
   end
 end

data/lib/skywalker/version.rb

@@ -1,3 +1,3 @@
 module Skywalker
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/skywalker.rb

@@ -1,5 +1,4 @@
 require "skywalker/version"
 
 module Skywalker
-  # Your code goes here...
 end

data/skywalker.gemspec

@@ -18,6 +18,8 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
+  spec.required_ruby_version = '>= 2.1.2'
+
   spec.add_dependency 'activerecord', '~> 4.1'
 
   spec.add_development_dependency "bundler", "~> 1.7"

data/spec/lib/skywalker/command_spec.rb

@@ -5,21 +5,20 @@ module Skywalker
   RSpec.describe Command do
     describe "convenience" do
       it "provides a class call method that instantiates and calls" do
-        arg = 'blah'
-
         expect(Command).to receive_message_chain('new.call')
-        Command.call(arg)
+        Command.call
       end
     end
 
 
     describe "instantiation" do
-      it "accepts an on_success callback" do
-        expect { Command.new(on_success: ->{ nil }) }.not_to raise_error
+      it "accepts a variable list of arguments" do
+        expect { Command.new(a_symbol: :my_symbol, a_string: "my string") }.not_to raise_error
       end
 
-      it "accepts an on_failure callback" do
-        expect { Command.new(on_failure: ->{ nil }) }.not_to raise_error
+      it "sets an instance variable for each argument" do
+        command = Command.new(a_symbol: :my_symbol)
+        expect(command.a_symbol).to eq(:my_symbol)
       end
     end
 
@@ -53,10 +52,27 @@ module Skywalker
           command.call
         end
 
-        it "calls the on_success callback with itself" do
-          expect(on_success).to receive(:call).with(command)
+        it "runs the success callbacks" do
+          expect(command).to receive(:run_success_callbacks)
           command.call
         end
+
+        describe "on_success" do
+          context "when on_success is defined" do
+            it "calls the on_success callback with itself" do
+              expect(on_success).to receive(:call).with(command)
+              command.call
+            end
+          end
+
+          context "when on_success is not defined" do
+            let(:command) { Command.new }
+
+            it "does not call on_success" do
+              expect(command).not_to receive(:on_success)
+            end
+          end
+        end
       end
 
 
@@ -79,11 +95,32 @@ module Skywalker
           command.call
         end
 
-        it "calls the on_failure callback with itself" do
+        it "runs the failure callbacks" do
           allow(command).to receive(:error=)
-          expect(on_failure).to receive(:call).with(command)
+          expect(command).to receive(:run_failure_callbacks)
           command.call
         end
+
+        describe "on_failure" do
+          before do
+            allow(command).to receive(:error=)
+          end
+
+          context "when on_failure is defined" do
+            it "calls the on_failure callback with itself" do
+              expect(on_failure).to receive(:call).with(command)
+              command.call
+            end
+          end
+
+          context "when on_failure is not defined" do
+            let(:command) { Command.new }
+
+            it "does not call on_failure" do
+              expect(command).not_to receive(:on_failure)
+            end
+          end
+        end
       end
     end
   end

data/spec/spec_helper.rb

@@ -54,7 +54,7 @@ RSpec.configure do |config|
 
   # This setting enables warnings. It's recommended, but in some cases may
   # be too noisy due to issues in dependencies.
-  config.warnings = true
+  # config.warnings = true
 
   # Many RSpec users commonly either run the entire suite or an individual
   # file, and it's useful to allow more verbose output when running an

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: skywalker
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Rob Yurkowski
@@ -103,6 +103,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -125,7 +126,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.1.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="