active_record-events 2.0.0 → 4.0.1

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ZTljYzhjZWM1OGRmODA4YjIzYjYyYzMwMDg3YmMxOWVmMWM5ZTMwOA==
-  data.tar.gz: !binary |-
-    ZDljYzhkYTk1ZjI1ZjIyNWRlYmZmZTVhNDIzNDNhNjFiNmRlZjA5Ng==
+SHA256:
+  metadata.gz: 18d2fc6a8788d3190b5da3dd8dc45fbf307bb55344a6072ba24db67ff9b0e6cb
+  data.tar.gz: 17767f7e00810c9717cc5fa4bd92d49303b22427eb5da06a3f27ea39f8a4fbf8
 SHA512:
-  metadata.gz: !binary |-
-    Nzg4ODRhMzRiNzFiMjUwZjkzNWNiNTFmZmE5MjAzZDZjNGE1YzkzNmI5MWQx
-    NDVhZjJlOGM2YzNlNGFhZjc2ZjgzNzMwN2Y1YzU5MjVmOTU3OTMyMzJjY2Zl
-    Y2NiZDU1ZTk4M2UxYjdlOTRjNzM1ZTUwZjMwMjQ0Njk1MWMzOTk=
-  data.tar.gz: !binary |-
-    ODYzYjIyZTNjM2I2NDNhNTk0YWFmOTkxZGU4NjQwZjQ1YzdjODJjM2M4OTkz
-    YzUzZjZmMWM4ZWVhZTNmYWEwYzZkZjA0YzFjNDZhY2Q5MDVhOTk2ODk1ODA3
-    NjE2ZmI5NzdiYzcxN2IyOTFiNjU3NWJkNTA3OWFmYjIxMWMyNzY=
+  metadata.gz: d39a25b8c5695aa8c81b9780744f0639ab2b0bac74296486721ec1c28cad0c67f801441b78c3faa48162d60938297a33638dada9e597a84a7c8c888c94cc86b2
+  data.tar.gz: afb5395aba7821776ff9aa3790d0f04f625daa1a4de6495e9069cf210a4ea3023b7449bb6cce58e9eb158887a541da6f927b9ba03e61df0974b6cd473a6beacf

data/README.md

@@ -1,7 +1,15 @@
-# ActiveRecord::Events [![Gem version](https://img.shields.io/gem/v/active_record-events.svg)](https://rubygems.org/gems/active_record-events) [![Build status](https://img.shields.io/travis/pienkowb/active_record-events.svg)](https://travis-ci.org/pienkowb/active_record-events)
+# ActiveRecord::Events [![Gem version](https://img.shields.io/gem/v/active_record-events)](https://rubygems.org/gems/active_record-events) [![Build status](https://img.shields.io/travis/pienkowb/active_record-events/develop)](https://travis-ci.org/pienkowb/active_record-events) [![Coverage status](https://img.shields.io/coveralls/github/pienkowb/active_record-events/develop)](https://coveralls.io/github/pienkowb/active_record-events) [![Maintainability status](https://img.shields.io/codeclimate/maintainability/pienkowb/active_record-events)](https://codeclimate.com/github/pienkowb/active_record-events)
 
 An ActiveRecord extension providing convenience methods for timestamp management.
 
+## Screencast
+
+<a href="https://www.youtube.com/watch?v=TIR7YDF3O-4">
+  <img src="https://img.youtube.com/vi/TIR7YDF3O-4/maxresdefault.jpg" title="ActiveRecord::Events - Awesome Ruby Gems" width="50%">
+</a>
+
+[Watch screencast](https://www.youtube.com/watch?v=TIR7YDF3O-4) (courtesy of [Mike Rogers](https://github.com/MikeRogers0))
+
 ## Installation
 
 Add the following line to your application's Gemfile:
@@ -24,9 +32,12 @@ $ gem install active_record-events
 
 ## Usage
 
-Recording a timestamp in order to mark that an event occurred to an object is a common practice when dealing with ActiveRecord models – `created_at` and `updated_at` fields handled by ActiveRecord itself are a good example of such approach.
+Recording a timestamp in order to mark that an event occurred to an object is a common practice when dealing with ActiveRecord models.
+A good example of such an approach is how ActiveRecord handles the `created_at` and `updated_at` fields.
 This gem allows you to manage custom timestamp fields in the exact same manner.
 
+### Example
+
 Consider a `Task` model with a `completed_at` field and the following methods:
 
 ```ruby
@@ -35,17 +46,25 @@ class Task < ActiveRecord::Base
     completed_at.present?
   end
 
+  def not_completed?
+    !completed?
+  end
+
   def complete
-    complete! unless completed?
+    complete! if not_completed?
   end
 
   def complete!
     touch(:completed_at)
   end
+
+  def self.complete_all
+    touch_all(:completed_at)
+  end
 end
 ```
 
-Instead of defining these three methods explicitly, you can use a macro provided by the gem.
+Instead of defining all of these methods by hand, you can use the `has_event` macro provided by the gem.
 
 ```ruby
 class Task < ActiveRecord::Base
@@ -53,12 +72,10 @@ class Task < ActiveRecord::Base
 end
 ```
 
-This approach is very efficient when more than one field has to be handled that way.
-In such a case, many lines of code can be replaced with an expressive one-liner.
+As a result, the methods will be generated automatically.
 
-```ruby
-has_events :complete, :archive
-```
+*It's important to note that the `completed_at` column has to already exist in the database.*
+*Consider [using the generator](#using-a-rails-generator) to create a necessary migration.*
 
 ### Scopes
 
@@ -69,7 +86,40 @@ scope :not_completed, -> { where(completed_at: nil) }
 scope :completed, -> { where.not(completed_at: nil) }
 ```
 
-### Object
+The inclusion of scope methods can be omitted by passing the `skip_scopes` flag.
+
+```ruby
+has_event :complete, skip_scopes: true
+```
+
+### Multiple events
+
+Using the macro is efficient when more than one field has to be handled that way.
+In such a case, many lines of code can be replaced with an expressive one-liner.
+
+```ruby
+has_events :complete, :archive
+```
+
+### Date fields
+
+In case of date fields, which by convention have names ending with `_on` instead of `_at` (e.g. `completed_on`), the `field_type` option needs to be passed to the macro:
+
+```ruby
+has_event :complete, field_type: :date
+```
+
+### Custom field name
+
+If there's a field with a name that doesn't follow the naming convention (i.e. does not end with `_at` or `_on`), you can pass it as the `field_name` option.
+
+```ruby
+has_event :complete, field_name: :completion_time
+```
+
+Note that the `field_name` option takes precedence over the `field_type` option.
+
+### Specifying an object
 
 There are events which do not relate to a model itself but to one of its attributes – take the `User` model with the `email_confirmed_at` field as an example.
 In order to keep method names grammatically correct, you can specify an object using the `object` option.
@@ -80,8 +130,85 @@ class User < ActiveRecord::Base
 end
 ```
 
-This will generate `email_confirmed?`, `confirm_email` and `confirm_email!` methods.
+This will generate the following methods:
+
+- `email_not_confirmed?`
+- `email_confirmed?`
+- `confirm_email`
+- `confirm_email!`
+- `confirm_all_emails` (class method)
+
+As well as these two scopes:
+
+- `email_confirmed`
+- `email_not_confirmed`
+
+### Using a Rails generator
+
+If you want to quickly add a new event, you can make use of a Rails generator provided by the gem:
+
+```
+$ rails generate active_record:event task complete
+```
+
+It will create a necessary migration and insert a `has_event` statement into the model class.
+
+```ruby
+# db/migrate/XXX_add_completed_at_to_tasks.rb
+
+class AddCompletedAtToTasks < ActiveRecord::Migration[6.0]
+  def change
+    add_column :tasks, :completed_at, :datetime
+  end
+end
+```
+
+```ruby
+# app/models/task.rb
+
+class Task < ActiveRecord::Base
+  has_event :complete
+end
+```
+
+All of the macro options are supported by the generator and can be passed via the command line.
+For instance:
+
+```
+$ rails generate active_record:event user confirm --object=email --skip-scopes
+```
+
+For more information, run the generator with the `--help` option.
+
+### Overriding methods
+
+If there's a need to override any of the methods generated by the macro, you can define a new method with the same name in the corresponding model class.
+This applies to instance methods as well as class methods.
+In both cases, the `super` keyword invokes the original method.
+
+```ruby
+class Task < ActiveRecord::Base
+  has_event :complete
+
+  def complete!
+    super
+    logger.info("Task #{id} has been completed")
+  end
+
+  def self.complete_all
+    super
+    logger.info('All tasks have been completed')
+  end
+end
+```
+
+## Contributors
+
+- [Bartosz Pieńkowski](https://github.com/pienkowb)
+- [Tomasz Skupiński](https://github.com/tskupinski)
+- [Oskar Janusz](https://github.com/oskaror)
+- [Mike Rogers](https://github.com/MikeRogers0)
 
 ## See also
 
-- [ActiveRecord::Enum](http://api.rubyonrails.org/classes/ActiveRecord/Enum.html)
+- [ActiveRecord::Enum](https://api.rubyonrails.org/classes/ActiveRecord/Enum.html)

data/Rakefile

@@ -16,14 +16,38 @@ end
 
 RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'ActiveRecord::Events'
+  rdoc.title = 'ActiveRecord::Events'
   rdoc.options << '--line-numbers'
   rdoc.rdoc_files.include('README.rdoc')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-require 'standalone_migrations'
-StandaloneMigrations::Tasks.load_tasks
+require 'active_record'
+require 'yaml'
+
+include ActiveRecord::Tasks
+
+dummy_root = File.expand_path('spec/dummy', __dir__)
+database_config = YAML.load_file("#{dummy_root}/config/database.yml")
+
+DatabaseTasks.root = dummy_root
+DatabaseTasks.env = ENV['RAILS_ENV'] || 'development'
+DatabaseTasks.db_dir = "#{dummy_root}/db"
+DatabaseTasks.database_configuration = database_config
+DatabaseTasks.migrations_paths = "#{dummy_root}/db/migrate"
+
+task :environment do
+  require "#{dummy_root}/config/environment.rb"
+end
+
+ACTIVE_RECORD_MIGRATION_CLASS =
+  if ActiveRecord::VERSION::MAJOR >= 5
+    ActiveRecord::Migration[4.2]
+  else
+    ActiveRecord::Migration
+  end
+
+load 'active_record/railties/databases.rake'
 
 Bundler::GemHelper.install_tasks
 

data/lib/active_record/events.rb

@@ -1,39 +1,13 @@
 require 'active_support'
-require 'active_record/events/naming'
-
-module ActiveRecord
-  module Events
-    def has_events(*names)
-      options = names.extract_options!
-      names.each { |n| has_event(n, options) }
-    end
-
-    def has_event(name, options = {})
-      naming = Naming.new(name, options)
-
-      define_method("#{naming.predicate}?") do
-        self[naming.field].present?
-      end
 
-      define_method(naming.action) do
-        touch(naming.field) if self[naming.field].blank?
-      end
+require 'active_record/events/version'
 
-      define_method("#{naming.action}!") do
-        touch(naming.field)
-      end
-
-      define_singleton_method(naming.scope) do
-        where(arel_table[naming.field].not_eq(nil))
-      end
+require 'active_record/events/naming'
+require 'active_record/events/method_factory'
+require 'active_record/events/extension'
 
-      define_singleton_method(naming.inverse_scope) do
-        where(arel_table[naming.field].eq(nil))
-      end
-    end
-  end
-end
+require 'active_record/events/macro'
 
 ActiveSupport.on_load(:active_record) do
-  extend ActiveRecord::Events
+  extend ActiveRecord::Events::Extension
 end

data/lib/active_record/events/extension.rb

@@ -0,0 +1,19 @@
+require 'active_record/events/method_factory'
+
+module ActiveRecord
+  module Events
+    module Extension
+      def has_events(*names)
+        options = names.extract_options!
+        names.each { |n| has_event(n, options) }
+      end
+
+      def has_event(name, options = {})
+        method_factory = MethodFactory.new(name, options)
+
+        include method_factory.instance_methods
+        extend method_factory.class_methods
+      end
+    end
+  end
+end

data/lib/active_record/events/macro.rb

@@ -0,0 +1,36 @@
+module ActiveRecord
+  module Events
+    class Macro
+      def initialize(event_name, options)
+        @event_name = event_name.to_s
+        @options = options
+      end
+
+      def to_s
+        "has_event :#{event_name}#{options_list}"
+      end
+
+      private
+
+      def event_name
+        @event_name.underscore
+      end
+
+      def options_list
+        options.unshift('').join(', ') if options.present?
+      end
+
+      def options
+        @options.map { |k, v| "#{k}: #{convert_value(v)}" }
+      end
+
+      def convert_value(value)
+        symbol_or_string?(value) ? ":#{value}" : value
+      end
+
+      def symbol_or_string?(value)
+        value.is_a?(Symbol) || value.is_a?(String)
+      end
+    end
+  end
+end

data/lib/active_record/events/method_factory.rb

@@ -0,0 +1,88 @@
+require 'active_record/events/naming'
+
+module ActiveRecord
+  module Events
+    class MethodFactory
+      def initialize(event_name, options)
+        @options = options
+        @naming = Naming.new(event_name, options)
+      end
+
+      def instance_methods
+        Module.new.tap do |module_|
+          define_predicate_method(module_, naming)
+          define_inverse_predicate_method(module_, naming)
+
+          define_action_method(module_, naming)
+          define_safe_action_method(module_, naming)
+        end
+      end
+
+      def class_methods
+        Module.new.tap do |module_|
+          define_collective_action_method(module_, naming)
+
+          unless options[:skip_scopes]
+            define_scope_method(module_, naming)
+            define_inverse_scope_method(module_, naming)
+          end
+        end
+      end
+
+      private
+
+      attr_reader :options
+      attr_reader :naming
+
+      def define_predicate_method(module_, naming)
+        module_.send(:define_method, naming.predicate) do
+          self[naming.field].present?
+        end
+      end
+
+      def define_inverse_predicate_method(module_, naming)
+        module_.send(:define_method, naming.inverse_predicate) do
+          !__send__(naming.predicate)
+        end
+      end
+
+      def define_action_method(module_, naming)
+        module_.send(:define_method, naming.action) do
+          if persisted?
+            touch(naming.field)
+          else
+            self[naming.field] = current_time_from_proper_timezone
+          end
+        end
+      end
+
+      def define_safe_action_method(module_, naming)
+        module_.send(:define_method, naming.safe_action) do
+          __send__(naming.action) if __send__(naming.inverse_predicate)
+        end
+      end
+
+      def define_collective_action_method(module_, naming)
+        module_.send(:define_method, naming.collective_action) do
+          if respond_to?(:touch_all)
+            touch_all(naming.field)
+          else
+            update_all(naming.field => Time.current)
+          end
+        end
+      end
+
+      def define_scope_method(module_, naming)
+        module_.send(:define_method, naming.scope) do
+          where(arel_table[naming.field].not_eq(nil))
+        end
+      end
+
+      def define_inverse_scope_method(module_, naming)
+        module_.send(:define_method, naming.inverse_scope) do
+          where(arel_table[naming.field].eq(nil))
+        end
+      end
+    end
+  end
+end