resulting 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3da1dbc393fe607cb6285fb6e0a3c5fb2c932bd7e50e7312ef17e7896232a85b
-  data.tar.gz: 87eb2836ec966a6db44d0aa16a8aa4ae46a838e07cd65ba963f5e63249fa22c0
+  metadata.gz: a335ef962f6b9785f66c8c4d6830f575ba5db1910d3d49e74e693c83798775a0
+  data.tar.gz: fd89e762a7bc39aec9be3678478509c6306482aa4ca81f8954a07c9c61e0e06f
 SHA512:
-  metadata.gz: 581c7a452f0bda593ea2659dcf9bae700e4d1695057cc93d9224119f5c14b682c1c8fd10117b7833a52413468714cfcd5ecf90815f26d94c8f6326f56fab86e2
-  data.tar.gz: 86bcf54897b14ea11ccc04082c7b58dece2f7fd09ece466dd2d74fb748d8f4f9a7f788cf465a2046e03fd397267c3592fb4b561db8e00bc346e6f267b133fbca
+  metadata.gz: a2212406ba4ac45959186a25b579d20cfac6bf7b784abe62d81d184daac9ee42a866af16d4a32f87981ae48bcadf7288e21b409482bd3fbdd6c1369f6d2cee8e
+  data.tar.gz: 919091b0a3a3c486871815aa105a7714238ba4e16959cc55e272460763a4d222e3d87db412f752bb0a7e8a5ea174b4c25c73e75c5270d5b343e8e9af9d853f7d

data/.projections.json

@@ -0,0 +1,4 @@
+{
+  "lib/*.rb": { "alternate": "spec/{}_spec.rb" },
+  "spec/*_spec.rb": { "alternate": "lib/{}.rb" }
+}

data/.rspec

@@ -1,4 +1,4 @@
 --color
---format documentation
+--format progress
 --order random
 --require spec_helper

data/.rubocop.yml

@@ -16,7 +16,7 @@ Layout/MultilineMethodCallIndentation:
   Enabled: false
 
 Layout/LineLength:
-  Max: 100
+  Max: 110
   Exclude:
     - Rakefile
 
@@ -53,6 +53,9 @@ RSpec/MessageSpies:
 RSpec/MultipleExpectations:
   Enabled: false
 
+RSpec/NestedGroups:
+  Max: 4
+
 RSpec/NotToNot:
   EnforcedStyle: to_not
 

data/CHANGELOG.md

@@ -1,2 +1,5 @@
+# 2020-04-15
+Add basic functionality.
+
 # 2020-04-14
 Initial commit and release.

data/README.md

@@ -1,10 +1,7 @@
 # Resulting
 
-Welcome to your new gem! In this directory, you'll find the files you need to be
-able to package up your Ruby library into a gem. Put your Ruby code in the file
-`lib/resulting`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Resulting is a gem to help with result handling and coordinating validations and
+saving of (primarily) ActiveRecord objects.
 
 ## Installation
 
@@ -24,7 +21,311 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+There is a common pattern in a rails controller doing something like this:
+
+- Controller action calls a service (or two or three)
+- That service returns an object (or two or three)
+- If you want to see if it was successful, that service may have its own result
+object, or you can check if the object was persisted.
+- Maybe the service does that and just returns and object for serialization
+(more likely since we should have skinny controllers). But then you have the
+same problem.
+- Result objects are hard to manage outside a framework explicitly and
+ruthlessly designed to use them.
+
+There are of course some very complicated situations, but many situations can be
+solved using `Resulting`.
+
+While `Resulting` can be used in any way you see fit, the way I use it is
+described below.
+
+### Custom Results
+
+First we create a result object specific to our controller action. The reason
+for this is we don't need a result object that is so flexible it is basically an
+openstruct, but we want something with a slightly nicer API than a hash.
+
+Additionally, this adds clarity, with a tested class, to the result object. So
+anyone looking for what this result contains knows to just look for a result
+named after the controller action.
+
+```ruby
+class CreateUserAndWidgetResult
+  include Resulting::Resultable
+
+  def user
+    value[:user]
+  end
+
+  def widget
+    value[:widget]
+  end
+end
+```
+
+### Controller
+
+Now in our controller, since we know the result looks like, we can simply grab
+the relevant objects out of it and set them to instance variables for a view, or
+put them into JSON with [JBuilder](https://github.com/rails/jbuilder) or whatever.
+
+We can also just check to see if our result was successful, the simplest API for
+a result object.
+
+```ruby
+class NewController
+  def create
+    result = UserAndWidgetCreateService.call(params)
+    @user = result.user
+    @widget = result.widget
+
+    if result.success?
+      redirect_to :show
+    else
+      render :new
+    end
+  end
+end
+```
+
+### Result Object and Handlers
+
+Finally, in our service, we initialize the result object we first defined with
+our objects that we need to validate, save, and do whatever on.
+
+Then we call the shortcut `.validate_and_save` method which will validate all
+objects, this ensures that all objects will have `errors` even if the first one
+fails validation.
+
+If they are all valid, it will call `.save` (not `save!`) on each of them, inside an
+`ActiveRecord::Base.transaction`. If all `.save` calls return `true`. Then we
+will return a succesful result. If any of them return `false`, we will bail out
+early and raise an `ActiveRecord::Rollback` error inside of the transaction.
+
+```ruby
+class UserAndWidgetCreateService
+  def call(params)
+    new_result = CreateResult.success({
+      user: User.build(params[:user])
+      widget: Widget.build(params[:widget])
+      role: Role.build(user: user, widget: widget, role: :admin)
+    })
+
+    Resulting.validate_and_save(result)
+  end
+end
+```
+
+## Details
+
+1. [`Resulting::Runner`](#resultingrunner)
+     1. [`.run_all`](#run_allresult-method)
+     1. [`.run_until_failure`](#run_until_failureresult-method)
+     1. [With blocks](#with-blocks)
+     1. [Options (`:failure_case`, `:wrapper`)](#options-failure_case-wrapper)
+     1. [With Rails](#with-rails)
+1. [`Resulting::Handler`](#resultinghandler)
+1. [`Resulting::Result`](#resultingresult)
+    1. [Constructors (`.new`, `.success`, and `.failure`](#constructors-new-success-failure)
+    1. [`.wrap`](#wrap)
+    1. [Methods (`#value`, `#success?`, and `#failure?`](#methods-value-success-and-failure)
+    1. [Values](#values)
+1. [Resulting::Helpers](#resultinghelpers)
+
+## Resulting::Runner
+
+The `Resulting::Runner`'s will take a result object, and if that result is
+failing, return immediately. That way you can safely pass the results to any
+method that takes them without worrying about acting on a failed result. (It's
+almost like a monad, but definitely not a monad).
+
+### `.run_all(result, method:)`
+
+This will call the given `method` on every object in `result.values`. It will
+keep track whether or not all calls to `method` on each object were true.
+
+If all calls to `method` were `true`, it will return a successful result.
+
+### `.run_until_failure(result, method:)`
+
+This will call the given `method` on every object in `result.values` UNTIL it
+sees a failure. At that point, it will bail out and stop calling the method.
+
+### With Blocks
+
+Both of these methods take an optional block:
+
+- In `run_all`, the block will be run no matter what. The return value of the
+block will be `&&`'d with the current success value of calling `method` on all
+the values. That new success value will determine whether the call was
+successful.
+  ```ruby
+    Resulting::Runner.run_all(result, method: :validate) do
+      # Validate other things
+      # return true
+    end
+  ```
+- In `run_until_falure`, the block will be run no matter what. The return value of the
+block will be `&&`'d with the current success value of calling `method` on all
+the values. That new success value will determine whether the call was
+successful.
+  ```ruby
+    Resulting::Runner.run_until_failure(result, method: :validate) do
+      # Save other things
+      # return true
+    end
+  ```
+
+****NOTE: The return value of the block is what is used to determine
+success.**** Be mindful of the return value.
+
+### Options (`:failure_case`, `:wrapper`)
+
+`failure_case` is an optional argument. It should be a lambda that describes
+what to do at the end if a failure is encountered. By default it's just a lambda
+that returns false.
+
+For example, when validating, if all `:validate` calls have returned false, we
+just want to return `false`. However, if we are saving, and one of the saves
+returns false, we actually want to do `raise ActiveRecord::Rollback`.
+
+Odds are you will either return false or raise some error, but any lambda will
+do.
+
+`wrapper` is something that will wrap the whole result handling process. The
+common example here would be to wrap all saves in an
+`ActiveRecord::Base.transaction` block to ensure we can rollback safely.
+
+### With Rails (`.validate`, `.save`, and `.validate_and_save`)
+
+Most of the time this is used within rails, and as described there are some
+things you will commonly want to do.
+
+```ruby
+Resulting.validate(param)
+```
+
+Is equivalent to:
+
+```ruby
+Resulting::Runner.run_all(param, method: :validate)
+```
+
+```ruby
+Resulting.save(param)
+```
+
+Is equivalent to:
+
+```ruby
+Resulting::Runner.run_until_failure(
+  param,
+  method: :save,
+  failure_case: -> { raise ActiveRecord::Rollback },
+  wrapper: -> { ActiveRecord::Base.method(:transaction) },
+)
+```
+
+Both of these still take blocks.
+
+Finally, `Resulting.validate_and_save` will just call one after the other. This
+one does not take a block, so it assumes you just want to validating everything
+and then save it.
+
+## Resulting::Result
+
+This is a generic result class that implements `Resulting::Resultable`.
+
+### Constructors: (`.new`, `.success`, `.failure`)
+
+- `.new(success, value)` stores the value and sets success to the first
+parameter
+- `.success(value)` stores the value and sets success to true
+- `.failure(value)` stores the value and sets success as false
+
+### `.wrap`
+
+`Resulting::Result.wrap` is worth calling out on its own. `Result.wrap(value)`
+will do the following:
+
+- If `value` is a result (i.e. implements `Resulting::Resultable`) it returns
+the value.
+- If `value` is anything else, it will return `Result.success(value)`.
+
+```ruby
+$ foo = Object.new
+$ result = Resulting::Result.wrap(foo)
+$ result
+=> #<Resulting::Result:0x00007f91dd072238 @success=true, @value=#<Object:0x00007f91db929950>>
+$ Resulting::Result.wrap(result)
+=> #<Resulting::Result:0x00007f91dd072238 @success=true, @value=#<Object:0x00007f91db929950>>
+```
+
+You can use wrap to ensure you have a result object if you need it.
+
+### Methods: `#value`, `#success?`, and `#failure?`
+
+A result has helper methods, `#success?` and `#failure?` which just check whether
+`success` is truthy, and the obj is stored as the `value`.
+
+```ruby
+success = obj.validate # => true
+result = Resulting::Result.new(success, obj)
+
+result.success? # => true
+result.value # => obj
+```
+
+### `#values`
+
+`values` returns the `value` collapsed into an array. This variable is iterated
+over by the two runner methods.
+
+****NOTE: Resulting assumes any methods calls on the value mutate the value
+itself and that it is passed by reference.****
+
+- If `value` is a `Hash`, `values` is `value.values.flatten`
+- If `value` is anything else, `values` is `Array(value).flatten`
+  - (This will wrap objects in an array, and leave arrays alone.)
+
+When building your own result you can override this to provide different
+behavior. You could use this maintain access to an object but not call a method
+on it, or to add data you want acted on from a side effect.
+
+```ruby
+class MyResult
+  def user
+    values[:user]
+  end
+
+  def hashed_password
+    values[:password] # Omit from values, so it's not acted on
+  end
+
+  def values
+    [user, user.side_effect_record]
+  end
+end
+```
+
+In this case, we have a password (or any object in memory we don't/can't
+persist). It will be on the result object so we can do something with it, but by
+omitting it from `#values`, we don't have to worry about it being acted on.
+
+In contrast, let's say in our services we create some record as a side effect
+which couldn't be created at the time we created the result (this is pretty
+contrived, but go with it), then we can add that to the values as something to
+be validated, saved, or whatever when the runners process the result.
+
+## Resulting::Helpers
+
+If you include `Resulting::Helpers` in a given class or module, you get the
+some nifty helper shortcuts.
+
+```ruby
+Success(value) # Equal to Resulting::Result.success(value)
+Failure(value) # Equal to Resulting::Result.failure(value)
+```
 
 ## Development
 
@@ -35,4 +336,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at
-https://github.com/[USERNAME]/resulting.
+https://github.com/dewyze/resulting.

data/TODO.md

@@ -0,0 +1,3 @@
+- Chain methods together?
+- Failure case should take the values or the result so someone can manually do a
+rollback or something.

data/lib/resulting.rb

@@ -1,6 +1,29 @@
 require "resulting/version"
+require "resulting/resultable"
+require "resulting/helpers"
+require "resulting/handler"
+require "resulting/result"
+require "resulting/runner"
 
 module Resulting
-  class Error < StandardError; end
-  # Your code goes here...
+  class << self
+    def validate(result_or_value, &blk)
+      Resulting::Runner.run_all(result_or_value, method: :validate, &blk)
+    end
+
+    def save(result_or_value, &blk)
+      params = { method: :save }
+
+      if defined?(ActiveRecord::Base) && defined?(ActiveRecord::Rollback)
+        params[:failure_case] = -> { raise ActiveRecord::Rollback }
+        params[:wrapper] = ActiveRecord::Base.method(:transaction)
+      end
+
+      Resulting::Runner.run_until_failure(result_or_value, params, &blk)
+    end
+
+    def validate_and_save(result_or_value)
+      save(validate(result_or_value))
+    end
+  end
 end

data/lib/resulting/handler.rb

@@ -0,0 +1,17 @@
+module Resulting
+  module Handler
+    include Resulting::Helpers
+
+    def self.handle(result_or_value, wrapper: ->(&blk) { return blk.call })
+      wrapper.call do
+        result = Resulting::Result.wrap(result_or_value)
+
+        return result if result.failure?
+
+        success = yield
+
+        result.class.new(success, result.value)
+      end
+    end
+  end
+end

data/lib/resulting/helpers.rb

@@ -0,0 +1,17 @@
+module Resulting
+  module Helpers
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def Success(*args, &block) # rubocop:disable Naming/MethodName
+        Resulting::Result.success(*args, &block)
+      end
+
+      def Failure(*args, &block) # rubocop:disable Naming/MethodName
+        Resulting::Result.failure(*args, &block)
+      end
+    end
+  end
+end

data/lib/resulting/result.rb

@@ -0,0 +1,5 @@
+module Resulting
+  class Result
+    include Resultable
+  end
+end

data/lib/resulting/resultable.rb

@@ -0,0 +1,45 @@
+module Resulting
+  module Resultable
+    def self.included(base)
+      base.extend ClassMethods
+      attr_reader :success, :value
+    end
+
+    def initialize(success, value)
+      @success = success
+      @value = value.is_a?(Resulting::Resultable) ? value.value : value
+    end
+
+    def success?
+      @success
+    end
+
+    def failure?
+      !@success
+    end
+
+    def values
+      if value.is_a?(Hash)
+        value.values.flatten
+      else
+        Array(value).flatten
+      end
+    end
+
+    module ClassMethods
+      def success(value)
+        new(true, value)
+      end
+
+      def failure(value)
+        new(false, value)
+      end
+
+      def wrap(param)
+        return param if param.is_a?(Resulting::Resultable)
+
+        success(param)
+      end
+    end
+  end
+end

data/lib/resulting/runner.rb

@@ -0,0 +1,28 @@
+module Resulting
+  module Runner
+    def self.run_all(result, method:, failure_case: -> { false }, wrapper: ->(&blk) { blk.call })
+      Resulting::Handler.handle(result, wrapper: wrapper) do
+        new_result = result.values.reduce(true) do |success, v|
+          v.send(method) ? success : false
+        end
+
+        if block_given?
+          block_result = yield
+          new_result &&= block_result
+        end
+
+        new_result ? true : failure_case.call
+      end
+    end
+
+    def self.run_until_failure(result, method:, failure_case: -> { false }, wrapper: ->(&blk) { blk.call })
+      Resulting::Handler.handle(result, wrapper: wrapper) do
+        result = result.values.all?(&method)
+
+        result &&= yield if block_given?
+
+        result ? true : failure_case.call
+      end
+    end
+  end
+end

data/lib/resulting/version.rb

@@ -1,3 +1,3 @@
 module Resulting
-  VERSION = "0.0.1".freeze
+  VERSION = "0.1.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: resulting
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - John DeWyze
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-04-14 00:00:00.000000000 Z
+date: 2020-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry-byebug
@@ -93,6 +93,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".projections.json"
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
@@ -102,11 +103,17 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- TODO.md
 - bin/console
 - bin/rake
 - bin/rubocop
 - bin/setup
 - lib/resulting.rb
+- lib/resulting/handler.rb
+- lib/resulting/helpers.rb
+- lib/resulting/result.rb
+- lib/resulting/resultable.rb
+- lib/resulting/runner.rb
 - lib/resulting/version.rb
 - resulting.gemspec
 homepage: https://github.com/dewyze/resulting