u-observers 2.3.0 → 3.0.0

data/README.md

@@ -1,38 +1,38 @@
 <p align="center">
   <h1 align="center">👀 μ-observers</h1>
   <p align="center"><i>Simple and powerful implementation of the observer pattern.</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 href="https://github.com/u-gems/u-observers/actions/workflows/ci.yml">
+    <img alt="Build Status" src="https://github.com/u-gems/u-observers/actions/workflows/ci.yml/badge.svg">
   </a>
+  <br/>
+  <a href="https://qlty.sh/gh/u-gems/projects/u-observers"><img src="https://qlty.sh/gh/u-gems/projects/u-observers/maintainability.svg" alt="Maintainability" /></a>
+  <a href="https://qlty.sh/gh/u-gems/projects/u-observers"><img src="https://qlty.sh/gh/u-gems/projects/u-observers/coverage.svg" alt="Code Coverage" /></a>
+  <br/>
+  <img src="https://img.shields.io/badge/Ruby%20%3E%3D%202.7%2C%20%3C%3D%20Head-ruby.svg?colorA=444&colorB=333" alt="Ruby">
+  <img src="https://img.shields.io/badge/Rails%20%3E%3D%206.0%2C%20%3C%3D%20Edge-rails.svg?colorA=444&colorB=333" alt="Rails">
 </p>
 
+> [!IMPORTANT]
+> **No breaking API changes — ever.** `u-observers` is a dependency-free gem that many projects rely on (directly or transitively). Its role is to remain a stable, backward-compatible foundation — every change keeps existing code working.
+>
+> Major version bumps signal only that a Ruby or Rails version was dropped from the supported matrix — per SemVer, a dependency-floor change. Your code keeps working.
+
 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 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/object).
 
-> **Note:** Você entende português? 🇧🇷&nbsp;🇵🇹 Verifique o [README traduzido em pt-BR](https://github.com/serradura/u-observers/blob/main/README.pt-BR.md).
+> **Note:** Você entende português? 🇧🇷&nbsp;🇵🇹 Verifique o [README traduzido em pt-BR](https://github.com/u-gems/u-observers/blob/main/README.pt-BR.md).
 
 # Table of contents <!-- omit in toc -->
+
 - [Installation](#installation)
 - [Compatibility](#compatibility)
   - [Usage](#usage)
@@ -46,13 +46,14 @@ Because of this issue, I decided to create a gem that encapsulates the pattern w
       - [`observers.attach(*args, perform_once: true)`](#observersattachargs-perform_once-true)
       - [`observers.once(event:, call:, ...)`](#observersonceevent-call-)
     - [Defining observers using blocks](#defining-observers-using-blocks)
-      - [order.observers.on()](#orderobserverson)
-      - [order.observers.on()](#orderobserverson-1)
+      - [`observers.on()`](#observerson)
+      - [`observers.once()`](#observersonce)
       - [Replacing a block by a `lambda`/`proc`](#replacing-a-block-by-a-lambdaproc)
     - [Detaching observers](#detaching-observers)
     - [ActiveRecord and ActiveModel integrations](#activerecord-and-activemodel-integrations)
-      - [notify_observers_on()](#notify_observers_on)
-      - [notify_observers()](#notify_observers)
+      - [`.notify_observers_on()`](#notify_observers_on)
+      - [Attaching observers at the class level (`.notify_observers!()`)](#attaching-observers-at-the-class-level-notify_observers)
+      - [`.notify_observers()`](#notify_observers)
   - [Development](#development)
   - [Contributing](#contributing)
   - [License](#license)
@@ -68,11 +69,24 @@ gem 'u-observers'
 
 # Compatibility
 
-| u-observers | branch  | ruby     | activerecord  |
-| ----------- | ------- | -------- | ------------- |
-| unreleased  | main    | >= 2.2.0 | >= 3.2, < 6.1 |
-| 2.3.0       | v2.x    | >= 2.2.0 | >= 3.2, < 6.1 |
-| 1.0.0       | v1.x    | >= 2.2.0 | >= 3.2, < 6.1 |
+| u-observers | branch | ruby     | activerecord    |
+| ----------- | ------ | -------- | --------------- |
+| 3.0.0       | main   | >= 2.7.0 | >= 6.0, <= Edge |
+| 2.3.0       | v2.x   | >= 2.2.0 | >= 3.2, < 6.1   |
+| 1.0.0       | v1.x   | >= 2.2.0 | >= 3.2, < 6.1   |
+
+This library is tested (CI matrix) against:
+
+| Ruby / Rails | 6.0 | 6.1 | 7.0 | 7.1 | 7.2 | 8.0 | 8.1 | Edge |
+| ------------ | --- | --- | --- | --- | --- | --- | --- | ---- |
+| 2.7          | ✅  | ✅  | ✅  | ✅  |     |     |     |      |
+| 3.0          | ✅  | ✅  | ✅  | ✅  |     |     |     |      |
+| 3.1          |     |     | ✅  | ✅  | ✅  |     |     |      |
+| 3.2          |     |     | ✅  | ✅  | ✅  | ✅  |     |      |
+| 3.3          |     |     | ✅  | ✅  | ✅  | ✅  | ✅  | ✅   |
+| 3.4          |     |     |     |     | ✅  | ✅  | ✅  | ✅   |
+| 4.x          |     |     |     |     |     |     | ✅  | ✅   |
+| Head         |     |     |     |     |     |     | ✅  | ✅   |
 
 > **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).
 
@@ -219,8 +233,8 @@ order.observers.notify(:changed, data: 1)
 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](#sharing-a-context-with-your-observers) that was defined in the moment that you attach the observer.
+- `#subject` will be the observed object.
+- `#context` will be [the context data](#sharing-a-context-with-your-observers) that was defined at 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.
@@ -231,9 +245,10 @@ The `Micro::Observers::Event` is the event payload. Follow below all of its prop
 
 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).
+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).
 
 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.
@@ -381,9 +396,9 @@ order.cancel!         # Nothing will happen because there aren't observers.
 
 ### Defining observers using blocks
 
-The methods `#on()` and `#once()` can receive the event name (a `symbol`) and a block to define observers.
+The methods `#on()` and `#once()` can receive an event (`symbol`) and a block to define observers.
 
-#### order.observers.on()
+#### `observers.on()`
 
 ```ruby
 class Order
@@ -406,7 +421,7 @@ order.cancel!         # The order #(70301497466060) has been canceled.
 order.observers.some? # true
 ```
 
-#### order.observers.on()
+#### `observers.once()`
 
 ```ruby
 class Order
@@ -431,7 +446,7 @@ order.observers.some? # false
 
 #### Replacing a block by a `lambda`/`proc`
 
-Ruby allows you to replace any block with a `lambda`/`proc`. e.g.
+Ruby allows you to replace any block with a `lambda`/`proc`. So, it will be possible to use this kind of feature to define your observers. e.g.
 
 ```ruby
 class Order
@@ -475,11 +490,12 @@ module OrderNotifications
 end
 
 order = Order.new
+order.observers.on(:canceled) { |_event| }
 order.observers.on(event: :canceled, call: NotifyAfterCancel)
 order.observers.attach(OrderNotifications)
 
 order.observers.some? # true
-order.observers.count # 2
+order.observers.count # 3
 
 order.observers.off(:canceled) # removing the callable (NotifyAfterCancel).
 order.observers.some? # true
@@ -497,15 +513,16 @@ order.observers.count # 0
 To make use of this feature you need to require an additional module.
 
 Gemfile example:
+
 ```ruby
 gem 'u-observers', require: 'u-observers/for/active_record'
 ```
 
 This feature will expose modules that could be used to add macros (static methods) that were designed to work with `ActiveModel`/`ActiveRecord` callbacks. e.g:
 
-#### notify_observers_on()
+#### `.notify_observers_on()`
 
-The `notify_observers_on` allows you to define 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 observers.
 
 ```ruby
 class Post < ActiveRecord::Base
@@ -545,9 +562,64 @@ end
 
 [⬆️ &nbsp; Back to Top](#table-of-contents-)
 
-#### notify_observers()
+#### Attaching observers at the class level (`.notify_observers!()`)
+
+While `notify_observers_on` only wires the callback to a broadcast (you still `attach` the observers on every instance), `notify_observers!` also **binds the observers to the model at the class level** through the required `with:` option — so you never call `observers.attach` yourself. The `event:` option names the callback to hook; use `context:` to forward a context to those observers, and pass any extra option (e.g. `on:`) straight through to the underlying callback.
+
+```ruby
+class Post < ActiveRecord::Base
+  include ::Micro::Observers::For::ActiveRecord
+
+  # Attach TitlePrinter (and TitlePrinterWithContext) on every after_commit
+  # triggered by an update — no per-instance `observers.attach` needed.
+  notify_observers!(
+    on: :update,
+    with: [TitlePrinter, TitlePrinterWithContext],
+    event: :after_commit,
+    context: { from: 'class-level' }
+  )
+
+  # Equivalent to:
+  #
+  # after_commit(on: :update) do |record|
+  #   record.observers.attach(TitlePrinter, TitlePrinterWithContext, context: { from: 'class-level' })
+  #   record.observers.subject_changed!
+  #   record.observers.notify(:after_commit)
+  # end
+end
+
+Post.transaction { Post.create(title: 'Hello world') } # nothing — `on: :update`
+
+post = Post.first
+Post.transaction { post.update(title: 'Hello again') }
+# Title: Hello again
+# Title: Hello again (from: class-level)
+```
+
+> **Note**: `event:` and `with:` are required (`with:` accepts a single observer or an array). Without observers to attach, use `notify_observers_on` instead.
+
+The declared observers are introspectable and detachable at the class level:
+
+```ruby
+Post.observers_to_notify
+# { after_commit: [TitlePrinter, TitlePrinterWithContext] }
+
+# Stop notifying a given observer (from every callback, or scope it with `from:`)
+Post.detach_observers_to_notify(TitlePrinterWithContext)
+# { after_commit: [TitlePrinter] }
+
+Post.detach_observers_to_notify(TitlePrinter, from: :after_commit)
+# {}
+
+# With no observers, clears the callback(s) entirely:
+Post.detach_observers_to_notify(from: :after_commit)
+```
+
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
+
+#### `.notify_observers()`
 
-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.
+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
@@ -563,12 +635,6 @@ class Post < ActiveRecord::Base
   # 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]})")
@@ -577,7 +643,11 @@ end
 
 Post.transaction do
   post = Post.new(title: 'Olá mundo')
-  post.observers.attach(TitlePrinter, TitlePrinterWithContext, context: { from: 'example #7' })
+
+  post.observers.on(:transaction_completed) { |event| puts("Title: #{event.subject.title}") }
+
+  post.observers.attach(TitlePrinterWithContext, context: { from: 'example #7' })
+
   post.save
 end
 # The message below will be printed by the observers (TitlePrinter, TitlePrinterWithContext):
@@ -597,8 +667,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/serradura/u-observers. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/serradura/u-observers/blob/master/CODE_OF_CONDUCT.md).
-
+Bug reports and pull requests are welcome on GitHub at https://github.com/u-gems/u-observers. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/u-gems/u-observers/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -606,4 +675,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the `Micro::Observers` project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/serradura/u-observers/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the `Micro::Observers` project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/u-gems/u-observers/blob/master/CODE_OF_CONDUCT.md).

data/README.pt-BR.md

@@ -1,29 +1,28 @@
 <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 href="https://github.com/u-gems/u-observers/actions/workflows/ci.yml">
+    <img alt="Build Status" src="https://github.com/u-gems/u-observers/actions/workflows/ci.yml/badge.svg">
   </a>
+  <br/>
+  <a href="https://qlty.sh/gh/u-gems/projects/u-observers"><img src="https://qlty.sh/gh/u-gems/projects/u-observers/maintainability.svg" alt="Maintainability" /></a>
+  <a href="https://qlty.sh/gh/u-gems/projects/u-observers"><img src="https://qlty.sh/gh/u-gems/projects/u-observers/coverage.svg" alt="Code Coverage" /></a>
+  <br/>
+  <img src="https://img.shields.io/badge/Ruby%20%3E%3D%202.7%2C%20%3C%3D%20Head-ruby.svg?colorA=444&colorB=333" alt="Ruby">
+  <img src="https://img.shields.io/badge/Rails%20%3E%3D%206.0%2C%20%3C%3D%20Edge-rails.svg?colorA=444&colorB=333" alt="Rails">
 </p>
 
+> [!IMPORTANT]
+> **Nenhuma mudança que quebre a API — nunca.** `u-observers` é uma gem sem dependências da qual muitos projetos dependem (direta ou transitivamente). Seu papel é permanecer uma base estável e retrocompatível — toda mudança mantém o código existente funcionando.
+>
+> Saltos de versão major sinalizam apenas que uma versão de Ruby ou Rails foi removida da matriz suportada — pela SemVer, uma mudança no piso de dependências. Seu código continua funcionando.
+
 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.
@@ -45,13 +44,14 @@ Por causa desse problema, decidi criar uma gem que encapsula o padrão sem alter
       - [`observers.attach(*args, perform_once: true)`](#observersattachargs-perform_once-true)
       - [`observers.once(event:, call:, ...)`](#observersonceevent-call-)
     - [Definindo observers com blocos](#definindo-observers-com-blocos)
-      - [order.observers.on()](#orderobserverson)
-      - [order.observers.on()](#orderobserverson-1)
+      - [`observers.on()`](#observerson)
+      - [`observers.once()`](#observersonce)
       - [Substituindo um bloco por um `lambda`/`proc`](#substituindo-um-bloco-por-um-lambdaproc)
     - [Desanexando observers](#desanexando-observers)
     - [Integrações ActiveRecord e ActiveModel](#integrações-activerecord-e-activemodel)
-      - [notify_observers_on()](#notify_observers_on)
-      - [notify_observers()](#notify_observers)
+      - [`.notify_observers_on()`](#notify_observers_on)
+      - [Anexando observers no nível da classe (`.notify_observers!()`)](#anexando-observers-no-nível-da-classe-notify_observers)
+      - [`.notify_observers()`](#notify_observers)
   - [Desenvolvimento](#desenvolvimento)
   - [Contribuindo](#contribuindo)
   - [License](#license)
@@ -67,11 +67,24 @@ gem 'u-observers'
 
 # Compatibilidade
 
-| u-observers | branch  | ruby     | activerecord  |
-| ----------- | ------- | -------- | ------------- |
-| unreleased  | main    | >= 2.2.0 | >= 3.2, < 6.1 |
-| 2.3.0       | v2.x    | >= 2.2.0 | >= 3.2, < 6.1 |
-| 1.0.0       | v1.x    | >= 2.2.0 | >= 3.2, < 6.1 |
+| u-observers | branch | ruby     | activerecord    |
+| ----------- | ------ | -------- | --------------- |
+| 3.0.0       | main   | >= 2.7.0 | >= 6.0, <= Edge |
+| 2.3.0       | v2.x   | >= 2.2.0 | >= 3.2, < 6.1   |
+| 1.0.0       | v1.x   | >= 2.2.0 | >= 3.2, < 6.1   |
+
+Esta biblioteca é testada (CI matrix) contra:
+
+| Ruby / Rails | 6.0 | 6.1 | 7.0 | 7.1 | 7.2 | 8.0 | 8.1 | Edge |
+| ------------ | --- | --- | --- | --- | --- | --- | --- | ---- |
+| 2.7          | ✅  | ✅  | ✅  | ✅  |     |     |     |      |
+| 3.0          | ✅  | ✅  | ✅  | ✅  |     |     |     |      |
+| 3.1          |     |     | ✅  | ✅  | ✅  |     |     |      |
+| 3.2          |     |     | ✅  | ✅  | ✅  | ✅  |     |      |
+| 3.3          |     |     | ✅  | ✅  | ✅  | ✅  | ✅  | ✅   |
+| 3.4          |     |     |     |     | ✅  | ✅  | ✅  | ✅   |
+| 4.x          |     |     |     |     |     |     | ✅  | ✅   |
+| Head         |     |     |     |     |     |     | ✅  | ✅   |
 
 > **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).
 
@@ -158,7 +171,7 @@ order.observers.notify
 
 ### 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*.
+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.
 
@@ -190,7 +203,7 @@ order.cancel!
 
 ### 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.
+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
@@ -217,12 +230,13 @@ order.observers.notify(:changed, data: 1)
 ### 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*.
+- `#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`.
+- `#subj` é um _alias_ para o método `#subject`.
 
 [⬆️ Voltar para o índice](#índice-)
 
@@ -233,10 +247,11 @@ O método `observers.on()` permite que você anexe um callable (objeto que respo
 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*.
+4. `:context` serão os dados de contexto que foram definidos no momento em que você anexa o _observer_.
 
 ```ruby
 class Person
@@ -280,7 +295,7 @@ person.name = 'Coutinho'
 
 ### 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`.
+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
@@ -383,7 +398,7 @@ order.cancel!         # Nothing will happen because there aren't observers.
 
 Os métodos `#on()` e `#once()` podem receber um evento (a `symbol`) e um bloco para definir observers.
 
-#### order.observers.on()
+#### `observers.on()`
 
 ```ruby
 class Order
@@ -406,7 +421,7 @@ order.cancel!         # The order #(70301497466060) has been canceled.
 order.observers.some? # true
 ```
 
-#### order.observers.on()
+#### `observers.once()`
 
 ```ruby
 class Order
@@ -431,7 +446,7 @@ order.observers.some? # false
 
 #### Substituindo um bloco por um `lambda`/`proc`
 
-Ruby permite que você substitua qualquer bloco com um `lambda`/`proc`. Exemplo:
+Ruby permite que você substitua qualquer bloco com um `lambda`/`proc`. Portanto, será possível usar este tipo de recurso para definir seus observers. Exemplo:
 
 ```ruby
 class Order
@@ -475,11 +490,12 @@ module OrderNotifications
 end
 
 order = Order.new
+order.observers.on(:canceled) { |_event| }
 order.observers.on(event: :canceled, call: NotifyAfterCancel)
 order.observers.attach(OrderNotifications)
 
 order.observers.some? # true
-order.observers.count # 2
+order.observers.count # 3
 
 order.observers.off(:canceled) # removing the callable (NotifyAfterCancel).
 order.observers.some? # true
@@ -497,15 +513,16 @@ order.observers.count # 0
 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()
+#### `.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*.
+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
@@ -546,7 +563,62 @@ end
 
 [⬆️ Voltar para o índice](#índice-)
 
-#### notify_observers()
+#### Anexando observers no nível da classe (`.notify_observers!()`)
+
+Enquanto o `notify_observers_on` apenas conecta o callback a um broadcast (você ainda precisa chamar `attach` em cada instância), o `notify_observers!` também **vincula os _observers_ ao modelo no nível da classe** através da opção obrigatória `with:` — assim você nunca chama `observers.attach`. A opção `event:` nomeia o callback a ser usado; use `context:` para encaminhar um contexto para esses _observers_, e passe qualquer opção extra (por exemplo, `on:`) diretamente para o callback subjacente.
+
+```ruby
+class Post < ActiveRecord::Base
+  include ::Micro::Observers::For::ActiveRecord
+
+  # Anexa TitlePrinter (e TitlePrinterWithContext) em todo after_commit
+  # disparado por um update — sem precisar de `observers.attach` por instância.
+  notify_observers!(
+    on: :update,
+    with: [TitlePrinter, TitlePrinterWithContext],
+    event: :after_commit,
+    context: { from: 'class-level' }
+  )
+
+  # Equivalente a:
+  #
+  # after_commit(on: :update) do |record|
+  #   record.observers.attach(TitlePrinter, TitlePrinterWithContext, context: { from: 'class-level' })
+  #   record.observers.subject_changed!
+  #   record.observers.notify(:after_commit)
+  # end
+end
+
+Post.transaction { Post.create(title: 'Hello world') } # nada — `on: :update`
+
+post = Post.first
+Post.transaction { post.update(title: 'Hello again') }
+# Title: Hello again
+# Title: Hello again (de: class-level)
+```
+
+> **Nota**: `event:` e `with:` são obrigatórios (`with:` aceita um único _observer_ ou um array). Sem _observers_ para anexar, use o `notify_observers_on`.
+
+Os _observers_ declarados são inspecionáveis e removíveis no nível da classe:
+
+```ruby
+Post.observers_to_notify
+# { after_commit: [TitlePrinter, TitlePrinterWithContext] }
+
+# Para de notificar um dado observer (de todos os callbacks, ou use `from:` para limitar)
+Post.detach_observers_to_notify(TitlePrinterWithContext)
+# { after_commit: [TitlePrinter] }
+
+Post.detach_observers_to_notify(TitlePrinter, from: :after_commit)
+# {}
+
+# Sem observers, remove o(s) callback(s) por completo:
+Post.detach_observers_to_notify(from: :after_commit)
+```
+
+[⬆️ 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`.
 
@@ -564,12 +636,6 @@ class Post < ActiveRecord::Base
   # 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]})")
@@ -578,7 +644,11 @@ end
 
 Post.transaction do
   post = Post.new(title: 'Olá mundo')
-  post.observers.attach(TitlePrinter, TitlePrinterWithContext, context: { from: 'example #7' })
+
+  post.observers.on(:transaction_completed) { |event| puts("Title: #{event.subject.title}") }
+
+  post.observers.attach(TitlePrinterWithContext, context: { from: 'example #7' })
+
   post.save
 end
 
@@ -599,7 +669,7 @@ Para instalar esta gem em sua máquina local, execute `bundle exec rake install`
 
 ## 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).
+Reportar bugs e solicitações de pull-requests são bem-vindos no GitHub em https://github.com/u-gems/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/u-gems/u-observers/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -607,4 +677,4 @@ A gem está disponível como código aberto sob os termos da [Licença MIT](http
 
 ## 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).
+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/u-gems/u-observers/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -7,4 +7,34 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+require 'appraisal/task'
+
+Appraisal::Task.new
+
+desc 'Run the full test suite against every supported Rails version'
+task :matrix do
+  appraisals =
+    if RUBY_VERSION < '3.1'
+      %w[rails-6-0 rails-6-1 rails-7-0 rails-7-1]
+    elsif RUBY_VERSION < '3.2'
+      %w[rails-7-0 rails-7-1 rails-7-2]
+    elsif RUBY_VERSION < '3.3'
+      %w[rails-7-0 rails-7-1 rails-7-2 rails-8-0]
+    elsif RUBY_VERSION < '3.4'
+      %w[rails-7-0 rails-7-1 rails-7-2 rails-8-0 rails-8-1 rails-edge]
+    elsif RUBY_VERSION < '4.0'
+      %w[rails-7-2 rails-8-0 rails-8-1 rails-edge]
+    else
+      %w[rails-8-1 rails-edge]
+    end
+
+  # Baseline (no activerecord)
+  sh 'bundle exec rake test'
+
+  # Each activerecord appraisal
+  appraisals.each do |appraisal|
+    sh "bundle exec appraisal #{appraisal} rake test"
+  end
+end
+
+task default: :test

data/bin/matrix

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+ruby -v
+
+rm -f Gemfile.lock
+
+bundle install
+
+bundle exec appraisal update
+
+bundle exec rake matrix
+
+ruby -v