u-observers 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c90f3338948cf8db02bdb1a882e3191adfd52f106fc2b4c1acf873447abd82a
-  data.tar.gz: 2db659fbaee101e1af2838bdb89dc85838f0e9686d14fe14fd9782fc568ee1f6
+  metadata.gz: 5098d44090f611866c96aa4005c6475742972a9a986dbbcd5618753932b33817
+  data.tar.gz: 8b18f175cc5ff7fd1aae8e34302be62a1f295a151231c62e253d4b984d0225b8
 SHA512:
-  metadata.gz: 674b8dabdc6cfca0a982c1f72582bf1fcaab34ead0f0de29d4975cc62e164c13bbded5e6118152951584fb5855b6c539510ca393b36f9cf56622bf663d7b22e2
-  data.tar.gz: ff1e33f5029a40745172c7196d7e21552e8f4d534c71f057bf5643e3262fe8fa243fb55219eed352195a09abc51c337476f9f8bfcd5bce5f61cee416c2ec8de7
+  metadata.gz: e51002b6af05c7aba17eff30ba962d1d726ce9e169ae19c8a71626c035daf7c1e4e6da727c74f73c06c46ad0f5b1faaad1d1248df018ada97aa123a613e1dedf
+  data.tar.gz: 20972cd57db02b9a25905896af9429a597cfb22e951fe73a3af6346962cd1f3574df30c241b7aa9ef3a99c502097ad0a7d75210a33227a98c6d3435371c8bb03

data/README.md

@@ -35,6 +35,9 @@ Because of this issue, I decided to create a gem that encapsulates the pattern w
 - [Compatibility](#compatibility)
   - [Usage](#usage)
     - [Passing a context for your observers](#passing-a-context-for-your-observers)
+    - [Passing data when performing observers](#passing-data-when-performing-observers)
+    - [What is a `Micro::Observers::Event`?](#what-is-a-microobserversevent)
+    - [Passing a callable as an observer](#passing-a-callable-as-an-observer)
     - [Calling the observers](#calling-the-observers)
     - [Notifying observers without marking them as changed](#notifying-observers-without-marking-them-as-changed)
     - [ActiveRecord and ActiveModel integrations](#activerecord-and-activemodel-integrations)
@@ -57,11 +60,12 @@ gem 'u-observers'
 
 | u-observers | branch  | ruby     | activerecord  |
 | ----------- | ------- | -------- | ------------- |
-| 1.0.0       | main    | >= 2.2.0 | >= 3.2, < 6.1 |
+| 2.0.0       | main    | >= 2.2.0 | >= 3.2, < 6.1 |
+| 1.0.0       | v1.x    | >= 2.2.0 | >= 3.2, < 6.1 |
 
 > **Note**: The ActiveRecord isn't a dependency, but you could add a module to enable some static methods that were designed to be used with its [callbacks](https://guides.rubyonrails.org/active_record_callbacks.html).
 
-[⬆️ Back to Top](#table-of-contents-)
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
 
 ## Usage
 
@@ -102,8 +106,8 @@ end
 order = Order.new
 #<Order:0x00007fb5dd8fce70 @code="X0o9yf1GsdQFvLR4", @status=:draft>
 
-order.observers.attach(OrderEvents) # attaching multiple observers. e.g. observers.attach(A, B, C)
-# <#Micro::Observers::Manager @subject=#<Order:0x00007fb5dd8fce70> @subject_changed=false @subscribers=[OrderEvents]
+order.observers.attach(OrderEvents)          # attaching multiple observers. e.g. observers.attach(A, B, C)
+# <#Micro::Observers::Set @subject=#<Order:0x00007fb5dd8fce70> @subject_changed=false @subscribers=[OrderEvents]
 
 order.canceled?
 # false
@@ -114,6 +118,15 @@ order.cancel!
 
 order.canceled?
 # true
+
+order.observers.detach(OrderEvents)          # detaching multiple observers. e.g. observers.detach(A, B, C)
+# <#Micro::Observers::Set @subject=#<Order:0x00007fb5dd8fce70> @subject_changed=false @subscribers=[]
+
+order.canceled?
+# true
+
+order.observers.subject_changed!
+order.observers.notify(:canceled) # nothing will happen, because there are no observers attached.
 ```
 
 **Highlights of the previous example:**
@@ -131,12 +144,14 @@ order.observers.notify
 # ArgumentError (no events (expected at least 1))
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
 
 ### Passing a context for your observers
 
 To pass a context (any kind of Ruby object) for one or more observers, you will need to use the `context:` keyword as the last argument of the `#attach` method.
 
+When the observer method receives two arguments, the first one will be the subject, and the second one an instance of `Micro::Observers::Event`.
+
 ```ruby
 class Order
   include Micro::Observers
@@ -149,19 +164,102 @@ class Order
 end
 
 module OrderEvents
-  def self.canceled(order, context)
-    puts "The order #(#{order.code}) has been canceled. (from: #{context[:from]})"
+  def self.canceled(order, event)
+    puts "The order #(#{order.object_id}) has been canceled. (from: #{event.context[:from]})" # event.ctx is an alias for event.context
   end
 end
 
 order = Order.new
-order.observers.attach(OrderEvents, context: { from: 'example #2' ) # attaching multiple observers. e.g. observers.attach(A, B, context: {hello: :world})
+order.observers.attach(OrderEvents, context: { from: 'example #2' }) # attaching multiple observers. e.g. observers.attach(A, B, context: {hello: :world})
 order.cancel!
 # The message below will be printed by the observer (OrderEvents):
 # The order #(70196221441820) has been canceled. (from: example #2)
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
+
+### Passing data when performing observers
+
+The [`event context`](#passing-a-context-for-your-observers) is a value that is stored when you attach your observer. But sometimes, will be useful to send some additional data when broadcasting an event to the observers.
+
+```ruby
+class Order
+  include Micro::Observers
+end
+
+module OrderHandler
+  def self.changed(order, event)
+    puts "The order #(#{order.object_id}) received the number #{event.data} from #{event.ctx[:from]}."
+  end
+end
+
+order = Order.new
+order.observers.attach(OrderHandler, context: { from: 'example #3' })
+order.observers.subject_changed!
+order.observers.notify(:changed, data: 1)
+# The message below will be printed by the observer (OrderHandler):
+# The order #(70196221441820) received the number 1 from example #3.
+```
+
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
+
+### What is a `Micro::Observers::Event`?
+
+The `Micro::Observers::Event` is the event payload. Follow below all of its properties:
+
+- `#name` will be the broadcasted event.
+- `#subject` will be the observed subject.
+- `#context` will be [the context data](#passing-a-context-for-your-observers) that was attached to the observer.
+- `#data` will be [the value that was passed to the observers' notification](#passing-data-when-performing-observers).
+
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
+
+### Passing a callable as an observer
+
+The `observers.on()` method enables you to attach callable as observers. It could receive three options:
+1. `:event` that will be notified
+2. `:call` with the callable object.
+3. `:with` (optional) it can define the value which will be used as the callable object's argument. So, if it receives a `Proc` a `Micro::Observers::Event` instance will be passed to it and the argument will be defined as the `Proc` output. But if this option wasn't be defined, the `Micro::Observers::Event` instance will be its argument.
+
+```ruby
+class Person
+  include Micro::Observers
+
+  attr_reader :name
+
+  def initialize(name)
+    @name = name
+  end
+
+  def name=(new_name)
+    observers.subject_changed(new_name != @name)
+
+    return unless observers.subject_changed?
+
+    @name = new_name
+
+    observers.notify(:name_has_been_changed)
+  end
+end
+
+PrintPersonName = -> (data) do
+  puts("Person name: #{data.fetch(:person).name}, number: #{data.fetch(:number)}")
+end
+
+person = Person.new('Rodrigo')
+
+person.observers.on(
+  event: :name_has_been_changed,
+  call: PrintPersonName,
+  with: -> event { {person: event.subject, number: rand} }
+)
+
+person.name = 'Serradura'
+# The message below will be printed by the observer (PrintPersonName):
+# Person name: Serradura, number: 0.5018509191706862
+```
+
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
 
 ### Calling the observers
 
@@ -184,13 +282,13 @@ OrderCancellation = -> (order) { puts "The order #(#{order.object_id}) has been
 order = Order.new
 order.observers.attach(OrderCancellation)
 order.cancel!
-# The message below will be printed by the observer (OrderEvents):
+# The message below will be printed by the observer (OrderCancellation):
 # The order #(70196221441820) has been canceled.
 ```
 
-PS: The `observers.call` can receive one or more events, but in this case, the default event (`call`) won't be transmitted.a
+> **Note**: The `observers.call` can receive one or more events, but in this case, the default event (`call`) won't be transmitted.a
 
-[⬆️ Back to Top](#table-of-contents-)
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
 
 ### Notifying observers without marking them as changed
 
@@ -198,7 +296,7 @@ This feature needs to be used with caution!
 
 If you use the methods `#notify!` or `#call!` you won't need to mark observers with `#subject_changed`.
 
-[⬆️ Back to Top](#table-of-contents-)
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
 
 ### ActiveRecord and ActiveModel integrations
 
@@ -230,22 +328,22 @@ module TitlePrinter
 end
 
 module TitlePrinterWithContext
-  def self.after_commit(post, context)
-    puts "Title: #{post.title} (from: #{context[:from]})"
+  def self.after_commit(post, event)
+    puts "Title: #{post.title} (from: #{event.context[:from]})"
   end
 end
 
 Post.transaction do
   post = Post.new(title: 'Hello world')
-  post.observers.attach(TitlePrinter, TitlePrinterWithContext, context: { from: 'example 4' })
+  post.observers.attach(TitlePrinter, TitlePrinterWithContext, context: { from: 'example #6' })
   post.save
 end
-# The message below will be printed by the observer (OrderEvents):
+# The message below will be printed by the observers (TitlePrinter, TitlePrinterWithContext):
 # Title: Hello world
-# Title: Hello world (from: example 4)
+# Title: Hello world (from: example #6)
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
 
 #### notify_observers()
 
@@ -265,24 +363,24 @@ module TitlePrinter
 end
 
 module TitlePrinterWithContext
-  def self.transaction_completed(post, context)
-    puts("Title: #{post.title} (from: #{context[:from]})")
+  def self.transaction_completed(post, event)
+    puts("Title: #{post.title} (from: #{event.ctx[:from]})")
   end
 end
 
 Post.transaction do
   post = Post.new(title: 'Olá mundo')
-  post.observers.attach(TitlePrinter, TitlePrinterWithContext, context: { from: 'example 5' })
+  post.observers.attach(TitlePrinter, TitlePrinterWithContext, context: { from: 'example #7' })
   post.save
 end
-# The message below will be printed by the observer (OrderEvents):
+# The message below will be printed by the observers (TitlePrinter, TitlePrinterWithContext):
 # Title: Olá mundo
-# Title: Olá mundo (from: example 5)
+# Title: Olá mundo (from: example #5)
 ```
 
-PS: You can use `include ::Micro::Observers::For::ActiveModel` if your class only makes use of the `ActiveModel` and all the previous examples will work.
+> **Note**: You can use `include ::Micro::Observers::For::ActiveModel` if your class only makes use of the `ActiveModel` and all the previous examples will work.
 
-[⬆️ Back to Top](#table-of-contents-)
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
 
 ## Development
 

data/lib/micro/observers.rb

@@ -3,11 +3,11 @@ require 'micro/observers/version'
 module Micro
   module Observers
     require 'micro/observers/utils'
-    require 'micro/observers/events'
-    require 'micro/observers/manager'
+    require 'micro/observers/event'
+    require 'micro/observers/set'
 
     def observers
-      @__observers ||= Observers::Manager.for(self)
+      @__observers ||= Observers::Set.for(self)
     end
   end
 end

data/lib/micro/observers/event.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Micro
+  module Observers
+
+    class Event
+      require 'micro/observers/event/names'
+
+      attr_reader :name, :subject, :context, :data
+
+      def initialize(name, subject, context, data)
+        @name, @subject = name, subject
+        @context, @data = context, data
+      end
+
+      alias ctx context
+      alias subj subject
+    end
+
+  end
+end

data/lib/micro/observers/{events.rb → event/names.rb}

@@ -3,7 +3,7 @@
 module Micro
   module Observers
 
-    module Events
+    class Event::Names
       def self.[](value, default: Utils::EMPTY_ARRAY)
         values = Utils.compact_array(value)
 

data/lib/micro/observers/for/active_model.rb

@@ -14,7 +14,7 @@ module Micro
           end
 
           def notify_observers(*events)
-            notify_observers!(Events.fetch(events))
+            notify_observers!(Event::Names.fetch(events))
           end
 
           def notify_observers_on(*callback_methods)

data/lib/micro/observers/{manager.rb → set.rb}

@@ -3,7 +3,7 @@
 module Micro
   module Observers
 
-    class Manager
+    class Set
       MapSubscriber = -> (observer, options) { [:observer, observer, options[:context]] }
 
       MapSubscribers = -> (value) do
@@ -46,11 +46,7 @@ module Micro
       INVALID_BOOLEAN_MSG = 'expected a boolean (true, false)'.freeze
 
       def subject_changed(state)
-        if state == true || state == false
-          @subject_changed = state
-
-          return self
-        end
+        return @subject_changed = state if state == true || state == false
 
         raise ArgumentError, INVALID_BOOLEAN_MSG
       end
@@ -91,28 +87,28 @@ module Micro
         self
       end
 
-      def notify(*events)
-        broadcast_if_subject_changed(Events.fetch(events))
+      def notify(*events, data: nil)
+        broadcast_if_subject_changed(Event::Names.fetch(events), data)
 
         self
       end
 
-      def notify!(*events)
-        broadcast(Events.fetch(events))
+      def notify!(*events, data: nil)
+        broadcast(Event::Names.fetch(events), data)
 
         self
       end
 
       CALL_EVENT = [:call].freeze
 
-      def call(*events)
-        broadcast_if_subject_changed(Events[events, default: CALL_EVENT])
+      def call(*events, data: nil)
+        broadcast_if_subject_changed(Event::Names[events, default: CALL_EVENT], data)
 
         self
       end
 
-      def call!(*events)
-        broadcast(Events[events, default: CALL_EVENT])
+      def call!(*events, data: nil)
+        broadcast(Event::Names[events, default: CALL_EVENT], data)
 
         self
       end
@@ -125,43 +121,51 @@ module Micro
 
       private
 
-        def broadcast_if_subject_changed(events)
+        def broadcast_if_subject_changed(events, data = nil)
           return unless subject_changed?
 
-          broadcast(events)
+          broadcast(events, data)
 
           subject_changed(false)
         end
 
-        def broadcast(events)
+        def broadcast(event_names, data)
           return if @subscribers.empty?
 
-          events.each do |event|
+          event_names.each do |event_name|
             @subscribers.each do |strategy, observer, context|
               case strategy
-              when :observer then notify_observer(observer, event, context)
-              when :callable then notify_callable(observer, event, context)
+              when :observer then notify_observer(observer, event_name, context, data)
+              when :callable then notify_callable(observer, event_name, context, data)
               end
             end
           end
         end
 
-        def notify_observer(observer, method_name, context)
-          return unless observer.respond_to?(method_name)
+        def notify_observer(observer, event_name, context, data)
+          return unless observer.respond_to?(event_name)
 
-          handler = observer.is_a?(Proc) ? observer : observer.method(method_name)
+          handler = observer.is_a?(Proc) ? observer : observer.method(event_name)
 
-          handler.arity == 1 ? handler.call(@subject) : handler.call(@subject, context)
+          return handler.call(@subject) if handler.arity == 1
+
+          handler.call(@subject, Event.new(event_name, @subject, context, data))
         end
 
-        def notify_callable(expected_event, event, context)
-          return if expected_event != event
+        def notify_callable(expected_event_name, event_name, context, data)
+          return if expected_event_name != event_name
 
           callable, with = context[0], context[1]
+          callable_arg =
+            if with && !with.is_a?(Proc)
+              with
+            else
+              event = Event.new(event_name, @subject, nil, data)
 
-          arg = with.is_a?(Proc) ? with.call(@subject) : (with || @subject)
+              with.is_a?(Proc) ? with.call(event) : event
+            end
 
-          callable.call(arg)
+          callable.call(callable_arg)
         end
 
       private_constant :INVALID_BOOLEAN_MSG, :CALL_EVENT

data/lib/micro/observers/version.rb

@@ -1,5 +1,5 @@
 module Micro
   module Observers
-    VERSION = '1.0.0'
+    VERSION = '2.0.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: u-observers
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-10-05 00:00:00.000000000 Z
+date: 2020-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -57,10 +57,11 @@ files:
 - bin/console
 - bin/setup
 - lib/micro/observers.rb
-- lib/micro/observers/events.rb
+- lib/micro/observers/event.rb
+- lib/micro/observers/event/names.rb
 - lib/micro/observers/for/active_model.rb
 - lib/micro/observers/for/active_record.rb
-- lib/micro/observers/manager.rb
+- lib/micro/observers/set.rb
 - lib/micro/observers/utils.rb
 - lib/micro/observers/version.rb
 - lib/u-observers.rb