tron 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 990e0bd04a0f3189d1483d9ebe010c740461aedc
-  data.tar.gz: e11e18fc405897c6d3fc36fd14440efd4b5a2bb7
+  metadata.gz: eea7d3927403faf13121f530c2a64d3ae05fa55b
+  data.tar.gz: 6d70cb35c23eeb4b8b49e9cd031f6fad1fdb77b4
 SHA512:
-  metadata.gz: 6651802dd7c1e274810caff0c0f0e924614da61c3861e66278264e24e91cc285c97d24c64c2d79528fcf7b4adfbbefe3eb0108559f1e7c31ec89be4e6fd9ff2f
-  data.tar.gz: 4aa73296745a4415dd108627176530b320408cd96e6f639b462aa5610fa8e8889ef42f2c6023097b2c5d7f0f9a7d5f44c8efa32236a777a52b379f7d775cfb85
+  metadata.gz: a748c9ab621daf636f70d19f56ccc69f1b5f16881fd62a89e5389541175e6029db2aaec2125c2a61e858b51c4e77872a2e4e08d582a2bdce83b127a725aa0966
+  data.tar.gz: 2d2360d3a7ed669c84c01a45ebfc5826d30999ae8f083fd2f81b9ec9b033c3117cb6bc4a1f67dc14e205b6488a4e4bd5081e9463681cdeda067594d09b0675c3

data/README.md

@@ -2,7 +2,19 @@
 [![Build Status](https://travis-ci.org/halo/tron.svg?branch=master)](https://travis-ci.org/halo/tron)
 [![License](http://img.shields.io/badge/license-MIT-blue.svg)](http://github.com/halo/tron/blob/master/LICENSE.md)
 
-# Tron
+## TL;DR
+
+Tron is a minimalistic combination of a [monad](https://www.morozov.is/2018/09/08/monad-laws-in-ruby.html) and [value object](https://madeintandem.com/blog/creating-value-objects-in-ruby/), implemented in [a few lines](https://github.com/halo/tron/blob/master/lib/tron.rb) of code.
+
+Return `Tron.success(:it_worked)` or `Tron.failure(:aww_too_bad)` from a method to explain why and how it succeded/failed. That returns an immutable Struct (value object) that responds to `result.success?` and `result.failure?`. 
+
+The reason is accessible in `result.success #=> :it_worked`. You can add more metadata as a second argument: `Tron.failure(:nopes, error_code: 404)` which you can access like a Struct: `result.error_code #=> 404`.
+
+Chaining can make your code cleaner: `result.on_success { download }.on_failure { show_message }`
+
+## Introduction
+
+
 
 Imagine you have a class like this:
 
@@ -14,7 +26,7 @@ class User
 end
 ```
 
-It's not clear from the code what this method returns (`true`?, a `User`?, a user ID?). What if an error occured - how does anyone calling `User.delete 42` know what happened?
+It's not clear from the code what this method returns. `true`?, a `User`?, a user ID?. What if a network error occurs, how does anyone calling `User.delete 42` know what happened?
 
 Indeed, it is not even clear what "successful" means in the context of this message - if there is no user and you try to delete one, is that considered a "failure"?
 
@@ -22,21 +34,19 @@ Let's rewrite the method using Tron:
 
 ```ruby
 class User
-  include Tron
-
   def self.delete(id)
-    return Failure.call(:id_missing) unless id
-    return Failure.call(:invalid_id, id: id) unless id.match /[a-f]{8}/
+    return Tron.failure(:id_missing) unless id
+    return Tron.failure(:invalid_id, id: id) unless id.match /[a-f]{8}/
 
     user = @users[id]
     if @users.delete id
-      Success.call :user_deleted, user: user
+      Tron.success :user_deleted, user: user
     else
-      Success.call :deletion_failed, id: id
+      Tron.success :deletion_failed, id: id
     end
 
   rescue ConnectionError
-      Failure.call :deletion_failed_badly, id: id
+    Tron.failure :deletion_failed_badly, id: id
   end
 end
 ```
@@ -45,39 +55,37 @@ One could even take it a step further and write it like this:
 
 ```ruby
 class User
-  include Tron
-
   def self.delete(id)
-    # If any one of these fail, the following blocks won't be executed
-    check_id_syntax(id)
-      .on_success { delete_user(id) }
-      .on_success { send_sms }
-      .on_success { redirect }
+    check_id_syntax(id).on_success { delete_user(id) }
+                       .on_success { send_sms }
+                       .on_success { redirect }
   end
 
   def self.check_id_syntax(id)
-    return Failure.call(:id_missing) unless id
-    return Failure.call(:invalid_id, id: id) unless id.match /[a-f]{8}/
-    Success.call(:id_looks_good)
+    return Tron.failure(:id_missing) unless id
+    return Tron.failure(:invalid_id, id: id) unless id.match /[a-f]{8}/
+    
+    Tron.success :id_looks_good
   end
 
   def self.delete_user(id)
     user = @users[id]
+    
     if @users.delete id
-      Success.call :user_deleted, user: user
+      Tron.success :user_deleted, user: user
     else
-      Success.call :deletion_failed, id: id
+      Tron.success :deletion_failed, id: id
     end
 
-  rescue ConnectionError
-    Failure.call :deletion_failed_badly, id: id
+  rescue ConnectionError => ex
+    Tron.failure :deletion_failed_badly, id: id, message: ex.message
   end
 end
 ```
 
-### So what are the benefits?
+## So what are the benefits?
 
-#### 1. It will give you robust and predictable code
+### 1. It will give you robust and predictable code
 
 Tron will give you this consistent, implementation-unaware, programming convention:
 
@@ -85,28 +93,33 @@ Tron will give you this consistent, implementation-unaware, programming conventi
 result = User.delete 42
 
 if result.success?
-  puts "It worked! You deleted the user #{result.meta.user.first_name}"
+  puts "It worked! You deleted the user #{result.user.first_name}"
 else
-  puts "Aw, could not delete User with ID #{result.meta.id} because #{result.code}"
+  puts "Aw, couldn't delete User with ID #{result.id} because #{result.failure}"
 end
 ```
 
+The result is just a Struct:
+
 ```ruby
 result = User.delete 42
 
-result.success? # => true
-result.failure? # => false
-result.metadata # => { object: <#User id=42> }
-result.meta     # => { object: <#User id=42> }
-result.object   # => <#User id=42>   <- shortcut for meta[:object]
+# Query whether it worked
+result.success? # => false
+result.failure? # => true
+
+# Query why and how
+result.success # => nil
+result.failure # => :deletion_failed_badly
 
-# In case you use Hashie, you will get that via #meta
-require 'hashie/mash'
-result.meta     # => <#Hashie::Mash object: <#User id=42>>
-result.object   # => <#User id=42>   <- shortcut for meta.object
+# Access immutable metadata
+result.message # => "..."
+result.inspect # => "#<struct failure=:alright, user_id=42, message='...'>"
+
+result.message.upcase! # => modification raises an exception
 ```
 
-#### 2. If will give you better tests
+### 2. If will give you better tests
 
 How would you test this code?
 
@@ -127,20 +140,29 @@ end
 
 You cannot simply test for the `false` as expected return value because it could mean anything. Tron helps you to check the response objects for every case.
 
-#### 3. It gives you documentation
+### 3. It gives you documentation
 
 While the code you're writing becomes slightly more verbose, that verbosity translates directly into documenation. You see immediately what each line is doing.
 
-### Background
+## Upgrading from 0.x.x to 1.x.x
+
+* Don't use `include Tron`, it is not useful any more. There are no subclasses you might want to access.
+* Replace `Tron::Success.call` with `Tron.success` (same for failure). The syntax is identical.
+* The result object is now a Struct and has no `#meta` and `#metadata` methods anymore.
+* The result object does not respond to `#code` any more. Instead use `#success` and `#failure` respectively. This is so that you can use `#code` as metadata, and also so that you can query the code via `#success` immediately, without first having to check `#success?`.
+
+## Background
+
+Tron is a complete rewrite of its predecessor [operation](https://github.com/halo/operation). I got inspired by the [deterministic](https://github.com/pzol/deterministic) gem, which is the follow-up of the [monadic](https://github.com/pzol/monadic) gem. There are some [complicated structs](https://github.com/dry-rb/dry-struct/blob/master/lib/dry/struct.rb) so I got inspired by [this robust implementation](https://github.com/iconara/immutable_struct) and simplified it even more.
 
-Tron is a complete rewrite of its predecessor [operation](https://github.com/halo/operation). I got inspired by the [deterministic](https://github.com/pzol/deterministic) gem, which is the follow-up of the [monadic](https://github.com/pzol/monadic) gem.
+## Requirements
 
-`operation` is very useful, but the API was always a bit cumbersome. Additionally, there was no paradigm of chaining trons, i.e. run multiple trons but bail out if one of them fails.
+* Ruby >= 2.3.0
 
-### Requirements
+## Copyright
 
-* Ruby >= 2.2.3
+MIT 2015-2019 halo. See [MIT-LICENSE](http://github.com/halo/tron/blob/master/LICENSE.md).
 
-### Copyright
+## Caveats
 
-MIT 2015 halo. See [MIT-LICENSE](http://github.com/halo/tron/blob/master/LICENSE.md).
+* There are no setter methods in the returned Struct, so you cannot overwrite the metadata. The values are also frozen, so you don't accidentally modify the attributes in-place. However, they are not deep-frozen, so an object may still be modified if you're ignorant.

data/lib/tron.rb

@@ -11,7 +11,7 @@ module Tron
     code.respond_to?(:to_sym) ||
       raise(ArgumentError, 'Tron.success must be called with a Symbol as first argument')
 
-    attributes.respond_to?(:keys)||
+    attributes.respond_to?(:keys) ||
       raise(ArgumentError, 'The attributes Hash for Tron.success must respond to #keys')
 
     attributes.respond_to?(:values) ||
@@ -34,7 +34,7 @@ module Tron
       end
 
       def on_success(proc = nil, &block)
-        (proc || block).call
+        (proc || block).call self
       end
 
       def on_failure(_ = nil)
@@ -47,7 +47,7 @@ module Tron
     code.respond_to?(:to_sym) ||
       raise(ArgumentError, 'Tron.failure must be called with a Symbol as first argument')
 
-    attributes.respond_to?(:keys)||
+    attributes.respond_to?(:keys) ||
       raise(ArgumentError, 'The attributes Hash for Tron.failure must respond to #keys')
 
     attributes.respond_to?(:values) ||
@@ -74,7 +74,7 @@ module Tron
       end
 
       def on_failure(proc = nil, &block)
-        (proc || block).call
+        (proc || block).call self
       end
     end.new code.to_sym, *attributes.values.map(&:freeze)
   end

data/lib/tron/version.rb

@@ -2,7 +2,7 @@ module Tron
   module VERSION #:nodoc:
     MAJOR = 1
     MINOR = 0
-    TINY  = 0
+    TINY  = 1
     PRE = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join '.'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tron
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - halo
@@ -66,20 +66,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  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: General-purpose method return objects that can be chained. Think minimalistic
   value object monads. Heavily inspired by the `deterministic` gem, but much much
   more light-weight.