custom_active_record_observer 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d517d3fde840c8135daaf6eb3c5399ae908feca7
-  data.tar.gz: 65d5a41cf511bef2dc452a9f47e6a52740fba8c3
+  metadata.gz: 4af7438aff8a12f47958c45d93a0fa4da7efbcba
+  data.tar.gz: 00116ca29ecc84e69dac009c5313a265e0697578
 SHA512:
-  metadata.gz: 58dbf2b12928f3b643a402317b305c2388b997dab1caf1ca2084fbd4b6235389f9ebbc4d81e3852763b5a33749aa0aa88c4ed5ca70a09b334370d8beb3bc4daa
-  data.tar.gz: 480d372c5311324ba4fb3c65c1a29d439921b59188095906c8aa4d354d74ac02275bfc9522bc977955973253dfc0287bcbdc34d0fafe944ae2f2a5a0ee8e1f78
+  metadata.gz: d0718789103b5aaac520e90497227f4484877317f3351b37dba4104a2b45839847d502b818682829fca542e19dfcc5b1e94f9723cb8dd454e2f918f4f0d4679e
+  data.tar.gz: 5ad0514aa41b98a010e30f8c714f30cd0f01c12b5a520de5c76f3c6f390b43d440eb132d96685b51e81ae0bf31f9e963668a7e7bb6e9f09e9849447f9ef5d393

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/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/base.rb

@@ -1,5 +1,8 @@
 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
 

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.3.0'.freeze
+  VERSION = '0.3.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: custom_active_record_observer
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - OnApp Ltd.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-15 00:00:00.000000000 Z
+date: 2018-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord