observable_model 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a939a2bb754dc9c5992a26b998b47d4f443a375d35a11b7f2eb840008befa43
-  data.tar.gz: 85372a16208f607ab3d7e47cb58dcbe918946a30e1f6d1c56555651a1e2d513c
+  metadata.gz: d3bd27344026bbc33d4329242d221f0163ee2655cabd79872a7fce079cd10db3
+  data.tar.gz: c4fdd4dfb9817e46e7eabcf0832e819c9b4c15520439b8b60412a7f8495e522f
 SHA512:
-  metadata.gz: db0a4ea664067980f74e61b18430667889b773f24fdfe9ea86f0bf297ba7e65ff886e599368ab6c7617f4e11f60c864c3902ba089179194c5e8a95eeeb5ed718
-  data.tar.gz: f99c5c875395af8e25d8293931f8c33e830c4e998b01eb6e3727b90b0db5c0a58df36cb740f656cb4b2bd726cf1507306d96296e740983ec65e4a4a65d93e9cd
+  metadata.gz: 58ad1ab5c99f79de7ddade0e4406acd7d2ae9fe105f78bee4bfa6cc61d34fb8b4f24f7dce8ca65da77a68be0aa00a4b74085bae97f91dd4e6dd5987549b1497b
+  data.tar.gz: a79492c661e875f5cb3060424d8d0ff6c210db7790030f875d48ffa425824b1760908ff87c763e190e927e9b58b57f1360125099970fc0bd328107abf5ef6f62

data/README.md

@@ -1,24 +1,201 @@
 # ObservableModel
 
-TODO: Delete this and the text below, and describe your gem
+A Ruby gem that implements the Observer pattern for ActiveRecord models in Rails applications. ObservableModel provides a clean, organized way to respond to model lifecycle events (create, update, destroy) without cluttering your models with callback logic.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/observable_model`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Why ObservableModel?
 
-## Installation
+As Rails applications grow, model callbacks can become cluttered with business logic, side effects, and external service integrations. ObservableModel helps you:
+
+- **Separate concerns** - Keep models focused on data and validation
+- **Organize side effects** - Isolate external service calls, notifications, and async jobs
+- **Improve testability** - Easily skip observers in tests with `skip_observers` flag
+- **Follow patterns** - Implement the classic Observer pattern in a Rails-friendly way
+- **Maintain clarity** - Know exactly where lifecycle-triggered logic lives
+
+## Features
+
+- 🎯 **Simple integration** - Just include a module in your ActiveRecord models
+- 🔄 **Lifecycle hooks** - Respond to before and after commit events for create, update, and destroy
+- 🚫 **Skippable observers** - Disable observers per-instance when needed
+- 🧩 **Convention-based** - Auto-discovers observer classes (e.g., `UserObserver` for `User`)
+- ⚡ **Before-commit callbacks** - Enables observer actions to run before changes are committed
+- ⚡ **After-commit callbacks** - Ensures database transactions complete before running observer actions
+- 🧪 **Test-friendly** - Easy to bypass observers in test scenarios
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Requirements
+
+- Ruby >= 3.2.0
+- Rails >= 6.1
+
+## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Add this line to your application's Gemfile:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+gem 'observable_model'
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+And then execute:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```bash
+$ bundle install
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Basic Setup
+
+1. **Include the module in your ActiveRecord model:**
+
+```ruby
+class User < ApplicationRecord
+  include ObservableModel::Sources::ActiveRecordObservable
+  
+  # Your model code...
+end
+```
+
+2. **Create an observer class:**
+
+ObservableModel uses a naming convention: for a model named `User`, create a `UserObserver` class.
+
+```ruby
+# app/observers/user_observer.rb
+class UserObserver < ObservableModel::Observers::Base
+  def pre_create
+    # Called before the record is created
+  end
+
+  def pre_update
+    # Called before the record is updated
+  end
+
+  def pre_destroy
+    # Called before the record is destroyed
+  end
+
+  def on_create_commit
+    # Called after a user is created and committed to the database
+    WelcomeMailer.welcome_email(@observable).deliver_later
+    AnalyticsService.track_signup(@observable)
+  end
+
+  def on_update_commit
+    # Called after a user is updated and committed
+    if @observable.saved_change_to_email?
+      EmailChangeNotifier.notify(@observable)
+    end
+  end
+
+  def on_destroy_commit
+    # Called after a user is destroyed and committed
+    CleanupService.remove_user_data(@observable.id)
+  end
+end
+```
+
+The `@observable` instance variable contains the model instance that triggered the event.
+
+### Skipping Observers
+
+To bypass observers for a specific operation:
+
+```ruby
+user = User.new(name: "John Doe")
+user.skip_observers = true
+user.save  # No observer callbacks will be triggered
+```
+
+### Custom Observer Class Names
+
+Override `observer_class_name` to use a non-conventional class name:
+
+```ruby
+class User < ApplicationRecord
+  include ObservableModel::Sources::ActiveRecordObservable
+
+  def observer_class_name
+    "CustomUserObserver"
+  end
+end
+```
+
+### Organizing Observers
+
+We recommend creating an `app/observers` directory in your Rails application:
+
+```
+app/
+  observers/
+    user_observer.rb
+    order_observer.rb
+    payment_observer.rb
+```
+
+Make sure to add this to your `config/application.rb`:
+
+```ruby
+config.autoload_paths += %W(#{config.root}/app/observers)
+```
+
+## How It Works
+
+When you include `ObservableModel::Sources::ActiveRecordObservable` in your model, six callbacks are registered:
+
+- `before_create` → `pre_create`
+- `before_update` → `pre_update`
+- `before_destroy` → `pre_destroy`
+- `after_create_commit` → `on_create_commit`
+- `after_update_commit` → `on_update_commit`
+- `after_destroy_commit` → `on_destroy_commit`
+
+On each event, the model looks up the observer class by convention, instantiates it with itself, and delegates the callback to it. If `skip_observers` is `true`, no observer is instantiated and all callbacks are silently skipped.
+
+## Examples
+
+### Example: Send Welcome Email on User Registration
+
+```ruby
+class UserObserver < ObservableModel::Observers::Base
+  def on_create_commit
+    UserMailer.welcome_email(@observable).deliver_later
+  end
+end
+```
+
+### Example: Validate State Before Destruction
+
+```ruby
+class OrderObserver < ObservableModel::Observers::Base
+  def pre_destroy
+    raise "Cannot delete a completed order" if @observable.completed?
+  end
+end
+```
+
+### Example: Track Order Status Changes
+
+```ruby
+class OrderObserver < ObservableModel::Observers::Base
+  def on_update_commit
+    if @observable.saved_change_to_status?
+      OrderStatusNotifier.notify_customer(@observable)
+      AnalyticsService.track_status_change(@observable)
+    end
+  end
+end
+```
+
+### Example: Cleanup Related Data on Deletion
+
+```ruby
+class AccountObserver < ObservableModel::Observers::Base
+  def on_destroy_commit
+    DeleteUserDataJob.perform_later(@observable.id)
+    AuditLog.create(action: 'account_deleted', account_id: @observable.id)
+  end
+end
+```
 
 ## Development
 
@@ -26,6 +203,28 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Testing
+
+Run the test suite with:
+
+```bash
+$ bundle exec rake spec
+```
+
+## Roadmap
+
+- [ ] Observer registration/configuration DSL
+- [ ] Built-in async observer execution
+- [ ] Observer metrics and monitoring hooks
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/observable_model.
+Bug reports and pull requests are welcome on GitHub at https://github.com/CodeTectonics/observable-model. This project is intended to be a safe, welcoming space for collaboration.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the ObservableModel project's codebases and issue trackers is expected to follow the project's code of conduct.

data/lib/observable_model/observers/base.rb

@@ -5,6 +5,12 @@ module ObservableModel
         @observable = observable
       end
 
+      def pre_create; end
+
+      def pre_update; end
+
+      def pre_destroy; end
+
       def on_create_commit; end
 
       def on_update_commit; end

data/lib/observable_model/sources/active_record_observable.rb

@@ -6,6 +6,9 @@ module ObservableModel
       included do
         attr_accessor :skip_observers
 
+        before_create :pre_create
+        before_update :pre_update
+        before_destroy :pre_destroy
         after_create_commit :on_create_commit
         after_update_commit :on_update_commit
         after_destroy_commit :on_destroy_commit
@@ -18,6 +21,12 @@ module ObservableModel
           observer_class_name.constantize.new(self) unless skip_observers
         end
 
+        delegate :pre_create, to: :observer, allow_nil: true
+
+        delegate :pre_update, to: :observer, allow_nil: true
+
+        delegate :pre_destroy, to: :observer, allow_nil: true
+
         delegate :on_create_commit, to: :observer, allow_nil: true
 
         delegate :on_update_commit, to: :observer, allow_nil: true

data/lib/observable_model/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: observable_model
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Mark Harbison
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-01 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails