voltage 0.1.0

data/README.md

@@ -0,0 +1,299 @@
+# Voltage
+
+[![Tests](https://github.com/fnando/voltage/actions/workflows/ruby-tests.yml/badge.svg)](https://github.com/fnando/voltage/actions/workflows/ruby-tests.yml)
+[![Gem](https://img.shields.io/gem/v/voltage.svg)](https://rubygems.org/gems/voltage)
+[![Gem](https://img.shields.io/gem/dt/voltage.svg)](https://rubygems.org/gems/voltage)
+
+A simple observer implementation on POROs (Plain Old Ruby Object) and
+ActiveRecord objects.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "voltage"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install voltage
+
+## Usage
+
+You can use Voltage with PORO (Plain Old Ruby Object) and ActiveRecord.
+
+### Plain Ruby
+
+All you have to do is including the `Voltage` module. Then you can add listeners
+and trigger events.
+
+```ruby
+class Status
+  include Voltage
+
+  def ready!
+    emit(:ready)
+  end
+end
+
+status = Status.new
+status.before(:ready) { puts "Before the ready event!" }
+status.on(:ready) { puts "I'm ready!" }
+status.after(:ready) { puts "After the ready event!" }
+status.ready!
+#=> Before the ready event!
+#=> I'm ready!
+#=> After the ready event!
+```
+
+You can also pass objects that implement methods like `before_*`, `on_*` and
+`after_*`.
+
+```ruby
+class MyListener
+  def before_ready
+    puts "Before the ready event!"
+  end
+
+  def on_ready
+    puts "I'm ready!"
+  end
+
+  def after_ready
+    puts "After the ready event!"
+  end
+end
+
+Status.new
+  .add_listener(MyListener.new)
+  .ready!
+#=> Before the ready event!
+#=> I'm ready!
+#=> After the ready event!
+```
+
+Executed blocks don't switch context. You always have to emit the object you're
+interested in. The follow example uses `emit(:output, self)` to send the
+`Contact` instance to all listeners.
+
+```ruby
+class Contact
+  include Voltage
+
+  attr_reader :name, :email
+
+  def initialize(name, email)
+    @name, @email = name, email
+  end
+
+  def output!
+    emit(:output, self)
+  end
+end
+
+contact = Contact.new('John Doe', 'john@example.org')
+contact.on(:output) {|contact| puts contact.name, contact.email }
+contact.output!
+#=> John Doe
+#=> john@example.org
+```
+
+You can provide arguments while emitting a voltage:
+
+```ruby
+class Arguments
+  include Voltage
+end
+
+class MyListener
+  def on_args(a, b)
+    puts a, b
+  end
+end
+
+Arguments.new
+  .on(:args) {|a, b| puts a, b }
+  .add_listener(MyListener.new)
+  .emit(:args, 1, 2)
+```
+
+### ActiveRecord
+
+You can use Voltage with ActiveRecord, which will give you some default events
+like `:create`, `:update`, `:remove` and `:validation`.
+
+```ruby
+class Thing < ActiveRecord::Base
+  include Voltage.active_record
+
+  validates_presence_of :name
+end
+
+thing = Thing.new(:name => "Stuff")
+thing.on(:create) {|thing| puts thing.updated_at, thing.name }
+thing.on(:update) {|thing| puts thing.updated_at, thing.name }
+thing.on(:remove) {|thing| puts thing.destroyed? }
+thing.on(:validation) {|thing| p thing.errors.full_messages }
+
+thing.save!
+#=> 2013-01-26 10:32:39 -0200
+#=> Stuff
+
+thing.update_attributes(:name => "Updated stuff")
+#=> 2013-01-26 10:33:11 -0200
+#=> Updated stuff
+
+thing.update_attributes(:name => nil)
+#=> ["Name can't be blank"]
+
+thing.destroy
+#=> true
+```
+
+These are the available events:
+
+- `before(:create)`: triggered before creating the record (record is valid).
+- `on(:create)`: triggered after `before(:create)` event.
+- `after(:create)`: triggered after the `on(:create)` event.
+- `before(:update)`: triggered before updating the record (record is valid).
+- `on(:update)`: triggered when the `before(:update)` event.
+- `after(:update)`: triggered after the `on(:update)` event.
+- `before(:remove)`: triggered before removing the record.
+- `on(:remove)`: triggered after the `before(:remove)`.
+- `after(:remove)`: triggered after the `on(:remove)` event.
+- `before(:validation)`: triggered before validating record.
+- `on(:validation)`: triggered when record is invalid.
+- `after(:validation)`: triggered after validating record.
+
+### Inside Rails
+
+Although there's no special code for Rails, here's just an example of how you
+can use it:
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = User.new(user_params)
+
+    Signup.new(@user)
+      .on(:success) { redirect_to login_path, notice: 'Welcome to MyApp!' }
+      .on(:failure) { render :new }
+      .call
+  end
+end
+```
+
+If you're using plain ActiveRecord, just do something like the following:
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = User.new(user_params)
+    @user
+      .on(:create) { redirect_to login_path, notice: 'Welcome to MyApp!' }
+      .on(:validation) { render :new }
+      .save
+  end
+end
+```
+
+### Voltage::Call
+
+You can include `Voltage.call` instead, so you can have a common interface for
+your observable object. This will add the `.call()` method to the target class,
+which will delegate attributes to the observable's `initialize` method and call
+its `call` method.
+
+```ruby
+class Contact
+  include Voltage.call
+
+  attr_reader :name, :email
+
+  def initialize(name, email)
+    @name, @email = name, email
+  end
+
+  def call
+    emit(:output, self)
+  end
+end
+
+Contact.call('John', 'john@example.com') do |o|
+  o.on(:output) {|contact| puts contact }
+end
+```
+
+Notice that you don't have to explicit call the instance's `call` method;
+`Contact.call` will initialize the object with all the provided parameters and
+call `Contact#call` after the block has been executed.
+
+### Testing
+
+`Voltage::Mock` can be helpful for most test situations where you don't want to
+bring other mock libraries.
+
+```ruby
+require "voltage/mock"
+
+class SomeTest < Minitest::Test
+  def test_some_test
+    mock = Voltage::Mock.new
+
+    # Using listener
+    sum = Sum.new
+    sum.add_listener(mock)
+
+    # Calling `mock.on(event_name)` is required because
+    # the handler doesn't receive the event name, just the
+    # arguments.
+    sum = Sum.new
+    sum.on(:result, &mock.on(:result))
+
+    # Using with Voltage.call
+    Sum.call(1, 2, &mock)
+
+    assert mock.received?(:result)
+    assert mock.received?(:result, times: 1)
+    assert mock.received?(:result, with: [3])
+    assert mock.received?(:result, with: ->(result) { result == 3 } )
+  end
+end
+
+```
+
+## 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
+
+## License
+
+Copyright (c) 2013 Nando Vieira
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sub-license, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rubocop/rake_task"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/examples/activerecord_model.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "voltage"
+require "active_record"
+
+ActiveRecord::Base.establish_connection(
+  adapter: "sqlite3",
+  database: ":memory:"
+)
+
+ActiveRecord::Schema.define(version: 0) do
+  create_table :things do |t|
+    t.string :name
+    t.timestamps null: false
+  end
+end
+
+class Thing < ActiveRecord::Base
+  include Voltage::ActiveRecord
+
+  validates_presence_of :name
+end
+
+thing = Thing.new(name: "Stuff")
+thing.on(:create) {|model| puts model.updated_at, model.name }
+thing.on(:update) {|model| puts model.updated_at, model.name }
+thing.on(:remove) {|model| puts model.destroyed? }
+thing.on(:validation) {|model| p model.errors.full_messages }
+
+thing.save!
+#=> 2013-01-26 10:32:39 -0200
+#=> Stuff
+
+thing.update_attributes(name: "Updated stuff")
+#=> 2013-01-26 10:33:11 -0200
+#=> Updated stuff
+
+thing.update_attributes(name: nil)
+#=> ["Name can"t be blank"]
+
+thing.destroy
+#=> true

data/examples/arguments.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "voltage"
+
+class Arguments
+  include Voltage
+end
+
+class MyListener
+  def on_args(a, b)
+    puts a, b
+  end
+end
+
+args = Arguments.new
+args.on(:args) {|a, b| puts a, b }
+args.listeners << MyListener.new
+args.emit(:args, 1, 2)

data/examples/block_context.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "voltage"
+
+class Contact
+  include Voltage
+
+  attr_reader :name, :email
+
+  def initialize(name, email)
+    @name = name
+    @email = email
+  end
+
+  def output!
+    emit(:output, self)
+  end
+end
+
+contact = Contact.new("John Doe", "john@example.org")
+contact.on(:output) {|c| puts c.name, c.email }
+contact.output!

data/examples/blocks.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "voltage"
+
+class Status
+  include Voltage
+
+  def ready!
+    emit(:ready)
+  end
+end
+
+status = Status.new
+status.before(:ready) { puts "Before the ready event!" }
+status.on(:ready) { puts "I'm ready!" }
+status.after(:ready) { puts "After the ready event!" }
+status.ready!

data/examples/call.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "voltage"
+
+class Contact
+  include Voltage.call
+
+  attr_reader :name, :email
+
+  def initialize(name, email)
+    @name = name
+    @email = email
+  end
+
+  def call
+    emit(:output, self)
+  end
+end
+
+Contact.call("John", "john@example.com") do |o|
+  o.on(:output) {|contact| puts contact.name }
+end

data/examples/chain.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "voltage"
+require "active_record"
+
+ActiveRecord::Base.establish_connection(
+  adapter: "sqlite3",
+  database: ":memory:"
+)
+
+ActiveRecord::Schema.define(version: 0) do
+  create_table :things do |t|
+    t.string :name
+    t.timestamps null: false
+  end
+end
+
+class Thing < ActiveRecord::Base
+  include Voltage.active_record
+
+  validates_presence_of :name
+end
+
+class MyListener
+  %i[validation update create remove].each do |type|
+    class_eval <<-RUBY, __FILE__, __LINE__ + 1
+      def before_#{type}(thing); puts __method__; end
+      def on_#{type}(thing); puts __method__; end
+      def after_#{type}(thing); puts __method__; end
+    RUBY
+  end
+end
+
+puts "\n=== Creating valid record"
+thing = Thing.new(name: "Stuff")
+thing.listeners << MyListener.new
+thing.save
+
+puts "\n=== Creating invalid record"
+thing = Thing.new(name: nil)
+thing.listeners << MyListener.new
+thing.save
+
+puts "\n=== Updating valid record"
+thing = Thing.create(name: "Stuff")
+thing.listeners << MyListener.new
+thing.update_attributes(name: "Updated stuff")
+
+puts "\n=== Updating invalid record"
+thing = Thing.create!(name: "Stuff")
+thing.listeners << MyListener.new
+thing.update_attributes(name: nil)
+
+puts "\n=== Removing record"
+thing = Thing.create(name: "Stuff")
+thing.listeners << MyListener.new
+thing.destroy

data/examples/listener.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "voltage"
+
+class Status
+  include Voltage
+
+  def ready!
+    emit(:ready)
+  end
+end
+
+class MyListener
+  def before_ready
+    puts "Before the ready event!"
+  end
+
+  def on_ready
+    puts "I'm ready!"
+  end
+
+  def after_ready
+    puts "After the ready event!"
+  end
+end
+
+status = Status.new
+status.listeners << MyListener.new
+status.ready!

data/lib/voltage/extensions/active_record.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Voltage
+  def self.active_record
+    Extensions::ActiveRecord
+  end
+
+  module Extensions
+    module ActiveRecord
+      def self.included(base)
+        base.class_eval do
+          include Voltage
+
+          around_create     :around_create_signal
+          around_save       :around_save_signal
+          around_destroy    :around_destroy_signal
+          before_validation :before_validation_signal
+          after_validation  :after_validation_signal
+        end
+      end
+
+      private def around_create_signal
+        emit_signal(:before, :create, self)
+        yield
+        return unless persisted?
+
+        emit_signal(:on, :create, self)
+        emit_signal(:after, :create, self)
+      end
+
+      private def around_save_signal
+        if new_record?
+          yield
+          return
+        end
+
+        emit_signal(:before, :update, self)
+        yield
+        emit_signal(:on, :update, self)
+        emit_signal(:after, :update, self)
+      end
+
+      private def around_destroy_signal
+        emit_signal(:before, :remove, self)
+        yield
+        emit_signal(:on, :remove, self)
+        emit_signal(:after, :remove, self)
+      end
+
+      private def before_validation_signal
+        emit_signal(:before, :validation, self)
+      end
+
+      private def after_validation_signal
+        emit_signal(:on, :validation, self) if errors.any?
+        emit_signal(:after, :validation, self)
+      end
+    end
+  end
+end

data/lib/voltage/extensions/call.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Voltage
+  def self.call
+    Extensions::Call
+  end
+
+  module Extensions
+    module Call
+      def self.included(target)
+        target.include(Voltage)
+        target.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def call(*args, **kwargs)
+          new(*args, **kwargs).tap do |instance|
+            yield(instance) if block_given?
+            instance.call
+          end
+        end
+      end
+    end
+  end
+end

data/lib/voltage/listener.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Voltage
+  class Listener
+    def initialize(context, type, event, &block)
+      @context = context
+      @type = type
+      @event = event
+      @block = block
+      @event_method = :"#{@type}_#{@event}"
+    end
+
+    def method_missing(method_name, *args)
+      return super unless respond_to_missing?(method_name, false)
+
+      @block.call(*args)
+    end
+
+    def to_s
+      "<#{self.class} event: #{@event_method}>"
+    end
+
+    def respond_to_missing?(method_name, _include_private)
+      method_name == @event_method
+    end
+  end
+end

data/lib/voltage/mock.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Voltage
+  class Mock
+    def calls
+      @calls ||= []
+    end
+
+    def method_missing(name, *args)
+      return super unless respond_to_missing?(name)
+
+      calls << {event: name.to_s.gsub(/^on_/, "").to_sym, args: args}
+    end
+
+    def respond_to_missing?(name, _include_all = false)
+      name =~ /^on_/
+    end
+
+    def received?(event, options = {})
+      received_event?(event, options[:times] || -1) &&
+        received_with?(event, options[:with])
+    end
+
+    def to_proc
+      proc {|action| action.add_listener(self) }
+    end
+
+    def on(event)
+      proc {|*args| calls << {event: event, args: args} }
+    end
+
+    private def received_event?(event, count)
+      received_calls = calls.count {|call| call[:event] == event }
+
+      return received_calls.nonzero? if count == -1
+
+      received_calls == count
+    end
+
+    private def received_with?(event, args)
+      return true unless args
+
+      calls.any? do |call|
+        next unless call[:event] == event
+        next args.call(call[:args]) if args.is_a?(Proc)
+
+        args == call[:args]
+      end
+    end
+  end
+end

data/lib/voltage/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Voltage
+  VERSION = "0.1.0"
+end