operation 0.0.3 → 1.0.0.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7476c1c39664219019b09c247cc250dbebf0f345
-  data.tar.gz: 40fa98cae6e39acfbf0dcbd53a7791b2d303ce1a
+  metadata.gz: e609f4ffd6fbf2a50ff0667fbf4bfdedd3a2f874
+  data.tar.gz: 28a06955ebe29eba6317917ae0be8dd3211a4711
 SHA512:
-  metadata.gz: eac58c9b91409957e0b30b06d0a9ed8202184df68dccde38096876e1f678cdba1351e42fe257fb4482e21b89993d7d40eaa176cd5f590567c1fed9d4a8548c6c
-  data.tar.gz: 791d169139a360edb60d6a5dcc2d8bdb683a344d5b1e5007099f9bd86a978416be1ba2116f731e9cbef841bd23a877e02bf3038d347e28ae557d7d66df4dfe81
+  metadata.gz: 8f8ee5b725295f6bd571e116775662374ae825f348752dd8284b244f45cb76cf160cbe50e16db8fbe1706bb3dd35e120caac1ad3da858492a0accae7473f835e
+  data.tar.gz: 6eb1d71f1794e0eebccb48f260922a0675de4f16f9d49f92e8cd15977f6bacd4b72390155bb114d7947a96df020f726e6807f4d66682b14f15e9c16c55942efe

data/README.md

@@ -4,7 +4,7 @@ Imagine you have a class like this:
 
 ```ruby
 class User
-  def delete(id)
+  def self.delete(id)
     @users.delete id
   end
 end
@@ -12,42 +12,32 @@ end
 
 What does it return? True? The User? an ID? What if an error occured? How does anyone calling `User.delete 42` know what happened?
 
-This is where `Operation` comes in. You would just **always** return an Operation. That Object holds information about what happened, like so:
+This is where `Operation` comes in. You would simply return an operation object. That instance holds information about what happened, like so:
 
 ```ruby
 class User
-  def delete(id)
+  def self.delete(id)
     return Operation.new(code: :id_missing) unless id
     return Operation.new(code: :invalid_id, id: id) unless id.match /[a-f]{8}/
 
     user = @users[id]
     if @users.delete id
-      Operation.new success:true, code: :user_deleted, user: user
+      Operation.new success: true, code: :user_deleted, user: user
     else
-      Operation.new code: :deletion_failed
+      Operation.new code: :deletion_failed, id: id
     end
+
   rescue ConnectionError
-      Operation.new code: :deletion_failed_badly
+      Operation.new code: :deletion_failed_badly, id: id
   end
 end
 ```
 
-This will give you this joyful, consistent, conventional, implementation-unaware programming feeling:
-
-```ruby
-  operation = User.delete 42
-  if operation.success?
-    puts "It worked! You deleted the user #{operation.meta.user.first_name}"
-  else
-    puts "Oh, could not delete User with ID #{operation.object} because #{operation.code}"
-  end
-```
-
-For your convenience you can use `Operations#failure` and `Operations.success`:
+There are some shortcuts too keep it less verbose:
 
 ```ruby
 class User
-  def delete(id)
+  def self.delete(id)
     return Operations.failure(:id_missing) unless id
     return Operations.failure(:invalid_id, id: id) unless id.match /[a-f]{8}/
 
@@ -57,27 +47,73 @@ class User
     else
       Operations.failure :deletion_failed
     end
+
   rescue ConnectionError
       Operation.failure :deletion_failed_badly
   end
 end
 ```
 
-`#object` is just a shortcut to `#meta.object`:
+### So what are the benefits?
+
+#### 1. Robust and predictable code
+
+This will give you this joyful, consistent, conventional, implementation-unaware programming feeling:
+
+```ruby
+operation = User.delete 42
+
+if operation.success?
+  puts "It worked! You deleted the user #{operation.meta.user.first_name}"
+else
+  puts "Aw, could not delete User with ID #{operation.meta.id} because #{operation.code}"
+end
+```
+
+```ruby
+operation = User.delete 42
+
+operation.success? # => true
+operation.failure? # => false
+operation.metadata # => { object: <#User id=42> }
+operation.meta     # => { object: <#User id=42> }
+operation.object   # => <#User id=42>   <- shortcut for meta[:object]
+
+# In case you use Hashie, you will get that via #meta
+require 'hashie/mash'
+operation.meta     # => <#Hashie::Mash object: <#User id=42>>
+operation.object   # => <#User id=42>   <- shortcut for meta.object
+```
+
+#### 2. Better tests
+
+How would you test this code?
 
 ```ruby
-  operation = User.delete 42
-  operation.success? # => true
-  operation.object # => <#User id=42>
-  operation.meta # => <#Hashie::Mash object: <#User id=42>>
-  operation.metadata # => { object: <#User id=42> }
-  operation.failure? # => false
+class Product
+  def self.delete(id)
+    return false if id.blank?
+    return false unless product = Products.find(id)
+    return false unless permission?
+    api.update(id, attributes)
+  end
+
+  def self.permission?
+    Date.today.sunday?
+  end
+end
 ```
 
+You cannot simply test for the `false` as expected return value because it could mean anything.
+
+#### 3. Documentation
+
+While the code becomes more verbose, that verbosity translates directly into documenation. You see immediately what each line is doing.
+
 ### Requirements
 
-* Ruby >= 1.9
+* Ruby >= 2.1
 
 ### Copyright
 
-MIT 2014 halo. See [MIT-LICENSE](http://github.com/halo/operation/blob/master/MIT-LICENSE).
+MIT 2015 halo. See [MIT-LICENSE](http://github.com/halo/operation/blob/master/LICENSE.md).

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/lib/operation/deferrable.rb

@@ -0,0 +1,90 @@
+class Operation
+  module Deferrable
+
+    attr_reader :arguments
+
+    def on_progress(&block)
+      return unless block
+      progressables.unshift block
+    end
+
+    def on_success(&block)
+      return unless block
+
+      if succeeded?
+        block.call(*arguments)
+      elsif !failed?
+        successables.unshift block
+      end
+    end
+
+    def on_failure(&block)
+      return unless block
+
+      if failed?
+        block.call(*arguments)
+      elsif !succeeded?
+        failables.unshift block
+      end
+    end
+
+    def succeeded?
+      status == :succeeded
+    end
+
+    def failed?
+      status == :failed
+    end
+
+    def status
+      @status ||= :unknown
+    end
+
+    def set_status(new_status, *args)
+      @arguments = args
+      @status = new_status
+
+      if succeeded? && !successables.empty?
+        while callback = successables.pop
+          callback.call(*arguments)
+        end
+        failables.clear if !failables.empty?
+
+      elsif failed? && !failables.empty?
+        while callback = failables.pop
+          callback.call(*arguments)
+        end
+        successables.clear if !failables.empty?
+      end
+    end
+
+    def progress(percent, code)
+      return if succeeded? || failed?
+
+      progressables.each do |callback|
+        callback.call ::Operation::Progress.new(percent, code)
+      end
+    end
+
+    def succeed(*args)
+      set_status :succeeded, *args
+    end
+
+    def fail(*args)
+      set_status :failed, *args
+    end
+
+    def successables
+      @successables ||= []
+    end
+
+    def failables
+      @failables ||= []
+    end
+
+    def progressables
+      @progressables ||= []
+    end
+
+  end
+end

data/lib/operation/progress.rb

@@ -0,0 +1,18 @@
+class Operation
+  class Progress
+
+    def initialize(percent, code = nil)
+      @percent, @code = percent, code
+    end
+
+    def percent
+      @percent.to_i
+    end
+
+    def code
+      return if @code.to_s == ''
+      @code.to_s.to_sym
+    end
+
+  end
+end

data/lib/operation/version.rb

@@ -1,9 +1,10 @@
 class Operation
   module VERSION #:nodoc:
-    MAJOR = 0
+    MAJOR = 1
     MINOR = 0
-    TINY  = 3
+    TINY  = 0
+    PRE = 'beta'
 
-    STRING = [MAJOR, MINOR, TINY].compact.join('.')
+    STRING = [MAJOR, MINOR, TINY, PRE].compact.join '.'
   end
 end

data/lib/operation.rb

@@ -1,30 +1,48 @@
-require 'hashie/mash'
-require 'operations' # <- Not that we need them here, but the developer using this gem might want them.
+require 'operation/deferrable'
+require 'operation/progress'
+require 'operations'
 
 class Operation
-
+  include ::Operation::Deferrable
   attr_reader :metadata, :code
 
   def initialize(options = {})
-    @success = [true, 'true', 1, '1'].include? options[:success]
-    @code = options[:code].to_s.to_sym unless options[:code].to_s == ''
-    @metadata = options[:metadata]
+    @options = options
   end
 
   def success?
-    !!@success
+    [true, 'true', 1, '1'].include? options[:success]
   end
 
   def failure?
     !success?
   end
 
+  def code
+    return if options[:code].to_s == ''
+    options[:code].to_s.to_sym
+  end
+
   # Convenience Wrapper
   def object
-    meta.object
+    meta[:object] || meta['object'] || meta.object
+  rescue
+    nil
+  end
+
+  def metadata
+    options[:metadata]
   end
 
   def meta
+    if defined? Hashie::Mash
+      metamash
+    else
+      metadata
+    end
+  end
+
+  def metamash
     if metadata.respond_to? :each_pair
       Hashie::Mash.new metadata
     elsif metadata
@@ -33,4 +51,9 @@ class Operation
       Hashie::Mash.new
     end
   end
+
+  private
+
+  attr_reader :options
+
 end

data/lib/operations.rb

@@ -1,11 +1,11 @@
 module Operations
 
   def self.success(code = :success, metadata = {})
-    Operation.new success: true, code: code, metadata: metadata
+    ::Operation.new success: true, code: code, metadata: metadata
   end
 
   def self.failure(code, metadata = {})
-    Operation.new success: false, code: code, metadata: metadata
+    ::Operation.new success: false, code: code, metadata: metadata
   end
 
 end

data/spec/lib/operation/deferrable_spec.rb

@@ -0,0 +1,69 @@
+require 'spec_helper'
+
+RSpec.describe Operation do
+  let(:operation)     { Operation.new }
+  let(:successables)  { [] }
+  let(:progressables) { [] }
+  let(:failables)     { [] }
+
+  describe '#on_progress' do
+    before do
+      operation.on_progress { |result| progressables << result }
+      operation.progress 42, :still_working
+      operation.progress 99, :almost_done
+    end
+
+    it 'calls all the successables' do
+      expect(progressables.size).to eq 2
+      expect(progressables.first.percent).to eq 42
+      expect(progressables.first.code).to eq :still_working
+      expect(progressables.last.percent).to eq 99
+      expect(progressables.last.code).to eq :almost_done
+    end
+
+    it 'does not call the successables' do
+      expect(successables).to be_empty
+    end
+
+    it 'does not call the failables' do
+      expect(failables).to be_empty
+    end
+
+    it 'does not alter the state' do
+      expect(operation.status).to eq :unknown
+    end
+  end
+
+  describe '#on_success' do
+    before do
+      operation.on_success { successables << 'called' }
+      operation.on_success { |result| successables << result }
+      operation.succeed :great
+    end
+
+    it 'calls all the successables' do
+      expect(successables).to eq ['called', :great]
+    end
+
+    it 'does not call the failables' do
+      expect(failables).to be_empty
+    end
+  end
+
+  describe '#on_failure' do
+    before do
+      operation.on_failure { failables << 'called' }
+      operation.on_failure { |result| failables << result }
+      operation.fail :bummer
+    end
+
+    it 'calls all the successables' do
+      expect(failables).to eq ['called', :bummer]
+    end
+
+    it 'does not call the failables' do
+      expect(successables).to be_empty
+    end
+  end
+
+end

data/spec/lib/operation_spec.rb

@@ -1,7 +1,6 @@
 require 'spec_helper'
-require 'operation'
 
-describe Operation do
+RSpec.describe Operation do
 
   describe '#success' do
     it 'handles different types of success' do
@@ -18,6 +17,7 @@ describe Operation do
       expect( Operation.new(success: 'false') ).to be_failure
       expect( Operation.new(success: 0) ).to be_failure
       expect( Operation.new(success: '0') ).to be_failure
+      expect( Operation.new ).to be_failure
     end
   end
 
@@ -45,7 +45,29 @@ describe Operation do
     end
   end
 
+  describe 'test setup' do
+    it 'has no Hashie' do
+      expect { Hashie }.to raise_error NameError
+    end
+  end
+
   describe '#meta' do
+    it 'is nil for nil' do
+      expect( Operation.new.meta ).to be_nil
+      expect( Operation.new(metadata: nil).meta ).to be_nil
+    end
+
+    it 'is whatever was passed in' do
+      expect( Operation.new(metadata: {}).meta ).to be_instance_of Hash
+      expect( Operation.new(metadata: { one: { two: :three } }).meta[:one][:two] ).to eq :three
+    end
+  end
+
+  describe '#meta', :hashie do
+    before :all do
+      require 'hashie/mash'
+    end
+
     it 'is a Mash for nil' do
       expect( Operation.new.meta ).to be_instance_of Hashie::Mash
       expect( Operation.new(metadata: nil).meta ).to be_instance_of Hashie::Mash

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require 'operation'
+
+RSpec.configure do |config|
+
+  config.raise_errors_for_deprecations!
+  config.disable_monkey_patching!
+  config.color = true
+  config.fail_fast = true
+
+end

metadata

@@ -1,69 +1,69 @@
 --- !ruby/object:Gem::Specification
 name: operation
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 1.0.0.beta
 platform: ruby
 authors:
 - halo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-27 00:00:00.000000000 Z
+date: 2015-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rb-fsevent
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: Implementation-agnostic method return status objects (say what?). Your
@@ -74,11 +74,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- MIT-LICENSE
 - README.md
+- Rakefile
 - lib/operation.rb
+- lib/operation/deferrable.rb
+- lib/operation/progress.rb
 - lib/operation/version.rb
 - lib/operations.rb
+- spec/lib/operation/deferrable_spec.rb
 - spec/lib/operation_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/halo/operation
@@ -91,17 +94,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.9.3
+      version: 2.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Implementation-agnostic method return status objects

data/MIT-LICENSE

@@ -1,20 +0,0 @@
-Copyright 2014 halo
-
-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.