u-observers 2.2.1 → 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)
@@ -45,10 +45,15 @@ Because of this issue, I decided to create a gem that encapsulates the pattern w
     - [Defining observers that execute only once](#defining-observers-that-execute-only-once)
       - [`observers.attach(*args, perform_once: true)`](#observersattachargs-perform_once-true)
       - [`observers.once(event:, call:, ...)`](#observersonceevent-call-)
+    - [Defining observers using blocks](#defining-observers-using-blocks)
+      - [`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)
@@ -64,11 +69,24 @@ gem 'u-observers'
 
 # Compatibility
 
-| u-observers | branch  | ruby     | activerecord  |
-| ----------- | ------- | -------- | ------------- |
-| unreleased  | main    | >= 2.2.0 | >= 3.2, < 6.1 |
-| 2.2.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).
 
@@ -215,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.
@@ -227,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.
@@ -375,6 +394,83 @@ order.cancel!         # Nothing will happen because there aren't observers.
 
 [⬆️ &nbsp; Back to Top](#table-of-contents-)
 
+### Defining observers using blocks
+
+The methods `#on()` and `#once()` can receive an event (`symbol`) and a block to define observers.
+
+#### `observers.on()`
+
+```ruby
+class Order
+  include Micro::Observers
+
+  def cancel!
+    observers.notify!(:canceled)
+  end
+end
+
+order = Order.new
+order.observers.on(:canceled) do |event|
+  puts "The order #(#{event.subject.object_id}) has been canceled."
+end
+
+order.observers.some? # true
+
+order.cancel!         # The order #(70301497466060) has been canceled.
+
+order.observers.some? # true
+```
+
+#### `observers.once()`
+
+```ruby
+class Order
+  include Micro::Observers
+
+  def cancel!
+    observers.notify!(:canceled)
+  end
+end
+
+order = Order.new
+order.observers.once(:canceled) do |event|
+  puts "The order #(#{event.subject.object_id}) has been canceled."
+end
+
+order.observers.some? # true
+
+order.cancel!         # The order #(70301497466060) has been canceled.
+
+order.observers.some? # false
+```
+
+#### Replacing a block by a `lambda`/`proc`
+
+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
+  include Micro::Observers
+
+  def cancel!
+    observers.notify!(:canceled)
+  end
+end
+
+NotifyAfterCancel = -> event { puts "The order #(#{event.subject.object_id}) has been canceled." }
+
+order = Order.new
+order.observers.once(:canceled, &NotifyAfterCancel)
+
+order.observers.some? # true
+order.cancel!         # The order #(70301497466060) has been canceled.
+
+order.observers.some? # false
+order.cancel!         # Nothing will happen because there aren't observers.
+```
+
+[⬆️ &nbsp; Back to Top](#table-of-contents-)
+
 ### Detaching observers
 
 As shown in the first example, you can use the `observers.detach()` to remove observers.
@@ -394,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
@@ -416,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
@@ -464,9 +562,64 @@ end
 
 [⬆️ &nbsp; Back to Top](#table-of-contents-)
 
-#### notify_observers()
+#### Attaching observers at the class level (`.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.
+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.
 
 ```ruby
 class Post < ActiveRecord::Base
@@ -482,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]})")
@@ -496,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):
@@ -516,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
 
@@ -525,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).