outbacker 0.0.2

data/examples/app/domain/appointment_calendar.rb

@@ -0,0 +1,95 @@
+#
+# Plain-old Ruby object that contains our business logic.
+#
+# Can be a domain object, a service object, a use-case object,
+# a DCI context, or whatever.
+#
+class AppointmentCalendar
+
+  #
+  # Include the Outbacker module. See config/initializers/outbacker.rb
+  # for the restrictions on where you can include this.
+  #
+  include Outbacker
+
+  #
+  # An "outbacked" domain method, i.e., one that can
+  # process outcome callbacks passed into it—here via
+  # the &outcome_handlers parameter:
+  #
+  def book_appointment(params, &outcome_handlers)
+
+    #
+    # Immediately pass the outcome_handlers block to the
+    # with method (provided by Outbacker), which in turn
+    # takes a block that must wrap the body of your
+    # business-logic method:
+    #
+    with(outcome_handlers) do |outcomes|
+      if user_lacks_sufficient_credits?
+        #
+        # Trigger the insufficient_credits outcome and run the
+        # corresponding callback block (provided via the
+        # &outcome_handlers block):
+        #
+        outcomes.handle :insufficient_credits
+        return
+      end
+
+      appointment = Appointment.new(params)
+      if appointment.save
+        ledger.deduct_credits_for appointment
+
+        notify_user_about appointment
+        notify_office_about appointment
+
+        #
+        # Trigger the successful_booking outcome and run the
+        # corresponding callback block (provided via the
+        # &outcome_handlers block), and pass that block
+        # the newly-booked appointment:
+        #
+        outcomes.handle :successful_booking, appointment
+      else
+        #
+        # Trigger the failed_validation outcome and run the
+        # corresponding callback block (provided via the
+        # &outcome_handlers block), and pass that block
+        # the appointment that failed validation:
+        #
+        outcomes.handle :failed_validation, appointment
+      end
+    end
+  end
+
+  #
+  # Any other public business logic methods.
+  # ...
+  #
+
+
+  private
+
+  def user_lacks_sufficient_credits?
+    # Check current user's credit balance is >= cost of appointment.
+  end
+
+  def ledger
+    # Return Ledger object that manages credit balances and transactions.
+  end
+
+  def notify_user_about(appointment)
+    # Enqueue background jobs to send emails, SMS, phone push notifications, etc.
+    # This lets us avoids ActiveRecord callback spaghetti.
+  end
+
+  def notify_office_about(appointment)
+    # Post office dashboard notification and activity feed entry, enqueue
+    # background jobs to send emails, SMS, phone push notifications, etc.
+    # This also lets us avoids ActiveRecord callback spaghetti.
+  end
+
+  #
+  # Any other private internal helper methods.
+  #
+end

data/examples/config/initializers/outbacker.rb

@@ -0,0 +1,27 @@
+
+#
+# Specify where the Outbacker module cannot be included.
+# If you try to include Outbacker within subclasses of
+# ActiveRecord::Base, ActionController::Base, or
+# MyBlacklistedClass, Outbacker will raise an exception.
+#
+# By default, ActiveRecord::Base and ActionController::Base
+# are blacklisted. This is how Outbacker encourages skinny
+# models, and discourages fat, obese models.
+#
+Outbacker.configure do |c|
+  c.blacklist = [ActiveRecord::Base, ActionController::Base, MyBlacklistedClass]
+end
+
+#
+# Specify where the Outbacker module can be included.
+# If you try to include Outbacker within subclasses of any
+# classes other than UseCase, ServiceObject, or DomainObject,
+# Outbacker will raise an exception.
+#
+# The default is an empty whitelist, but specifying a whitelist
+# is recommended way to configure this policy.
+#
+Outbacker.configure do |c|
+  c.whitelist = [UseCase, ServiceObject, DomainObject]
+end

data/examples/test/controllers/appointments_controller_test.rb

@@ -0,0 +1,33 @@
+
+#
+# You'll probably want to move the following to your test_helper.rb
+#
+require 'outbacker'
+require 'test_support/outbacker_stub'
+
+
+class AppointmentsControllerTest < ActionController::TestCase
+
+
+  test "user is redirected to the credits purchase page when they lack sufficient credits" do
+    #
+    # Stub the AppointmntsController#book_appointment method, specifying that
+    # it will have an outcome of :insufficient_credits.
+    #
+    calendar_stub = Outbacker::OutbackerStub.new
+    calendar_stub.stub('book_appointment', :insufficient_credits, stubbed_appointment)
+
+    # This is a method we added to our controller to inject dependencies:
+    @controller.inject_calendar(calendar_stub)
+
+    post :create, appointment: {
+      starts_at: '201506051600-600',
+      ends_at: '201506051600-600',
+      etc: 'and so on'
+    }
+
+    assert_redirected_to new_credits_url
+  end
+
+
+end

data/lib/outbacker.rb

@@ -0,0 +1,130 @@
+require "outbacker/version"
+require "configurations"
+
+module Outbacker
+
+  include Configurations
+
+  DEFAULT_BLACKLIST = [ActiveRecord::Base, ActionController::Base]
+  DEFAULT_WHITELIST = []
+
+  configuration_defaults do |c|
+    c.blacklist = DEFAULT_BLACKLIST
+    c.whitelist = DEFAULT_WHITELIST
+  end
+
+
+  #
+  # DSL-ish factory method to create an instance of OutcomeHandlerSet
+  # given a block of outcome handlers.
+  #
+  # To be used within your business-logic methods in combination with
+  # the OutcomeHandlerSet#handle method.
+  #
+  def with(outcome_handlers)
+    outcome_handler_set = OutcomeHandlerSet.new(outcome_handlers)
+    yield outcome_handler_set
+
+    if outcome_handlers.nil?
+      return outcome_handler_set.triggered_outcome, *outcome_handler_set.args
+    else
+      raise "No outcome selected" unless outcome_handler_set.outcome_handled?
+    end
+  end
+
+  #
+  # Class to encapsulate the processing of a block of outcome handlers.
+  #
+  OutcomeHandlerSet = Struct.new(:outcome_handlers,
+                                 :triggered_outcome,
+                                 :args,
+                                 :handled_outcome) do
+
+    #
+    # Process the outcome specified by the given outcome_key,
+    # using the outcome handlers set on this OutcomeHandlerSet
+    # instance. Any additiona arbitrary arguments can be passed
+    # through to the corresponding outcome handler callback.
+    #
+    def handle(outcome_key, *args)
+      self.triggered_outcome = outcome_key
+      self.args = args
+
+      if outcome_handlers
+        outcome_handlers.call(self)
+        raise "No outcome handler for outcome #{outcome_key}" unless outcome_handled?
+      end
+    end
+
+    #
+    # Internal method to indicate that the outcome has been
+    # handled by some han dler.
+    #
+    def outcome_handled?
+      !!self.handled_outcome
+    end
+
+    #
+    # Specify an outcome handler callback block for the specified
+    # outcome key.
+    #
+    def of(outcome_key, &outcome_block)
+      execute_outcome_block(outcome_key, &outcome_block)
+    end
+
+    #
+    # Provides an alternate way to specify a callback block using
+    # method names.
+    #
+    def method_missing(method_name, *args, &outcome_block)
+      super unless /^outcome_of_(?<suffix>.*)/ =~ method_name.to_s
+      outcome_key = suffix.to_sym
+
+      execute_outcome_block(outcome_key, &outcome_block)
+    end
+
+
+    private
+
+    #
+    # Internal helper method to execute the given outcome block
+    # if it matches the triggered outcome.
+    #
+    def execute_outcome_block(outcome_key, &outcome_block)
+      if !outcome_block
+        raise "No block provided for outcome #{outcome_key}"
+      end
+
+      if outcome_key == self.triggered_outcome
+        raise "Outcome #{outcome_key} already handled" if outcome_handled?
+        self.handled_outcome = outcome_key
+        outcome_block.call(*self.args)
+      end
+    end
+
+  end
+
+  #
+  # Restrict where Outbacker can be included.
+  #
+  def self.included(target_module)
+    apply_whitelist(target_module) if Outbacker.configuration.whitelist.any?
+    apply_blacklist(target_module) if Outbacker.configuration.blacklist.any?
+  end
+
+  def self.apply_whitelist(target_module)
+    Outbacker.configuration.whitelist.each do |whitelisted_classs|
+      return if target_module.ancestors.include?(whitelisted_classs)
+    end
+    fail "Can only include #{self.name} within a subclass of: #{Outbacker.configuration.whitelist.join(', ')}"
+  end
+
+  def self.apply_blacklist(target_module)
+    Outbacker.configuration.blacklist.each do |blacklisted_class|
+      if target_module.ancestors.include?(blacklisted_class)
+        fail "Cannot include #{self.name} within an #{blacklisted_class} class, a plain-old Ruby object is preferred."
+      end
+    end
+  end
+
+end

data/lib/outbacker/version.rb

@@ -0,0 +1,3 @@
+module Outbacker
+  VERSION = "0.0.2"
+end

data/lib/test_support/outbacker_stub.rb

@@ -0,0 +1,42 @@
+#
+# Provides a simple means to stub "Outbacked" methods. Specifically,
+# it lets you specify what outcome callback you want invoked on
+# your stubbed method.
+#
+# Usage:
+# stubbed_object = OutbackerStub.new
+# stubbed_object.stub('stubbed_method_name',
+#                     :desired_outcome,
+#                     block_arg1, block_arg2, ...)
+#
+# Alternatively, combine instantiation and stubbing:
+# stubbed_object = OutbackerStub.new('stubbed_method_name',
+#                                    :desired_outcome,
+#                                    block_arg1, block_arg2, ...)
+#
+# Note that this only provides stubbing functionality, no mocking
+# functionality (i.e., ability to verify that a method was invoked on
+# a test double) is provided. This should be sufficient for your test
+# needs, as you can/should write separate tests to verify that
+# the expected methods were invoked on your double.
+#
+module Outbacker
+  class OutbackerStub
+    include Outbacker
+
+    def initialize(method_name=nil, outcome_key=nil, *block_args)
+      if method_name && outcome_key
+        stub(method_name, outcome_key, *block_args)
+      end
+    end
+
+    def stub(method_name, outcome_key, *block_args)
+      define_singleton_method(method_name, ->(*args, &outcome_handlers) {
+        with(outcome_handlers) do |outcomes|
+          outcomes.handle outcome_key, *block_args
+        end
+      })
+    end
+
+  end
+end

data/outbacker.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'outbacker/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "outbacker"
+  spec.version       = Outbacker::VERSION
+  spec.authors       = ["Anthony Garcia"]
+  spec.email         = ["polypressure@outlook.com"]
+  spec.summary       = "Drive complexity out of your Rails controllers once and for all, while keeping your models fit and trim."
+  spec.description   = <<-DESC
+    A micro library to keep conditional logic out of your Rails
+    controllers and help you write more intention-revealing
+    code with both skinny controllers and skinny models.
+  DESC
+  spec.homepage      = "https://github.com/polypressure/outbacker"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.5"
+  spec.add_development_dependency "m", "~> 1.3.1"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency 'configurations', '~> 2.2.0'
+  spec.add_development_dependency "codeclimate-test-reporter"
+end

data/test/outbacker_stub_test.rb

@@ -0,0 +1,97 @@
+require 'test_helper'
+
+class OutbackerStubTest < Minitest::Test
+  extend DefineTestNamesWithStrings
+
+  test "#stub defines the specified method on the stub instance" do
+    outbacker_stub = Outbacker::OutbackerStub.new
+
+    outbacker_stub.stub('register_user', :successful_registration, Object.new)
+
+    assert_respond_to outbacker_stub, 'register_user'
+  end
+
+  test "#stub invokes the outcome callback for the specified outcome key" do
+    outbacker_stub = Outbacker::OutbackerStub.new
+    correct_block_executed = false
+
+    outbacker_stub.stub('register_user', :successful_registration, Object.new)
+
+    outbacker_stub.register_user do |on_outcome|
+      on_outcome.of(:successful_registration) do |user|
+        correct_block_executed = true
+      end
+
+      on_outcome.of(:failed_validation) do |user|
+        correct_block_executed = false
+      end
+
+      on_outcome.of(:some_other_outcome) do |user|
+        correct_block_executed = false
+      end
+    end
+
+    assert correct_block_executed, "Outcome block not executed by stub."
+  end
+
+  test "#stub passes the specified block arguments to the outcome block" do
+    outbacker_stub = Outbacker::OutbackerStub.new
+    block_arg_1 = Object.new
+    block_arg_2 = Object.new
+    block_args_passed = []
+
+    outbacker_stub.stub('register_user', :successful_registration, block_arg_1, block_arg_2)
+
+    outbacker_stub.register_user do |on_outcome|
+      on_outcome.of(:successful_registration) do |arg1, arg2|
+        block_args_passed = [arg1, arg2]
+      end
+    end
+
+    assert_equal [block_arg_1, block_arg_2], block_args_passed
+  end
+
+
+  test "#new defines the specified method on the stub instance" do
+    outbacker_stub = Outbacker::OutbackerStub.new('register_user', :successful_registration, Object.new)
+
+    assert_respond_to outbacker_stub, 'register_user'
+  end
+
+  test "#new invokes the outcome callback for the specified outcome key" do
+    outbacker_stub = Outbacker::OutbackerStub.new('register_user', :successful_registration, Object.new)
+    correct_block_executed = false
+
+    outbacker_stub.register_user do |on_outcome|
+      on_outcome.of(:successful_registration) do |user|
+        correct_block_executed = true
+      end
+
+      on_outcome.of(:failed_validation) do |user|
+        correct_block_executed = false
+      end
+
+      on_outcome.of(:some_other_outcome) do |user|
+        correct_block_executed = false
+      end
+    end
+
+    assert correct_block_executed, "Outcome block not executed by stub."
+  end
+
+  test "#new passes the specified block arguments to the outcome block" do
+    block_arg_1 = Object.new
+    block_arg_2 = Object.new
+    outbacker_stub = Outbacker::OutbackerStub.new('register_user', :successful_registration, block_arg_1, block_arg_2)
+    block_args_passed = []
+
+    outbacker_stub.register_user do |on_outcome|
+      on_outcome.of(:successful_registration) do |arg1, arg2|
+        block_args_passed = [arg1, arg2]
+      end
+    end
+
+    assert_equal [block_arg_1, block_arg_2], block_args_passed
+  end
+
+end