power-types 0.1.2 → 0.2.0

data/.travis.yml

@@ -1,5 +1,13 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.3.1
+- 2.3.1
 before_install: gem install bundler -v 1.12.4
+deploy:
+  provider: rubygems
+  api_key:
+    secure: e5mtRDYciM2I5IxsMJDKKNSHgyQsfmAQEMCgbf1tN+SEmxeJTif0FXfA1M4vZ2y6XL7sza0Pf1hTMIqmEIh4L8tv/JxTOl6ZWkD2l8x+nn/2Hlu5mVsztsBh+qDPWPg29hbvTptOfcLHfAqIboB4L4f5nNuHeeLZQjGD7irwaVil7IntV3oG+XfD1uJzkqO9x7Xw+cN+HzACwZQ3u+XhmedCnMWJdCwai5QZAYlytxqKirYoGgS9pi4ZgAs0ptIT+aG3dG8ckCRvhDiu2iGDrv7AnG+K2MrI7O06g0676Iao1O0xTcW2Yo9uArkVXRo9L3Ghk1T5O5zCPoiF7oLiNlBkHeRGOw/+H+88NxziNaOi9BZswn2ROpFylVPrg8hDvIoOqRZfxqgnCtM2vTdOdyCcPOJgm3nhZl9OZ9aPbE3x/Fh5zXVBFT5Vwz3RV0s9uDuKa6pjphxOGb/be+ZYyPJ/uOU7Wo6Qj+lQ+/YBwbZ2wPJ2qAqb69gRBliYpSFbMsLptKw7YUYNW22yknZHGrhHlok7YDDpotUMMDJmSKUrXvBIPdqq9Y61gXLXE5QxxQkWqAFyhluDDMdIDs0PMkDBl45LvHfPJQZxp8sX+FK5ashmMPgdsDcb8DRK+LYrCHrinMkPcwIME5JeuAnb7bT0ErrtBSq8iAD8sPeI+/Q=
+  gem: power-types
+  on:
+    tags: true
+    repo: platanus/power-types

data/README.md

@@ -1,62 +1,231 @@
-# Power-Types
+# Power Types
+[![Gem Version](https://badge.fury.io/rb/power-types.svg)](https://badge.fury.io/rb/power-types) [![Build Status](https://travis-ci.org/platanus/power-types.svg?branch=master)](https://travis-ci.org/platanus/power-types) [![Coverage Status](https://coveralls.io/repos/github/platanus/power-types/badge.svg)](https://coveralls.io/github/platanus/power-types)
 
-Rails pattern enforcing types used by the Platanus team
+Rails pattern enforcing types used by the Platanus team.
 
 ## Introduction
 
-In Rails projects, Platanus encourages  to  use classes beyond models and controllers to hold the app's logic.
-These powerful types proposed are Services, Commands, Utils and Values.
+In Rails projects, Platanus encourages to use classes beyond models and controllers to hold the app's logic.
+These powerful types proposed are Services, Commands, Observers, Utils and Values.
 
-For a deeper understanding about the usage of these patterns, feel welcome to read the [related post in Platanus Blog](https://cb.platan.us/services-commands-y-otros-poderosos-patrones-en-rails) (in spanish).
-   
-The goal aimed with this gem is to go further, and not just apply this patterns over POROs (plain simple ruby classes).  The gem provides an special structure and syntax to create and run Services and Commands with ease.
+For a deeper understanding about the usage of these patterns, feel welcome to read the [related post in Platanus Blog](https://blog.platan.us/services-commands-y-otros-poderosos-patrones-en-rails) (in spanish).
+
+The goal aimed with this gem is to go further, and not just apply this patterns over POROs (plain simple ruby classes). The gem provides an special structure and syntax to create and run services, commands and more, with ease.
 
 It also creates the directory for each type, and provides generators.
 
-## Usage
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "power-types"
+```
+
+```bash
+bundle install
+```
+
+## Power types
+
+- [Services](#services)
+- [Commands](#commands)
+- [Observers](#observers)
+- [Values and Utils](#values-and-utils)
 
-### Generators
+### Services
 
 For generating services we use:
 
-    $ rails generate service MagicMakingService foo bar
+```
+$ rails generate service MyService foo bar
+```
+
+This will create the MyService class, inheriting from a base service class:
+
+```ruby
+class MyService < PowerTypes::Service.new(:foo, :bar)
+  # Service code goes here
+end
+```
+
+And its corresponding rspec file:
+
+```ruby
+require 'rails_helper'
+
+describe MyService do
+  def build(*_args)
+    described_class.new(*_args)
+  end
+
+  pending "describe what your service does here"
+end
+```
+
+The arguments get available to be used in the service class as instance variables: `@foo` and `@bar`.
+Default values for arguments are optional, and can't be defined in the generator, but manually after like this:
+
+```ruby
+class MyService < PowerTypes::Service.new(foo: "X", bar: nil)
+  # Service code goes here
+end
+```
+
+This is a way to make the argument optional. If no default value is assigned, the argument will be required, and an error raised if missing.
+
+Now, suppose you have defined the following service:
+
+```ruby
+class MagicMakingService < PowerTypes::Service.new(wizard: "Harry Potter")
+  def gandalfize(who)
+    "#{@wizard} gandalfized #{who}"
+  end
+
+  def harrypotterize(who)
+    "#{@wizard} harrypotterized #{who}"
+  end
+end
+```
+
+Then, you can use it like this:
+
+```ruby
+magic_service = MagicMakingService.new(wizard: "Gandalf")
+magic_service.gandalfize("Sauron") #=> "Gandalf gandalfized Sauron"
+
+magic_service = MagicMakingService.new
+magic_service.harrypotterize("Voldemort") #=> "Harry Potter harrypotterize Voldemort"
+```
+
+### Commands
+
+For generating commands we use:
+
+```
+$ rails generate command ExecuteSomeAction foo bar
+```
+
+This will create the ExecuteSomeAction class, inheriting from a base command class:
+
+```ruby
+class ExecuteSomeAction < PowerTypes::Command.new(:foo, :bar)
+  def perform
+    # Command code goes here
+  end
+end
+```
+
+And its corresponding rspec file:
 
-This will create the MagicMakingService class, inheriting from a base service class:
+```ruby
+require 'rails_helper'
+
+describe ExecuteSomeAction do
+  def perform(*_args)
+    described_class.for(*_args)
+  end
+
+  pending "describe what perform does here"
+end
+```
 
-    class MagicMakingService < PowerTypes::Service.new(:foo, bar: nil)
+The arguments get available to be used in the command class as instance variables: `@foo` and `@bar`.
+Default values for arguments are optional, and can't be defined in the generator, but manually after like this:
 
-The arguments get available to be used in the service class as instance variables: `@foo` and `@bar`
-Default values for arguments are optional, and can't be defined in the generator, but manually after.  In this case a `nil` value was given for `bar`.
-This is a way to make the argument optional.  If no default value is assigned, the argument will be required, and an error raised if missing.
+```ruby
+class ExecuteSomeAction < PowerTypes::Command.new(foo: "X", bar: nil)
+  def perform
+    # Command code goes here
+  end
+end
+```
 
-This generator will create its corresponding rspec file.
+This is a way to make the argument optional. If no default value is assigned, the argument will be required, and an error raised if missing.
 
+Now, suppose you have defined the following command:
 
+```ruby
+class MakeMagicTrick < PowerTypes::Command.new(:wizard, receiver: "Sauron")
+  def perform
+    "#{@wizard} enchanted #{@receiver}"
+  end
+end
+```
 
-For generating commands:
+Then, you can use it like this:
 
-    $ rails generate command MakeMagic foo bar
+```ruby
+MakeMagicTrick.for(wizard: "Gandalf") #=> "Gandalf enchanted Sauron"
+MakeMagicTrick.for(wizard: "Harry Potter", receiver: "Voldemor") #=> "Harry Portter enchanted Voldemor"
+```
 
-Which will generate the corresponding class, with the `perform` method.  This method must be implemented, and its called when the command is executed.
+> In the case of commands, we are not supposed to store or reuse the object. You just want to run it and keep the result.
 
-    class MakeMagic < PowerTypes::Command.new(:foo, bar: nil)
+### Observers
 
-And in a similar way to services, the command's spec file is also created by this generator
- 
-### Instantiate and Run
- 
-We can create service objects like this
- 
-    magic_service = MagicMakingService.new(foo: my_foo, bar: "a bar")
+For generating observers we use:
 
-And use any method the service provides
-    
-    magic_service.gandalfize(sauron)
-    magic_service.harry_potterize(voldemort)
+```
+$ rails generate observer MyModel
+```
 
-In the case of commands, we are not suposed to store or reuse the object.  You just want to run it and keep the result
-    
-    result = MakeMagic.for(foo: a_foo, bar:  "i'm bar")
+This will create the MyModelObserver class, inheriting from a base observer class:
+
+```ruby
+class MyModelObserver < PowerTypes::Observer
+  # after_save :run
+  # before_create { puts "yes, you can provide a block to work with" }
+  #
+  # def run
+  #   p object # object holds an MyModel instance.
+  # end
+end
+```
+
+It will also include the `PowerTypes::Observable` mixin in `MyModel` class:
+
+```ruby
+class MyModel < ActiveRecord::Base
+  include PowerTypes::Observable
+end
+```
+
+And the corresponding rspec file:
+
+```ruby
+require 'rails_helper'
+
+describe MyModelObserver do
+  pending "add some examples to (or delete) #{__FILE__}"
+end
+```
+
+Now, suppose you have defined the following model (with name and villian attributes) and observer:
+
+```ruby
+class Wizard < ActiveRecord::Base
+  include PowerTypes::Observable
+end
+```
+
+```ruby
+class WizardObserver < PowerTypes::Observer
+  after_create :kill_villain
+
+  def kill_villain
+    p "#{object.name} have killed #{object.villian}"
+  end
+end
+```
+
+Then, you can use it like this:
+
+```ruby
+Wizard.create!(name: "Gandalf", villian: "Sauron") #=> This action will trigger the method kill_villian defined in the WizardObserver's after_create callback.
+```
+
+> As you can guess, `object` holds the Wizard instance.
 
 ### Values and Utils
 
@@ -65,26 +234,38 @@ This two types do not have generators.
 Values are just simple Ruby classes, but watch out to keep them in the Values directory!
 
 Utils should be defined as a module.  There you define the independent but related functions.  Use the extend self pattern to call them directly after the module name.
+
 ```ruby
 module MagicTricks
-extend self
-    
-    def dissappear(object)
-        #blah blah
-    end
-    
-    def shrink(children)
-        #bleh bleeh
-    end
-
-    def shuffle(cards)
-        #blaah
-    end  
+  extend self
+
+  def dissappear(object)
+    #blah blah
+  end
+
+  def shrink(children)
+    #bleh bleeh
+  end
+
+  def shuffle(cards)
+    #blaah
+  end
+end  
 ```
+
 Example of calling a Util function:
 
-    MagicTricks.dissapear(rabbit)
+```ruby
+MagicTricks.dissapear(rabbit)
+```
+
+## Contributing
 
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
 
 ## Credits
 
@@ -96,4 +277,4 @@ Power-Types is maintained by [platanus](http://platan.us).
 
 ## License
 
-Power-Types is © 2016 Platanus, S.p.A. It is free software and may be redistributed under the terms specified in the LICENSE file.
+Power Types is © 2016 Platanus, S.p.A. It is free software and may be redistributed under the terms specified in the LICENSE file.

data/lib/generators/power_types/init_generator.rb

@@ -4,6 +4,7 @@ module PowerTypes
     def create_folders
       empty_directory "app/commands/"
       empty_directory "app/services/"
+      empty_directory "app/observers/"
       empty_directory "app/utils/"
       empty_directory "app/values/"
     end

data/lib/generators/rails/observer_generator.rb

@@ -0,0 +1,18 @@
+module Rails
+  class ObserverGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path("../templates", __FILE__)
+
+    desc "This generator creates a new observer at app/observers"
+    def create_observer
+      template('observer.rb', "app/observers/#{file_name.underscore}_observer.rb")
+      template('observer_spec.rb', "spec/observers/#{file_name.underscore}_observer_spec.rb")
+    end
+
+    def include_observable_mixin
+      line = "class #{class_name} < ActiveRecord::Base"
+      gsub_file "app/models/#{file_name.underscore}.rb", /(#{Regexp.escape(line)})/mi do |match|
+        "#{match}\n  include PowerTypes::Observable"
+      end
+    end
+  end
+end

data/lib/generators/rails/templates/observer.rb

@@ -0,0 +1,8 @@
+class <%= class_name %>Observer < PowerTypes::Observer
+  # after_save :run
+  # before_create { puts "yes, you can provide a block to work with" }
+  #
+  # def run
+  #   p object # object holds an <%= class_name %> instance.
+  # end
+end

data/lib/generators/rails/templates/observer_spec.rb

@@ -0,0 +1,5 @@
+require 'rails_helper'
+
+describe <%= class_name %>Observer do
+  pending "add some examples to (or delete) #{__FILE__}"
+end

data/lib/power_types.rb

@@ -1,6 +1,10 @@
 require "power_types/version"
+require "power_types/util"
 require "power_types/patterns/service"
 require "power_types/patterns/command"
+require "power_types/patterns/observer/observable"
+require "power_types/patterns/observer/observer"
+require "power_types/patterns/observer/trigger"
 
 module PowerTypes
 end

data/lib/power_types/patterns/observer/observable.rb

@@ -0,0 +1,39 @@
+module PowerTypes
+  module Observable
+    @@observable_disabled = false
+
+    def self.observable_disabled=(_value)
+      @@observable_disabled = _value
+    end
+
+    def self.observable_disabled?
+      @@observable_disabled
+    end
+
+    def self.included(_klass)
+      _klass.extend ClassMethods
+    end
+
+    PowerTypes::Util::OBSERVABLE_EVENTS.each do |event|
+      define_method("_run_#{event}_callbacks") do |&_block|
+        self.class.observers.each { |o| o.trigger(:before, event, self) }
+        result = super &_block
+        self.class.observers.each { |o| o.trigger(:after, event, self) }
+        result
+      end
+    end
+
+    module ClassMethods
+      def observers
+        return [] if PowerTypes::Observable.observable_disabled?
+        @observers ||= [].tap do |array|
+          begin
+            array << Kernel.const_get("#{self}Observer")
+          rescue NameError
+            # could not find observer
+          end
+        end
+      end
+    end
+  end
+end

data/lib/power_types/patterns/observer/observer.rb

@@ -0,0 +1,38 @@
+module PowerTypes
+  class Observer
+    attr_reader :object
+
+    PowerTypes::Util::OBSERVABLE_EVENTS.each do |event|
+      PowerTypes::Util::OBSERVABLE_TYPES.each do |type|
+        define_singleton_method("#{type}_#{event}") do |args = nil, &_block|
+          add_trigger(type, event, *args, &_block)
+        end
+      end
+    end
+
+    def self.trigger(_type, _event, _object)
+      triggers.select { |t| t.type == _type && t.event == _event }.each do |trigger|
+        trigger.call(new(_object))
+      end
+    end
+
+    def self.add_trigger(_type, _event, _handler = nil, _options = {}, &_block)
+      triggers << PowerTypes::Trigger.new(
+        _type,
+        _event,
+        (_handler || _block),
+        _options
+      )
+
+      triggers.last
+    end
+
+    def self.triggers
+      @triggers ||= []
+    end
+
+    def initialize(_object)
+      @object = _object
+    end
+  end
+end