logicum 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ab68d2f62115c7415f63a168a7aeea0ec5290b7cde49569461ea436757584b1
-  data.tar.gz: 1c7fecdd88c64abafa7a13fd7f1ddf820be6efa398cdfdf83b1953d337e6eb8f
+  metadata.gz: 98f50316e65e143565d4860ded87ea42f6c15710e9366ad3d461de939090ba9c
+  data.tar.gz: ec3ac7c1b95508eabeb1b65a6f893b2b952add91d306ba96701810f90ddeb102
 SHA512:
-  metadata.gz: 8e562354af41440cfb932d8a4fcd86dc6f0e670b455a37962fe81b441707e21f1ed64ae7accc4abfe8581ad17c850b0f63b4c76274dc44b5c38a8afa31bc6206
-  data.tar.gz: 101c01166953568e1e8cce92e470d8c98ef65dc07796a6da4fe7204a9c921ea8020868eea8b881dcdae11cda41b0de857c190e953ff49c548293b2ba53894eae
+  metadata.gz: e193993fec01cbf098e429750d2fe0a102c7742a547cb674520986e34abc5c686781d009dbd832ef105b745cbc2e03db614fe3e829595f306b09373c73af6a93
+  data.tar.gz: ad952edbb3aa6cd4f17ea7f5e8057890e7e22299b53b32866700be6c3f5c793c6ab9c31418511ad4009e9db4cae0ed0d864384616d5dc0702914bb51a58072b3

data/.gitignore

@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+Gemfile.lock

data/README.md

@@ -1,8 +1,140 @@
 # Logicum
 
-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/logicum`. To experiment with that code, run `bin/console` for an interactive prompt.
+A simple, consistent interface for executing a unit of business logic.
+
+
+## Usage
+
+In a nutshell:
+
+```ruby
+class DoSomething
+  # Turn your object into an interactor.
+  include Logicum::Interactor
+
+  # Declare any values available on the result of call().
+  # You must set these instance variables in your call() method.
+  provides :foo, :bar
+
+  # Encapsulate your logic in a call() method.
+  #
+  # The call() method will not raise an error if your logic raises an error.
+  # Instead the result will be a failure and the error message will be available.
+  #
+  # Returns a result object which responds to :success?, :failure?, and :error.
+  def call(params:)
+    # do stuff
+
+    # Set the variables to provide on the result.
+    @foo = params[:foo] + 3
+    @bar = 153
+  end
+end
+
+# And you use it like this:
+
+result = DoSomething.new.call params: {foo: 42}
+result.success?  # true
+result.foo       # 45
+result.bar       # 153
+```
+
+If you don't need to pass arguments into your initializer, you can send `:call` to the class instead:
+
+```ruby
+result = DoSomething.call params: {foo: 42}
+```
+
+The result is successful unless an exception is raised.  You can also explicitly make the result a failure using the `fail!` method, which takes an optional string message.
+
+```ruby
+class DoSomething
+  include Logicum::Interactor
+
+  def call(foo:)
+    fail! 'This went wrong'
+  end
+end
+
+result = DoSomething.call 153
+result.failure?  # true
+resut.error      # 'This went wrong'
+```
+
+## Purpose
+
+The motivation was to move all business logic out of Rails controllers.
+
+Instead of this:
+
+```ruby
+class UsersController < ApplicationController
+
+  def create
+    @user = User.new user_params
+
+    if @user.save
+      redirect_to @user
+    else
+      render :edit
+    end
+  end
+
+end
+```
+
+You can write this:
+
+```ruby
+class AddUser
+  include Logicum::Interactor
+
+  provides :user
+
+  def call(params)
+    @user = User.new params
+    @user.save!
+  end
+end
+
+
+class UsersController < ApplicationController
+
+  def create
+    result = AddUser.call user_params
+
+    if result.success?
+      redirect_to result.user
+    else
+      @user = result.user
+      render :edit
+    end
+  end
+
+end
+```
+
+This is more code, so why bother?
+
+The controller no longer has any business logic in it.  It simply mediates between HTTP and your domain.  We have separated concerns, reduced coupling, and increased cohesion.
+
+It's a consistent interface.
+
+If you situate all your business operations in a directory, e.g. `app/interactors/` or `app/services/`, you can see at a glance everything your application does.
+
+The more complicated your logic gets, the more appealing this approach is.  The example above is simple and therefore not especially compelling :)  However as your application grows and you add business logic – e.g. sending emails, updating analytics, triggering background jobs – you can do it without cluttering up your controllers with details they should not know about.
+
+
+## Inspiration
+
+Although the command object / service object pattern has been around for ages I have never felt it was worthwhile for my applications.  However recently these three libraries persuaded me otherwise.
+
+- GoCardless's [Coach](https://github.com/gocardless/coach)
+- CollectiveIdea's [Interactor](https://github.com/collectiveidea/interactor)
+- Hanami's [Interactor](https://github.com/hanami/utils/blob/a74304af5bb69f6a561aad2718943388fac30782/lib/hanami/interactor.rb)
+
+I wanted something even lighter weight, providing just enough structure for the benefits to materialise, so I wrote my own.
 
-TODO: Delete this and the text above, and describe your gem
 
 ## Installation
 
@@ -20,19 +152,6 @@ Or install it yourself as:
 
     $ gem install logicum
 
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/airblade/logicum.
 
 ## License
 

data/lib/logicum.rb

@@ -1,6 +1,5 @@
-require "logicum/version"
+require 'logicum/interactor'
+require 'logicum/version'
 
 module Logicum
-  class Error < StandardError; end
-  # Your code goes here...
 end

data/lib/logicum/class_attribute.rb

@@ -0,0 +1,42 @@
+# https://github.com/hanami/utils/blob/master/lib/hanami/utils/class_attribute.rb
+
+require 'set'
+
+module Logicum
+  module ClassAttribute
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+
+    module ClassMethods
+      def class_attribute(*attributes)
+        singleton_class.class_eval do
+          attr_accessor *attributes
+        end
+
+        class_attributes.merge attributes
+      end
+
+      protected
+
+      def inherited(subclass)
+        class_attributes.each do |attribute|
+          value = send(attribute).dup
+          subclass.class_attribute attribute
+          subclass.send "#{attribute}=", value
+        end
+
+        super
+      end
+
+      private
+
+      def class_attributes
+        @class_attributes ||= Set.new
+      end
+    end
+
+  end
+end

data/lib/logicum/errors.rb

@@ -0,0 +1,12 @@
+module Logicum
+
+  Error = Class.new StandardError
+
+  # The business object does not implement a call() instance method.
+  MissingCallError = Class.new Error
+
+  # The business object declares that it provides a value, but it was
+  # not set in the call() instance method.
+  ProvisionError = Class.new Error
+
+end

data/lib/logicum/interactor.rb

@@ -0,0 +1,75 @@
+require 'logicum/class_attribute'
+require 'logicum/result'
+require 'logicum/errors'
+
+module Logicum
+  module Interactor
+
+    def self.included(base)
+      base.extend ClassMethods
+      base.prepend CallInterface
+    end
+
+
+    module ClassMethods
+      def self.extended(base)
+        base.class_eval do
+          include ClassAttribute
+          class_attribute :provisions
+          self.provisions = []
+        end
+      end
+
+      def provides(*instance_variable_names)
+        provisions.concat instance_variable_names
+      end
+
+      # Shortcut for caller if nothing needed in intializer.
+      # For example:
+      #
+      #     AddUser.call foo: 'bar'
+      #
+      # is equivalent to:
+      #
+      #     AddUser.new.call foo: 'bar'
+      def call(*args, &block)
+        new.call *args, &block
+      end
+    end
+
+
+    module CallInterface
+      def call(*)
+        raise MissingCallError unless defined? super
+
+        @__result__ = Result.new
+
+        begin
+          super
+        rescue StandardError => e
+          @__result__.fail! e.message
+        end
+
+        self.class.provisions.each do |attr|
+          ivar_name = "@#{attr}"
+          if instance_variable_defined? ivar_name
+            val = instance_variable_get ivar_name
+            @__result__.define_singleton_method(attr) { val }
+          else
+            # Calling code must ensure instance variables to provide are
+            # set before any code which could raise an exception.
+            raise ProvisionError, "#{ivar_name} was not set in call() method"
+          end
+        end
+
+        @__result__
+      end
+    end
+
+
+    def fail!(message = '')
+      @__result__.fail! message
+    end
+
+  end
+end

data/lib/logicum/result.rb

@@ -0,0 +1,30 @@
+module Logicum
+  module Interactor
+
+    class Result
+      def initialize
+        @success = true
+        @error = ''
+      end
+
+      def success?
+        @success
+      end
+
+      def failure?
+        !success?
+      end
+
+      def fail!(message = '')
+        @success = false
+        @error = message
+      end
+
+      def error
+        @error.dup
+      end
+    end
+
+  end
+end
+

data/lib/logicum/version.rb

@@ -1,3 +1,3 @@
 module Logicum
-  VERSION = "0.0.1"
+  VERSION = '1.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logicum
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Andy Stewart
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-31 00:00:00.000000000 Z
+date: 2019-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -67,6 +67,10 @@ files:
 - bin/console
 - bin/setup
 - lib/logicum.rb
+- lib/logicum/class_attribute.rb
+- lib/logicum/errors.rb
+- lib/logicum/interactor.rb
+- lib/logicum/result.rb
 - lib/logicum/version.rb
 - logicum.gemspec
 homepage: https://github.com/airblade/logicum
@@ -88,7 +92,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.1
+rubyforge_project: 
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: Simplifies writing a unit of business logic.