u-observers 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5098d44090f611866c96aa4005c6475742972a9a986dbbcd5618753932b33817
-  data.tar.gz: 8b18f175cc5ff7fd1aae8e34302be62a1f295a151231c62e253d4b984d0225b8
+  metadata.gz: 52f8cf4c9f76af4b9438412dc60fa7b4156fa84afec92f89a12bb40b90d1ed32
+  data.tar.gz: 1c1ad202a47f467e468186b58671bed796656180660302f057005a7387bdcc7f
 SHA512:
-  metadata.gz: e51002b6af05c7aba17eff30ba962d1d726ce9e169ae19c8a71626c035daf7c1e4e6da727c74f73c06c46ad0f5b1faaad1d1248df018ada97aa123a613e1dedf
-  data.tar.gz: 20972cd57db02b9a25905896af9429a597cfb22e951fe73a3af6346962cd1f3574df30c241b7aa9ef3a99c502097ad0a7d75210a33227a98c6d3435371c8bb03
+  metadata.gz: c2f779070c6e11ef08c71b85f9d90342907cef3e910e7f6a7b61bbebeeec283baf56d197df1edf3bb4bb7437424e43d74208d97fed1e745b76367b2c14fb2206
+  data.tar.gz: 7995b96fe8868e126fd053e05e831b92adc421325b133324222591c74a288ba4de9677dc59b2b5f57a8d8a437c04a342f04a9548ed460546e9f56b571e4ac3c5

data/README.md

@@ -26,18 +26,20 @@
 
 This gem implements the observer pattern [[1]](https://en.wikipedia.org/wiki/Observer_pattern)[[2]](https://refactoring.guru/design-patterns/observer) (also known as publish/subscribe). It provides a simple mechanism for one object to inform a set of interested third-party objects when its state changes.
 
-Ruby's standard library [has an abstraction](https://ruby-doc.org/stdlib-2.7.1/libdoc/observer/rdoc/Observable.html) that enables you to use this pattern. But its design can conflict with other mainstream libraries, like the [`ActiveModel`/`ActiveRecord`](https://api.rubyonrails.org/classes/ActiveModel/Dirty.html#method-i-changed), which also has the [`changed`](https://ruby-doc.org/stdlib-2.7.1/libdoc/observer/rdoc/Observable.html#method-i-changed) method. In this case, the behavior of the Stdlib will be been compromised.
+Ruby's standard library [has an abstraction](https://ruby-doc.org/stdlib-2.7.1/libdoc/observer/rdoc/Observable.html) that enables you to use this pattern. But its design can conflict with other mainstream libraries, like the [`ActiveModel`/`ActiveRecord`](https://api.rubyonrails.org/classes/ActiveModel/Dirty.html#method-i-changed), which also has the [`changed`](https://ruby-doc.org/stdlib-2.7.1/libdoc/observer/rdoc/Observable.html#method-i-changed) method. In this case, the behavior of the Stdlib will be compromised.
 
-Because of this issue, I decided to create a gem that encapsulates the pattern without changing the object's implementation so much. The `Micro::Observers` includes just one instance method in the target class (its instance will be the observed subject).
+Because of this issue, I decided to create a gem that encapsulates the pattern without changing the object's implementation so much. The `Micro::Observers` includes just one instance method in the target class (its instance will be the observed subject/object).
+
+> **Note:** Você entende português? 🇧🇷 🇵🇹 Verifique o [README traduzido em pt-BR](https://github.com/serradura/u-observers/blob/main/README.pt-BR.md).
 
 # Table of contents <!-- omit in toc -->
 - [Installation](#installation)
 - [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)
+    - [Sharing a context with your observers](#sharing-a-context-with-your-observers)
+    - [Sharing data when notifying the observers](#sharing-data-when-notifying-the-observers)
     - [What is a `Micro::Observers::Event`?](#what-is-a-microobserversevent)
-    - [Passing a callable as an observer](#passing-a-callable-as-an-observer)
+    - [Using a callable as an observer](#using-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)
@@ -60,7 +62,8 @@ gem 'u-observers'
 
 | u-observers | branch  | ruby     | activerecord  |
 | ----------- | ------- | -------- | ------------- |
-| 2.0.0       | main    | >= 2.2.0 | >= 3.2, < 6.1 |
+| unreleased  | main    | >= 2.2.0 | >= 3.2, < 6.1 |
+| 2.1.0       | v2.x    | >= 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).
@@ -107,7 +110,7 @@ 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::Set @subject=#<Order:0x00007fb5dd8fce70> @subject_changed=false @subscribers=[OrderEvents]
+# <#Micro::Observers::Set @subject=#<Order:0x00007fb5dd8fce70> @subject_changed=false @subscribers=[OrderEvents]>
 
 order.canceled?
 # false
@@ -120,7 +123,7 @@ 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=[]
+# <#Micro::Observers::Set @subject=#<Order:0x00007fb5dd8fce70> @subject_changed=false @subscribers=[]>
 
 order.canceled?
 # true
@@ -131,7 +134,7 @@ order.observers.notify(:canceled) # nothing will happen, because there are no ob
 
 **Highlights of the previous example:**
 
-To avoid an undesired behavior, do you need to mark the subject as changed before notify your observers about some event.
+To avoid an undesired behavior, you need to mark the subject as changed before notifying your observers about some event.
 
 You can do this when using the `#subject_changed!` method. It will automatically mark the subject as changed.
 
@@ -146,11 +149,11 @@ order.observers.notify
 
 [⬆️ &nbsp; Back to Top](#table-of-contents-)
 
-### Passing a context for your observers
+### Sharing a context with 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.
+To share a context value (any kind of Ruby object) with one or more observers, you will need to use the `:context` keyword as the last argument of the `#attach` method. This feature gives you a unique opportunity to share a value in the attaching moment.
 
-When the observer method receives two arguments, the first one will be the subject, and the second one an instance of `Micro::Observers::Event`.
+When the observer method receives two arguments, the first one will be the subject, and the second one an instance of `Micro::Observers::Event` that will have the given context value.
 
 ```ruby
 class Order
@@ -178,9 +181,9 @@ order.cancel!
 
 [⬆️ &nbsp; Back to Top](#table-of-contents-)
 
-### Passing data when performing observers
+### Sharing data when notifying the 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.
+As previously mentioned, the [`event context`](#sharing-a-context-with-your-observers) is a value that is stored when you attach your observer. But sometimes, it will be useful to send some additional data when broadcasting an event to the observers. The `event data` gives you this unique opportunity to share some value at the the notification moment.
 
 ```ruby
 class Order
@@ -209,17 +212,24 @@ The `Micro::Observers::Event` is the event payload. Follow below all of its prop
 
 - `#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).
+- `#context` will be [the context data](#sharing-a-context-with-your-observers) that was defined in the moment that you attach the observer.
+- `#data` will be [the value that was shared in the observers' notification](#sharing-data-when-notifying-the-observers).
+- `#ctx` is an alias for the `#context` method.
+- `#subj` is an alias for the `#subject` method.
 
 [⬆️ &nbsp; Back to Top](#table-of-contents-)
 
-### Passing a callable as an observer
+### Using a callable as an observer
+
+The `observers.on()` method enables you to attach a callable as an observer.
+
+Usually, a callable has a well-defined responsibility (do only one thing), because of this, it tends to be more [SRP (Single-responsibility principle)](https://en.wikipedia.org/wiki/Single-responsibility_principle). friendly than a conventional observer (that could have N methods to respond to different kinds of notification).
 
-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.
+This method receives the below options:
+1. `:event` the expected event name.
+2. `:call` the callable object itself.
+3. `:with` (optional) it can define the value which will be used as the callable object's argument. So, if it is a `Proc`, a `Micro::Observers::Event` instance will be received as the `Proc` argument, and its output will be the callable argument. But if this option wasn't defined, the `Micro::Observers::Event` instance will be the callable argument.
+4. `:context` will be the context data that was defined in the moment that you attach the observer.
 
 ```ruby
 class Person
@@ -232,9 +242,7 @@ class Person
   end
 
   def name=(new_name)
-    observers.subject_changed(new_name != @name)
-
-    return unless observers.subject_changed?
+    return unless observers.subject_changed(new_name != @name)
 
     @name = new_name
 
@@ -251,7 +259,8 @@ person = Person.new('Rodrigo')
 person.observers.on(
   event: :name_has_been_changed,
   call: PrintPersonName,
-  with: -> event { {person: event.subject, number: rand} }
+  with: -> event { {person: event.subject, number: event.context} },
+  context: rand
 )
 
 person.name = 'Serradura'
@@ -264,7 +273,7 @@ person.name = 'Serradura'
 ### Calling the observers
 
 You can use a callable (a class, module, or object that responds to the call method) to be your observers.
-To do this, you only need make use of the method `#call` instead of `#notify`.
+To do this, you only need to make use of the method `#call` instead of `#notify`.
 
 ```ruby
 class Order
@@ -286,7 +295,7 @@ order.cancel!
 # The order #(70196221441820) has been canceled.
 ```
 
-> **Note**: 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.
 
 [⬆️ &nbsp; Back to Top](#table-of-contents-)
 
@@ -300,7 +309,7 @@ If you use the methods `#notify!` or `#call!` you won't need to mark observers w
 
 ### ActiveRecord and ActiveModel integrations
 
-To make use of this feature you need to require an additional module (`require 'u-observers/for/active_record'`).
+To make use of this feature you need to require an additional module.
 
 Gemfile example:
 ```ruby
@@ -312,13 +321,20 @@ This feature will expose modules that could be used to add macros (static method
 
 #### notify_observers_on()
 
-The `notify_observers_on` allows you to pass one or more `ActiveModel`/`ActiveRecord` callbacks, that will be used to notify your object observers.
+The `notify_observers_on` allows you to define one or more `ActiveModel`/`ActiveRecord` callbacks, that will be used to notify your object observers.
 
 ```ruby
 class Post < ActiveRecord::Base
   include ::Micro::Observers::For::ActiveRecord
 
-  notify_observers_on(:after_commit) # passing multiple callbacks. e.g. notify_observers_on(:before_save, :after_commit)
+  notify_observers_on(:after_commit) # using multiple callbacks. e.g. notify_observers_on(:before_save, :after_commit)
+
+  # The method above does the same as the commented example below.
+  #
+  # after_commit do |record|
+  #  record.subject_changed!
+  #  record.notify(:after_commit)
+  # end
 end
 
 module TitlePrinter
@@ -347,13 +363,20 @@ end
 
 #### notify_observers()
 
-The `notify_observers` allows you to pass one or more *events*, that will be used to notify after the execution of some `ActiveModel`/`ActiveRecord` callback.
+The `notify_observers` allows you to define one or more *events*, that will be used to notify after the execution of some `ActiveModel`/`ActiveRecord` callback.
 
 ```ruby
 class Post < ActiveRecord::Base
   include ::Micro::Observers::For::ActiveRecord
 
   after_commit(&notify_observers(:transaction_completed))
+
+  # The method above does the same as the commented example below.
+  #
+  # after_commit do |record|
+  #  record.subject_changed!
+  #  record.notify(:transaction_completed)
+  # end
 end
 
 module TitlePrinter

data/README.pt-BR.md

@@ -0,0 +1,426 @@
+<p align="center">
+  <h1 align="center">👀 μ-observers</h1>
+  <p align="center"><i>Implementação simples e poderosa do padrão observer.</i></p>
+  <br>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/ruby->%3D%202.2.0-ruby.svg?colorA=99004d&colorB=cc0066" alt="Ruby">
+
+  <a href="https://rubygems.org/gems/u-observers">
+    <img alt="Gem" src="https://img.shields.io/gem/v/u-observers.svg?style=flat-square">
+  </a>
+
+  <a href="https://travis-ci.com/serradura/u-observers">
+    <img alt="Build Status" src="https://travis-ci.com/serradura/u-observers.svg?branch=main">
+  </a>
+
+  <a href="https://codeclimate.com/github/serradura/u-observers/maintainability">
+    <img alt="Maintainability" src="https://api.codeclimate.com/v1/badges/e72ffa84bc95c59823f2/maintainability">
+  </a>
+
+  <a href="https://codeclimate.com/github/serradura/u-observers/test_coverage">
+    <img alt="Test Coverage" src="https://api.codeclimate.com/v1/badges/e72ffa84bc95c59823f2/test_coverage">
+  </a>
+</p>
+
+Esta gem implementa o padrão observer[[1]](https://en.wikipedia.org/wiki/Observer_pattern)[[2]](https://refactoring.guru/design-patterns/observer) (também conhecido como publicar/assinar). Ela fornece um mecanismo simples para um objeto informar um conjunto de objetos de terceiros interessados ​​quando seu estado muda.
+
+A biblioteca padrão do Ruby [tem uma abstração](https://ruby-doc.org/stdlib-2.7.1/libdoc/observer/rdoc/Observable.html) que permite usar esse padrão, mas seu design pode entrar em conflito com outras bibliotecas convencionais, como [`ActiveModel`/`ActiveRecord`](https://api.rubyonrails.org/classes/ActiveModel/Dirty.html#method-i-changed), que também tem o método [`changed`](https://ruby-doc.org/stdlib-2.7.1/libdoc/observer/rdoc/Observable.html#method-i-changed). Nesse caso, o comportamento ficaria comprometido por conta dessa sobrescrita de métodos.
+
+Por causa desse problema, decidi criar uma gem que encapsula o padrão sem alterar tanto a implementação do objeto. O `Micro::Observers` inclui apenas um método de instância na classe de destino (sua instância será o sujeito/objeto observado).
+
+# Índice <!-- omit in toc -->
+
+- [Instalação](#instalação)
+- [Compatibilidade](#compatibilidade)
+  - [Uso](#uso)
+    - [Compartilhando um contexto com seus observadores](#compartilhando-um-contexto-com-seus-observadores)
+    - [Compartilhando dados ao notificar os observadores](#compartilhando-dados-ao-notificar-os-observadores)
+    - [O que é `Micro::Observers::Event`?](#o-que-é-microobserversevent)
+    - [Usando um calleable como um observador](#usando-um-calleable-como-um-observador)
+    - [Chamando os observadores](#chamando-os-observadores)
+    - [Notificar observadores sem marcá-los como alterados](#notificar-observadores-sem-marcá-los-como-alterados)
+    - [Integrações ActiveRecord e ActiveModel](#integrações-activerecord-e-activemodel)
+      - [notify_observers_on()](#notify_observers_on)
+      - [notify_observers()](#notify_observers)
+  - [Desenvolvimento](#desenvolvimento)
+  - [Contribuindo](#contribuindo)
+  - [License](#license)
+  - [Código de conduta](#código-de-conduta)
+
+# Instalação
+
+Adicione esta linha ao Gemfile da sua aplicação e execute `bundle install`:
+
+```ruby
+gem 'u-observers'
+```
+
+# Compatibilidade
+
+| u-observers | branch  | ruby     | activerecord  |
+| ----------- | ------- | -------- | ------------- |
+| unreleased  | main    | >= 2.2.0 | >= 3.2, < 6.1 |
+| 2.1.0       | v2.x    | >= 2.2.0 | >= 3.2, < 6.1 |
+| 1.0.0       | v1.x    | >= 2.2.0 | >= 3.2, < 6.1 |
+
+> **Nota**: O ActiveRecord não é uma dependência, mas você pode adicionar um módulo para habilitar alguns métodos estáticos que foram projetados para serem usados ​​com seus [callbacks](https://guides.rubyonrails.org/active_record_callbacks.html).
+
+[⬆️ Voltar para o índice](#índice-)
+
+## Uso
+
+Qualquer classe com o `Micro::Observers` incluído pode notificar eventos para observadores anexados.
+
+```ruby
+require 'securerandom'
+
+class Order
+  include Micro::Observers
+
+  attr_reader :code
+
+  def initialize
+    @code, @status = SecureRandom.alphanumeric, :draft
+  end
+
+  def canceled?
+    @status == :canceled
+  end
+
+  def cancel!
+    return self if canceled?
+
+    @status = :canceled
+
+    observers.subject_changed!
+    observers.notify(:canceled) and return self
+  end
+end
+
+module OrderEvents
+  def self.canceled(order)
+    puts "The order #(#{order.code}) has been canceled."
+  end
+end
+
+order = Order.new
+#<Order:0x00007fb5dd8fce70 @code="X0o9yf1GsdQFvLR4", @status=:draft>
+
+order.observers.attach(OrderEvents)  # anexando vários observadores. Exemplo: observers.attach(A, B, C)
+# <#Micro::Observers::Set @subject=#<Order:0x00007fb5dd8fce70> @subject_changed=false @subscribers=[OrderEvents]>
+
+order.canceled?
+# false
+
+order.cancel!
+# A mensagem abaixo será impressa pelo observador (OrderEvents):
+# The order #(X0o9yf1GsdQFvLR4) has been canceled
+
+order.canceled?
+# true
+
+order.observers.detach(OrderEvents)  # desanexando vários observadores. Exemplo: 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)  # nada acontecerá, pois não há observadores vinculados (observers.attach)
+```
+
+**Destaques do exemplo anterior:**
+
+Para evitar um comportamento indesejado, você precisa marcar o "subject" (sujeito) como alterado antes de notificar seus observadores sobre algum evento.
+
+Você pode fazer isso ao usar o método `#subject_changed!`. Ele marcará automaticamente o sujeito como alterado.
+
+Mas se você precisar aplicar alguma condicional para marcar uma mudança, você pode usar o método `#subject_changed`. Exemplo: `observers.subject_changed(name != new_name)`
+
+O método `#notify` sempre requer um evento para fazer uma transmissão. Portanto, se você tentar usá-lo sem nenhum evento, você obterá uma exceção.
+
+```ruby
+order.observers.notify
+# ArgumentError (no events (expected at least 1))
+```
+
+[⬆️ Voltar para o índice](#índice-)
+
+### Compartilhando um contexto com seus observadores
+
+Para compartilhar um valor de contexto (qualquer tipo de objeto Ruby) com um ou mais observadores, você precisará usar a palavra-chave `:context` como o último argumento do  método `#attach`. Este recurso oferece a você uma oportunidade única de compartilhar um valor no momento de anexar um *observer*.
+
+Quando o método do observer receber dois argumentos, o primeiro será o sujeito e o segundo uma instância `Micro::Observers::Event` que terá o valor do contexto.
+
+```ruby
+class Order
+  include Micro::Observers
+
+  def cancel!
+    observers.subject_changed!
+    observers.notify(:canceled)
+    self
+  end
+end
+
+module OrderEvents
+  def self.canceled(order, event)
+    puts "The order #(#{order.object_id}) has been canceled. (from: #{event.context[:from]})"  # event.ctx é um alias para event.context
+  end
+end
+
+order = Order.new
+order.observers.attach(OrderEvents, context: { from: 'example #2' })  # anexando vários observadores. Exemplo: observers.attach(A, B, context: {hello:: world})
+order.cancel!
+# A mensagem abaixo será impressa pelo observador (OrderEvents):
+# The order #(70196221441820) has been canceled. (from: example #2)
+```
+
+[⬆️ Voltar para o índice](#índice-)
+
+### Compartilhando dados ao notificar os observadores
+
+Como mencionado anteriormente, o [`event context`](#compartilhando-um-contexto-com-seus-observadores) é um valor armazenado quando você anexa seu *observer*. Mas, às vezes, será útil enviar alguns dados adicionais ao transmitir um evento aos seus *observers*. O `event data` dá a você esta oportunidade única de compartilhar algum valor no momento da notificação.
+
+```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)
+
+# A mensagem abaixo será impressa pelo observador (OrderHandler):
+# The order #(70196221441820) received the number 1 from example #3.
+```
+
+[⬆️ Voltar para o índice](#índice-)
+
+### O que é `Micro::Observers::Event`?
+
+O `Micro::Observers::Event` é o payload do evento. Veja abaixo todas as suas propriedades:
+- `#name` será o evento transmitido.
+- `#subject` será o sujeito observado.
+- `#context` serão [os dados de contexto](#compartilhando-um-contexto-com-seus-observadores) que foram definidos no momento em que você anexa o *observer*.
+- `#data` será [o valor compartilhado na notificação dos observadores](#compartilhando-dados-ao-notificar-os-observadores).
+- `#ctx` é um apelido para o método `#context`.
+- `#subj` é um *alias* para o método `#subject`.
+
+[⬆️ Voltar para o índice](#índice-)
+
+### Usando um calleable como um observador
+
+O método `observers.on()` permite que você anexe um callable (objeto que responda ao método `call`) como um observador.
+
+Um callable tende a ter uma responsabilidade bem definida, promovendo assim o uso de [SRP (Single-responsibility principle).
+
+Normalmente, um callable tem uma responsabilidade bem definida (faz apenas uma coisa), por isso, tende a ser mais amigável com o [SRP (princípio de responsabilidade única)](https://en.wikipedia.org/wiki/Single-responsibility_principle) do que um observador convencional (que poderia ter N métodos para responder a diferentes tipos de notificação).
+
+Este método recebe as opções abaixo:
+1. `:event` o nome do evento esperado.
+2. `:call` o próprio callable.
+3. `:with` (opcional) pode definir o valor que será usado como argumento do objeto callable. Portanto, se for um `Proc`, uma instância de `Micro::Observers::Event` será recebida como o argumento `Proc` e sua saída será o argumento que pode ser chamado. Mas se essa opção não for definida, a instância `Micro::Observers::Event` será o argumento do callable.
+4. `#context` serão os dados de contexto que foram definidos no momento em que você anexa o *observer*.
+
+```ruby
+class Person
+  include Micro::Observers
+
+  attr_reader :name
+
+  def initialize(name)
+    @name = name
+  end
+
+  def name=(new_name)
+    return unless observers.subject_changed(new_name != @name)
+
+    @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('Aristóteles')
+
+person.observers.on(
+  event: :name_has_been_changed,
+  call: PrintPersonName,
+  with: -> event { {person: event.subject, number: rand} }
+)
+
+person.name = 'Coutinho'
+
+# A mensagem abaixo será impressa pelo observador (PrintPersonName):
+# Person name: Coutinho, number: 0.5018509191706862
+```
+
+[⬆️ Voltar para o índice](#índice-)
+
+### Chamando os observadores
+
+Você pode usar um callable (uma classe, módulo ou objeto que responda ao método `call`) para ser seu *observer*. Para fazer isso, você só precisa usar o método `#call` em vez de `#notify`.
+
+```ruby
+class Order
+  include Micro::Observers
+
+  def cancel!
+    observers.subject_changed!
+    observers.call # na prática, este é um alias para observers.notify(:call)
+    self
+  end
+end
+
+OrderCancellation = -> (order) { puts "The order #(#{order.object_id}) has been canceled." }
+
+order = Order.new
+order.observers.attach(OrderCancellation)
+order.cancel!
+
+# A mensagem abaixo será impressa pelo observador (OrderCancellation):
+# The order #(70196221441820) has been canceled.
+```
+
+> **Nota**: O `observers.call` pode receber um ou mais eventos, mas no caso de receber eventos/argumentos, o evento padrão (`call`) não será transmitido.
+
+[⬆️ Voltar para o índice](#índice-)
+
+### Notificar observadores sem marcá-los como alterados
+
+Este recurso deve ser usado com cuidado!
+
+Se você usar os métodos `#notify!` ou `#call!` você não precisará marcar observers com `#subject_changed`.
+
+[⬆️ Voltar para o índice](#índice-)
+
+### Integrações ActiveRecord e ActiveModel
+
+Para fazer uso deste recurso, você precisa de um módulo adicional.
+
+Exemplo de Gemfile:
+```ruby
+gem 'u-observers', require: 'u-observers/for/active_record'
+```
+
+Este recurso irá expor módulos que podem ser usados ​​para adicionar macros (métodos estáticos) que foram projetados para funcionar com os callbacks do `ActiveModel`/`ActiveRecord`. Exemplo:
+
+#### notify_observers_on()
+
+O `notify_observers_on` permite que você defina um ou mais callbacks do `ActiveModel`/`ActiveRecord`, que serão usados ​​para notificar seus *observers*.
+
+```ruby
+class Post < ActiveRecord::Base
+  include ::Micro::Observers::For::ActiveRecord
+
+  notify_observers_on(:after_commit) # usando vários callbacks. Exemplo: notificar_observadores_on(:before_save, :after_commit)
+
+  # O método acima faz o mesmo que o exemplo comentado abaixo.
+  #
+  # after_commit do | record |
+  #   record.subject_changed!
+  #   record.notify (:after_commit)
+  # end
+end
+
+module TitlePrinter
+  def self.after_commit(post)
+    puts "Title: #{post.title}"
+  end
+end
+
+module TitlePrinterWithContext
+  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 #6' })
+  post.save
+end
+
+# A mensagem abaixo será impressa pelos observadores (TitlePrinter, TitlePrinterWithContext):
+# Title: Hello world
+# Title: Hello world (de: exemplo # 6)
+```
+
+[⬆️ Voltar para o índice](#índice-)
+
+#### notify_observers()
+
+O `notify_observers` permite definir um ou mais eventos, que serão utilizados para notificar após a execução de algum callback do `ActiveModel`/`ActiveRecord`.
+
+```ruby
+class Post < ActiveRecord::Base
+  include ::Micro::Observers::For::ActiveRecord
+
+  after_commit(&notify_observers(:transaction_completed))
+
+  # O método acima faz o mesmo que o exemplo comentado abaixo.
+  #
+  # after_commit do | record |
+  # record.subject_changed!
+  # record.notify (:transaction_completed)
+  # end
+end
+
+module TitlePrinter
+  def self.transaction_completed(post)
+    puts("Title: #{post.title}")
+  end
+end
+
+module TitlePrinterWithContext
+  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 #7' })
+  post.save
+end
+
+# A mensagem abaixo será impressa pelos observadores (TitlePrinter, TitlePrinterWithContext):
+# Title: Olá mundo
+# Title: Olá mundo (from: example # 5)
+```
+
+> **Observação**: você pode usar `include ::Micro::Observers::For::ActiveModel` se sua classe apenas fizer uso do `ActiveModel` e todos os exemplos anteriores funcionarão.
+
+[⬆️ Voltar para o índice](#índice-)
+
+## Desenvolvimento
+
+Depois de verificar o repositório, execute `bin/setup` para instalar as dependências. Em seguida, execute `rake test` para executar os testes. Você também pode executar `bin/console` um prompt interativo que permitirá que você experimente.
+
+Para instalar esta gem em sua máquina local, execute `bundle exec rake install`. Para lançar uma nova versão, atualize o número da versão em `version.rb` e execute `bundle exec rake release`, que criará uma tag git para a versão, envie os commits ao git e envie e envie o arquivo `.gem` para [rubygems.org](https://rubygems.org).
+
+## Contribuindo
+
+Reportar bugs e solicitações de pull-requests são bem-vindos no GitHub em https://github.com/serradura/u-observers. Este projeto pretende ser um espaço seguro e acolhedor para colaboração, e espera-se que os colaboradores sigam o [código de conduta](https://github.com/serradura/u-observers/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+A gem está disponível como código aberto sob os termos da [Licença MIT](https://opensource.org/licenses/MIT).
+
+## Código de conduta
+
+Espera-se que todos que interagem nas bases de código do projeto `Micro::Observers`, rastreadores de problemas, salas de bate-papo e listas de discussão sigam o [código de conduta](https://github.com/serradura/u-observers/blob/master/CODE_OF_CONDUCT.md).

data/lib/micro/observers/event/names.rb

@@ -4,8 +4,10 @@ module Micro
   module Observers
 
     class Event::Names
-      def self.[](value, default: Utils::EMPTY_ARRAY)
-        values = Utils.compact_array(value)
+      EMPTY_ARRAY = [].freeze
+
+      def self.[](value, default: EMPTY_ARRAY)
+        values = Utils::Arrays.flatten_and_compact(value)
 
         values.empty? ? default : values
       end

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

@@ -18,7 +18,7 @@ module Micro
           end
 
           def notify_observers_on(*callback_methods)
-            Utils.compact_array(callback_methods).each do |callback_method|
+            Utils::Arrays.flatten_and_compact(callback_methods).each do |callback_method|
               self.public_send(callback_method, &notify_observers!([callback_method]))
             end
           end

data/lib/micro/observers/set.rb

@@ -4,11 +4,13 @@ module Micro
   module Observers
 
     class Set
+      EMPTY_HASH = {}.freeze
+
       MapSubscriber = -> (observer, options) { [:observer, observer, options[:context]] }
 
       MapSubscribers = -> (value) do
-        array = Utils.compact_array(value.kind_of?(Array) ? value : [])
-        array.map { |observer| MapSubscriber[observer, Utils::EMPTY_HASH] }
+        array = Utils::Arrays.flatten_and_compact(value.kind_of?(Array) ? value : [])
+        array.map { |observer| MapSubscriber[observer, EMPTY_HASH] }
       end
 
       GetObserver = -> subscriber { subscriber[0] == :observer ? subscriber[1] : subscriber[2][0] }
@@ -60,9 +62,9 @@ module Micro
       end
 
       def attach(*args)
-        options = args.last.is_a?(Hash) ? args.pop : Utils::EMPTY_HASH
+        options = args.last.is_a?(Hash) ? args.pop : EMPTY_HASH
 
-        Utils.compact_array(args).each do |observer|
+        Utils::Arrays.flatten_and_compact(args).each do |observer|
           @subscribers << MapSubscriber[observer, options] unless included?(observer)
         end
 
@@ -70,19 +72,19 @@ module Micro
       end
 
       def detach(*args)
-        Utils.compact_array(args).each do |observer|
+        Utils::Arrays.flatten_and_compact(args).each do |observer|
           @subscribers.delete_if(&EqualTo[observer])
         end
 
         self
       end
 
-      def on(options = Utils::EMPTY_HASH)
-        event, callable, with = options[:event], options[:call], options[:with]
+      def on(options = EMPTY_HASH)
+        event, callable, with, context = options[:event], options[:call], options[:with], options[:context]
 
         return self unless event.is_a?(Symbol) && callable.respond_to?(:call)
 
-        @subscribers << [:callable, event, [callable, with]] unless included?(callable)
+        @subscribers << [:callable, event, [callable, with, context]] unless included?(callable)
 
         self
       end
@@ -152,15 +154,15 @@ module Micro
           handler.call(@subject, Event.new(event_name, @subject, context, data))
         end
 
-        def notify_callable(expected_event_name, event_name, context, data)
+        def notify_callable(expected_event_name, event_name, opt, data)
           return if expected_event_name != event_name
 
-          callable, with = context[0], context[1]
+          callable, with, context = opt[0], opt[1], opt[2]
           callable_arg =
             if with && !with.is_a?(Proc)
               with
             else
-              event = Event.new(event_name, @subject, nil, data)
+              event = Event.new(event_name, @subject, context, data)
 
               with.is_a?(Proc) ? with.call(event) : event
             end
@@ -168,7 +170,7 @@ module Micro
           callable.call(callable_arg)
         end
 
-      private_constant :INVALID_BOOLEAN_MSG, :CALL_EVENT
+      private_constant :EMPTY_HASH, :INVALID_BOOLEAN_MSG, :CALL_EVENT
       private_constant :MapSubscriber, :MapSubscribers, :GetObserver, :EqualTo
     end
 

data/lib/micro/observers/utils.rb

@@ -4,11 +4,10 @@ module Micro
   module Observers
 
     module Utils
-      EMPTY_HASH = {}.freeze
-      EMPTY_ARRAY = [].freeze
-
-      def self.compact_array(value)
-        Array(value).flatten.tap(&:compact!)
+      module Arrays
+        def self.flatten_and_compact(value)
+          Array(value).flatten.tap(&:compact!)
+        end
       end
     end
 

data/lib/micro/observers/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: u-observers
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-10-06 00:00:00.000000000 Z
+date: 2020-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,6 +53,7 @@ files:
 - Gemfile
 - LICENSE.txt
 - README.md
+- README.pt-BR.md
 - Rakefile
 - bin/console
 - bin/setup