workout 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4dd785717f0d7e8ecdd15a9cfd0b654281324335
+  data.tar.gz: c611ae01b7fea3fa364e53f71db641600f833b5a
+SHA512:
+  metadata.gz: 5b51601c6b4e8ac03a0710853af0009c598a044120714677ccc39a293d1b8d7de0bd9b3f244a5c81d6065f796022ccb3b292b5b96f2cb9464c1676768e19a45d
+  data.tar.gz: 28020d6b73f05160302b335f94d3beebceeb3676fb22242ad98f40efb8cb7815674ab74868e20c6b4e7ffcb025a188cad2c8d55da0f5f1a855e3d745d93d4108

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in workout.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 myobie
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,208 @@
+# Workout
+
+Build simple workflows by enumerating the steps to execute. Know if it
+succeeds or not and get at the failures. A nice way to write service
+objects.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'workout'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install workout
+
+## Usage
+
+### The basics
+
+Make a simple service object that does one thing:
+
+```ruby
+class SayHello
+  include Workout
+
+  work do
+    puts "Hello"
+  end
+end
+
+SayHello.new.() # => # prints Hello
+```
+
+Calling the class method `::work` will define an instance method
+`#work` and define it as the only step to execute when `#call` is
+called.
+
+Or if you need to do three things:
+_(Steps are executing in the order they are defined.)_
+
+```ruby
+class SayStuff
+  include Workout
+
+  step :one do
+    puts "one"
+  end
+
+  step :two do
+    puts "two"
+  end
+
+  step :three do
+    puts "three"
+  end
+end
+
+SayStuff.new.() # => # prints one, then two, then three
+```
+
+`::step` will define a method named the same as the symbol argument
+passed. In this example, instances of `SayStuff` will have the methods
+`#one`, `#two`, and `#three`. Those method names are stored in an array
+so they are executed in the correct order when `#call` is called.
+
+If any step `#fail`s or `#raise`s, then the execution stops at that point:
+
+```ruby
+class SayStuff
+  include Workout
+
+  step :one do
+    puts "one"
+  end
+
+  step :two do
+    raise "What is going on here?"
+  end
+
+  step :three do
+    puts "three"
+  end
+end
+
+workflow = SayStuff.new.() # => # prints one
+
+workflow.errors.first.to_a # => [:two, { message: "What is going on here?", ... }]
+
+workflow.complete? # => true
+workflow.valid?    # => false
+workflow.success?  # => false
+```
+
+### Validations
+
+Including `Workout` also means including
+[`ActiveModel::Validations`](http://www.rubydoc.info/gems/activemodel/ActiveModel/Validations).
+An example of how to use it is:
+
+```ruby
+class EmailReceipt
+  include Workout
+
+  attr_reader :email
+
+  validates :email, format: { with: /.+@.+\..+/ }
+
+  def initialize(email, receipt)
+    @email = email
+    @receipt = receipt
+  end
+
+  step :pdf do
+    @receipt.prepare_pdf
+  end
+
+  step :send_email do
+    ReceiptMailer.email(email, receipt).deliver_later
+  end
+end
+```
+
+### A real example
+
+```ruby
+class ChargeStripeCard
+  include Workout
+
+  attr_reader :payment, :payable
+
+  def initialize(stripe_account:, card_token:, payable:, current_user:)
+    super
+
+    @stripe_account = stripe_account
+    @card_token = card_token
+    @payable = payable
+    @current_user = current_user
+  end
+
+  def description
+    "Charge for #{@current_user.email} for #{@payable.description}"
+  end
+
+  def application_percentage
+    0.005
+  end
+
+  def amount
+    @payable.amount
+  end
+
+  def application_fee
+    (amount * application_percentage).to_i
+  end
+
+  validates :amount, numericality: { only_integer: true, greater_than_or_equal_to: 100 }
+
+  step :stripe_charge do
+    Stripe::Charge.create({
+      amount: @payable.amount,
+      currency: @payable.currency,
+      card: @card_token,
+      description: description,
+      application_fee: application_fee
+    }, @stripe_account.access_token)
+  end
+
+  # The return value of the previous step is optionally passed in as an
+  # argument to the current step. The first step would be passed nil.
+  step :build_payment do |charge|
+    charge_response = StripeChargeResponse.new(body: charge.to_hash)
+    Payment.new({
+      stripe_charge_response: charge_response,
+      payable: @payable,
+      stripe_charge_id: charge.id,
+      amount: charge.amount,
+      currency: charge.currency,
+      application_fee: application_fee # TODO: retreive this from the stripe api?
+    })
+  end
+
+  step :save_and_complete do |payment|
+    @payable.payment = payment
+
+    Payable.transaction do
+      payment.save!
+      @payable.pay!
+      @payment = payment
+      complete! # one can force the workflow to be complete at anytime
+    end
+  end
+end
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/myobie/workout/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/workout.rb

@@ -0,0 +1,135 @@
+require "workout/version"
+require "active_support/concern"
+require "active_model/validations"
+
+module Workout
+  extend ActiveSupport::Concern
+  include ActiveModel::Validations
+
+  class_methods do
+    def steps
+      @_steps ||= []
+    end
+
+    def step(name, &blk)
+      define_method name, &blk
+      self.steps << name
+    end
+
+    def work(&blk)
+      define_method :work, &blk
+      self.steps.replace([:work])
+    end
+  end
+
+  included do
+    attr_accessor :current_step
+    private :current_step=
+    attr_reader :fsm
+    validate :copy_failures_to_errors
+  end
+
+  def initialize(**opts)
+    @_fsm = MicroMachine.new(:pending).tap do |fsm|
+      fsm.when(:complete, :pending => :completed)
+      fsm.when(:fail,     :pending => :failed)
+    end
+    @_failures = []
+  end
+
+  def complete?
+    @_fsm.state == :completed
+  end
+
+  def complete
+    @_fsm.trigger(:complete)
+  end
+
+  def complete!
+    @_fsm.trigger!(:complete)
+  end
+
+  def fail(**args)
+    should_throw = args.delete(:throw) != false
+    @_failures.push({ step: current_step, args: args })
+    @_fsm.trigger(:fail)
+    validate
+    throw :failure if should_throw
+  end
+
+  private def copy_failures_to_errors
+    @_failures.each do |info|
+      errors.add info[:step], info[:args]
+    end
+  end
+
+  def success?
+    complete? && valid?
+  end
+
+  private def rescuing(&blk)
+    if defined?(ActiveRecord::ActiveRecordError)
+      rescuing_with_active_record(&blk)
+    else
+      rescuing_without_active_record(&blk)
+    end
+  end
+
+  private def rescuing_with_active_record(&blk)
+    rescuing_without_active_record do
+      blk.call
+    end
+  rescue ActiveRecord::ActiveRecordError => e
+    fail({
+      message: e.message,
+      subject: e.record,
+      exception: e,
+      throw: false
+    })
+    self
+  end
+
+  private def rescuing_without_active_record(&blk)
+    blk.call
+    self
+  rescue StandardError => e
+    fail({
+      message: e.message,
+      subject: e,
+      exception: e,
+      throw: false
+    })
+    self
+  end
+
+  def call
+    # don't even try if we are already invalid
+    return self if invalid?
+
+    rescuing do
+      # run each step, possibly feeding the last result to the next
+      self.class.steps.reduce(nil) do |last, name|
+        self.current_step = name
+
+        # #fail will throw :failure instead of raising
+        result = catch :failure do
+          if method(name).arity == 1
+            send name, last
+          else
+            send name
+          end
+        end
+
+        if invalid?
+          break
+        else
+          result
+        end
+      end
+
+      complete if valid?
+    end
+  ensure
+    self.current_step = nil
+  end
+end

data/lib/workout/version.rb

@@ -0,0 +1,3 @@
+module Workout
+  VERSION = "0.0.1"
+end

data/workout.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'workout/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "workout"
+  spec.version       = Workout::VERSION
+  spec.authors       = ["Nathan Herald"]
+  spec.email         = ["me@nathanherald.com"]
+  spec.summary       = %q{Build simple workflow service objects.}
+  spec.description   = %q{Make objects to represent and execute operations as steps, one by one, and know if it succeeded.}
+  spec.homepage      = ""
+  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_dependency "activesupport"
+  spec.add_dependency "activemodel"
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: workout
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Nathan Herald
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: Make objects to represent and execute operations as steps, one by one,
+  and know if it succeeded.
+email:
+- me@nathanherald.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/workout.rb
+- lib/workout/version.rb
+- workout.gemspec
+homepage: ''
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Build simple workflow service objects.
+test_files: []