custom_active_record_observer 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b13cc7f8b0aceb704bd1d8e1e1fad0835574c65d
-  data.tar.gz: 219db492b79a927aaecc9afe16d5d4d8fc6270e2
+SHA256:
+  metadata.gz: 6644843d956acabec36f996af2a3add3756ee78aaeb5cf1b9286bbf1fb3edfc3
+  data.tar.gz: 6f4f323b250aac555eb294762811fe0c1d52c0f0288d03a41657489c2b804022
 SHA512:
-  metadata.gz: 3d0ad899787e4a3e447cc3255b373875f541d731698bd200f48688d7645132e6bb83593657daa2b1a0929c563a5eb0ec69470ef9c8bc9655864fced1f03d26d4
-  data.tar.gz: ef7562bcbce78b0b2a0cc29ceb64ba14d8222c31621d761bb63e26c0152a27862bdb415e6fd019f429e82fa0a1217c6a22bfbabbb218de13a1ecd1610865082a
+  metadata.gz: 6cc3163d3cf8ba51021ce31681945d301413ee30aff9387014c86c8f522d1cca62331f9ae7d25f910b6020aa06a72ab29956e6302133a48ec1be064df5d48efe
+  data.tar.gz: 30bbcc652985d669ef52e620a9b0e55d136d7feabdffd214b83db4ce1678b33589fe93830dee145d082f8944ec434dc428e7296e597e2fd885511d4927871a34

data/README.md

@@ -1,25 +1,99 @@
+[gem]: https://rubygems.org/gems/custom_active_record_observer
+[travis]: https://travis-ci.org/OnApp/custom_active_record_observer
+
 # CustomActiveRecordObserver
 
-`custom_active_record_observer` is a DSL to track create/update/destroy operations based on AR callbacks.
+[![Gem Version](https://badge.fury.io/rb/custom_active_record_observer.svg)][gem]
+[![Build Status](https://travis-ci.org/OnApp/custom_active_record_observer.svg?branch=master)][travis]
+
+A DSL to track create/update/destroy operations based on AR callbacks.
 
-Its a simple DSL similar to the code below:
+### Installation
+Add the following code to your `Gemfile`
 
+```ruby
+# Gemfile
+gem 'custom_active_record_observer'
 ```
-CustomActiveRecordObserver.observe :EngagedUser, :CompanyOwner, handler: CustomerEventPublisher.new do
-  on_create do |customer|
-    Events::CustomerSignedUp.new(data: {customer_id: customer.id}
+and run `bundle install`
+
+Then add the observation rules (in `config/initializers/events_observation.rb`)
+```ruby
+# config/initializers/events_observation.rb
+CustomActiveRecordObserver.observe 'User' do
+  on_create do |user|
+    # do something
   end
+end
+```
+
+In this expample we track model `User`. If a new user is created, AR `:after_commit` callback is launched and the block in `on_create` executes.
 
-  on_destroy do |customer|
-    Events::CustomerSignedOut.new(data: {…})
+We can track by real classes (which is not always possible, since that code is better to be placed in `config/initializers`). But passing strings or symbols is also allowed:
+```ruby
+  CustomActiveRecordObserver.observe User, :EngagedUser, 'CompanyOwner' { ... }
+```
+Here we track three classes.
+
+### Usage
+How do we use `custom_active_record_observer` in the wild? For instance, in this example we publish `UserRegisteredEvent` on user creation. (using `rails_event_store` gem). This is a pretty useful trade-off if there are no operations or aggregates introduced in the system architecture.
+
+```ruby
+CustomActiveRecordObserver.observe 'User' do
+  on_create do |user|
+    Rails.application.config.event_store.publish_event(
+      UserRegisteredEvent.strict(data: { user_id: user.id }),
+      stream_name: "users-#{user.id}"
+    )
   end
+end
+```
+
+#### Usage with `handler`
+`handler` might be passed into the observation. It is a simple object/class which has metho `call`. The result of `do..end` block is passed into that handler.
 
-  on_change :group_id do |customer|
-    Events::CustomerGroupChanged.new(data: {…})
+```ruby
+handler = ->(event) do
+  Rails.application.config.event_store.publish_event(
+    event,
+    stream_name: "users-#{ event.data.fetch(:user_id) }"
+  )
+end
+
+CustomActiveRecordObserver.observe 'User', handler: handler do
+  on_create do |user|
+    UserRegisteredEvent.strict(data: { user_id: user.id })
+  end
+
+  on_add :user_group_id do |user|
+    UserAssignedToUserGroup.strict(data: {
+      user_id: user.id,
+      user_group_id: user.user_group_id
+    })
+  end
+
+  on_change :user_group_id do |user|
+    UserAssignedToAnotherUserGroupEvent.strict(data: {
+      user_id: user.id,
+      user_group_id: user.user_group_id
+    })
+  end
+
+  on_remove :user_group_id do |user|
+    UserUnassignedFromUserGroupEvent.strict(data: {
+      user_id: user.id,
+      user_group_id: user.previous_changes.fetch(:user_group_id).first
+    })
+  end
+
+  on_destroy do |user|
+    UserTerminatedEvent.strict(data: { user_id: user.id })
   end
-…
 end
 ```
 
-which you can put into a single initializer file instead of scattering it around and having it in each AR model.
-That file is easier to remove in future. It incapsulates all the “inaccurate" dependencies.
+### Licence
+See `LICENSE` file.
+
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/OnApp/custom_active_record_observer.

data/lib/custom_active_record_observer.rb

@@ -6,6 +6,42 @@ module CustomActiveRecordObserver
   mattr_accessor :schema
   @@schema = Schema.new
 
+  # @param class_names [Symbols] - list of class names
+  #   may be an object of Class, Symbol, or String
+  #   (e.g. :User, 'User' or User)
+  # @example Usage without handler
+  #   CustomActiveRecordObserver.observe 'User' do
+  #     on_create do |user|
+  #       Rails.application.config.event_store.publish_event(
+  #         UserRegisteredEvent.strict(data: { user_id: user.id }),
+  #         stream_name: "users-#{user.id}"
+  #       )
+  #     end
+  #
+  #     on_destroy do |user|
+  #       Rails.application.config.event_store.publish_event(
+  #         UserTerminatedEvent.strict(data: { user_id: user.id }),
+  #         stream_name: "users-#{user.id}"
+  #       )
+  #     end
+  #   end
+  #
+  # @example Usage with handler
+  #   handler = ->(event) {
+  #     Rails.application.config.event_store.publish_event(
+  #       event,
+  #       stream_name: "users-#{event.data[:user_id]}"
+  #     )
+  #   }
+  #   CustomActiveRecordObserver.observe 'User', handler: handler do
+  #     on_create do |user|
+  #       UserRegisteredEvent.strict(data: { user_id: user.id })
+  #     end
+  #
+  #     on_destroy do |user|
+  #       UserTerminatedEvent.strict(data: { user_id: user.id })
+  #     end
+  #   end
   def self.observe(*class_names, handler: proc {}, &block)
     class_names.each do |class_name|
       DSL.new(block).actions_and_rules.each do |(action, rule)|

data/lib/custom_active_record_observer/all.rb

@@ -1,4 +1,6 @@
 require_relative 'models_extender'
+require_relative 'observable/base'
+require_relative 'observable/paranoid'
 require_relative 'observable'
 require_relative 'engine'
 require_relative 'rules/all'

data/lib/custom_active_record_observer/changes_tracker.rb

@@ -5,7 +5,7 @@ module CustomActiveRecordObserver
         method_names.each do |name|
           define_method name do |*args|
             @_active_record_observer_changes ||= {}
-            @_active_record_observer_changes.merge!(changes)
+            @_active_record_observer_changes.merge!(previous_changes)
 
             super(*args)
           end

data/lib/custom_active_record_observer/dsl.rb

@@ -1,21 +1,50 @@
+# @title CustomActiveRecordObserver::DSL
 module CustomActiveRecordObserver
+  # A main methods that are supposed to be used within CustomActiveRecordObserver
+  #
+  # @author OnApp Ltd.
   class DSL
+    attr_reader :actions_and_rules
+
+    # @attr_reader [Array] actions_and_rules the resulting list of applied rules
     def initialize(block)
-      instance_exec(&block)
-    end
+      @actions_and_rules = []
 
-    def actions_and_rules
-      @actions_and_rules ||= []
+      instance_exec(&block)
     end
 
+    # Executes the code inside a block after the record is *created*
     def on_create(&block)
       store(:create, Rules::CreateRule.new(block))
     end
 
+    # Executes the code inside a block after the record is *destroyed*
     def on_destroy(&block)
       store(:destroy, Rules::DestroyRule.new(block))
     end
 
+    # @param attributes [Symbols] - list of attribute names (e.g. :user_id, :user_group_id ...)
+    # @param values [Array(2)] - array of two values (before and after)
+    # Launches code inside a block if an object changes any of attributes according
+    # to the pattern which is described in the brackets (value before -> value after)
+    #
+    # This uses `===` method to compare values.
+    # @example Add hook on update any of attributes according to the pattern
+    #  on_update :address, :phone_number, [CustomActiveRecordObserver::NotNill,
+    #                                      CustomActiveRecordObserver::NotNill] do |user|
+    #    # notify system that user contact info was changed
+    #  end
+    #
+    # Will be launched only if user_group_id was changed from `nil` to anything but nil.
+    # in the array [] there are two values that are compared with the real changes
+    # to detect if they maches.
+    # @example Track nil -> not nill changes of user_group_id attribute
+    #   on_update :user_group_id, [nil, CustomActiveRecordObserver::NotNill] do |user|
+    #     # here we know that some user_group was assigned to user
+    #   end
+    # @example Other examples of usage:
+    #   on_update :user_group_id, [1, 2] { |user| ... }
+    #   on_update :user_group_id, [1, Integer] { |user| ... }
     def on_update(*attributes, &block)
       pattern = attributes.pop if attributes.last.is_a?(Array)
 
@@ -24,14 +53,32 @@ module CustomActiveRecordObserver
       end
     end
 
+    # Executes the code inside a block when the specific attributes are *updated*
+    # from <tt>nil</tt> to some <tt>not nil</tt> value
+    # @example
+    #   on_add :user_group_id do |user|
+    #     # here we know that user_group_id was nil, but now it is not
+    #   end
     def on_add(*attributes, &block)
       on_update(*attributes.push([nil, NotNil]), &block)
     end
 
+    # Executes the code inside a block when the specific attributes are *updated*
+    # from some <tt>not nil</tt> value to <tt>nil</tt>
+    # @example
+    #   on_remove :user_group_id do |user|
+    #     # here we know that user_group_id is equal to nil now
+    #   end
     def on_remove(*attributes, &block)
       on_update(*attributes.push([NotNil, nil]), &block)
     end
 
+    # Executes the code inside a block when the specific attributes are *updated*
+    # from some <tt>not nil</tt> to another <tt>not nil</tt>
+    # @example
+    #   on_change :user_group_id do |user|
+    #     # user was assigned to another user group
+    #   end
     def on_change(*attributes, &block)
       on_update(*attributes.push([NotNil, NotNil]), &block)
     end

data/lib/custom_active_record_observer/not_nil.rb

@@ -1,5 +1,9 @@
+# @title CustomActiveRecordObserver::NotNil
 module CustomActiveRecordObserver
+  # A module to represent any of values that are not equal to +nil+
   module NotNil
+    # @param other [Any]
+    # @return [Boolean]
     def self.===(other)
       super || !other.nil?
     end

data/lib/custom_active_record_observer/observable.rb

@@ -3,9 +3,15 @@ module CustomActiveRecordObserver
     extend ActiveSupport::Concern
 
     included do
-      after_commit -> { CustomActiveRecordObserver::Handler.(self, :create, previous_changes) }, on: :create
-      after_commit -> { CustomActiveRecordObserver::Handler.(self, :update, previous_changes) }, on: :update
-      after_commit -> { CustomActiveRecordObserver::Handler.(self, :destroy, previous_changes) }, on: :destroy
+      if defined?(CollectiveIdea::Acts::NestedSet) && self < CollectiveIdea::Acts::NestedSet::Model
+        prepend CustomActiveRecordObserver::ChangesTracker[:set_depth!]
+      end
+
+      if try(:paranoid?)
+        include Paranoid
+      else
+        include Base
+      end
     end
   end
 end

data/lib/custom_active_record_observer/observable/base.rb

@@ -0,0 +1,16 @@
+module CustomActiveRecordObserver
+  module Observable
+    # The base module which is included to all classes that are observed.
+    # It adds AR after commit callbacks to class instances and handles
+    # the results with <tt>CustomActiveRecordObserver::Handler</tt>
+    module Base
+      extend ActiveSupport::Concern
+
+      included do
+        after_commit -> { CustomActiveRecordObserver::Handler.(self, :create, previous_changes) }, on: :create
+        after_commit -> { CustomActiveRecordObserver::Handler.(self, :update, previous_changes) }, on: :update
+        after_commit -> { CustomActiveRecordObserver::Handler.(self, :destroy, previous_changes) }, on: :destroy
+      end
+    end
+  end
+end

data/lib/custom_active_record_observer/observable/paranoid.rb

@@ -0,0 +1,16 @@
+module CustomActiveRecordObserver
+  module Observable
+    module Paranoid
+      extend ActiveSupport::Concern
+
+      included do
+        after_commit  -> { CustomActiveRecordObserver::Handler.(self, :create, previous_changes) },
+                      on: :create
+        after_commit  -> { CustomActiveRecordObserver::Handler.(self, :update, previous_changes) },
+                      on: :update
+        after_destroy -> { CustomActiveRecordObserver::Handler.(self, :destroy, previous_changes) },
+                      if: -> { deleted_at }
+      end
+    end
+  end
+end

data/lib/custom_active_record_observer/schema.rb

@@ -20,6 +20,10 @@ module CustomActiveRecordObserver
     end
 
     def add_rule(class_name, action, rules, handler)
+      unless class_name.is_a?(Symbol)
+        class_name = class_name.to_s.to_sym
+      end
+
       schema[class_name] ||= {}
       schema[class_name][action] ||= []
 

data/lib/custom_active_record_observer/version.rb

@@ -1,3 +1,3 @@
 module CustomActiveRecordObserver
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.5.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: custom_active_record_observer
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.5.0
 platform: ruby
 authors:
 - OnApp Ltd.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-22 00:00:00.000000000 Z
+date: 2020-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,40 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '6'
+        version: '5.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '6'
+        version: '5.2'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '6'
+        version: '5.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.2'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '6'
+        version: '5.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -78,6 +66,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |2
       This gem delivers a simple DSL based on the after_commit callback
       which can be used as an alternative to hooks from inside the model
@@ -98,6 +114,8 @@ files:
 - lib/custom_active_record_observer/models_extender.rb
 - lib/custom_active_record_observer/not_nil.rb
 - lib/custom_active_record_observer/observable.rb
+- lib/custom_active_record_observer/observable/base.rb
+- lib/custom_active_record_observer/observable/paranoid.rb
 - lib/custom_active_record_observer/rules/all.rb
 - lib/custom_active_record_observer/rules/base_rule.rb
 - lib/custom_active_record_observer/rules/create_rule.rb
@@ -117,7 +135,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.2.0
+      version: 2.5.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -125,7 +143,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.7.6.2
 signing_key: 
 specification_version: 4
 summary: A small handy library to track create/update/destroy actions on active_record