README.md in safe_operation-1.0.0 vs README.md in safe_operation-2.0.0
- old
+ new
@@ -1,23 +1,12 @@
# SafeOperation
+[](https://rubygems.org/gems/safe_operation)
+[](https://travis-ci.org/JuanitoFatas/safe_operation)
+
Write safer code with SafeOperation.
-```ruby
-any_operation_may_fail = ->{ User.find(1) }
-
-operation = SafeOperation.either(any_operation_may_fail) do
- # MUST handle the failure here
-end
-
-# know if operation succeeded
-operation.success?
-
-# get the result of the performed operation
-operation.result
-```
-
## Installation
Add this line to your application's Gemfile:
```ruby
@@ -32,49 +21,71 @@
$ gem install safe_operation
## Usage
+No monkey patch.
+
```ruby
-class User
- ActiveRecordRecordNotFound = Class.new(StandardError)
+class RecordNotFound < StandardError; end
+class User def self.find(id); new; end; end;
+class Guest; end
+class Admin; def initialize(user); end; end
+class SuperAdmin; def initialize(admin); end; end
- def self.find(id)
- (id == 1) ? new : raise(ActiveRecordRecordNotFound)
- end
-
- def self.find_by(*); end
+operation = SafeOperation.run do
+ User.find(1)
end
-class Guest
-end
+# Know if operation succeeded
+operation.success?
-SafeOperation.either(->{ User.find(1) })
-# => raises an SafeOperation::NoFailureHandler error
+# Get the value of the performed operation
+operation.value
-SafeOperation.either(->{ User.find(1) }) do
- Guest.new
-end
-# => returns a SafeOperation::Success object with User
-# => #<SafeOperation::Success:0x007fbc8d8c5ae0 @success=#<User:0x007fbc8d8c5b08>>
+# Common patterns, reloaded
+SafeOperation.run { User.find(1) }.value_or(Guest.new)
-SafeOperation.either(->{ User.find(2) }) do
- Guest.new
+# Handling exceptions
+SafeOperation.run { raise(RecordNotFound) }.value_or_else do |exception|
+ if exception.is_a?(RecordNotFound)
+ Guest.new
+ else
+ # logging, re-raise, etc.
+ end
end
-# => rescue ActiveRecordRecordNotFound, returns a SafeOperation::Failure object with Guest
-# #<SafeOperation::Failure:0x007fbc8dbb71e0 @failure=#<Guest:0x007fbc8dbb7208>>
-SafeOperation.either(->{ User.find_by(id: 42) }) do
- Guest.new
-end
-# => returns a SafeOperation::Failure object with Guest
-# #<SafeOperation::Failure:0x007fbc8dbb71e0 @failure=#<Guest:0x007fbc8dbb7208>>
+# Apply on first operation
+operation = SafeOperation.
+ run { User.find(1) }.
+ and_then { |user| Admin.new(user) }
+
+operation.value # #<Admin ...>
+
+# Chainable
+operation = SafeOperation.
+ run { User.find(1) }.
+ and_then { |user| Admin.new(user) }.
+ and_then { |admin| SuperAdmin.new(admin) }
+
+operation.value # #<SuperAdmin ...>
+
+# Add or_else to handle failed operation
+operation = SafeOperation.
+ run { raise(RecordNotFound) }.
+ and_then { |user| Admin.new(user) }.
+ or_else { Guest.new }
+
+operation.success? # => false
+operation.value # => #<Guest ...>
```
+See test suite for more examples.
+
## Contributing
This project follows the [Moya Contributors Guidelines][moya].
-TLDR: means we give out push access easily and often.
+TLDR: means we give out commit access easily and often.
[moya]: https://github.com/Moya/contributors
Bug reports and pull requests are welcome on GitHub at https://github.com/JuanitoFatas/safe_operation.
This project is intended to be a safe, welcoming space for collaboration, and contributors are